Handoff: produce Abschnitt 1 Step 3 NPZ data with return counts on Azure

Summary

Current state

Published packages (Nexus, verified 2026-09-03)

Orchestrator (/home/ai/dev/3dai.iolabs.orchestrator)

• origin/master = 97df5d7 "AI3D-379 Repin AML envs to the pydantic-config package releases; bump env versions". It pins iolabs-point-cloud-segmentation-trajectory==0.7.4 in environments/s3_segment_mapper/conda.yml with environment.yml version 19, and components/s3_segment_mapper.yml references azureml:s3_segment_mapper:19. Step 6 is mask-clustering 0.3.2 / env v7, Step 5 line-bitmap-inference 0.2.1 / env v2.
• not registered In AML only s3_segment_mapper versions up to 17 exist (17 pins trajectory 0.7.2, which has no return counts). s6_mask_clustering max registered is 5, s5_line_bitmap_inference max is 1. Versions 18 and 19 of s3 were never created.
• The main checkout is on branch feat/s3-angle-limit (fully merged into master) with uncommitted AI3D-318 edits (components/s3_segment_mapper.yml, scripts/s3_segment_mapper/s3_segment_mapper.py, untracked test and helper pipeline). Leave it alone; work from a detached worktree of origin/master.
• The Step 3 wrapper on master already writes the field itself for its chunked path (scripts/s3_segment_mapper/s3_segment_mapper.py, _chunk_number_of_returns, around line 1107) and the package does it for the non-chunked path. A LAS chunk without the field degrades to zeros; 0 means "unknown", never 1.
• Orchestrator tests: uv run python -m pytest -q --ignore=tests/test_s8_s9_worker_contract.py (135 passed on 2026-09-03). tests/test_env_pins.py guards that every component env reference matches its environment.yml version.

Abschnitt 1 runs on Azure

• Baseline full run lanefinder_abschnitt_1_pipeline_20260702070612. Its persisted outputs that the Step 3 helper reuses: step3_las_tasks under azureml/f63c89de-44ca-4420-ba83-f80c4f500a46/, prepared_step3_inputs under azureml/75bc5d64-a543-48ff-9608-301df7224534/, step3_geometry under azureml/eea78ab2-b8d2-40e4-9557-77263fd24659/, LAS cache lanefinder/acc-cache. Its Step 3 output (with angle filter, no return counts) is azureml/77f7ac77-a89a-446c-911c-37182f8caf4d/step3_output/ and is what abschnitt_1_from_step3.yaml and abschnitt_1_render_zrange.yaml currently point at.
• Newest Step 3 rerun: lanefinder_abschnitt_1_s3_no_angle_filter_20260901081739 (Completed 2026-09-01, child e84a337d-0af7-4b6c-b5ce-0c8dd4ccae8c, 16 instances, s3_angle_limit=-1). It ran on env 17 = trajectory 0.7.2, so its NPZs have no number_of_returns. The earlier attempt ..._20260901071431 failed.
• Miro's earlier feedback on Step 3 reruns (memory in the lanefinder project): a rerun must clean run3 files inside lane_points/ but never delete segment_NNN directories; stale segment dirs from an older padding scheme may be deleted. On AML each run writes to a fresh step3_output, so this only matters if you point at a shared folder.

Next steps

1. Clean worktree.

   cd /home/ai/dev/3dai.iolabs.orchestrator && git fetch origin
   git worktree add --detach /tmp/orch-returns origin/master
   cd /tmp/orch-returns
   grep -n "segmentation-trajectory" environments/s3_segment_mapper/conda.yml   # expect ==0.7.4
   grep -n "^version" environments/s3_segment_mapper/environment.yml          # expect 19
   grep -n "environment:" components/s3_segment_mapper.yml components/s3_build_geometry.yml   # both :19

   If a newer master moved the pin again, use whatever it says. Do not downgrade.
2. Register the Step 3 environment (this builds a new image on AML, expect 10 to 20 minutes):

   az account set --subscription ba81b555-ffe9-4625-b90a-d0011d0b57c9
   az configure --defaults group=AI3D-rg workspace=ai3d-lf-mlw-pc-01
   az ml environment create --file environments/s3_segment_mapper/environment.yml
   az ml environment show --name s3_segment_mapper --version 19 --query "[name,version]" -o tsv

   The README section "Environments" explains the difference between a portal Rebuild and a new version. Only register s6 (v7) and s5 (v2) as well if Miro also wants Steps 5 and 6 rerun on the new data.
3. Pick the Step 3 pipeline. Step 3 alone is enough for the NPZ data. Reuse pipelines/helpers/abschnitt_1_step3_no_angle_filter.yaml: it binds the baseline run's las_tasks, prepared inputs and geometry, and runs only s3_segment_mapping via components/s3_segment_mapper.yml. Decide the scan-angle filter with Miro: that helper sets s3_angle_limit: -1 (filter off, which is what the 2026-09-01 rerun used). To keep the default filter instead, override --set inputs.s3_angle_limit=<default from components/s3_segment_mapper.yml> or copy the helper to a new file such as pipelines/helpers/abschnitt_1_step3_returns.yaml and commit it. Consider also copying the display name / description so the run is identifiable.
4. Submit.

   az ml job create --file pipelines/helpers/abschnitt_1_step3_no_angle_filter.yaml \
     --set name="lanefinder_abschnitt_1_s3_returns_$(date -u +%Y%m%d%H%M%S)" \
     --set inputs.s3_instance_count=16

   Azure rejects duplicate names, hence the timestamp. 16 instances was the last successful setting; the file default is 8.
5. Monitor with the azure-cli skill: find the child job of the pipeline, tail its user_logs, and confirm the wrapper banner reports trajectory 0.7.4 and common 0.9.0. Expect the run to take roughly as long as the 2026-09-01 run (check its duration with az ml job show).
6. Verify the NPZ contract on the output (see Verification) and record the new datastore path azureml://datastores/workspaceblobstore/paths/azureml/<child-guid>/step3_output/.
7. Wire and commit. If Miro wants downstream steps or the z-range QA to consume the new data, update existing_step3_output in pipelines/helpers/abschnitt_1_from_step3.yaml and abschnitt_1_render_zrange.yaml (datastore form, never a raw https URL). Commit on master from the worktree with a one-line message prefixed by the ticket (AI3D-382 unless Miro names another), no co-author trailer, push, then git worktree remove.
8. Report back: pipeline name, child job id, output path, one verified NPZ key list with dtypes, count of segments, and the fraction of points with number_of_returns > 1 for one or two segments so Miro can see the channel is real.

Verification

Done in the previous session: package tests (producer 47, mask-clustering 93, segmentation-3d 552, filtering-intensity 13) against published common; orchestrator env-pin test green at 34e12a4. Not done: no Azure run has produced return-count NPZs yet, and no AML image has been built for the new pins.

Check one segment after the run (download via az ml job download on the child job or az storage blob download with the datastore container from the azure-cli skill):

python - <<'EOF'
import numpy as np, glob
for p in sorted(glob.glob("lane_points/segment_0*/**/*_run3_points.npz", recursive=True))[:3]:
    z = np.load(p)
    n = z["number_of_returns"]
    print(p, z.files, n.dtype, "unknown(0)=%.3f" % (n == 0).mean(), "multi(>1)=%.3f" % (n > 1).mean())
EOF

• Expected keys: points, scan_angle, intensity, red, green, blue, number_of_returns; dtype uint8; values in 1..15 for real data. An all-zero array means the LAS files in the ACC cache lack the field or the run used an old package, so inspect run3_versions.json in the output before blaming the data.
• run3_versions.json next to the segments must list segmentation-trajectory 0.7.4.

Key artifacts

Risks and open questions

• scope "Option 1" was not defined in the session that wrote this page. The assumption is: Step 3 NPZs with return counts for Abschnitt 1, for the AI3D-337 multiple-return-fraction channel. If option 1 means a different dataset (Abschnitt 2, 3, 4_5 have their own helpers) or includes downstream steps, adjust before submitting.
• env build The s3 conda env pulls common 0.9.0 with pydantic>=2.7 through pip. If the image build fails, read the build log in the portal before touching pins; a pin change means a new environment version and a matching component reference (test_env_pins).
• config validation Trajectory 0.7.4 validates its config through the new Pydantic models. Unknown keys in a job config still raise. The helper pipeline passes only segment_length_m, longitudinal_limit_distance_m and angle_limit, so this should be safe, but a failed child job with a config error points here.
• angle filter Whether the return-count data should be produced with or without the scan-angle filter is a product decision. The most recent rerun used no filter.
• downstream The z-range rasterizer that would consume the channel is on the unmerged branch feature/zrange-extra-channels and the s4c env pins rasterizer 0.6.0; producing the channel itself is a separate task.
• AML quota: the s4c helper notes Standard FSv2 is capped at 10 vCPUs; Step 3 runs on CPU-Compute-4x and 16 instances worked on 2026-09-01.
• Secrets: environments/*/conda.yml embed a Nexus credential in the extra-index-url. Never paste those lines into reports or Slack.

Suggested skills

azure-cli for everything on AML; codex-rescue or cursor-delegate for log digging; slack-post only if Miro asks for progress updates.