feat(inspection): add RLE mask encode/decode module

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

inspection/masks.py

@@ -0,0 +1,103 @@
+"""RLE (Run-Length Encoding) for binary segmentation masks.
+
+Uses a pure-Python COCO-compatible RLE implementation so we do not
+require pycocotools (which has C build dependencies that complicate
+Docker builds). The encoding is column-major (Fortran order) to
+match COCO convention.
+"""
+
+import logging
+from typing import Dict, List
+
+import numpy as np
+
+logger = logging.getLogger(__name__)
+
+
+def rle_encode(mask: np.ndarray) -> Dict:
+    """Encode a binary mask as COCO-format RLE.
+
+    Args:
+        mask: HxW boolean or uint8 numpy array.
+
+    Returns:
+        Dict with 'counts' (list of run lengths) and 'size' [H, W].
+    """
+    h, w = mask.shape[:2]
+    # Flatten in column-major (Fortran) order per COCO convention
+    flat = mask.astype(np.uint8).ravel(order="F")
+
+    # Compute run lengths
+    counts: List[int] = []
+    prev = 0
+    run = 0
+    for val in flat:
+        if val == prev:
+            run += 1
+        else:
+            counts.append(run)
+            run = 1
+            prev = val
+    counts.append(run)
+
+    # Ensure counts starts with a run of 0s (COCO convention)
+    if len(counts) > 0 and flat[0] == 1:
+        counts.insert(0, 0)
+
+    return {"counts": counts, "size": [h, w]}
+
+
+def rle_decode(rle: Dict) -> np.ndarray:
+    """Decode a COCO-format RLE to a binary mask.
+
+    Args:
+        rle: Dict with 'counts' (list of run lengths) and 'size' [H, W].
+
+    Returns:
+        HxW boolean numpy array.
+    """
+    h, w = rle["size"]
+    counts = rle["counts"]
+
+    flat = np.zeros(h * w, dtype=np.uint8)
+    pos = 0
+    val = 0  # Starts with 0s (background)
+    for run in counts:
+        flat[pos : pos + run] = val
+        pos += run
+        val = 1 - val
+
+    mask = flat.reshape((h, w), order="F").astype(bool)
+    return mask
+
+
+def mask_area(rle: Dict) -> int:
+    """Count the number of True pixels from an RLE-encoded mask.
+
+    Args:
+        rle: COCO-format RLE dict.
+
+    Returns:
+        Number of foreground pixels.
+    """
+    counts = rle["counts"]
+    # Odd-indexed runs (0-based) are foreground (value=1)
+    return sum(counts[i] for i in range(1, len(counts), 2))
+
+
+def mask_to_png_bytes(mask: np.ndarray) -> bytes:
+    """Encode a binary mask as a single-channel PNG (white on black).
+
+    Args:
+        mask: HxW boolean numpy array.
+
+    Returns:
+        PNG bytes.
+    """
+    import cv2
+
+    img = (mask.astype(np.uint8)) * 255
+    success, buffer = cv2.imencode(".png", img)
+    if not success:
+        raise RuntimeError("Failed to encode mask as PNG")
+    return buffer.tobytes()

tests/test_inspection_masks.py

@@ -0,0 +1,79 @@
+import numpy as np
+import pytest
+
+
+def test_rle_encode_returns_dict():
+    """RLE encode should return a dict with 'counts' and 'size' keys."""
+    from inspection.masks import rle_encode
+
+    mask = np.zeros((100, 200), dtype=bool)
+    mask[20:40, 50:100] = True
+    rle = rle_encode(mask)
+
+    assert isinstance(rle, dict)
+    assert "counts" in rle
+    assert "size" in rle
+    assert rle["size"] == [100, 200]
+
+
+def test_rle_roundtrip():
+    """Encoding then decoding should reproduce the original mask."""
+    from inspection.masks import rle_encode, rle_decode
+
+    mask = np.zeros((64, 64), dtype=bool)
+    mask[10:30, 20:50] = True
+
+    rle = rle_encode(mask)
+    decoded = rle_decode(rle)
+
+    assert decoded.shape == mask.shape
+    assert decoded.dtype == bool
+    assert np.array_equal(mask, decoded)
+
+
+def test_rle_empty_mask():
+    """An all-False mask should encode and decode correctly."""
+    from inspection.masks import rle_encode, rle_decode
+
+    mask = np.zeros((50, 50), dtype=bool)
+    rle = rle_encode(mask)
+    decoded = rle_decode(rle)
+    assert not decoded.any()
+
+
+def test_rle_full_mask():
+    """An all-True mask should encode and decode correctly."""
+    from inspection.masks import rle_encode, rle_decode
+
+    mask = np.ones((50, 50), dtype=bool)
+    rle = rle_encode(mask)
+    decoded = rle_decode(rle)
+    assert decoded.all()
+
+
+def test_rle_encode_compact():
+    """RLE of a simple mask should be much smaller than the raw mask."""
+    from inspection.masks import rle_encode
+    import json
+
+    mask = np.zeros((720, 1280), dtype=bool)
+    mask[100:200, 300:500] = True  # Small rectangle
+
+    rle = rle_encode(mask)
+    rle_size = len(json.dumps(rle))
+    raw_size = mask.nbytes
+
+    assert rle_size < raw_size / 100  # At least 100x compression
+
+
+def test_mask_area():
+    """mask_area should count the number of True pixels."""
+    from inspection.masks import mask_area
+
+    rle = {"counts": None, "size": [100, 100]}  # placeholder
+    mask = np.zeros((100, 100), dtype=bool)
+    mask[10:20, 10:20] = True  # 100 pixels
+
+    from inspection.masks import rle_encode
+    rle = rle_encode(mask)
+    assert mask_area(rle) == 100