# Semantic work-zone digital-twin pilot

This package runs a deterministic **procedural sensor-fusion pilot** over three
illustrative work-zone boundary layouts, five fixed seeds, and three patrol
strategies. It simulates an ordinary 3-D LiDAR observation process with finite
range, angular-bin occlusion, dropout, coordinate noise, and semantic noise;
fuses observations into a voxel semantic point cloud; detects temporary
traffic-control (TTC) instances; and lowers their estimated boundary into a
four-class operational bird's-eye-view map.

This is synthetic algorithm test data. It is **not CARLA data, real LiDAR or
hardware evidence, an approved temporary-traffic-control design, or a safety
assessment**. The operational classes are evaluation labels in an illustrative
coordinate frame, not deployment permissions.

## Experiment matrix

- Layouts: `right_lane_closure`, `shoulder_work_area`, `lane_shift_chicane`
- Seeds: `20260808`, `20260809`, `20260810`, `20260811`, `20260812`
- Patrols: `single_pose`, `one_way_patrol`, `loop_patrol`
- Total runs: 45
- Preregistered representative artifact: `right_lane_closure`, seed
  `20260808`, `loop_patrol`

Metric definitions and claim boundaries are specified in
`docs/research_protocol.md`; figure forms are fixed in
`docs/chart_contract.md`.

## Result snapshot

Mean reconstruction completeness was `0.071`, `0.627`, and `0.787` for the
single-pose, one-way, and loop strategies. Mean actionable mIoU was `0.086`,
`0.687`, and `0.717`; mean known coverage was `0.099`, `0.804`, and `0.821`.

Two preregistered directional expectations were supported: the loop exceeded
the single pose in mean completeness and actionable mIoU. The expectation that
loop false-traversable rate would be no higher was **not supported** (`0.00084`
versus `0.00000`). The single-pose zero accompanies only 9.9% mean known
coverage because unknown cells are excluded from that failure rate; it is not
evidence of greater safety.

## Run

```bash
cd "/home/bo/UMD/proposal/ScholarMind AI/research-portfolio/semantic-workzone-digital-twin"
python3 -m pip install -r requirements.txt
python3 -m pip install -e . --no-deps
python3 -m semantic_workzone.experiment --output results
python3 make_figures.py --results results
python3 -m unittest discover -s tests -v

# Build and execute the portable analysis notebook.
python3 notebooks/build_notebook.py
jupyter nbconvert --to notebook --execute \
  notebooks/semantic_workzone_digital_twin_colab.ipynb \
  --output semantic_workzone_digital_twin_colab.ipynb \
  --output-dir notebooks --ExecutePreprocessor.timeout=300
```

The experiment writes the manifest, 45-row run index, validation record,
per-run prediction-safe observation, separate evaluation-audit, fusion,
boundary, and BEV NPZ files, raw and aggregate CSV tables, and a complete JSON
summary. Figures are rendered only from those saved artifacts.
