AI3D-373 — split vegetation into low / medium / tree

Summary

Key decisions

How the RGB information is used

Each run3 record carries red/green/blue uint16 per point (A1: full 16-bit range). The fusion stage turns them into a single scale-free greenness value:

s   = R + G + B                      (s == 0 → no colour → not green)
ExG = (2·G − R − B) / s              (chromatic excess green, −2…+2 theoretically, ≈ −0.3…+0.6 in practice)
green = ExG ≥ green_exg_min  and  G > R  and  G > B  and  s ≥ green_min_brightness

• Why chromatic: dividing by the sum removes exposure/shadow; a leaf at noon and the same leaf in shade share the ExG. Also removes the 8-bit vs 16-bit storage difference.
• Why not "G is the max channel" alone: grey asphalt, concrete and bark have G ≈ R ≈ B with G marginally largest under some white balances; the margin (green_exg_min) is what rejects them. The phase-6 ExG study on A1 (docs/research/greenness-exg-phase6.md) gives the anchor numbers: crowns p50 +0.21 / p25 +0.14, man-made p75 +0.11, bark ≈ 0.
• Brightness floor: optional (green_min_brightness, default off). Very dark returns have noisy chroma; enable if shadow noise shows up in the QC rasters.
• Colour is necessary, not sufficient: green is only consulted for points nobody else claimed (unclassified / ground), never over asphalt, and it is combined with height above ground. A green sign back or a green-painted fence caught by the detector stays sign/guardrail; an undetected green fence becomes medium vegetation — accepted for pre-annotation.
• What colour cannot do: brown winter grass, dry weeds, mown stubble stay ground; conifers in deep shade may fall under the threshold (they are mostly detector trees anyway). The threshold is a knob and the first thing the QC loop tunes (sweep 0.06 / 0.10 / 0.14 on 085).

How low is separated from medium (and from tree)

1. Height above ground

From the points already classified ground or asphalt: 1 m grid, per-cell 10th-percentile z (robust to grass tops and stray low returns), empty cells filled from the nearest filled cell (cKDTree on cell centres), then bilinear sampling → h = z − dtm(x, y) for every candidate. Grass sits at h ≈ 0–0.3 m, hedges 0.5–2.5 m, crowns 3–15 m.

2. Column banding

Green candidates are binned into 0.5 m XY cells; each cell's band is decided by the 95th percentile of its candidate heights, and every candidate in the cell inherits it:

Consequences, deliberately accepted: grass directly under a crown the detector did not claim becomes medium_vegetation (canopy columns). Per-point banding stays available as vegetation_band_mode=point for comparison.

3. Tree vs hedge for detector clusters

The detector's tree clusters (≥ 2 m crown, RF ≥ threshold or conic/conifer rule) keep priority and are never re-banded by colour. Inside verticalsigns each accepted cluster is put through the hedge test that the instance splitter already runs out of band: grounded (p5 h < 2 m), low (p99 h ≤ 7.5 m), long (≥ 8 m), stemless (< 1 strong stem seed / 10 m), continuous, flat-topped (relief ≤ 1.5 m). A hedge-shaped cluster is emitted as medium_vegetation; everything else stays tree. seg3d maps both through SIGN_TYPE_MAP. Fallback knob in seg3d (default off): re-band a detector tree instance whose p95 height is below vegetation_tree_min_height_m to medium — a safety net while the detector change is not yet in the production pin.

4. Precedence

ground → asphalt → lines → detector masks [vegetation first, guardrail, sign, supports last]
       → guardrail JSON → sign JSON → vegetation per-point (unclassified/ground, not above asphalt; low/medium only)
       → vehicle sweep (unclassified inside corridor) → voxel pick (tier: veg = ground < asphalt < …)

Phases

Risks

Open questions

1. Where should the per-point colour + height rule live?

   default seg3d fusion (D1) — corridor, ground, precedence and RGB are all there; verticalsigns only decides tree vs hedge.

   alt verticalsigns stage emitting low/medium masks — needs a second streamed pass over run3 (candidates start at 0.3 m), a rasterised run7 band test for the carriageway, and loading the guardrails sidecar for precedence; iteration = detector + fuse rerun.

2. Median strip: allow vegetation between the two carriageways?

   default Yes — reject only columns with asphalt beneath (D6); median grass/hedges get their classes.

   alt Whole corridor polygon rejected; median residual stays vehicle as today.

3. Height bands?

   default low < 0.5 m, medium 0.5–2 m, tree > 2 m (ASPRS-style).

   alt low < 0.3 m, medium 0.3–1.5 m — if the QC shows tall grass/weeds landing in medium.

4. Green points the tablecloth kept as ground?

   default Become low_vegetation (D5); brown/grey ground stays ground.

   alt Only the unclassified residual is banded; grass stays ground.

5. Tall green residual (> 2 m, not a detector tree)? answered 27 Aug

   default medium_vegetation — only the detector defines tree; hedges and trees are exclusive.

   alt vegetation_tall_class=tree or unclassified per run.

6. Hedge definition: promote the instance-splitter verdict as is (≥ 8 m long, ≤ 7.5 m tall, flat top)?

   default Yes, plus the seg3d height fallback off; tune only after seeing 085/002/003.

   alt Height-only: any detector tree with p95 height < 3 m is medium; skip the verticalsigns change for now (no signs3 rerun needed).

7. Where does the seg3d branch merge?

   default Into feat/AI3D-369-production (production waits on this), then that branch to main as planned.

   alt Straight to main via its own PR.