Upload README.md with huggingface_hub

README.md

@@ -1,52 +1,83 @@
 # S23DR 2026 — WireframeDETR
 
-Third-place submission to the [S23DR 2026 Challenge](https://huggingface.co/spaces/usm3d/S23DR2026).
+Submission to the [S23DR 2026 Challenge](https://huggingface.co/spaces/usm3d/S23DR2026).
 
-## Related Work
-
-Classical 3D structured reconstruction methods ([PolyFit](https://doi.org/10.1109/ICCV.2017.258), [City3D](https://doi.org/10.3390/rs14092254)) detect planar primitives via RANSAC then intersect them to find edges/vertices — multi-stage pipelines with handcrafted priors. 2D wireframe parsing ([WireframeParser](https://arxiv.org/abs/1905.03246), [L-CNN](https://arxiv.org/abs/1905.03246), [HAWP](https://arxiv.org/abs/2005.03246)) works on images, not 3D. [RoomFormer](https://arxiv.org/abs/2301.09051) is the closest precedent: DETR-style transformer predicting room polygons from 3D scan density maps. We extend this to outdoor building wireframes on raw sparse semantic point clouds, replacing density projection with direct point encoding.
+**Public test HSS: 0.575** (F1=0.664, IoU=0.516)
 
 ## Approach
 
-We formulate 3D building wireframe prediction as DETR-style set prediction over semantic point clouds. Starting from the official Perceiver baseline, we tried Perceiver fine-tuning (catastrophic forgetting) and a two-stage PointNet pipeline (poor edge precision) before arriving at this approach.
+End-to-end 3D wireframe prediction via DETR-style set prediction over COLMAP point clouds.
+Each predicted edge is a 6D coordinate pair `(x1,y1,z1,x2,y2,z2)` regressed by a learned query.
+Hungarian matching assigns predictions to ground-truth edges at training time.
 
 **Our contributions:**
-- Contrastive Denoising Training (CDN) adapted from [DN-DETR](https://arxiv.org/abs/2203.01305) to stabilise Hungarian matching
-- Multi-scale encoder memory: learned weighted average of last 3 encoder layer outputs
-- Progressive auxiliary loss weighting across decoder layers
-- Test-time augmentation via Y-axis rotations
+- **Contrastive Denoising Training (CDN)** — adapted from [DN-DETR](https://arxiv.org/abs/2203.01305); injects GT-aligned denoising queries alongside learned queries to stabilise Hungarian matching in early epochs
+- **Multi-scale encoder** — learned softmax-weighted average of last K=3 encoder layer outputs, giving the decoder access to both fine-grained and abstract representations
+- **Gestalt-guided point sampling** — vertex-class points (apex, eave end, flashing end) sampled at 100×, edge-class points at 10×, background at 1×; concentrates samples on structural features without encoding semantics as model features
+- **Progressive auxiliary loss weighting** — decoder layer i weighted at 0.5 + 0.5·(i+1)/N
+- **Test-time augmentation** — four Y-axis rotations (0°/90°/180°/270°), predictions merged via vertex deduplication
 
-**Adopted from public code ([jastermark/S23DR2026](https://huggingface.co/jastermark/S23DR2026)):**
-- Gestalt-weighted point sampling (vertex classes 100x, edge classes 10x)
-- 183-d semantic feature encoding (Gestalt one-hot + ADE20K one-hot + RGB)
-- Post-processing pipeline (confidence filtering, intersection-based vertex merging)
+**Model input:** plain 3-channel RGB per point. No semantic feature encoding.
 
-The Gestalt pipeline turned out to be a significant contributor — an ablation against plain RGB features confirms this.
+**Adopted from [jastermark/S23DR2026](https://huggingface.co/jastermark/S23DR2026):**
+- COLMAP point projection pipeline (assign Gestalt label per point by majority vote across views)
+- Post-processing (confidence filtering, intersection-based vertex merging, gap filling)
 
 ## Results
 
-| Approach | Val HSS |
-|---|---|
-| Perceiver baseline | 0.350 |
-| WireframeDETR (ours, best checkpoint) | 0.520 |
-| Final submission | TBD |
+| Approach | Split | F1 | IoU | HSS |
+|---|---|---|---|---|
+| Perceiver baseline | cleaned val | — | — | 0.350 |
+| PointNet two-stage (Path B) | public test | 0.497 | 0.409 | 0.442 |
+| WireframeDETR (ours) | cleaned val | 0.603 | 0.471 | 0.534 |
+| WireframeDETR (ours, best) | public test | **0.664** | **0.516** | **0.575** |
 
-## Training
+## Architecture
 
-Training was done on Modal Labs A100 80GB GPUs. I used ~$500 in Modal credits from a previous hackathon win — grateful for that, as it made running 200-epoch experiments feasible within a tight timeline.
+- Embedding dim: 384, Queries: 128, Encoder layers: 4, Decoder layers: 5
+- ~22.7M parameters
+- CDN groups: 5, λ_pos=0.4, λ_neg=0.8
+- Training: AdamW lr=1e-4, OneCycle schedule, batch=14, 200 epochs, A100 80GB (~27h)
 
-```bash
-# reproduce training
-bash reproduce.sh /path/to/ply_data run-name
+## Checkpoint
+
+`wireframe_detr_cdn_multiscale_384d_128q.pth` — plain RGB, feature_dim=3
+
+## Inference
+
+```python
+from s23dr_2026.model import get_model, load_checkpoint_compat
+from s23dr_2026.inference import predict_wireframe_v2
+
+import torch
+ckpt = torch.load("wireframe_detr_cdn_multiscale_384d_128q.pth", map_location="cpu")
+model = get_model(ckpt)
+load_checkpoint_compat(model, ckpt)
+model.eval().to("cuda")
 
-# or via Modal
+verts, edges = predict_wireframe_v2(scene, model, "cuda")
+```
+
+## Training
+
+```bash
+# via Modal
 modal run pipeline.py --step train --name my-run
+
+# local
+python -m s23dr_2026.train \
+  --name my-run \
+  --ply_dir /path/to/ply_data \
+  --embed_dim 384 --num_queries 128 \
+  --num_encoder_layers 4 --num_decoder_layers 5 \
+  --use_cdn --cdn_groups 5 \
+  --scheduler onecycle --num_epochs 200 \
+  --batch_size 14 --device cuda
 ```
 
 ## Credits
 
-- [jastermark/S23DR2026](https://huggingface.co/jastermark/S23DR2026) — Public EdgeDETRPE implementation; data pipeline and post-processing adopted from here
-- [DN-DETR](https://arxiv.org/abs/2203.01305) — contrastive denoising training scheme
-- [DINO-DETR](https://arxiv.org/abs/2203.03605) — progressive auxiliary loss weighting
+- [jastermark/S23DR2026](https://huggingface.co/jastermark/S23DR2026) — COLMAP projection pipeline and post-processing
+- [DN-DETR](https://arxiv.org/abs/2203.01305) — contrastive denoising training
 - [S23DR 2026 organisers](https://huggingface.co/spaces/usm3d/S23DR2026) — challenge and baseline
 - [Modal Labs](https://modal.com) — GPU compute