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 패키지도 제공합니다.