Add image cleanup app

.gitattributes

@@ -33,3 +33,6 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+*.png filter=lfs diff=lfs merge=lfs -text
+*.tif filter=lfs diff=lfs merge=lfs -text
+*.tiff filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -0,0 +1,4 @@
+.DS_Store
+__pycache__
+out/
+data/test

.python-version

@@ -0,0 +1 @@
+3.12.11

README.md

@@ -1,13 +1,48 @@
 ---
-title: Ihc Cleanup
-emoji: 👀
-colorFrom: yellow
+title: Image Cleanup
+emoji: 🧑‍🔬
+colorFrom: pink
 colorTo: yellow
 sdk: gradio
-sdk_version: 6.20.0
-python_version: '3.12'
+sdk_version: 6.19.0
+python_version: 3.12.11
 app_file: app.py
 pinned: false
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# Image cleanup
+
+Script for removing dark, low-saturation debris from IHC images with OpenCV
+inpainting.
+
+```bash
+uv sync
+uv run python main.py data/dirty.png
+```
+
+PNG, JPEG, TIFF, and TIF inputs are supported. Cleaned images are written to
+`out/cleaned/` with `_cleaned` added before the original extension, and masks
+are written to `out/masks/` as PNG files.
+
+An optional Gradio interface is also available:
+
+```bash
+uv run python app.py
+```
+
+Open the local URL printed in the terminal, upload an input image, and select
+**Clean image**. TIFF inputs are converted to PNG previews in the interface,
+and the cleaned file can be downloaded with the original extension.
+
+For batch processing, open the **Image directory** tab and select a folder.
+The app processes all uploaded images, including `.tif` and `.tiff` files, and
+returns a ZIP archive.
+
+Project layout:
+
+- `main.py` — primary image-cleaning script
+- `cleaning.py` — reusable cleaning operations
+- `app.py` — optional Gradio interface
+- `data/` — source and example images
+- `out/` — generated cleaned images and masks
+- `test.ipynb` — image-cleaning experiments

app.py

@@ -0,0 +1,162 @@
+import tempfile
+import zipfile
+from pathlib import Path
+from uuid import uuid4
+
+import gradio as gr
+
+from cleaning import (
+    clean_image,
+    cleaned_image_name,
+    read_image_rgb,
+    write_image_rgb,
+)
+
+_BATCH_OUTPUTS = tempfile.TemporaryDirectory(prefix="ihc-cleaner-")
+_EXAMPLE_IMAGES = [["data/dirty.png"], ["data/dirty.tiff"]]
+_IMAGE_FILE_TYPES = ["image", ".tif", ".tiff"]
+
+
+def _uploaded_path(file_path: str | Path | None) -> Path:
+    if not file_path:
+        raise ValueError("Upload an input image.")
+
+    return Path(file_path)
+
+
+def preview_image(file_path: str | Path | None):
+    if not file_path:
+        return None, None, None
+
+    return read_image_rgb(file_path), None, None
+
+
+def clean_uploaded_image(file_path: str | Path | None):
+    image_path = _uploaded_path(file_path)
+    output_dir = Path(_BATCH_OUTPUTS.name) / uuid4().hex
+    output_dir.mkdir(parents=True)
+
+    image_rgb = read_image_rgb(image_path)
+    cleaned_rgb = clean_image(image_rgb)
+    cleaned_path = output_dir / cleaned_image_name(image_path)
+    write_image_rgb(cleaned_path, cleaned_rgb)
+
+    return image_rgb, cleaned_rgb, str(cleaned_path)
+
+
+def clean_directory(image_paths: list[str] | None) -> tuple[str, str]:
+    if not image_paths:
+        raise ValueError("Upload a directory containing images.")
+
+    batch_dir = Path(_BATCH_OUTPUTS.name) / uuid4().hex
+    cleaned_dir = batch_dir / "cleaned"
+    cleaned_dir.mkdir(parents=True)
+
+    used_names: set[str] = set()
+
+    for image_path_string in image_paths:
+        image_path = Path(image_path_string)
+        cleaned_rgb = clean_image(read_image_rgb(image_path))
+
+        output_name = cleaned_image_name(image_path, used_names)
+        write_image_rgb(cleaned_dir / output_name, cleaned_rgb)
+
+    archive_path = batch_dir / "cleaned_images.zip"
+    with zipfile.ZipFile(archive_path, "w", zipfile.ZIP_DEFLATED) as archive:
+        for cleaned_path in sorted(cleaned_dir.iterdir()):
+            archive.write(cleaned_path, arcname=cleaned_path.name)
+
+    count = len(used_names)
+    return str(archive_path), f"Cleaned {count} image{'s' if count != 1 else ''}."
+
+
+def build_app() -> gr.Blocks:
+    with gr.Blocks(title="Image Cleanup") as app:
+        gr.Markdown(
+            "# Image Cleanup\n"
+            "Upload an input image to remove dark, low-saturation debris."
+        )
+
+        with gr.Tab("Single image"):
+            with gr.Row():
+                input_image = gr.File(
+                    label="Input image",
+                    file_types=_IMAGE_FILE_TYPES,
+                    type="filepath",
+                )
+                cleaned_file = gr.File(
+                    label="Cleaned file",
+                    interactive=False,
+                )
+            with gr.Row():
+                input_preview = gr.Image(
+                    label="Input preview",
+                    format="png",
+                    buttons=["fullscreen"],
+                    interactive=False,
+                )
+                cleaned_preview = gr.Image(
+                    label="Cleaned image",
+                    format="png",
+                    buttons=["fullscreen"],
+                    interactive=False,
+                )
+
+            with gr.Row():
+                clean_button = gr.Button("Clean image", variant="primary")
+                gr.ClearButton(
+                    [input_image, input_preview, cleaned_preview, cleaned_file]
+                )
+
+            gr.Examples(
+                examples=_EXAMPLE_IMAGES,
+                inputs=input_image,
+                label="Example image",
+            )
+
+            input_image.change(
+                fn=preview_image,
+                inputs=input_image,
+                outputs=[input_preview, cleaned_preview, cleaned_file],
+                api_name=False,
+            )
+
+            clean_button.click(
+                fn=clean_uploaded_image,
+                inputs=input_image,
+                outputs=[input_preview, cleaned_preview, cleaned_file],
+                api_name="clean_image",
+            )
+
+        with gr.Tab("Image directory"):
+            directory_input = gr.File(
+                label="Image directory",
+                file_count="directory",
+                file_types=_IMAGE_FILE_TYPES,
+                type="filepath",
+            )
+            clean_directory_button = gr.Button(
+                "Clean directory",
+                variant="primary",
+            )
+            batch_status = gr.Textbox(label="Status", interactive=False)
+            batch_download = gr.File(
+                label="Cleaned images",
+                interactive=False,
+            )
+
+            clean_directory_button.click(
+                fn=clean_directory,
+                inputs=directory_input,
+                outputs=[batch_download, batch_status],
+                api_name="clean_directory",
+            )
+
+    return app
+
+
+demo = build_app()
+
+
+if __name__ == "__main__":
+    demo.launch(ssr_mode=False)

cleaning.py

@@ -0,0 +1,145 @@
+from pathlib import Path
+
+import cv2
+import numpy as np
+
+TIFF_EXTENSIONS = {".tif", ".tiff"}
+
+
+def _as_rgb_uint8(image: np.ndarray) -> np.ndarray:
+    image = np.asarray(image)
+
+    if image.ndim == 3 and image.shape[2] == 1:
+        image = image[:, :, 0]
+
+    if image.ndim == 2:
+        image = cv2.cvtColor(image, cv2.COLOR_GRAY2RGB)
+    elif image.ndim != 3:
+        raise ValueError("Expected a grayscale or RGB image.")
+
+    if image.shape[2] == 4:
+        image = cv2.cvtColor(image, cv2.COLOR_RGBA2RGB)
+    elif image.shape[2] != 3:
+        raise ValueError("Expected an image with 1, 3, or 4 channels.")
+
+    if image.dtype != np.uint8:
+        image = image.astype(np.float32)
+        if image.size:
+            max_value = float(np.nanmax(image))
+            if max_value <= 1:
+                image *= 255
+            elif max_value > 255:
+                image *= 255 / max_value
+        image = np.clip(image, 0, 255).astype(np.uint8)
+
+    return image
+
+
+def _is_tiff_path(image_path: str | Path) -> bool:
+    return Path(image_path).suffix.lower() in TIFF_EXTENSIONS
+
+
+def cleaned_image_name(
+    image_path: str | Path,
+    used_names: set[str] | None = None,
+) -> str:
+    image_path = Path(image_path)
+    extension = image_path.suffix or ".png"
+    output_name = f"{image_path.stem}_cleaned{extension}"
+
+    if used_names is None:
+        return output_name
+
+    suffix = 2
+    while output_name in used_names:
+        output_name = f"{image_path.stem}_cleaned_{suffix}{extension}"
+        suffix += 1
+
+    used_names.add(output_name)
+    return output_name
+
+
+def _select_tiff_plane(image: np.ndarray) -> np.ndarray:
+    image = np.asarray(image)
+
+    while image.ndim > 2 and 1 in image.shape:
+        image = np.squeeze(image)
+
+    if image.ndim == 2:
+        return image
+
+    if image.ndim == 3:
+        if image.shape[-1] in {1, 3, 4}:
+            return image
+        if image.shape[0] in {1, 3, 4}:
+            return np.moveaxis(image, 0, -1)
+
+    raise ValueError("Expected a 2D grayscale or RGB TIFF image.")
+
+
+def read_image_rgb(image_path: str | Path) -> np.ndarray:
+    image_path = Path(image_path)
+
+    if _is_tiff_path(image_path):
+        try:
+            import tifffile
+        except ImportError as exc:
+            raise ImportError(
+                "Reading TIFF images requires the tifffile package."
+            ) from exc
+
+        image = tifffile.imread(image_path)
+        return _as_rgb_uint8(_select_tiff_plane(image))
+
+    image = cv2.imread(str(image_path), cv2.IMREAD_UNCHANGED)
+    if image is None:
+        raise FileNotFoundError(f"Could not read image: {image_path}")
+
+    if image.ndim == 3 and image.shape[2] == 3:
+        image = cv2.cvtColor(image, cv2.COLOR_BGR2RGB)
+    elif image.ndim == 3 and image.shape[2] == 4:
+        image = cv2.cvtColor(image, cv2.COLOR_BGRA2RGBA)
+
+    return _as_rgb_uint8(image)
+
+
+def write_image_rgb(image_path: str | Path, image: np.ndarray) -> None:
+    image_path = Path(image_path)
+    image = _as_rgb_uint8(image)
+
+    if _is_tiff_path(image_path):
+        try:
+            import tifffile
+        except ImportError as exc:
+            raise ImportError(
+                "Writing TIFF images requires the tifffile package."
+            ) from exc
+
+        tifffile.imwrite(image_path, image)
+        return
+
+    image_bgr = cv2.cvtColor(image, cv2.COLOR_RGB2BGR)
+
+    if not cv2.imwrite(str(image_path), image_bgr):
+        raise OSError(f"Could not write image: {image_path}")
+
+
+def create_debris_mask(image: np.ndarray) -> np.ndarray:
+    image = _as_rgb_uint8(image)
+    hsv = cv2.cvtColor(image, cv2.COLOR_RGB2HSV)
+    _, saturation, value = cv2.split(hsv)
+
+    debris_mask = ((value < 60) & (saturation < 50)).astype(np.uint8) * 255
+
+    kernel = cv2.getStructuringElement(cv2.MORPH_ELLIPSE, (3, 3))
+    debris_mask = cv2.morphologyEx(debris_mask, cv2.MORPH_OPEN, kernel)
+    return cv2.dilate(debris_mask, kernel)
+
+
+def clean_image(image: np.ndarray | None) -> np.ndarray:
+    if image is None:
+        raise ValueError("An input image is required.")
+
+    image = _as_rgb_uint8(image)
+    debris_mask = create_debris_mask(image)
+    return cv2.inpaint(image, debris_mask, 3, cv2.INPAINT_NS)

create_test_images.py

@@ -0,0 +1,39 @@
+import cv2
+import numpy as np
+from skimage import io
+
+
+def add_debris(img, n_debris=40, seed=None):
+    rng = np.random.default_rng(seed)
+    h, w = img.shape[:2]
+    out = img.copy()
+    mask = np.zeros((h, w), dtype=np.uint8)
+
+    for _ in range(n_debris):
+        cx = rng.integers(10, w - 10)
+        cy = rng.integers(10, h - 10)
+        radius = int(rng.choice(np.concatenate([
+            rng.integers(20, 40,   size=6),  # small specks
+            rng.integers(40, 60,  size=3),  # medium
+            rng.integers(100, 120, size=1),  # occasional big chunk
+        ])))
+
+        # irregular blob via random polygon
+        n_pts  = rng.integers(6, 14)
+        angles = np.linspace(0, 2 * np.pi, n_pts, endpoint=False)
+        angles += rng.uniform(-0.2, 0.2, n_pts)
+        radii  = radius * rng.uniform(0.5, 1.4, n_pts)
+        pts = np.stack([
+            cx + radii * np.cos(angles),
+            cy + radii * np.sin(angles)
+        ], axis=1).astype(np.int32)
+
+        cv2.fillPoly(out, [pts], color=(10, 10, 10))
+        cv2.fillPoly(mask, [pts], color=255)
+
+    return out, mask
+img = io.imread("data/original.tiff")[:, :, :3]
+
+for i in range(10):
+    dirty, mask = add_debris(img, n_debris=60)
+    io.imsave(f"data/test/dirty{i}.tiff", dirty)

main.py

@@ -0,0 +1,53 @@
+import argparse
+from pathlib import Path
+
+import cv2
+
+from cleaning import (
+    clean_image,
+    cleaned_image_name,
+    create_debris_mask,
+    read_image_rgb,
+    write_image_rgb,
+)
+
+
+def main(
+    image_paths: list[str],
+    output_dir: str | Path = "out",
+) -> None:
+    output_dir = Path(output_dir)
+    cleaned_dir = output_dir / "cleaned"
+    masks_dir = output_dir / "masks"
+    cleaned_dir.mkdir(parents=True, exist_ok=True)
+    masks_dir.mkdir(parents=True, exist_ok=True)
+
+    for image_path_string in image_paths:
+        image_path = Path(image_path_string)
+        image_rgb = read_image_rgb(image_path)
+        debris_mask = create_debris_mask(image_rgb)
+        cleaned_rgb = clean_image(image_rgb)
+
+        cv2.imwrite(str(masks_dir / f"{image_path.stem}_mask.png"), debris_mask)
+        cleaned_path = cleaned_dir / cleaned_image_name(image_path)
+        write_image_rgb(cleaned_path, cleaned_rgb)
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description="Clean debris from IHC images.")
+    parser.add_argument(
+        "images",
+        nargs="+",
+        help="Paths to one or more input images.",
+    )
+    parser.add_argument(
+        "--output-dir",
+        default="out",
+        help="Directory for cleaned images and masks (default: out).",
+    )
+    return parser.parse_args()
+
+
+if __name__ == "__main__":
+    args = parse_args()
+    main(args.images, args.output_dir)

pyproject.toml

@@ -0,0 +1,120 @@
+[project]
+name = "ihc-cleanup"
+version = "0.1.0"
+requires-python = ">=3.12"
+dependencies = [
+    "anyio==4.13.0",
+    "appnope==0.1.4",
+    "argon2-cffi==25.1.0",
+    "argon2-cffi-bindings==25.1.0",
+    "arrow==1.4.0",
+    "asttokens==3.0.1",
+    "async-lru==2.3.0",
+    "attrs==26.1.0",
+    "babel==2.18.0",
+    "beautifulsoup4==4.15.0",
+    "bleach==6.4.0",
+    "certifi==2026.5.20",
+    "cffi==2.0.0",
+    "charset-normalizer==3.4.7",
+    "comm==0.2.3",
+    "contourpy==1.3.3",
+    "cycler==0.12.1",
+    "debugpy==1.8.21",
+    "decorator==5.3.1",
+    "defusedxml==0.7.1",
+    "executing==2.2.1",
+    "fastjsonschema==2.21.2",
+    "fonttools==4.63.0",
+    "fqdn==1.5.1",
+    "gradio>=5.0,<7",
+    "h11==0.16.0",
+    "httpcore==1.0.9",
+    "httpx==0.28.1",
+    "idna==3.18",
+    "imageio==2.37.3",
+    "ipykernel==7.3.0",
+    "ipython==9.14.1",
+    "ipython-pygments-lexers==1.1.1",
+    "ipywidgets==8.1.8",
+    "isoduration==20.11.0",
+    "jedi==0.20.0",
+    "jinja2==3.1.6",
+    "json5==0.14.0",
+    "jsonpointer==3.1.1",
+    "jsonschema==4.26.0",
+    "jsonschema-specifications==2025.9.1",
+    "jupyter==1.1.1",
+    "jupyter-client==8.9.1",
+    "jupyter-console==6.6.3",
+    "jupyter-core==5.9.1",
+    "jupyter-events==0.12.1",
+    "jupyter-lsp==2.3.1",
+    "jupyter-server==2.19.0",
+    "jupyter-server-terminals==0.5.4",
+    "jupyterlab==4.5.8",
+    "jupyterlab-pygments==0.3.0",
+    "jupyterlab-server==2.28.0",
+    "jupyterlab-widgets==3.0.16",
+    "kiwisolver==1.5.0",
+    "lark==1.3.1",
+    "lazy-loader==0.5",
+    "markupsafe==3.0.3",
+    "matplotlib==3.10.9",
+    "matplotlib-inline==0.2.2",
+    "mistune==3.2.1",
+    "nbclient==0.11.0",
+    "nbconvert==7.17.1",
+    "nbformat==5.10.4",
+    "nest-asyncio2==1.7.2",
+    "networkx==3.6.1",
+    "notebook==7.5.7",
+    "notebook-shim==0.2.4",
+    "numpy==2.4.6",
+    "opencv-python==4.13.0.92",
+    "packaging==26.2",
+    "pandocfilters==1.5.1",
+    "parso==0.8.7",
+    "pexpect==4.9.0",
+    "pillow==12.2.0",
+    "platformdirs==4.10.0",
+    "prometheus-client==0.25.0",
+    "prompt-toolkit==3.0.52",
+    "psutil==7.2.2",
+    "ptyprocess==0.7.0",
+    "pure-eval==0.2.3",
+    "pycparser==3.0",
+    "pygments==2.20.0",
+    "pyparsing==3.3.2",
+    "python-dateutil==2.9.0.post0",
+    "python-json-logger==4.1.0",
+    "pyyaml==6.0.3",
+    "pyzmq==27.1.0",
+    "referencing==0.37.0",
+    "requests==2.34.2",
+    "rfc3339-validator==0.1.4",
+    "rfc3986-validator==0.1.1",
+    "rfc3987-syntax==1.1.0",
+    "rpds-py==2026.5.1",
+    "scikit-image==0.26.0",
+    "scipy==1.17.1",
+    "send2trash==2.1.0",
+    "setuptools==82.0.1",
+    "six==1.17.0",
+    "soupsieve==2.8.4",
+    "stack-data==0.6.3",
+    "terminado==0.18.1",
+    "tifffile==2026.6.1",
+    "tinycss2==1.5.1",
+    "tornado==6.5.7",
+    "traitlets==5.15.1",
+    "typing-extensions==4.15.0",
+    "tzdata==2026.2",
+    "uri-template==1.3.0",
+    "urllib3==2.7.0",
+    "wcwidth==0.8.1",
+    "webcolors==25.10.0",
+    "webencodings==0.5.1",
+    "websocket-client==1.9.0",
+    "widgetsnbextension==4.0.15",
+]

pyrefly.toml

@@ -0,0 +1,4 @@
+project-includes = [
+    "**/*.py*",
+    "**/*.ipynb",
+]

requirements.txt

@@ -0,0 +1,3 @@
+numpy==2.4.6
+opencv-python-headless==4.13.0.92
+tifffile==2026.6.1