Pointcept/Utonia

[ICML'26] Official repository of Utonia: Toward One Encoder for All Point Clouds

📦 项目：Utonia – 适用于所有点云的一个编码器

TL;DR – Utonia 为 3D 点云任务提供跨领域、预训练的 Point Transformer V3 模型。它提供即用型权重（tiny、small、full）、推理代码和一系列可视化演示。该仓库可以作为快速入门环境安装，也可以作为 Python 包安装，以便将编码器嵌入到您自己的流程中。

🎯 它是什么？

领域： 3D 点云表示学习（自监督预训练、下游推理）。
核心思想： 一个单一的编码器 – Point Transformer V3 – 在多个 3D 数据集上训练，旨在无需针对特定任务进行微调即可在室内、室外和物体级点云上表现良好。
输出： 分层点特征，可以可视化、馈送到下游头（例如，分割）或导出用于下游任务。

✨ 亮点（来自 README）

预训练权重（tiny、small、full）托管在 Hugging Face 上（2026 年 10 月）。
演示套件 重现了 Sonata 和 Concerto 论文中的可视化 – PCA、相似性热图、语义分割、批量转发、视频到点云演示。
两种安装模式 – 独立 Conda 环境（包括 CUDA 12.4、PyTorch 2.5、FlashAttention）用于快速演示运行，以及包模式用于集成到其他代码库。
Docker 镜像 适用于 RTX 4090 级硬件（CUDA 12.8），由社区提供。

🛠️ 安装

1️⃣ 独立（快速演示）

conda env create -f environment.yml   # 创建包含 CUDA 12.4、PyTorch 2.5、FlashAttention 的 "utonia" 环境
conda activate utonia

（如果您已经安装了 CUDA，请先执行 unset CUDA_PATH。）

2️⃣ 包模式（嵌入到您的项目中）

# 先决条件：已安装匹配的 CUDA 和 PyTorch 版本
pip install spconv-cu${CUDA_VERSION}
pip install torch-scatter -f https://data.pyg.org/whl/torch-${TORCH_VERSION}+cu${CUDA_VERSION}.html
pip install git+https://github.com/Dao-AILab/flash-attention.git
pip install huggingface_hub timm
python setup.py install   # 可选 – 将 utonia 包复制到您的 site-packages 中

演示脚本的额外运行时依赖项：

pip install open3d fast_pytorch_kmeans psutil addict scipy camtools natsort opencv-python trimesh gradio numpy==1.26.4

（Open3D 目前需要 NumPy 1.x。）

🚀 快速入门（演示和推理）

可视化演示

export PYTHONPATH=./
python demo/0_pca_indoor.py            # 室内扫描的 PCA
python demo/1_similarity.py           # 相似性热图
python demo/2_sem_seg.py              # ScanNet 上的线性探针分割（仅完整编码器）
python demo/3_batch_forward.py         # 批量处理示例
python demo/4_pca_hk.py                # HK 数据集的 PCA
python demo/5_pca_manipulation.py     # 交互式操作演示
python demo/6_pca_object.py           # 物体级 PCA
python demo/7_pca_outdoor.py           # 室外场景 PCA

使用 --model utonia_small 或 --model utonia_tiny 切换编码器大小（大多数演示支持，ScanNet 头除外）。

视频到点云演示（需要 VGGT）

git clone https://github.com/facebookresearch/vggt.git && cd vggt && pip install -e . && cd ..
python demo/8_pca_video.py \
  --input_video YOUR_VIDEO.mp4 \
  --conf_thres 0 \
  --prediction_mode "Depthmap and Camera Branch" \
  --if_TSDF \
  --pca_start 1 \
  --pca_brightness 1.2

对您自己的数据进行推理

import utonia, torch, numpy as np

# 1️⃣ 准备一个符合预期模式的字典
point = {
    "coord": np.random.rand(10000, 3).astype(np.float32),   # XYZ
    "color": np.random.rand(10000, 3).astype(np.float32),   # RGB（可选）
    "normal": np.random.rand(10000, 3).astype(np.float32),  # 法线（可选）
}

# 2️⃣ 构建变换流程（与预训练模型使用的相同）
transform = utonia.transform.default(scale=1.0, apply_z_positive=True, normalize_coord=False)
point = transform(point)

# 3️⃣ 将张量移动到 GPU
for k, v in point.items():
    if isinstance(v, torch.Tensor):
        point[k] = v.cuda(non_blocking=True)

# 4️⃣ 加载编码器（full、small 或 tiny）
model = utonia.model.load("utonia", repo_id="Pointcept/Utonia").cuda()
# model = utonia.model.load("utonia_small").cuda()   # 替代方案

# 5️⃣ 前向传播 – 输出是分层点特征字典
out = model(point)

# 6️⃣ （可选）将分层特征折叠回原始点数
for _ in range(2):
    parent = out.pop("pooling_parent")
    inv = out.pop("pooling_inverse")
    parent.feat = torch.cat([parent.feat, out.feat[inv]], dim=-1)
    out = parent
while "pooling_parent" in out:
    parent = out.pop("pooling_parent")
    inv = out.pop("pooling_inverse")
    parent.feat = out.feat[inv]
    out = parent
feat_original = out.feat[out.inverse]   # (N, C) 与输入点云对齐

生成的 feat_original 可以馈送到下游头（例如，线性分类器）或使用提供的演示脚本进行可视化。

📄 许可证

代码： Apache 2.0（继承自 Meta 的 Sonata 代码）。
预训练权重： CC-BY-NC 4.0（仅限非商业用途，由于数据集限制，如 HM3D、ARKitScenes）。

📚 引用

如果您在研究中使用 Utonia，请引用 ICML 2026 论文：

@inproceedings{zhang2026utonia,
  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},
  booktitle={International Conference on Machine Learning (ICML)},
  year={2026}
}

底层 Point Transformer V3、Sonata、Concerto 和相关工作的其他参考资料列在 README 中以供参考。

底线： Utonia 为您提供即用型、高性能的 3D 点云编码器，带有预训练权重和一系列视觉演示，以及一个用于集成到自定义流程中的简洁 Python 包。