Add detection: skew, system anchors, ink extents, cuts, staff height

Systems anchor on the vertical bracket and expand over nearby ink, per
ADR 0006. Two corrections the corpus forced:

- Expansion measures distance from the bracket, never from the growing
  extent. A chaining expansion hops between the closely-stacked lines of
  a title block and walks the whole way up the page — on Engel p1 it
  swallowed the title into system 1 and the copyright footer into
  system 3.
- Reach is 1.5 staff heights, which takes in the lyrics below the last
  staff and the tempo mark and INTRO box above the first, while leaving
  the title block and footer out.

Verified against the corpus. Ketun joululaulu: 2 systems per page except
p7 (3) and p12 (1), staff 48px throughout, skew -2.7 to +1.2 per page,
and p2 system 1 spans 179-1071 where its bracket is 177-994 — the
difference being the bottom voice's lyric line. Engel: 2-3 systems per
page, staff 70-72px. Elaman nalka: 3 systems per page, 0 skew, staff
118px at 600 DPI.

The overlay dump is what made both bugs visible, and stays as the tool
for diagnosing a page that comes out wrong.

Closes #4, #5, #6, #7, #8, #9

noteman_slicer/cli.py

@@ -5,7 +5,12 @@ from __future__ import annotations
 import argparse
 import sys
 
-from . import __version__
+import numpy as np
+
+from pathlib import Path
+
+from . import __version__, overlay
+from .detect import detect_page
 from .pdf import SourceType, open_source, page_raster
 
 
@@ -20,6 +25,31 @@ def _info(args: argparse.Namespace) -> int:
     return 0
 
 
+def _detect(args: argparse.Namespace) -> int:
+    source = open_source(args.pdf, SourceType(args.type) if args.type else None)
+    out = Path(args.out)
+    out.mkdir(parents=True, exist_ok=True)
+    pages = range(len(source)) if args.page is None else [args.page - 1]
+
+    for i in pages:
+        gray = page_raster(source, i)
+        detection = detect_page(gray)
+        staves = [s.staff_height for s in detection.systems if s.staff_height]
+        note = f", staff {np.median(staves):.0f}px" if staves else ""
+        print(
+            f"p{i + 1:<3} skew {detection.skew:+.2f}°  "
+            f"{len(detection.systems)} systems{note}"
+            f"{'  (no bracket)' if detection.bracketless else ''}"
+        )
+        for n, system in enumerate(detection.systems, 1):
+            print(f"      sys{n}: {system.top}–{system.bottom}  h={system.height}")
+        overlay.write(gray, detection, out / f"{source.path.stem}-p{i + 1:02}.png")
+
+    print(f"overlays written to {out}/")
+    source.close()
+    return 0
+
+
 def main(argv: list[str] | None = None) -> int:
     parser = argparse.ArgumentParser(
         prog="noteman-slicer",
@@ -37,6 +67,13 @@ def main(argv: list[str] | None = None) -> int:
     )
     info.set_defaults(func=_info)
 
+    det = sub.add_parser("detect", help="run detection and write debug overlays")
+    det.add_argument("pdf")
+    det.add_argument("--out", default="overlays", help="output directory")
+    det.add_argument("--page", type=int, help="single 1-based page instead of all")
+    det.add_argument("--type", choices=[t.value for t in SourceType])
+    det.set_defaults(func=_detect)
+
     args = parser.parse_args(argv)
     return args.func(args)