Constraint-guided, set-valued terminal repair for generated 3D indoor scenes.
SceneRepair_v2 combines stage-specific neural proposal models, deterministic fallbacks, hard geometric verification, and transactionally isolated execution. It repairs terminal scene states while preserving a strict fail-closed boundary: an invalid candidate is rejected and rolled back rather than committed.
Research status: this repository is a research prototype. The current SceneExpert integration runs in read-only Shadow mode and Active scene mutation remains disabled. See Current status for the latest evidence and blockers.
The screenshot is a deterministic expected-output showcase. It demonstrates the intended five-stage interaction and is not presented as a measured SceneExpert result. Measured results are reported separately below.
SceneRepair operates after scene generation. It inspects the current scene,
routes each stage to KEEP, bounded local repair, or ESCALATE, generates a
set of candidate repairs, executes each candidate in isolation, and accepts only
states that pass the release verifier and stage policy.
| Stage | Repair scope | Current implementation |
|---|---|---|
| Floor Plan | House topology and room routing | FloorPlanRouter; routes to keep or regeneration without mutating topology in-process |
| Furniture | Object identity and bounded x/y/yaw edits |
FurnitureRepairModel plus verifier-guided local search |
| Wall | Wall-mounted object placement | Independent SurfaceCandidateRanker |
| Ceiling | Ceiling-mounted object placement | Independent SurfaceCandidateRanker |
| Manipuland | Support-local placement of small objects | ManipulandCandidateRanker with deterministic fallback |
flowchart LR
A[Scene state and task] --> B[Typed scene graph]
B --> C[Stage router]
C --> D[Neural candidate set]
C --> E[Deterministic fallback]
D --> F[Transactional executor]
E --> F
F --> G[Release verifier]
G -->|valid| H[Stage policy and selection]
G -->|invalid| I[Exact rollback]
H --> J[KEEP or bounded repair]
I --> K[Next candidate or ESCALATE]
Key design properties:
- Set-valued supervision: multiple verifier-valid repair strategies can be correct; training and evaluation do not force one arbitrary target.
- Verifier-owned acceptance: model scores never bypass identity checks, action budgets, hard constraints, robustness checks, or rollback.
- Stage isolation: checkpoint families and feature schemas are stage-specific; cross-stage loading and mismatched runtime contracts are rejected.
- Evidence provenance: datasets, checkpoints, calibration files, Shadow reports, and source states are bound by versioned schemas and hashes.
- Fail-closed data gates: missing source coverage or provenance stops dataset materialization instead of silently fabricating supervision.
Furniture checkpoint computation graph
The diagram shows the branches actually consumed by the current Shadow checkpoint. Verifier-guided search, candidate execution, rule fallbacks, and physical validation are deliberately outside the neural network.
The latest frozen research snapshot is dated 2026-07-26. The compact HSSD82 Furniture test split passes its offline gates, but this does not establish real-domain readiness.
| Metric | Result |
|---|---|
| Route accuracy | 1.0000 |
| Target-set F1 / exact-set accuracy | 1.0000 / 1.0000 |
| Translation error | 0.1330 m |
| Hard-valid calibration error | 0.0686 |
| OOD AUROC / F1 | 1.0000 / 1.0000 |
| Component | Frozen evidence | Readiness |
|---|---|---|
| Semantic join | 79/79 HSSD instances resolved exactly | shadow_join_ready |
| Floor Plan | 24/24 controlled routes correct | route_only_shadow_ready |
| Furniture | Real held-out raw-neural route 1/2; hard-valid controlled repair 0/1 | not_ready |
| Wall | Neural top-1 4/4; hybrid 4/4 | bbox_shadow_neural_plus_verifier |
| Ceiling | Neural top-1 7/7; hybrid 7/7 | bbox_shadow_neural_plus_verifier |
| Manipuland | Neural 6/7; hybrid 7/7 | bbox_shadow_rule_fallback_required |
For Furniture, the deterministic fallback repaired 1/1 controlled held-out
fault and the guarded system routed 2/2 states correctly, while the raw neural
model did not pass. Therefore guarded_system_pass=true and
raw_neural_model_pass=false are intentionally reported as separate claims.
The next data release is gated on independent real SceneExpert sources across
four room types, three splits, and native KEEP/ESCALATE routes. Collection,
provenance binding, and V6 materialization tooling are implemented; the V6
corpus must pass the full 24-cell source audit before training begins. Details:
- Furniture V6 diagnosis and execution status
- Furniture real-domain training contract V6
- SceneExpert Furniture V5 Shadow deployment
- Python
3.11 - PyTorch
2.5 - Windows, Linux, or macOS for CPU development
- CUDA-capable hardware only for model training and GPU evaluation
Create an environment and install the package in editable mode:
git clone https://github.com/Hex671/SceneRepair_v2.git
cd SceneRepair_v2
python -m venv .venv
python -m pip install --upgrade pip
python -m pip install -e ".[dev]"Activate .venv using the command for your shell, then run the tests:
python -m pytest -qStart the deterministic five-stage showcase without loading live checkpoints:
python -m scene_repair.demo --no-liveOpen http://127.0.0.1:8791/. Select the living room, studio, or bedroom
scenario and run the complete repair sequence. Add ?autorun=1 to the URL to
start automatically.
Windows users can also run:
.\start_demo.ps1List the available data, training, evaluation, calibration, and Shadow commands:
scene-repair-v2 --helpA minimal synthetic workflow is:
scene-repair-v2 build-synthetic-episodes artifacts/example_episodes \
--scenes 20 --corruptions-per-scene 4
scene-repair-v2 train-episodes \
artifacts/example_episodes/repair_episode_manifest.jsonl \
artifacts/example_model.pt --epochs 2 --device cpu
scene-repair-v2 evaluate-episodes \
artifacts/example_episodes/repair_episode_manifest.jsonl \
artifacts/example_model.pt --split test --device cpuUse small synthetic runs only to validate the software path. They do not replace the frozen HSSD/SceneSmith datasets, calibration, or independent Shadow evidence.
Raw ProcTHOR, HSSD, and SceneSmith assets are not redistributed by this repository. Large databases, model checkpoints, generated states, and logs are also excluded from Git. The repository tracks source code, versioned configuration, tests, compact frozen reports, hashes, and selected visual summaries.
See artifacts/README.md for the artifact policy and data/README.md for local data layout. Most commands accept explicit paths, so no contributor-specific server directory is required.
| Path | Purpose |
|---|---|
scene_repair/ |
Models, graph construction, repair engine, verifiers, datasets, evaluation, and demo server |
configs/ |
Versioned data, training, runtime, and release configurations |
tools/ |
Reproducible builders, audits, evaluators, collection runners, and visualization utilities |
tests/ |
Unit, contract, integration, transaction, and regression tests |
docs/ |
Design notes, data contracts, deployment guides, and experiment reports |
current_work/ |
Current status, decisions, update log, and ordered next steps |
artifacts/ |
Small frozen reports and selected visual evidence; large outputs stay local |
Start with these documents:
- Current project status
- Ordered next steps
- Complete design document
- HSSD runtime semantic contract
- Furniture training data contract v3
- SceneRepair ideal-repair showcase
- SceneExpert CCI output audit
- Shadow expansion readiness
Interactive local visualizations are available in
docs/visualizations/network_architecture.html and
docs/visualizations/training_data_explorer.html.
- Active mutation is disabled by default and is not certified by the current evidence.
- A bbox/relation verifier result is not a mesh, MuJoCo, Drake, or real-world physics result.
- Controlled corruptions and repeated runs are reported separately from independent natural failures.
- Guarded-system performance is never presented as raw-neural performance.
- Historical Critic scores are baselines, not post-repair scores; a new live Critic session is required for causal comparison.
- Unknown evidence remains unknown. Candidate-search failure is not relabeled as proof that a scene is unrepairable.
This repository does not currently publish an open-source license. Source availability does not imply permission to reuse or redistribute the code or artifacts. Contact the repository owner before external reuse.