AI3D-371 · ReCap-annotated segment → training data

One-off, PowerShell (N: is stream-only and invisible to WSL). Land it in the tier-0 inbox, mirroring the lane layout normalize_sources.py expects:

$src = 'N:\02_Modelling\05_Rink\02_AI 3D modeling\03_Working folder\260803_recap_annotation_Abschnitt_1\pre_annotation\260812_full_sweep'
$dst = '\\wsl.localhost\Ubuntu\home\miro\.t3\worktrees\3dai.iolabs.pointcloud.mlsegmentation\t3code-0a2985e1\data\00_external\a1_recap_v1\raw_drop'
robocopy "$src\branch_000\segment_085\reCap export_classfied_v2" "$dst\labels\segment_085\recap_export_v2" *.e57 /R:3 /W:5
robocopy "$src\branch_000\segment_085" "$dst\geometry\segment_085" segment_085_seg3d.las /R:3 /W:5
robocopy "$src" "$dst\provenance" README.md las_validation.json /R:3 /W:5

• Script it as scripts/dev/fetch_recap_segment.ps1 -Branch 000 -Segment 085 -ExportName "reCap export_classfied_v2" so segments 083/014/050/087 follow with one line. Verify sizes + a SHA-256 list into provenance/fetch_manifest.json.
• raw_drop/ is never DVC-tracked; no commit of data.
• Also drop desktop.ini; the importer must ignore non-point files anyway.

configs/contracts/recap_export_map_v1.yaml + src/contracts/recap_export_map.py (load_recap_export_map(path) → RecapExportMap, frozen dataclass, sha256).

schema_version: 1
name: recap_export_map_v1
filename_pattern: '^(?P<code>\d{1,3})\s+(?P<name>.+)$'   # "66 guardrail"
entries:
  2:   {recap_name: Terén,            seg3d_code: 71, note: ASPRS ground}
  3:   {recap_name: Nízká vegetace,   seg3d_code: 71}
  4:   {recap_name: Střední vegetace, seg3d_code: 5}
  5:   {recap_name: Tree,             seg3d_code: 5}
  10:  {recap_name: Rezervováno,      seg3d_code: 1}
  11:  {recap_name: Asphalt,          seg3d_code: 2}
  64:  {recap_name: solid_line,       seg3d_code: 64}
  65:  {recap_name: dashed_line,      seg3d_code: 65}
  66:  {recap_name: guardrail,        seg3d_code: 66}
  70:  {recap_name: delineator,       seg3d_code: 70}
  100: {recap_name: bordel,           seg3d_code: 1}
  101: {recap_name: car noise,        seg3d_code: 1}

Red: tests/test_recap_export_map.py — loads the shipped file; every seg3d_code ∈ BY_CODE; unknown top-level/entry key → RecapExportMapError; duplicate code → error; resolve("66 guardrail.e57") → 66; resolve("desktop.ini") → None-and-ignored vs resolve("foo.e57") → error naming the file; name mismatch vs recap_name → error (guards a re-export where the annotator renumbered, e.g. v1's 72 Car noise).

Green: minimal loader. Refactor: share the strict-YAML helpers already used by ontology.py.

src/dataset/e57.py: read_e57_world_xyz(path) → NDArray[float64] (N,3). Applies each scan's pose (rotation quaternion + translation) via pye57.E57.read_scan(i, transform=True, ignore_missing_fields=True), concatenates scans, checks the returned count against the header recordCount, raises E57ReadError naming the file if pye57 is missing or the file has no cartesian fields.

Red: tests/test_e57.py writes a 5-point E57 with pye57 (write_scan_raw with an explicit translation) → reader returns translated float64 coordinates within 1e-4 m; empty scan list → error; missing file → error.

Green/Refactor: implement; keep it a single-purpose module (~60 lines). Add pye57>=0.4.19,<0.5 to [project.dependencies], uv lock.

src/dataset/recap_export.py:

• load_las_segment(path) → LasSegment — reuses iter_las_chunks (coord f64, intensity u16, color u16, scan_angle i8, las_classification u8) into preallocated arrays; records point count + sha256.
• join_exports(segment_coord, exports: Sequence[ResolvedExport], *, tolerance_m, max_unmatched_fraction) → RecapJoinResult — per file: surface_keys + match_keys, then cKDTree on the LAS coords for misses within tolerance_m; assigns seg3d_code; tracks n_exact / n_nearest / n_unmatched; conflicts (same LAS row, different code) → RecapExportError with file pair + count; rows with no hit → code 1; guards on exported-unmatched fraction and on unlabeled LAS fraction.
• RecapJoinResult: classification u8, matched bool, files: tuple[FileReport], changes {old→new: n} against the LAS pre-annotation, counts_before/after, unmatched_rate — same field names as upstream ImportReport so the existing report gate reads it unchanged.

Red: tests/test_recap_export.py with a synthetic 200-point LAS (PDRF 7, RGB, intensity, classes) written by laspy into tmp_path, exports as in-memory arrays (no E57 dependency here): exact hits; a 0.3 mm-perturbed export point resolves through NN; a 2 cm-perturbed one stays unmatched; conflict → error; unmatched-fraction gate trips at 0.02; unlabeled-LAS gate; deterministic output across two runs.

Green/Refactor: vectorise; no Python loops over points; keep memory ≤ 3× the LAS arrays.

• write_recap_artifacts(out_dir, segment_id, segment, join, *, class_map, provenance) → dict[str, Path]: NPZ (compressed; keys as decided), _report.json, _stats.json (las_geoshift: null, instances: [], source: {las_path, las_sha256, export_dir, export_sha256s, class_map_sha256, tool_version, git_commit}), review LAZ (LAS copy with the new classification, RGB/intensity untouched). Atomic writes; refuse to overwrite unless --force.
• scripts/import_recap_export.py --las … --exports … --class-map configs/contracts/recap_export_map_v1.yaml --out-dir … --segment-id 085 [--tolerance 0.01] [--max-unmatched 0.02] [--force]; exit 2 on any domain error, prints the manifest path; Google-style docstrings; fully typed.

Red: CLI test on the synthetic LAS + a pye57-written E57 export dir: artifacts exist, NPZ round-trips through select_preannotation + load_preannotation + labels_for_training_geometry (i.e. the existing ingest path accepts it, incl. the report gate), intensity/RGB equal the LAS values row-for-row, class_codes/class_names equal legend(), second run without --force refuses.

uv run python scripts/import_recap_export.py \
  --las data/00_external/a1_recap_v1/raw_drop/geometry/segment_085/segment_085_seg3d.las \
  --exports data/00_external/a1_recap_v1/raw_drop/labels/segment_085/recap_export_v2 \
  --class-map configs/contracts/recap_export_map_v1.yaml \
  --out-dir data/00_external/a1_recap_v1/raw_drop/labels/segment_085 --segment-id 085

Acceptance: unmatched exported ≤ 0.5 % (expect ≈ 0 exact misses + a few % NN), unlabeled LAS rows ≈ 67, no conflicts, per-class counts equal the E57 record counts above. Report the old→new correction table (this is the first quantitative view of how much the annotator changed vs the seg3d pre-annotation — worth a line in the ticket). Eyeball the review LAZ in CloudCompare if any class count looks off.

1. uv run python scripts/normalize_sources.py --dataset a1_recap_v1 → LAS→LAZ into geometry/, labels copied, dvc add both lanes (no push).
2. configs/contracts/corridor_splits_a1_v1.yaml: corridor a1_b000_segment_085, tier train, EPSG 25832, geoshift_m: null, scanner/campaign from the sweep README, placeholder: false, class counts from the report.
3. configs/dev/a1_recap_segment_085.yaml: copy of the A1 Pointcept smoke config with data.root/canonical_root/processed_root on a1_recap_v1, globs labels/segment_*/…, source_geometry_glob: "geometry/*/segment_*_seg3d.laz", features.names: [xyz, intensity, rgb], normalization_manifest: …/normalization_xyz_intensity_rgb.json. Config test asserts it loads.
4. Smoke: ingest_preannotations.py --config … --split train → prepare_dataset.py --config … --split train --emit canonical --emit pointcept. Check the canonical manifest: label mode exact_1mm_join, unmatched fraction ≈ 67/1.87 M, feature columns x,y,z,intensity,red,green,blue, tile count > 0.
5. Add the two DVC stages for the new dataset (or parametrise the existing ones) only if step 4 passes; keep cache: false on emissions.
6. Docs: docs/data/recap_import.md (workflow, class map rationale, fetch script, limitations: no instances, one segment, no validation tier yet); README cross-link; register the new contract in the spec's config table.

Out of scope here: actually launching a training run (needs a validation corridor — segments 083/014/050/087 are annotated on N: too and become the follow-up).

• uv run pytest, uv run ruff check ., git diff --check green; CPU suite still Torch-free.
• Opus 5 + Sol review in parallel (correctness of join/precision, fail-closed config parsing, style guide), then one Fable pass on code quality; fix, re-run.
• Commits under AI3D-371: one per phase (contract, e57, join, cli, dataset wiring, docs) on t3code/0a2985e1. No push, no data commits.
• File the upstream follow-up: recap_import._read_e57 ignores pose; class_from_filename rejects ReCap's own naming.