Upload README.md with huggingface_hub

README.md

@@ -0,0 +1,94 @@
+---
+license: apache-2.0
+tags:
+  - 3d-occupancy-prediction
+  - autonomous-driving
+  - self-supervised
+  - nuscenes
+library_name: pytorch
+---
+
+# QueryOcc: Query-based Self-Supervision for 3D Semantic Occupancy
+
+Weights for [QueryOcc](https://arxiv.org/abs/2511.17221) (Lilja, Lan, Fu, Hammarstrand).
+Code: [github.com/LiljaAdam/queryocc](https://github.com/LiljaAdam/queryocc).
+
+QueryOcc learns continuous 3D semantic occupancy from multi-view camera images by supervising
+directly in 4D space-time: positive and negative queries are sampled along rays from point
+clouds observed in adjacent frames — no rendering losses, no voxelized lidar aggregation. No
+human annotation is used at any stage. This checkpoint is the **lidar-supervised** arm, where
+the supervising point clouds are real lidar sweeps with per-point pseudo-semantics.
+
+## Files
+
+| File | Preset | Supervision | Sem. RayIoU | Dyn. RayIoU | Occ. RayIoU | Sem. IoU | Occ. IoU |
+|---|---|---|---|---|---|---|---|
+| `queryocc-lidar-nusc.pth` | `queryocc-lidar-nusc` | real lidar | 23.2 | 19.5 | 48.8 | 20.4 | 56.9 |
+
+Occ3D-nuScenes validation split, self-supervised protocol. 112.1 M parameters, 449 MB.
+`sha256 561112071f8c1417b466798353dadaf5c54175b2107d25f8434839145c9d9dcc`
+
+For reference, the paper's headline camera-only model (`queryocc-nusc`, supervised by pseudo
+point clouds from a vision foundation model) reports 23.6 / 21.7 / 45.2 / 21.3 / 55.0 on the
+same columns: lidar supervision trades a little semantic accuracy for better occupancy, which
+is what its accurate depth would predict.
+
+## Usage
+
+```bash
+git clone https://github.com/LiljaAdam/queryocc && cd queryocc
+./setup_uv_env.sh && source .venv/bin/activate
+
+python queryocc/train.py queryocc-lidar-nusc --no-train --test \
+    --load_ckpt_from=hf://QueryOcc/queryocc
+```
+
+The checkpoint is downloaded and cached automatically, and records the preset it belongs to —
+loading it into a different preset is an error rather than a silent partial load. To use a
+manually downloaded file, pass its path instead.
+
+Evaluation additionally requires nuScenes, the Occ3D-nuScenes labels and a CUDA toolkit (the
+RayIoU raycaster is JIT-compiled on first use); the repository README covers the setup. Nothing
+else is needed — in particular, evaluating these weights does **not** require the gated DINOv3
+backbone checkpoint that training uses.
+
+Add `--allow_visualization --visualizer.f_viz_occ_3d_bev --visualizer.f_viz_bev_features` to log
+BEV predictions and a PCA projection of the BEV features to Weights & Biases.
+
+## Loading the weights directly
+
+The file is a plain `torch.save` payload containing only tensors and primitives, so it needs no
+trust in the publisher:
+
+```python
+import torch
+
+payload = torch.load("queryocc-lidar-nusc.pth", map_location="cpu", weights_only=True)
+payload["preset"]  # 'queryocc-lidar-nusc'
+payload["metrics"]  # the numbers in the table above
+payload["state_dict"]  # 'net.'-prefixed network weights
+```
+
+## Training data and intended use
+
+Trained on nuScenes trainval: multi-view camera images, supervised by lidar sweeps carrying
+offline per-point pseudo-semantics. Research artifact: a demonstration of self-supervised
+occupancy learning, not a validated driving component. Its outputs reflect the geometry, sensor
+suite and geographies of nuScenes (Boston and Singapore) and should not be relied on for
+safety-critical decisions. Use is subject to the
+[nuScenes terms](https://www.nuscenes.org/terms-of-use) as well as the license below.
+
+## License
+
+Apache 2.0, matching the code.
+
+## Citation
+
+```bibtex
+@article{lilja2025queryocc,
+  title={QueryOcc: Query-based Self-Supervision for 3D Semantic Occupancy},
+  author={Lilja, Adam and Lan, Ji and Fu, Junsheng and Hammarstrand, Lars},
+  journal={arXiv preprint arXiv:2511.17221},
+  year={2025}
+}
+```