raw/README.md

---
library_name: pytorch
tags:
  - robotics
  - diffusion-policy
  - 3d-point-cloud
  - coverage-path-planning
  - safetensors
---

# 3D-CovDiffusion checkpoints

Category-specific pretrained policies for **3D-CovDiffusion: 3D-Aware
Diffusion Policy for Coverage Path Planning**.

- Project page: https://crystalccy1.github.io/3D-CovDiffusion/
- Code: https://github.com/crystalccy1/3D-CovDiffusion
- Train-ready dataset: https://huggingface.co/datasets/ChenyuanC/3D-CovDiffusion-Train-Ready

## Released models

Each root category directory contains the EMA weights selected by the original
seed-42 training run. `raw/<category>/` contains a tensor-only exact export of
the raw `state_dicts.model` entry loaded by the archived selected-visualization
test script. Every directory includes its inference configuration and
provenance metadata.

| Directory | Dataset | Training run | Top-k selection PCD ↓ |
|:--|:--|:--|--:|
| `windows/` | `windows-v2` | `TML4Q-S42` | 10.410878 |
| `cuboids/` | `cuboids-v2` | `X1PD1-S42` | 6.612324 |
| `shelves/` | `shelves-v2` | `52VCU-S42` | 10.069027 |
| `containers/` | `containers-v2` | `ODAV4-S42` | 347.932620 |

| Selected inference case | Raw tensor path | Test split item |
|:--|:--|:--|
| Windows | `raw/windows/model.safetensors` | index 5, `810_wr1fr_1` |
| Cuboids | `raw/cuboids/model.safetensors` | index 3, `669_cube_1001_1285_1263` |
| Shelves | `raw/shelves/model.safetensors` | index 4, `box_h620_w500_d220.0_sh1.0_sv2.0` |
| Containers | `raw/containers/model.safetensors` | index 1, `spoegcr3gv` |

The values above are the per-run validation monitor used for top-k checkpoint
selection. They are not the three-seed test results reported in the paper.
Containers is a separate low-data experiment; `ODAV4-S42` is released because
it is the checkpoint referenced by the original in-domain, OOD, and video
evaluation scripts.

## Download and evaluate

From the code repository, download one category plus release manifests:

```bash
python reproduce.py download --category windows
python reproduce.py smoke --category windows --device cuda
```

With the separate raw evaluation meshes, trajectories, and fixed splits:

```bash
python reproduce.py evaluate \
  --category windows \
  --eval-root /absolute/path/to/evaluation-data \
  --episodes 0
```

Replace `windows` with `cuboids`, `shelves`, or `containers`. Numeric evaluation
is metrics-only by default. The train-ready dataset is train-only and cannot be
used as the evaluation root.

To reproduce one selected project-page visualization with the exact raw tensor
variant, use the tagged `inference-v1` code release. It replays the archived
`GT_Cond -> Pred_Cond` RNG order and reports the prediction-conditioned result:

```bash
python reproduce.py download \
  --category windows \
  --weight-variant raw \
  --models-only

python reproduce.py inference \
  --category windows \
  --eval-root /absolute/path/to/raw-evaluation-data \
  --save-artifacts
```

The full checkpoint/config/test-index matrix and SHA-256 regression hashes are
in the code repository's `docs/INFERENCE.md` and
`configs/inference/seed42_selected_episodes.json`.

## Format and integrity

- Root `<category>/model.safetensors` files contain complete EMA policy states.
- `raw/<category>/model.safetensors` files contain the complete raw policy
  states used by the archived selected-visualization tests.
- Both variants include the action and point-cloud normalizer tensors.
- Optimizer state, full Python/Dill training checkpoints, W&B metadata, and
  machine-local paths are intentionally excluded.
- `metrics.json` records the source run, epoch, step, selection metric, source
  checkpoint digest, release digest, and exact tensor-roundtrip validation.
- `manifest.json` and `SHA256SUMS` provide repository-wide integrity metadata.

The original training checkpoints must be treated as trusted pickle files. All
files in this repository use tensor-only safetensors; users never need to load
the source `.ckpt` files.

## Intended use and limitations

These checkpoints generate ordered 6-DoF coverage-trajectory chunks from a
5,120-point observation and recent execution history. They are research
artifacts evaluated on the corresponding geometry categories; they are not a
certified motion-planning or robot-safety system. Validate collision handling,
kinematic feasibility, workcell constraints, and emergency behavior before any
physical deployment.

Only the selected seed-42 checkpoint is currently released for each category.
The paper's three-seed mean and standard deviation cannot be regenerated until
the other checkpoints or their per-seed result JSON files are published.

## License

No standalone repository or model-weight license has been selected yet.
Third-party components remain subject to their original terms; see the notices
in the code repository.

## Citation

```bibtex
@misc{chen2026_3dcovdiffusion,
  title  = {{3D-CovDiffusion}: 3D-Aware Diffusion Policy for Coverage Path Planning},
  author = {Chen, Chenyuan and Ding, Haoran and Ding, Ran and Liu, Tianyu
            and He, Zewen and Duan, Anqing and Nakamura, Yoshihiko},
  year   = {2026},
  note   = {Manuscript}
}
```