README.md

# S23DR 2026 — Iterating on the Baseline (5th place)

Solution for the [S23DR 2026](https://huggingface.co/spaces/usm3d/S23DR2026)
structured 3D wireframe reconstruction challenge. Private leaderboard:
**0.5388 HSS, 5th place**, with a single 8.85M-parameter Perceiver.

The submitted entry is the **raw 8k Perceiver**: a learned segment model over a
fused, priority-sampled COLMAP/depth point cloud, with no hand-crafted
post-processing. The repository also contains the hand-crafted pipeline and the
classifier-gated hybrid that we used earlier in the competition, and the
training/repro scripts behind them. See the accompanying write-up for the full
account.

## Run inference

```bash
pip install -r requirements.txt
python script.py
```

The challenge harness provides `params.json`, downloads the dataset, runs
`script.py`, and reads the resulting `submission.json`
(`{order_id, wf_vertices, wf_edges}` per scene). `script.py` loads
`checkpoint_8192.pt` and runs the raw 8k model (`CONF_THRESH=0.5`, no seam,
no augments).

## Layout

```
script.py                 raw 8k inference (the submitted entry)
Writeup.pdf               method write-up (full account of the solution)
checkpoint_8192.pt        8k Perceiver weights (the 5th-place model)
checkpoint.pt             organizers' 4k Perceiver (curriculum start point)
solution.py               hand-crafted geometric pipeline
edge_classifier.py        PointNet edge classifier (hybrid augment)
vertex_refiner.py         PointNet vertex classifier (hybrid augment)
pnet_class_2026.pth       edge classifier weights
vertex_refiner.pth        vertex classifier weights
s23dr_2026_example/       model + training package (Perceiver, tokenizer, losses, train.py)
configs/                  training config (base.json)
REPRODUCE.md              recipe for the resolution curriculum (2k -> 4k -> 8k)
training/                 data-generation and training scripts (see below)
experiments/ptv3/         the Point Transformer V3 encoder experiment
                          (negative result; trained model + logs + code)
```

## Reproducing

**The 8k model.** Follow `REPRODUCE.md`: train the Perceiver from scratch at
2048 points, then fine-tune at 4096 and 8192 points on the organizers' released
sampled point clouds. Our contribution is the 4k→8k stage; the released 4k
checkpoint (`checkpoint.pt`) is the starting point.

**Classifier augments.** `training/gen_edge_dataset.py` and
`training/gen_vertex_dataset.py` build the per-candidate patch datasets from the
hand-crafted pipeline's predictions; `training/train_edge_classifier_2026.py`
and `training/train_vertex_refiner_2026.py` train the PointNet classifiers.

**Router (negative result).** `training/train_routing_gbt.py` with
`training/oracle_sources_{train,validation}.json` reproduces the gradient-boosted
per-scene router; it recovered only 4.5% of the per-scene oracle ceiling.

Some scripts under `training/` contain absolute paths from the original training
environment and expect the repository root on `PYTHONPATH`
(e.g. `PYTHONPATH=. python training/train_edge_classifier_2026.py`); adapt the
paths to your setup.