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、類似性ヒートマップ、セマンティックセグメンテーション、バッチ転送、ビデオから点群へのデモ。
2 つのインストールモード – 高速デモ実行用のスタンドアロン 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 パッケージも提供します。