naver/must3r

MUSt3R – 스테레오 3D 재구성용 멀티뷰 네트워크

무엇인가요 – MUSt3R은 MUSt3R 모델을 구현하는 연구용 Python 라이브러리입니다. 이는 여러 이미지에서 밀도 높은 3D 기하를 재구성하는 멀티뷰 신경망입니다. 이전의 DUSt3R 아키텍처를 기반으로 하며, 대칭 처리, 다층 메모리, 온라인 카메라 자세 추정을 추가하여 순서 없는 이미지 세트, 비디오 스트림, 또는 실시간 웹캠 입력을 처리할 수 있도록 합니다.

주요 기능

• 임의의 수의 시점(순서 있음/없음)에서 스테레오 스타일 3D 재구성.
• 온라인 자세 및 구조 추정 – 모델은 3D 지도를 구축하면서 카메라 자세를 예측하여 SLAM과 유사한 동작을 가능하게 합니다.
• 메모리 메커니즘 – 학습 가능한 토큰 메모리가 중간 기하를 저장하여 과거 프레임을 개선하고, 순서 없는 컬렉션의 경우 관련 키프레임을 검색할 수 있습니다.
• 두 가지 모델 크기 – 빠른 프로토타이핑을 위한 224픽셀 버전(ViT-L 인코더, ViT-B 디코더)과 더 높은 품질 결과를 위한 512픽셀 버전.
• 검색 모드 – 입력 순서가 불분명할 때 일치하는 키프레임을 찾기 위해 가벼운 "학습 없음" 인코더 + 코드북을 사용할 수 있습니다.

설치 방법

1. 환경 생성 (Python 3.11, CMake ≥ 3.14). README는 micromamba를 권장하지만, conda/virtualenv는 모두 가능합니다.
2. PyTorch 설치 (2.7.0) – GPU에 맞는 CUDA 빌드를 사용하세요.
3. 선택 사항이지만 권장: 메모리 효율적인 어텐션을 위해 xformers 설치.
4. 리포지토리에서 직접 패키지 설치:

   pip install must3r@git+https://github.com/naver/must3r.git
   # pillow-heif, curope 등 추가 기능을 [optional] extras로 지정 가능
   

5. 개발용으로는 리포지토리 클론, 서브모듈 설치, 보조 asmk 및 선택적 RoPE CUDA 커널(curope) 빌드 가능.

사전 학습된 체크포인트

모델	해상도	인코더	디코더	다운로드
MUSt3R_224_cvpr.pth	224×224	ViT‑L	ViT‑B	링크
MUSt3R_512_cvpr.pth	512×384 … 512×160	ViT‑L	ViT‑B	링크
MUSt3R_512.pth (피니튜닝됨)	위와 동일	ViT‑L	ViT‑B	링크

순서 없는 이미지 모드용으로 리트리벌 전용 가중치(*_retrieval_trainingfree.pth)와 코드북(*_retrieval_codebook.pkl)도 제공됩니다.

데모 인터페이스

• Gradio + viser (오프라인) – python demo.py … (또는 설치된 must3r_demo 엔트리포인트) 실행. 이미지는 Gradio UI를 통해 업로드되며, 3D 재구성 결과는 실시간으로 viser 웹 뷰어에 스트리밍됩니다. 해상도, 미스드 프리시전(--amp bf16|fp16), 로컬 네트워크 노출 여부 등을 선택할 수 있습니다.
• 라이브 비주얼 오도메트리 (온라인) 데모 – python slam.py … (설치된 must3r_slam). 웹캠, 비디오 파일, 또는 프레임 폴더와 함께 작동합니다. 키프레임 선택, 자세 추적, Open3D로 시각화된 3D 포인트 클라우드를 표시합니다. 메모리 갱신, 키프레임 간격, 초점 길이 추정, GPU 가속 RoPE 커널 등 고급 플래그로 제어 가능.

학습 리포지토리에는 완전한 학습 파이프라인(train.py, eval.py)이 포함되어 있습니다. 학습은 5개의 이미지 블록을 인과적 어텐션 마스크로 처리하는 causal 버전의 모델(CausalMUSt3R)을 사용하여 그래디언트 계산을 가속화합니다. README에는 중요한 하이퍼파라미터(메모리 크기, 드롭아웃 모드, 미스드 프리시전, 시점 수 등)가 나와 있으며, 멀티 GPU 학습을 위한 torchrun 명령어 샘플도 제공됩니다.

라이선스 MUSt3R은 비영리 라이선스 하에 배포됩니다. 리포지토리의 LICENSE 외에도 NOTICE 파일은 학습 데이터셋(예: "mapfree" 데이터셋)의 제한된 라이선스를 상세히 설명합니다. 제공된 체크포인트를 사용하려면 MUSt3R 라이선스와 데이터셋 라이선스 모두에 동의해야 합니다.

누가 사용할 수 있나요

• 신경망 기반 SLAM, 멀티뷰 기하학, 또는 밀도 높은 재구성에 관심 있는 연구자.
• 휴대용 카메라에서 실시간 3D 매핑이 필요한 AR/VR 파이프라인을 개발하는 개발자.
• 순서 있는 비디오 스트림과 순서 없는 사진 컬렉션 모두를 처리할 수 있는 즉시 사용 가능한 스테레오 재구성 데모가 필요한 사람.

---

위 정보는 리포지토리의 README에서 직접 인용되었으며, 추가 기능은 추측되지 않았습니다.