Robbyant/lingbot-map

teaser.mp4

🗺️ LingBot-Map을 만나보세요! 스트리밍 3D 재구성 (3D reconstruction)을 위한 피드포워드 (feed-forward) 3D 파운데이션 모델 (foundation model)을 구축했습니다! 🏗️🌍

LingBot-Map은 다음 사항에 집중했습니다:

기하학적 컨텍스트 트랜스포머 (Geometric Context Transformer): 앵커 컨텍스트 (anchor context), 포즈 참조 윈도우 (pose-reference window), 궤적 메모리 (trajectory memory)를 통해 좌표 그라운딩 (coordinate grounding), 밀집 기하학적 단서 (dense geometric cues), 장거리 드리프트 보정 (long-range drift correction)을 단일 스트리밍 프레임워크 내에서 구조적으로 통합합니다.
고효율 스트리밍 추론 (High-Efficiency Streaming Inference): 페이지드 KV 캐시 어텐션 (paged KV cache attention)을 갖춘 피드포워드 (feed-forward) 아키텍처로, 10,000 프레임을 초과하는 긴 시퀀스에서도 518×378 해상도에서 약 20 FPS의 안정적인 추론을 가능하게 합니다.
최첨단 재구성 (State-of-the-Art Reconstruction): 기존의 스트리밍 방식 및 반복 최적화 (iterative optimization) 기반 방식 모두와 비교하여 다양한 벤치마크에서 우수한 성능을 보여줍니다.

클릭하여 확장

2026-05-25— 📊평가 벤치마크 (Evaluation benchmark) 출시. KITTI 및 Oxford Spires에 대한 평가 스크립트를 출시했습니다 — 파이프라인은 benchmark/를 참조하고, 평가 전 Oxford Spires 데이터를 준비하려면 preprocess/oxford.py를 실행하세요.

2026-04-29— 📹장기 비디오 데모 (Long-video demo) 출시. 오프라인 파이프라인으로 렌더링된 매우 긴 비디오 예시(~25,000 프레임, 13분 길이의 실내 워크스루)를 출시했습니다 — 명령어, 플래그 근거 및 렌더링된 결과물은 Worked Example을 참조하세요.

2026-04-27— 🚀LingBot-Map 가속화. 최신 main 브랜치를 풀(pull)하고, 사용자의 하드웨어에서 확인하려면 python demo.py --compile ... 또는 python gct_profile.py --backend flashinfer --dtype bf16 --compile을 실행하세요.

2026-04-24— --keyframe_interval > 1일 때 키프레임이 아닌 프레임을 조용히 캐싱하던 FlashInfer KV 캐시 버그를 수정했습니다.
이제 320 프레임 이상으로 실행할 때 더 나은 포즈 및 재구성 품질을 확인할 수 있습니다.

• ✅ 평가 벤치마크 출시

• ✅ Oxford Spires 데이터셋

• ✅ KITTI 데이터셋

• ✅ VBR 데이터셋

• ✅ Droid-W 데이터셋

• ✅ TUM-D 데이터셋

• ✅ 7-scenes 데이터셋

• ✅ ETH3D 데이터셋

• ✅ Tanks and Temples 데이터셋

• ✅ NRGBD 데이터셋

• ✅ 데모 스크립트 출시

• ✅ 실내 장기 비디오 (Long-video) 데모 (주요 실내 워크스루 기능 포함)

• ✅ 실외 장기 비디오 (Long-video) 데모

• ✅ LingBot-World 데모

• ✅ 항공 (Aerial) 장기 비디오 (Long-video) 데모

1. conda 환경 생성

conda create -n lingbot-map python=3.10 -y
conda activate lingbot-map

2. PyTorch 설치 (CUDA 12.8)

pip install torch==2.8.0 torchvision==0.23.0 --index-url https://download.pytorch.org/whl/cu128

PyTorch 2.8.0 버전을 권장합니다. 이는 NVIDIA Kaolin (배치 렌더링 파이프라인에 필요)이

torch-2.8.0_cu128

용으로 미리 빌드된 휠(wheels)을 제공하기 때문입니다. 만약 demo.py만 필요하다면 더 최신 버전의 PyTorch를 사용할 수 있지만, 이 경우 배치 렌더러(batch renderer)를 사용하기 위해 Kaolin을 소스에서 직접 빌드해야 합니다. 다른 CUDA 버전에 대해서는 PyTorch 시작하기(Get Started)를 참조하세요.

3. lingbot-map 설치

pip install -e .

4. FlashInfer 설치 (권장)

FlashInfer는 효율적인 스트리밍 추론 (streaming inference)을 위해 페이지 단위의 KV 캐시 어텐션 (paged KV cache attention)을 제공합니다. 이는 첫 사용 시 CUDA 커널을 JIT 컴파일하는 순수 Python 패키지이므로, 단일 휠(wheel)로 다양한 CUDA/PyTorch 버전에 대응할 수 있습니다:

pip install --index-url https://pypi.org/simple flashinfer-python

--index-url https://pypi.org/simple은 기본 pip 인덱스가 flashinfer-python을 포함하지 않는 내부 미러(internal mirror)인 경우에만 필요합니다. (선택 사항) 첫 사용 속도를 높이려면 CUDA 전용 JIT 캐시를 추가로 설치할 수 있습니다: pip install flashinfer-jit-cache -f https://flashinfer.ai/whl/cu128/flashinfer-jit-cache/. 자세한 내용은 FlashInfer 설치 가이드를 참조하세요. FlashInfer가 설치되지 않은 경우, 모델은 --use_sdpa를 통해 SDPA (PyTorch 네이티브 어텐션)로 대체됩니다.

5. 시각화 의존성 설치 (선택 사항)

pip install -e ".[vis]"

모델 이름	Huggingface 저장소	ModelScope 저장소	설명
lingbot-map-long	robbyant/lingbot-map	Robbyant/lingbot-map	긴 시퀀스 및 대규모 장면에 더 적합함 (권장).
...
🚧

곧 출시 예정: 더 긴 시퀀스를 지원하는 더 강력한 모델을 학습 중입니다 — 계속 지켜봐 주세요.

설치 후, 다음 명령어를 통해 첫 번째 장면을 실행하세요:

python demo.py --model_path /path/to/lingbot-map-long.pt \
--image_folder example/courthouse --mask_sky

이 명령은 http://localhost:8080에서 대화형 viser 뷰어 (interactive viser viewer)를 실행합니다.

전체 장면 세트와 플래그 (flags)에 대해서는 아래의 대화형 데모 (Interactive Demo)를 참조하거나, 긴 시퀀스의 배치 렌더링 (batch rendering)을 위해 오프라인 렌더링 파이프라인 (Offline Rendering Pipeline) 섹션으로 이동하세요.

브라우저 기반의 viser 뷰어(http://localhost:8080 기본값)를 통한 대화형 3D 시각화 (3D visualization)를 위해 demo.py를 실행하세요.

example/ 디렉토리에 즉시 실행 가능한 네 가지 예시 장면을 제공합니다:

# courthouse 장면
python demo.py --model_path /path/to/lingbot-map-long.pt \
--image_folder example/courthouse --mask_sky

output_pointcloud_side_by_side.mp4

# University 장면
python demo.py --model_path /path/to/lingbot-map-long.pt \
--image_folder example/university --mask_sky

output_pointcloud_side_by_side.mp4

# Loop 장면 (루프 폐쇄 궤적, loop closure trajectory)
python demo.py --model_path /path/to/lingbot-map-long.pt \
--image_folder example/loop

output_pointcloud_side_by_side.mp4

# 하늘 마스킹이 적용된 Oxford 장면 (실외, 대규모 장면)
python demo.py --model_path /path/to/lingbot-map-long.pt \
--image_folder example/oxford --mask_sky

output_pointcloud_side_by_side.mp4

시퀀스가 대화형 viser 뷰어에 사용하기에는 너무 깁니다 — 이 클립은 오프라인 렌더링 파이프라인 (Offline Rendering Pipeline)으로 렌더링되었습니다. 전체 명령어는 해당 섹션을 참조하세요.

추후 더 많은 예시를 제공할 예정입니다.

--keyframe_interval을 사용하여 매 N번째 프레임만 키프레임 (keyframe)으로 유지함으로써 KV 캐시 (KV cache) 메모리를 줄일 수 있습니다. 키프레임이 아닌 프레임도 예측을 생성하지만 캐시에 저장되지는 않습니다. 이는 320 프레임을 초과하는 긴 시퀀스에 유용합니다 (저희는 320개의 뷰에 대해 비디오 RoPE (video RoPE)를 사용하여 학습하므로, KV 캐시가 320개 이상의 뷰를 저장하면 성능이 저하됩니다. 키프레임 전략을 사용하면 더 긴 시퀀스에 대해 추론 (inference)이 가능합니다.).

데이터셋 (Dataset): Hugging Face의 robbyant/lingbot-map-demo에서 데모 시퀀스를 다운로드하세요.

위 데이터셋의 travel 시퀀스에 대한 실행 예시 (sky masking 적용, 4회의 카메라 최적화 반복, 2프레임마다 키프레임 생성):

python demo.py \
--image_folder /path/to/lingbot-map-demo/travel/ \
--model_path /path/to/lingbot-map-long.pt \
...

output_pointcloud_side_by_side.mp4

추론 범위 (inference range)에 관한 참고 사항. 저희 방법은 기본적으로 상태 초기화 (state resetting)를 수행하지 않으므로, 최대 추론 범위는 데이터셋 학습 과정에서 관찰된 가장 긴 거리에 의해 제한됩니다. 해당 거리를 초과하면 상태 초기화가 필요합니다. 만약 포즈 붕괴 (pose collapse) 현상이 관찰된다면, 윈도우 모드 (--mode windowed)로 전환하십시오. 대부분의 경우 --keyframe_interval을 조정하는 것만으로 충분하며, 나머지 윈도우 관련 파라미터는 기본값을 유지해도 됩니다.

python demo.py --model_path /path/to/lingbot-map-long.pt \
--video_path video.mp4 --fps 10 \
--mode windowed --window_size 128 --overlap_keyframes 16 --keyframe_interval 2

Sky masking은 ONNX 기반의 하늘 세그멘테이션 (sky segmentation) 모델을 사용하여 재구성된 포인트 클라우드 (point cloud)에서 하늘 포인트를 필터링하며, 이는 실외 장면의 시각화 품질을 향상시킵니다.

설정 (Setup):

# onnxruntime 설치 (필수)
pip install onnxruntime # CPU
# 또는
...

하늘 세그멘테이션 모델 (skyseg.onnx)은 처음 사용 시 Hugging Face에서 자동으로 다운로드됩니다.

사용법 (Usage):

python demo.py --model_path /path/to/checkpoint.pt \
--image_folder /path/to/images/ --mask_sky

Sky mask는 <image_folder>_sky_masks/에 캐시(cache)되므로, 이후 실행 시 재생성 과정을 건너뜁니다. --sky_mask_dir을 사용하여 사용자 정의 캐시 디렉토리를 지정하거나, --sky_mask_visualization_dir을 사용하여 side-by-side 마스크 시각화 결과물을 저장할 수 있습니다.

python demo.py --model_path /path/to/checkpoint.pt \
--image_folder /path/to/images/ --mask_sky \
--sky_mask_dir /path/to/cached_masks/ \
...

인자 (Argument)	기본값 (Default)	설명 (Description)
--port	8080	Viser 뷰어 포트
--conf_threshold	1.5	신뢰도가 낮은 포인트를 필터링하기 위한 가시성 임계값 (Visibility threshold)
--point_size	0.00001	포인트 클라우드 (Point cloud) 포인트 크기
--downsample_factor	10	포인트 클라우드 디스플레이를 위한 공간적 다운샘플링 (Spatial downsampling)

python demo.py --model_path /path/to/checkpoint.pt \
--image_folder /path/to/images/ --use_sdpa

만약 메모리 부족 (Out-of-memory) 문제가 발생한다면, 다음 중 하나(또는 둘 다)를 시도해 보세요:

— 추론 (Inference) 동안 프레임당 예측을 CPU로 오프로드 (offload) 합니다 (기본적으로 활성화되어 있음; 메모리 여유가 있는 경우에만 --no-offload_to_cpu를 사용하세요).
— 양방향 스케일 프레임 (bidirectional scale frames)의 수를 기본값인 8에서 2로 줄입니다. 이는 초기 스케일 단계의 활성화 피크 (activation peak)를 줄여줍니다: --num_scale_frames 2

포즈 (Pose) 정확도를 약간 희생하는 대신 실제 실행 속도 (wall-clock speed)를 높이려면 카메라 헤드 (camera head)의 반복 정밀화 (iterative refinement) 단계 수를 줄이세요:

python demo.py --model_path /path/to/checkpoint.pt \
--image_folder /path/to/images/ --camera_num_iterations 1

--camera_num_iterations의 기본값은 4이며, 이를 1로 설정하면 카메라 헤드에서의 정밀화 패스(refinement passes) 3회를 건너뜁니다 (또한 KV 캐시 (KV cache)를 4배 축소합니다).

시퀀스가 인터랙티브 Viser 뷰어로 보기에는 너무 긴 경우(예: 위에 소개된 실내 워크스루)에는 이 파이프라인을 사용하세요. demo_render/batch_demo.py는 올인원 오프라인 엔트리 포인트 (all-in-one offline entry point)입니다. 비디오나 이미지 폴더를 입력하면 단일 명령으로 모델 추론을 실행하고 헤드리스 (headless) 포인트 클라우드 플라이스루 (flythrough) MP4를 생성합니다. 이는 demo.py와 동일한 PyTorch / FlashInfer / 체크포인트 (checkpoint) 스택을 공유합니다.

VRAM 또는 GPU 사용량이 제한적인 분들은 다음 구현을 참고할 수 있습니다: https://github.com/ureeey/lingbot-map-rtx4060-8g/commit/eeee84a89cc97c1e39b736b46df4ee315275700b

1. 렌더링 Python 의존성 (dependencies)

pip install -e ".[vis,render]"

render는 open3d>=0.19와 pyyaml (핵심 numpy<2...

제약 사항은 베이스 lingbot-map에서 비롯됩니다.

배치 세그멘테이션 (batched segmentation)을 위한 이 파이프라인의 스카이 마스킹 (Sky masking)에는 onnxruntime-gpu를 사용합니다. CPU용 onnxruntime이 이미 설치되어 있지 않다면 설치하십시오:

pip install onnxruntime-gpu

2. Kaolin — 위에서 권장한 PyTorch 2.8.0 + CUDA 12.8 버전과 일치합니다:

pip install --index-url https://pypi.org/simple \
kaolin -f https://nvidia-kaolin.s3.us-east-2.amazonaws.com/torch-2.8.0_cu128.html

--index-url https://pypi.org/simple은 PyPI 플레이스홀더 휠 (PyPI placeholder wheel)을 제공하여 임포트 시 ImportError를 발생시킬 수 있는 내부 미러 (internal mirror)를 우회합니다. NVIDIA Kaolin은 PyTorch 2.9.x용 사전 빌드된 휠 (prebuilt wheels)을 게시하지 않습니다. 다른 이유로 2.9 버전을 사용 중이라면, Kaolin을 소스에서 빌드하십시오 (pip install --no-build-isolation git+https://github.com/NVIDIAGameWorks/kaolin.git, 로컬 CUDA 툴킷 (CUDA toolkit) 필요). 다른 torch/CUDA 조합에 대해서는 NVIDIA Kaolin 설치 안내를 참조하십시오.

3. ffmpeg

sudo apt install ffmpeg # 또는: brew install ffmpeg

4. CUDA 확장 (CUDA extensions) (첫 실행 전 필수)

cd demo_render/render_cuda_ext && python setup.py build_ext --inplace && cd ../..

이 명령은 voxel_morton_ext와 frustum_cull_ext를 제자리 (in place)에서 빌드합니다. 두 모듈 모두 GPU 복셀화 (voxelization) 및 프러스텀 컬링 (frustum culling)을 위해 rgbd_render에서 임포트됩니다.

데이터셋 (Dataset): Hugging Face의 robbyant/lingbot-map-demo에서 예제 비디오를 다운로드하십시오.

python demo_render/batch_demo.py \
--video_path /data/demo_videos/indoor_travel.MP4 \
--output_folder /data/outputs/indoor_travel/ \
...

플래그별 근거 (Flag-by-flag rationale):