3分钟装好Utonia点云预训练编码器：conda独立模式与pip包模式完整安装指南-育师

【免费下载链接】Utonia

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

项目地址：https://gitcode.com/gh_mirrors/ut/Utonia

Utonia 是一个基于 Point Transformer V3 的跨域点云预训练编码器（ICML 2026），一个模型即可用于室内场景、室外 LiDAR、物体操作等场景的 3D 点云理解。本文带你用3 分钟完成 Utonia 官方的conda 独立模式与pip 包模式两种安装方式，并跑通可视化 demo 完成验证，照着做即可。🚀

Utonia 是什么：一个编码器搞定所有点云

Utonia 来自论文Utonia: Toward One Encoder for All Point Clouds，核心思路是用多数据集、多领域联合预训练出一个通用的 PTv3 编码器，输出的点特征可直接用于分割、相似度计算等下游任务。本仓库聚焦预训练权重 + 推理代码 + 可视化 demo，代码结构非常轻量：

目录 / 文件	作用
utonia/model.py	PTv3 模型定义与权重加载入口`utonia.load`
utonia/data.py	示例点云数据加载（sample1 等样例）
utonia/transform.py	默认数据预处理流水线
demo/	9 个开箱即用的可视化 demo（PCA、相似度、语义分割等）
environment.yml	conda 独立模式的一键环境文件
setup.py	pip 包模式安装脚本

💡 若想复现 Utonia 的预训练过程，请参考 Pointcept 代码库；本仓库面向推理与可视化用户。

选型指南：conda 独立模式 vs pip 包模式怎么选

对比项	conda 独立模式	pip 包模式
适合人群	快速推理、跑 demo 可视化	把 Utonia 编码器接入自己的项目
环境要求	零基础，一条命令搞定 CUDA + PyTorch	本地需已装好 CUDA 和 PyTorch
官方推荐	⭐ 首选	备选
灵活度	独立环境互不干扰	版本与现有工程完全融合

方式一：conda 独立模式（推荐，最快）

项目提供了 environment.yml 环境文件，预配置了Python 3.10 + CUDA 12.4 + PyTorch 2.5.0，并内置了spconv、torch-scatter、flash-attn三个 GPU 依赖。

1️⃣ 克隆代码

git clone https://gitcode.com/gh_mirrors/ut/Utonia cd Utonia

2️⃣ 一条命令创建环境

# 若本地系统已装 CUDA，先执行下面这行避免版本冲突 unset CUDA_PATH # 创建名为 utonia 的 conda 环境并激活 conda env create -f environment.yml --verbose conda activate utonia

✅关键点：环境文件里已通过pytorch-cuda=12.4通道装好 CUDA 与 PyTorch，无需单独下载。

3️⃣ 验证 FlashAttention 是否就绪

python -c "import flash_attn; print('FlashAttention OK')"

方式二：pip 包模式（接入自己的项目）

适合希望在自有代码库中import utonia的用户，前提是本地已安装 CUDA 和 PyTorch。

1️⃣ 安装 GPU 相关依赖（版本需与本机匹配）

# 先查看本机版本 nvcc --version # CUDA 版本，如 12.4 → 124 python -c "import torch; print(torch.__version__)" # PyTorch 版本，如 2.5.0 # 安装点云计算三件套（注意选择匹配的构建） pip install spconv-cu124 # 124 = CUDA 主+次版本，按本机修改 pip install torch-scatter # 需选与本机 PyTorch 匹配的 wheel 构建 pip install flash-attn # 选与本机环境匹配的预编译 wheel

2️⃣ 安装其余依赖与 Utonia 包

pip install huggingface_hub timm # 在 Utonia 仓库根目录执行 python setup.py install

torch-scatter / flash-attn 的版本匹配细节，可参考 README.md 的 Installation 一节；另外 setup.py 安装与直接把 utonia/ 目录拷进项目两种方式等效。

3️⃣ （可选）安装 demo 可视化依赖

若还想运行 demo/ 里的演示脚本，再补装：

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

⚠️open3d暂不支持 numpy 2.x，务必固定numpy==1.26.4。

安装验证：跑通第一个点云可视化 demo

装完后最直观的验证方式是运行官方 PCA 可视化 demo：

export PYTHONPATH=./ python demo/0_pca_indoor.py

首次运行会自动完成两件事：

utonia.model.load（utonia/model.py）从 HuggingFace 下载预训练权重，缓存在~/.cache/utonia/ckpt，可通过download_root参数自定义缓存路径；
utonia.data.load("sample1")（utonia/data.py）下载官方室内样例点云到~/.cache/utonia/data；

随后会弹出 3D 窗口，展示 PCA 着色后的点云特征分布。能看到彩色点云，就说明 Utonia 安装成功！✅

其余 demo（相似度热图、ScanNet 语义分割、室外/操作/视频点云等）都在 demo/ 目录，替换文件名即可运行：

python demo/2_sem_seg.py # ScanNet 线性探测分割 python demo/1_similarity.py # 相似度热图

💡 如果环境始终装不好，社区还提供了现成的 Docker 镜像（如utonia-cuda128），可参考 README.md 中的说明。

常见安装避坑指南

现象	原因与解决办法
`conda env create`报 CUDA 冲突	本地 CUDA 干扰了环境，先`unset CUDA_PATH`再重建
`import flash_attn`失败	装了对应环境的预编译 wheel 重试；即使缺失，demo 也会自动降级为非 Flash 路径（见 demo/0_pca_indoor.py），可正常跑但更慢
`spconv`安装失败	`spconv-cu124`只匹配 CUDA 12.4，按`nvcc --version`结果选对应构建
`open3d`导入报错	numpy 2.x 不兼容，执行`pip install "numpy==1.26.4"`

最后提醒一点授权：Utonia 代码基于 Apache 2.0 许可（LICENSE），而预训练权重采用 CC-BY-NC 4.0 许可（限非商业用途），商用前请自行确认合规。

总结：3 步速查清单

快速上手：conda env create -f environment.yml→conda activate utonia→python demo/0_pca_indoor.py验证；
接入项目：装好 4 个 GPU/Python 依赖 →python setup.py install；
仍有问题：对照上文避坑表，或查阅 README.md 官方安装说明。

至此你就拥有了一个可跨域工作的点云预训练编码器 Utonia。下一步可以进入 README.md 的 Quick Start 一节，学习把特征映射回原始点云，并用它对你自己的点云数据做推理。