LingBot-Map 딥다이브
— 스트리밍 영상에서 3D 지도를 실시간으로 그리는 기하학 트랜스포머

카메라 포즈와 3D 재구성의 수학

카메라 포즈는 "카메라가 공간 어디에 있고 어느 방향을 보는지"를 행렬로 표현한 것이다. LingBot-Map은 이를 9차원 벡터(translation 3 + quaternion 4 + FoV 2)로 압축해 예측한다. 변환 코드는 lingbot_map/utils/pose_enc.py에 있다. 특히 SE3(특수 유클리드 군) 역행렬 계산인 closed_form_inverse_se3()는 3D 변환의 기초 중 기초다.

# pose_enc.py — 포즈 벡터→카메라 외/내부 파라미터 변환
def pose_encoding_to_extri_intri(pose_encoding, ...):
    # T(translation) + R(quaternion) + FoV → 4×4 변환 행렬
    ...

인과적 어텐션과 KV 캐시의 실제 구현

LLM과 동일한 KV 캐시 개념이 비전에 적용된 실제 코드를 볼 수 있다. lingbot_map/layers/attention.py에 FlashInfer 페이지드 어텐션과 PyTorch SDPA 두 가지 백엔드가 모두 구현되어 있다. 두 코드를 비교하면 "왜 페이지드 어텐션이 필요한가"가 명확하게 보인다.

lingbot_map/layers/flashinfer_cache.py는 KV 캐시 슬롯 할당·해제·스케줄링을 담당한다. LLM 추론 최적화 공부의 훌륭한 실제 사례다.

ViT 특징을 픽셀 수준 예측으로 업샘플링하는 법

DPT(Dense Prediction Transformer)는 ViT의 여러 레이어에서 중간 토큰을 뽑아 멀티스케일로 융합한 뒤 픽셀 해상도로 업샘플링한다. Depth Anything V2와 같은 설계다. lingbot_map/heads/dpt_head.py는 이 패턴의 깔끔한 PyTorch 구현체이므로 "ViT로 밀집 예측을 어떻게 하나"를 배우기 최적이다.

# dpt_head.py — 4개 중간 레이어 특징을 fusion
intermediate_layer_idx: List[int] = [0, 1, 2, 3]
# output_dim=2 → depth + confidence
# output_dim=4 → XYZ + confidence (포인트맵)

긴 시퀀스를 슬라이딩 윈도우로 처리하는 패턴

320프레임을 초과하는 시퀀스는 RoPE 학습 범위를 벗어나 정확도가 떨어진다. LingBot-Map은 슬라이딩 윈도우로 이를 해결한다. 인접 윈도우가 8개 키프레임을 공유(overlap)해서 포즈 정렬이 연속되도록 한다. 이 설계 패턴은 긴 문맥을 다루는 어떤 ML 시스템에도 응용 가능하다. 코드는 lingbot_map/models/gct_stream_window.py에 있다.

모델을 Hub에서 바로 로드하는 PyTorchModelHubMixin

GCTBase가 PyTorchModelHubMixin을 상속하기 때문에 GCTStream.from_pretrained("robbyant/lingbot-map") 한 줄로 가중치를 내려받을 수 있다. 자신의 PyTorch 모델을 HF Hub에 올리고 싶을 때 참고할 만한 패턴이다.

예제 장면 실행하기 난이도 ★☆☆ 입문

레포에 포함된 example/courthouse/ 이미지 시퀀스로 viser 뷰어를 띄워본다. 브라우저에서 http://localhost:8080을 열면 3D 포인트 클라우드가 실시간으로 생성되는 것을 확인할 수 있다.

conda create -n lingbot-map python=3.10 -y
conda activate lingbot-map
pip install torch==2.8.0 torchvision==0.23.0 --index-url https://download.pytorch.org/whl/cu128
pip install -e ".[vis]"
pip install flashinfer-python
# 모델 가중치를 HuggingFace에서 다운로드 후:
python demo.py --model_path lingbot-map-long.pt \
    --image_folder example/courthouse --mask_sky

직접 촬영한 영상으로 3D 재구성 난이도 ★★☆ 중급

스마트폰으로 방 안을 천천히 찍은 영상 파일을 만들어 입력으로 넣어본다. --fps로 샘플링 비율을 조정하고, --conf_threshold를 바꿔가며 포인트 클라우드 밀도 변화를 관찰한다.

python demo.py --model_path lingbot-map-long.pt \
    --video_path my_room.mp4 --fps 5 \
    --conf_threshold 2.0 \
    --camera_num_iterations 1   # 속도 우선

다음으로 --keyframe_interval 3을 추가해서 KV 캐시 사용량이 줄어드는지 LINGBOT_DEBUG_KV=1 환경변수로 직접 확인해본다.

gct_profile.py로 성능 프로파일링 난이도 ★★☆ 중급

다양한 백엔드·정밀도 조합의 추론 속도와 메모리를 비교해본다. FlashInfer vs SDPA, bf16 vs fp32, compile 유무를 체계적으로 실험해 보면 딥러닝 추론 최적화 감각이 생긴다.

# FlashInfer + BF16 + 컴파일 최대 성능
python gct_profile.py --backend flashinfer --dtype bf16 --compile
# SDPA 폴백 비교
python gct_profile.py --backend sdpa --dtype fp32

슬라이딩 윈도우 모드로 장시간 영상 처리 난이도 ★★★ 고급

3000프레임 이상의 영상에서 윈도우 모드를 실험한다. --window_size·--overlap_keyframes·--keyframe_interval 세 파라미터를 조합하며 "KV 캐시 슬롯 수 × keyframe_interval = 실제 커버 프레임 수" 공식을 직접 검증해본다.

python demo.py --model_path lingbot-map-long.pt \
    --video_path long_walk.mp4 --fps 10 \
    --mode windowed \
    --window_size 128 --overlap_keyframes 8 --keyframe_interval 2
# 커버 범위: 8 + (128-8)×2 = 248프레임/윈도우

오프라인 렌더링 파이프라인으로 MP4 출력 난이도 ★★★ 고급

CUDA 확장을 직접 빌드하고, 배치 렌더링 파이프라인으로 포인트 클라우드 플라이스루 영상을 만들어본다. YAML 카메라 경로를 편집해서 다양한 시점(follow → birdeye → follow)을 연출해 보자.

# CUDA 확장 빌드
cd demo_render/render_cuda_ext && python setup.py build_ext --inplace
# 오프라인 렌더링
python demo_render/batch_demo.py \
    --video_path my_video.mp4 \
    --output_folder outputs/ \
    --model_path lingbot-map.pt \
    --config demo_render/config/indoor.yaml \
    --mode windowed --window_size 64 --keyframe_interval 5