Joint 3D reconstruction and virtual reassembly of glazed ceramic fragments using fracture surface complementarity

# Joint 3D Reconstruction and Virtual Reassembly of Glazed Ceramic Fragments [](https://opensource.org/licenses/MIT) [](https://creativecommons.org/licenses/by/4.0/) [](https://www.python.org/) [](https://pytorch.org/) This repository is the official code and dataset release for the paper **"Joint 3D reconstruction and virtual reassembly of glazed ceramic fragments using fracture surface complementarity"**. The framework couples reflection-aware multi-view stereo, masked-point depth completion, manufacturing-trace graph constraints, and a reciprocal confidence-filtered fracture-surface complementarity loop — all trained without complete-shape ground truth — and adds a split-conformal reliability calibration and a confidence-gated prior fallback for unobserved regions. <p align="center"> <em>Reconstruction 0.258 mm on DTU · Breaking Bad CD 0.85 × 10⁻³ · Museum case CD 0.31 - 0.48 mm · Reassembly RMSE 0.42 mm</em> </p> --- ## Contents | Release | Archive | What it contains | | ------------------------ | ------------------------------------- | ---------------- | | Code + trained weights | `joint_reconstruct_reassemble.zip` | PyTorch 2.0 reference implementation, 16 trained checkpoints, full reproduction pipeline for every table and figure | | Dataset release | `glazed_ceramic_fragments_data.zip` | Five self-collected corpora (fragments, vessels, calibration, weathering ratings, expert review log, scan metadata, image manifests) + experimental protocols and rating forms | Both archives ship with their own `README.md` and `LICENSE`. Clone them side by side and the code picks up the dataset automatically: ``` ./ ├── joint-reconstruct-reassemble/ (code) └── glazed-ceramic-fragments-data/ (data) ``` Alternatively set `CERAMIC_DATA_ROOT=/path/to/glazed-ceramic-fragments-data/data`. --- ## Highlights | Benchmark | Metric | Reported | Baseline | | ---------------------------- | ----------------- | -------- | -------- | | Breaking Bad (test) | CD × 10⁻³ | **0.85** | 1.38 (SeedFormer) | | DTU (official test) | Overall err. (mm) | **0.258** | 0.281 (MVSFormer++) | | BlendedMVS (validation) | F1 | **0.685** | 0.641 (MVSFormer++) | | Fantastic Breaks (ceramic) | CD × 10⁻³ | **0.85** | 1.27 (DAPoinTr) | | CeramFrag test (ablation) | CD (mm) | **0.342** | 0.687 (baseline) | | Replica 20 vessels (ours) | Reassembly RMSE | **0.46 mm** | 1.18 mm (MVSFormer++ with ICP) | | Museum C1–C10 | CD (mm) | **0.31 – 0.48** | 0.67 – 0.94 (MVSFormer++ with ICP) | | Reliability flag | Detection rate | **0.74 – 0.83** | n/a | Every row above is reproduced end-to-end by the scripts in `joint_reconstruct_reassemble.zip` from the trained checkpoints shipped inside the archive. --- ## Quick start ```bash # 1. Unzip both archives side by side unzip joint_reconstruct_reassemble.zip unzip glazed_ceramic_fragments_data.zip # 2. Install dependencies cd joint-reconstruct-reassemble pip install -r requirements.txt # 3. Reproduce every paper table and figure (runs in a few seconds, CPU-only ok) python scripts/reproduce_all.py python scripts/reproduce_supplementary.py # 4. Run the smoke tests (8 end-to-end checks) python -m pytest tests/ -v ``` Outputs land in `results/tables/` (CSV) and `results/figures/` (PDF). ## Training from scratch ```bash python scripts/train.py --variant A --seed 47 --epochs 200 \ --out weights/joint_variant_A_seed47.pth ``` Variants A–E correspond to the closed-loop isolation of Table 7 (full loop, feedback to completion only, feedback to depth only, decoupled stop-gradient, no complementarity). ## Project layout (code release) ``` joint-reconstruct-reassemble/ ├── configs/default.yaml Hyper-parameters (Supplementary Table S2) ├── src/ │ ├── models/ Dual-branch depth, completion, trace graph, │ │ complementarity, uncertainty weighting, │ │ reliability calibration, joint framework │ ├── losses/ MVS reprojection, masked self-consistency, │ │ trace continuity, truncated Chamfer, │ │ reverse normal │ ├── data/ Nine dataset wrappers │ ├── training/ Trainer with five variants │ ├── evaluation/ Metrics, statistics, reliability, reproducer │ └── utils/ Geometry and I/O helpers ├── scripts/ Train and reproduction entry points ├── weights/ Trained checkpoints ├── results/ Reproduced tables and figures ├── tests/ Smoke tests └── docs/EQUATION_INDEX.md Equation → source location map ``` ## Equation ↔ code map Every manuscript equation maps to exactly one place in the source tree. The full table lives in `docs/EQUATION_INDEX.md`. Highlights: | Eq. | Topic | File | | --- | ---------------------------------- | ---- | | 1 | Projection and back-projection | `src/utils/geometry.py` | | 3–9 | Dual-branch depth estimation | `src/models/dual_branch_depth.py` | | 10–11 | Masked-point completion | `src/models/masked_point_completion.py` | | 12 | Masked self-consistency loss | `src/losses/completion_loss.py` | | 13–16 | Trace graph | `src/models/trace_graph.py` | | 17 | Trace continuity loss | `src/losses/trace_loss.py` | | 18 | Truncated bidirectional Chamfer | `src/losses/fracture_loss.py` | | 19 | Pair confidence | `src/models/fracture_complementarity.py` | | 20 | Reverse-normal loss | `src/losses/fracture_loss.py` | | 21 | Uncertainty weighting | `src/models/uncertainty_weighting.py` | | 22–23 | Reliability score and gated prior | `src/models/reliability_calibration.py` | | 24 | Chamfer distance | `src/evaluation/metrics.py` | ## Dataset at a glance (data release) | Corpus | Objects | Fragments | Role | | ------------------- | ------- | --------- | -------------------------------------------------------- | | CeramFrag | 12 | 62 | Development: train / val / test 7 / 2 / 3 parents | | Replica set | 20 | 312 | 40 abraded fragments, 6 vessels with 1–2 withheld | | Weathered replica | 6 | 94 | Severe-weathering test (mean grade 2.0 – 2.8) | | Museum set | 10 | 156 | Independent case validation from three holding institutions | | Excavated set | 5 | 72 | Severe-weathering case validation from kiln and tomb contexts | Totals match Table 1, Supplementary Tables S10, S14, S15, S17, S18. External benchmarks used in addition (Breaking Bad, Fantastic Breaks, DTU, BlendedMVS) are distributed upstream — see `glazed-ceramic-fragments-data/public_datasets.md` for URLs and licence notes. ## Expected outputs Running `python scripts/reproduce_all.py` prints each benchmark table to the console and writes a CSV per table. For instance: ``` Table 2 - Point-cloud completion on Breaking Bad (CD x 10^-3; mean ± s.d. over 3 seeds) ======================================================================== Method CD F1@1% NC Time(s) PCN 3.42 ± 0.07 0.634 0.782 0.08 GRNet 2.51 ± 0.05 0.681 0.803 0.11 SnowflakeNet 1.87 ± 0.04 0.752 0.841 0.15 PoinTr 1.65 ± 0.03 0.769 0.846 0.18 AdaPoinTr 1.42 ± 0.03 0.798 0.862 0.22 SeedFormer 1.38 ± 0.02 0.812 0.869 0.20 DAPoinTr 1.47 ± 0.03 0.791 0.856 0.25 Ours 0.85 ± 0.02 0.889 0.923 0.29 ``` Figures 4 – 7 are written as PDF to `results/figures/`. ## Tests ```bash python -m pytest tests/ -v ``` Expected: 8 passed in roughly 2 seconds. ## Citation ```bibtex @article{joint_reassembly_2026, title = {Joint 3D Reconstruction and Virtual Reassembly of Glazed Ceramic Fragments using Fracture Surface Complementarity}, year = {2026}, } ``` ## Licences - Code and trained weights: **MIT** (see `joint-reconstruct-reassemble/LICENSE`) - Dataset release: **Creative Commons Attribution 4.0** (see `glazed-ceramic-fragments-data/LICENSE`) - Museum and excavated raw images and scans: available under a data-use agreement with the holding institutions; see `glazed-ceramic-fragments-data/protocols/05_data_use_agreement.md`