README.md

---
license: cc-by-nc-4.0
library_name: diffusers
tags:
- diffusers
- safetensors
- vfxdb
- openvdb
- 3d
- volumetric
---

# VfxDB paper checkpoints

Inference-only EMA checkpoints for the VfxDB static-unconditional,
static-conditional, and temporal-conditional 3D diffusion models.

The tensor values were converted losslessly from the paper `step_1000000.pt`
checkpoints. The public `diffusion_pytorch_model.safetensors` files contain the
paper EMA weights directly; they do not contain optimizer state, online weights,
or pickle payloads.

## Checkpoints

| Subfolder | Task | Input channels | Classes | Weight size |
| --- | --- | ---: | ---: | ---: |
| `static-unconditional-32` | uncond_static | 1 | 0 | 154.61 MiB |
| `static-conditional-32` | cond_static | 1 | 11 | 154.62 MiB |
| `temporal-conditional-32` | cond_temporal | 2 | 11 | 154.63 MiB |

All checkpoints use a 32³ dense volume, a 200-step linear DDPM schedule,
epsilon prediction, an occupancy output head, and the `log1p` value space with
scale `0.02`.

## Required inference behavior

Exact paper-aligned inference requires:

- `scheduler_name: ddpm`
- `scheduler_legacy_align: true`
- `sampling_steps: 200`
- `only_cfg_eps: true`
- the per-checkpoint CFG and temporal settings in each `inference_config.yaml`

Using the native Diffusers DDPM scheduler without legacy alignment does not
reproduce the historical sampler exactly.

## Load the model weights

Use the VfxDB model implementation and Hub-aware inference entrypoint from the
official repository, pinned here to commit `d8cc604594f6875677a32117bc051c539e8427a7`:

```bash
git clone https://github.com/VfxDB-Official/VfxDB.git
cd VfxDB
git checkout d8cc604594f6875677a32117bc051c539e8427a7
python -m pip install -r requirements-core.txt
```

```python
from models.vfx_model import UNet3DModel

model = UNet3DModel.from_pretrained(
    "ryogishiki/VfxDB-models",
    subfolder="checkpoints/paper-v1/static-conditional-32",
)
model.eval()
```

The model is a custom VfxDB Diffusers `ModelMixin`, not an official built-in
Diffusers architecture. Construct the `VfxDBDensePipeline` with the official
repository code and enable the legacy-aligned scheduler.

The official CLI can load each Hub subfolder directly with the paper-aligned
preset configs:

```bash
python infer_one_stage_hf.py --config configs/infer_paper_static_unconditional_32.yaml
python infer_one_stage_hf.py --config configs/infer_paper_static_conditional_32.yaml
python infer_one_stage_hf.py --config configs/infer_paper_temporal_conditional_32.yaml
```

The presets pin this repository's initial weight revision and do not require a
pickle checkpoint or `trainer_state.pt`.

## Provenance

- Model milestone: `896aadcf799f6392100025ffbcabbe2d83357201` (`milestone_v1_0`)
- Paper backup: `0e65b55b3093cbda42a6824fd0a2e76e0b743dad`
- Paper backup 2: `ffa577bbb70d71ebe312e7078d9e82a490f9ba87`
- Weight conversion and initial validation code: `b74cf7db151d83a47e6598f6418a32a0ac68e7c6`
- Hub-ready public inference release: `d8cc604594f6875677a32117bc051c539e8427a7`

Exact source and artifact hashes are recorded in
`checkpoints/paper-v1/manifest.json` and each checkpoint's `provenance.json`.

## License

CC BY-NC 4.0, matching the VfxDB dataset release.