Update tests/test_segmentation.py

tests/test_segmentation.py

@@ -12,7 +12,11 @@ import numpy as np
 
 sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
 
-from segmentation import segment_sheet
+from segmentation import (
+    detect_separator_grid,
+    detect_tile_grid,
+    segment_sheet,
+)
 
 
 def test_single_sprite():
@@ -147,6 +151,175 @@ def test_low_confidence_flagged_for_oversized_region():
     assert detected[0].confidence < 100
 
 
+# ---------------------------------------------------------------------------
+# Grid-corrected segmentation: animation frames and edge-to-edge tilesets
+# ---------------------------------------------------------------------------
+
+def _particle_frame(mask, x0, y0, w, h, rng):
+    """A frame drawn as scattered 1px particles, like an explosion's debris."""
+    for _ in range(24):
+        mask[y0 + rng.integers(0, h), x0 + rng.integers(0, w)] = True
+    # anchor the frame's extent so its bbox is predictable
+    mask[y0, x0] = True
+    mask[y0 + h - 1, x0 + w - 1] = True
+
+
+def test_particle_animation_frames_are_not_lost_as_noise():
+    """
+    An animation strip whose frames are clouds of loose 1-2px particles.
+    Every one of those particles is individually below MIN_SPRITE_SIZE_PX,
+    so the gap pipeline drops them and whole frames vanish. The frame
+    gutters must be used instead, giving exactly one sprite per frame with
+    no ink thrown away.
+    """
+    rng = np.random.default_rng(11)
+    mask = np.zeros((40, 200), dtype=bool)
+    for i in range(5):
+        _particle_frame(mask, 5 + i * 40, 5, 30, 30, rng)
+
+    detected, _, _ = segment_sheet(mask)
+    assert len(detected) == 5
+
+    covered = np.zeros_like(mask)
+    for d in detected:
+        covered[d.bbox.y:d.bbox.y2, d.bbox.x:d.bbox.x2] = True
+    assert (mask & ~covered).sum() == 0, "particles were dropped from the result"
+
+
+def test_separator_grid_finds_phase_shifted_pitch():
+    """
+    A lattice whose gutters sit at 8, 19, 30, ... -- period 11, phase 8.
+    Searching phase 0 only would report a much coarser (wrong) period.
+    """
+    mask = np.zeros((110, 110), dtype=bool)
+    for row in range(10):
+        for col in range(10):
+            mask[row * 11:row * 11 + 8, col * 11:col * 11 + 8] = True
+    layout = detect_separator_grid(mask)
+    assert layout is not None
+    assert layout.cell_width == 11 and layout.cell_height == 11
+    assert layout.occupied_cells == 100
+
+
+def test_frame_with_internal_gap_is_not_halved_by_the_grid():
+    """
+    Frames separated by a wide gutter, each frame containing a 1px internal
+    gap. That gap offers a cut line which is technically legal (the row
+    really is empty) but slices every frame in half. The merge-only
+    regrouping must keep each frame whole regardless.
+    """
+    mask = np.zeros((30, 120), dtype=bool)
+    for i in range(4):
+        x = i * 30
+        mask[5:15, x:x + 10] = True       # upper half of the frame
+        mask[16:25, x:x + 10] = True      # lower half, 1px gap at row 15
+    detected, _, _ = segment_sheet(mask)
+    assert len(detected) == 4
+    for d in detected:
+        assert d.bbox.y == 5 and d.bbox.y2 == 25
+
+
+def test_shattered_frames_regroup_but_never_split_a_merged_sprite():
+    """
+    The regrouping is merge-only: a sprite the gap stage already joined
+    across a background gap keeps its identity even when a grid line falls
+    between its parts.
+    """
+    mask = np.zeros((30, 30), dtype=bool)
+    mask[5:8, 5:8] = True       # leaf
+    mask[10:12, 6:9] = True     # stem, 2px gap -- one sprite
+    detected, _, _ = segment_sheet(mask)
+    assert len(detected) == 1
+    assert detected[0].bbox.y == 5
+    assert detected[0].bbox.y2 == 12
+
+
+def _tileset_rgba(tile: int, tiles_across: int, rng):
+    """Edge-to-edge tileset: no background anywhere, tiles differ sharply."""
+    size = tile * tiles_across
+    rgba = np.zeros((size, size, 4), dtype=np.uint8)
+    rgba[:, :, 3] = 255
+    for r in range(tiles_across):
+        for c in range(tiles_across):
+            colour = rng.integers(0, 256, size=3, dtype=np.uint16).astype(np.uint8)
+            rgba[r * tile:(r + 1) * tile, c * tile:(c + 1) * tile, :3] = colour
+    return rgba
+
+
+def test_tile_grid_recovers_pitch_of_edge_to_edge_tileset():
+    """
+    A tileset drawn corner to corner has no background gutter at all, so
+    the gap pipeline sees one sheet-sized blob. The tile pitch has to come
+    from the sheet's own edge periodicity -- and must be the FUNDAMENTAL
+    pitch, not a multiple of it (16, never 32 or 80).
+    """
+    rng = np.random.default_rng(5)
+    rgba = _tileset_rgba(16, 10, rng)
+    mask = np.ones(rgba.shape[:2], dtype=bool)
+
+    layout = detect_tile_grid(rgba, mask)
+    assert layout is not None
+    assert layout.cell_width == 16 and layout.cell_height == 16
+
+    detected, _, _ = segment_sheet(mask, rgba=rgba)
+    assert len(detected) == 100
+
+
+def test_tile_grid_needs_pixels_and_is_skipped_without_them():
+    """Mask-only callers keep the original behaviour, never a tile grid."""
+    rng = np.random.default_rng(5)
+    rgba = _tileset_rgba(16, 10, rng)
+    mask = np.ones(rgba.shape[:2], dtype=bool)
+    assert detect_tile_grid(None, mask) is None
+    detected, _, _ = segment_sheet(mask)
+    assert len(detected) == 1
+
+
+def test_animation_sheet_does_not_get_a_tile_grid():
+    """
+    A sheet with a strong pitch on ONE axis only (a horizontal strip) is
+    not a tileset; requiring both axes to agree is what keeps it out.
+    """
+    rng = np.random.default_rng(9)
+    rgba = np.zeros((64, 512, 4), dtype=np.uint8)
+    for i in range(8):
+        colour = rng.integers(0, 256, size=3, dtype=np.uint16).astype(np.uint8)
+        rgba[10:54, i * 64 + 8:i * 64 + 56, :3] = colour
+        rgba[10:54, i * 64 + 8:i * 64 + 56, 3] = 255
+    mask = rgba[:, :, 3] > 0
+    assert detect_tile_grid(rgba, mask) is None
+    detected, _, _ = segment_sheet(mask, rgba=rgba)
+    assert len(detected) == 8
+
+
+def test_two_close_sprites_are_not_fused_by_a_grid():
+    """
+    The grid paths must never merge a couple of independent sprites that
+    the gap pipeline correctly kept apart.
+    """
+    mask = np.zeros((20, 40), dtype=bool)
+    mask[5:15, 5:15] = True
+    mask[5:15, 18:28] = True
+    rgba = np.zeros((20, 40, 4), dtype=np.uint8)
+    rgba[mask] = (200, 120, 60, 255)
+    detected, _, _ = segment_sheet(mask, rgba=rgba)
+    assert len(detected) == 2
+
+
+def test_grid_backed_sprites_are_not_flagged_low_confidence_for_being_sparse():
+    """
+    A validated grid cut is more trustworthy than the gap heuristic, so a
+    frame that is legitimately a sparse cloud of particles must not be
+    pushed below the manual-review threshold just for being sparse.
+    """
+    rng = np.random.default_rng(11)
+    mask = np.zeros((40, 200), dtype=bool)
+    for i in range(5):
+        _particle_frame(mask, 5 + i * 40, 5, 30, 30, rng)
+    detected, _, _ = segment_sheet(mask)
+    assert detected and all(d.confidence >= 70 for d in detected)
+
+
 if __name__ == "__main__":
     # Minimal manual runner for environments without pytest installed.
     import traceback