README.md

---
license: cc-by-nc-sa-4.0
library_name: mast3r
tags:
  - 3d-reconstruction
  - uncertainty-quantification
  - evidential-deep-learning
  - pointmap
  - mast3r
  - dust3r
---

# Trust3R — evidential uncertainty for feed-forward 3D reconstruction

Checkpoints for **“Trust It or Not: Evidential Uncertainty for Feed-Forward 3D
Reconstruction with Trust3R”** (ICML 2026).

- Code: https://github.com/phai-lab/Trust3R
- Project page: https://trust3r-z.github.io/
- Paper: https://arxiv.org/abs/2605.19539

Trust3R adds two lightweight heads to a **frozen MASt3R backbone**: an evidential
uncertainty head that predicts the parameters of a Normal-Inverse-Wishart prior over each
3D point — yielding a closed-form Student-*t* predictive distribution and a calibrated
per-pixel uncertainty map in a **single forward pass, no ensembles and no Monte Carlo
sampling** — and a gated residual head that applies small, gated corrections to the
pretrained pointmap.

## Files

| File | Head | Backbone | Res. | Size |
|---|---|---|---|---|
| `trust3r_niw_mast3r_224.pth` | NIW evidential (full 3×3 covariance) + gated residual | frozen MASt3R ViT-L | 224 | 3.0 GB |
| `trust3r_nig_mast3r_224.pth` | NIG evidential (diagonal variance) + gated residual | frozen MASt3R ViT-L | 224 | 3.0 GB |

NIW is the main model. NIG is the evidential-family ablation. Each `.pth` ships a
`.sha256` sidecar and a `.metadata.json` recording provenance, training mix and the
evaluation protocol.

## Download

```bash
pip install -U "huggingface_hub[cli]"
mkdir -p checkpoints
hf download phai-lab/Trust3R \
    trust3r_niw_mast3r_224.pth trust3r_nig_mast3r_224.pth \
    trust3r_niw_mast3r_224.pth.sha256 trust3r_nig_mast3r_224.pth.sha256 \
    --local-dir checkpoints/
(cd checkpoints && sha256sum -c *.sha256)
```

## Usage

```python
from mast3r.model import AsymmetricMASt3R

model = AsymmetricMASt3R.from_pretrained("checkpoints/trust3r_niw_mast3r_224.pth").eval()
```

The model expression is stored inside the checkpoint, so no architecture arguments are
needed. A minimal pair-inference example is `infer.py` in the GitHub repo; the NIW
predictive variance is recovered from the head outputs as

```python
kappa = pred1["xyz_niw_kappa"]           # (1, 1, H, W)
nu    = pred1["xyz_niw_nu"]              # (1, 1, H, W)
Psi   = pred1["xyz_niw_Psi"]             # (1, 3, 3, H, W)
trace_Psi = Psi[:, 0, 0] + Psi[:, 1, 1] + Psi[:, 2, 2]
total_var = trace_Psi / (kappa.squeeze(1) * (nu.squeeze(1) - 4.0).clamp_min(1e-3))
```

Provenance and protocol metadata:

```python
import torch
print(torch.load("checkpoints/trust3r_niw_mast3r_224.pth", map_location="cpu")["trust3r"])
```

## Training

Initialised from `MASt3R_ViTLarge_BaseDecoder_512_catmlpdpt_metric.pth`, backbone frozen,
150k steps at 224px (batch 10, 10 epochs) on a four-dataset mix of 150k pairs per epoch:
ScanNet++ (25k), ARKitScenes (25k), Waymo (50k) and MegaDepth (50k). AdamW, base LR
3e-4 with cosine schedule, evidence regularisation λ_evi = 1e-3.

## Evaluation

`eval/reproduce_table1_table2.sh` in the GitHub repo reproduces the paper tables from
these checkpoints — AURC, AUSE, Spearman ρ, Sim(3)-aligned MAE/RMSE and NLL over
ScanNet++, TUM RGB-D, KITTI and ETH3D. See `eval/README.md` there for the protocol.

## License and intended use

**CC BY-NC-SA 4.0 — non-commercial use only**, inherited from MASt3R and DUSt3R. See
`CHECKPOINTS_NOTICE` in the GitHub repo for the terms attached to the training datasets;
ScanNet++, Waymo and ETH3D additionally require registration with their providers.

These weights are trained at 224px for research on uncertainty-aware 3D reconstruction.
Other resolutions are outside the trained regime.

## Citation

```bibtex
@misc{zhu2026trust3r,
  title  = {Trust It or Not: Evidential Uncertainty for Feed-Forward 3D Reconstruction with Trust3R},
  author = {Zhu, Zihao and Zhao, Wenyuan and Chen, Nuo and Tian, Chao and Fan, Zhiwen},
  year   = {2026},
  eprint = {2605.19539},
  archivePrefix = {arXiv}
}
```