# 설계와 그 근거 결정마다 *왜 그렇게 했는지* 를 남긴다. 나중에 뒤집을 때 무엇이 걸려 있는지 알기 위해서다. ## 전체 그림 ``` nuScenes 원본 (NFS, 읽기전용) │ │ ① 인덱싱 — 한 번만, 스트리밍 ▼ cache/scene_index/*.json.gz 씬별 6캠 프레임 + ego 포즈 + 캘리브 │ │ ② 재구성 — 씬당 1회, PyTorch/CUDA ▼ outputs/gs/.ply 정적 배경 3DGS + 객체별 3DGS │ │ ③ 렌더링 — 매 프레임, Vulkan ▼ 6 × (1600×900) RGB │ │ ④ closed-loop ▼ VLM/VLA 모델 → 제어 → ego 적분 → ③ 으로 되돌아감 ``` ## 왜 학습은 CUDA, 렌더링은 Vulkan 인가 둘을 한 API 로 통일하지 않은 건 의도적이다. **학습에 CUDA 를 쓰는 이유.** 3DGS 최적화는 역전파가 필요하다. PyTorch 의 autograd 위에 올리면 densification/pruning 같은 실험을 며칠이 아니라 몇 시간 단위로 돌려볼 수 있다. Vulkan 으로 학습 파이프라인을 다시 쓰는 것은 가능하지만, 얻는 것이 없다 — 학습은 오프라인이고 한 번만 돈다. **렌더링에 Vulkan 을 쓰는 이유.** closed-loop 는 매 스텝 6장을 새로 그린다. CUDA 래스터라이저를 그대로 쓰면 (a) 화면 출력에 CUDA-GL interop 이 끼어야 하고, (b) 학습 프레임워크 전체가 런타임 의존성이 되며, (c) 모델 추론과 GPU 를 다투게 된다. Vulkan 쪽은 그래픽 파이프라인·스왑체인·타임라인 세마포어가 이미 있어서 렌더링과 추론을 별도 큐로 겹칠 수 있다. 교환 지점은 **`.ply` 파일 하나** 다. 학습기는 표준 3DGS ply 를 쓰고, 렌더러는 그걸 읽는다. 두 쪽이 서로를 링크하지 않는다. ## 왜 devkit 을 감싸지 않고 인덱스를 따로 만드나 `nuscenes-devkit` 은 버릴 물건이 아니다 — 어노테이션과 맵 API 는 그대로 쓴다. 다만 `NuScenes()` 생성자가 모든 테이블을 통째로 올리는 게 문제다 (trainval 2~3분, 10 GB+). 시뮬레이션 루프가 "scene-0553 의 CAM_FRONT 137번째 프레임 경로와 그때 ego 자세" 를 묻는 데 낼 비용이 아니다. 그래서 **뜨거운 경로만** 덜어낸다. 인덱스에 담는 것은 재구성과 렌더링에 매번 필요한 것뿐이다: 파일 경로, 타임스탬프, ego 포즈, 카메라 캘리브. 어노테이션·맵·라이다는 필요할 때 devkit 으로 간다. `nusim.io.jsonstream` 이 이걸 가능하게 한다. 최상위 JSON 배열을 원소 단위로 흘려보내므로 1.35 GB 파일을 피크 30 MB 로 훑는다. `json.load()` 는 같은 파일에 6 GB 안팎을 쓴다. ## 좌표계 여기서 틀리면 전부 틀린다. 한 곳(`nusim.data.rig`)에만 적어 둔다. | 프레임 | 축 | 비고 | |---|---|---| | global / map | x=동, y=북, z=위 | nuScenes 맵 좌표, 미터 | | ego | x=전방, y=좌, z=상 | | | camera | x=우, y=하, z=전방 | OpenCV. nuScenes intrinsic 이 이걸 가정 | | clip | NDC x,y ∈ [-1,1], **y 아래가 +**, **z ∈ [0,1]** | Vulkan. OpenGL 과 다름 | nuScenes 원본의 의미: - `ego_pose.translation/rotation` = **ego → global** - `calibrated_sensor.translation/rotation` = **camera → ego** - 쿼터니언은 전부 `(w, x, y, z)` 순서 따라서 `c2w = ego2global @ cam2ego`, view 행렬은 그 역이다. 실측으로 확인한 6-카메라 배치 (scene-0003, ego 전방 기준 방위각): ``` CAM_FRONT_LEFT +55.2° HFOV 64.3° CAM_FRONT +0.3° HFOV 64.6° CAM_FRONT_RIGHT -56.4° HFOV 64.8° CAM_BACK_RIGHT -110.8° HFOV 64.8° CAM_BACK +179.9° HFOV 89.3° ← 후방만 광각 렌즈 CAM_BACK_LEFT +108.6° HFOV 65.0° ``` 겹침을 포함해 360° 를 덮는다. CAM_BACK 만 초점거리가 809 px 로 다른 5개(약 1260 px)와 다르다 — 멀티뷰 텐서를 만들 때 intrinsic 을 공유하면 안 되는 이유다. ## 렌더러: 왜 2단계인가 1단계 **빌보드**: 가우시안마다 화면정렬 쿼드를 그리고 깊이순으로 정렬해 알파 블렌딩. 그래픽 파이프라인만 쓰므로 며칠이면 화면이 뜬다. 정렬이 per-가우시안 근사라 카메라가 돌 때 popping 이 생긴다. 2단계 **컴퓨트 타일**: 원본 3DGS 방식. 화면을 16×16 타일로 나누고, 각 타일에 겹치는 가우시안을 binning 한 뒤 타일별로 정확한 순서로 블렌딩한다. 논문 대비 정확한 결과가 나오고 6뷰 동시 렌더링에서 훨씬 빠르다. 1단계를 건너뛰지 않는 이유는 **검증 수단** 때문이다. 타일 래스터라이저를 디버깅할 때 "이 장면이 대충 이렇게 보여야 한다" 는 기준 이미지가 있어야 한다. 빌보드 렌더러가 그 기준이 된다. 빌보드 경로는 2단계가 끝나도 남긴다 — 저사양 폴백으로 쓸 수 있다. ## 렌더러 리소스 바인딩: bindless (2026-10-05) 모든 파이프라인이 **전역 descriptor set 하나**(set 0)와 **같은 파이프라인 레이아웃**(push constant 160 B, 모든 단계)을 쓴다. set 에는 종류별 리소스 배열이 있고 셰이더는 번호로 고른다 (`shaders/bindless.glsl`, Vulkan 1.2 descriptor indexing — partially bound, update-after-bind): | binding | 종류 | 쓰임 | |---|---|---| | 0 | SSBO[256] | 0 전역 상수(IBL 큐브 번호), 1 가우시안, 2 스플랫, 3 정렬 키, 4 인다이렉트 인자, 5~ glTF 재질 (모델마다 하나) | | 1 | UBO[16] | 0 카메라, 1 날씨 | | 2 | sampler2D[4096] | 0 BRDF LUT, 1 흰색, 2~ glTF 텍스처 | | 3 | samplerCube[32] | 0 IBL specular, 1 irradiance, 2 학습된 하늘 | | 4 / 5 | image2D 4채널[8] / 1~2채널[8] (형식 없는 storage — 실제 형식은 렌더 그래프 JSON) | 렌더 타겟·날씨 결과·배경·강수 / 거리 누적 | 하나뿐인 리소스는 고정 슬롯(셰이더와 C++ 의 같은 상수), 여러 개인 리소스(재질·텍스처·큐브)는 push constant 나 전역 상수의 번호. 프레임마다 set 을 두 바인드 지점에 한 번씩만 묶고, glTF 는 재질이 바뀔 때 push 만 바꾼다. 리소스를 더해도 파이프라인·set 을 새로 만들 필요가 없어서, 차량·텍스처·씬(맵 스트리밍)이 늘어나도 같은 구조다. 전환 전후 렌더 14장(스플랫·IBL·BEV+glTF 차량·날씨·학습된 하늘)이 비트 단위로 같다 (`cache/bindless_check.sh`). ## 렌더 그래프와 셰이더 리플렉션 (2026-10-05) 한 프레임이 무엇을 어떤 순서로 하는지는 **`configs/render_graph.json`** 이 정한다. 엔진(`src/vkgs/src/render_graph.*`)은 1. `pipelines` 로 파이프라인을 만든다 (셰이더 파일·토폴로지·깊이 모드·컬링). 셰이더 인터페이스는 SPIR-V 리플렉션(SPIRV-Reflect)으로 읽는다. push 범위, bindless 레이아웃과 binding 종류가 맞는지, 거리 누적 출력 (location 1)을 쓰는지, 컴퓨트 워크그룹 크기를 모두 셰이더 자신에게서 얻는다. 2. **실행 순서 = 선언 순서**다. 선언 순서가 곧 접근 순서를 정의하므로, `uses`(리소스, 사용 방식)로 만든 의존 간선 (RAW·WAW·WAR)은 늘 앞 패스 → 뒤 패스이고 순환이 생길 수 없다. 간선은 그림과, 앞으로 독립 패스를 찾는 데(큐 병렬화) 쓴다. (2026-10-05 검토 전까지 문서는 '위상 정렬로 재배치' 라고 했지만 결과는 늘 선언 순서였다.) 3. 매 프레임 **for 문 하나**로 그 순서를 돈다: 사용 방식마다 배리어와 이미지 레이아웃 전환을 자동으로 넣는다 (리소스별 마지막 쓰기 단계·접근, 그 뒤 읽은 단계를 추적한다). 그런 다음 `kind` 이름의 실행기를 부르고 타임스탬프를 찍는다. 엔진 코드는 **패스 종류별 실행기**만 갖는다: `fill_draw_args`, `compute`(디스패치 크기 `gaussians_pow2`|`screen`, `push_slots`), `radix_sort`(대체 `bitonic_sort`), `copy_buffer`(`host_read`), `copy_image`, `raster`(`target` + 그리기 항목 목록), `none`. 리소스는 JSON `create` 로 엔진이 만든다 (버퍼: `bytes` 또는 `bytes_per`×`stride`, 이미지: 화면 크기 + `format`), 렌더 패스는 `targets`. 래스터 패스의 그리기 항목(`background`, `splats`, `gltf_opaque` …)도 이름 → 실행기 표다. 패스·그리기 항목·파이프라인을 JSON 에 더하면 순회 코드는 그대로다. - 그림: `vkgs_viewer x --graph out.dot` (GPU 불필요; 같은 이름의 `.json` 에 실행 순서도 쓴다), `dot -Tsvg out.dot`. 현재 그래프는 `docs/img/render_graph.svg`. - 창 뷰어의 **F2** 는 렌더 그래프 창이다. 정렬 순서, 패스별 GPU ms, 리소스 사용을 보여 주고, 그리기 항목과 `"optional": true` 패스를 켜고 끌 수 있다. - 검증: 전환 전후 렌더 14장 중 12장이 비트 단위로 같다 (날씨 2장은 최대 1/255). Khronos 검증 레이어의 동기화 검증에서도 해저드가 0이다 (`VK_INSTANCE_LAYERS=VK_LAYER_KHRONOS_validation`, `VK_LAYER_ENABLES=VK_VALIDATION_FEATURE_ENABLE_SYNCHRONIZATION_VALIDATION_EXT`). 정렬·배리어 규칙은 `tests/test_render_graph_cpp.py` 가 GPU 없이 시험한다. - 첨부(color/depth attachment)의 전환은 렌더 패스(외부 의존성 포함)가 맡고, 그래프는 패스가 끝난 뒤의 상태만 기록한다. 패스 안의 반복 배리어(radix·bitonic 단계 사이)는 실행기가 직접 넣는다. - 한계: `begin_frame` 은 모든 이미지 레이아웃을 UNDEFINED 로 돌린다 — 프레임을 넘겨 내용을 이어 쓰는 이미지(TAA 기록 등)는 아직 없다. 생기면 `persistent` 표시가 필요하다. ### 거리 누적과 배경 분리 (2026-10-05 검토) 거리 누적 첨부는 RG32F 로 (Σz·α·T, Σα·T) 를 쌓는다 — 표면 깊이 = R/G, 배경이 보이는 비율 = 1 − G (`depth_common.glsl`). 예전에는 R 하나에 배경 1000 m 를 섞은 '기대 깊이' 를 써서, 반투명이 3%만 남아도 깊이가 30 m 늘어 빗방울 가림·안개·노면 판정이 틀렸다. 배경 하늘(시뮬레이션 하늘·학습된 하늘·환경맵)은 별도 `background` 패스가 그리고, 장면 패스는 투명 배경 위에 쌓는다. `weather` 가 가우시안 부분(premultiplied 를 풀어서)과 하늘 부분을 따로 보정한 뒤 덮임 α 로 합친다 — 시뮬레이션 하늘을 두 번 어둡게 하거나, 반투명 픽셀이 낮 하늘색을 품은 채 밤 보정을 피하는 일이 없다. 날씨를 끄면 같은 합성식이라 렌더는 그대로다. ### 셰이더 그래프 후처리 효과는 **노드 그래프**(`configs/shader_graphs/<이름>.json`)로 짠다. 노드의 연산은 노드 라이브러리 (`src/vkgs/shaders/nodes/*.glsl`)의 GLSL 함수 `n_` 이다. 생성기(`scripts/shader_graph.py`)는 **함수 시그니처를 읽어** 노드 정의를 얻는다 — `Ctx` 앞의 인자는 입력 포트, 뒤의 float 은 매개변수이고, 기본값·범위는 `// @param` 주석에서 온다. 노드를 더할 때 생성기는 그대로다. 생성기는 노드를 위상 정렬해 함수 호출 한 줄씩으로 펼치고, 순환·간선 타입·빠진 입력·모르는 매개변수를 빌드 때 잡는다. 결과는 세 가지다: `<이름>.comp` 는 CMake 가 SPIR-V 로 굽고, `<이름>.params.json` 은 매개변수 표, `<이름>.dot` 은 그림이다. 엔진은 렌더 그래프의 compute 패스로 돌린다. 매개변수는 SSBO 에 있고, 이 버퍼는 렌더 그래프 JSON 의 `"create"` 로 엔진이 만든다. 셰이더는 push 된 bindless 슬롯(`push_slots`)으로 버퍼를 읽는다. 그래서 슬라이더(F2 창)나 `sim.json` `shader_graphs.<이름>.params` 로 값을 바꿔도 다시 컴파일하지 않는다. 노드는 픽셀 하나만 보므로 결과를 같은 이미지(post)에 덮어써도 안전하다. 첫 그래프 `camera_isp` 는 카메라 ISP 다 (sRGB → 선형 → 노출 → 화이트밸런스 → 비네팅 → 센서 노이즈 → sRGB → 채도 → 대비, `docs/img/shader_graph_camera_isp.svg`). VLM 이 카메라 특성 변화를 얼마나 견디는지 시험하려는 것이다. 기본은 꺼져 있다 (렌더 결과는 그대로). ## 프로파일링: Tracy (2026-10-05) `vkgs_viewer` 에는 Tracy 클라이언트가 들어 있다 (CMake `VKGS_TRACY`, 기본 켬, `TRACY_ON_DEMAND`). 프로파일러가 붙어 있을 때만 기록하므로 평소 실행 비용은 거의 없다. 기록하는 것은 다음과 같다. - CPU 구간: `render`, `record`, `gpu wait`, 렌더 그래프 `pass`(이름 붙음), `png queue`/`png encode` - GPU 구간: 렌더 그래프 패스와 래스터 그리기 항목마다 Vulkan 타임스탬프 (`TracyVkZoneTransient`), 프레임 경계, 그래프 값(보이는 가우시안 수·속도) 도구는 `scripts/build_tracy.sh` 로 사용자 공간에서 빌드한다: GUI(X11), 창 없이 캡처하는 `tracy-capture`, 표로 뽑는 `tracy-csvexport`. `scripts/profile.sh` 는 캡처와 통계 출력을 한 번에 한다. 첫 측정에서 오프스크린 한 장 229 ms 중 PNG 저장(stb, zlib 8, 행마다 필터 5종 시험)이 216 ms 였다. 인코딩을 백그라운드 스레드로 넘기고 필터를 고정해(`sim.json` `output`) 한 장 23 ms 가 됐다. ## 하늘 가우시안 표시 (2026-10-05) 하늘을 분리하지 않고 학습한 모델(`_env`, `_depth`)은 낮 하늘을 가우시안으로 구워 넣어, 합성 밤에도 하늘이 하얗다. `nusim recon skylabel` 은 가우시안 중심을 학습 뷰에 투영해 SegFormer 하늘 마스크에 떨어지는 비율을 센다. 라이다 깊이보다 뒤라서 가려진 뷰는 세지 않는다. 비율이 0.4 를 넘으면 하늘로 표시해 `sky_gaussians.u8` 에 쓰고, 뷰어는 시뮬레이션 하늘 모드에서 이것들을 뺀다. scene-0003_env 에서는 6.9만 개가 표시됐다. weather.comp 는 거리 버퍼로 배경 하늘이 실제로 보이는 픽셀만 '시뮬레이션 하늘이 이미 그렸다' 로 본다. 하늘처럼 밝아도 가우시안이 그린 픽셀은 밤 노출을 받는다. `nusim render compare` 는 `--keep-sky-gaussians` 로 학습기와 같게 그린다. ## 동적 객체 이게 closed-loop 의 핵심 난점이다. 씬 전체를 하나의 정적 3DGS 로 재구성하면 지나가던 차가 배경에 "구워져" 버린다. ego 가 원본과 다른 경로로 가는 순간 그 구워진 차는 말이 안 되는 위치에 남는다. nuScenes 에는 3D 박스 어노테이션이 있으므로 SfM 기반 방법들이 하는 추정 없이 바로 분리할 수 있다: - 박스 안의 픽셀 → 객체별 3DGS (객체 로컬 좌표계에서 학습) - 박스 밖의 픽셀 → 정적 배경 3DGS - 렌더링 시점에 객체를 원하는 자세로 배치 이러면 시뮬레이터가 다른 차량을 독립적으로 움직일 수 있고, 그래야 "모델이 급정거했을 때 뒤차가 어떻게 되는가" 같은 질문이 성립한다. **무엇이 '움직이는' 객체인가** (`nusim.recon.dynamic.dynamic_instances`). 어노테이션만 믿을 수 없다. 정적 물체도 키프레임마다 박스가 0.5~1.5 m 흔들려서 최대 변위 기준으로는 주차 차량·콘까지 전부 동적으로 잡힌다 (scene-0003: 66개 중 58개). 그래서 궤적 앞 1/3 과 뒤 1/3 의 **중앙값 위치 차이** 를 쓴다 — 흔들림이 상쇄된다. 실측 분포: 움직이는 객체 3.8 m 이상, 정적 객체 1.5 m 이하 → 기준 2 m. 사람은 서 있어도 항상 동적, 한두 키프레임만 스친 차는 moving 속성 과반으로 잡는다. ## 자차를 실제 차량으로 그리기 (객체 에셋) nuScenes 자차(Renault Zoe)는 자기 카메라에 찍히지 않으므로 재구성할 수 없다. 대신 다른 씬의 **주차 차량**을 쓴다. 주차 차량은 정적이라 씬 3DGS 안에 이미 재구성돼 있다 — 3D 박스 안의 가우시안을 잘라 박스 좌표계(x 앞, y 왼쪽, z 위, 바닥 중앙 원점)로 옮기면 에셋이 된다 (`nusim asset extract`, `nusim/recon/asset.py`). - 고르는 법: 주간 씬 전수 조사(`nusim asset scan`) — 자차가 5 m 안으로 지나가며 여러 방위에서 본 차. scene-0003 의 주차 차량은 12 m 밖에서 한두 방위로만 보여 가우시안 3천 개, 흐릿했다. scene-0916 instance 8 (세단, 8방위 중 6방위) → 7,831개, 옆면은 바퀴·창까지 선명. - 못 본 옆면은 차의 좌우 대칭으로 채운다 (잘 보인 쪽을 거울 복사, 쿼터니언 (w,−x,y,−z)). - 회전하면 고차 SH 축이 어긋나므로 0차(기본 색)만 쓴다. - 앞·뒷면은 주차 차량이라 비스듬히만 보여 흐리다. 3인칭 기본 시점을 정뒤가 아닌 왼쪽 뒤 10°로 둔 이유. 더 돌리면 카메라가 학습 궤적에서 벗어나 배경이 깨진다 (25° = 옆으로 3.2 m 에서 실측). 렌더러는 에셋을 씬 가우시안 뒤에 붙여 **한 번에 정렬**한다 — 장면과 서로 올바르게 가린다. 에셋 가우시안은 전처리 셰이더에서 매 프레임 자차 포즈로 옮긴다(`obj_xform`, 공분산은 RΣRᵀ). 자차 카메라 시점(관측 저장 포함)에서는 숨긴다 — 모델 입력에 자기 차가 끼면 안 된다. 맵 선은 깊이를 쓰지 않는 오버레이라, 에셋 경계 상자를 깊이에만 그려(가림막) 선이 차 뒤로 가려지게 했다. ## 색: 왜 학습 중 보정을 두고, 그걸 중심화하는가 nuScenes 6캠은 노출·화이트밸런스가 제각각이고 자동노출이라 프레임마다도 바뀐다. 학습은 렌더에 카메라별 3x4 아핀 + 프레임별 RGB 게인을 곱해 원본과 비교한다. 보정을 빼면 가우시안 색이 카메라 간 차이를 평균내느라 흐려진다. 하지만 렌더러는 ply 만 읽는다. 보정과 가우시안 색은 서로 값을 떠넘길 수 있어서 (전부 밝게 + 보정으로 어둡게 = 같은 결과), 그냥 두면 ply 의 '정준 색' 이 실제 카메라와 한참 다르다 (보정 없이 18 dB). 그래서 보정을 **중심화** 한다: 카메라 평균 아핀은 항상 항등, 학습 프레임 평균 게인은 항상 1. 그러면 정준 색이 곧 평균 카메라의 색이다. 처음엔 학습 끝에 평균 변환을 SH 계수에 구웠다. 변환은 선형이라 수식상 정확하지만 gsplat 이 SH 색에 `clamp_min(0)` 을 걸어 어두운 픽셀에서 틀어진다 — 주간 0.1 dB, 야간 0.3 dB / SSIM 0.05 를 잃었다. 중심화는 학습이 곧바로 최종 결과를 최적화하므로 이 문제가 없다. 순서도 중요하다: 선형 색 → 카메라 변환 → [0,1] 포화. Vulkan 렌더러도 마지막에만 포화시켜야 학습기와 픽셀이 맞는다. ## 카메라 외부 파라미터 보정 nuScenes 의 camera→ego 캘리브는 완벽하지 않다. 카메라마다 SE3 보정 하나(시간 불변)를 같이 학습하면 scene-0003 에서 캠마다 0.29~0.44° / 3~8 cm 가 잡히고, 반복 실행에서 재현된다. 0.4° 는 20 m 앞에서 14 cm — 뷰 사이 가우시안이 흐려지기에 충분하다. 다만 제약이 약한 씬에서는 보정이 표류한다. scene-0003(주간)과 scene-0992(야간)는 같은 차량(n015)이라 CAM_FRONT_LEFT 캘리브가 **완전히 같은데**, 학습된 보정은 0.30° vs 1.98° 였다. 그래서 보정에 약한 L2 사전분포(스케일 0.5° / 5 cm)를 건다. 더 나은 방향: 캘리브는 차량 단위로 거의 고정이다 (싱가포르 n015 씬 거의 전부가 같은 값). 주간 씬 여럿에서 보정을 추정해 평균을 내고, 그걸 차량별 고정 캘리브로 쓰는 편이 씬마다 따로 추정하는 것보다 안정적이다. 아직 하지 않았다. ## IBL — nuScenes 카메라 파노라마로 만든 환경 조명 ``` 6캠 사진 (+3DGS 위쪽 채움) → 360° 파노라마 → HDR 근사 → 큐브맵 512² → prefiltered specular (GGX, mip 6단계 = 거칠기 0→1) + irradiance (SH9 → 32²) + BRDF LUT (256², split-sum) → BC6H 압축 (AMD Compressonator) → KTX2 (자체 작성기, Khronos `ktx validate` 통과) → Vulkan: 환경 배경 + PBR 메시 조명 ``` `nusim render ibl ` (20초), 뷰어 `--ibl outputs/ibl/ [--pbr-spheres]`. - **파노라마**: 카메라 세로 시야가 ±20° 뿐이라 사진은 구의 약 26% 만 덮는다. 사진마다 학습된 색 보정을 거꾸로 걸어 정준 색으로 맞춘다 (안 하면 캠 경계 이음매). 위쪽은 3DGS 렌더를 알파로 합성하고 빈 곳(천정)은 위 가장자리의 밝은 15% 색(하늘)으로, 아래쪽은 아래 가장자리 색(노면)으로 매끄럽게 외삽한다. - 3DGS 만으로 채우면 천정이 검고(위를 본 학습 카메라가 없다) 발밑은 바늘 투성이였다. - 가장자리 색을 그대로 위로 늘이면 기둥·건물 색이 세로 줄무늬가 된다 → 방위 ±10° 평활. - **HDR 은 근사다.** nuScenes 는 8bit JPEG. sRGB→선형 후 휘도 0.75 위를 최대 7배로 키운다. 태양 직사광 세기는 모른다. 화면에 그릴 때는 같은 식을 되돌려(compress_highlights) 3DGS 와 같은 카메라 sRGB 공간으로 맞춘다. - **큐브 면 방향**은 Vulkan 스펙 표 그대로, 셰이더는 씬 좌표(z 위) 방향으로 바로 샘플링한다 — 굽는 쪽과 그리는 쪽이 같은 표를 쓴다. 검증: 거울 구에 하늘이 위, 노면이 아래로 비친다. - **압축**: specular 16 MB → 2 MB (BC6H 8:1), 중앙값 상대 오차 0.35%. - **메시와 스플랫의 깊이 합성**: 스플랫 쿼드에 가우시안 중심 깊이를 주고 깊이 테스트만 한다. 메시를 먼저 그리면 그 뒤의 스플랫이 가려진다 (3DGS 는 원래 깊이를 쓰지 않는다). - 메시 앞면 판정: 투영이 OpenCV 축(y 아래)을 그대로 Vulkan NDC 로 보내 화면 감김이 뒤집힌다 → `VK_FRONT_FACE_CLOCKWISE`. 반대로 두면 구의 안쪽이 보여 비금속도 거울처럼 보였다. 한계: 환경맵은 한 지점(프레임) 것이다 — 자차가 수십 m 움직이면 반사가 맞지 않는다. 3DGS 자차 에셋은 메시가 아니라 IBL 조명을 받지 않는다. IBL 은 glTF 차량(다음 단계)을 위한 것이다. ## closed-loop 평가 인터페이스 — HUGSIM 식 (2026-10-11) 목적지("모델의 제어가 다음 관측을 바꾸는 루프")를 평가 가능한 형태로 묶었다. 설계는 HUGSIM(arXiv 2412.01718)을 따른다: 시뮬레이터를 Gymnasium env 로 감싸고, 시뮬레이터와 AD 알고리즘은 다른 프로세스, 같은 기계에서는 이름 있는 파이프로 말한다. ``` 정책 (nusim.sim.policies / UniAD·VAD 래퍼) ── 웨이포인트(자차 좌표, 0.5 s × 6) ──▶ LQR 추종 (nusim.sim.controller) ▲ 6캠 RGB + 자차 상태 + 내비 명령 │ 가속·조향각, 50 ms 마다 │ ▼ VkgsEnv (nusim.sim.closed_loop) ◀── 상태 줄 ── DIR/resp ── vkgs_viewer --serve DIR (창 없음) ── 명령 줄 ──▶ DIR/cmd drive.hpp Vehicle + step_with_contact (0.01 s), 구간 모델 스트리밍, 관측: /dev/shm/vkgs_sim_*/obs/.rgb (H×W×3 uint8) ◀── 6캠 렌더 (결정 시점마다) ``` - **서버** (`vkgs_viewer --cams rig.txt [--segments …] --drivable … --obstacles … [--voxels …] --size WxH --serve DIR`): 창 운전과 **같은** 차량 모델·충돌 코드를 쓴다 — 물리 한 스텝은 `drive.hpp step_with_contact` 로 빼서 창 루프와 서버가 같이 부른다. 가속·조향각 명령은 `control_for` 가 페달·핸들로 바꾼다 (정지 중 음의 가속 = 정지 유지, 후진하지 않음). 카메라는 평지 자세(기록 z)로 붙인다 — 학습 카메라도 그 높이였다. `settle_on_ground` 의 z·pitch·roll 은 상태로만 알린다. - **프로토콜** (`src/vkgs/src/serve.hpp`, 줄 단위 `이름 key=value …` → `ok key=value …` | `err …`): `hello` (해상도·카메라·차체 치수·충돌 허용치), `reset x= y= yaw= [v=] [frame=]`, `step dt= accel= delta=` 또는 `step dt= throttle= brake= steer=` (+ `render=1`, `sensors=1` 이면 라이다·레이더도 shm 에 nuScenes 형식으로), `render`, `state`, `actors boxes=x,y,yaw,반길이,반폭;…` (다른 차량 바닥 사각형 — 충돌·센서용, 그리기는 아직), `close`. 상태 키: `t x y z yaw v yaw_rate accel delta contact contact_n blocked collisions on_road log_dev ground_z pitch roll seg step_ms render_ms n_obs obs`. 두 쪽 다 cmd 를 먼저 연다 (교착 방지). - **시나리오** `configs/scenarios/<이름>.json` (`nusim sim make-scenarios` 가 `outputs/gs_day` 의 구간이 다 끝난 씬마다 Easy 를 만든다): 씬·모델 디렉터리(단일 또는 구간), 출발(리그 프레임, 기록 속도), 경로(그 프레임부터의 기록 궤적, `max_m` 으로 자름), 제한 시간, `actors` (지금은 `static_box` — 보이지 않는 충돌 상자. replay/IDM/aggressive·3DRealCar 에셋은 같은 자리에 들어온다), `overrides` (closed_loop.json 덮어쓰기). 형식은 `nusim/sim/scenario.py` docstring. - **종료**: 장애물·차량에 막힘(충돌), 도로 이탈 2 s 지속, 경로에서 8 m 넘게 벗어남(재구성 범위 밖), 경로 끝 2 m 안(완주), 시간 초과 — 값은 `configs/closed_loop.json termination`. ### HD-Score (`nusim/sim/hdscore.py`, 설정 `configs/closed_loop.json hdscore`) 결정 시점(2 Hz) t 마다 `HD_t = NC × DAC × (5·TTC + 2·COM) / 7`, 최종 `HD-Score = Rc × 평균_t HD_t` (HUGSIM 식, NAVSIM PDM 에서 EP 를 뺀 것). 부분 점수는 NAVSIM 정의를 우리 판정 재료로 옮겼다: | | 정의 | 판정 재료 | |---|---|---| | NC | 결정 구간 안 닿은 것의 종류별 값 최소 (차량 0, 장애물 0, 연석 1 — NAVSIM 은 정적 물체 0.5, `hdscore.nc`) | 서버 접촉: 막힘 또는 graze 표본 넘게 닿음 | | DAC | 결정 구간 모든 제어 스텝에서 차체 둘레 8점이 주행가능영역 안 | 서버 `on_road` (= 연석 판정과 같은 둘레·허용치) | | TTC | 등속·등방위 1 s 투영(0.1 s 간격)이 지금보다 깊이 닿으면 0, 서 있으면 1 | Python `geometry.World` — 장애물 지도·차량 상자 | | COM | 그 시점까지 2 s 동안 종가속 [-4.05, 2.40], 횡가속 4.89, 종저크 4.13, 저크 8.37, 요레이트 0.95, 요가속 1.93 | 20 Hz 상태, 0.3 s 이동평균 뒤 미분 (미래 표본 안 씀) | | Rc | 경로 투영 진행 최대 / 경로 길이 (완주 허용 거리 안이면 1) | 기록 궤적 폴리라인 | Python 판정은 `drive.hpp vehicle_contact` 와 같은 표본점(float32 누적 0.1 m 격자, 둘레 8점)을 쓴다 — `tests/test_serve_cpp.py` 가 같은 지도·자세에서 C++ 와 점 수를 대조한다. 결정 t 의 점수는 t 까지의 로그만 쓰므로 환경이 매 결정 주는 보상과 `nusim sim score` 가 끝난 로그로 다시 낸 점수가 같다. 기준선 (2026-10-11, 800×450, 학습 작업과 GPU 공유): scene-0402 Easy (235 m 직선) replay **1.000** / constant 0.169 (49 m 에서 왼쪽 나무에 충돌), scene-0006 Easy (101 m, 90° 회전) replay **0.982** (회전 중 TTC 한 번 0 — 등방위 투영이 바깥 장애물로 나간다, NAVSIM 과 같은 한계) / constant 0.440 (회전 구간에서 충돌). 6캠 렌더 62~79 ms, 물리 50 ms 적분 + 접촉 0.3~0.6 ms, 결정 한 번 약 120 ms (실시간의 약 4배 빠르기). 한계: 다른 참가자는 아직 그리지 않는다 (Easy 만 의미 있다). 지역 맵(`_map/<지역>`)은 장애물·복셀이 없어 시나리오로 쓰지 않는다. 관측 화질은 그 씬 재구성 품질 그대로다 (scene-0006 은 회전 구간이 흐리다). ## 8 GB VRAM 이라는 제약 RTX 3060 Ti 8 GB 가 설계 전반을 누른다. 가우시안 1개 = 236 B (fp32): | 항목 | 바이트 | |---|---:| | 위치 xyz | 12 | | 스케일 | 12 | | 회전 쿼터니언 | 16 | | 불투명도 | 4 | | SH 계수 (degree 3, 48개 float) | 192 | - 렌더링 전용: 8 GB ÷ 236 B ≈ **2,000만 개** 가 이론 상한. 프레임버퍼·정렬 버퍼를 빼면 실질 1,200만 개 안팎. - 학습: gradient + Adam 모멘텀 2개가 붙어 파라미터당 4배. 씬당 **100만~200만 개**, 이미지 **2배 다운스케일** 을 기준선으로 잡는다. - SH 를 fp16 으로 저장하면 가우시안당 96 B 를 아낀다 (40%). `vkgs_probe` 가 `shaderFloat16` 지원 여부를 보고한다. ## 데이터를 절대 쓰지 않는다 nuScenes 원본은 67 TB 가 찬 공용 NFS 위에 있다. `docker-compose.yml` 에서 `:ro` 로 마운트하는 것은 편의가 아니라 안전장치다. 파생물은 전부 로컬 디스크의 `cache/` 와 `outputs/` 로 간다.