README.md

---
license: mit
library_name: pytorch
tags:
  - semantic-scene-completion
  - lidar
  - semantickitti
  - diffusion
  - autonomous-driving
  - 3d
---

# GSSC-S2D2 — released checkpoints

Pretrained weights for **S²D² (Structured Source Discrete Diffusion)** and the
PS³ pyramid generator, as released with the paper *Generative Semantic Scene
Completion*. Code, configs, docs and every reproduction command live in the
GitHub repository:

**➡ https://github.com/BillyChern/GSSC-S2D2**

> **Non-commercial.** Although our own contribution is MIT-licensed, every
> checkpoint here was trained on **SemanticKITTI**, which is distributed under
> **CC BY-NC-SA 4.0**. Downstream use of these weights therefore inherits that
> dataset's non-commercial, share-alike and attribution terms. The MIT grant
> does not by itself authorise commercial use. See `LICENSE` in this repo.

## What is in here

18 checkpoint directories, 52 files, **4.91 GB (4.58 GiB)**. Each directory
ships `config.json` (training config, `best_miou`, `global_step`,
`source_sha256`, paper cross-reference), `model.safetensors` (training
weights) and, where the run used EMA, `model_ema.safetensors` (deployment
weights — the paper convention and the default for the inference scripts).
One directory, `bev/bev_s2d2_scpnet/`, additionally ships the pre-conversion
`model.pt`; prefer the `.safetensors` (see *Verify before you load*).

| Directory | What it is |
|---|---|
| `gssc_mf/gssc_31k_mf_step40000/` | **Headline** S²D² model on the frozen SCPNet base |
| `gssc_mf/gssc_57k_mf_step40000/` | Internal 57K multi-frame negative result (in no paper table) |
| `gssc_sf/gssc_{0,10,20,31,57}K_sf_step*/` | Single-frame data-scaling companion sweep |
| `gssc_js3c/gssc_js3c_s2d2_real/` | Cross-base row: JS3C-Net + S²D² |
| `gssc_lmsc/gssc_lmsc_s2d2_real/` | Cross-base row: LMSCNet + S²D² |
| `gssc_timesteps/gssc_{T10,T50,T100skewed}/` | Timestep-schedule ablation (supplement prose, no table) |
| `pyramid/pyramid_s{1,2,3}/` | PS³ pyramid generator stages (32×32×4 → 64×64×8 → 256×256×32) |
| `bev/bev_s2d2_scpnet/` | The BEV secondary-task model |
| `bev/bev_perception_net/` | A 938K-param refinement net. **NOT** the paper's BEV row, and it does not load in the BEV evaluator |
| `bev/bev_direct_l3_deeper/` | Internal BEV-architecture ablation, not tabulated |
| `scpnet_v2_port.pth` | Third-party SCPNet base weights (see licence below) |
| `MANIFEST.txt` | Generated cross-reference: directory → paper label, size, provenance |
| `checksums.txt` | Generated SHA256 of every other file in this repo |

**`MANIFEST.txt` is the authority** on which checkpoint backs which paper
claim, and under which evaluation protocol. It is generated from disk and
from each `config.json`, so it cannot drift from what is actually here. Read
it before quoting any number from these weights — several of them are
internal diagnostics that the paper deliberately does not print, and one
directory (`bev/bev_perception_net/`) has previously been mis-cited as the
paper's BEV model.

Headline result for orientation only: `gssc_mf/gssc_31k_mf_step40000`
reaches **38.54 % val mIoU** on SemanticKITTI sequence 08 (N=1, no TTA,
official `semantic-kitti-api`). The cross-base rows lift their frozen bases
by **+1.6 pp** (JS3C-Net) and **+1.8 pp** (LMSCNet) under the same evaluator.
Full per-row numbers, protocols and commands are in
[`docs/MODEL_ZOO.md`](https://github.com/BillyChern/GSSC-S2D2/blob/main/docs/MODEL_ZOO.md).

## Download

The supported route is the downloader in the code repository, which places
everything where the configs expect it (`data/checkpoints/`):

```bash
git clone https://github.com/BillyChern/GSSC-S2D2
cd GSSC-S2D2
python scripts/download_assets.py --checkpoints      # ~4.9 GB
```

Or directly:

```python
from huggingface_hub import snapshot_download
snapshot_download("Stone-Chern/GSSC-S2D2-checkpoints",
                  repo_type="model", local_dir="data/checkpoints")
```

## Verify before you load

```bash
cd data/checkpoints && sha256sum -c checksums.txt
```

Paths inside `checksums.txt` are relative to that directory, so run it from
**inside** `data/checkpoints/`, not from its parent. Every line must print
`OK` and the command must exit 0.

This matters more than usual here. Of the 52 files, 30 are `.safetensors` -- a
format that cannot carry an executable payload -- but **two are pickles**:
the third-party `scpnet_v2_port.pth`, and `bev/bev_s2d2_scpnet/model.pt` (the
pre-conversion copy of that checkpoint's weights; the `.safetensors` beside it
is the one the evaluator command uses). GSSC-S2D2 loads `.pt` / `.pth`
checkpoints with `torch.load(..., weights_only=False)`, because the saved
state carries optimizer and EMA buffers that `weights_only=True` cannot
represent, so loading a tampered one is equivalent to running
attacker-supplied code. For `scpnet_v2_port.pth` that loader is
`src/gssc/inference/run_scpnet.py`, which `scripts/eval_semanticposs.py`
drives with `--checkpoint data/checkpoints/scpnet_v2_port.pth`. A `FAILED` or
`FAILED open or read` line means **do not load that file**. See
[`SECURITY.md`](https://github.com/BillyChern/GSSC-S2D2/blob/main/SECURITY.md).

## Paper

Generative Semantic Scene Completion — https://arxiv.org/abs/2608.26737

## Related repositories

* **Code** — https://github.com/BillyChern/GSSC-S2D2
* **Datasets** (base-model predictions + rare-class object bank) —
  [`Stone-Chern/GSSC-S2D2-datasets`](https://huggingface.co/datasets/Stone-Chern/GSSC-S2D2-datasets)
* **Synthetic pool** — cite
  [doi:10.21227/nqgf-9k39](https://dx.doi.org/10.21227/nqgf-9k39) (IEEE
  DataPort; downloading from there needs an IEEE DataPort subscription),
  download from either that record or the free mirror
  [`Stone-Chern/PS3-SemanticKITTI`](https://huggingface.co/datasets/Stone-Chern/PS3-SemanticKITTI),
  which holds the identical archives. `docs/DATASET.md` also documents a local
  rebuild. The pyramid generator checkpoints in this repo are what that rebuild
  runs.

## Licence

* **Our contribution** (the trained weights, manifests and this card): **MIT**
  — see the `LICENSE` file in this repository.
* **Upstream data**: all weights were trained on **SemanticKITTI**
  ([CC BY-NC-SA 4.0](https://semantic-kitti.org/dataset.html)) — non-commercial,
  share-alike, attribution required. Credit SemanticKITTI and KITTI when you
  use these weights.
* **`scpnet_v2_port.pth`**: third-party **SCPNet** (Xia et al., CVPR 2023)
  pretrained weights, carried unmodified -- the "port" in the name is
  spconv-2.3 kernel-shape patching applied at load time, not a modified file. SCPNet publishes no upstream licence; this
  file is redistributed with the SCPNet authors' explicit permission and with
  attribution to them. No licence is asserted on their behalf.

The full notice list is in `LICENSE` here, and in
[`THIRD_PARTY_NOTICES.md`](https://github.com/BillyChern/GSSC-S2D2/blob/main/THIRD_PARTY_NOTICES.md)
in the code repository.

## Citation

```bibtex
@unpublished{chen2026gssc,
  title   = {Generative Semantic Scene Completion},
  author  = {Chen, Shi and Ge, Weifeng},
  note    = {Under review},
  year    = {2026}
}
```

Please also cite [SemanticKITTI](https://semantic-kitti.org/) as the source
dataset, and the relevant base model (SCPNet, JS3C-Net or LMSCNet) when using
a cross-base checkpoint.