Upload README.md with huggingface_hub

README.md

@@ -0,0 +1,82 @@
+---
+license: cc-by-nc-4.0
+library_name: mlx
+pipeline_tag: graph-ml
+tags:
+- mlx
+- mlx-swift
+- 3d
+- point-cloud
+- self-supervised-learning
+- point-transformer-v3
+base_model: Pointcept/Utonia
+---
+
+# Utonia — MLX (safetensors) weights for Apple Silicon
+
+MLX-converted weights for **[Utonia](https://huggingface.co/Pointcept/Utonia)** (*Utonia: Toward One Encoder for All Point Clouds*, [arXiv:2603.03283](https://arxiv.org/abs/2603.03283)) — a Point Transformer V3 (mode-3) encoder pretrained across indoor RGB-D, outdoor LiDAR, remote sensing, object CAD, and video-lifted point clouds.
+
+These weights power **[mlx-swift-utonia](https://github.com/mnmly/mlx-swift-utonia)**, a numerically verified Swift/[mlx-swift](https://github.com/ml-explore/mlx-swift) port that runs Utonia natively on Apple Silicon (macOS): full-resolution multi-million-point clouds, ScanNet-20 semantic segmentation, and PCA feature visualization.
+
+## Files
+
+| File | Contents |
+| --- | --- |
+| `utonia.safetensors` | Encoder weights (137,253,816 params, float32) — converted from `utonia.pth` |
+| `utonia_config.json` | Model config extracted from the checkpoint (`enc_channels=(54,108,216,432,576)`, `enc_depths=(3,3,3,12,3)`, `enc_num_head=(3,6,12,24,32)`, 3D RoPE, 4 serialization curves) |
+| `utonia_seg_head_sc.safetensors` | ScanNet-20 linear-probe segmentation head (`Linear(1386→20)`) — converted from `utonia_linear_prob_head_sc.pth` |
+| `utonia_seg_head_sc_config.json` | Seg-head config |
+| `*_manifest.txt` | Tensor name/shape manifests for both checkpoints |
+
+## Changes from the original
+
+Converted from the PyTorch checkpoints in [Pointcept/Utonia](https://huggingface.co/Pointcept/Utonia) (no retraining, no fine-tuning — the numbers are byte-identical modulo the format changes below):
+
+- `.pth` (pickled state dict) → `.safetensors`, float32.
+- Config dict extracted from the checkpoint into a standalone JSON.
+- Tensor **values are unchanged**; the Swift loader transposes the spconv `SubMConv3d` kernels from `(C_out, k, k, k, C_in)` to `(k, k, k, C_in, C_out)` at load time.
+
+Numerical parity of the Swift port against the reference PyTorch implementation: bit-exact serialization, encoder relative error 0.27 % (fp32 GPU drift), 99.87 % semantic-segmentation argmax agreement.
+
+## Usage (mlx-swift)
+
+```swift
+import Utonia
+
+let session = try UtoniaSession.load(SessionConfig(weightsDir: weightsDirURL))
+let result = session.run(RawCloud(coord: coords, color: colors, normal: normals))
+```
+
+Or via the CLI from [mlx-swift-utonia](https://github.com/mnmly/mlx-swift-utonia):
+
+```sh
+utonia-cli semseg --weights-dir weights --input scene/ --output segmented.ply
+utonia-cli pca    --weights-dir weights --input scene/ --output features.ply
+```
+
+## License
+
+**CC-BY-NC-4.0**, inherited from the original [Pointcept/Utonia](https://huggingface.co/Pointcept/Utonia) weights — **non-commercial use only**. The mlx-swift-utonia *code* is licensed separately (see its repository); this restriction applies to the weights.
+
+All credit for the model belongs to the Utonia authors (Pointcept / The University of Hong Kong and collaborators).
+
+## Citation
+
+```bibtex
+@misc{zhang2026utoniaencoderpointclouds,
+      title={Utonia: Toward One Encoder for All Point Clouds},
+      author={Yujia Zhang and Xiaoyang Wu and Yunhan Yang and Xianzhe Fan and Han Li and Yuechen Zhang and Zehao Huang and Naiyan Wang and Hengshuang Zhao},
+      year={2026},
+      eprint={2603.03283},
+      archivePrefix={arXiv},
+      primaryClass={cs.CV},
+      url={https://arxiv.org/abs/2603.03283},
+}
+
+@misc{pointcept2023,
+    title={Pointcept: A Codebase for Point Cloud Perception Research},
+    author={Pointcept Contributors},
+    howpublished = {\url{https://github.com/Pointcept/Pointcept}},
+    year={2023}
+}
+```