[WIP] Group OCR line detections by mutual gap, not absolute pixel buckets

[PawelPeczek-Roboflow]

🚧 Work in progress — not ready for review

Draft PR from a batch addressing findings from an in-depth engineering review. Fixes review finding 26 (Medium, Correctness).

The bug

group_detections_by_line in stitch_ocr_detections/v1.py:315 (and the byte-identical v2.py:400) assigns each OCR detection to a line via np.round(y1 / tolerance) * tolerance, snapping the top-y coordinate to the nearest absolute multiple of tolerance. Two boxes on the same physical text line whose y1 values straddle a bucket boundary land on different lines even though they are far closer than tolerance — directly contradicting the documented contract "Detections within this tolerance distance are grouped into the same line."

Root cause

Grouping was done by fixed pixel-grid bucket membership, not by mutual distance. With tolerance=10, y1=14 -> round(1.4)*10 = 10 and y1=16 -> round(1.6)*10 = 20, so two boxes 2px apart are placed on separate lines and the output becomes A\nB instead of AB.

Fix

Rewrote group_detections_by_line in both v1.py and v2.py to group by mutual gap (the same greedy approach v2.adaptive_word_grouping already uses for lines): sort detections by the primary coordinate, then start a new line only when the gap to the previous detection exceeds tolerance. Each line is keyed by its first detection's primary coordinate, so the caller's sorted(boxes_by_line.keys(), reverse=...) top-to-bottom / bottom-to-top ordering is preserved unchanged. Both blocks' tolerance stitching mode are affected (v2's default stitching_algorithm="tolerance" routes to the same function).

Verification

Standalone before/after on the review's exact repro (Box A xyxy=[0,14,10,30] 'A', Box B xyxy=[20,16,30,32] 'B', left_to_right, tolerance=10):

• straddle-boundary y1=14/16: OLD 'A\nB' -> NEW 'AB' (fixed)
• genuine two lines y1=14/40: NEW 'A\nB' (still splits correctly)
• same-bucket y1=11/13: OLD 'AB' == NEW 'AB' (unchanged)
• within-line ordering (A right of B, left_to_right): NEW 'BA' (correct)

Scope

Focused change; one of a coordinated batch (one PR per finding).

---

🤖 Generated with Claude Code