README.md

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

# 3D-CovDiffusion checkpoints

Category-specific tensor-only 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
- Dataset: https://huggingface.co/datasets/ChenyuanC/3D-CovDiffusion-Train-Ready

## Released variants

Each root category contains the EMA policy selected by its original seed-42
run. `raw/<category>/` contains the non-EMA `state_dicts.model` export used by
the archived selected-visualization script. Here **raw means policy weights
before EMA**, not raw dataset input or a Python/pickle checkpoint.

Every directory contains `model.safetensors`, `config.yaml`, and provenance
metadata.

| Directory | Dataset | Training run | Historical 6-D selection score ↓ |
|:--|:--|:--|--:|
| `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 |

The score above is the run's prediction-conditioned weighted 6-D pose Chamfer
used for top-k selection. It includes XYZ and orientation normal and is **not**
the final XYZ-only PCD or the paper's three-seed test result.

| Selected case | Non-EMA 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` |

Containers is a separate low-data experiment. `ODAV4-S42` is released because
it is referenced by the archived in-domain, OOD, and video evaluation scripts.

## Evaluate

From the code repository:

```bash
bash scripts/create_locked_environment.sh 3dcov-cu117
source "$(conda info --base)/etc/profile.d/conda.sh"
conda activate 3dcov-cu117
export PYTHONNOUSERSITE=1
python reproduce.py prepare windows
python reproduce.py evaluate windows
```

`prepare` obtains the model, processed/canonical Hugging Face data, and the raw
Zenodo mesh/trajectory/split records below one `--artifact-root`. The canonical
cache locks the exact preprocessed model input; the raw records remain necessary
for rollout geometry, ground truth, and metrics.

Use `evaluate all` for every released EMA policy. To replay the selected
non-EMA case and automatically verify its numeric result:

```bash
python reproduce.py infer windows
```

Rendering is optional:

```bash
python -m pip install --no-build-isolation --require-hashes \
  -r requirements/requirements-visualization-linux-py310-cu117.lock.txt
python reproduce.py infer windows --render
```

The PLY hash is a locked-environment render regression, not a requirement for
numeric reproduction. The full checkpoint/config/test-index matrix and hashes
are in `docs/INFERENCE.md` and
`configs/inference/seed42_selected_episodes.json` in the code repository.

## Format and integrity

- `<category>/model.safetensors` contains the complete EMA policy state.
- `raw/<category>/model.safetensors` contains the complete non-EMA policy state
  used for the selected-case replay.
- Both include action and point-cloud normalizer tensors.
- Optimizer state, Python/Dill training checkpoints, experiment logs, and
  machine-local paths are excluded.
- `metrics.json` records source run, epoch/step, historical selection score,
  source digest, release digest, and tensor-roundtrip validation.
- `manifest.json` and `SHA256SUMS` provide repository-wide integrity metadata.

Users never need to load the trusted historical pickle checkpoints; all public
weights are safetensors.

## Intended use and limitations

The policies generate ordered 6-DoF coverage-trajectory chunks from a
5,120-point observation and the previous 24-D action token (four ordered 6-DoF
poses). They are research artifacts, not a certified motion-planning or robot-
safety system. Validate collisions, kinematics, workcell constraints, and
emergency behavior before physical deployment.

Only one selected seed-42 checkpoint is public per category. The paper's
three-seed mean and standard deviation require the independent seed-123/456
checkpoints or their result JSON files.

## License

To the extent the 3D-CovDiffusion authors hold the necessary rights, the
released EMA and non-EMA model weights are licensed under
[CC BY 4.0](https://creativecommons.org/licenses/by/4.0/legalcode). The grant
covers model-weight files only; source code, datasets, the paper, website media,
and third-party materials retain their separate terms. See
[`MODEL_LICENSE.md`](https://github.com/crystalccy1/3D-CovDiffusion/blob/main/MODEL_LICENSE.md)
and the repository's third-party notices.

## 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   = {Accepted at IROS 2026}
}
```