vkgs-sim

nuScenes 싱가포르 맵 기반 Vulkan 3D Gaussian Splatting closed-loop 시뮬레이터

VLM/VLA 주행 모델을 closed-loop 로 시험하기 위한 시뮬레이터다. 모델이 6-카메라 이미지를 보고 제어를 내면, 그 제어로 차가 움직이고, 새 자세에서 6장을 다시 렌더링해 돌려준다. 원본 로그를 재생하는 open-loop 평가와 달리 모델의 행동이 다음 관측을 바꾼다.

   ┌──────────────┐  6 x (1600x900)  ┌───────────┐
   │  Vulkan 3DGS │ ───────────────► │  VLM/VLA  │
   │   렌더러     │                  │   모델    │
   │              │ ◄─────────────── │           │
   └──────┬───────┘   조향/가속      └───────────┘
          │
   ego 상태 적분 (자전거 모델) + 싱가포르 차선 그래프 제약

현재 상태

단계	내용	상태
0	로컬 개발 환경 (CUDA + Vulkan + PyTorch, micromamba)	완료
0	nuScenes 데이터 계층 (씬 인덱스, 카메라 리그)	완료·검증됨
1	3DGS 재구성 (LiDAR 초기화 → gsplat 학습)	주간 기준선 통과 — scene-0003 정적 PSNR 25.62 dB. 야간+우천은 미해결
2	Vulkan 렌더러 (빌보드 → 컴퓨트 타일)	빌보드 경로 완료 — gsplat 과 PSNR 56 dB 일치, 맵 오버레이 뷰어
3	closed-loop 환경 + VLA 브리지	미착수

자세한 계획은 docs/roadmap.md, 설계 근거는 docs/architecture.md 를 보라.

빠른 시작

Docker 없이 로컬에서 개발한다. sudo 불필요 — 전부 $HOME 아래(micromamba)에 설치된다. 스택은 docker/Dockerfile 과 같다: CUDA 12.1 / PyTorch 2.4.1 / gsplat 1.4.0 / Vulkan.

# 1. 환경 구축 (최초 1회, 재실행 안전)
bash scripts/local_setup.sh

# 2. 매 셸마다 활성화
source scripts/local_env.sh

활성화된 셸에서:

vkgs-doctor                     # CUDA / Vulkan / 데이터셋 / 인덱스 한 번에 점검
nusim index build               # 씬 인덱스 생성 (약 40초, 최초 1회)
nusim index list --grep rain    # 야간·우천 씬 찾기
nusim scene show scene-0003     # 씬 하나의 카메라 구성 확인
pytest tests/

cmake -S src/vkgs -B build -GNinja && cmake --build build
./build/vkgs_probe              # Vulkan 경로 끝까지 검증

Docker 로 돌리고 싶다면 (선택)

bash scripts/host_install_docker.sh   # sudo 필요
bash scripts/build.sh && bash scripts/run.sh && bash scripts/shell.sh

데이터

nuScenes v1.0-trainval 전체가 NAS 에 있고, 읽기 전용으로 마운트된다.

/home/mm/nas2/nuscenes_original_junhan/nuscenes/original/full   (호스트)
                          ↓ :ro
/data/nuscenes                                                  (컨테이너)

싱가포르 씬만 다룬다 (boston-seaport 467개는 범위 밖):

맵	씬	성격
singapore-onenorth	183	업무지구·연구단지
singapore-queenstown	115	주거지·주차장
singapore-hollandvillage	85	야간·우천이 몰려 있음
합계	383	이미지 532,157장 (6캠 × 약 12 Hz × 20초)

씬 인덱스

nuscenes-devkit 의 NuScenes() 는 모든 테이블을 메모리에 올린다 — trainval 기준 2~3분에 10 GB 이상이다. 재구성·시뮬레이션 루프가 매번 낼 비용이 아니고, 원본이 NFS 위에 있어 반복 접근은 특히 비싸다.

그래서 원본 테이블을 딱 한 번 스트리밍으로 훑어 씬별로 잘라 캐시에 굳힌다.

nusim index build
  → cache/scene_index/catalog.json          카탈로그
  → cache/scene_index/scene-XXXX.json.gz    씬별 (6캠 프레임 + ego 포즈 + 캘리브)

실측 (RTX 3060 Ti 머신, NFS):

빌드 시간	35.8초 (sample_data.json 1.35 GB + ego_pose.json 645 MB 포함)
피크 메모리	0.51 GB
인덱스 크기	35 MB (383씬 전체)
씬 1개 로드	7 ms

스트리밍 파서(nusim.io.jsonstream)가 이걸 가능하게 한다 — 263만 행짜리 sample_data.json 을 순회하는 데 피크 RSS 30 MB 다.

저장소 구조

docker/           Dockerfile, requirements, entrypoint
scripts/          호스트 설치 + 컨테이너 빌드/기동/진입
config/           paths.yaml — 데이터셋 경로
src/nusim/        파이썬: 데이터 · 재구성 · 맵 · 시뮬 루프
src/vkgs/         C++/Vulkan: 3DGS 렌더러 (현재는 프로브만)
tests/            pytest
cache/            파생물 (씬 인덱스). git 에 넣지 않는다
outputs/          렌더 결과, 체크포인트. git 에 넣지 않는다

하드웨어 제약

RTX 3060 Ti 8 GB 가 이 프로젝트의 가장 강한 제약이다.

• 가우시안 1개 = fp32 기준 약 236 B (위치 12 + 스케일 12 + 회전 16 + 불투명도 4 + SH 192). 렌더링 전용으로 쓰면 8 GB 에 약 2,000만 개가 상한이다.
• 학습 은 gradient·Adam 상태·활성화가 더 붙어 실질 상한이 훨씬 낮다. 씬당 100만~200만 개, 이미지 다운스케일 2배를 기준선으로 잡는다.
• 6개 카메라를 동시에 1600×900 으로 렌더링하면 프레임당 8.6 Mpixel 이다. 실시간(10 Hz)을 노리려면 타일 래스터라이저가 필수고, 빌보드 방식으로는 어렵다.

이 수치는 vkgs_probe 가 실제 장치에서 다시 확인해 준다.