Handoff · AI3D-382 — open the PR, then file the follow-ups

## Summary

Uses the new per-point `number_of_returns` on the no-scan-angle-filter dataset to
(1) fix tree recall — the old 10 m candidate slab and the v6 hedge gate were tuned on
scan-angle-filtered clouds with the tree tops cut off — and (2) separate foliage from
signs, guardrails and walls.

Nine detection passes, each ≤ 3 segments + visual check, discarding anything that did
not help. Final gate on **six validation segments never used for tuning**
(003/022/023/087/093/094), base config vs shipped config:

| metric | base | shipped | delta |
|---|---|---|---|
| canopy recall > 10 m | 0.018 | **0.769** | +0.752 (6/6 segments) |
| canopy recall 4–10 m | 0.750 | **0.903** | +0.153 |
| foliage-cell recall (segment-wide) | 0.494 | **0.860** | +0.366 |
| hard-contamination cells | 111 | **26** | points −75 % |
| truth-spot recall | 1.000 | **1.000** | both `not_tree` spots bit-identical |
| signs / delineators | 4 / 88 | **5 / 88** | +1 real sign, 0 lost |
| tree detections | 331 | 322 | −9, all rendered: road / mast / barrier, 0 vegetation |
| worst-segment runtime | 308 s | **447 s (7.4 min)** | +45 %, budget is 20 min |

085 human ground truth (ReCap annotations, 1.87 M points, 100 % matched @ 5 cm):
precision 0.489 → **0.543**, veg-tolerant precision 0.741 → **0.853**, recall 0.755
**unchanged** — every precision gain was bought with zero true-tree loss.

**Old-data parity with the packaged defaults is identical**: `clusters.csv`,
`tree_clusters.csv` and `point_masks.npz` match row-for-row and bit-for-bit against the
pre-change reference; the only differences are append-only columns and one crown-circle
float inside the documented P2 overlay tolerance. Every new knob defaults OFF.

## What this adds (all default-off knobs)

| knob | effect |
|---|---|
| `tree_detection.canopy_extension_*` (0.20 / 0.02) | paints the canopy above the 10 m slab from per-cell multi/triple-return fractions — the whole recall win |
| `returns_stripper.*` (tau 0.30, r 0.75, `reject_promoted_poles`) | drops foliage returns from sign candidates before the shape features; guards: min height 1.5 m, min 20 dropped, keep-only sparse fallback, min remaining 0.5, max surviving mrf 0.25, neighbour rules on unstripped geometry, promoted-pole guard |
| `sign_post.min_points_per_m = 100` | sparse-sign guard, kills airborne ghost signs (reason `sparse_sign`) |
| `tree_detection.hard_blob_unpaint_enabled` + `reject_instance` + survivor test + `cell_hysteresis 0.5` + `low_band_min_elev_m 0.3` with canopy-column guard | removes hard flat structure (billboards, lane markings, moving vehicles, road slivers) from tree paint, and drops whole instances that are mostly structure |
| `tree_detection.guardrail_mask_unpaint_enabled` | point-level unpaint of tree paint claimed by the seg3d guardrail masks; reaches rails inside mega-instances that no per-cluster rule can touch |
| perf: lazy crown-overlay fits, voxel-weighted lobe DBSCAN, convex-hull MEC prefilter | `crown_circles()` was 86 % of runtime; segment 002 1 355 s → 198 s (6.8×), decisions and masks bit-identical |
| `tcs_ground.*` per-segment ground | implemented, reviewed, tested — **shipped `per_segment = false`**; the code path stays for the tablecloth work |

## What was tried and removed

- hedge-gate returns veto — fired on nothing corpus-wide; tree/hedge AUC is 0.70. **Code removed.**
- returns stripper on the rail half-post path — inert, emitted half-posts byte-identical. **Code removed.**
- hard-blob mrf hysteresis 0.02 — cut rectangles out of a live shrub bank, never fired on its target. **Default 0.0.**
- per-segment TCS ground (naive / supported-seeding / ELM variants) — none reached per-record parity. **`per_segment = false`.**
- DEM (Digital Elevation Model, the per-cell ground surface) percentile / cell-size / noise-trim changes, lower hard-cell point floor, elongation gate — each measured, each loses more true tree than it gains, or captures almost nothing.

## Evidence

Final summary: https://miro-plans-battlebox.pages.dev/pages/ai3d-382-summary-20260907
Per-pass reports: /pages/ai3d-382-pass2-3-report-20260906 · pass4 · pass5 · pass6 · pass7 (all -20260906)
· pass8 · pass9 (-20260907) · DEM-bias explainer /pages/dem-bias-explainer-20260906

## Config

Recommended new-data config: `configs/a1nr_returns_recommended.json` (+ README section).
Requires `rail_halfpost.models_dir` pointing at a seg3d guardrails output root for the
guardrail-mask unpaint; without it the hook is a no-op.

## Tests

1 811 tests green (`uv run pytest -q`), `uv tool run ruff check src tests scripts` clean.

## Known untested on the real corpus

These landed as review fixes and are byte-neutral on every segment run so far, i.e. no
run exercised their branch. They are covered by unit tests only:

- canopy provenance check — extend canopies only for tree-path trees (`ae988ba`)
- hard-blob reject **survivor test** anchored at `min_elev` (`c51bca6`, docs `7bd8792`)
- returns-stripper **pole guard on `sign_post`** clusters (docs `2483578`)
- **`marker_mask` keying** of the marker return-column skip (`740854e`)
- hard-blob **hysteresis cap fallback** to strict cells (`18c9d73`, relaxation `b3dcc24`)

## Open items (tickets filed separately)

1. product definition: do attached shrubs/grass under a tree count as “tree”? (67 % of residual FPs)
2. mega-instance splitting — seg3d
3. pole-vs-trunk discriminator (lamp/camera masts, gantry columns painted tree)
4. tree vs hedge needs labels (returns AUC 0.70)
5. `return_number` export — available in the LAS on N:, not needed so far
6. per-segment TCS ground — handed to tablecloth
7. seg3d fuse: add `tree` to `PAINT_FIRST_CLASSES` in `3dsegmentation/masks.py`