Improved image cleaning

README.md

@@ -24,7 +24,8 @@ PNG, JPEG, TIFF, and TIF inputs are supported. Inpainted QC images are written
 to `out/cleaned/` with `_cleaned` added before the original extension, and
 debris-exclusion masks are written to `out/masks/` as PNG files. Preserve the
 original image and exclude masked pixels when quantifying DAB; do not quantify
-the synthetic pixels in the inpainted QC image.
+the synthetic pixels in the inpainted QC image. TIFF outputs use lossless LZW
+compression.
 
 An optional Gradio interface is also available:
 
@@ -33,9 +34,11 @@ uv run python app.py
 ```
 
 Open the local URL printed in the terminal, upload an input image, and select
-**Create mask and QC preview**. TIFF inputs are percentile-scaled to PNG
-previews in the interface. The full-resolution mask and inpainted QC file can
-both be downloaded; the uploaded source image remains unchanged.
+**Create mask and QC preview**. TIFF previews and cleaned QC downloads use a
+full-range 8-bit conversion, matching the notebook's display conversion. Debris
+detection retains its separate processing conversion. A conservative background
+fit corrects the cleaned QC image only when it detects meaningful edge falloff;
+the uploaded source image and debris mask remain unchanged.
 
 For batch processing, open the **Image directory** tab and select a folder.
 The app processes all uploaded images, including `.tif` and `.tiff` files, and

app.py

@@ -8,10 +8,10 @@ import gradio as gr
 import numpy as np
 
 from cleaning import (
-    clean_image,
-    clean_image_and_mask,
+    clean_display_image_and_mask,
     cleaned_image_name,
-    read_image_rgb,
+    read_image_preview_rgb,
+    read_image_rgb_and_preview,
     write_image_rgb,
 )
 
@@ -60,7 +60,7 @@ def preview_image(file_path: str | Path | None):
     if not file_path:
         return None, None, None, None, None
 
-    return _preview_image(read_image_rgb(file_path)), None, None, None, None
+    return _preview_image(read_image_preview_rgb(file_path)), None, None, None, None
 
 
 def clean_uploaded_image(file_path: str | Path | None):
@@ -68,9 +68,12 @@ def clean_uploaded_image(file_path: str | Path | None):
     output_dir = Path(_BATCH_OUTPUTS.name) / uuid4().hex
     output_dir.mkdir(parents=True)
 
-    image_rgb = read_image_rgb(image_path)
-    cleaned_rgb, debris_mask = clean_image_and_mask(image_rgb)
-    input_preview = _preview_image(image_rgb)
+    image_rgb, display_rgb = read_image_rgb_and_preview(image_path)
+    cleaned_display_rgb, debris_mask = clean_display_image_and_mask(
+        image_rgb,
+        display_rgb,
+    )
+    input_preview = _preview_image(display_rgb)
     preview_mask = debris_mask
     if preview_mask.shape != input_preview.shape[:2]:
         preview_mask = cv2.resize(
@@ -81,14 +84,14 @@ def clean_uploaded_image(file_path: str | Path | None):
     mask_outline = _mask_outline(input_preview, preview_mask)
     cleaned_path = output_dir / cleaned_image_name(image_path)
     mask_path = output_dir / f"{image_path.stem}_debris_mask.png"
-    write_image_rgb(cleaned_path, cleaned_rgb)
+    write_image_rgb(cleaned_path, cleaned_display_rgb)
     if not cv2.imwrite(str(mask_path), debris_mask):
         raise OSError(f"Could not write debris mask: {mask_path}")
 
     return (
         input_preview,
         mask_outline,
-        _preview_image(cleaned_rgb),
+        _preview_image(cleaned_display_rgb),
         str(mask_path),
         str(cleaned_path),
     )
@@ -106,7 +109,8 @@ def clean_directory(image_paths: list[str] | None) -> tuple[str, str]:
 
     for image_path_string in image_paths:
         image_path = Path(image_path_string)
-        cleaned_rgb = clean_image(read_image_rgb(image_path))
+        image_rgb, display_rgb = read_image_rgb_and_preview(image_path)
+        cleaned_rgb, _ = clean_display_image_and_mask(image_rgb, display_rgb)
 
         output_name = cleaned_image_name(image_path, used_names)
         write_image_rgb(cleaned_dir / output_name, cleaned_rgb)

cleaning.py

@@ -2,6 +2,7 @@ from pathlib import Path
 
 import cv2
 import numpy as np
+from skimage.util import img_as_ubyte
 
 TIFF_EXTENSIONS = {".tif", ".tiff"}
 DEBRIS_VALUE_MAX = 60
@@ -9,11 +10,19 @@ DEBRIS_SATURATION_MAX = 15
 DEBRIS_MASK_EXPANSION = 10
 INPAINT_RADIUS = 5
 PREVIEW_PERCENTILES = (1.0, 99.5)
-
-
-def _as_rgb_uint8(image: np.ndarray) -> np.ndarray:
+VIGNETTING_SATURATION_MAX = 30
+VIGNETTING_VALUE_MIN = 80
+VIGNETTING_MIN_FALLOFF = 0.03
+VIGNETTING_MAX_GAIN = 1.60
+VIGNETTING_FIT_MAX_DIMENSION = 800
+VIGNETTING_CORRECTION_ROWS = 256
+VIGNETTING_TILE_SIZE = 16
+VIGNETTING_TILE_PERCENTILE = 50
+VIGNETTING_SURFACE_BLUR_SIGMA = 0.8
+
+
+def _as_rgb_array(image: np.ndarray) -> np.ndarray:
     image = np.asarray(image)
-    source_dtype = image.dtype
 
     if image.ndim == 3 and image.shape[2] == 1:
         image = image[:, :, 0]
@@ -28,6 +37,13 @@ def _as_rgb_uint8(image: np.ndarray) -> np.ndarray:
     elif image.shape[2] != 3:
         raise ValueError("Expected an image with 1, 3, or 4 channels.")
 
+    return image
+
+
+def _as_rgb_uint8(image: np.ndarray) -> np.ndarray:
+    source_dtype = np.asarray(image).dtype
+    image = _as_rgb_array(image)
+
     if image.dtype != np.uint8:
         image = image.astype(np.float32)
         if image.size:
@@ -54,6 +70,26 @@ def _as_rgb_uint8(image: np.ndarray) -> np.ndarray:
     return image
 
 
+def _as_display_rgb_uint8(image: np.ndarray) -> np.ndarray:
+    """Convert an RGB image for display without changing its encoded contrast."""
+    image = _as_rgb_array(image)
+
+    if image.dtype == np.uint8:
+        return image
+
+    if np.issubdtype(image.dtype, np.integer) or image.dtype == np.bool_:
+        return img_as_ubyte(image)
+
+    finite_values = image[np.isfinite(image)]
+    if not finite_values.size:
+        raise ValueError("Image contains no finite pixel values.")
+    if 0 <= np.min(finite_values) and np.max(finite_values) <= 1:
+        finite_image = np.nan_to_num(image, nan=0, posinf=1, neginf=0)
+        return img_as_ubyte(finite_image)
+
+    return _as_rgb_uint8(image)
+
+
 def _is_tiff_path(image_path: str | Path) -> bool:
     return Path(image_path).suffix.lower() in TIFF_EXTENSIONS
 
@@ -96,7 +132,7 @@ def _select_tiff_plane(image: np.ndarray) -> np.ndarray:
     raise ValueError("Expected a 2D grayscale or RGB TIFF image.")
 
 
-def read_image_rgb(image_path: str | Path) -> np.ndarray:
+def _read_image_rgb_values(image_path: str | Path) -> np.ndarray:
     image_path = Path(image_path)
 
     if _is_tiff_path(image_path):
@@ -108,7 +144,7 @@ def read_image_rgb(image_path: str | Path) -> np.ndarray:
             ) from exc
 
         image = tifffile.imread(image_path)
-        return _as_rgb_uint8(_select_tiff_plane(image))
+        return _select_tiff_plane(image)
 
     image = cv2.imread(str(image_path), cv2.IMREAD_UNCHANGED)
     if image is None:
@@ -119,7 +155,23 @@ def read_image_rgb(image_path: str | Path) -> np.ndarray:
     elif image.ndim == 3 and image.shape[2] == 4:
         image = cv2.cvtColor(image, cv2.COLOR_BGRA2RGBA)
 
-    return _as_rgb_uint8(image)
+    return image
+
+
+def read_image_rgb(image_path: str | Path) -> np.ndarray:
+    return _as_rgb_uint8(_read_image_rgb_values(image_path))
+
+
+def read_image_preview_rgb(image_path: str | Path) -> np.ndarray:
+    return _as_display_rgb_uint8(_read_image_rgb_values(image_path))
+
+
+def read_image_rgb_and_preview(
+    image_path: str | Path,
+) -> tuple[np.ndarray, np.ndarray]:
+    """Return the processing image and its independent display preview."""
+    image = _read_image_rgb_values(image_path)
+    return _as_rgb_uint8(image), _as_display_rgb_uint8(image)
 
 
 def write_image_rgb(image_path: str | Path, image: np.ndarray) -> None:
@@ -134,7 +186,13 @@ def write_image_rgb(image_path: str | Path, image: np.ndarray) -> None:
                 "Writing TIFF images requires the tifffile package."
             ) from exc
 
-        tifffile.imwrite(image_path, image)
+        tifffile.imwrite(
+            image_path,
+            image,
+            photometric="rgb",
+            compression="lzw",
+            predictor=True,
+        )
         return
 
     image_bgr = cv2.cvtColor(image, cv2.COLOR_RGB2BGR)
@@ -179,11 +237,273 @@ def create_debris_mask(image: np.ndarray) -> np.ndarray:
     return cv2.dilate(filled_mask, expansion_kernel)
 
 
+def _estimate_vignetting_surface(
+    image: np.ndarray,
+    background_mask: np.ndarray,
+) -> np.ndarray | None:
+    """Estimate local slide-background colour on a small spatial grid."""
+    if np.count_nonzero(background_mask) < 1_000:
+        return None
+
+    height, width = background_mask.shape
+    grid_height = max(2, int(np.ceil(height / VIGNETTING_TILE_SIZE)))
+    grid_width = max(2, int(np.ceil(width / VIGNETTING_TILE_SIZE)))
+    surface = np.full((grid_height, grid_width, 3), np.nan, dtype=np.float32)
+
+    for grid_y in range(grid_height):
+        y_start = grid_y * height // grid_height
+        y_stop = (grid_y + 1) * height // grid_height
+        for grid_x in range(grid_width):
+            x_start = grid_x * width // grid_width
+            x_stop = (grid_x + 1) * width // grid_width
+            tile_mask = background_mask[y_start:y_stop, x_start:x_stop]
+            if np.count_nonzero(tile_mask) < 16:
+                continue
+            pixels = image[y_start:y_stop, x_start:x_stop][tile_mask]
+            surface[grid_y, grid_x] = np.percentile(
+                pixels,
+                VIGNETTING_TILE_PERCENTILE,
+                axis=0,
+            )
+
+    missing = np.isnan(surface[..., 0])
+    if np.all(missing):
+        return None
+
+    for channel in range(3):
+        channel_surface = surface[..., channel]
+        if np.any(missing):
+            channel_surface = cv2.inpaint(
+                np.nan_to_num(channel_surface, nan=0).astype(np.float32),
+                missing.astype(np.uint8),
+                3,
+                cv2.INPAINT_TELEA,
+            )
+        surface[..., channel] = cv2.GaussianBlur(
+            channel_surface,
+            (0, 0),
+            sigmaX=VIGNETTING_SURFACE_BLUR_SIGMA,
+            sigmaY=VIGNETTING_SURFACE_BLUR_SIGMA,
+            borderType=cv2.BORDER_REPLICATE,
+        )
+
+    return surface / 255
+
+
+def _largest_connected_region(mask: np.ndarray) -> np.ndarray | None:
+    component_count, labels, stats, _ = cv2.connectedComponentsWithStats(
+        mask.astype(np.uint8),
+        connectivity=8,
+    )
+    if component_count <= 1:
+        return None
+
+    largest_component = 1 + np.argmax(stats[1:, cv2.CC_STAT_AREA])
+    region = labels == largest_component
+    if np.count_nonzero(region) < 1_000:
+        return None
+    return region
+
+
+def create_tissue_mask(
+    image: np.ndarray,
+    debris_mask: np.ndarray | None = None,
+) -> np.ndarray:
+    """Return the established spheroid segmentation as a filled binary mask."""
+    # Imported here to avoid a module-import cycle: the quantification module
+    # reuses cleaning helpers before defining its segmentation function.
+    from ihc_quantification_simplified import segment_spheroids
+
+    image = _as_display_rgb_uint8(image)
+    segmentation_image = image
+    if debris_mask is not None:
+        if debris_mask.shape != image.shape[:2]:
+            raise ValueError("Debris mask must match the image height and width.")
+        segmentation_image = _inpaint_image(
+            segmentation_image,
+            debris_mask,
+        )
+
+    return (
+        (segment_spheroids(segmentation_image) > 0).astype(np.uint8) * 255
+    )
+
+
+def _extend_surface_to_image_edges(surface: np.ndarray) -> np.ndarray:
+    """Linearly extrapolate tile-centre estimates to the image boundaries."""
+    extended = np.empty(
+        (surface.shape[0] + 2, surface.shape[1] + 2, 3),
+        dtype=np.float32,
+    )
+    extended[1:-1, 1:-1] = surface
+    extended[0, 1:-1] = 2 * surface[0] - surface[1]
+    extended[-1, 1:-1] = 2 * surface[-1] - surface[-2]
+    extended[:, 0] = 2 * extended[:, 1] - extended[:, 2]
+    extended[:, -1] = 2 * extended[:, -2] - extended[:, -3]
+    return np.clip(extended, 0.05, 1.5)
+
+
+def correct_vignetting(
+    image: np.ndarray,
+    debris_mask: np.ndarray | None = None,
+    tissue_mask: np.ndarray | None = None,
+) -> tuple[np.ndarray, bool]:
+    """Correct smooth edge falloff when a robust background fit detects it."""
+    image = _as_display_rgb_uint8(image)
+    height, width = image.shape[:2]
+    scale = min(1, VIGNETTING_FIT_MAX_DIMENSION / max(height, width))
+    if scale < 1:
+        fit_size = (round(width * scale), round(height * scale))
+        fit_image = cv2.resize(image, fit_size, interpolation=cv2.INTER_AREA)
+    else:
+        fit_image = image
+
+    hsv = cv2.cvtColor(fit_image, cv2.COLOR_RGB2HSV)
+    background_mask = (
+        (hsv[..., 1] <= VIGNETTING_SATURATION_MAX)
+        & (hsv[..., 2] >= VIGNETTING_VALUE_MIN)
+    )
+    if debris_mask is not None:
+        if debris_mask.shape != image.shape[:2]:
+            raise ValueError("Debris mask must match the image height and width.")
+        fit_mask = debris_mask
+        if scale < 1:
+            fit_mask = cv2.resize(
+                debris_mask,
+                fit_size,
+                interpolation=cv2.INTER_NEAREST,
+            )
+        background_mask &= fit_mask == 0
+
+    background_region = _largest_connected_region(background_mask)
+    if background_region is None:
+        return image, False
+
+    surface = _estimate_vignetting_surface(
+        fit_image,
+        background_region,
+    )
+    if surface is None:
+        return image, False
+
+    grid_y, grid_x = np.meshgrid(
+        np.linspace(-1, 1, surface.shape[0]),
+        np.linspace(-1, 1, surface.shape[1]),
+        indexing="ij",
+    )
+    grid_luminance = surface @ np.array([0.2126, 0.7152, 0.0722])
+    grid_radius = np.maximum(np.abs(grid_x), np.abs(grid_y))
+    center_region = grid_radius <= 0.35
+    edge_region = grid_radius >= 0.8
+    center_level = float(np.median(grid_luminance[center_region]))
+    edge_level = float(np.percentile(grid_luminance[edge_region], 20))
+    if center_level <= np.finfo(np.float64).eps:
+        return image, False
+
+    falloff = 1 - edge_level / center_level
+    if falloff < VIGNETTING_MIN_FALLOFF:
+        return image, False
+
+    references = np.percentile(
+        fit_image[background_region].astype(np.float32) / 255,
+        90,
+        axis=0,
+    )
+    extended_surface = _extend_surface_to_image_edges(surface)
+    corrected = image.copy()
+    correction_region = cv2.resize(
+        background_region.astype(np.uint8),
+        (width, height),
+        interpolation=cv2.INTER_NEAREST,
+    ).astype(bool)
+    full_hsv = cv2.cvtColor(image, cv2.COLOR_RGB2HSV)
+    correction_region &= (
+        (full_hsv[..., 1] <= VIGNETTING_SATURATION_MAX)
+        & (full_hsv[..., 2] >= VIGNETTING_VALUE_MIN)
+    )
+    if tissue_mask is None:
+        tissue_mask = create_tissue_mask(image, debris_mask)
+    elif tissue_mask.shape != image.shape[:2]:
+        raise ValueError("Tissue mask must match the image height and width.")
+    correction_region &= tissue_mask == 0
+    if debris_mask is not None:
+        correction_region &= debris_mask == 0
+    surface_y = np.clip(
+        (np.arange(height, dtype=np.float32) + 0.5)
+        * surface.shape[0]
+        / height
+        + 0.5,
+        0,
+        extended_surface.shape[0] - 1,
+    )
+    surface_x = np.clip(
+        (np.arange(width, dtype=np.float32) + 0.5)
+        * surface.shape[1]
+        / width
+        + 0.5,
+        0,
+        extended_surface.shape[1] - 1,
+    )
+    source_x = np.arange(extended_surface.shape[1], dtype=np.float32)
+
+    for channel in range(3):
+        horizontal_surface = np.vstack(
+            [
+                np.interp(surface_x, source_x, row)
+                for row in extended_surface[..., channel]
+            ]
+        ).astype(np.float32)
+        for row_start in range(0, height, VIGNETTING_CORRECTION_ROWS):
+            row_stop = min(row_start + VIGNETTING_CORRECTION_ROWS, height)
+            y = surface_y[row_start:row_stop]
+            y_low = np.floor(y).astype(np.int32)
+            y_high = np.minimum(y_low + 1, extended_surface.shape[0] - 1)
+            y_fraction = (y - y_low)[:, None]
+            strip_surface = (
+                horizontal_surface[y_low] * (1 - y_fraction)
+                + horizontal_surface[y_high] * y_fraction
+            )
+            strip_surface = np.clip(strip_surface, 0.05, 1.5)
+            gain = np.clip(
+                references[channel] / strip_surface,
+                1,
+                VIGNETTING_MAX_GAIN,
+            )
+            corrected_channel = corrected[
+                row_start:row_stop,
+                :,
+                channel,
+            ].astype(np.float32)
+            corrected_values = np.clip(
+                np.rint(corrected_channel * gain),
+                0,
+                255,
+            ).astype(np.uint8)
+            strip_region = correction_region[row_start:row_stop]
+            corrected_channel = corrected[
+                row_start:row_stop,
+                :,
+                channel,
+            ]
+            corrected_channel[strip_region] = corrected_values[strip_region]
+
+    return corrected, True
+
+
 def clean_image(image: np.ndarray | None) -> np.ndarray:
     cleaned_image, _ = clean_image_and_mask(image)
     return cleaned_image
 
 
+def _inpaint_image(image: np.ndarray, debris_mask: np.ndarray) -> np.ndarray:
+    return cv2.inpaint(
+        image,
+        debris_mask,
+        INPAINT_RADIUS,
+        cv2.INPAINT_TELEA,
+    )
+
+
 def clean_image_and_mask(
     image: np.ndarray | None,
 ) -> tuple[np.ndarray, np.ndarray]:
@@ -192,10 +512,27 @@ def clean_image_and_mask(
 
     image = _as_rgb_uint8(image)
     debris_mask = create_debris_mask(image)
-    cleaned_image = cv2.inpaint(
-        image,
+    cleaned_image = _inpaint_image(image, debris_mask)
+    return cleaned_image, debris_mask
+
+
+def clean_display_image_and_mask(
+    processing_image: np.ndarray | None,
+    display_image: np.ndarray | None,
+) -> tuple[np.ndarray, np.ndarray]:
+    if processing_image is None or display_image is None:
+        raise ValueError("Processing and display images are required.")
+
+    processing_image = _as_rgb_uint8(processing_image)
+    display_image = _as_display_rgb_uint8(display_image)
+    if processing_image.shape != display_image.shape:
+        raise ValueError("Processing and display images must have the same shape.")
+
+    debris_mask = create_debris_mask(processing_image)
+    tissue_mask = create_tissue_mask(processing_image, debris_mask)
+    corrected_display, _ = correct_vignetting(
+        display_image,
         debris_mask,
-        INPAINT_RADIUS,
-        cv2.INPAINT_TELEA,
+        tissue_mask,
     )
-    return cleaned_image, debris_mask
+    return _inpaint_image(corrected_display, debris_mask), debris_mask

main.py

@@ -4,9 +4,9 @@ from pathlib import Path
 import cv2
 
 from cleaning import (
-    clean_image_and_mask,
+    clean_display_image_and_mask,
     cleaned_image_name,
-    read_image_rgb,
+    read_image_rgb_and_preview,
     write_image_rgb,
 )
 
@@ -23,8 +23,11 @@ def main(
 
     for image_path_string in image_paths:
         image_path = Path(image_path_string)
-        image_rgb = read_image_rgb(image_path)
-        cleaned_rgb, debris_mask = clean_image_and_mask(image_rgb)
+        image_rgb, display_rgb = read_image_rgb_and_preview(image_path)
+        cleaned_rgb, debris_mask = clean_display_image_and_mask(
+            image_rgb,
+            display_rgb,
+        )
 
         cv2.imwrite(str(masks_dir / f"{image_path.stem}_mask.png"), debris_mask)
         cleaned_path = cleaned_dir / cleaned_image_name(image_path)

tests/test_preview_conversion.py

@@ -0,0 +1,213 @@
+import tempfile
+import unittest
+from pathlib import Path
+
+import cv2
+import numpy as np
+import tifffile
+from skimage.util import img_as_ubyte
+
+from cleaning import (
+    INPAINT_RADIUS,
+    _as_display_rgb_uint8,
+    _as_rgb_uint8,
+    clean_display_image_and_mask,
+    correct_vignetting,
+    create_debris_mask,
+    create_tissue_mask,
+    read_image_rgb_and_preview,
+    write_image_rgb,
+)
+
+
+class PreviewConversionTests(unittest.TestCase):
+    def test_uint16_preview_uses_full_dtype_range(self):
+        image = np.array([[0, 32768, 65535]], dtype=np.uint16)
+
+        preview = _as_display_rgb_uint8(image)
+
+        expected = np.array([0, 128, 255], dtype=np.uint8)
+        np.testing.assert_array_equal(preview[:, :, 0], expected[None, :])
+        np.testing.assert_array_equal(preview[:, :, 1], expected[None, :])
+        np.testing.assert_array_equal(preview[:, :, 2], expected[None, :])
+
+    def test_uint8_preview_is_unchanged(self):
+        image = np.array([[[10, 120, 240]]], dtype=np.uint8)
+
+        preview = _as_display_rgb_uint8(image)
+
+        np.testing.assert_array_equal(preview, image)
+
+    def test_reader_returns_separate_processing_and_display_views(self):
+        image = np.full((10, 10, 3), 32768, dtype=np.uint16)
+        image[0, 0] = 0
+        image[-1, -1] = 65535
+
+        with tempfile.TemporaryDirectory() as directory:
+            image_path = Path(directory) / "image.tiff"
+            tifffile.imwrite(image_path, image, photometric="rgb")
+
+            processing, display = read_image_rgb_and_preview(image_path)
+
+        np.testing.assert_array_equal(processing, _as_rgb_uint8(image))
+        np.testing.assert_array_equal(display, img_as_ubyte(image))
+
+    def test_cleaned_output_uses_display_brightness_and_processing_mask(self):
+        raw = np.full((32, 32, 3), 32768, dtype=np.uint16)
+        raw[12:20, 12:20] = 0
+        processing = _as_rgb_uint8(raw)
+        display = _as_display_rgb_uint8(raw)
+
+        cleaned, debris_mask = clean_display_image_and_mask(
+            processing,
+            display,
+        )
+
+        expected_mask = create_debris_mask(processing)
+        expected_cleaned = cv2.inpaint(
+            display,
+            expected_mask,
+            INPAINT_RADIUS,
+            cv2.INPAINT_TELEA,
+        )
+        np.testing.assert_array_equal(debris_mask, expected_mask)
+        np.testing.assert_array_equal(cleaned, expected_cleaned)
+
+    def test_vignetting_correction_flattens_detected_edge_falloff(self):
+        size = 160
+        axis = np.linspace(-1, 1, size, dtype=np.float32)
+        x, y = np.meshgrid(axis, axis)
+        illumination = 1 - 0.18 * (x * x + y * y)
+        base_color = np.array([230, 220, 210], dtype=np.float32)
+        image = np.clip(
+            illumination[..., None] * base_color,
+            0,
+            255,
+        ).astype(np.uint8)
+
+        corrected, was_corrected = correct_vignetting(image)
+
+        center = np.s_[60:100, 60:100]
+        border = np.zeros((size, size), dtype=bool)
+        border[:20] = True
+        border[-20:] = True
+        border[:, :20] = True
+        border[:, -20:] = True
+        before_gap = image[center].mean() - image[border].mean()
+        after_gap = corrected[center].mean() - corrected[border].mean()
+        self.assertTrue(was_corrected)
+        self.assertLess(abs(after_gap), abs(before_gap) * 0.25)
+
+    def test_uniform_image_skips_vignetting_correction(self):
+        image = np.full((128, 128, 3), 220, dtype=np.uint8)
+
+        corrected, was_corrected = correct_vignetting(image)
+
+        self.assertFalse(was_corrected)
+        np.testing.assert_array_equal(corrected, image)
+
+    def test_vignetting_correction_handles_steep_one_sided_falloff(self):
+        height, width = 180, 240
+        x = np.linspace(0, 1, width, dtype=np.float32)
+        illumination = 1 - 0.35 * np.clip((x - 0.72) / 0.28, 0, 1)
+        base_color = np.array([245, 240, 235], dtype=np.float32)
+        image = np.clip(
+            illumination[None, :, None] * base_color,
+            0,
+            255,
+        ).astype(np.uint8)
+        image = np.repeat(image, height, axis=0)
+
+        corrected, was_corrected = correct_vignetting(image)
+
+        center_level = image[:, 80:140].mean()
+        edge_level = image[:, -12:].mean()
+        corrected_center_level = corrected[:, 80:140].mean()
+        corrected_edge_level = corrected[:, -12:].mean()
+        before_gap = center_level - edge_level
+        after_gap = corrected_center_level - corrected_edge_level
+        self.assertTrue(was_corrected)
+        self.assertLess(after_gap, before_gap * 0.15)
+
+    def test_vignetting_correction_preserves_stained_tissue(self):
+        height, width = 180, 240
+        x = np.linspace(0, 1, width, dtype=np.float32)
+        illumination = 1 - 0.30 * np.clip((x - 0.65) / 0.35, 0, 1)
+        background_color = np.array([245, 240, 235], dtype=np.float32)
+        image = np.clip(
+            illumination[None, :, None] * background_color,
+            0,
+            255,
+        ).astype(np.uint8)
+        image = np.repeat(image, height, axis=0)
+        tissue_mask = np.zeros((height, width), dtype=np.uint8)
+        cv2.circle(tissue_mask, (190, 90), 35, 255, cv2.FILLED)
+        tissue_color = np.array([155, 90, 110], dtype=np.uint8)
+        image[tissue_mask > 0] = tissue_color
+
+        corrected, was_corrected = correct_vignetting(image)
+
+        self.assertTrue(was_corrected)
+        np.testing.assert_array_equal(
+            corrected[tissue_mask > 0],
+            image[tissue_mask > 0],
+        )
+        self.assertGreater(
+            corrected[:, -12:][tissue_mask[:, -12:] == 0].mean(),
+            image[:, -12:][tissue_mask[:, -12:] == 0].mean() + 40,
+        )
+
+    def test_tissue_mask_fills_and_preserves_pale_spheroid_interior(self):
+        height, width = 240, 320
+        x = np.linspace(0, 1, width, dtype=np.float32)
+        illumination = 1 - 0.30 * np.clip((x - 0.65) / 0.35, 0, 1)
+        background_color = np.array([245, 240, 235], dtype=np.float32)
+        image = np.clip(
+            illumination[None, :, None] * background_color,
+            0,
+            255,
+        ).astype(np.uint8)
+        image = np.repeat(image, height, axis=0)
+
+        spheroid = np.zeros((height, width), dtype=np.uint8)
+        cv2.circle(spheroid, (250, 120), 55, 255, cv2.FILLED)
+        image[spheroid > 0] = [220, 205, 205]
+        cv2.circle(image, (250, 120), 55, (150, 85, 105), 10)
+        image[110:130, 240:260] = 0
+
+        tissue_mask = create_tissue_mask(image)
+        corrected, was_corrected = correct_vignetting(image)
+        cleaned, debris_mask = clean_display_image_and_mask(image, image)
+
+        self.assertTrue(was_corrected)
+        self.assertEqual(tissue_mask[120, 250], 255)
+        np.testing.assert_array_equal(
+            corrected[spheroid > 0],
+            image[spheroid > 0],
+        )
+        self.assertTrue(np.any(debris_mask[110:130, 240:260]))
+        self.assertFalse(
+            np.array_equal(
+                cleaned[110:130, 240:260],
+                image[110:130, 240:260],
+            )
+        )
+
+    def test_tiff_output_uses_lossless_lzw_compression(self):
+        image = np.full((128, 128, 3), 127, dtype=np.uint8)
+
+        with tempfile.TemporaryDirectory() as directory:
+            image_path = Path(directory) / "cleaned.tiff"
+            write_image_rgb(image_path, image)
+
+            with tifffile.TiffFile(image_path) as tiff:
+                page = tiff.pages[0]
+                self.assertEqual(page.compression.name, "LZW")
+                self.assertEqual(page.tags["Predictor"].value, 2)
+                np.testing.assert_array_equal(page.asarray(), image)
+
+            self.assertLess(image_path.stat().st_size, image.nbytes)
+
+
+if __name__ == "__main__":
+    unittest.main()