rmcontrols 0.1.0__py3-none-any.whl

rmcontrols/__init__.py

@@ -0,0 +1,46 @@
+"""rmcontrols — detect and flag control tissues in IHC thumbnail images."""
+
+from ._extract import ExtractResult, extract_thumbnails
+from ._hooks import DetectionHooks
+from ._region import ControlRegion
+from ._s3 import (
+    glob_s3,
+    load_mrxs_thumbnail_from_s3,
+    load_slide_thumbnail_from_s3,
+    open_slide_thumbnail,
+)
+from ._validation import (
+    validate_control_split_x,
+    validate_control_split_x_batch,
+    validate_control_split_x_wsi,
+)
+from .detector import detect_controls, detect_controls_debug
+from .viz import visualize, visualize_debug
+
+__version__ = "0.1.0"
+
+__all__ = [
+    # Detection
+    "detect_controls",
+    "detect_controls_debug",
+    # Data classes
+    "ControlRegion",
+    "DetectionHooks",
+    # Rendering
+    "visualize",
+    "visualize_debug",
+    # Interactive validation
+    "validate_control_split_x",
+    "validate_control_split_x_batch",
+    "validate_control_split_x_wsi",
+    # Thumbnail extraction
+    "extract_thumbnails",
+    "ExtractResult",
+    # S3 / slide reader
+    "glob_s3",
+    "load_slide_thumbnail_from_s3",
+    "load_mrxs_thumbnail_from_s3",  # backwards-compat alias
+    "open_slide_thumbnail",
+    # Package metadata
+    "__version__",
+]

rmcontrols/_blobs.py

@@ -0,0 +1,110 @@
+"""Connected-component blob extraction from binary tissue masks."""
+
+from __future__ import annotations
+
+import numpy as np
+from scipy import ndimage
+
+from ._types import BlobDict
+
+
+def _extract_blobs(mask: np.ndarray, min_area: int) -> list[BlobDict]:
+    """Extract connected components from a binary mask and filter by area.
+
+    Uses :func:`scipy.ndimage.find_objects` for a single-pass label scan
+    instead of repeated full-array comparisons (``labeled == i``), reducing
+    complexity from ``O(H × W × n_blobs)`` to ``O(H × W + sum(blob_areas))``.
+
+    Parameters
+    ----------
+    mask : np.ndarray, shape (H, W), dtype bool
+        Binary tissue mask.
+    min_area : int
+        Blobs with fewer than this many pixels are discarded.
+
+    Returns
+    -------
+    list of BlobDict
+        One dict per surviving blob, with ``blob_id``, ``pixels``, ``area``,
+        ``bbox``, ``centroid``, and ``role`` populated.  ``features`` is not
+        populated here; see :func:`~rmcontrols._features._shape_features`.
+    """
+    labeled, _ = ndimage.label(mask)
+    slices = ndimage.find_objects(labeled)  # one pass over the label array
+    blobs: list[BlobDict] = []
+
+    for blob_id, sl in enumerate(slices, start=1):
+        if sl is None:
+            continue
+        rows_sl, cols_sl = sl
+        sub = labeled[sl] == blob_id
+        area = int(sub.sum())
+        if area < min_area:
+            continue
+
+        r0, c0 = rows_sl.start, cols_sl.start
+        r1, c1 = rows_sl.stop - 1, cols_sl.stop - 1
+        rows_idx, cols_idx = np.where(sub)
+        pixels = np.column_stack([rows_idx + r0, cols_idx + c0])
+
+        blobs.append(
+            {
+                "blob_id": blob_id,
+                "pixels": pixels,
+                "area": area,
+                "bbox": (c0, r0, c1 - c0 + 1, r1 - r0 + 1),
+                "centroid": (
+                    float(pixels[:, 0].mean()),
+                    float(pixels[:, 1].mean()),
+                ),
+                "role": "main",
+            }
+        )
+
+    return blobs
+
+
+def _perimeter(pixels: np.ndarray) -> int:
+    """Count the boundary pixels of a blob.
+
+    Converts the pixel set to a compact boolean mask, then erodes it by one
+    step; pixels present in the original but absent after erosion are the
+    boundary.
+
+    Parameters
+    ----------
+    pixels : np.ndarray, shape (N, 2), dtype int
+        Row/column coordinates of every foreground pixel (full-image frame).
+
+    Returns
+    -------
+    int
+        Number of boundary pixels.
+    """
+    local = _pixels_to_mask(pixels)
+    boundary = local & ~ndimage.binary_erosion(local)
+    return int(boundary.sum())
+
+
+def _pixels_to_mask(pixels: np.ndarray) -> np.ndarray:
+    """Convert a pixel-coordinate array to a compact boolean mask.
+
+    The output mask is the tightest bounding box that contains all pixels;
+    its origin corresponds to the minimum row and column in *pixels*.
+
+    Parameters
+    ----------
+    pixels : np.ndarray, shape (N, 2), dtype int
+        Row/column coordinates in any reference frame.
+
+    Returns
+    -------
+    np.ndarray, dtype bool
+        Local boolean mask sized ``(max_row - min_row + 1,
+        max_col - min_col + 1)``.
+    """
+    rows, cols = pixels[:, 0], pixels[:, 1]
+    r0, c0 = int(rows.min()), int(cols.min())
+    out = np.zeros((int(rows.max()) - r0 + 1, int(cols.max()) - c0 + 1), dtype=bool)
+    out[rows - r0, cols - c0] = True
+    return out

rmcontrols/_build.py

@@ -0,0 +1,41 @@
+"""Build public ControlRegion objects from raw blob dicts."""
+
+from __future__ import annotations
+
+from ._region import ControlRegion
+from ._types import BlobDict
+
+
+def _build_regions(blobs: list[BlobDict]) -> list[ControlRegion]:
+    """Convert a list of accepted control blobs into public ControlRegion objects.
+
+    Blobs are sorted by centroid column position (left-to-right) so that
+    labels are assigned in a consistent, human-readable order regardless of
+    the order in which connected components were labelled.
+
+    Parameters
+    ----------
+    blobs : list of BlobDict
+        Accepted control blobs (role ``'strip_control'`` or
+        ``'strip_proximity'``).  Each must have ``centroid``, ``bbox``,
+        ``area``, and ``features`` populated.
+
+    Returns
+    -------
+    list of ControlRegion
+        One :class:`~rmcontrols.ControlRegion` per blob, labelled
+        ``'control_0'``, ``'control_1'``, … in centroid-column order.
+    """
+    sorted_blobs = sorted(blobs, key=lambda b: (b["centroid"][1], b["centroid"][0]))
+    return [
+        ControlRegion(
+            label=f"control_{i}",
+            bbox=b["bbox"],
+            metadata={
+                "area_px": b["area"],
+                "centroid": b["centroid"],
+                "features": b.get("features", {}),
+            },
+        )
+        for i, b in enumerate(sorted_blobs)
+    ]

rmcontrols/_cli_extract.py

@@ -0,0 +1,130 @@
+"""CLI entry point for parallel thumbnail extraction from whole-slide images.
+
+Entry point
+-----------
+``rmcontrols-extract-thumbnails``
+    Resolve a local or S3 glob pattern, extract a downsampled thumbnail
+    from each matched slide in parallel, and save the results as PNG (or
+    other Pillow-supported) image files.
+
+Examples
+--------
+::
+
+    # Local slides (non-recursive: only files directly inside slides/)
+    rmcontrols-extract-thumbnails "slides/*.svs" --output-dir thumbnails/
+
+    # Multiple formats via brace expansion (shell-level)
+    rmcontrols-extract-thumbnails "slides/*.mrxs" --output-dir thumbnails/ \\
+        --thumbnail-size 2000 --workers 8
+
+    # S3 slides
+    rmcontrols-extract-thumbnails "s3://my-bucket/slides/*.svs" \\
+        --output-dir thumbnails/
+
+    # S3 with explicit AWS profile and JPEG output
+    rmcontrols-extract-thumbnails "s3://my-bucket/slides/*.ndpi" \\
+        --output-dir thumbnails/ --format jpeg --aws-profile my-profile
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+
+def main(argv: list[str] | None = None) -> None:
+    """Entry point for ``rmcontrols-extract-thumbnails``."""
+    parser = argparse.ArgumentParser(
+        prog="rmcontrols-extract-thumbnails",
+        description=(
+            "Extract downsampled thumbnails from whole-slide images matched"
+            " by a glob pattern (local or S3). Slides are processed in parallel."
+        ),
+        formatter_class=argparse.ArgumentDefaultsHelpFormatter,
+    )
+    parser.add_argument(
+        "glob",
+        help=(
+            "Glob pattern for slide files, e.g. 'slides/*.svs' or"
+            " 's3://bucket/slides/*.mrxs'. Quote to prevent shell expansion."
+            " The pattern is non-recursive: '*' does not cross '/' boundaries."
+        ),
+    )
+    parser.add_argument(
+        "--output-dir",
+        "-o",
+        type=Path,
+        default=Path("thumbnails"),
+        metavar="DIR",
+        help="Directory where extracted thumbnails are written.",
+    )
+    parser.add_argument(
+        "--thumbnail-size",
+        type=int,
+        default=1000,
+        metavar="PX",
+        help="Maximum side length (width or height) of each thumbnail in pixels.",
+    )
+    parser.add_argument(
+        "--workers",
+        "-j",
+        type=int,
+        default=4,
+        metavar="N",
+        help="Number of parallel worker threads.",
+    )
+    parser.add_argument(
+        "--format",
+        dest="fmt",
+        default="png",
+        metavar="FMT",
+        help="Output image format accepted by Pillow (e.g. png, jpeg).",
+    )
+    parser.add_argument(
+        "--overwrite",
+        action="store_true",
+        help="Overwrite existing output files. Without this flag, already-extracted slides are skipped.",
+    )
+    parser.add_argument(
+        "--aws-profile",
+        default=None,
+        metavar="PROFILE",
+        help="Boto3 AWS profile name for S3 access. Uses the default credential chain when omitted.",
+    )
+    args = parser.parse_args(argv)
+
+    from ._extract import extract_thumbnails
+
+    try:
+        results = extract_thumbnails(
+            args.glob,
+            output_dir=args.output_dir,
+            thumbnail_size=args.thumbnail_size,
+            workers=args.workers,
+            fmt=args.fmt,
+            overwrite=args.overwrite,
+            aws_profile=args.aws_profile,
+        )
+    except ValueError as exc:
+        sys.exit(str(exc))
+
+    ok = [r for r in results if r.error is None]
+    skipped = [r for r in results if r.error and "already exists" in r.error]
+    failed = [r for r in results if r.error and "already exists" not in r.error]
+
+    for r in ok:
+        print(f"  [ok]      {r.slide_path}  →  {r.output_path}")
+    for r in skipped:
+        print(f"  [skipped] {r.slide_path}  (output exists, use --overwrite)")
+    for r in failed:
+        print(f"  [failed]  {r.slide_path}  —  {r.error}", file=sys.stderr)
+
+    print(
+        f"\nDone: {len(ok)} extracted, {len(skipped)} skipped, {len(failed)} failed"
+        f"  →  {args.output_dir}"
+    )
+
+    if failed:
+        sys.exit(1)

rmcontrols/_cli_validate.py

@@ -0,0 +1,287 @@
+"""CLI entry points for interactive batch validation of control_split_x.
+
+Entry points
+------------
+``rmcontrols-validate-thumbnails``
+    Batch-validate control_split_x over a glob of thumbnail images.
+
+``rmcontrols-validate-slides``
+    Batch-validate control_split_x over a glob of whole-slide image files,
+    loading thumbnails via OpenSlide (local) or S3.
+
+Both commands write a JSON results file on exit.  The default output path is
+``./outputs/<command>.json`` (the directory is created automatically).
+Use ``--overwrite`` to replace an existing file; without it the command
+aborts with a warning.
+
+Examples
+--------
+::
+
+    rmcontrols-validate-thumbnails "assets/*.png" --side left
+
+    rmcontrols-validate-thumbnails "assets/*.png" --side left \\
+        --output results.json --overwrite
+
+    rmcontrols-validate-slides "slides/*.mrxs" --side left \\
+        --thumbnail-size 1000
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+_DEFAULT_OUTPUT_DIR = Path("outputs")
+
+
+# ---------------------------------------------------------------------------
+# Shared argument building
+# ---------------------------------------------------------------------------
+
+
+def _add_common_args(parser: argparse.ArgumentParser) -> None:
+    """Add detection-tuning and output arguments shared by both commands."""
+    parser.add_argument(
+        "--side",
+        choices=["left", "right"],
+        default="left",
+        help="Side where controls are placed",
+    )
+    parser.add_argument(
+        "--strip-width",
+        type=float,
+        default=0.40,
+        metavar="FRAC",
+        help="Strip width as fraction of image width (max 0.40)",
+    )
+    parser.add_argument(
+        "--threshold",
+        type=float,
+        default=0.05,
+        metavar="Z",
+        help="Dissimilarity Z-score threshold",
+    )
+    parser.add_argument(
+        "--min-area",
+        type=int,
+        default=500,
+        metavar="PX",
+        help="Minimum blob area in pixels",
+    )
+    parser.add_argument(
+        "--max-aspect-ratio",
+        type=float,
+        default=5.0,
+        metavar="R",
+        help="Reject blobs with bounding-box aspect ratio above this",
+    )
+    parser.add_argument(
+        "--split-margin",
+        type=int,
+        default=50,
+        metavar="PX",
+        help="Extra pixels added beyond the outermost control bbox edge",
+    )
+    parser.add_argument(
+        "--proximity",
+        type=int,
+        default=50,
+        metavar="PX",
+        help="Proximity rescue radius in pixels",
+    )
+    parser.add_argument(
+        "--full-debug",
+        action="store_true",
+        help="Show the full 5-panel debug grid instead of the simple split-x view",
+    )
+    parser.add_argument(
+        "--overwrite",
+        action="store_true",
+        help="Overwrite the output file if it already exists",
+    )
+
+
+def _detection_kwargs(args: argparse.Namespace) -> dict:
+    """Build **kwargs dict for detect_controls_debug from parsed args."""
+    return dict(
+        strip_width_frac=args.strip_width,
+        dissimilarity_threshold=args.threshold,
+        min_tissue_area_px=args.min_area,
+        max_aspect_ratio=args.max_aspect_ratio,
+        control_split_x_margin=args.split_margin,
+        control_proximity_px=args.proximity,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Output helpers
+# ---------------------------------------------------------------------------
+
+
+def _resolve_output(output: Path | None, default_name: str) -> Path:
+    """Return *output* if given, otherwise ``./outputs/<default_name>``."""
+    if output is not None:
+        return output
+    return _DEFAULT_OUTPUT_DIR / default_name
+
+
+def _guard_overwrite(output: Path, overwrite: bool) -> None:
+    """Abort with a warning when *output* exists and *overwrite* is False."""
+    if output.exists() and not overwrite:
+        sys.exit(f"Output file already exists: {output}\nUse --overwrite to replace it.")
+
+
+def _write_results(
+    results: dict[str, tuple[int | None, int]],
+    output: Path,
+) -> None:
+    """Serialise *results* as JSON and write to *output*."""
+    payload = [
+        {
+            "path": path,
+            "control_split_x": cx,
+            "thumbnail_width": w,
+            "pct": (f"{cx / w * 100:.1f}%" if cx is not None and w > 0 else "N/A"),
+        }
+        for path, (cx, w) in results.items()
+    ]
+    output.parent.mkdir(parents=True, exist_ok=True)
+    output.write_text(json.dumps(payload, indent=2))
+    print(f"Wrote {len(payload)} result(s) to {output}")
+
+
+# ---------------------------------------------------------------------------
+# validate-thumbnails
+# ---------------------------------------------------------------------------
+
+
+def main_validate_thumbnails(argv: list[str] | None = None) -> None:
+    """Entry point for ``rmcontrols-validate-thumbnails``."""
+    parser = argparse.ArgumentParser(
+        prog="rmcontrols-validate-thumbnails",
+        description=(
+            "Interactively validate control_split_x for a batch of thumbnail"
+            " images matched by a glob pattern."
+        ),
+        formatter_class=argparse.ArgumentDefaultsHelpFormatter,
+    )
+    parser.add_argument(
+        "glob",
+        help=(
+            "Glob pattern for thumbnail images, e.g. 'assets/*.png'."
+            " Quote the pattern to prevent shell expansion."
+        ),
+    )
+    parser.add_argument(
+        "--output",
+        "-o",
+        type=Path,
+        default=None,
+        metavar="PATH",
+        help=(
+            "Write results as JSON to this file. "
+            f"Default: {_DEFAULT_OUTPUT_DIR}/validate_thumbnails.json"
+        ),
+    )
+    _add_common_args(parser)
+    args = parser.parse_args(argv)
+
+    output = _resolve_output(args.output, "validate_thumbnails.json")
+    _guard_overwrite(output, args.overwrite)
+
+    paths = sorted(Path(".").glob(args.glob))
+    if not paths:
+        sys.exit(f"No files matched: {args.glob!r}")
+
+    print(f"Found {len(paths)} thumbnail(s) matching {args.glob!r}")
+
+    from ._validation import validate_control_split_x_batch
+
+    results = validate_control_split_x_batch(
+        paths,
+        side=args.side,
+        full_debug=args.full_debug,
+        **_detection_kwargs(args),
+    )
+    _write_results(results, output)
+
+
+# ---------------------------------------------------------------------------
+# validate-slides
+# ---------------------------------------------------------------------------
+
+
+def main_validate_slides(argv: list[str] | None = None) -> None:
+    """Entry point for ``rmcontrols-validate-slides``."""
+    parser = argparse.ArgumentParser(
+        prog="rmcontrols-validate-slides",
+        description=(
+            "Interactively validate control_split_x for a batch of whole-slide"
+            " images matched by a glob pattern. Accepts local paths or"
+            " s3:// URIs. Requires openslide-python."
+        ),
+        formatter_class=argparse.ArgumentDefaultsHelpFormatter,
+    )
+    parser.add_argument(
+        "glob",
+        help=(
+            "Glob pattern for local WSI files (e.g. 'slides/*.mrxs') or an"
+            " S3 URI / S3 glob pattern"
+            " (e.g. 's3://bucket/slides/*.mrxs')."
+            " Quote the pattern to prevent shell expansion."
+        ),
+    )
+    parser.add_argument(
+        "--thumbnail-size",
+        type=int,
+        default=1000,
+        metavar="PX",
+        help="Maximum dimension (width or height) of the extracted thumbnail",
+    )
+    parser.add_argument(
+        "--output",
+        "-o",
+        type=Path,
+        default=None,
+        metavar="PATH",
+        help=(
+            "Write results as JSON to this file. "
+            f"Default: {_DEFAULT_OUTPUT_DIR}/validate_slides.json"
+        ),
+    )
+    _add_common_args(parser)
+    args = parser.parse_args(argv)
+
+    output = _resolve_output(args.output, "validate_slides.json")
+    _guard_overwrite(output, args.overwrite)
+
+    glob_str = args.glob
+    if glob_str.startswith("s3://"):
+        if any(c in glob_str for c in ("*", "?", "[")):
+            from ._s3 import glob_s3
+
+            paths = glob_s3(glob_str)
+            if not paths:
+                sys.exit(f"No S3 objects matched: {glob_str!r}")
+        else:
+            paths = [glob_str]
+    else:
+        paths = sorted(str(p) for p in Path(".").glob(glob_str))
+        if not paths:
+            sys.exit(f"No files matched: {glob_str!r}")
+
+    print(f"Found {len(paths)} slide(s)")
+
+    from ._validation import validate_control_split_x_wsi
+
+    results = validate_control_split_x_wsi(
+        paths,
+        side=args.side,
+        thumbnail_size=args.thumbnail_size,
+        full_debug=args.full_debug,
+        **_detection_kwargs(args),
+    )
+    _write_results(results, output)