Add files using upload-large-folder tool

configs/jobs/demo_camera_modes.json

@@ -0,0 +1,18 @@
+{
+  "_doc": "발표용 카메라 모드 주행 영상 (2026-10-12). demo_videos 와 같은 자동 주행 20초 창 화면 녹화를 카메라 모드(--camera-mode)만 바꿔 깊이 · 시맨틱 · 흑백으로 — 모드는 위쪽 줄 카메라 센서 영상에만 걸리고 메인 주행 화면 · BEV 는 RGB 그대로. 시맨틱은 모델 옆 semantic.rgba 가 있어야 한다 (nusim recon semantic --location singapore-onenorth). 창이 화면에 떠서 혼자 달린다 — 사용자에게 미리 알릴 것. 결과: outputs/videos/camera_<모드>.mp4 (+ _poster.jpg).",
+  "name": "demo_camera_modes",
+  "vars": {
+    "map": "render map singapore-onenorth --no-sensors --",
+    "common": "--autopilot --front-cams --bev-pip --hide-panels --autoshot 400",
+    "dir": "outputs/videos",
+    "enc": "render encode --bitrate 2M"
+  },
+  "steps": [
+    {"name": "rec_depth", "run": "${map} ${common} --camera-mode depth --record-screen ${dir}/camera_depth/frames"},
+    {"name": "enc_depth", "run": "${enc} ${dir}/camera_depth/frames ${dir}/camera_depth.mp4 --poster ${dir}/camera_depth_poster.jpg --caption '깊이 카메라 — 로그 거리 turbo 색 (0~80 m)'"},
+    {"name": "rec_semantic", "run": "${map} ${common} --camera-mode semantic --record-screen ${dir}/camera_semantic/frames"},
+    {"name": "enc_semantic", "run": "${enc} ${dir}/camera_semantic/frames ${dir}/camera_semantic.mp4 --poster ${dir}/camera_semantic_poster.jpg --caption '시맨틱 세그멘테이션 카메라 — nuScenes-lidarseg 라벨 (Cityscapes 색)'"},
+    {"name": "rec_gray", "run": "${map} ${common} --camera-mode gray --record-screen ${dir}/camera_gray/frames"},
+    {"name": "enc_gray", "run": "${enc} ${dir}/camera_gray/frames ${dir}/camera_gray.mp4 --poster ${dir}/camera_gray_poster.jpg --caption '흑백 카메라 — Rec.601 루마'"}
+  ]
+}

configs/jobs/ground_ablation.json

@@ -0,0 +1,11 @@
+{
+  "_doc": "지면 모델 (HUGSIM 다중 평면 지면, nusim/recon/ground.py) 효과 점검 (2026-10-10). scene-0003 을 맵 배치와 같은 프리셋(day_map, 15k)으로 지면 모델 없이 / λ 10 / λ 100 학습하고, 원래 경로 평가(eval)와 실제 차선 변경 시점(onenorth_0003 타일에서 뺀 주행 0127·0969, 옆 약 4 m — tile-eval)을 비교한다. L_ground 는 m² 단위 분산이라 노면 잡음 0.05 m 이면 0.0025 — 측광 손실(~0.1)과 맞추려면 λ 10~100. 맵 배치(day_map)가 끝난 뒤에 돌린다 (사용자 결정 2026-10-10: GPU 실험은 배치 뒤).",
+  "name": "ground_ablation",
+  "vars": {"base": "recon train scene-0003 --preset day_map", "out": "outputs/gs_exp/ground"},
+  "steps": [
+    {"name": "base", "run": "${base} --out ${out}/base"},
+    {"name": "g10", "run": "${base} --ground-lambda 10 --out ${out}/g10"},
+    {"name": "g100", "run": "${base} --ground-lambda 100 --out ${out}/g100"},
+    {"name": "lane", "run": "recon tile-eval onenorth_0003 --dir ${out}/base --dir ${out}/g10 --dir ${out}/g100 --out ${out}/tile_eval"}
+  ]
+}

configs/jobs/veh_60k_v2.json

@@ -0,0 +1,14 @@
+{
+  "_doc": "차량 동시 학습 60k 재학습 (2026-10-06). veh_60k 는 MCMC 재배치가 객체 가우시안을 다른 곳으로 옮겨 차량 35대 중 17대만 남았다 → 재배치 판정 직전에 객체 가우시안 불투명도 하한(train.py). 3k 점검에서 35대 전부 남음.",
+  "name": "veh_60k_v2",
+  "steps": [
+    {
+      "name": "train",
+      "run": "recon train scene-0003 --strategy mcmc --depth-lambda 0.1 --objects vehicles --eval-every 5000 --out outputs/gs/scene-0003_veh60p"
+    },
+    {
+      "name": "eval",
+      "run": "recon eval scene-0003 --dir outputs/gs/scene-0003_veh60p --geom"
+    }
+  ]
+}

src/nusim/nusim/__init__.py

@@ -0,0 +1,33 @@
+"""nuScenes 싱가포르 맵 기반 Vulkan 3DGS closed-loop 시뮬레이터.
+
+레이어 구조 (docs/architecture.md 참고):
+
+    data/   nuScenes 읽기 — scene 인덱스, 카메라 리그, ego 궤적
+    maps/   맵 확장(map expansion) — 차선 그래프, 주행가능영역
+    recon/  3DGS 재구성(학습) — gsplat 기반
+    io/     .ply / .splat 직렬화 — 학습기와 Vulkan 렌더러 사이의 교환 포맷
+    sim/    closed-loop 환경 — ego 상태 적분, 6카메라 관측 생성
+    cli/    커맨드라인 진입점
+"""
+
+__version__ = "0.1.0"
+
+# 6개 카메라. nuScenes 의 표준 이름이자 이 프로젝트 전체에서 쓰는 정준 순서다.
+# 순서가 바뀌면 멀티뷰 텐서의 축 의미가 달라지므로 여기서만 정의한다.
+CAMERAS = (
+    "CAM_FRONT_LEFT",
+    "CAM_FRONT",
+    "CAM_FRONT_RIGHT",
+    "CAM_BACK_RIGHT",
+    "CAM_BACK",
+    "CAM_BACK_LEFT",
+)
+
+# 싱가포르 맵 3종. boston-seaport 는 이 프로젝트의 범위 밖이다.
+SINGAPORE_MAPS = (
+    "singapore-onenorth",
+    "singapore-queenstown",
+    "singapore-hollandvillage",
+)
+
+__all__ = ["CAMERAS", "SINGAPORE_MAPS", "__version__"]

src/nusim/nusim/aug/__init__.py

@@ -0,0 +1 @@
+"""데이터셋 다양성 증강 — 재구성 장면으로 새 카메라 시점(rig_aug), 생성 모델로 밤·비 → 낮(translate)."""

src/nusim/nusim/aug/artifixer_prep.py

@@ -0,0 +1,128 @@
+"""ArtiFixer(nv-tlabs/artifixer, SIGGRAPH 2026) 입력 만들기 — 시점 변형 렌더를 확산 모델로 고치는 실험 (nusim aug artifixer-prep).
+
+ArtiFixer 는 3D 재구성 렌더(+불투명도)와 실제 참조 사진 몇 장, 카메라 자세를 받아 렌더의 흐림 · 구멍 · 떠다니는 조각을
+자기회귀 비디오 확산(Wan2.1)으로 고친다. 원래 파이프라인은 COLMAP → 3DGRUT 를 새로 학습하지만, 여기서는 우리 구간 모델
+(outputs/gs_day/<씬>/seg<k>)의 gsplat 렌더를 그대로 넣는다 — model_eval/datasets/reconstructed_colmap_eval.py 형식:
+
+  <out>/split.json          {"test": {<id>: {transforms_path, image_root, render_dir, opacity_dir,
+                                             selected_indices_path, target_indices_path, prompt_path, camera_scale, has_gt}}}
+  <out>/transforms.json     OPENCV 내부 파라미터 + frames[i].transform_matrix (NeRFStudio/OpenGL c2w, 미터)
+  <out>/images/             참조 사진 (원래 자세의 실제 nuScenes 사진, 렌더 해상도로 줄임)
+  <out>/renders/{i:05d}.png 렌더 (색 보정 · 하늘 합성 = nusim recon eval 과 같은 영상)
+  <out>/opacity/{i:05d}.png 렌더 불투명도 α (하늘 합성 전)
+  <out>/selected_indices.json  참조(실제 사진) 프레임 = 0..N-1
+  <out>/target_indices.json    고칠 프레임 = 변형 자세 N..2N-1
+  <out>/caption.txt         캡션 — 임베딩(caption.h5)은 artifixer 환경에서 UMT5 로 (scripts/artifixer_caption.py)
+
+자세는 학습이 보정한 외부 파라미터(camera_adjust)를 적용한 렌더 자세 그대로다. 미터 단위라 metric_scale = 1,
+camera_scale = 0.01 (ArtiFixer prepare_colmap_artifixer_inputs 의 DEFAULT_CAMERA_CONDITIONING_SCALE).
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from dataclasses import replace
+from pathlib import Path
+
+import numpy as np
+
+LOG = logging.getLogger(__name__)
+CAMERA_CONDITIONING_SCALE = 0.01
+OPENCV_TO_OPENGL = np.diag([1.0, -1.0, -1.0, 1.0])
+DEFAULT_CAPTION = ("A daytime dashcam video driving along a tree-lined street in Singapore, asphalt road with white "
+                   "lane markings, curbs, sidewalks, trees and buildings, clear sky, realistic photo.")
+
+
+def prepare(scene_name: str, model_dir: Path, variant: dict, out: Path, cam: str = "CAM_FRONT",
+            width: int | None = None, max_frames: int | None = None, timestamps: set | None = None, start: int = 0, caption: str = DEFAULT_CAPTION,
+            tag: str = "", log=LOG.info) -> dict:
+    import torch
+    from PIL import Image
+
+    from nusim.aug.rig_aug import transform_calib
+    from nusim.cli.main import _model_data, _model_objects, _model_views
+    from nusim.io.ply import read_ply
+    from nusim.recon.dataset import build_views
+    from nusim.recon.train import CameraAdjust, ColorCorrection, SkyCube, _to_params, composite_sky, render
+
+    model_dir = Path(model_dir)
+    out.mkdir(parents=True, exist_ok=True)
+    for d in ("images", "renders", "opacity"):
+        (out / d).mkdir(exist_ok=True)
+    g = read_ply(model_dir / "point_cloud.ply")
+    vk = _model_views(model_dir)
+    sub, ds = _model_data(scene_name, model_dir)
+    kw = dict(downscale=vk["downscale"], frame_stride=vk["frame_stride"], keyframes_only=vk["keyframes_only"],
+              objects=_model_objects(model_dir), load_images=False, mask_dynamic=False, log=LOG.debug)
+    # 학습과 같은 뷰 번호 (색 보정의 프레임별 게인이 이 번호) — 그중 한 카메라만 쓴다
+    real = build_views(sub, ds, g.origin, **kw)
+    vsub = replace(sub, calib={c: (transform_calib(k, variant.get("shift_m", (0, 0, 0)), variant.get("rot_deg", (0, 0, 0)))
+                                   if c == cam else k) for c, k in sub.calib.items()})
+    var = build_views(vsub, ds, g.origin, **kw)
+    from nusim import CAMERAS
+
+    cid = CAMERAS.index(cam)
+    rv = [v for v in real.all if v.cam_id == cid][start:]
+    tv = [v for v in var.all if v.cam_id == cid][start:]
+    if timestamps is not None:  # 구간 모델이 '맡는' 프레임만 (nusim.aug.map_aug.assign_front_frames)
+        keep = [i for i, v in enumerate(rv) if v.pose.timestamp in timestamps]
+        rv, tv = [rv[i] for i in keep], [tv[i] for i in keep]
+    if max_frames:
+        rv, tv = rv[:max_frames], tv[:max_frames]
+    if width and width != rv[0].width:  # 8 GB VRAM: ArtiFixer 토큰 수가 해상도에 비례 — 렌더 해상도 자체를 줄인다
+        s = width / rv[0].width
+
+        def small(v):
+            K = v.K.copy()
+            K[:2] *= s
+            return replace(v, K=K, width=width, height=round(v.height * s))
+        rv, tv = [small(v) for v in rv], [small(v) for v in tv]
+    assert [v.pose.timestamp for v in rv] == [v.pose.timestamp for v in tv]
+    n = len(rv)
+    dev = torch.device("cuda")
+    params = _to_params(g, dev)
+    color = ColorCorrection.load(model_dir / "color_correction.pt", 6, len(real.all), dev)
+    adj = None
+    if (model_dir / "camera_adjust.pt").exists():
+        adj = CameraAdjust(6).to(dev)
+        adj.load_state_dict(torch.load(model_dir / "camera_adjust.pt", weights_only=True))
+    sky = SkyCube.from_state(torch.load(model_dir / "sky.pt", weights_only=True)) if (model_dir / "sky.pt").exists() else None
+
+    frames = []
+    w, h = rv[0].width, rv[0].height
+    K = rv[0].K
+    for i, v in enumerate(rv + tv):
+        with torch.no_grad():
+            img, alpha, info = render(params, v, g.sh_degree, cam_adjust=adj, cam_grad=False)
+            img = composite_sky(img, alpha, sky, v, info["viewmat"])
+            img = color(img, v.cam_id, rv[i % n].idx).clamp(0, 1)  # 변형 프레임도 같은 시각 실제 프레임의 게인
+        Image.fromarray((img[0].cpu().numpy() * 255 + 0.5).astype(np.uint8)).save(out / "renders" / f"{i:05d}.png")
+        Image.fromarray((alpha[0, ..., 0].clamp(0, 1).cpu().numpy() * 255 + 0.5).astype(np.uint8)).save(
+            out / "opacity" / f"{i:05d}.png")
+        w2c = info["viewmat"][0].double().cpu().numpy() if info["viewmat"].dim() == 3 else info["viewmat"].double().cpu().numpy()
+        c2w = np.linalg.inv(w2c) @ OPENCV_TO_OPENGL
+        fr = rv[i % n].pose
+        name = f"images/{i % n:05d}.jpg"
+        if i < n:  # 참조 = 원래 자세의 실제 사진
+            Image.open(ds.root / fr.filename).convert("RGB").resize((w, h), Image.BICUBIC).save(out / name, quality=95)
+        frames.append({"file_path": name, "transform_matrix": c2w.tolist(), "timestamp": int(fr.timestamp),
+                       "original_filename": fr.filename, "role": "reference" if i < n else "target"})
+    tr = {"camera_model": "OPENCV", "w": int(w), "h": int(h), "fl_x": float(K[0, 0]), "fl_y": float(K[1, 1]),
+          "cx": float(K[0, 2]), "cy": float(K[1, 2]), "k1": 0.0, "k2": 0.0, "p1": 0.0, "p2": 0.0, "frames": frames}
+    (out / "transforms.json").write_text(json.dumps(tr, indent=1))
+    (out / "selected_indices.json").write_text(json.dumps(list(range(n))))
+    (out / "target_indices.json").write_text(json.dumps(list(range(n, 2 * n))))
+    (out / "caption.txt").write_text(caption)
+    sid = f"{scene_name}_{model_dir.name}_{cam}_{variant['name']}{tag}"  # tag: 한 구간을 나눈 조각 (artifixer_run.prep_scene)
+    split = {"test": {sid: {"scene_id": sid, "transforms_path": "transforms.json", "image_root": ".",
+                            "render_dir": "renders", "opacity_dir": "opacity",
+                            "selected_indices_path": "selected_indices.json", "target_indices_path": "target_indices.json",
+                            "prompt_path": "caption.h5", "metric_scale": 1.0,
+                            "camera_scale": CAMERA_CONDITIONING_SCALE, "has_gt": False}}}
+    (out / "split.json").write_text(json.dumps(split, indent=1))
+    meta = {"scene": scene_name, "model": str(model_dir), "cam": cam, "variant": variant, "frames": n,
+            "size": [int(w), int(h)], "scene_id": sid}
+    (out / "prep.json").write_text(json.dumps(meta, indent=1))
+    log(f"  {sid}: 참조 {n}장 + 고칠 프레임 {n}장 ({w}×{h}) → {out}")
+    return meta

src/nusim/nusim/aug/artifixer_run.py

@@ -0,0 +1,257 @@
+"""ArtiFixer + 차선 후처리 증강을 씬 단위로 끝까지 (nusim aug artifixer) — 설정 configs/aug/artifixer.json.
+
+씬 하나, 카메라 하나마다:
+  1. prep     구간 모델(outputs/gs_day/<씬>/seg<k>) × 리그 변형(날씨 없는 9종)마다 ArtiFixer 입력
+              (nusim.aug.artifixer_prep.prepare — 구간이 '맡는' 프레임만, nusim.aug.map_aug.assign_front_frames)
+              → outputs/artifixer/<씬>_<CAM>/<구간>_<변형>/ + 합친 split.json
+  2. infer    artifixer 환경에서 model_eval.run_inference 한 번 (모델 로드 한 번에 입력 전부) → <같은 곳>/run
+  3. collect  고친 프레임 중 키프레임 → outputs/aug/aug_artfixer/<씬>/<변형>/<CAM>/<원본 파일명>.jpg + meta.json
+  4. lanefix  노면을 실제 사진의 평면 호모그래피로 (nusim.aug.lane_fix, road 모드)
+              → outputs/aug/aug_artfixer/<씬>_lanefix/<변형>/<CAM>/ + meta.json
+  5. 중간 파일 정리 (렌더 · 불투명도 · 추론 프레임, 씬당 약 2.8 GB) — keep_intermediate 로 남길 수 있다
+끝난 표시는 <씬>_lanefix/done.json (카메라별). 있으면 건너뛰므로 끊었다 다시 돌려도 된다.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import subprocess
+import time
+from dataclasses import asdict
+from pathlib import Path
+
+from nusim.config import configs_dir
+from nusim.paths import output_dir, workspace_root
+
+
+def artifixer_config() -> dict:
+    return json.loads((configs_dir() / "aug" / "artifixer.json").read_text())
+
+
+def _variants() -> list[dict]:
+    from nusim.aug.rig_aug import load_variants
+
+    return [v for v in load_variants(configs_dir() / "aug" / "rig_variants.json") if not v.get("weather")]
+
+
+def done_cams(scene: str) -> set[str]:
+    p = output_dir() / "aug" / "aug_artfixer" / f"{scene}_lanefix" / "done.json"
+    return set(json.loads(p.read_text()).get("cams", {})) if p.exists() else set()
+
+
+def finished_scenes(root: Path | None = None) -> list[str]:
+    """학습 · 기존 증강(aug map)까지 끝난 씬 — 기존 증강이 끝난 순서(= 도로 커버리지 우선 학습 순서)대로."""
+    n_var = len(_variants())
+    base = output_dir() / "aug" / "map"
+    out = []
+    for d in base.glob("scene-*"):
+        metas = list(d.glob("*/meta.json"))
+        if len(metas) >= n_var:
+            out.append((max(m.stat().st_mtime for m in metas), d.name))
+    return [s for _, s in sorted(out)]
+
+
+def prep_scene(scene: str, cam: str, cfg: dict, root: Path, log=print) -> Path:
+    from nusim.aug.artifixer_prep import prepare
+    from nusim.aug.map_aug import assign_front_frames
+    from nusim.data.index import load_scene
+    from nusim.recon.batch import segment_dirs
+
+    base = output_dir() / "artifixer" / f"{scene}_{cam}"
+    segs = segment_dirs(root, scene)
+    if not segs:
+        raise RuntimeError(f"{scene}: 학습된 구간 모델이 없음 ({root})")
+    sc = load_scene(scene)
+    owned = assign_front_frames(sc, [s for s, _ in segs])
+    cap = workspace_root() / cfg["caption_h5"]
+    split = {"test": {}}
+    for (info, d), fr in zip(segs, owned):
+        # 구간이 맡는 시각 — 정면 카메라 시각 기준이라 다른 카메라는 구간 모델의 학습 뷰 전부
+        ts = {f.timestamp for f in fr} if cam == "CAM_FRONT" else None
+        # 8 GB: 입력이 길면 ArtiFixer 가 메모리 부족 — 60 m 보다 짧아 한 구간으로 학습된 씬(약 230프레임)이 그랬다.
+        # 연속한 조각으로 나눠 따로 넣는다 (조각 경계에서 시간 일관성은 끊긴다)
+        chunks = [ts]
+        mx = cfg.get("max_frames")
+        if ts is not None and mx and len(ts) > mx:
+            order, n = sorted(ts), -(-len(ts) // mx)
+            chunks = [set(order[j * len(order) // n:(j + 1) * len(order) // n]) for j in range(n)]
+        for c, cts in enumerate(chunks):
+            tag = f"_c{c}" if len(chunks) > 1 else ""
+            for v in _variants():
+                out = base / f"{d.name}_{v['name']}{tag}"
+                meta = prepare(scene, d, v, out, cam=cam, width=cfg["width"], timestamps=cts, tag=tag, log=log)
+                shutil.copy(cap, out / "caption.h5")
+                ent = json.loads((out / "split.json").read_text())["test"][meta["scene_id"]]
+                for k in ("transforms_path", "image_root", "render_dir", "opacity_dir", "selected_indices_path",
+                          "target_indices_path", "prompt_path"):
+                    ent[k] = str((out / ent[k]).resolve())
+                split["test"][meta["scene_id"]] = {**ent, "prep_dir": str(out.resolve())}
+    (base / "split.json").write_text(json.dumps(split, indent=1))
+    log(f"  prep: 입력 {len(split['test'])}개 → {base / 'split.json'}")
+    return base
+
+
+def _collected(scene: str, cam: str, base: Path) -> dict[str, list] | None:
+    """split.json 의 변형마다 수집된 ArtiFixer 결과(meta.json 의 이 카메라 표본) — 하나라도 없으면 None."""
+    sp = base / "split.json"
+    if not sp.exists():
+        return None
+    want = {json.loads((Path(e["prep_dir"]) / "prep.json").read_text())["variant"]["name"]
+            for e in json.loads(sp.read_text())["test"].values()}
+    root = output_dir() / "aug" / "aug_artfixer" / scene
+    out = {}
+    for var in want:
+        m = root / var / "meta.json"
+        smp = [x for x in json.loads(m.read_text())["samples"] if x["filename"].startswith(cam + "/")] if m.exists() else []
+        if not smp:
+            return None
+        out[var] = smp
+    return out
+
+
+def _inferred(base: Path) -> bool:
+    """split.json 의 입력마다 ArtiFixer 결과(pred)가 있나 — 지금 설정(max_frames)으로 만든 split 이어야 한다."""
+    sp = base / "split.json"
+    if not sp.exists():
+        return False
+    sids = json.loads(sp.read_text())["test"]
+    return bool(sids) and all(next((base / "run").glob(f"*/*/{sid}/frames/batch_0000/pred"), None) for sid in sids)
+
+
+def infer(base: Path, cfg: dict, log=print) -> Path:
+    """artifixer 환경 하위 프로세스 — vkgs 환경과 torch 버전이 달라 같은 프로세스에서 못 돌린다."""
+    repo = workspace_root() / cfg["repo"]
+    run = base / "run"
+    env = {**os.environ, "PYTHONPATH": str(repo / "thirdparty" / "3DGRUT-ArtiFixer"),
+           "PYTORCH_CUDA_ALLOC_CONF": "expandable_segments:True"}
+    cmd = [os.path.expanduser(cfg["python"]), "-m", "model_eval.run_inference", "--evalset", "reconstructed_colmap",
+           "--checkpoint_pt", str(workspace_root() / cfg["checkpoint"]), "--model_id", cfg["model_id"],
+           "--save_dir", str(run), "--split_path", str(base / "split.json"), *cfg["infer_args"]]
+    t = time.time()
+    with open(base / "run.log", "w") as f:
+        r = subprocess.run(cmd, cwd=repo, env=env, stdout=f, stderr=subprocess.STDOUT)
+    if r.returncode:
+        raise RuntimeError(f"ArtiFixer 추론 실패 (코드 {r.returncode}) — {base / 'run.log'}")
+    log(f"  infer: {(time.time() - t) / 60:.1f}분 → {run}")
+    return run
+
+
+def collect(scene: str, cam: str, base: Path, log=print) -> dict[str, list]:
+    from PIL import Image
+
+    split = json.loads((base / "split.json").read_text())["test"]
+    dst_root = output_dir() / "aug" / "aug_artfixer" / scene
+    per_var: dict[str, list] = {}
+    size = None
+    for sid, ent in split.items():
+        prep_dir = Path(ent["prep_dir"])
+        pm = json.loads((prep_dir / "prep.json").read_text())
+        tr = json.loads((prep_dir / "transforms.json").read_text())
+        pred = next((base / "run").glob(f"*/*/{sid}/frames/batch_0000/pred"), None)
+        if pred is None:
+            raise RuntimeError(f"{sid}: ArtiFixer 결과 없음 — 추론이 중간에 끊겼다")
+        var = pm["variant"]["name"]
+        out = dst_root / var / cam
+        out.mkdir(parents=True, exist_ok=True)
+        size = Image.open(prep_dir / "renders/00000.png").size  # ArtiFixer 는 16 배수로 바꿔 내므로 렌더 크기로 되돌린다
+        for i, f in enumerate(tr["frames"]):
+            if f["role"] != "target" or not f["original_filename"].startswith("samples/"):  # 키프레임만
+                continue
+            src = pred / f"{i:05d}.png"
+            if not src.exists():
+                continue
+            name = Path(f["original_filename"]).name
+            Image.open(src).convert("RGB").resize(size, Image.BICUBIC).save(out / name, quality=95)
+            per_var.setdefault(var, []).append({"segment": Path(pm["model"]).name, "original_filename": f["original_filename"],
+                                                "filename": f"{cam}/{name}", "timestamp": f["timestamp"]})
+    for var, samples in per_var.items():
+        p = dst_root / var / "meta.json"
+        old = json.loads(p.read_text()) if p.exists() else {}
+        keep = [s for s in old.get("samples", []) if not s["filename"].startswith(cam + "/")]
+        (dst_root / var / "meta.json").write_text(json.dumps({
+            "scene": scene, "variant": var, "cams": sorted(set(old.get("cams", [])) | {cam}),
+            "method": "ArtiFixer 1.3B (nv-tlabs/artifixer) on VKGS-Sim 3DGS renders",
+            "size": list(size), "keyframes_only": True,
+            "samples": sorted(keep + samples, key=lambda s: (s["filename"].split("/")[0], s["timestamp"]))}, indent=1))
+    log(f"  collect: {sum(map(len, per_var.values()))}장 → {dst_root}")
+    return per_var
+
+
+def lanefix(scene: str, cam: str, base: Path, log=print) -> int:
+    from scipy.spatial import cKDTree
+
+    from nusim.aug.lane_fix import LaneFixConfig, Segmenter, fix_prep_dir, map_points
+    from nusim.data.index import load_scene
+
+    lcfg = LaneFixConfig()
+    sc = load_scene(scene)
+    tree = cKDTree(map_points(sc, lcfg))
+    seg = Segmenter()
+    src_root = output_dir() / "aug" / "aug_artfixer" / scene
+    dst_root = output_dir() / "aug" / "aug_artfixer" / f"{scene}_lanefix"
+    n = 0
+    preps = sorted({Path(e["prep_dir"]) for e in json.loads((base / "split.json").read_text())["test"].values()})
+    for prep in preps:  # 구간 없는 씬은 scene-XXXX_<변형> — seg* 만 보면 0장이 된다
+        var = json.loads((prep / "prep.json").read_text())["variant"]["name"]
+        n += fix_prep_dir(prep, src_root / var, dst_root / var, seg, sc, tree, lcfg)
+    for var_dir in src_root.iterdir():
+        if not (var_dir / "meta.json").exists() or not (dst_root / var_dir.name).exists():
+            continue
+        m = json.loads((var_dir / "meta.json").read_text())
+        m["method"] += " + 노면 평면 호모그래피 차선 후처리 (nusim.aug.lane_fix)"
+        m["lanefix"] = asdict(lcfg)
+        (dst_root / var_dir.name / "meta.json").write_text(json.dumps(m, indent=1, ensure_ascii=False))
+    del seg
+    import torch
+
+    torch.cuda.empty_cache()
+    log(f"  lanefix: {n}장 → {dst_root}")
+    return n
+
+
+def cleanup(base: Path) -> None:
+    """무거운 중간 파일만 지운다 — prep.json · transforms.json · split.json 은 남겨 다시 후처리할 수 있게."""
+    shutil.rmtree(base / "run", ignore_errors=True)
+    for prep in (d for d in base.iterdir() if d.is_dir() and d.name != "run"):  # 구간 없는 씬은 scene-XXXX_<변형>
+        for d in ("images", "renders", "opacity"):
+            shutil.rmtree(prep / d, ignore_errors=True)
+
+
+def aug_scene(scene: str, cfg: dict | None = None, root: Path | None = None, cams=None, force: bool = False,
+              log=print) -> dict:
+    cfg = cfg or artifixer_config()
+    root = root or output_dir() / "gs_day"
+    res = {}
+    for cam in cams or cfg["cams"]:
+        if cam in done_cams(scene) and not force:
+            log(f"  {cam}: 이미 끝남 — 건너뜀")
+            continue
+        t = time.time()
+        base = output_dir() / "artifixer" / f"{scene}_{cam}"
+        per_var = None if force else _collected(scene, cam, base)
+        if per_var:  # 추론 · 수집까지 끝나고 차선 후처리에서 실패한 씬 — 20분짜리 추론을 다시 돌리지 않는다
+            log(f"  {cam}: ArtiFixer 결과 {sum(map(len, per_var.values()))}장 있음 — 차선 후처리부터")
+        elif not force and _inferred(base):
+            log(f"  {cam}: 추론 결과 있음 — 수집부터")
+        else:
+            base = prep_scene(scene, cam, cfg, root, log=log)
+            import torch
+
+            torch.cuda.empty_cache()  # ArtiFixer 가 8 GB 거의 전부를 쓴다
+            infer(base, cfg, log=log)
+        if not per_var:
+            per_var = collect(scene, cam, base, log=log)
+        n = lanefix(scene, cam, base, log=log)
+        if not cfg.get("keep_intermediate"):
+            cleanup(base)
+        p = output_dir() / "aug" / "aug_artfixer" / f"{scene}_lanefix" / "done.json"
+        p.parent.mkdir(parents=True, exist_ok=True)
+        d = json.loads(p.read_text()) if p.exists() else {"scene": scene, "cams": {}}
+        d["cams"][cam] = {"images": n, "variants": sorted(per_var), "minutes": round((time.time() - t) / 60, 1),
+                          "finished": time.strftime("%Y-%m-%d %H:%M")}
+        p.write_text(json.dumps(d, indent=1))
+        res[cam] = d["cams"][cam]
+        log(f"  {cam}: 완료 {n}장, {d['cams'][cam]['minutes']}분")
+    return res

src/nusim/nusim/aug/lane_check.py

@@ -0,0 +1,145 @@
+"""증강 영상의 차선 보임 검사 (nusim aug lanecheck) — 차선 검출기 없이, nuScenes 맵의 차선으로 잰다.
+
+맵의 lane_divider · road_divider 폴리라인을 지면(자차 높이)에 놓고 카메라에 투영한 뒤, 표본점마다 선에 수직인
+밝기 단면을 본다. 단면 가운데 창(±search_m, 맵 · 포즈 오차 몫) 안에 주변(중앙값)보다 contrast 이상 밝은 능선이 있으면
+'보임'. 실제 사진 · 원래 위치 렌더 · 변형 렌더를 같은 표본점으로 재므로, 차이가 곧 재구성 · 시점 이동의 손실이다.
+능선이 둘 이상(사이에 골)이면 '이중선' — 시점 이동에서 노면 기하가 틀려 차선이 갈라진 것.
+
+표본점: 카메라 앞 near_m~far_m, 0.5 m 간격, 영상 안. 사진에서 차량이 가린 점은 사진에서도 안 보이므로
+보임 비율은 사진 대비로 읽는다 (recall_vs_photo = 렌더도 보이고 사진도 보인 점 / 사진에서 보인 점).
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from pathlib import Path
+
+import numpy as np
+
+
+@dataclass
+class LaneCheckConfig:
+    near_m: float = 5.0
+    far_m: float = 25.0
+    step_m: float = 0.5
+    profile_m: float = 1.2      # 단면 반폭 (지면 m)
+    search_m: float = 0.35      # 능선을 찾는 가운데 창 반폭
+    contrast: float = 0.06      # 능선 − 주변 중앙값 (0~1 밝기)
+    cams: tuple = ("CAM_FRONT",)
+    layers: tuple = ("lane_divider", "road_divider")
+
+
+def _gray(path: Path) -> np.ndarray:
+    from PIL import Image
+
+    return np.asarray(Image.open(path).convert("L"), np.float32) / 255
+
+
+def map_lines(scene, margin: float = 40.0) -> list[np.ndarray]:
+    from nusim.maps.expansion import BBox, MapExpansion
+    from nusim.paths import dataset
+
+    ego = np.array([f.ego_translation for f in scene.frames["CAM_FRONT"]])
+    box = BBox(ego[:, 0].min() - margin, ego[:, 1].min() - margin, ego[:, 0].max() + margin, ego[:, 1].max() + margin)
+    feats = MapExpansion(scene.location, dataset()).features(box)
+    out = []
+    for layer in LaneCheckConfig.layers:
+        for pl in feats.get(layer, []):
+            pl = np.asarray(pl, np.float64)[:, :2]
+            d = np.r_[0, np.cumsum(np.linalg.norm(np.diff(pl, axis=0), axis=1))]
+            t = np.arange(0, d[-1], 0.5)
+            if len(t) >= 2:
+                out.append(np.c_[np.interp(t, d, pl[:, 0]), np.interp(t, d, pl[:, 1])])
+    return out
+
+
+def sample_points(pose, lines: list[np.ndarray], ground_z: float, cfg: LaneCheckConfig):
+    """(u, v, 단면 방향 (du, dv) 픽셀/m) — 지면 위 차선 표본점 중 보이는 것."""
+    w2c, K = pose.w2c, pose.K
+    out = []
+    for pl in lines:
+        tang = np.gradient(pl, axis=0)
+        tang /= np.linalg.norm(tang, axis=1, keepdims=True) + 1e-9
+        nrm = np.c_[-tang[:, 1], tang[:, 0]]
+        P = np.c_[pl, np.full(len(pl), ground_z), np.ones(len(pl))]
+        Pn = np.c_[pl + 0.1 * nrm, np.full(len(pl), ground_z), np.ones(len(pl))]
+        c, cn = (w2c @ P.T).T, (w2c @ Pn.T).T
+        ok = (c[:, 2] > cfg.near_m) & (c[:, 2] < cfg.far_m)
+        for i in np.nonzero(ok)[0]:
+            uv = K @ c[i, :3]
+            uvn = K @ cn[i, :3]
+            u, v = uv[:2] / uv[2]
+            un, vn = uvn[:2] / uvn[2]
+            if 2 <= u < pose.width - 2 and 2 <= v < pose.height - 2:
+                out.append((u, v, (un - u) / 0.1, (vn - v) / 0.1))
+    return out
+
+
+def ridge(img: np.ndarray, u, v, du, dv, cfg: LaneCheckConfig) -> tuple[bool, int]:
+    """(가운데 창에 능선이 있나, 창 안 능선 수)."""
+    s = np.linspace(-cfg.profile_m, cfg.profile_m, 49)
+    x, y = u + s * du, v + s * dv
+    h, w = img.shape
+    keep = (x >= 0) & (x < w - 1) & (y >= 0) & (y < h - 1)
+    if keep.sum() < 30:
+        return False, 0
+    xi, yi = np.clip(x, 0, w - 1).astype(int), np.clip(y, 0, h - 1).astype(int)
+    prof = img[yi, xi]
+    base = np.median(prof[keep])
+    mid = keep & (np.abs(s) <= cfg.search_m)
+    lift = prof - base
+    hit = mid & (lift > cfg.contrast)
+    if not hit.any():
+        return False, 0
+    runs = np.diff(np.r_[0, hit.astype(int), 0])
+    return True, int((runs == 1).sum())
+
+
+def check_scene(scene_name: str, sources: dict[str, Path], variants: dict[str, dict], cfg: LaneCheckConfig | None = None,
+                keyframes: bool = True) -> dict:
+    """sources: 이름 → 영상 디렉터리 (<dir>/<CAM>/<원본 파일명>), 'photo' 는 데이터셋 원본. variants: 이름 → 리그 변형
+    (그 소스의 카메라 포즈). 결과: 소스마다 표본점 수 · 보임 비율 · 사진 대비 재현율 · 이중선 비율."""
+    from nusim.aug.rig_aug import transform_calib
+    from nusim.data.index import load_scene
+    from nusim.data.rig import camera_pose
+    from nusim.paths import dataset
+
+    cfg = cfg or LaneCheckConfig()
+    scene = load_scene(scene_name)
+    ds = dataset()
+    lines = map_lines(scene)
+    res = {}
+    for name, d in sources.items():
+        var = variants.get(name, {})
+        st = {"points": 0, "visible": 0, "double": 0, "photo_visible": 0, "both": 0}
+        for cam in cfg.cams:
+            calib = transform_calib(scene.calib[cam], var.get("shift_m", (0, 0, 0)), var.get("rot_deg", (0, 0, 0)))
+            calib0 = scene.calib[cam]
+            for fr in scene.frames[cam]:
+                if keyframes and not fr.is_keyframe:
+                    continue
+                p = (ds.root / fr.filename) if d is None else d / cam / Path(fr.filename).name
+                if not p.exists():
+                    continue
+                img = _gray(p)
+                pose = camera_pose(fr, calib, cam)
+                gz = fr.ego_translation[2]
+                pts = sample_points(pose, lines, gz, cfg)
+                photo = None
+                if d is not None and not var:  # 같은 포즈의 사진과 점마다 짝지어 재현율
+                    photo = _gray(ds.root / fr.filename)
+                for u, v, du, dv in pts:
+                    vis, n = ridge(img, u, v, du, dv, cfg)
+                    st["points"] += 1
+                    st["visible"] += vis
+                    st["double"] += n >= 2
+                    if photo is not None:
+                        pv, _ = ridge(photo, u, v, du, dv, cfg)
+                        st["photo_visible"] += pv
+                        st["both"] += pv and vis
+        n = max(st["points"], 1)
+        res[name] = {**st, "visible_rate": st["visible"] / n, "double_rate": st["double"] / max(st["visible"], 1)}
+        if st["photo_visible"]:
+            res[name]["recall_vs_photo"] = st["both"] / st["photo_visible"]
+    return res

src/nusim/nusim/aug/lane_fix.py

@@ -0,0 +1,219 @@
+"""차선 후처리 — ArtiFixer 증강 영상의 끊기고 흐린 차선을 실제 사진의 차선으로 바꾼다 (scripts/artifixer_lanefix.py).
+
+시점 변형은 같은 시각 · 같은 자차에서 카메라만 옮긴 것이다. 노면을 평면(자차 좌표 z = 0)으로 보면, 변형 카메라의 픽셀마다
+광선 → 노면 교점 → 원래 카메라로 투영해 **실제 사진**(1600×900)을 그 자리에 가져올 수 있다 (평면 호모그래피 — 평평한 노면이면
+기하가 정확하다). 그중 nuScenes HD 맵의 lane_divider · road_divider · ped_crossing · stop_line 주변(±band_m)만 바꾼다:
+맵은 '차선이 어디 있나' 만 주고, 차선의 모양(점선 간격 · 폭 · 색)은 실제 사진에서 온다 (맵에는 점선 간격 · 폭이 없고
+영상과 10~30 cm 어긋나서, 맵 선을 직접 그리면 실제와 안 맞는다).
+
+빼는 곳: 노면 교점이 max_dist_m 보다 먼 곳(작은 각도 오차가 크게 번진다), 원래 카메라 영상 밖, 실제 사진에서 차량 · 사람이
+가린 곳 (SegFormer-B5 Cityscapes — nusim.recon.sky 와 같은 모델), 실제 사진에서 노면 · 보도가 아닌 곳.
+합성: 띠 안 노면(차선 제외)의 평균 · 표준편차로 실제 사진 색을 ArtiFixer 영상 쪽으로 맞추고, 가장자리를 흐려 섞는다.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from pathlib import Path
+
+import numpy as np
+
+OPENGL_TO_OPENCV = np.diag([1.0, -1.0, -1.0, 1.0])
+MOVERS = ("car", "truck", "bus", "train", "motorcycle", "bicycle", "person", "rider")
+GROUND = ("road", "sidewalk")
+
+
+@dataclass
+class LaneFixConfig:
+    band_m: float = 0.6        # 맵 선 둘레 바꿀 띠 반폭
+    max_dist_m: float = 35.0   # 이보다 먼 노면은 그대로 (호모그래피 오차가 커진다)
+    feather_px: float = 12.0   # 합성 가장자리 섞는 폭 (영역 안쪽으로, 출력 해상도 픽셀)
+    contrast: float = 0.75     # 실제 사진 노면 대비를 ArtiFixer 쪽으로 맞추는 정도 (1 = 완전히)
+    mover_dilate_px: int = 9   # 실제 사진 차량 마스크 팽창 (원본 해상도)
+    layers: tuple = ("lane_divider", "road_divider", "ped_crossing", "stop_line")
+    mode: str = "road"         # road = 노면 전체를 실제 사진으로 (권장) · band = 맵 차선 띠만
+
+
+def map_points(scene, cfg: LaneFixConfig, step: float = 0.1, margin: float = 60.0) -> np.ndarray:
+    """맵 차선 요소를 전역 xy 점들로 (선은 0.1 m 간격, 다각형은 테두리 + 내부 격자)."""
+    from matplotlib.path import Path as MPath
+
+    from nusim.maps.expansion import BBox, MapExpansion
+    from nusim.paths import dataset
+
+    ego = np.array([f.ego_translation for f in scene.frames["CAM_FRONT"]])
+    box = BBox(ego[:, 0].min() - margin, ego[:, 1].min() - margin, ego[:, 0].max() + margin, ego[:, 1].max() + margin)
+    feats = MapExpansion(scene.location, dataset()).features(box)
+    pts = []
+    for layer in cfg.layers:
+        for pl in feats.get(layer, []):
+            pl = np.asarray(pl, np.float64)[:, :2]
+            d = np.r_[0, np.cumsum(np.linalg.norm(np.diff(pl, axis=0), axis=1))]
+            if d[-1] <= 0:
+                continue
+            t = np.arange(0, d[-1], step)
+            pts.append(np.c_[np.interp(t, d, pl[:, 0]), np.interp(t, d, pl[:, 1])])
+            if layer in ("ped_crossing", "stop_line") and len(pl) >= 3:  # 다각형 내부도 (횡단보도 줄무늬)
+                lo, hi = pl.min(0), pl.max(0)
+                gx, gy = np.meshgrid(np.arange(lo[0], hi[0], 0.3), np.arange(lo[1], hi[1], 0.3))
+                g = np.c_[gx.ravel(), gy.ravel()]
+                pts.append(g[MPath(pl).contains_points(g)])
+    return np.concatenate(pts) if pts else np.zeros((0, 2))
+
+
+class Segmenter:
+    def __init__(self):
+        import torch
+        from transformers import SegformerForSemanticSegmentation
+
+        from nusim.recon.sky import MODEL
+
+        self.torch = torch
+        self.model = SegformerForSemanticSegmentation.from_pretrained(MODEL).half().cuda().eval()
+        ids = {v.lower(): int(k) for k, v in self.model.config.id2label.items()}
+        self.movers = [ids[k] for k in MOVERS if k in ids]
+        self.ground = [ids[k] for k in GROUND if k in ids]
+        self.mean = torch.tensor([0.485, 0.456, 0.406], device="cuda")[:, None, None]
+        self.std = torch.tensor([0.229, 0.224, 0.225], device="cuda")[:, None, None]
+
+    def __call__(self, im: np.ndarray) -> np.ndarray:
+        """(H,W,3) uint8 → 클래스 번호 (H,W)."""
+        import torch.nn.functional as F
+
+        t = self.torch.as_tensor(im, device="cuda").permute(2, 0, 1).float() / 255
+        h, w = im.shape[:2]
+        t = F.interpolate(t[None], size=(576, 1024), mode="bilinear", align_corners=False)
+        with self.torch.no_grad():
+            lg = self.model(pixel_values=((t - self.mean) / self.std).half()).logits
+        lg = F.interpolate(lg.float(), size=(h, w), mode="bilinear", align_corners=False)[0]
+        return lg.argmax(0).cpu().numpy()
+
+
+def ground_lookup(c2w_v: np.ndarray, Kv: np.ndarray, size_v, plane_n: np.ndarray, plane_p: np.ndarray):
+    """변형 카메라 픽셀마다 노면 교점 (H,W,3) 과 거리 (H,W). 노면에 안 닿으면 nan."""
+    w, h = size_v
+    u, v = np.meshgrid(np.arange(w) + 0.5, np.arange(h) + 0.5)
+    d_cam = np.stack([(u - Kv[0, 2]) / Kv[0, 0], (v - Kv[1, 2]) / Kv[1, 1], np.ones_like(u)], -1)
+    R, o = c2w_v[:3, :3], c2w_v[:3, 3]
+    d = d_cam @ R.T
+    denom = d @ plane_n
+    t = ((plane_p - o) @ plane_n) / np.where(np.abs(denom) < 1e-9, np.nan, denom)
+    t = np.where(t > 0, t, np.nan)
+    X = o + d * t[..., None]
+    dist = t * np.linalg.norm(d_cam, axis=-1)
+    return X, dist
+
+
+def project(X: np.ndarray, c2w: np.ndarray, K: np.ndarray):
+    w2c = np.linalg.inv(c2w)
+    Xc = X @ w2c[:3, :3].T + w2c[:3, 3]
+    z = Xc[..., 2]
+    uv = (Xc[..., :2] / z[..., None]) * np.array([K[0, 0], K[1, 1]]) + np.array([K[0, 2], K[1, 2]])
+    return uv, z
+
+
+def bilinear(img: np.ndarray, uv: np.ndarray) -> np.ndarray:
+    import cv2
+
+    m = uv.astype(np.float32)
+    return cv2.remap(img, m[..., 0] - 0.5, m[..., 1] - 0.5, cv2.INTER_LINEAR, borderMode=cv2.BORDER_REPLICATE)
+
+
+def fix_image(art: np.ndarray, photo: np.ndarray, seg: np.ndarray, seg_ids: tuple, c2w_v, c2w_o, Kv, Ko,
+              plane_n, plane_p, origin_xy, tree, cfg: LaneFixConfig) -> tuple[np.ndarray, np.ndarray]:
+    """(후처리 영상, 바꾼 가중치 α) — art (h,w,3) 출력 해상도, photo (H,W,3) 원본 해상도."""
+    import cv2
+
+    h, w = art.shape[:2]
+    X, dist = ground_lookup(c2w_v, Kv, (w, h), plane_n, plane_p)
+    ok = np.isfinite(dist) & (dist < cfg.max_dist_m)
+    Xs = np.where(ok[..., None], X, 0)
+    if cfg.mode == "band":
+        dmap, _ = tree.query((Xs[..., :2] + origin_xy).reshape(-1, 2), distance_upper_bound=cfg.band_m)
+        ok &= np.isfinite(dmap.reshape(h, w))
+    uv, z = project(Xs, c2w_o, Ko)
+    H, W = photo.shape[:2]
+    ok &= (z > 0.5) & (uv[..., 0] >= 0) & (uv[..., 0] < W - 1) & (uv[..., 1] >= 0) & (uv[..., 1] < H - 1)
+    movers, ground = seg_ids
+    bad = np.isin(seg, movers).astype(np.uint8)
+    bad = cv2.dilate(bad, np.ones((cfg.mover_dilate_px, cfg.mover_dilate_px), np.uint8)) > 0
+    good = np.isin(seg, ground if cfg.mode == "band" else ground[:1]) & ~bad  # road 모드: 차도만 (보도는 15 cm 높아 평면이 아니다)
+    uvc = np.clip(np.nan_to_num(uv), 0, [W - 1, H - 1])
+    ok &= bilinear(good.astype(np.float32), uvc) > 0.99
+    if ok.sum() < 50:
+        return art, np.zeros((h, w), np.float32)
+    warped = bilinear(photo.astype(np.float32), uvc)
+    # 색 맞춤: 띠 안 노면(차선 페인트 = 밝은 상위 20% 제외)에서 채널별 평균 · 표준편차
+    lum_w, lum_a = warped.mean(-1), art.astype(np.float32).mean(-1)
+    road = ok & (lum_w < np.percentile(lum_w[ok], 80))
+    out = art.astype(np.float32).copy()
+    fixed = warped.copy()
+    for c in range(3):
+        mw, sw = warped[..., c][road].mean(), warped[..., c][road].std() + 1e-3
+        ma, sa = out[..., c][road].mean(), out[..., c][road].std() + 1e-3
+        k = cfg.contrast * (sa / sw) + (1 - cfg.contrast)  # 대비를 다 맞추면 차선이 흐려진다 — 일부만
+        fixed[..., c] = (warped[..., c] - mw) * k + ma
+    # 영역 경계(원래 카메라 시야 끝 · 연석 · 차량)에서 안쪽으로 feather_px 에 걸쳐 섞는다
+    inside = cv2.distanceTransform(ok.astype(np.uint8), cv2.DIST_L2, 5)
+    a = cv2.GaussianBlur(np.clip(inside / cfg.feather_px, 0, 1).astype(np.float32), (0, 0), 1.5) * ok
+    out = out * (1 - a[..., None]) + fixed * a[..., None]
+    _ = lum_a
+    return np.clip(out, 0, 255).astype(np.uint8), a
+
+
+def plane_of(frame, origin: np.ndarray) -> tuple[np.ndarray, np.ndarray]:
+    """자차 좌표 z = 0 평면 (씬 원점 기준 좌표의 법선 · 한 점)."""
+    from nusim.data.rig import quat_to_matrix
+
+    R = quat_to_matrix(frame.ego_rotation)
+    return R[:, 2], np.asarray(frame.ego_translation, np.float64) - origin
+
+
+def fix_prep_dir(prep_dir: Path, art_dir: Path, out_dir: Path, seg: Segmenter, scene, tree, cfg: LaneFixConfig,
+                 keyframes_only: bool = True, debug_dir: Path | None = None) -> int:
+    """준비 디렉터리 하나(구간 × 변형)의 고칠 프레임마다. art_dir = 그 변형의 ArtiFixer 결과 (<CAM>/<원본 파일명>.jpg)."""
+    from PIL import Image
+
+    from nusim.io.ply import read_origin
+    from nusim.paths import dataset
+
+    pm = json.loads((prep_dir / "prep.json").read_text())
+    tr = json.loads((prep_dir / "transforms.json").read_text())
+    origin = read_origin(Path(pm["model"]) / "point_cloud.ply")
+    frames = tr["frames"]
+    n = len(frames) // 2
+    Kv = np.array([[tr["fl_x"], 0, tr["cx"]], [0, tr["fl_y"], tr["cy"]], [0, 0, 1]], np.float64)
+    by_fn = {f.filename: f for f in scene.frames[pm["cam"]]}
+    calib = scene.calib[pm["cam"]]
+    Ko = np.asarray(calib.intrinsic, np.float64)
+    ds = dataset()
+    cnt = 0
+    for i in range(n):
+        ref, tgt = frames[i], frames[i + n]
+        fn = ref["original_filename"]
+        if keyframes_only and not fn.startswith("samples/"):
+            continue
+        src = art_dir / pm["cam"] / Path(fn).name
+        if not src.exists():
+            continue
+        art = np.asarray(Image.open(src).convert("RGB"))
+        photo = np.asarray(Image.open(ds.root / fn).convert("RGB"))
+        s = photo.shape[1] / tr["w"]  # 원래 카메라는 원본 해상도로 — 자세는 같고 K 만 키운다
+        Ko_s = Kv.copy()
+        Ko_s[:2] *= s
+        c2w_v = np.asarray(tgt["transform_matrix"]) @ OPENGL_TO_OPENCV
+        c2w_o = np.asarray(ref["transform_matrix"]) @ OPENGL_TO_OPENCV
+        pn, pp = plane_of(by_fn[fn], origin)
+        lab = seg(photo)
+        out, a = fix_image(art, photo, lab, (seg.movers, seg.ground), c2w_v, c2w_o, Kv, Ko_s, pn, pp,
+                           origin[:2], tree, cfg)
+        dst = out_dir / pm["cam"] / Path(fn).name
+        dst.parent.mkdir(parents=True, exist_ok=True)
+        Image.fromarray(out).save(dst, quality=95)
+        if debug_dir is not None:
+            debug_dir.mkdir(parents=True, exist_ok=True)
+            Image.fromarray((a * 255).astype(np.uint8)).save(debug_dir / (Path(fn).stem + "_alpha.png"))
+        cnt += 1
+    _ = Ko
+    return cnt

src/nusim/nusim/aug/map_aug.py

@@ -0,0 +1,115 @@
+"""맵 전체 시점 변형 증강 — 일괄 재구성(nusim recon batch)한 낮 씬들을 리그 변형으로 다시 찍는다.
+
+nusim aug rig 은 씬 하나를 모델 하나로 그린다. 맵 일괄 재구성에서는 긴 씬이 구간(seg<k>)으로 나뉘어 있으므로
+(nusim.recon.batch.plan_segments), CAM_FRONT 프레임마다 그 시각을 '맡는' 구간의 모델로 그린다. 맡는 구간은 이웃과
+겹치지 않는다 (겹침 10 m 의 가운데에서 자름) — 프레임마다 정확히 한 모델이고, 각 모델은 자기 학습 구간 안쪽만 그린다.
+
+결과: <out>/<scene>/<variant>/<CAM>/<원본 파일명>.jpg + meta.json (nusim aug rig 과 같은 형식 + segments·keyframes_only).
+같은 모델·설정으로 끝난 변형은 건너뛴다 (meta.json 의 model 목록 비교) — 일괄 학습을 따라가며 여러 번 불러도 된다.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import shutil
+from dataclasses import replace
+from pathlib import Path
+
+LOG = logging.getLogger(__name__)
+
+
+def assign_front_frames(scene, segs: list[dict]) -> list[list]:
+    """구간마다 맡는 CAM_FRONT 프레임 — 반열린 구간 [own0, own1) (마지막은 끝까지), 씬 시작 기준 마이크로초로 비교."""
+    start = min(f.timestamp for fs in scene.frames.values() for f in fs[:1])
+    front = scene.frames["CAM_FRONT"]
+    out = []
+    for i, s in enumerate(segs):
+        lo = -1 if s.get("own0") is None or i == 0 else start + round(s["own0"] * 1e6)
+        hi = None if s.get("own1") is None or i == len(segs) - 1 else start + round(s["own1"] * 1e6)
+        out.append([f for f in front if f.timestamp >= lo and (hi is None or f.timestamp < hi)])
+    return out
+
+
+def _stamp(d: Path) -> str:
+    p = d / "point_cloud.ply"
+    return f"{d}@{int(p.stat().st_mtime)}"
+
+
+def ensure_ibl(scene_name: str, segs: list[tuple[dict, Path]], log=LOG.info) -> None:
+    """glTF 차량을 다시 넣으려면 씬의 IBL(환경 조명)이 있어야 한다 (_ibl_gltf_args). 없으면 가운데 프레임을 맡는 구간 모델로 굽는다."""
+    from nusim.data.index import load_scene
+    from nusim.paths import output_dir
+    from nusim.render.ibl import bake_ibl
+
+    out = output_dir() / "ibl" / scene_name
+    if (out / "env_specular.ktx2").exists():
+        return
+    scene = load_scene(scene_name)
+    mid = len(scene.frames["CAM_FRONT"]) // 2
+    owned = assign_front_frames(scene, [s for s, _ in segs])
+    tmid = scene.frames["CAM_FRONT"][mid].timestamp
+    d = next((d for (s, d), fr in zip(segs, owned) if any(f.timestamp == tmid for f in fr)), segs[0][1])
+    # 구간 모델의 색 보정은 그 학습 구간의 뷰 수만큼이다 — 같은 구간으로 자른 씬을 넘긴다
+    from nusim.cli.main import _model_data
+
+    sub, _ = _model_data(scene_name, d)
+    front = sub.frames["CAM_FRONT"]
+    k = min(range(len(front)), key=lambda i: abs(front[i].timestamp - tmid))
+    log(f"  IBL 굽기 (모델 {d})")
+    bake_ibl(sub, d, out, frame=k)
+
+
+def aug_scene(scene_name: str, root: Path, variants: list[dict], out_root: Path, viewer: Path,
+              keyframes: bool = True, agents: bool = True, log=LOG.info) -> dict:
+    from nusim.aug.rig_aug import keyframes_only, render_frames, variant_meta
+    from nusim.cli.main import _ibl_gltf_args
+    from nusim.data.index import load_scene
+    from nusim.recon.batch import segment_dirs
+
+    segs = segment_dirs(root, scene_name)
+    if not segs:
+        raise FileNotFoundError(f"{root / scene_name} 에 학습된 모델이 없다")
+    if len(segs) != segs[0][0]["n"]:
+        raise RuntimeError(f"{scene_name}: 구간 {segs[0][0]['n']}개 중 {len(segs)}개만 학습됨")
+    if agents:
+        ensure_ibl(scene_name, segs, log)
+    extra = _ibl_gltf_args(scene_name, agents=True) if agents else []
+    scene = load_scene(scene_name)
+    owned = assign_front_frames(scene, [s for s, _ in segs])
+    base = keyframes_only(scene) if keyframes else scene
+    models = [_stamp(d) for _, d in segs]
+    summary = {}
+    for v in variants:
+        out = out_root / scene_name / v["name"]
+        meta_path = out / "meta.json"
+        if meta_path.exists():
+            old = json.loads(meta_path.read_text())
+            if old.get("model") == models and old.get("keyframes_only") == keyframes and old.get("variant") == v \
+                    and old.get("agents") == agents:
+                summary[v["name"]] = len(old["samples"])
+                continue
+        if out.exists():
+            shutil.rmtree(out)
+        samples, seg_meta, offset = [], [], 0
+        for (s, d), fr in zip(segs, owned):
+            keep = {f.timestamp for f in fr}
+            front = [f for f in base.frames["CAM_FRONT"] if f.timestamp in keep]
+            if not front:
+                continue
+            sub = replace(base, frames={**base.frames, "CAM_FRONT": front})
+            got = render_frames(sub, d, v, out, viewer, extra)
+            (out / "rig.txt").rename(out / f"rig_seg{s['k']}.txt")
+            for x in got:
+                x["frame"] += offset
+                x["segment"] = s["k"]
+            offset += len(front)
+            samples += got
+            seg_meta.append({"k": s["k"], "own0": s.get("own0"), "own1": s.get("own1"), "model": str(d),
+                             "front_frames": len(front), "images": len(got)})
+        meta = variant_meta(scene, v, models, samples)
+        meta.update(keyframes_only=keyframes, agents=agents, segments=seg_meta)
+        meta_path.write_text(json.dumps(meta, indent=1, ensure_ascii=False))
+        summary[v["name"]] = len(samples)
+        log(f"  {v['name']:<14} {len(samples):,}장 (구간 {len(seg_meta)}개) → {out}")
+    return summary

src/nusim/nusim/aug/rig_aug.py

@@ -0,0 +1,170 @@
+"""카메라 리그 변형 증강 — 재구성한 낮 장면을 6캠 시점을 바꿔 다시 찍는다.
+
+같은 주행(같은 시각·같은 자차 궤적)을 카메라 장착 위치·자세만 바꿔 렌더한다: 옆 차선 쪽으로 이동, 더 높은/낮은
+차, 아래로 숙임, 좌우로 돌림 (configs/aug/rig_variants.json). 6캠 전체에 같은 변형을 주므로 리그 기하가 일관된다.
+
+방법: 씬 인덱스의 카메라 캘리브레이션(cam → ego)만 바꾼 사본으로 뷰어 리그(rig.txt)를 만들고
+(nusim.render.export.write_rig — 학습이 보정한 외부 파라미터도 그대로 적용), vkgs_viewer --offscreen 으로 렌더한다.
+결과: outputs/aug/rig/<scene>/<variant>/
+    <CAM>/<원본 파일명>.jpg   원본과 같은 이름 — CAM_FRONT 프레임마다 각 카메라의 가장 가까운 장 (rig.txt 와 같은 대응).
+                            원본 sweep 전부는 아니다 (카메라마다 약 12 Hz 중 CAM_FRONT 시각에 가까운 것만)
+    meta.json               변형, 바뀐 calibrated_sensor (cam → ego, nuScenes 형식), 장마다 원본 파일·시각·자차 포즈
+    rig.txt                 렌더에 쓴 리그
+원본 데이터셋에는 쓰지 않는다.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import shutil
+import subprocess
+from dataclasses import replace
+from pathlib import Path
+
+import numpy as np
+
+from nusim.data.rig import matrix_to_quat, quat_to_matrix
+
+LOG = logging.getLogger(__name__)
+RENDER_ATTEMPTS = 3  # 깨진 PNG 가 나오면 구간을 다시 렌더하는 횟수 (render_frames)
+
+
+def _broken_pngs(d: Path) -> list[Path]:
+    """d 의 PNG 중 끝까지 디코딩되지 않는 것 (zlib 검사합 포함)."""
+    from PIL import Image
+
+    bad = []
+    for p in sorted(d.glob("*.png")):
+        try:
+            with Image.open(p) as im:
+                im.load()
+        except OSError:
+            bad.append(p)
+    return bad
+
+
+def _rx(a: float) -> np.ndarray:
+    c, s = np.cos(a), np.sin(a)
+    return np.array([[1, 0, 0], [0, c, -s], [0, s, c]])
+
+
+def _rz(a: float) -> np.ndarray:
+    c, s = np.cos(a), np.sin(a)
+    return np.array([[c, -s, 0], [s, c, 0], [0, 0, 1]])
+
+
+def transform_calib(calib, shift_m=(0, 0, 0), rot_deg=(0, 0, 0)):
+    """CameraCalib (cam → ego) 에 리그 변형을 준다.
+    shift_m: ego 좌표 [x 앞, y 왼쪽, z 위] 이동. rot_deg: [roll, pitch, yaw] —
+    pitch + = 카메라가 아래로 숙인다 (카메라 자신의 가로축), yaw + = 왼쪽으로 (ego z 축, 리그 전체가 같이),
+    roll = 카메라 광축 둘레. 카메라 좌표는 OpenCV (x 오른쪽, y 아래, z 앞) — rig.py 와 같다."""
+    roll, pitch, yaw = np.radians(np.asarray(rot_deg, dtype=np.float64))
+    R = quat_to_matrix(calib.rotation)
+    # 카메라 x 축 둘레 +θ 는 광축(z)을 위(-y)로 든다 → 숙이려면 -pitch
+    R2 = _rz(yaw) @ R @ _rx(-pitch) @ _rz(roll)
+    t2 = np.asarray(calib.translation, dtype=np.float64) + np.asarray(shift_m, dtype=np.float64)
+    return replace(calib, rotation=matrix_to_quat(R2), translation=tuple(float(x) for x in t2))
+
+
+def load_variants(path: Path, names: list[str] | None = None) -> list[dict]:
+    vs = [v for v in json.loads(path.read_text())["variants"]]
+    if names:
+        missing = set(names) - {v["name"] for v in vs}
+        if missing:
+            raise ValueError(f"변형이 없음: {sorted(missing)} (있는 것: {[v['name'] for v in vs]})")
+        vs = [v for v in vs if v["name"] in names]
+    return vs
+
+
+def keyframes_only(scene):
+    """키프레임(2 Hz sample)만 남긴 사본. rig_frames 는 CAM_FRONT 시각에 가장 가까운 장을 고르므로, 모든 카메라를
+    키프레임으로 줄이면 같은 sample 의 6장이 짝지어진다."""
+    return replace(scene, frames={c: [f for f in fs if f.is_keyframe] for c, fs in scene.frames.items()})
+
+
+def render_frames(scene, model_dir: Path, variant: dict, out: Path, viewer: Path,
+                  extra_args: list[str] | None = None, jpeg_quality: int = 95) -> list[dict]:
+    """scene(구간·키프레임으로 줄인 사본이어도 됨)의 CAM_FRONT 프레임마다 6캠을 리그 변형으로 렌더해
+    out/<CAM>/<원본 파일명>.jpg 로 쓴다. 장마다 메타 목록을 돌려준다 (frame 은 이 호출 안의 번호)."""
+    from PIL import Image
+
+    from nusim.cli.main import _model_objects
+    from nusim.io.ply import read_origin
+    from nusim.render.export import load_camera_adjust, rig_frames, write_rig
+
+    vscene = replace(scene, calib={cam: transform_calib(c, variant.get("shift_m", (0, 0, 0)), variant.get("rot_deg", (0, 0, 0)))
+                                   for cam, c in scene.calib.items()})
+    out.mkdir(parents=True, exist_ok=True)
+    origin = read_origin(model_dir / "point_cloud.ply")
+    write_rig(out / "rig.txt", vscene, origin, load_camera_adjust(model_dir), objects=_model_objects(model_dir))
+    tmp = out / "_png"
+    # 데이터셋용: 화면 공간 AA 없음 — 실제 카메라 영상처럼. 하늘: 날씨가 없으면 학습기와 같은 하늘(하늘 가우시안 유지,
+    # 하늘 큐브맵을 학습한 모델이면 그 큐브맵), 날씨 변형이면 낮 하늘 가우시안을 빼고 시뮬레이션 하늘
+    cmd = [str(viewer), str(model_dir / "point_cloud.ply"), "--cams", str(out / "rig.txt"), "--offscreen",
+           "--out", str(tmp), "--pass", "fxaa=off"]
+    if (model_dir / "objects" / "objects.json").exists():  # 차량을 함께 학습한 모델 — 차량 에셋도 같은 시점에서
+        cmd += ["--objects", str(model_dir / "objects")]
+    if variant.get("weather"):
+        cmd += ["--weather", variant["weather"]]
+    else:
+        cmd += ["--keep-sky-gaussians"]
+        if (model_dir / "sky.ktx2").exists():
+            cmd += ["--sky", str(model_dir / "sky.ktx2")]
+    cmd += extra_args or []
+    # 렌더는 결정적인데 PNG 가 가끔 깨진다 — 다시 렌더한 것과 1비트 차이 (2026-10-12, scene-0017·0036: ECC 없는 메모리의
+    # 비트 뒤집힘으로 본다). zlib 검사합이 잡으므로 PNG 를 다 열어 보고, 깨졌으면 그 구간을 한 번 더 렌더한다
+    for attempt in range(RENDER_ATTEMPTS):
+        if tmp.exists():
+            shutil.rmtree(tmp)
+        r = subprocess.run(cmd, capture_output=True, text=True)
+        if r.returncode != 0:
+            raise RuntimeError(f"vkgs_viewer 실패:\n{r.stdout[-2000:]}\n{r.stderr[-2000:]}")
+        bad = _broken_pngs(tmp)
+        if not bad:
+            break
+        LOG.warning(f"  깨진 PNG {len(bad)}장 ({bad[0].name}) — 다시 렌더 ({attempt + 2}/{RENDER_ATTEMPTS})")
+    else:
+        raise RuntimeError(f"PNG 가 {RENDER_ATTEMPTS}번 다 깨짐: {bad[:3]}")
+    samples, done = [], set()
+    for k, cam, fr in rig_frames(scene):
+        src = tmp / f"f{k:04d}_{cam}.png"
+        # rig 는 CAM_FRONT 프레임마다 각 카메라의 가장 가까운 장을 고르므로 같은 장이 두 번 뽑힐 수 있다 — 한 번만
+        if not src.exists() or fr.filename in done:
+            continue
+        done.add(fr.filename)
+        dst = out / cam / Path(fr.filename).name
+        dst.parent.mkdir(parents=True, exist_ok=True)
+        Image.open(src).convert("RGB").save(dst, quality=jpeg_quality)
+        samples.append({"frame": k, "cam": cam, "timestamp": fr.timestamp, "is_keyframe": fr.is_keyframe,
+                        "original_filename": fr.filename, "filename": str(dst.relative_to(out)),
+                        "ego_translation": list(fr.ego_translation), "ego_rotation": list(fr.ego_rotation)})
+    shutil.rmtree(tmp)
+    return samples
+
+
+def variant_meta(scene, variant: dict, models, samples: list[dict]) -> dict:
+    vscene_calib = {cam: transform_calib(c, variant.get("shift_m", (0, 0, 0)), variant.get("rot_deg", (0, 0, 0)))
+                    for cam, c in scene.calib.items()}
+    return {
+        "scene": scene.name, "variant": variant, "model": models,
+        "calibrated_sensor": {cam: {"translation": list(c.translation), "rotation": list(c.rotation),
+                                    "camera_intrinsic": [list(r) for r in c.intrinsic]}
+                              for cam, c in vscene_calib.items()},
+        "note": "calibrated_sensor = 바뀐 cam → ego (nuScenes 형식, 학습 보정 전). 자차 포즈는 원본 그대로.",
+        "samples": samples,
+    }
+
+
+def render_variant(scene_name: str, model_dir: Path, variant: dict, out_root: Path, viewer: Path,
+                   extra_args: list[str] | None = None, jpeg_quality: int = 95, log=LOG.info) -> dict:
+    """씬 전체를 모델 하나로 (nusim aug rig). 구간 모델로 나눈 씬은 nusim.aug.map_aug."""
+    from nusim.data.index import load_scene
+
+    scene = load_scene(scene_name)
+    out = out_root / scene_name / variant["name"]
+    samples = render_frames(scene, model_dir, variant, out, viewer, extra_args, jpeg_quality)
+    meta = variant_meta(scene, variant, str(model_dir), samples)
+    (out / "meta.json").write_text(json.dumps(meta, indent=1, ensure_ascii=False))
+    log(f"  {variant['name']:<20} {len(samples):,}장 → {out}")
+    return meta

src/nusim/nusim/aug/translate.py

@@ -0,0 +1,117 @@
+"""밤·비 → 낮 영상 변환 — 낮 씬만으로는 못 덮는 지역(싱가포르 야간·우천 씬)을 재구성할 수 있게.
+
+모델: CycleGAN-Turbo (img2img-turbo, Parmar et al. 2024, MIT 코드 / SD-Turbo 가중치 연구용) 의 BDD100K 주행 영상
+사전학습 체크포인트 night_to_day, rainy_to_clear. third_party/img2img-turbo, 체크포인트는 cache/models/img2img-turbo
+(cache/models/img2img-turbo/fetch.sh 로 병렬 다운로드 — 개당 1.7 GB).
+
+결과는 원본과 같은 상대 경로로 outputs/aug/translate/<model>/samples|sweeps/... 에 쓴다. 재구성은
+`nusim recon train <scene> --image-root outputs/aug/translate/<model>` — 이미지만 바뀌고 라이다·포즈는 원본이다.
+원본 데이터셋에는 쓰지 않는다.
+
+알고 쓰자: 프레임마다 따로 변환하므로 시간 깜빡임·카메라 사이 불일치가 있다. 3DGS 는 여러 뷰의 평균을 배우므로
+조금은 견디지만, 결과는 재구성 PSNR·육안으로 확인한다.
+"""
+
+from __future__ import annotations
+
+import logging
+import sys
+import time
+from pathlib import Path
+
+import numpy as np
+
+LOG = logging.getLogger(__name__)
+ROOT = Path(__file__).resolve().parents[4]
+CKPT_DIR = ROOT / "cache" / "models" / "img2img-turbo"
+MODELS = {"night_to_day": "night2day.pkl", "rainy_to_clear": "rainy2clear.pkl"}
+
+
+def load_model(name: str):
+    import torch
+
+    if name not in MODELS:
+        raise ValueError(f"모르는 변환 '{name}' (있는 것: {list(MODELS)})")
+    if not (CKPT_DIR / MODELS[name]).exists():
+        raise FileNotFoundError(f"{CKPT_DIR / MODELS[name]} 가 없습니다: bash {CKPT_DIR / 'fetch.sh'} {MODELS[name][:-4]}")
+    src = str(ROOT / "third_party" / "img2img-turbo" / "src")
+    if src not in sys.path:
+        sys.path.append(src)  # nusim 보다 뒤 — 그쪽 모듈 이름과 겹치지 않게
+    from cyclegan_turbo import CycleGAN_Turbo
+
+    # 원래 코드는 fp32 로 GPU 에 올린 뒤 줄인다 (4.4 GB) — 8 GB GPU 에서 학습과 같이 못 돈다.
+    # 생성 중 Module.cuda 를 잠시 막아 CPU 에서 만들고, fp16 으로 바꾼 뒤 올린다 (약 2 GB).
+    # 체크포인트(1.7 GB fp32)도 GPU 로 저장돼 있어 torch.load 가 바로 올린다 → CPU 로 읽게.
+    real_cuda, real_load = torch.nn.Module.cuda, torch.load
+    torch.nn.Module.cuda = lambda self, *a, **k: self
+    torch.load = lambda f, *a, **k: real_load(f, *a, **{**k, "map_location": "cpu", "weights_only": False})
+    try:
+        m = CycleGAN_Turbo(pretrained_name=name, ckpt_folder=str(CKPT_DIR))
+    finally:
+        torch.nn.Module.cuda, torch.load = real_cuda, real_load
+    m = m.eval().half().cuda()
+    m.requires_grad_(False)
+    return m
+
+
+def translate_image(model, img, size: tuple[int, int]):
+    """PIL 이미지 → 변환한 PIL 이미지 (원래 크기로). size = 모델 입력 (8의 배수)."""
+    import torch
+    from PIL import Image
+    from torchvision import transforms
+
+    x = transforms.ToTensor()(img.resize(size, Image.LANCZOS))
+    x = (x * 2 - 1).unsqueeze(0).cuda().half()
+    with torch.no_grad():  # 전역 grad 설정은 건드리지 않는다 (같은 프로세스의 학습을 망치지 않게)
+        y = model(x)
+    out = ((y[0].float().clamp(-1, 1) + 1) * 127.5).round().byte().permute(1, 2, 0).cpu().numpy()
+    return Image.fromarray(out).resize(img.size, Image.LANCZOS)
+
+
+def translate_scene(scene_name: str, models: list[str], out_root: Path, size=(912, 512), cameras=None,
+                    stride: int = 1, keyframes_only: bool = False, quality: int = 95, log=LOG.info) -> dict:
+    """씬의 카메라 영상을 models 순서대로 변환 (예: rainy_to_clear 다음 night_to_day). 이미 있는 파일은 건너뛴다."""
+    from PIL import Image
+
+    from nusim import CAMERAS
+    from nusim.data.index import load_scene
+    from nusim.paths import dataset
+
+    scene, ds = load_scene(scene_name), dataset()
+    cams = cameras or CAMERAS
+    frames = []
+    for cam in cams:
+        fr = scene.keyframes(cam) if keyframes_only else scene.frames[cam]
+        frames += fr[::stride]
+    tag = "+".join(models)
+    out = out_root / tag
+    todo = [f for f in frames if not (out / f.filename).exists()]
+    log(f"  {scene_name}: {len(frames):,}장 중 {len(todo):,}장 변환 ({tag}, 입력 {size[0]}x{size[1]}) → {out}")
+    if not todo:
+        return {"n": len(frames), "done": 0, "out": str(out)}
+    # 모델은 하나씩만 올린다 (fp16 하나에 약 2.2 GB — 8 GB GPU 에서 학습과 같이 돌게). 연쇄 변환은 단계별로:
+    # 앞 단계 결과를 out/_stage<i>/ 에 두고 다음 단계가 읽는다.
+    import shutil
+
+    import torch
+
+    t0 = time.time()
+    src_root = ds.root
+    for si, name in enumerate(models):
+        last = si == len(models) - 1
+        dst_root = out if last else out / f"_stage{si}_{scene_name}"  # 씬마다 따로 (동시에 돌려도 서로 안 지우게)
+        net = load_model(name)
+        for i, f in enumerate(todo):
+            img = Image.open(src_root / f.filename).convert("RGB")  # 원본은 읽기만
+            img = translate_image(net, img, size)
+            dst = dst_root / f.filename
+            dst.parent.mkdir(parents=True, exist_ok=True)
+            img.save(dst, quality=quality if last else 98)
+            if i % 200 == 0:
+                log(f"    [{name}] {i:,}/{len(todo):,}  {(time.time() - t0) / max(i + si * len(todo), 1):.2f}s/장")
+        del net
+        torch.cuda.empty_cache()
+        if si > 0:
+            shutil.rmtree(src_root)  # 앞 단계 임시 결과
+        src_root = dst_root
+    return {"n": len(frames), "done": len(todo), "out": str(out), "s_per_image": (time.time() - t0) / len(todo)}

src/nusim/nusim/cli/__init__.py

@@ -0,0 +1 @@
+"""커맨드라인 진입점."""

src/nusim/nusim/cli/doctor.py

@@ -0,0 +1,255 @@
+"""vkgs-doctor — 컨테이너 환경이 실제로 쓸 수 있는 상태인지 한 번에 점검한다.
+
+이게 따로 있는 이유: 이 스택은 조용히 반쯤 망가지는 방식이 여럿이다.
+  - nvidia-container-toolkit 은 있는데 DRIVER_CAPABILITIES 에 graphics 가 빠지면
+    CUDA 는 되고 Vulkan 만 GPU 를 0개로 본다. 에러 없이 검은 화면만 나온다.
+  - NFS 가 잠깐 끊기면 데이터셋 경로가 '없는 것처럼' 보인다.
+  - gsplat 의 CUDA 확장이 빌드는 됐는데 아키텍처가 안 맞으면 첫 backward 에서야 터진다.
+학습을 40분 돌린 뒤에 아는 것보다 여기서 아는 게 낫다.
+"""
+
+from __future__ import annotations
+
+import os
+import platform
+import shutil
+import subprocess
+import sys
+
+_OK, _WARN, _FAIL = "✔", "!", "✘"
+_C = {"✔": "\033[1;32m", "!": "\033[1;33m", "✘": "\033[1;31m"}
+_RESET = "\033[0m"
+
+_failures = 0
+_warnings = 0
+
+
+def _line(status: str, label: str, detail: str = "") -> None:
+    global _failures, _warnings
+    if status == _FAIL:
+        _failures += 1
+    elif status == _WARN:
+        _warnings += 1
+    color = _C.get(status, "")
+    print(f"  {color}{status}{_RESET} {label:<22} {detail}")
+
+
+def _head(title: str) -> None:
+    print(f"\n\033[1;36m{title}\033[0m")
+
+
+def _run(cmd: list[str], timeout: int = 20) -> tuple[int, str]:
+    try:
+        p = subprocess.run(cmd, capture_output=True, text=True, timeout=timeout)
+        return p.returncode, (p.stdout or "") + (p.stderr or "")
+    except FileNotFoundError:
+        return 127, "실행파일 없음"
+    except subprocess.TimeoutExpired:
+        return 124, "시간 초과"
+
+
+# --------------------------------------------------------------------------- 검사들
+def check_runtime() -> None:
+    _head("런타임")
+    _line(_OK, "python", f"{platform.python_version()}  ({sys.executable})")
+    _line(_OK, "platform", f"{platform.system()} {platform.release()}")
+    in_docker = os.path.exists("/.dockerenv")
+    in_local = os.environ.get("CONDA_DEFAULT_ENV") == "vkgs"
+    if in_docker:
+        _line(_OK, "실행 환경", "Docker 컨테이너")
+    elif in_local:
+        _line(_OK, "실행 환경", f"로컬 micromamba 'vkgs'  ({os.environ.get('CONDA_PREFIX', '')})")
+    else:
+        _line(_WARN, "실행 환경", "컨테이너도 vkgs 환경도 아님 — source scripts/local_env.sh 를 했는지 확인하세요")
+
+
+def check_cuda() -> None:
+    _head("CUDA / PyTorch")
+    try:
+        import torch
+    except ImportError as e:
+        _line(_FAIL, "torch", f"임포트 실패: {e}")
+        return
+    _line(_OK, "torch", torch.__version__)
+
+    if not torch.cuda.is_available():
+        _line(_FAIL, "cuda", "torch.cuda.is_available() == False  "
+                             "→ --gpus all 없이 컨테이너를 띄웠거나 드라이버 불일치")
+        return
+    n = torch.cuda.device_count()
+    _line(_OK, "cuda", f"{torch.version.cuda}, 장치 {n}개")
+    for i in range(n):
+        p = torch.cuda.get_device_properties(i)
+        cap = f"sm_{p.major}{p.minor}"
+        vram = p.total_memory / 1024**3
+        note = ""
+        if vram < 10:
+            note = "  ← 8 GB 급: 3DGS 학습 시 다운스케일/가우시안 수 제한 필요"
+        _line(_OK, f"gpu[{i}]", f"{p.name}  {vram:.1f} GB  {cap}{note}")
+
+    # 실제로 커널이 도는지. is_available() 만으로는 부족하다.
+    try:
+        a = torch.randn(256, 256, device="cuda")
+        torch.cuda.synchronize()
+        _line(_OK, "cuda 연산", f"검증 통과 ({float((a @ a.T).sum()):.3e})")
+    except Exception as e:
+        _line(_FAIL, "cuda 연산", f"{type(e).__name__}: {e}")
+
+
+def check_gsplat() -> None:
+    _head("3DGS 학습 백엔드")
+    try:
+        import gsplat
+    except ImportError as e:
+        _line(_FAIL, "gsplat", f"임포트 실패: {e}")
+        return
+    _line(_OK, "gsplat", getattr(gsplat, "__version__", "?"))
+    try:
+        import torch
+        from gsplat import rasterization
+        if not torch.cuda.is_available():
+            _line(_WARN, "gsplat 래스터화", "CUDA 가 없어 건너뜀")
+            return
+        # 가우시안 1개짜리 최소 래스터화. CUDA 확장이 이 GPU 아키텍처로
+        # 실제 빌드됐는지 여기서 드러난다.
+        dev = "cuda"
+        means = torch.zeros(1, 3, device=dev); means[0, 2] = 5.0
+        quats = torch.tensor([[1.0, 0, 0, 0]], device=dev)
+        scales = torch.full((1, 3), 0.3, device=dev)
+        opac = torch.ones(1, device=dev)
+        colors = torch.ones(1, 3, device=dev)
+        viewmat = torch.eye(4, device=dev)[None]
+        K = torch.tensor([[[100.0, 0, 32.0], [0, 100.0, 32.0], [0, 0, 1.0]]], device=dev)
+        img, _, _ = rasterization(means, quats, scales, opac, colors, viewmat, K, 64, 64)
+        torch.cuda.synchronize()
+        _line(_OK, "gsplat 래스터화", f"출력 {tuple(img.shape)}, 최대값 {float(img.max()):.3f}")
+    except Exception as e:
+        _line(_FAIL, "gsplat 래스터화", f"{type(e).__name__}: {e}")
+
+
+def check_vulkan() -> None:
+    _head("Vulkan")
+    # 호스트는 /usr/share (드라이버 패키지), 컨테이너 이미지는 /etc 에 둔다 (docker/Dockerfile). VK_DRIVER_FILES 가 우선.
+    cands = [f for f in os.environ.get("VK_DRIVER_FILES", "").split(":") if f]
+    for icd_dir in ("/usr/share/vulkan/icd.d", "/etc/vulkan/icd.d"):
+        if os.path.isdir(icd_dir):
+            cands += [f"{icd_dir}/{f}" for f in sorted(os.listdir(icd_dir))]
+    nvidia_icd = [f for f in cands if "nvidia" in os.path.basename(f).lower() and os.path.isfile(f)]
+    if nvidia_icd:
+        _line(_OK, "NVIDIA ICD", nvidia_icd[0])
+    else:
+        _line(_FAIL, "NVIDIA ICD", "nvidia ICD 가 없습니다 (/usr/share · /etc vulkan/icd.d) — "
+                                   "NVIDIA_DRIVER_CAPABILITIES 에 graphics 가 빠졌을 가능성이 큽니다")
+
+    if not shutil.which("vulkaninfo"):
+        _line(_WARN, "vulkaninfo", "설치되지 않음 (vulkan-tools)")
+        return
+    rc, out = _run(["vulkaninfo", "--summary"])
+    if rc != 0:
+        _line(_FAIL, "vulkaninfo", f"종료코드 {rc}: {out.strip().splitlines()[-1][:120] if out.strip() else ''}")
+        return
+
+    gpus = [l.strip() for l in out.splitlines() if "deviceName" in l]
+    api = next((l.strip() for l in out.splitlines() if "apiVersion" in l), "")
+    if gpus:
+        _line(_OK, "Vulkan 장치", f"{len(gpus)}개")
+        for g in gpus:
+            _line(_OK, "", g)
+        if api:
+            _line(_OK, "apiVersion", api.split("=")[-1].strip())
+    else:
+        _line(_FAIL, "Vulkan 장치", "0개 — ICD 는 있는데 물리장치가 안 잡힙니다")
+
+    for tool, pkg in (("glslangValidator", "glslang-tools"), ("glslc", "glslc")):
+        if shutil.which(tool):
+            _line(_OK, f"셰이더 컴파일러", tool)
+            break
+    else:
+        _line(_FAIL, "셰이더 컴파일러", "glslangValidator / glslc 둘 다 없음")
+
+    if os.environ.get("DISPLAY"):
+        _line(_OK, "DISPLAY", os.environ["DISPLAY"] + "  (인터랙티브 뷰어 가능)")
+    else:
+        _line(_WARN, "DISPLAY", "없음 — 헤드리스. 오프라인 배치 렌더링은 정상 동작합니다")
+
+
+def check_dataset() -> None:
+    _head("nuScenes 데이터셋")
+    try:
+        from nusim.paths import dataset
+        ds = dataset()
+    except Exception as e:
+        _line(_FAIL, "데이터셋 루트", str(e).splitlines()[0])
+        return
+    _line(_OK, "루트", str(ds.root))
+    for name, (exists, path) in ds.check().items():
+        _line(_OK if exists else _FAIL, name, str(path) if not exists else "")
+
+    # NFS 는 마운트돼 보여도 응답이 죽어 있을 수 있다. 실제로 한 파일을 읽어 본다.
+    try:
+        import time
+        t = time.time()
+        (ds.meta / "scene.json").read_bytes()
+        _line(_OK, "읽기 시험", f"scene.json {(time.time()-t)*1000:.0f} ms")
+    except Exception as e:
+        _line(_FAIL, "읽기 시험", f"{type(e).__name__}: {e}")
+
+
+def check_index() -> None:
+    _head("씬 인덱스")
+    try:
+        from nusim.data.index import load_catalog
+        cat = load_catalog()
+    except FileNotFoundError:
+        _line(_WARN, "카탈로그", "아직 없음 —  nusim index build  를 실행하세요")
+        return
+    except Exception as e:
+        _line(_FAIL, "카탈로그", f"{type(e).__name__}: {e}")
+        return
+    import collections
+    by = collections.Counter(s["location"] for s in cat["scenes"])
+    total = sum(s["n_images"] for s in cat["scenes"])
+    _line(_OK, "카탈로그", f"씬 {len(cat['scenes'])}개 / 이미지 {total:,}장  (생성 {cat['built_at']})")
+    for loc, n in sorted(by.items()):
+        _line(_OK, "", f"{loc:26s} {n:4d} 씬")
+    if cat.get("dataset_root"):
+        from nusim.paths import nuscenes_root
+        cur = str(nuscenes_root())
+        if cat["dataset_root"] != cur:
+            _line(_WARN, "루트 불일치",
+                  f"인덱스는 {cat['dataset_root']} 기준으로 만들어졌는데 현재는 {cur} 입니다. "
+                  "파일 상대경로는 같으므로 보통 무해하지만, 이상하면 --force 로 재생성하세요.")
+
+
+def check_workspace() -> None:
+    _head("작업공간")
+    from nusim.paths import cache_dir, output_dir, workspace_root
+    _line(_OK, "workspace", str(workspace_root()))
+    for label, d in (("cache", cache_dir()), ("outputs", output_dir())):
+        writable = os.access(d, os.W_OK)
+        _line(_OK if writable else _FAIL, label,
+              str(d) if writable else f"{d}  ← 쓰기 불가. uid 불일치일 수 있습니다 (HOST_UID/.env 확인)")
+
+
+def main() -> int:
+    print("\033[1mvkgs-sim 환경 진단\033[0m")
+    for fn in (check_runtime, check_cuda, check_gsplat, check_vulkan,
+               check_dataset, check_index, check_workspace):
+        try:
+            fn()
+        except Exception as e:  # 한 항목이 터져도 나머지는 봐야 한다
+            _line(_FAIL, fn.__name__, f"검사 자체가 실패: {type(e).__name__}: {e}")
+
+    print()
+    if _failures:
+        print(f"\033[1;31m{_failures}개 실패\033[0m, {_warnings}개 경고")
+        return 1
+    if _warnings:
+        print(f"\033[1;33m문제 없음 ({_warnings}개 경고)\033[0m")
+        return 0
+    print("\033[1;32m모두 정상\033[0m")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

src/nusim/nusim/cli/main.py

@@ -0,0 +1,1487 @@
+"""nusim — 프로젝트 커맨드라인.
+
+typer/rich 가 아니라 argparse 로 쓴 이유: 이 CLI 는 컨테이너 밖 호스트에서도
+(의존성 설치 없이) 돌아야 진단에 쓸모가 있다. 표준 라이브러리만 쓴다.
+"""
+
+from __future__ import annotations
+
+import argparse
+import logging
+import sys
+from pathlib import Path
+
+
+LOG = logging.getLogger("nusim.cli")
+
+
+def _cmd_index_build(a: argparse.Namespace) -> int:
+    from nusim import SINGAPORE_MAPS
+    from nusim.data.index import build_index
+
+    locations = a.locations or list(SINGAPORE_MAPS)
+    build_index(
+        locations=locations,
+        include_sweeps=not a.no_sweeps,
+        force=a.force,
+    )
+    return 0
+
+
+def _cmd_index_list(a: argparse.Namespace) -> int:
+    from nusim.data.index import load_catalog
+
+    cat = load_catalog()
+    rows = cat["scenes"]
+    if a.location:
+        rows = [r for r in rows if r["location"] == a.location]
+    if a.grep:
+        g = a.grep.lower()
+        rows = [r for r in rows if g in r["description"].lower() or g in r["name"]]
+    if a.limit:
+        rows = rows[: a.limit]
+
+    print(f"{'scene':<12} {'location':<26} {'imgs':>6} {'sec':>6}  description")
+    print("-" * 100)
+    for r in rows:
+        print(f"{r['name']:<12} {r['location']:<26} {r['n_images']:>6} "
+              f"{r['duration_s']:>6.1f}  {r['description'][:44]}")
+    print(f"\n{len(rows)}개 씬 / 이미지 {sum(r['n_images'] for r in rows):,}장")
+    return 0
+
+
+def _cmd_scene_show(a: argparse.Namespace) -> int:
+    from nusim.data.index import load_scene
+    from nusim.paths import dataset
+
+    si = load_scene(a.name)
+    ds = dataset()
+    print(f"\n\033[1m{si.name}\033[0m  {si.location}")
+    print(f"  {si.description}")
+    print(f"  차량 {si.vehicle} / 촬영일 {si.date_captured} / {si.duration_s():.1f}초")
+    print(f"  키프레임 {si.nbr_samples}개 / 전체 이미지 {si.n_images:,}장\n")
+    print(f"  {'camera':<17} {'frames':>7} {'keyfr':>6} {'Hz':>6}  {'fx':>8} {'HFOV':>6}")
+    for cam, frames in si.frames.items():
+        if not frames:
+            continue
+        span = (frames[-1].timestamp - frames[0].timestamp) / 1e6
+        hz = (len(frames) - 1) / span if span > 0 else 0.0
+        c = si.calib[cam]
+        import math
+        fx = c.intrinsic[0][0]
+        hfov = math.degrees(2 * math.atan(c.width / (2 * fx)))
+        print(f"  {cam:<17} {len(frames):>7} {len(si.keyframes(cam)):>6} {hz:>6.1f}  {fx:>8.1f} {hfov:>5.1f}°")
+
+    f0 = si.frames["CAM_FRONT"][0]
+    print(f"\n  첫 프레임: {f0.filename}")
+    print(f"  존재 여부: {f0.path(ds).exists()}")
+    return 0
+
+
+def _cmd_recon_init(a: argparse.Namespace) -> int:
+    from nusim.data.index import load_scene
+    from nusim.io.ply import write_ply
+    from nusim.paths import dataset, output_dir
+    from nusim.recon.init import InitConfig, init_gaussians
+
+    import json
+
+    from nusim.recon.init import init_meta
+
+    cfg = InitConfig(voxel=a.voxel, max_points=a.max_points)
+    print(f"\033[1m{a.name}\033[0m 초기화")
+    g = init_gaussians(load_scene(a.name), dataset(), cfg)
+    path = write_ply(output_dir() / "gs" / a.name / "init.ply", g)
+    path.with_suffix(".json").write_text(json.dumps(init_meta(cfg), indent=2))
+    print(f"  → {path}")
+    return 0
+
+
+def _train_config(a: argparse.Namespace, **extra):
+    """recon train 옵션 → TrainConfig (단일 씬·타일 공용)."""
+    from nusim.recon.train import TrainConfig
+
+    mcmc = a.strategy == "mcmc"
+    return TrainConfig(iters=a.iters, max_gaussians=a.max_gaussians, depth_lambda=a.depth_lambda,
+                      depth_scale=a.depth_scale, strategy=a.strategy, sky=a.sky, objects=a.objects,
+                      downscale=a.downscale, frame_stride=a.stride, keyframes_only=a.keyframes_only,
+                      aniso_reg=a.aniso_reg, aniso_max=a.aniso_max,
+                      ground_lambda=getattr(a, "ground_lambda", 0.0),
+                      opacity_reg=a.opacity_reg if a.opacity_reg is not None else (0.01 if mcmc else 0.0),
+                      scale_reg=a.scale_reg if a.scale_reg is not None else (0.01 if mcmc else 0.0),
+                      # MCMC 는 cap 안에서 재배치만 하므로 오래 켜 둔다 (gsplat 기본 25k/30k ≈ 0.8)
+                      refine_stop=a.refine_stop or (int(0.8 * a.iters) if mcmc else min(15_000, a.iters // 2)),
+                      eval_every=a.eval_every, absgrad=a.absgrad,
+                      grow_grad2d=a.grow_grad2d or (0.0008 if a.absgrad else 0.0002),
+                      lr_camera=0.0 if a.no_camera_adjust else TrainConfig.lr_camera,
+                      time_window=a.time_window, **extra, image_root=str(Path(a.image_root).resolve()) if a.image_root else None)
+
+
+def _train_tile(a: argparse.Namespace, out: Path) -> int:
+    """여러 주행을 한 모델로 (recon.tile). a.name 은 무시하고 타일의 anchor 를 쓴다."""
+    import json
+
+    from nusim.io.ply import read_ply, write_ply
+    from nusim.log import run_log
+    from nusim.paths import dataset
+    from nusim.recon.init import InitConfig, init_meta
+    from nusim.recon.tile import ALIGN_VERSION, Tile, tile_init, tile_lidar, tile_scenes, tile_views
+    from nusim.recon.train import train
+
+    if a.objects == "vehicles":
+        raise SystemExit("타일 학습은 아직 --objects vehicles 를 지원하지 않는다 (주행마다 차량이 다르다) — agents 로")
+    tile, ds = Tile.load(a.tile), dataset()
+    if a.name != tile.anchor:
+        print(f"  타일 {tile.name} 의 기준 씬은 {tile.anchor} — {a.name} 대신 그걸 쓴다")
+    scenes = tile_scenes(tile)
+    icfg = InitConfig(sky_points=0 if a.sky else 30_000, objects=a.objects)
+    init_ply = out / "init.ply"
+    want = {**init_meta(icfg), "tile": json.loads(json.dumps(
+        {"train": tile.train, "center": tile.center.tolist(), "half_m": tile.half_m,
+         "align": ALIGN_VERSION if tile.align else 0}))}
+    meta_path = init_ply.with_suffix(".json")
+    out.mkdir(parents=True, exist_ok=True)
+    if not init_ply.exists() or not meta_path.exists() or json.loads(meta_path.read_text()) != want:
+        write_ply(init_ply, tile_init(tile, scenes, ds, icfg, max_total=icfg.max_points))
+        meta_path.write_text(json.dumps(want, indent=2))
+    init = read_ply(init_ply)
+    views = tile_views(scenes, ds, init.origin, objects=a.objects, downscale=a.downscale,
+                       frame_stride=a.stride, keyframes_only=a.keyframes_only)
+    pts = None
+    if a.depth_lambda > 0:
+        from nusim.recon.depth import lidar_depth_maps
+
+        pts = tile_lidar(scenes, ds, InitConfig(objects=a.objects), init.origin)
+        lidar_depth_maps(pts, views.train, scale=a.depth_scale)
+    if a.sky:
+        # 하늘 = 큐브맵 + 하늘 픽셀에서 스플랫 α→0. 날마다 하늘 밝기가 달라, 하늘을 따로 두지 않으면 가우시안이 부풀어
+        # 하늘을 덮다 카메라까지 감쌌다 (6주행 15k: 10 m 넘는 가우시안 685개, 자기 주행 평가 12.7 dB)
+        from nusim.recon.sky import sky_masks
+
+        for k, s in enumerate(scenes):
+            sky_masks([v for v in views.train if v.cam_id // 6 == k], ds, sky_mask_cache(s.name, ds))
+    cfg = _train_config(a, tile=tile.name, reg_visible=True)
+    with run_log(out / "run.log"):
+        LOG.info("타일 학습 %s (%d주행: %s, 뺀 주행 %s) → %s", tile.name, len(scenes), ", ".join(tile.train),
+                 ", ".join(tile.heldout) or "없음", out)
+        train(views, init, out, cfg, depth_points=pts)
+    return 0
+
+
+def _cmd_recon_tile_eval(a: argparse.Namespace) -> int:
+    import json
+
+    from nusim.log import run_log
+    from nusim.paths import dataset, output_dir
+    from nusim.recon.tile import Tile, tile_eval
+
+    tile = Tile.load(a.tile)
+    out = Path(a.out) if a.out else output_dir() / "tiles" / tile.name
+    out.mkdir(parents=True, exist_ok=True)
+    with run_log(out / "eval.log"):
+        res = tile_eval(tile, [Path(d) for d in a.dir], dataset(), stride=a.stride, save_dir=out / "renders")
+    (out / "eval.json").write_text(json.dumps(res, indent=2, ensure_ascii=False))
+    print(f"\n  뺀 주행 {', '.join(tile.heldout)} 의 실제 사진 (색 아핀 맞춤 후, 사람·차량 가림)")
+    print(f"  차선 변경 시점 = {tile.anchor} 의 같은 방향 카메라가 옆 6 m 안에 있는 뷰")
+    for d, r in res["models"].items():
+        dist = "  ".join(f"{k} {v['psnr']:.2f}/{v['ssim']:.3f}({v['n']})" for k, v in r["by_dist"].items() if v["n"])
+        print(f"  {Path(d).parent.name + '/' + Path(d).name:<36} PSNR {r['psnr']:.2f}  SSIM {r['ssim']:.4f}  "
+              f"| 옆 거리별 PSNR/SSIM: {dist}  | 전체 {r['all']['psnr']:.2f}")
+    print(f"  → {out / 'eval.json'}")
+    return 0
+
+
+def _cmd_recon_train(a: argparse.Namespace) -> int:
+    from nusim.data.index import load_scene
+    from nusim.io.ply import read_ply, write_ply
+    from nusim.paths import dataset, output_dir
+    from nusim.recon.dataset import build_views
+    from nusim.recon.init import init_gaussians
+    from nusim.recon.train import TrainConfig, train
+
+    out = Path(a.out) if a.out else output_dir() / "gs" / a.name
+    if a.tile:
+        return _train_tile(a, out)
+    scene, ds = load_scene(a.name), dataset()
+    if a.image_root:  # 카메라 이미지만 다른 곳에서 (밤·비 → 낮 변환 등, 같은 상대 경로)
+        from dataclasses import replace as _replace
+
+        ds = _replace(ds, image_root=Path(a.image_root))
+        print(f"  카메라 이미지 루트 {ds.images}")
+    if a.time_window:
+        t0, t1 = (float(x) for x in a.time_window.split(":"))
+        scene = scene.window(t0, t1)
+        print(f"  시간 구간 {t0:g}~{t1:g} 초 — 카메라 {scene.n_images}장, 라이다 {len(scene.lidar)}장")
+    # 초기화는 결과 디렉터리마다 따로 둔다 — 설정(sweep 여부 등)이 다른 실험이 서로의 init 을 쓰지 않게
+    init_ply = out / "init.ply"
+    print(f"\033[1m{a.name}\033[0m  {scene.description}")
+    import json
+
+    from nusim.recon.init import InitConfig, init_meta
+
+    # 하늘을 큐브맵으로 분리하면 먼 구면 가우시안(하늘 구)은 필요 없다 — 오히려 floater 원인
+    # vehicles: 배경 초기화·깊이 지도는 차량까지 뺀 라이다로 (차량은 객체 가우시안이 따로 맡는다 — recon.objects)
+    bg_objects = "agents" if a.objects == "vehicles" else a.objects
+    icfg = InitConfig(sky_points=0 if a.sky else 30_000, objects=bg_objects)
+    meta_path = init_ply.with_suffix(".json")
+    old_meta = json.loads(meta_path.read_text()) if meta_path.exists() else None
+    want_meta = {**init_meta(icfg), **({"time_window": a.time_window} if a.time_window else {}),
+                 **({"image_root": str(ds.images)} if a.image_root else {})}  # 색은 이 이미지에서
+    if not init_ply.exists() or old_meta != want_meta:
+        if init_ply.exists():
+            print("  init.ply 를 다시 만듭니다 (설정 또는 초기화 알고리즘 판이 다름)")
+        write_ply(init_ply, init_gaussians(scene, ds, icfg))
+        meta_path.write_text(json.dumps(want_meta, indent=2))
+    init = read_ply(init_ply)
+    views = build_views(scene, ds, init.origin, downscale=a.downscale,
+                        frame_stride=a.stride, keyframes_only=a.keyframes_only, objects=a.objects)
+    if a.depth_lambda > 0:
+        from nusim.recon.depth import lidar_depth_maps
+        from nusim.recon.init import InitConfig, accumulate_lidar
+
+        pts = accumulate_lidar(scene, ds, InitConfig(objects=bg_objects)) - init.origin  # 가린 객체의 점은 뺀다
+        lidar_depth_maps(pts, views.train, scale=a.depth_scale)
+    else:
+        pts = None
+    if a.sky:
+        from nusim.paths import cache_dir
+        from nusim.recon.sky import sky_masks
+
+        sky_masks(views.train, ds, sky_mask_cache(a.name, ds))
+    cfg = _train_config(a)
+    from nusim.log import run_log
+
+    with run_log(out / "run.log"):
+        LOG.info("학습 시작 %s → %s  (strategy=%s, sky=%s, depth_lambda=%s, objects=%s)", a.name, out, a.strategy,
+                 a.sky, a.depth_lambda, a.objects)
+        objs = obj_init = None
+        if a.objects == "vehicles":
+            from nusim.recon.objects import ObjectSet, init_objects
+
+            objs = ObjectSet.from_scene(scene, init.origin)
+            obj_init = init_objects(objs, scene, ds, icfg, log=print)
+        gmask = None
+        if cfg.ground_lambda > 0:
+            from nusim.recon.ground import ground_mask
+
+            gmask = ground_mask(init.means, scene, init.origin, ds)
+        train(views, init, out, cfg, depth_points=pts, objects=objs, obj_init=obj_init, ground=gmask)
+    return 0
+
+
+def _model_views(d: Path) -> dict:
+    """모델을 학습한 뷰 집합 설정 (report.json 의 config). 옛 모델은 기본값."""
+    import json
+
+    out = {"downscale": 2, "frame_stride": 1, "keyframes_only": False}
+    try:
+        cfg = json.loads((d / "report.json").read_text())["config"]
+        out.update({k: cfg[k] for k in out if k in cfg})
+    except (OSError, KeyError, ValueError):
+        pass
+    return out
+
+
+def _model_data(name: str, d: Path):
+    """(씬, 데이터 경로) — 모델을 학습한 데이터 범위 그대로 (report.json config 의 time_window·image_root).
+    평가·증류·정리·하늘 표시·사이클이 모두 이걸로 — 구간 모델에 씬 전체 뷰를 주면 색 보정 크기가 안 맞고,
+    변환 영상으로 학습한 모델을 원본(밤) 사진으로 평가하게 된다 (2026-10-05 검토)."""
+    import json
+    from dataclasses import replace
+
+    from nusim.data.index import load_scene
+    from nusim.paths import dataset
+
+    try:
+        cfg = json.loads((d / "report.json").read_text())["config"]
+    except (OSError, KeyError, ValueError):
+        cfg = {}
+    scene, ds = load_scene(name), dataset()
+    if cfg.get("time_window"):
+        t0, t1 = (float(x) for x in cfg["time_window"].split(":"))
+        scene = scene.window(t0, t1)
+    if cfg.get("image_root"):
+        ds = replace(ds, image_root=Path(cfg["image_root"]))
+    return scene, ds
+
+
+def sky_mask_cache(name: str, ds) -> Path:
+    """하늘 마스크 캐시 — 이미지 루트마다 따로 (원본 밤 사진과 변환한 낮 영상의 마스크를 섞지 않게)."""
+    from nusim.paths import cache_dir
+
+    tag = name if ds.image_root is None else f"{name}@{Path(ds.image_root).name}"
+    return cache_dir() / "sky_masks" / tag
+
+
+def _model_objects(d: Path) -> str:
+    """모델이 학습 때 가린 객체 종류 (report.json 의 config.objects). 옛 모델은 dynamic."""
+    import json
+
+    try:
+        return json.loads((d / "report.json").read_text())["config"].get("objects", "dynamic")
+    except (OSError, KeyError, ValueError):
+        return "dynamic"
+
+
+def _cmd_recon_eval(a: argparse.Namespace) -> int:
+    import json
+
+    import torch
+
+    from nusim.data.index import load_scene
+    from nusim.io.ply import read_ply
+    from nusim.paths import dataset, output_dir
+    from nusim.recon.dataset import build_views
+    from nusim.recon.train import CameraAdjust, ColorCorrection, _to_params, evaluate
+
+    d = Path(a.dir) if a.dir else output_dir() / "gs" / a.name
+    g = read_ply(d / "point_cloud.ply")
+    objects = _model_objects(d)
+    vk = _model_views(d)
+    scene, ds = _model_data(a.name, d)
+    views = build_views(scene, ds, g.origin, downscale=a.downscale or vk["downscale"],
+                        frame_stride=vk["frame_stride"], keyframes_only=vk["keyframes_only"], objects=objects)
+    color = ColorCorrection.load(d / "color_correction.pt", 6, len(views.train) + len(views.test), "cuda")
+    adj = None
+    if (d / "camera_adjust.pt").exists():
+        adj = CameraAdjust(6).cuda()
+        adj.load_state_dict(torch.load(d / "camera_adjust.pt", weights_only=True))
+    sky = None
+    if (d / "sky.pt").exists():
+        from nusim.recon.train import SkyCube
+
+        try:
+            sky = SkyCube.from_state(torch.load(d / "sky.pt", weights_only=True))
+        except ValueError as e:
+            LOG.warning("하늘 큐브맵을 못 읽음: %s", e)
+    params = _to_params(g, "cuda")
+    objposes = None
+    if objects == "vehicles" and (d / "objects" / "objects.json").exists():
+        # 차량 동시 학습 모델: 배경 ply 에 차량 에셋을 다시 붙여 학습 때처럼 그린다
+        from nusim.recon.objects import load_objects
+
+        arrays, ids, objs = load_objects(d, scene, g.origin)
+        if len(ids):
+            for key, val in arrays.items():
+                params[key] = torch.nn.Parameter(torch.cat([params[key].data, val], 0))
+            params["obj"] = torch.nn.Parameter(torch.cat([torch.full((len(g),), -1.0, device="cuda"),
+                                                          torch.as_tensor(ids, device="cuda")]))
+            cache: dict[int, tuple] = {}
+
+            def objposes(v):
+                t = int(v.pose.timestamp)
+                if t not in cache:
+                    cache[t] = tuple(torch.as_tensor(x, device="cuda", dtype=torch.float32) for x in objs.poses_at(t))
+                return cache[t]
+            print(f"  차량 에셋 {len(set(ids.tolist()))}대, 가우시안 {len(ids):,}개를 붙여 평가")
+    ev = evaluate(params, color, views, g.sh_degree, cam_adjust=adj, sky=sky, objposes=objposes, with_lpips=a.lpips)
+    if a.geom:
+        from nusim.paths import cache_dir
+        from nusim.recon.depth import lidar_depth_maps
+        from nusim.recon.init import InitConfig, accumulate_lidar
+        from nusim.recon.metrics import geometry_metrics
+        from nusim.recon.sky import sky_masks
+
+        pts = accumulate_lidar(scene, ds, InitConfig(objects=objects)) - g.origin
+        if adj is not None:  # 렌더와 같은 (보정된) 카메라로 투영한다
+            from nusim.recon.train import _refresh_depth
+
+            _refresh_depth(views.test, adj, pts, 4)
+        else:
+            lidar_depth_maps(pts, views.test, scale=4)
+        sky_masks(views.test, ds, sky_mask_cache(a.name, ds))
+        ev.update(geometry_metrics(params, views.test, g.sh_degree, cam_adjust=adj))
+    prev = json.loads((d / "eval.json").read_text()) if (d / "eval.json").exists() else {}
+    (d / "eval.json").write_text(json.dumps({**prev, **ev}, indent=2))  # 이전 --geom 등 다른 키는 남긴다
+    print(json.dumps(ev, indent=2))
+    return 0
+
+
+def _cmd_run(a: argparse.Namespace) -> int:
+    from nusim.config import resolve
+    from nusim.jobs import run_job
+    from nusim.log import run_log
+    from nusim.paths import output_dir
+
+    path = resolve("jobs", a.job)
+    with run_log(output_dir() / "jobs" / f"{path.stem}.log"):
+        return run_job(path, dry=a.dry_run)
+
+
+def _cmd_recon_batch(a: argparse.Namespace) -> int:
+    from nusim.paths import output_dir
+    from nusim.recon.batch import day_scenes, run_batch
+
+    if a.scenes:
+        scenes = [s.strip() for s in a.scenes.split(",") if s.strip()]
+    else:
+        scenes = day_scenes(a.location)
+    if a.order == "coverage":
+        from nusim.recon.batch import coverage_order
+
+        scenes = coverage_order(scenes)
+    if a.limit:
+        scenes = scenes[: a.limit]
+    root = Path(a.root) if a.root else output_dir() / "gs_day"
+    print(f"일괄 재구성 {len(scenes)}씬 (프리셋 {a.preset}) → {root}")
+    from nusim.log import run_log
+
+    with run_log(root / "batch.log"):
+        status = run_batch(scenes, root, a.preset, iters=a.iters, sky=False if a.no_sky else None,
+                           segment_m=a.segment_m, overlap_m=a.overlap_m, after=a.after, keep_init=a.keep_init)
+    units = [v for k, v in status.items() if not k.startswith("_")]
+    return 0 if all(v.get("state") == "done" for v in units) else 1
+
+
+def _cmd_recon_cycle(a: argparse.Namespace) -> int:
+    import json
+
+    from nusim.log import run_log
+    from nusim.paths import output_dir
+    from nusim.recon.cycle import bench_metrics, build_cycle
+
+    base = Path(a.base) if a.base else output_dir() / "gs_day" / a.name
+    with run_log(base / "cycle" / "run.log"):
+        cdir = build_cycle(a.name, base, a.iters, a.shift)
+        res = {k: bench_metrics(cdir / "bench", k) for k in ("render", "base")}
+    (cdir / "bench_metrics.json").write_text(json.dumps(res, indent=2))
+    print(json.dumps(res, indent=2))
+    return 0
+
+
+def _cmd_recon_prune(a: argparse.Namespace) -> int:
+    from nusim.log import run_log
+    from nusim.recon.prune import prune_model
+
+    src = Path(a.dir) if a.dir else _render_paths(a.name)
+    out = Path(a.out) if a.out else src.parent / f"{src.name}_pruned"
+    with run_log(out / "prune.log"):
+        prune_model(a.name, src, out, margin=a.margin, ratio=a.ratio, min_obs=a.min_obs)
+    return 0
+
+
+def _cmd_recon_bench(a: argparse.Namespace) -> int:
+    import json
+
+    from nusim.recon.cycle import bench_metrics, run_fixer_bench
+
+    bench = Path(a.bench)
+    if a.run_difix:
+        run_fixer_bench(bench)
+    res = {k: bench_metrics(bench, k) for k in a.pred.split(",")}
+    print(json.dumps(res, indent=2))
+    return 0
+
+
+def _cmd_recon_skylabel(a: argparse.Namespace) -> int:
+    from nusim.log import run_log
+    from nusim.recon.sky_label import label_sky
+
+    d = Path(a.dir) if a.dir else _render_paths(a.name)
+    with run_log(d / "sky_label.log"):
+        label_sky(a.name, d, ratio=a.ratio, min_obs=a.min_obs)
+    return 0
+
+
+def _cmd_recon_semantic(a: argparse.Namespace) -> int:
+    from nusim.data.index import load_scene
+    from nusim.paths import dataset, output_dir
+    from nusim.recon.batch import segment_dirs
+    from nusim.recon.semantic import is_current, semantic_config, write_semantic
+
+    root = Path(a.root) if a.root else output_dir() / "gs_day"
+    names = list(a.names)
+    if a.location:
+        from nusim.render.regionmap import trained_scenes
+
+        names += [s for s, _ in trained_scenes(root, a.location)]
+    if not names:
+        raise SystemExit("씬 이름이나 --location 을 준다")
+    cfg, paths, n = semantic_config(), dataset(), 0
+    for i, name in enumerate(names):
+        dirs = [m for _, m in segment_dirs(root, name)] or ([Path(a.dir)] if a.dir else [_render_paths(name)])
+        todo = [m for m in dirs if a.force or not is_current(m)]
+        if not todo:
+            continue
+        print(f"[{i + 1}/{len(names)}] {name}: 모델 {len(todo)}개")
+        sc, cache = load_scene(name), {}
+        for m in todo:
+            write_semantic(m, sc, paths, cfg, log=print, cache=cache)
+            n += 1
+    print(f"시맨틱 라벨 {n}개 모델 새로 만듦")
+    return 0
+
+
+def _ensure_sky_label(name: str, d: Path) -> None:
+    """하늘을 분리하지 않고 학습한 모델이면 하늘 가우시안을 표시해 둔다 (뷰어가 시뮬레이션 하늘 모드에서 뺀다).
+    하늘 큐브맵(sky.ktx2)이 있는 모델은 하늘이 이미 따로라 필요 없다."""
+    from nusim.recon.sky_label import is_fresh, label_sky
+
+    if (d / "sky.ktx2").exists() or is_fresh(d):
+        return
+    print("  하늘 가우시안 표시 (한 번만, 하늘 마스크 캐시 사용)…")
+    label_sky(name, d, log=print)
+
+
+def _cmd_aug_rig(a: argparse.Namespace) -> int:
+    from nusim.aug.rig_aug import load_variants, render_variant
+    from nusim.config import configs_dir
+    from nusim.log import run_log
+    from nusim.paths import output_dir
+    from nusim.render.compare import viewer_binary
+
+    d = _render_paths(a.name, a.model)
+    _ensure_export(a.name, d, 1)
+    variants = load_variants(Path(a.variants) if a.variants else configs_dir() / "aug" / "rig_variants.json",
+                             a.only.split(",") if a.only else None)
+    out_root = Path(a.out) if a.out else output_dir() / "aug" / "rig"
+    extra = _ibl_gltf_args(a.name, agents=True) if a.agents else []
+    with run_log(out_root / a.name / "aug.log"):
+        print(f"\033[1m{a.name}\033[0m  리그 변형 {len(variants)}개  (모델 {d})")
+        for v in variants:
+            render_variant(a.name, d, v, out_root, viewer_binary(), extra, log=print)
+    return 0
+
+
+def _cmd_aug_map(a: argparse.Namespace) -> int:
+    from nusim.aug.map_aug import aug_scene
+    from nusim.aug.rig_aug import load_variants
+    from nusim.config import configs_dir
+    from nusim.log import run_log
+    from nusim.paths import output_dir
+    from nusim.render.compare import viewer_binary
+
+    variants = load_variants(Path(a.variants) if a.variants else configs_dir() / "aug" / "rig_variants.json",
+                             a.only.split(",") if a.only else None)
+    if not a.only:  # 기본은 날씨 없는 변형만 — 날씨 합성은 논문 범위 밖 (2026-10-06)
+        variants = [v for v in variants if not v.get("weather")]
+    root = Path(a.root) if a.root else output_dir() / "gs_day"
+    out_root = Path(a.out) if a.out else output_dir() / "aug" / "map"
+    with run_log(out_root / a.name / "aug.log"):
+        print(f"\033[1m{a.name}\033[0m  리그 변형 {len(variants)}개  (모델 {root / a.name}, "
+              f"{'키프레임' if a.keyframes_only else '전체 프레임'}, 차량 {'glTF' if a.agents else '없음'})")
+        aug_scene(a.name, root, variants, out_root, viewer_binary(), keyframes=a.keyframes_only, agents=a.agents,
+                  log=print)
+    return 0
+
+
+def _cmd_aug_artifixer(a: argparse.Namespace) -> int:
+    from nusim.aug.artifixer_run import aug_scene, artifixer_config, done_cams, finished_scenes
+    from nusim.log import run_log
+    from nusim.paths import output_dir
+
+    cfg = artifixer_config()
+    cams = a.cams.split(",") if a.cams else cfg["cams"]
+    names = list(a.names) or finished_scenes()
+    if a.limit:
+        names = [n for n in names if a.force or not set(cams) <= done_cams(n)][:a.limit]
+    log_dir = output_dir() / "aug" / "aug_artfixer"
+    log_dir.mkdir(parents=True, exist_ok=True)
+    failed = []
+    with run_log(log_dir / "artifixer.log"):
+        for i, name in enumerate(names):
+            if not a.force and set(cams) <= done_cams(name):
+                continue
+            print(f"\033[1m[{i + 1}/{len(names)}] {name}\033[0m  ArtiFixer + 차선 후처리 ({','.join(cams)})", flush=True)
+            try:
+                aug_scene(name, cfg, Path(a.root) if a.root else None, cams, force=a.force)
+            except Exception as e:  # 씬 하나가 깨져도 (PNG 손상 · NFS 끊김) 나머지는 계속
+                print(f"  실패: {e}")
+                failed.append(name)
+    if failed:
+        print(f"실패 {len(failed)}씬: {' '.join(failed)}")
+    return 1 if failed else 0
+
+
+def _cmd_aug_translate(a: argparse.Namespace) -> int:
+    from nusim.aug.translate import translate_scene
+    from nusim.log import run_log
+    from nusim.paths import output_dir
+
+    out_root = Path(a.out) if a.out else output_dir() / "aug" / "translate"
+    w, h = (int(x) for x in a.size.split("x"))
+    with run_log(out_root / "translate.log"):
+        for name in a.names:
+            translate_scene(name, a.models.split(","), out_root, size=(w, h), stride=a.stride,
+                            keyframes_only=a.keyframes_only, log=print)
+    return 0
+
+
+def _is_seg(d: Path) -> bool:
+    from nusim.render.segmap import is_segmented
+
+    return is_segmented(d)
+
+
+def _render_paths(name: str, model: str | None = None, segmented: bool = False):
+    """렌더에 쓸 모델 디렉터리. 기본은 outputs/gs/<scene>_env (환경 전용), 다음 outputs/gs/<scene>_depth (라이다 깊이 감독),
+    없으면 outputs/gs/<scene>. 차선 변경 같은 새 시점에서 깊이 감독 모델이 확연히 낫다
+    (docs/roadmap.md 1단계 모델 비교). segmented: 구간으로 나눈 일괄 재구성 씬 디렉터리(seg<k>/)도 받는다 (render view)."""
+    from nusim.paths import output_dir
+
+    if model:
+        d = Path(model)
+    else:
+        # 환경 전용(_env: 차량·사람 전부 지움) > 일괄 재구성(gs_day, 환경 전용) > 깊이 감독(_depth) > 기본 순
+        cands = [output_dir() / "gs" / f"{name}_env", output_dir() / "gs_day" / name,
+                 output_dir() / "gs" / f"{name}_depth", output_dir() / "gs" / name]
+        for d in cands:
+            if (d / "point_cloud.ply").exists() or (segmented and _is_seg(d)):
+                break
+    if not (d / "point_cloud.ply").exists() and not (segmented and _is_seg(d)):
+        raise FileNotFoundError(f"{d / 'point_cloud.ply'} 가 없습니다. 먼저: nusim recon train {name}")
+    return d
+
+
+def _ibl_gltf_args(name: str, agents: bool = False) -> list[str]:
+    """IBL 이 구워져 있으면 환경 조명을 켠다.
+    다른 차량(glTF)은 기본으로 넣지 않는다 — 렌더링은 주행 환경(맵)만 구성하고, 차량·사람 같은 객체는
+    이후 시뮬레이터가 따로 넣는 방향이다. agents=True 면 nuScenes 로그의 움직이는 차 궤적에 glTF 차량을 놓는다."""
+    from nusim.paths import output_dir, workspace_root
+
+    args = []
+    ibl = output_dir() / "ibl" / name
+    if (ibl / "env_specular.ktx2").exists():
+        args += ["--ibl", str(ibl)]
+        car = workspace_root() / "assets" / "gltf" / "CarConcept.glb"
+        if agents and car.exists():
+            args += ["--gltf", str(car)]
+    return args
+
+
+def _write_obstacles(name: str, d: Path, origin) -> None:
+    """충돌용 장애물 지도 (정적 라이다, 모델과 같은 objects 설정으로 차량·사람 제거) → d/obstacles.pgm"""
+    from nusim.data.index import load_scene
+    from nusim.paths import dataset
+    from nusim.sim.obstacles import write_obstacles
+
+    info = write_obstacles(d / "obstacles.pgm", load_scene(name), dataset(), origin, objects=_model_objects(d))
+    print(f"  장애물 지도 {info['cells']:,}칸 ({info['res']} m; 노면 안쪽에서 비운 칸 {info['cleared_on_road']}, "
+          f"원래 경로에서 더 비운 칸 {info['carved_by_log_path']}) → {d / 'obstacles.pgm'}")
+
+
+EXPORT_VERSION = 2  # 내보내기 판 (바뀌면 다시 만든다). 2: 환경 전용 모델의 A 줄에 주차 차량
+
+
+def _model_stamp(d: Path) -> str:
+    """모델이 바뀌었는지 — ply 와 외부 파라미터 보정의 수정 시각."""
+    parts = [str(int((d / "point_cloud.ply").stat().st_mtime))]
+    if (d / "camera_adjust.json").exists():
+        parts.append(str(int((d / "camera_adjust.json").stat().st_mtime)))
+    return ":".join(parts)
+
+
+def _ensure_export(name: str, d: Path, downscale: int, margin: float = 60.0, force: bool = False) -> None:
+    """뷰어가 읽는 파일(rig.txt, map.txt, drivable.txt, obstacles.pgm)을 필요한 것만 다시 만든다.
+    예전에는 파일이 있기만 하면 그대로 써서, 모델을 다시 학습하거나 --downscale·objects·알고리즘을 바꿔도
+    낡은 리그·지도로 그렸다 (2026-10-02 리뷰). 무엇으로 만들었는지 export.json 에 남기고 비교한다."""
+    import json
+
+    from nusim.data.index import load_scene
+    from nusim.io.ply import read_origin
+    from nusim.render.export import load_camera_adjust, write_drivable, write_map_lines, write_rig
+    from nusim.sim.obstacles import OBSTACLES_VERSION
+    from nusim.sim.voxels import VOXELS_VERSION
+
+    state_path = d / "export.json"
+    state = json.loads(state_path.read_text()) if state_path.exists() and not force else {}
+    stamp = _model_stamp(d)
+    want = {
+        "rig": {"model": stamp, "downscale": downscale, "version": EXPORT_VERSION},
+        "map": {"model": stamp, "version": EXPORT_VERSION, "margin": margin},
+        "obstacles": {"model": stamp, "version": OBSTACLES_VERSION, "objects": _model_objects(d)},
+        "voxels": {"model": stamp, "version": VOXELS_VERSION, "objects": _model_objects(d)},
+    }
+    files = {"rig": ["rig.txt"], "map": ["map.txt", "drivable.txt"], "obstacles": ["obstacles.pgm"],
+             "voxels": ["world.vox"]}
+    todo = [k for k in want if state.get(k) != want[k] or not all((d / f).exists() for f in files[k])]
+    if not todo:
+        return
+    scene, _ = _model_data(name, d)  # 구간 모델(--time-window)이면 그 학습 구간만 재생·표시
+    origin = read_origin(d / "point_cloud.ply")
+    if "rig" in todo:
+        adjust = load_camera_adjust(d)
+        n = write_rig(d / "rig.txt", scene, origin, adjust, downscale=downscale, objects=_model_objects(d))
+        print(f"  카메라 리그  {n}프레임 × 6캠 → {d / 'rig.txt'}" + ("  (외부 파라미터 보정 반영)" if adjust else ""))
+    if "map" in todo:
+        counts = write_map_lines(d / "map.txt", scene, origin, margin=margin)
+        n_poly = write_drivable(d / "drivable.txt", scene, origin)
+        print(f"  주행가능영역 {n_poly}개 폴리곤 → {d / 'drivable.txt'}")
+        print(f"  맵 선       → {d / 'map.txt'}")
+        for k, v in counts.items():
+            print(f"      {k:<16} {v:>5}")
+    if "obstacles" in todo:
+        _write_obstacles(name, d, origin)
+    if "voxels" in todo:  # 라이다·레이더 레이캐스트용 (nusim/sim/voxels.py)
+        from nusim.paths import dataset
+        from nusim.sim.voxels import write_voxels
+
+        info = write_voxels(d / "world.vox", scene, dataset(), origin, objects=_model_objects(d))
+        print(f"  복셀 월드 {info['occupied']:,}칸 ({info['res']} m, {info['mb']} MB) → {d / 'world.vox'}")
+    state.update({k: want[k] for k in todo})
+    state_path.write_text(json.dumps(state, indent=2))
+
+
+def _cmd_render_export(a: argparse.Namespace) -> int:
+    d = _render_paths(a.name, getattr(a, "model", None))
+    _ensure_export(a.name, d, a.downscale, margin=a.margin, force=True)
+    return 0
+
+
+def _cmd_render_compare(a: argparse.Namespace) -> int:
+    import json
+
+    from nusim.data.index import load_scene
+    from nusim.io.ply import read_origin
+    from nusim.paths import dataset
+    from nusim.recon.dataset import build_views
+    from nusim.render.compare import compare, run_offscreen
+    from nusim.render.export import load_camera_adjust, write_views
+
+    d = _render_paths(a.name, getattr(a, "model", None))
+    origin = read_origin(d / "point_cloud.ply")
+    vk = _model_views(d)
+    scene, ds = _model_data(a.name, d)
+    views = build_views(scene, ds, origin, load_images=False, mask_dynamic=False,
+                        frame_stride=vk["frame_stride"], keyframes_only=vk["keyframes_only"]).test
+    views = views[:: max(1, len(views) // a.n)][: a.n]
+    adjust = load_camera_adjust(d)
+    write_views(d / "test_views.txt", views, adjust)
+    vk_dir = d / "vk_test"
+    for old in vk_dir.glob("*.png"):
+        old.unlink()
+    print(run_offscreen(d / "point_cloud.ply", d / "test_views.txt", vk_dir).rstrip())
+    res = compare(d, views, vk_dir, adjust)
+    (d / "vk_compare.json").write_text(json.dumps(res, indent=2))
+    ok = res["mean_abs_diff_pct"] < 2.0
+    print(f"\n  Vulkan vs gsplat ({res['n_views']}뷰):  PSNR {res['psnr_vk_vs_gsplat']:.2f} dB  "
+          f"평균 차이 {res['mean_abs_diff_pct']:.3f}%  2% 넘는 픽셀 {res['pixels_over_2pct']:.2f}%  "
+          f"최악 뷰 {res['worst_view_psnr']:.2f} dB  →  {'합격' if ok else '불합격'} (기준: 평균 차이 < 2%)")
+    return 0 if ok else 1
+
+
+def _cmd_render_view(a: argparse.Namespace) -> int:
+    import os
+
+    from nusim.render.compare import viewer_binary
+
+    d = _render_paths(a.name, getattr(a, "model", None), segmented=True)
+    sky_dir = d
+    if _is_seg(d):  # 일괄 재구성이 구간으로 나눈 씬 — 구간을 이어서 (자차 위치의 구간을 그린다)
+        from nusim.render.segmap import write_segment_map
+
+        segs = write_segment_map(a.name, d, log=print)
+        ply, sky_dir = segs[0][1] / "point_cloud.ply", segs[0][1]
+        from nusim.aug.map_aug import ensure_ibl
+
+        ensure_ibl(a.name, segs, log=print)  # glTF 자차의 조명 — 없으면 3DGS 자차 에셋으로 대신해 검은 덩어리가 나왔다
+        seg_args = ["--segments", str(d / "segments.txt")]
+        model_dirs = [m for _, m in segs]
+    else:
+        _ensure_export(a.name, d, a.downscale)
+        _ensure_sky_label(a.name, d)
+        ply, seg_args, model_dirs = d / "point_cloud.ply", [], [d]
+    from nusim.recon.semantic import ensure_semantic
+
+    ensure_semantic(a.name, model_dirs, log=print)  # 없으면 시맨틱 카메라(F3)가 하늘만 파랗고 나머지는 검다
+    cmd = [str(viewer_binary()), str(ply.resolve()), "--cams", str(d / "rig.txt"),
+           "--lines", str(d / "map.txt"), "--shot-dir", str(d / "shots"), *seg_args]
+    if (d / "drivable.txt").exists():
+        cmd += ["--drivable", str(d / "drivable.txt")]  # 직접 운전(G) 때 도로 이탈 판정 + 연석 충돌
+    cmd += ["--obstacles", str(d / "obstacles.pgm")]  # 건물·기둥·벽 충돌
+    if (d / "objects" / "objects.json").exists():  # 차량을 함께 학습한 모델 — 차량 에셋을 각자의 궤적으로 (K: 편집)
+        cmd += ["--objects", str(d / "objects")]
+    from nusim.paths import output_dir, workspace_root
+
+    cmd += _ibl_gltf_args(a.name, agents=a.agents)
+    if (sky_dir / "sky.ktx2").exists():
+        cmd += ["--sky", str(sky_dir / "sky.ktx2")]
+    if (d / "world.vox").exists():
+        cmd += ["--voxels", str(d / "world.vox")]  # 라이다·레이더 (configs/sim.json sensors, 창의 '센서' 패널)
+    from nusim.config import sim_config, sim_config_path
+
+    if sim_config_path().exists():
+        cmd += ["--config", str(sim_config_path())]  # 날씨 프리셋·하늘·3인칭 카메라·충돌 (configs/sim.json)
+    ego_cfg = sim_config().get("ego", {})
+    ego_gltf = workspace_root() / ego_cfg.get("gltf", "assets/gltf/ego_car.glb")
+    ego = workspace_root() / ego_cfg.get("fallback_3dgs_asset", "outputs/assets/ego_car.ply")
+    if ego_gltf.exists() and "--ibl" in cmd:
+        cmd += ["--ego-gltf", str(ego_gltf)]  # 자차 = 머티리얼 있는 차량 메시 (PBR + IBL)
+        if "length_m" in ego_cfg:
+            cmd += ["--ego-length", str(float(ego_cfg["length_m"]))]
+    elif ego.exists():
+        cmd += ["--ego-asset", str(ego)]  # 없으면 nuScenes 주차 차량 3DGS 에셋
+    if a.autoshot:
+        cmd += ["--autoshot", str(a.autoshot)]
+    elif not a.replay:
+        cmd += ["--drive"]  # 운전 모드(차 뒤 시점)로 시작. G 를 누르면 로그 재생(차에 달린 카메라 시점)
+    if a.weather:
+        cmd += ["--weather", a.weather]  # 합성 날씨 시작값 — 창 안 슬라이더(F1)로 바꿀 수 있다
+    os.execv(cmd[0], cmd)
+
+
+def _cmd_render_map(a: argparse.Namespace) -> int:
+    import os
+
+    from nusim.config import sim_config, sim_config_path
+    from nusim.paths import output_dir, workspace_root
+    from nusim.render.compare import viewer_binary
+    from nusim.render.regionmap import write_region_map
+
+    root = Path(a.root) if a.root else output_dir() / "gs_day"
+    out = root / "_map" / a.location
+    if not a.no_sensors:  # 없는 씬 것만 (--sensors: 학습된 구간이 바뀐 씬도 다시)
+        from nusim.render.regionmap import build_sensor_worlds
+
+        n = build_sensor_worlds(a.location, root, log=print, stale=a.sensors)
+        if n:
+            print(f"  센서 복셀 월드 {n}개 씬 새로 만듦")
+    info = write_region_map(a.location, root, out, start=a.start, log=print)
+    if a.no_view:
+        return 0
+    from nusim.recon.semantic import ensure_semantic
+    from nusim.render.regionmap import trained_scenes
+
+    for s, segs in ([] if a.no_semantic else trained_scenes(root, a.location)):  # 시맨틱 카메라(F3) 라벨 — 새로 학습된 구간만 (모델당 수 초)
+        ensure_semantic(s, [m for _, m in segs], log=print)
+    from nusim.aug.map_aug import ensure_ibl
+    from nusim.recon.batch import segment_dirs
+
+    ensure_ibl(info["anchor"], segment_dirs(root, info["anchor"]), log=print)  # 없으면 glTF 자차 대신 3DGS 자차(검은 덩어리)가 나온다
+    cmd = [str(viewer_binary()), info["first_ply"], "--cams", str(out / "rig.txt"), "--segments", str(out / "segments.txt"),
+           "--lines", str(out / "map.txt"), "--drivable", str(out / "drivable.txt"), "--shot-dir", str(out / "shots")]
+    cmd += _ibl_gltf_args(info["anchor"])
+    if Path(info["sky"]).exists():
+        cmd += ["--sky", info["sky"]]
+    if sim_config_path().exists():
+        cmd += ["--config", str(sim_config_path())]
+    ego_cfg = sim_config().get("ego", {})
+    ego_gltf = workspace_root() / ego_cfg.get("gltf", "assets/gltf/ego_car.glb")
+    ego = workspace_root() / ego_cfg.get("fallback_3dgs_asset", "outputs/assets/ego_car.ply")
+    if ego_gltf.exists() and "--ibl" in cmd:
+        cmd += ["--ego-gltf", str(ego_gltf)]
+        if "length_m" in ego_cfg:
+            cmd += ["--ego-length", str(float(ego_cfg["length_m"]))]
+    elif ego.exists():
+        cmd += ["--ego-asset", str(ego)]
+    if not a.replay:
+        cmd += ["--drive"]
+    cmd += a.viewer_args  # nusim render map <지역> -- --autopilot ... (뷰어 옵션 그대로)
+    print(f"  지역 맵 {info['location']}: 씬 {info['scenes']}개 · 구간 {info['segments']}개 — 센서 복셀 월드 "
+          f"{info['sensor_worlds']}/{info['scenes']}씬"
+          + ("" if info["sensor_worlds"] == info["scenes"] else " (나머지는 센서 꺼짐 — --no-sensors 를 빼고 다시)")
+          + " · 장애물 지도는 아직 지역 단위로 없음 (연석 충돌만)")
+    os.execv(cmd[0], cmd)
+
+
+def _cmd_render_encode(a: argparse.Namespace) -> int:
+    """PNG 프레임 디렉터리 (vkgs_viewer --record-screen / --record) → mp4. 왼쪽 아래에 설명 글자를 얹는다."""
+    import imageio.v2 as imageio
+    import numpy as np
+    from PIL import Image, ImageDraw, ImageFont
+
+    frames = sorted(Path(a.frames).glob("frame_*.png"))
+    if not frames:
+        raise SystemExit(f"{a.frames} 에 frame_*.png 가 없다")
+    font = None
+    for f in ("/usr/share/fonts/truetype/nanum/NanumGothicBold.ttf", "/usr/share/fonts/truetype/nanum/NanumSquareRoundB.ttf"):
+        if Path(f).exists():
+            font = ImageFont.truetype(f, a.font_size)
+            break
+    out = Path(a.out)
+    out.parent.mkdir(parents=True, exist_ok=True)
+    with imageio.get_writer(out, fps=a.fps, codec="libx264", quality=None, bitrate=a.bitrate, macro_block_size=1,
+                            pixelformat="yuv420p") as w:
+        for fp in frames:
+            im = Image.open(fp).convert("RGB")
+            if a.width and im.width != a.width:
+                im = im.resize((a.width, round(im.height * a.width / im.width / 2) * 2), Image.LANCZOS)
+            if a.caption:
+                d = ImageDraw.Draw(im, "RGBA")
+                x0, y0, x1, y1 = d.textbbox((0, 0), a.caption, font=font)
+                m = 10
+                d.rectangle((m, im.height - m - (y1 - y0) - 14, m + x1 - x0 + 16, im.height - m), fill=(0, 0, 0, 160))
+                d.text((m + 8 - x0, im.height - m - (y1 - y0) - 7 - y0), a.caption, font=font, fill=(255, 255, 255, 255))
+            w.append_data(np.asarray(im))
+    if a.poster:
+        Image.open(frames[len(frames) // 2]).convert("RGB").save(a.poster, quality=90)
+    print(f"  {len(frames)}프레임 → {out} ({out.stat().st_size / 2**20:.1f} MB)")
+    return 0
+
+
+def _cmd_render_video(a: argparse.Namespace) -> int:
+    from nusim.render.video import compose, render_frames, write_video
+
+    d = _render_paths(a.name, getattr(a, "model", None))
+    _ensure_export(a.name, d, 1)
+    _ensure_sky_label(a.name, d)
+    fdir = d / "sim_frames"
+    print(render_frames(d, fdir, a.frames, bev_height=a.bev_height).rstrip())
+    out = d / f"{a.name}_sim.mp4"
+    n = write_video(fdir, out, a.name, fps=a.fps)
+    # 첫 프레임 정지 이미지도 남긴다 (영상을 못 여는 곳에서 보려고)
+    from PIL import Image
+
+    first = sorted(fdir.glob("f*_BEV.png"))[len(sorted(fdir.glob("f*_BEV.png"))) // 2]
+    Image.fromarray(compose(fdir, int(first.name[1:5]), a.name)).save(d / f"{a.name}_sim.jpg", quality=92)
+    print(f"  영상 {n}프레임 → {out}\n  정지 이미지 → {d / (a.name + '_sim.jpg')}")
+    return 0
+
+
+def _cmd_recon_distill(a: argparse.Namespace) -> int:
+    from nusim.data.index import load_scene
+    from nusim.io.ply import read_ply
+    from nusim.paths import dataset, output_dir
+    from nusim.recon.dataset import build_views
+    from nusim.recon.distill import make_pseudo_views
+    from nusim.recon.train import TrainConfig, train
+
+    base = Path(a.base) if a.base else output_dir() / "gs" / a.name
+    out = Path(a.out) if a.out else base.parent / f"{base.name}_difix"
+    scene, ds = _model_data(a.name, base)
+    if (base / "sky.pt").exists():
+        # 하늘 큐브맵을 이어받는 미세조정은 아직 없다. 그냥 돌리면 하늘이 빠진 모델(하늘 구 가우시안도 없음)이
+        # 생기고, 의사 뷰의 검은 하늘을 Difix 가 고친 걸 가우시안이 배워 하늘 floater 가 된다.
+        print(f"오류: {base} 는 하늘을 큐브맵으로 분리한 모델(sky.pt) — distill 은 아직 하늘 분리 모델을 지원하지 않습니다")
+        return 1
+    g = read_ply(base / "point_cloud.ply")
+    print(f"\033[1m{a.name}\033[0m  Difix 의사 정답 → 3DGS 미세조정  ({base} → {out})")
+    objects = _model_objects(base)
+    vk = _model_views(base)
+    views = build_views(scene, ds, g.origin, downscale=vk["downscale"], frame_stride=vk["frame_stride"],
+                        keyframes_only=vk["keyframes_only"], objects=objects)
+    if a.depth_lambda > 0:  # 미세조정 중에도 기하를 붙잡는다 (의사 뷰에는 깊이가 없다)
+        from nusim.recon.depth import lidar_depth_maps
+        from nusim.recon.init import InitConfig, accumulate_lidar
+
+        import torch
+
+        from nusim.recon.train import CameraAdjust, _refresh_depth
+
+        pts = accumulate_lidar(scene, ds, InitConfig(objects=objects)) - g.origin
+        adj = CameraAdjust(6).cuda()  # 렌더와 같은 (보정된) 카메라로 깊이 지도를 만든다
+        if (base / "camera_adjust.pt").exists():
+            adj.load_state_dict(torch.load(base / "camera_adjust.pt", weights_only=True))
+        _refresh_depth(views.train, adj, pts, 4)
+        del adj
+
+    def cfg_for(iters: int):
+        return TrainConfig(depth_lambda=a.depth_lambda,
+            iters=iters, sh_degree_every=0, lr_camera=0.0,
+            lr_means=1.6e-5, lr_means_final_ratio=0.1,       # 이미 수렴한 위치를 크게 흔들지 않는다
+            refine_start=500, refine_stop=iters // 2, reset_every=10**9,  # 불투명도 리셋 없음 (step 0 은 train 이 건너뜀)
+            max_gaussians=a.max_gaussians, eval_every=a.eval_every, objects=objects,
+            downscale=vk["downscale"], frame_stride=vk["frame_stride"], keyframes_only=vk["keyframes_only"],
+            pseudo_prob=a.pseudo_prob, pseudo_weight=a.pseudo_weight)
+
+    def pseudo_from(model: Path, shifts):
+        # 의사 뷰 캐시는 기반 모델·가림 설정·간격마다 따로 — 재학습한 모델에 낡은 Difix 결과를 쓰지 않게
+        stamp = f"{objects}_every{a.every}_{int((model / 'point_cloud.ply').stat().st_mtime)}"
+        return make_pseudo_views(model, scene, views, model / "pseudo" / stamp, shifts, a.every, objects=objects,
+                                 downscale=vk["downscale"])
+
+    if not a.progressive:
+        pseudo = pseudo_from(base, tuple(float(x) for x in a.shifts.split(",")))
+        train(views, g, out, cfg_for(a.iters), resume_dir=base, pseudo=pseudo)
+        return 0
+
+    # 점진 증류 (Difix3D+): 가까운 이동부터. 단계마다 직전 단계 모델로 ±s 시점을 렌더 → Difix → 의사 뷰를 쌓고 짧게
+    # 미세조정. 출발점이 이미 좋아져서 Difix 결과가 시점마다 일관되고, 한 번에 3 m 를 고칠 때의 흐려짐을 줄인다.
+    steps = [float(x) for x in a.progressive.split(",")]
+    pseudo, cur = [], base
+    for k, s in enumerate(steps):
+        print(f"\n  ── 점진 {k + 1}/{len(steps)}: ±{s:g} m  (출발 {cur})")
+        pseudo += pseudo_from(cur, (-s, s))
+        stage = out / f"stage{k + 1}_{s:g}m" if k < len(steps) - 1 else out
+        g_cur = read_ply(cur / "point_cloud.ply")
+        train(views, g_cur, stage, cfg_for(a.iters_per_stage), resume_dir=cur, pseudo=pseudo)
+        cur = stage
+    return 0
+
+
+def _cmd_asset_scan(a: argparse.Namespace) -> int:
+    from nusim.data.index import iter_scenes
+    from nusim.recon.asset import scan_parked_cars
+
+    rows = scan_parked_cars(iter_scenes(), max_dist=a.max_dist)
+    print(f"{'방위(/8)':>8} {'최소거리':>8}  {'scene':<12} {'inst':>4}  크기 (w,l,h)")
+    for r in rows[: a.limit]:
+        print(f"{r[0]:>8} {r[1]:>7.1f}m  {r[2]:<12} {r[3]:>4}  {r[4]}")
+    return 0
+
+
+def _cmd_asset_extract(a: argparse.Namespace) -> int:
+    from nusim.data.index import load_scene
+    from nusim.io.ply import read_ply, write_ply
+    from nusim.paths import output_dir
+    from nusim.recon.asset import extract_vehicle
+
+    model = Path(a.model) if a.model else output_dir() / "gs" / f"{a.name}_depth"
+    g = extract_vehicle(read_ply(model / "point_cloud.ply"), load_scene(a.name), a.instance, mirror=not a.no_mirror)
+    out = Path(a.out) if a.out else output_dir() / "assets" / f"car_{a.name}_{a.instance}.ply"
+    write_ply(out, g)
+    print(f"  에셋 가우시안 {len(g):,}개 → {out}")
+    if a.as_ego:
+        ego = output_dir() / "assets" / "ego_car.ply"
+        ego.unlink(missing_ok=True)
+        ego.symlink_to(out.name)
+        print(f"  자차 에셋으로 지정 → {ego}  (nusim render view 가 자동으로 쓴다)")
+    return 0
+
+
+def _cmd_render_ibl(a: argparse.Namespace) -> int:
+    from nusim.data.index import load_scene
+    from nusim.paths import output_dir
+    from nusim.render.ibl import bake_ibl
+
+    d = _render_paths(a.name, a.model)
+    out = output_dir() / "ibl" / a.name
+    print(f"\033[1m{a.name}\033[0m IBL 굽기 (모델 {d})")
+    bake_ibl(load_scene(a.name), d, out, frame=a.frame, size=a.size, samples=a.samples, fill=a.fill)
+    return 0
+
+
+def _cmd_doctor(a: argparse.Namespace) -> int:
+    from nusim.cli.doctor import main as doctor_main
+    return doctor_main()
+
+
+
+# ------------------------------------------------------------------ closed-loop 평가 (nusim.sim.closed_loop, HUGSIM 식)
+def _cmd_sim_run(a: argparse.Namespace) -> int:
+    from nusim.paths import output_dir
+    from nusim.sim.closed_loop import run_episode
+    from nusim.sim.policies import make_policy
+    from nusim.sim.scenario import Scenario, closed_loop_config
+
+    scn = Scenario.load(a.scenario)
+    over = dict(scn.overrides)
+    if a.size:
+        w, h = a.size.lower().split("x")
+        over.setdefault("render", {}).update(width=int(w), height=int(h))
+    if a.max_duration:
+        scn.max_duration_s = a.max_duration
+    cfg = closed_loop_config(over)
+    out = Path(a.out) if a.out else output_dir() / "closed_loop" / scn.name / a.policy
+    print(f"  시나리오 {scn.name} ({scn.difficulty}, {scn.scene}) · 정책 {a.policy} → {out}")
+    res = run_episode(scn, make_policy(a.policy), out, cfg, save_front=not a.no_front, video=not a.no_video)
+    return 0 if res["hd_score"] >= 0 else 1
+
+
+def _cmd_sim_score(a: argparse.Namespace) -> int:
+    import json
+
+    from nusim.sim.hdscore import format_score, score_episode
+
+    for ep in a.episodes:
+        res = score_episode(Path(ep))
+        print(f"  {ep}  [{res.get('scenario')} · {res.get('policy')} · {res.get('termination')}]")
+        print(f"    {format_score(res)}")
+        if a.verbose:
+            for p in res["per_step"]:
+                print(f"      t={p['t']:5.1f}  NC {p['nc']:.1f} DAC {p['dac']:.0f} TTC {p['ttc']:.0f} COM {p['com']:.0f}"
+                      f"  → {p['hd']:.3f}" + (f"  (승차감: {','.join(p['com_fail'])})" if p["com_fail"] else ""))
+        if a.json:
+            print(json.dumps({k: v for k, v in res.items() if k != "per_step"}, indent=1))
+    return 0
+
+
+def _cmd_sim_make_scenarios(a: argparse.Namespace) -> int:
+    import numpy as np
+
+    from nusim.data.index import load_scene
+    from nusim.paths import output_dir, workspace_root
+    from nusim.recon.batch import segment_dirs
+    from nusim.sim.scenario import closed_loop_config, scenarios_dir, write_scenario
+
+    cfg = closed_loop_config()["scenarios"]
+    root = Path(a.root) if a.root else output_dir() / "gs_day"
+    names = a.scenes or sorted(p.name for p in root.iterdir() if p.is_dir() and p.name.startswith("scene-"))
+    out_dir = Path(a.out) if a.out else scenarios_dir()
+    n_ok = 0
+    for name in names:
+        segs = segment_dirs(root, name)
+        if not segs or len(segs) < segs[0][0].get("n", 1):
+            print(f"  {name}: 건너뜀 — 구간 {len(segs)}/{segs[0][0].get('n', 1) if segs else '?'}개만 학습됨")
+            continue
+        fr = load_scene(name).frames["CAM_FRONT"]
+        xy = np.array([f.ego_translation[:2] for f in fr])
+        ts = np.array([f.timestamp for f in fr]) * 1e-6
+        dist = float(np.linalg.norm(np.diff(xy, axis=0), axis=1).sum())
+        route_m = float(a.route_m if a.route_m is not None else cfg["route_m"])
+        use_m = min(dist, route_m) if route_m > 0 else dist
+        if use_m < cfg["min_route_m"]:
+            print(f"  {name}: 건너뜀 — 경로 {dist:.1f} m < {cfg['min_route_m']} m (정차 씬)")
+            continue
+        dur = float(ts[-1] - ts[0]) * (use_m / max(dist, 1e-6))
+        model = root / name
+        try:
+            model = model.relative_to(workspace_root())
+        except ValueError:
+            pass
+        d = {"name": f"{name}_easy", "difficulty": "easy", "scene": name, "model": str(model),
+             "start": {"frame": 0, "speed": cfg["start_speed"]},
+             "route": {"to_frame": None, "max_m": route_m},
+             "max_duration_s": round(dur * cfg["duration_factor"] + cfg["duration_pad_s"], 1),
+             "actors": [], "overrides": {},
+             "info": {"route_m": round(use_m, 1), "log_duration_s": round(dur, 1), "segments": len(segs)}}
+        write_scenario(out_dir / f"{name}_easy.json", d)
+        n_ok += 1
+        print(f"  {name}_easy: 경로 {use_m:.0f} m, 기록 {dur:.1f}초, 구간 {len(segs)}개")
+    print(f"  시나리오 {n_ok}개 → {out_dir}")
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(prog="nusim", description=__doc__.splitlines()[0])
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    idx = sub.add_parser("index", help="씬 인덱스 생성/조회").add_subparsers(dest="sub", required=True)
+
+    b = idx.add_parser("build", help="원본 테이블을 훑어 씬 인덱스를 캐시에 만든다 (약 40초)")
+    b.add_argument("--force", action="store_true", help="이미 있어도 다시 만든다")
+    b.add_argument("--no-sweeps", action="store_true",
+                   help="키프레임(2 Hz)만 담는다. 12배 작지만 재구성 품질이 떨어진다")
+    b.add_argument("--locations", nargs="+", metavar="LOC",
+                   help="기본값은 싱가포르 3종. 예: --locations boston-seaport")
+    b.set_defaults(func=_cmd_index_build)
+
+    l = idx.add_parser("list", help="인덱싱된 씬 목록")
+    l.add_argument("--location", help="singapore-onenorth 등으로 필터")
+    l.add_argument("--grep", help="이름/설명에 이 문자열이 든 씬만")
+    l.add_argument("--limit", type=int, help="상위 N개만")
+    l.set_defaults(func=_cmd_index_list)
+
+    s = sub.add_parser("scene", help="씬 상세").add_subparsers(dest="sub", required=True)
+    sh = s.add_parser("show", help="씬 하나의 카메라/프레임 요약")
+    sh.add_argument("name", help="예: scene-0003")
+    sh.set_defaults(func=_cmd_scene_show)
+
+    rn = sub.add_parser("run", help="작업 정의(configs/jobs/<이름>.json) 실행 — 여러 단계를 순서대로, 끝난 단계는 건너뛴다")
+    rn.add_argument("job", help="작업 이름 또는 JSON 경로")
+    rn.add_argument("--dry-run", action="store_true", help="실행하지 않고 펼친 단계만 보여 준다")
+    rn.set_defaults(func=_cmd_run)
+
+    r = sub.add_parser("recon", help="3DGS 재구성").add_subparsers(dest="sub", required=True)
+    ri = r.add_parser("init", help="LIDAR_TOP → 초기 가우시안 (outputs/gs/<scene>/init.ply)")
+    ri.add_argument("name")
+    ri.add_argument("--voxel", type=float, default=0.15, help="복셀 크기 m (기본 0.15)")
+    ri.add_argument("--max-points", type=int, default=1_500_000)
+    ri.set_defaults(func=_cmd_recon_init)
+
+    rt = r.add_parser("train", help="gsplat 학습 → point_cloud.ply + report.json")
+    p._nusim_train = rt
+    rt.add_argument("name")
+    rt.add_argument("--iters", type=int, default=60_000,
+                    help="기본 6만. 씬당 뷰가 1,200장 남짓이라 3만이면 뷰당 25회뿐 — 덜 학습된다")
+    rt.add_argument("--downscale", type=int, default=2, help="이미지 축소 비율 (기본 2 → 800x450)")
+    rt.add_argument("--stride", type=int, default=1, help="프레임 간격 (2 면 약 6 Hz)")
+    rt.add_argument("--keyframes-only", action="store_true", help="2 Hz 키프레임만")
+    rt.add_argument("--image-root", default=None,
+                    help="카메라 이미지를 이 루트에서 (원본과 같은 상대 경로) — nusim aug translate 결과 등")
+    rt.add_argument("--time-window", default=None, metavar="T0:T1",
+                    help="씬 시작부터 T0~T1 초만 학습 (빠른 씬을 구간별로 나눌 때)")
+    rt.add_argument("--max-gaussians", type=int, default=2_000_000)
+    rt.add_argument("--eval-every", type=int, default=5000)
+    rt.add_argument("--refine-stop", type=int, help="densify 종료 스텝 (기본 min(15000, iters/2))")
+    rt.add_argument("--absgrad", action="store_true", help="절댓값 gradient 로 densify (잎·세부에 유리)")
+    rt.add_argument("--grow-grad2d", type=float, help="densify 임계값 (기본 0.0002, absgrad 면 0.0008)")
+    rt.add_argument("--depth-lambda", type=float, default=0.0, help="라이다 깊이 감독 가중치 (0 이면 끔)")
+    rt.add_argument("--strategy", choices=["default", "mcmc"], default="default",
+                    help="densify 전략. mcmc = 3DGS-MCMC (cap = --max-gaussians, 불투명도·스케일 정규화 0.01)")
+    rt.add_argument("--sky", action="store_true", help="하늘을 학습 가능한 큐브맵으로 분리 (하늘 마스크 BCE)")
+    rt.add_argument("--no-sky", dest="sky", action="store_false", help="하늘 분리 끄기 (프리셋이 켠 것을 끌 때)")
+    rt.add_argument("--preset", help="학습 프리셋 (configs/train/<이름>.json 또는 경로) — 명령줄 값이 우선")
+    rt.add_argument("--objects", choices=("dynamic", "agents", "vehicles"), default="dynamic",
+                    help="학습에서 지울 객체. dynamic: 움직이는 것만 (주차 차량은 배경), "
+                         "agents: 차량·사람·자전거 전부 — 주행 맵만 남기는 환경 전용 재구성, "
+                         "vehicles: 차량은 객체 가우시안으로 함께 학습(에셋으로 내보냄), 사람·자전거만 지움")
+    rt.add_argument("--opacity-reg", type=float, help="불투명도 정규화 (mcmc 기본 0.01)")
+    rt.add_argument("--aniso-reg", type=float, default=0.0, help="바늘 억제 가중치 (가장 긴 축/두 번째 축 비 벌점, 0 = 끔)")
+    rt.add_argument("--aniso-max", type=float, default=6.0, help="바늘 억제가 시작되는 축 비")
+    rt.add_argument("--ground-lambda", type=float, default=0.0,
+                    help="지면 모델 (HUGSIM 다중 평면): 노면 가우시안을 원판으로 고정 + 칸별 높이 분산 가중치 (0 이면 끔)")
+    rt.add_argument("--scale-reg", type=float, help="스케일 정규화 (mcmc 기본 0.01)")
+    rt.add_argument("--depth-scale", type=int, default=2,
+                    help="깊이 지도 축소 비율 (sweep 누적이면 1/2 에서도 79%% 채워진다)")
+    rt.add_argument("--no-camera-adjust", action="store_true", help="카메라 외부 파라미터 보정 끄기")
+    rt.add_argument("--out", help="결과 디렉터리 (기본 outputs/gs/<scene>). 실험을 나란히 돌릴 ��")
+    rt.add_argument("--tile", help="여러 주행을 한 모델로 (configs/tiles/<이름>.json, recon.tile). name 대신 타일의 anchor")
+    rt.set_defaults(func=_cmd_recon_train)
+
+    rte = r.add_parser("tile-eval", help="타일에서 뺀 주행(옆 차선)의 실제 사진으로 모델들을 비교")
+    rte.add_argument("tile")
+    rte.add_argument("--dir", action="append", required=True, help="모델 디렉터리 (여러 번)")
+    rte.add_argument("--stride", type=int, default=4, help="뺀 주행의 프레임 간격")
+    rte.add_argument("--out", help="기본 outputs/tiles/<타일>")
+    rte.set_defaults(func=_cmd_recon_tile_eval)
+
+    rds = r.add_parser("distill", help="Difix 로 고친 새 시점(차선 이동)을 의사 정답으로 3DGS 미세조정")
+    rds.add_argument("name")
+    rds.add_argument("--shifts", default="-3,-1.5,1.5,3", help="자차 좌우 이동량 m (쉼표)")
+    rds.add_argument("--every", type=int, default=6, help="카메라별 학습 프레임 간격")
+    rds.add_argument("--iters", type=int, default=15000)
+    rds.add_argument("--pseudo-prob", type=float, default=0.3)
+    rds.add_argument("--pseudo-weight", type=float, default=0.5)
+    rds.add_argument("--max-gaussians", type=int, default=2_600_000)
+    rds.add_argument("--eval-every", type=int, default=5000)
+    rds.add_argument("--base", help="출발 모델 디렉터리 (기본 outputs/gs/<scene>)")
+    rds.add_argument("--depth-lambda", type=float, default=0.0, help="라이다 깊이 감독 유지 가중치")
+    rds.add_argument("--progressive", help="점진 증류: 이동량 단계 (쉼표, m) — 예 0.5,1,2,3. 주면 --shifts·--iters 대신")
+    rds.add_argument("--iters-per-stage", type=int, default=3000, help="점진 증류 단계당 미세조정 스텝")
+    rds.add_argument("--out", help="기본 <base>_difix")
+    rds.set_defaults(func=_cmd_recon_distill)
+
+    rb = r.add_parser("batch", help="여러 씬 일괄 재구성 (기본: 주간 씬 전체 → outputs/gs_day/<scene>, 이어 하기 가능)")
+    rb.add_argument("--scenes", help="쉼표로 구분한 씬 이름 (기본: 설명에 night/rain 이 없는 씬 전부)")
+    rb.add_argument("--location", help="singapore-onenorth 등으로 제한")
+    rb.add_argument("--limit", type=int, help="앞에서 N 씬만")
+    rb.add_argument("--order", choices=["location", "coverage"], default="location",
+                    help="location: 지역·씬 번호 순 (기본). coverage: 새 도로를 많이 덮는 씬부터 — 맵이 빨리 채워진다")
+    rb.add_argument("--preset", default="day_map", help="학습 프리셋 (configs/train/<이름>.json)")
+    rb.add_argument("--iters", type=int, help="프리셋의 iters 를 덮어쓴다")
+    rb.add_argument("--root", help="결과 루트 (기본 outputs/gs_day)")
+    rb.add_argument("--no-sky", action="store_true", help="프리셋과 상관없이 하늘 분리 없이")
+    rb.add_argument("--segment-m", type=float, default=60.0,
+                    help="구간 길이 상한 (자차 이동 m). 더 긴 씬은 같은 길이 구간으로 나눠 따로 학습 (기본 60)")
+    rb.add_argument("--overlap-m", type=float, default=10.0, help="이웃 구간 겹침 (m, 기본 10)")
+    rb.add_argument("--after", action="append", metavar="CMD",
+                    help="씬의 구간이 다 끝나면 돌릴 nusim 명령 ({scene}·{root} 치환, 여러 번). 예: 'aug map {scene} --root {root}'")
+    rb.add_argument("--keep-init", action="store_true", help="init.ply 를 지우지 않는다 (기본: 학습 뒤 지움, 디스크 절약)")
+    rb.set_defaults(func=_cmd_recon_batch)
+
+    rc = r.add_parser("cycle", help="사이클 렌더 벤치마크: 옆으로 옮긴 렌더로 모델을 다시 학습해 원래 시점(정답 사진)에서 잰다")
+    rc.add_argument("name")
+    rc.add_argument("--base", help="실제 사진으로 학습한 모델 (기본 outputs/gs_day/<scene>)")
+    rc.add_argument("--iters", type=int, default=15_000)
+    rc.add_argument("--shift", type=float, default=1.0, help="옆으로 옮기는 거리 m (기본 1, 논문과 같음)")
+    rc.set_defaults(func=_cmd_recon_cycle)
+    rp = r.add_parser("prune", help="floater 정리: 라이다가 비어 있다고 본 공간에 떠 있는 가우시안을 지운다")
+    rp.add_argument("name")
+    rp.add_argument("--dir", help="모델 디렉터리 (기본: render 가 쓰는 모델)")
+    rp.add_argument("--out", help="결과 (기본 <dir>_pruned)")
+    rp.add_argument("--margin", type=float, default=0.15, help="라이다 표면보다 이 비율 이상 앞이면 위반")
+    rp.add_argument("--ratio", type=float, default=0.5, help="위반 비율이 이보다 크면 지움")
+    rp.add_argument("--min-obs", type=int, default=3, help="판정에 필요한 최소 관측 횟수")
+    rp.set_defaults(func=_cmd_recon_prune)
+    rsl = r.add_parser("skylabel", help="하늘 가우시안 표시: 하늘 마스크에 떨어지는 가우시안 (밤에 하늘이 하얗게 남는 문제)")
+    rsl.add_argument("name")
+    rsl.add_argument("--dir", help="모델 디렉터리 (기본: render 가 쓰는 모델)")
+    rsl.add_argument("--ratio", type=float, default=0.4, help="하늘 픽셀 비율이 이보다 크면 하늘")
+    rsl.add_argument("--min-obs", type=int, default=3, help="판정에 필요한 최소 관측 횟수")
+    rsl.set_defaults(func=_cmd_recon_skylabel)
+    rse = r.add_parser("semantic", help="가우시안 시맨틱 라벨 (lidarseg 다수결) → 모델 옆 semantic.rgba — 뷰어의 시맨틱 카메라")
+    rse.add_argument("names", nargs="*", help="씬 (구간 모델이면 구간 전부)")
+    rse.add_argument("--location", help="이 지역의 학습된 씬 전부 (singapore-onenorth 등)")
+    rse.add_argument("--root", help="일괄 재구성 루트 (기본 outputs/gs_day)")
+    rse.add_argument("--dir", help="구간 모델이 아닌 씬의 모델 디렉터리 (기본: render 가 쓰는 모델)")
+    rse.add_argument("--force", action="store_true", help="있어도 다시")
+    rse.set_defaults(func=_cmd_recon_semantic)
+    rbn = r.add_parser("bench", help="벤치 세트(<cycle>/bench)의 예측을 정답과 비교 (PSNR·SSIM·LPIPS·DISTS)")
+    rbn.add_argument("bench")
+    rbn.add_argument("--pred", default="render,base", help="비교할 접미사들 (render = 사이클 렌더, base = 원 모델, "
+                                                          "difix = Difix 전체 보정, difixm = 신뢰도 마스크 블렌딩)")
+    rbn.add_argument("--run-difix", action="store_true", help="먼저 Difix 를 돌려 *_difix / *_difixm 을 만든다")
+    rbn.set_defaults(func=_cmd_recon_bench)
+
+    re_ = r.add_parser("eval", help="학습된 ply 를 hold-out 뷰로 다시 평가 (정적/전체 PSNR)")
+    re_.add_argument("name")
+    re_.add_argument("--dir", help="point_cloud.ply 와 color_correction.pt 가 있는 곳 (기본 outputs/gs/<scene>)")
+    re_.add_argument("--downscale", type=int, default=None, help="기본: 학습 때 값 (report.json)")
+    re_.add_argument("--geom", action="store_true",
+                     help="기하·floater 지표도: 정적/구멍(동적 마스크) 깊이 오차, 하늘 α (nusim.recon.metrics)")
+    re_.add_argument("--lpips", action="store_true", help="LPIPS (AlexNet) 도 — 전체 영상 · 정적 영역")
+    re_.set_defaults(func=_cmd_recon_eval)
+
+    rd = sub.add_parser("render", help="Vulkan 렌더러 (src/vkgs) 연동").add_subparsers(dest="sub", required=True)
+    ex = rd.add_parser("export", help="카메라 리그 + 맵 선 파일 → outputs/gs/<scene>/{rig,map}.txt")
+    ex.add_argument("name")
+    ex.add_argument("--model", help="모델 디렉터리 (기본 outputs/gs/<scene>_depth, 없으면 <scene>)")
+    ex.add_argument("--downscale", type=int, default=1, help="리그 해상도 축소 (기본 1 = 1600x900)")
+    ex.add_argument("--margin", type=float, default=60.0, help="궤적 주변 맵 범위 m")
+    ex.set_defaults(func=_cmd_render_export)
+    cp = rd.add_parser("compare", help="평가 뷰에서 Vulkan 렌더 vs gsplat 렌더 픽셀 비교")
+    cp.add_argument("name")
+    cp.add_argument("--model", help="모델 디렉터리 (기본 outputs/gs/<scene>_depth, 없으면 <scene>)")
+    cp.add_argument("-n", type=int, default=24, help="비교할 뷰 수")
+    cp.set_defaults(func=_cmd_render_compare)
+    vw = rd.add_parser("view", help="창 모드 뷰어 (자유 카메라 / 6캠 추종 / 궤적 재생 / BEV / 맵)")
+    vw.add_argument("name")
+    vw.add_argument("--model", help="모델 디렉터리 (기본 outputs/gs/<scene>_depth, 없으면 <scene>)")
+    vw.add_argument("--downscale", type=int, default=1)
+    vw.add_argument("--autoshot", type=int, default=0, help="N 프레임 뒤 스크린샷 찍고 종료 (점검용)")
+    vw.add_argument("--weather", help="합성 날씨 시작값: clear|overcast|dusk|night|rain|heavy_rain|fog|night_rain "
+                                      "또는 daylight=0.3,rain=0.5,... (창 안 슬라이더로도 조절, F1 패널)")
+    vw.add_argument("--replay", action="store_true", help="로그 재생 모드(차에 달린 CAM_FRONT 시점)로 시작 (기본: 운전 모드, 차 뒤 시점)")
+    vw.add_argument("--agents", action="store_true",
+                    help="nuScenes 로그의 움직이는 차 궤적에 glTF 차량을 넣는다 (기본: 환경만)")
+    vw.set_defaults(func=_cmd_render_view)
+    rm = rd.add_parser("map", help="지역 맵: 학습된 씬 구간들을 이어 한 공간에서 주행 (singapore-onenorth 등)")
+    rm.add_argument("location", help="singapore-onenorth | singapore-queenstown | singapore-hollandvillage")
+    rm.add_argument("--start", help="출발 씬 (기본: 구간이 가장 많은 씬)")
+    rm.add_argument("--root", help="일괄 재구성 루트 (기본 outputs/gs_day)")
+    rm.add_argument("--replay", action="store_true", help="출발 씬의 로그 재생 모드로 시작")
+    rm.add_argument("--sensors", action="store_true",
+                    help="학습된 구간이 바뀐 씬의 라이다·레이더 복셀 월드도 다시 만든다 (없는 씬 것�� 기본으로 만든다, 씬당 1~2분)")
+    rm.add_argument("--no-sensors", action="store_true", help="없는 복셀 월드를 만들지 않는다 (그 씬은 센서 꺼짐)")
+    rm.add_argument("--no-view", action="store_true", help="파일만 만들고 창은 띄우지 않는다")
+    rm.add_argument("--no-semantic", action="store_true",
+                    help="없는 시맨틱 라벨을 만들지 않는다 (그 구간은 F3 시맨틱 카메라가 비어 보인다, 나중에 nusim recon semantic)")
+    rm.set_defaults(viewer_args=[])  # '--' 뒤는 vkgs_viewer 옵션 그대로 (main 이 떼어 둔다): -- --autopilot --show-sensors
+    rm.set_defaults(func=_cmd_render_map)
+
+    ve = rd.add_parser("encode", help="PNG 프레임 (vkgs_viewer --record-screen) → mp4, 설명 글자 얹기")
+    ve.add_argument("frames", help="frame_*.png 디렉터리")
+    ve.add_argument("out", help="출력 .mp4")
+    ve.add_argument("--fps", type=float, default=20.0, help="녹화는 고정 50 ms 스텝 = 20 fps")
+    ve.add_argument("--width", type=int, default=1280, help="가로 픽셀로 줄인다 (0 = 그대로)")
+    ve.add_argument("--bitrate", default="3M", help="libx264 비트레이트 (발표자료에 넣을 크기: 3M × 20초 ≈ 7.5 MB)")
+    ve.add_argument("--caption", default="", help="왼쪽 아래 글자")
+    ve.add_argument("--font-size", type=int, default=24)
+    ve.add_argument("--poster", help="가운데 프레임을 이 jpg 로 (발표자료 표지 화면)")
+    ve.set_defaults(func=_cmd_render_encode)
+    vd = rd.add_parser("video", help="6캠 + BEV(맵 오버레이) 재생 영상 → outputs/gs/<scene>/<scene>_sim.mp4")
+    vd.add_argument("name")
+    vd.add_argument("--model", help="모델 디렉터리 (기본 outputs/gs/<scene>_depth, 없으면 <scene>)")
+    vd.add_argument("--frames", help="프레임 범위 A:B (기본 전체)")
+    vd.add_argument("--fps", type=float, default=12.0, help="기본 12 (nuScenes 카메라 약 12 Hz)")
+    vd.add_argument("--bev-height", type=float, default=70.0)
+    vd.set_defaults(func=_cmd_render_video)
+
+    asp = sub.add_parser("asset", help="nuScenes 실제 차량 → 3DGS 에셋").add_subparsers(dest="sub", required=True)
+    sc_ = asp.add_parser("scan", help="자차가 가까이 지나가며 여러 방위에서 본 주차 차량 찾기 (주간 씬)")
+    sc_.add_argument("--max-dist", type=float, default=5.0)
+    sc_.add_argument("--limit", type=int, default=15)
+    sc_.set_defaults(func=_cmd_asset_scan)
+    xt = asp.add_parser("extract", help="학습된 씬에서 주차 차량을 잘라 박스 로컬 3DGS 에셋으로")
+    xt.add_argument("name", help="씬 (예: scene-0916)")
+    xt.add_argument("--instance", type=int, required=True)
+    xt.add_argument("--model", help="씬 모델 디렉터리 (기본 outputs/gs/<scene>_depth)")
+    xt.add_argument("--no-mirror", action="store_true", help="좌우 대칭 복사 끄기")
+    xt.add_argument("--out")
+    xt.add_argument("--as-ego", action="store_true", help="outputs/assets/ego_car.ply 로 지정")
+    xt.set_defaults(func=_cmd_asset_extract)
+
+    ib = rd.add_parser("ibl", help="6캠 파노라마 → HDR 큐브맵 → prefiltered diffuse/specular + BRDF LUT → BC6H KTX2")
+    ib.add_argument("name")
+    ib.add_argument("--model")
+    ib.add_argument("--frame", type=int, help="CAM_FRONT 프레임 (기본 가운데)")
+    ib.add_argument("--size", type=int, default=512)
+    ib.add_argument("--samples", type=int, default=512, help="GGX 샘플 수")
+    ib.add_argument("--fill", choices=["extrap", "gs"], default="extrap",
+                    help="사진이 없는 위·아래 채움: extrap = 띠 가장자리 색 외삽 (기본), gs = 3DGS 렌더")
+    ib.set_defaults(func=_cmd_render_ibl)
+
+    ag = sub.add_parser("aug", help="데이터셋 다양성 증강").add_subparsers(dest="sub", required=True)
+    agr = ag.add_parser("rig", help="재구성 장면을 6캠 시점(장착 위치·자세)을 바꿔 다시 렌더 → outputs/aug/rig")
+    agr.add_argument("name")
+    agr.add_argument("--only", help="변형 이름들 (쉼표). 기본: 전부")
+    agr.add_argument("--variants", help="변형 정의 JSON (기본 configs/aug/rig_variants.json)")
+    agr.add_argument("--model", help="모델 디렉터리 (기본: render 가 쓰는 모델)")
+    agr.add_argument("--agents", action="store_true", help="지운 차량을 glTF 로 다시 넣는다 (환경 전용 모델일 때)")
+    agr.add_argument("--out", help="기본 outputs/aug/rig")
+    agr.set_defaults(func=_cmd_aug_rig)
+    agm = ag.add_parser("map", help="일괄 재구성(구간 모델) 씬을 리그 변형으로 다시 렌더 → outputs/aug/map")
+    agm.add_argument("name")
+    agm.add_argument("--root", help="일괄 재구성 루트 (기본 outputs/gs_day)")
+    agm.add_argument("--only", help="변형 이름들 (쉼표). 기본: 날씨 없는 변형 전부")
+    agm.add_argument("--variants", help="변형 정의 JSON (기본 configs/aug/rig_variants.json)")
+    agm.add_argument("--keyframes-only", action="store_true", help="키프레임(2 Hz sample)만")
+    agm.add_argument("--agents", action="store_true", help="지운 차량을 glTF 로 다시 넣는다 (IBL 이 없으면 굽는다)")
+    agm.add_argument("--out", help="기본 outputs/aug/map")
+    agm.set_defaults(func=_cmd_aug_map)
+    agx = ag.add_parser("artifixer", help="ArtiFixer 확산 보정 + 차선 후처리 증강 (configs/aug/artifixer.json) → outputs/aug/aug_artfixer/<씬>_lanefix")
+    agx.add_argument("names", nargs="*", help="씬 (기본: 학습 · aug map 이 끝난 씬 전부, 끝난 순서대로)")
+    agx.add_argument("--cams", help="카메라들 (쉼표, 기본 설정 cams = CAM_FRONT)")
+    agx.add_argument("--root", help="일괄 재구성 루트 (기본 outputs/gs_day)")
+    agx.add_argument("--limit", type=int, help="안 끝난 씬 중 앞에서 N개만")
+    agx.add_argument("--force", action="store_true", help="끝났어도 다시")
+    agx.set_defaults(func=_cmd_aug_artifixer)
+    agt = ag.add_parser("translate", help="밤·비 영상 → 낮 (CycleGAN-Turbo) → outputs/aug/translate/<모델>/ (원본과 같은 상대 경로)")
+    agt.add_argument("names", nargs="+")
+    agt.add_argument("--models", default="night_to_day",
+                     help="차례로 적용할 변환 (쉼표): night_to_day, rainy_to_clear — 예: rainy_to_clear,night_to_day")
+    agt.add_argument("--size", default="912x512", help="모델 입력 크기 (8의 배수). 원본 비율 16:9")
+    agt.add_argument("--stride", type=int, default=1)
+    agt.add_argument("--keyframes-only", action="store_true")
+    agt.add_argument("--out", help="기본 outputs/aug/translate")
+    agt.set_defaults(func=_cmd_aug_translate)
+    sm = sub.add_parser("sim", help="closed-loop 평가 (HUGSIM 식: 시나리오 · 정책 · HD-Score)").add_subparsers(dest="sub", required=True)
+    smr = sm.add_parser("run", help="시나리오 하나를 정책으로 끝까지 (창 없음, vkgs_viewer --serve) → 에피소드 로그 + HD-Score")
+    smr.add_argument("scenario", help="configs/scenarios/<이름>.json 의 이름 또는 경로")
+    smr.add_argument("--policy", default="replay", help="replay (기록 궤적 전문가) | constant (일정 속도 직진)")
+    smr.add_argument("--out", help="기본 outputs/closed_loop/<시나리오>/<정책>")
+    smr.add_argument("--size", help="관측 해상도 WxH (기본 configs/closed_loop.json render)")
+    smr.add_argument("--max-duration", type=float, help="제한 시간 덮어쓰기 (초)")
+    smr.add_argument("--no-front", action="store_true", help="전방 카메라 jpg 를 남기지 않는다")
+    smr.add_argument("--no-video", action="store_true", help="front.mp4 를 만들지 않는다")
+    smr.set_defaults(func=_cmd_sim_run)
+    sms = sm.add_parser("score", help="에피소드 로그 → NC/DAC/TTC/COM/Rc/HD-Score")
+    sms.add_argument("episodes", nargs="+", help="에피소드 디렉터리 (episode.json + steps.csv)")
+    sms.add_argument("-v", "--verbose", action="store_true", help="결정 시점마다")
+    sms.add_argument("--json", action="store_true")
+    sms.set_defaults(func=_cmd_sim_score)
+    smm = sm.add_parser("make-scenarios", help="일괄 재구성 씬(구간이 다 끝난 것)마다 Easy 시나리오 → configs/scenarios/")
+    smm.add_argument("scenes", nargs="*", help="기본: --root 의 모든 씬")
+    smm.add_argument("--root", help="기본 outputs/gs_day")
+    smm.add_argument("--route-m", type=float, help="경로 길이 상한 (기본 configs/closed_loop.json scenarios.route_m, 0 = 끝까지)")
+    smm.add_argument("--out", help="기본 configs/scenarios")
+    smm.set_defaults(func=_cmd_sim_make_scenarios)
+    d = sub.add_parser("doctor", help="환경 진단 (vkgs-doctor 와 동일)")
+    d.set_defaults(func=_cmd_doctor)
+
+    return p
+
+
+def _preset_defaults(argv: list[str] | None) -> dict:
+    """`recon train --preset X` 의 프리셋 값 (configs/train/X.json). 명령줄 값이 우선하도록 기본값으로만 쓴다."""
+    av = sys.argv[1:] if argv is None else argv
+    if "--preset" not in av or av[:2] != ["recon", "train"]:
+        return {}
+    from nusim.config import train_preset
+
+    return train_preset(av[av.index("--preset") + 1])
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    preset = _preset_defaults(argv)
+    if preset:
+        rt = parser._nusim_train  # recon train 하위 파서
+        known = {a.dest for a in rt._actions}
+        bad = sorted(set(preset) - known)
+        if bad:
+            print(f"\033[1;31m오류:\033[0m 프리셋에 모르는 키: {bad} (nusim recon train --help)", file=sys.stderr)
+            return 1
+        rt.set_defaults(**preset)
+    argv = list(sys.argv[1:] if argv is None else argv)
+    tail = []
+    if "--" in argv and argv[:2] == ["render", "map"]:  # render map 의 '--' 뒤 = 뷰어 옵션
+        k = argv.index("--")
+        argv, tail = argv[:k], argv[k + 1:]
+    args = parser.parse_args(argv)
+    if tail:
+        args.viewer_args = tail
+    try:
+        from nusim.log import setup
+        from nusim.paths import output_dir
+
+        tag = "_".join(x for x in (args.cmd, getattr(args, "sub", None)) if x)
+        path = setup(output_dir() / "logs", tag=tag)
+        LOG.debug("명령 %s  (로그 %s)", " ".join(sys.argv), path)
+    except Exception:  # 로그 설정 실패가 명령을 막으면 안 된다 (예: outputs 쓰기 불가)
+        pass
+    try:
+        return args.func(args)
+    except (FileNotFoundError, RuntimeError, ValueError) as e:
+        print(f"\033[1;31m오류:\033[0m {e}", file=sys.stderr)
+        return 1
+    except KeyboardInterrupt:
+        return 130
+    except BrokenPipeError:  # `nusim index list | head` 처럼 파이프가 먼저 닫힌 경우
+        sys.stderr.close()
+        return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

src/nusim/nusim/config.py

@@ -0,0 +1,57 @@
+"""설정 파일 (configs/*.json) — 코드에 박아 두던 조정값을 한곳에 모은다.
+
+    configs/sim.json          시뮬레이터(뷰어): 날씨 프리셋, 하늘, 3인칭 카메라, 충돌, 자차 (viewer.cpp 도 읽는다)
+    configs/train/<이름>.json  학습 프리셋 — `nusim recon train --preset <이름|경로>` (명령줄 값이 우선)
+    configs/jobs/<이름>.json   작업 정의 — `nusim run <이름|경로>` (nusim.jobs)
+
+JSON 의 "_doc" 키는 설명용이라 무시한다.
+"""
+
+from __future__ import annotations
+
+import json
+from functools import lru_cache
+from pathlib import Path
+
+from nusim.paths import workspace_root
+
+
+def configs_dir() -> Path:
+    return workspace_root() / "configs"
+
+
+def resolve(kind: str, name_or_path: str) -> Path:
+    """'day_map' → configs/<kind>/day_map.json, 경로면 그대로."""
+    p = Path(name_or_path)
+    if p.suffix == ".json" or p.exists():
+        return p if p.is_absolute() or p.exists() else workspace_root() / p
+    return configs_dir() / kind / f"{name_or_path}.json"
+
+
+def load(path: Path) -> dict:
+    if not path.exists():
+        raise FileNotFoundError(f"설정 파일이 없습니다: {path}")
+    return _strip_doc(json.loads(path.read_text()))
+
+
+def _strip_doc(x):
+    if isinstance(x, dict):
+        return {k: _strip_doc(v) for k, v in x.items() if not k.startswith("_doc")}
+    if isinstance(x, list):
+        return [_strip_doc(v) for v in x]
+    return x
+
+
+def sim_config_path() -> Path:
+    return configs_dir() / "sim.json"
+
+
+@lru_cache(maxsize=1)
+def sim_config() -> dict:
+    p = sim_config_path()
+    return load(p) if p.exists() else {}
+
+
+def train_preset(name_or_path: str) -> dict:
+    """학습 프리셋 → argparse dest 이름의 기본값 dict (예: {"iters": 15000, "strategy": "mcmc", ...})."""
+    return load(resolve("train", name_or_path))

src/nusim/nusim/data/__init__.py

@@ -0,0 +1,5 @@
+"""nuScenes 읽기 계층 — 씬 인덱스, 카메라 리그, ego 궤적."""
+
+from nusim.data.index import SceneIndex, build_index, load_catalog, load_scene
+
+__all__ = ["SceneIndex", "build_index", "load_catalog", "load_scene"]

src/nusim/nusim/data/index.py

@@ -0,0 +1,459 @@
+"""싱가포르 씬 인덱스 — 원본 테이블을 한 번만 훑어 캐시로 굳힌다.
+
+왜 이 계층이 필요한가:
+    nuscenes-devkit 의 NuScenes() 는 모든 테이블을 통째로 메모리에 올린다
+    (trainval 기준 2~3분, 10 GB 이상). 파일 목록 하나 보자고 매번 낼 비용이 아니다.
+    게다가 원본은 NFS 위에 있어 반복 접근이 특히 비싸다.
+
+    여기서는 테이블을 스트리밍으로 딱 한 번 훑어 우리가 쓰는 것만 씬별로
+    잘라 로컬 캐시에 저장한다. 이후 조회는 씬 하나당 수 MB 를 읽는 일이 된다.
+
+    devkit 을 대체하려는 게 아니다 — 어노테이션/맵 API 가 필요하면 devkit 을 쓴다.
+    이건 재구성·시뮬레이션 루프가 매번 두드리는 '뜨거운 경로' 만 덜어내는 것이다.
+"""
+
+from __future__ import annotations
+
+import logging
+import gzip
+import json
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Iterable, Iterator, Sequence
+
+from nusim import CAMERAS, SINGAPORE_MAPS
+from nusim.io import iter_json_array
+from nusim.paths import DatasetPaths, cache_dir, dataset
+
+INDEX_VERSION = 4  # 2: LIDAR_TOP 키프레임, 3: 3D 박스 어노테이션, 4: LIDAR_TOP sweep(20 Hz)
+_INDEX_DIRNAME = "scene_index"
+LIDAR = "LIDAR_TOP"
+
+
+# --------------------------------------------------------------------------- 자료구조
+_log = logging.getLogger(__name__).info  # 진행 메시지 기본 출력 → nusim.log (콘솔 + 로그 파일)
+
+
+@dataclass(frozen=True)
+class CameraCalib:
+    """차체(ego) 좌표계 기준 카메라 외부/내부 파라미터.
+
+    translation/rotation 은 nuScenes 의 calibrated_sensor 그대로다:
+    카메라 → ego 변환이며 rotation 은 wxyz 쿼터니언.
+    """
+
+    translation: tuple[float, float, float]
+    rotation: tuple[float, float, float, float]  # w, x, y, z
+    intrinsic: tuple[tuple[float, float, float], ...]  # 3x3
+    width: int
+    height: int
+
+
+@dataclass(frozen=True)
+class Frame:
+    """카메라 한 대의 한 장."""
+
+    timestamp: int  # 마이크로초
+    filename: str  # 데이터셋 루트 기준 상대경로
+    ego_translation: tuple[float, float, float]
+    ego_rotation: tuple[float, float, float, float]  # w, x, y, z, 전역(맵) → ego
+    is_keyframe: bool
+
+    def path(self, paths: DatasetPaths) -> Path:
+        return paths.root / self.filename
+
+
+@dataclass(frozen=True)
+class Box:
+    """키프레임 하나에서 객체 하나의 3D 박스. 전역(맵) 좌표.
+
+    nuScenes sample_annotation 그대로다: size 는 (w, l, h) — 박스 로컬 x 가 길이(l),
+    y 가 폭(w). 꼭짓점 계산은 nusim.data.rig.box_corners 를 쓴다.
+    """
+
+    timestamp: int  # 마이크로초 (키프레임 sample 의 시각)
+    instance: int  # SceneIndex.instances 의 번호
+    translation: tuple[float, float, float]
+    size: tuple[float, float, float]  # w, l, h
+    rotation: tuple[float, float, float, float]  # w, x, y, z
+    attribute: str  # 'vehicle.moving' 등. 없으면 ''
+
+
+@dataclass
+class SceneIndex:
+    """한 씬의 전체 멀티뷰 인덱스."""
+
+    token: str
+    name: str  # 'scene-0001'
+    location: str  # 'singapore-onenorth'
+    description: str
+    log_token: str
+    date_captured: str
+    vehicle: str
+    nbr_samples: int
+    calib: dict[str, CameraCalib] = field(default_factory=dict)
+    frames: dict[str, list[Frame]] = field(default_factory=dict)
+    # LIDAR_TOP 전부 (sweep 20 Hz, 씬당 약 400장). 키프레임(2 Hz)은 is_keyframe 으로 구분한다.
+    # 3DGS 초기화와 깊이 감독(카메라-라이다 융합)에 쓴다.
+    # lidar_calib 의 intrinsic 은 비어 있다 (nuScenes 가 라이다에 주지 않음).
+    lidar_calib: CameraCalib | None = None
+    lidar: list[Frame] = field(default_factory=list)
+
+    def lidar_keyframes(self) -> list[Frame]:
+        return [f for f in self.lidar if f.is_keyframe]
+    # 3D 박스 (키프레임에만 있다). instances[i] = (instance_token, category_name)
+    instances: list[tuple[str, str]] = field(default_factory=list)
+    boxes: list[Box] = field(default_factory=list)
+
+    @property
+    def n_images(self) -> int:
+        return sum(len(v) for v in self.frames.values())
+
+    def window(self, t0: float, t1: float) -> "SceneIndex":
+        """씬 시작부터 [t0, t1] 초 구간만 남긴 사본 (카메라·라이다 프레임). 박스는 그대로 —
+        빠른 씬(수백 m)을 구간별로 나눠 재구성하거나 진단할 때 쓴다."""
+        from dataclasses import replace
+
+        start = min(f.timestamp for fr in self.frames.values() for f in fr[:1])
+        lo, hi = start + int(t0 * 1e6), start + int(t1 * 1e6)
+        keep = lambda fr: [f for f in fr if lo <= f.timestamp <= hi]
+        return replace(self, frames={c: keep(fr) for c, fr in self.frames.items()}, lidar=keep(self.lidar))
+
+    def duration_s(self) -> float:
+        ts = [f.timestamp for v in self.frames.values() for f in v]
+        return (max(ts) - min(ts)) / 1e6 if ts else 0.0
+
+    def keyframes(self, camera: str) -> list[Frame]:
+        return [f for f in self.frames.get(camera, ()) if f.is_keyframe]
+
+    # ---- 직렬화 (캐시는 사람이 읽을 수 있는 gzip JSON) ----
+    def to_json(self) -> dict:
+        return {
+            "index_version": INDEX_VERSION,
+            "scene": {
+                "token": self.token, "name": self.name, "location": self.location,
+                "description": self.description, "log_token": self.log_token,
+                "date_captured": self.date_captured, "vehicle": self.vehicle,
+                "nbr_samples": self.nbr_samples,
+            },
+            "calib": {
+                cam: {
+                    "translation": list(c.translation), "rotation": list(c.rotation),
+                    "intrinsic": [list(r) for r in c.intrinsic],
+                    "width": c.width, "height": c.height,
+                }
+                for cam, c in self.calib.items()
+            },
+            # 프레임은 리스트-of-리스트로 저장한다. 키 이름을 60만 번 반복하는 것보다
+            # 파일이 3배 작고 파싱도 그만큼 빠르다.
+            "frame_schema": ["timestamp", "filename", "ex", "ey", "ez", "qw", "qx", "qy", "qz", "is_keyframe"],
+            "frames": {
+                cam: [
+                    [f.timestamp, f.filename, *f.ego_translation, *f.ego_rotation, int(f.is_keyframe)]
+                    for f in fs
+                ]
+                for cam, fs in self.frames.items()
+            },
+            "lidar_calib": None if self.lidar_calib is None else {
+                "translation": list(self.lidar_calib.translation),
+                "rotation": list(self.lidar_calib.rotation),
+            },
+            "lidar": [
+                [f.timestamp, f.filename, *f.ego_translation, *f.ego_rotation, int(f.is_keyframe)]
+                for f in self.lidar
+            ],
+            "instances": [list(i) for i in self.instances],
+            "box_schema": ["timestamp", "instance", "tx", "ty", "tz", "w", "l", "h",
+                           "qw", "qx", "qy", "qz", "attribute"],
+            "boxes": [
+                [b.timestamp, b.instance, *b.translation, *b.size, *b.rotation, b.attribute]
+                for b in self.boxes
+            ],
+        }
+
+    @classmethod
+    def from_json(cls, d: dict) -> "SceneIndex":
+        if d.get("index_version") != INDEX_VERSION:
+            raise ValueError(
+                f"인덱스 버전 불일치 ({d.get('index_version')} != {INDEX_VERSION}). "
+                "'nusim index build --force' 로 다시 만드세요."
+            )
+        s = d["scene"]
+        obj = cls(**s)
+        obj.calib = {
+            cam: CameraCalib(
+                translation=tuple(c["translation"]), rotation=tuple(c["rotation"]),
+                intrinsic=tuple(tuple(r) for r in c["intrinsic"]),
+                width=c["width"], height=c["height"],
+            )
+            for cam, c in d["calib"].items()
+        }
+        obj.frames = {
+            cam: [
+                Frame(timestamp=r[0], filename=r[1],
+                      ego_translation=(r[2], r[3], r[4]),
+                      ego_rotation=(r[5], r[6], r[7], r[8]),
+                      is_keyframe=bool(r[9]))
+                for r in rows
+            ]
+            for cam, rows in d["frames"].items()
+        }
+        if lc := d.get("lidar_calib"):
+            obj.lidar_calib = CameraCalib(
+                translation=tuple(lc["translation"]), rotation=tuple(lc["rotation"]),
+                intrinsic=(), width=0, height=0,
+            )
+        obj.lidar = [
+            Frame(timestamp=r[0], filename=r[1],
+                  ego_translation=(r[2], r[3], r[4]),
+                  ego_rotation=(r[5], r[6], r[7], r[8]),
+                  is_keyframe=bool(r[9]))
+            for r in d.get("lidar", ())
+        ]
+        obj.instances = [tuple(i) for i in d.get("instances", ())]
+        obj.boxes = [
+            Box(timestamp=r[0], instance=r[1], translation=(r[2], r[3], r[4]),
+                size=(r[5], r[6], r[7]), rotation=(r[8], r[9], r[10], r[11]), attribute=r[12])
+            for r in d.get("boxes", ())
+        ]
+        return obj
+
+
+# --------------------------------------------------------------------------- 빌드
+def _index_dir() -> Path:
+    d = cache_dir() / _INDEX_DIRNAME
+    d.mkdir(parents=True, exist_ok=True)
+    return d
+
+
+def build_index(
+    paths: DatasetPaths | None = None,
+    locations: Sequence[str] = SINGAPORE_MAPS,
+    cameras: Sequence[str] = CAMERAS,
+    include_sweeps: bool = True,
+    force: bool = False,
+    log=_log,
+) -> dict:
+    """테이블을 훑어 씬별 인덱스를 캐시에 쓴다. 카탈로그(dict)를 돌려준다.
+
+    include_sweeps=False 면 키프레임(2 Hz)만 담는다. 재구성 품질은 떨어지지만
+    인덱스가 12배 작아져 빠른 실험에 쓸 만하다.
+    """
+    paths = paths or dataset()
+    out = _index_dir()
+    catalog_path = out / "catalog.json"
+
+    if catalog_path.exists() and not force:
+        log(f"카탈로그가 이미 있습니다: {catalog_path}  (--force 로 재생성)")
+        return json.loads(catalog_path.read_text())
+
+    t0 = time.time()
+
+    # --- 1. 작은 테이블들 (합쳐서 8 MB 남짓) --------------------------------
+    log("1/6  log / scene / sensor / calibrated_sensor 읽는 중")
+    logs = {r["token"]: r for r in iter_json_array(paths.meta / "log.json")}
+    sensors = {r["token"]: r for r in iter_json_array(paths.meta / "sensor.json")}
+    calibs = {r["token"]: r for r in iter_json_array(paths.meta / "calibrated_sensor.json")}
+
+    # calibrated_sensor → 카메라 채널 이름. sample_data 필터링에 이걸 쓴다.
+    cam_set = set(cameras)
+    calib_channel = {
+        tok: sensors[c["sensor_token"]]["channel"]
+        for tok, c in calibs.items()
+        if sensors[c["sensor_token"]]["channel"] in cam_set
+    }
+    lidar_calibs = {
+        tok for tok, c in calibs.items() if sensors[c["sensor_token"]]["channel"] == LIDAR
+    }
+
+    wanted_loc = set(locations)
+    scenes: dict[str, dict] = {}
+    for r in iter_json_array(paths.meta / "scene.json"):
+        lg = logs[r["log_token"]]
+        if lg["location"] in wanted_loc:
+            scenes[r["token"]] = {**r, "_log": lg}
+    log(f"     대상 씬 {len(scenes)}개 ({', '.join(sorted(wanted_loc))})")
+    if not scenes:
+        raise RuntimeError(f"location {sorted(wanted_loc)} 에 해당하는 씬이 없습니다.")
+
+    # --- 2. sample → scene (7 MB) -------------------------------------------
+    log("2/6  sample.json 읽는 중")
+    sample_scene: dict[str, str] = {}
+    sample_ts: dict[str, int] = {}
+    for r in iter_json_array(paths.meta / "sample.json"):
+        if r["scene_token"] in scenes:
+            sample_scene[r["token"]] = r["scene_token"]
+            sample_ts[r["token"]] = r["timestamp"]
+    log(f"     키프레임 샘플 {len(sample_scene):,}개")
+
+    # --- 3. sample_data 스트리밍 (1.35 GB) ----------------------------------
+    # 가장 비싼 단계. 한 번만 훑으면서 필요한 행만 건진다.
+    log("3/6  sample_data.json 스트리밍 (1.35 GB — 30초 내외)")
+    per_scene: dict[str, dict[str, list]] = {t: {c: [] for c in cameras} for t in scenes}
+    need_pose: set[str] = set()
+    scene_calib: dict[str, dict[str, str]] = {t: {} for t in scenes}
+    per_scene_lidar: dict[str, list] = {t: [] for t in scenes}
+    scene_lidar_calib: dict[str, str] = {}
+    seen = kept = 0
+
+    for r in iter_json_array(paths.meta / "sample_data.json"):
+        seen += 1
+        cs = r["calibrated_sensor_token"]
+        chan = calib_channel.get(cs)
+        if chan is None:
+            # 라이다는 sweep 까지 전부 건진다 (RADAR 는 버린다).
+            if cs in lidar_calibs:
+                st = sample_scene.get(r["sample_token"])
+                if st is not None:
+                    per_scene_lidar[st].append(
+                        (r["timestamp"], r["filename"], r["ego_pose_token"], bool(r["is_key_frame"])))
+                    need_pose.add(r["ego_pose_token"])
+                    scene_lidar_calib.setdefault(st, cs)
+            continue
+        st = sample_scene.get(r["sample_token"])
+        if st is None:  # 싱가포르 씬이 아님
+            continue
+        if not include_sweeps and not r["is_key_frame"]:
+            continue
+        per_scene[st][chan].append(
+            (r["timestamp"], r["filename"], r["ego_pose_token"], r["is_key_frame"])
+        )
+        need_pose.add(r["ego_pose_token"])
+        scene_calib[st].setdefault(chan, r["calibrated_sensor_token"])
+        kept += 1
+    log(f"     {seen:,}행 중 {kept:,}행 채택, ego_pose {len(need_pose):,}개 필요")
+
+    # --- 4. ego_pose 스트리밍 (645 MB) --------------------------------------
+    log("4/6  ego_pose.json 스트리밍 (645 MB)")
+    poses: dict[str, tuple] = {}
+    for r in iter_json_array(paths.meta / "ego_pose.json"):
+        if r["token"] in need_pose:
+            t = r["translation"]
+            q = r["rotation"]
+            poses[r["token"]] = (t[0], t[1], t[2], q[0], q[1], q[2], q[3])
+    missing = len(need_pose) - len(poses)
+    if missing:
+        raise RuntimeError(f"ego_pose {missing}개를 찾지 못했습니다 — 데이터셋이 불완전합니다.")
+
+    # --- 5. 3D 박스 (sample_annotation 583 MB) ------------------------------
+    log("5/6  sample_annotation.json 스트리밍 (583 MB)")
+    categories = {r["token"]: r["name"] for r in iter_json_array(paths.meta / "category.json")}
+    attributes = {r["token"]: r["name"] for r in iter_json_array(paths.meta / "attribute.json")}
+    inst_cat = {r["token"]: categories[r["category_token"]]
+                for r in iter_json_array(paths.meta / "instance.json")}
+    per_scene_inst: dict[str, dict[str, int]] = {t: {} for t in scenes}
+    per_scene_boxes: dict[str, list] = {t: [] for t in scenes}
+    n_box = 0
+    for r in iter_json_array(paths.meta / "sample_annotation.json"):
+        st = sample_scene.get(r["sample_token"])
+        if st is None:
+            continue
+        ids = per_scene_inst[st]
+        inst = ids.setdefault(r["instance_token"], len(ids))
+        attr = attributes[r["attribute_tokens"][0]] if r["attribute_tokens"] else ""
+        per_scene_boxes[st].append(Box(
+            timestamp=sample_ts[r["sample_token"]], instance=inst,
+            translation=tuple(r["translation"]), size=tuple(r["size"]),
+            rotation=tuple(r["rotation"]), attribute=attr,
+        ))
+        n_box += 1
+    log(f"     박스 {n_box:,}개")
+
+    # --- 6. 씬별로 쓰기 ------------------------------------------------------
+    log("6/6  씬별 인덱스 기록")
+    catalog = {
+        "index_version": INDEX_VERSION,
+        "built_at": time.strftime("%Y-%m-%dT%H:%M:%S"),
+        "dataset_root": str(paths.root),
+        "version": paths.version,
+        "locations": sorted(wanted_loc),
+        "cameras": list(cameras),
+        "include_sweeps": include_sweeps,
+        "scenes": [],
+    }
+
+    for tok, sc in sorted(scenes.items(), key=lambda kv: kv[1]["name"]):
+        si = SceneIndex(
+            token=tok, name=sc["name"], location=sc["_log"]["location"],
+            description=sc["description"], log_token=sc["log_token"],
+            date_captured=sc["_log"]["date_captured"], vehicle=sc["_log"]["vehicle"],
+            nbr_samples=sc["nbr_samples"],
+        )
+        for cam, cs_tok in scene_calib[tok].items():
+            c = calibs[cs_tok]
+            # 이 채널의 첫 프레임에서 해상도를 가져온다 (씬 안에서는 불변).
+            si.calib[cam] = CameraCalib(
+                translation=tuple(c["translation"]),
+                rotation=tuple(c["rotation"]),
+                intrinsic=tuple(tuple(row) for row in c["camera_intrinsic"]),
+                width=1600, height=900,  # nuScenes 카메라는 전부 1600x900
+            )
+        for cam in cameras:
+            rows = sorted(per_scene[tok][cam])
+            si.frames[cam] = [
+                Frame(timestamp=ts, filename=fn,
+                      ego_translation=poses[ep][:3], ego_rotation=poses[ep][3:],
+                      is_keyframe=bool(kf))
+                for ts, fn, ep, kf in rows
+            ]
+        if cs_tok := scene_lidar_calib.get(tok):
+            c = calibs[cs_tok]
+            si.lidar_calib = CameraCalib(
+                translation=tuple(c["translation"]), rotation=tuple(c["rotation"]),
+                intrinsic=(), width=0, height=0,
+            )
+        si.lidar = [
+            Frame(timestamp=ts, filename=fn,
+                  ego_translation=poses[ep][:3], ego_rotation=poses[ep][3:],
+                  is_keyframe=kf)
+            for ts, fn, ep, kf in sorted(per_scene_lidar[tok])
+        ]
+        si.instances = [(it, inst_cat[it]) for it, _ in
+                        sorted(per_scene_inst[tok].items(), key=lambda kv: kv[1])]
+        si.boxes = sorted(per_scene_boxes[tok], key=lambda b: (b.timestamp, b.instance))
+        _write_scene(si)
+        catalog["scenes"].append({
+            "name": si.name, "token": si.token, "location": si.location,
+            "n_images": si.n_images, "nbr_samples": si.nbr_samples,
+            "duration_s": round(si.duration_s(), 2), "description": si.description,
+        })
+
+    catalog_path.write_text(json.dumps(catalog, indent=2, ensure_ascii=False))
+    total_img = sum(s["n_images"] for s in catalog["scenes"])
+    log(f"완료: 씬 {len(catalog['scenes'])}개 / 이미지 {total_img:,}장 / {time.time()-t0:.1f}초")
+    log(f"     → {out}")
+    return catalog
+
+
+def _write_scene(si: SceneIndex) -> Path:
+    p = _index_dir() / f"{si.name}.json.gz"
+    with gzip.open(p, "wt", encoding="utf-8") as f:
+        json.dump(si.to_json(), f, ensure_ascii=False)
+    return p
+
+
+# --------------------------------------------------------------------------- 조회
+def load_catalog() -> dict:
+    p = _index_dir() / "catalog.json"
+    if not p.exists():
+        raise FileNotFoundError(
+            f"씬 인덱스가 없습니다 ({p}).\n먼저 만드세요:  nusim index build"
+        )
+    return json.loads(p.read_text())
+
+
+def load_scene(name: str) -> SceneIndex:
+    """'scene-0001' 같은 이름으로 씬 인덱스를 읽는다."""
+    p = _index_dir() / f"{name}.json.gz"
+    if not p.exists():
+        raise FileNotFoundError(f"{name} 인덱스가 없습니다 ({p}).  'nusim index build' 를 먼저 실행하세요.")
+    with gzip.open(p, "rt", encoding="utf-8") as f:
+        return SceneIndex.from_json(json.load(f))
+
+
+def iter_scenes(location: str | None = None) -> Iterator[SceneIndex]:
+    for entry in load_catalog()["scenes"]:
+        if location and entry["location"] != location:
+            continue
+        yield load_scene(entry["name"])

src/nusim/nusim/data/rig.py

@@ -0,0 +1,204 @@
+"""카메라 리그 수학 — nuScenes 포즈를 렌더러가 쓰는 행렬로 바꾼다.
+
+좌표계 약속 (이 프로젝트 전체에서 고정):
+
+  global / map   nuScenes 맵 좌표. x=동, y=북, z=위. 미터.
+  ego            차체. x=전방, y=좌, z=상.
+  camera         OpenCV 관례. x=우, y=하, z=전방.  ← nuScenes intrinsic 이 이걸 가정한다
+  clip           Vulkan 관례. NDC x,y ∈ [-1,1], y 아래가 +, z ∈ [0,1].
+
+nuScenes 원본의 의미:
+  ego_pose           .translation/.rotation  = ego → global
+  calibrated_sensor  .translation/.rotation  = camera → ego
+  sample_annotation  .translation/.rotation  = box → global, 박스 중심 기준
+                     .size = (w, l, h). 박스 로컬 x 가 길이(l), y 가 폭(w), z 가 높이
+  쿼터니언은 전부 (w, x, y, z) 순서다.
+
+따라서  camera → global = ego_pose ∘ calib  이고,
+렌더러가 필요로 하는 view 행렬은 그 역이다.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import numpy as np
+
+from nusim.data.index import CameraCalib, Frame
+
+
+def quat_to_matrix(q: tuple[float, float, float, float]) -> np.ndarray:
+    """(w,x,y,z) 쿼터니언 → 3x3 회전행렬.
+
+    pyquaternion 을 쓰지 않는 이유: 이 함수는 프레임마다 6번씩 수십만 번 불린다.
+    의존성 없는 순수 numpy 쪽이 10배 이상 빠르고, 식도 짧다.
+    """
+    w, x, y, z = q
+    n = w * w + x * x + y * y + z * z
+    if n < 1e-12:
+        return np.eye(3)
+    s = 2.0 / n
+    wx, wy, wz = s * w * x, s * w * y, s * w * z
+    xx, xy, xz = s * x * x, s * x * y, s * x * z
+    yy, yz, zz = s * y * y, s * y * z, s * z * z
+    return np.array([
+        [1.0 - (yy + zz), xy - wz,         xz + wy],
+        [xy + wz,         1.0 - (xx + zz), yz - wx],
+        [xz - wy,         yz + wx,         1.0 - (xx + yy)],
+    ])
+
+
+def matrix_to_quat(r: np.ndarray) -> tuple[float, float, float, float]:
+    """3x3 회전행렬 → (w,x,y,z) 쿼터니언 (quat_to_matrix 의 역, w ≥ 0). Shepperd 방법."""
+    m = np.asarray(r, dtype=np.float64)
+    tr = m[0, 0] + m[1, 1] + m[2, 2]
+    if tr > 0:
+        s = 2.0 * np.sqrt(tr + 1.0)
+        q = (0.25 * s, (m[2, 1] - m[1, 2]) / s, (m[0, 2] - m[2, 0]) / s, (m[1, 0] - m[0, 1]) / s)
+    elif m[0, 0] > m[1, 1] and m[0, 0] > m[2, 2]:
+        s = 2.0 * np.sqrt(1.0 + m[0, 0] - m[1, 1] - m[2, 2])
+        q = ((m[2, 1] - m[1, 2]) / s, 0.25 * s, (m[0, 1] + m[1, 0]) / s, (m[0, 2] + m[2, 0]) / s)
+    elif m[1, 1] > m[2, 2]:
+        s = 2.0 * np.sqrt(1.0 + m[1, 1] - m[0, 0] - m[2, 2])
+        q = ((m[0, 2] - m[2, 0]) / s, (m[0, 1] + m[1, 0]) / s, 0.25 * s, (m[1, 2] + m[2, 1]) / s)
+    else:
+        s = 2.0 * np.sqrt(1.0 + m[2, 2] - m[0, 0] - m[1, 1])
+        q = ((m[1, 0] - m[0, 1]) / s, (m[0, 2] + m[2, 0]) / s, (m[1, 2] + m[2, 1]) / s, 0.25 * s)
+    q = np.asarray(q)
+    q = q / np.linalg.norm(q)
+    if q[0] < 0:
+        q = -q
+    return tuple(float(x) for x in q)
+
+
+def rt_to_matrix(r: np.ndarray, t) -> np.ndarray:
+    """3x3 회전 + 3벡터 → 4x4 동차변환."""
+    m = np.eye(4)
+    m[:3, :3] = r
+    m[:3, 3] = t
+    return m
+
+
+def box_corners(translation, size, rotation, pad: float = 0.0) -> np.ndarray:
+    """3D 박스 → 전역 좌표 꼭짓점 (8,3). devkit Box.corners() 와 같은 순서.
+
+    pad 는 각 방향으로 더하는 여유(m). 어노테이션 박스는 객체에 딱 붙어 있어서
+    그림자·백미러·보행자 팔다리가 삐져나온다.
+    """
+    w, l, h = (np.asarray(size, dtype=np.float64) + 2 * pad)
+    x = l / 2 * np.array([1, 1, 1, 1, -1, -1, -1, -1])
+    y = w / 2 * np.array([1, -1, -1, 1, 1, -1, -1, 1])
+    z = h / 2 * np.array([1, 1, -1, -1, 1, 1, -1, -1])
+    return np.stack([x, y, z], axis=1) @ quat_to_matrix(rotation).T + np.asarray(translation)
+
+
+def points_in_box(pts: np.ndarray, translation, size, rotation, pad: float = 0.0) -> np.ndarray:
+    """(N,3) 전역 좌표 점 중 박스 안에 있는 것의 bool 마스크."""
+    local = (pts - np.asarray(translation)) @ quat_to_matrix(rotation)  # R^T 를 곱하는 것과 같다
+    w, l, h = (np.asarray(size, dtype=np.float64) + 2 * pad) / 2
+    return (np.abs(local[:, 0]) <= l) & (np.abs(local[:, 1]) <= w) & (np.abs(local[:, 2]) <= h)
+
+
+@dataclass(frozen=True)
+class CameraPose:
+    """한 시점의 카메라 하나. 렌더러에 넘길 것이 전부 들어있다."""
+
+    channel: str
+    timestamp: int
+    c2w: np.ndarray  # 4x4, camera → global
+    K: np.ndarray  # 3x3 intrinsic
+    width: int
+    height: int
+    filename: str = ""
+
+    @property
+    def w2c(self) -> np.ndarray:
+        """view 행렬. 회전은 전치, 평행이동은 그에 맞춰 다시 계산한다
+        (일반 역행렬을 쓰면 수치오차가 누적된다)."""
+        r = self.c2w[:3, :3]
+        m = np.eye(4)
+        m[:3, :3] = r.T
+        m[:3, 3] = -r.T @ self.c2w[:3, 3]
+        return m
+
+    @property
+    def position(self) -> np.ndarray:
+        return self.c2w[:3, 3].copy()
+
+    def projection(self, znear: float = 0.1, zfar: float = 200.0) -> np.ndarray:
+        """intrinsic → Vulkan clip 공간 4x4 투영행렬.
+
+        OpenCV 카메라(y 아래, z 전방)와 Vulkan NDC(y 아래, z ∈ [0,1]) 는 축 방향이 같다.
+        그래서 OpenGL 식과 달리 y 뒤집기도, z 부호 반전도 없다. 정확히
+            ndc_x = 2u/w - 1,  ndc_y = 2v/h - 1   (u,v = K 로 투영한 픽셀 좌표)
+        가 성립하고, tests/test_rig.py 가 이걸 픽셀 단위로 검증한다.
+        """
+        fx, fy = self.K[0, 0], self.K[1, 1]
+        cx, cy = self.K[0, 2], self.K[1, 2]
+        w, h = self.width, self.height
+
+        p = np.zeros((4, 4))
+        p[0, 0] = 2.0 * fx / w
+        p[1, 1] = 2.0 * fy / h
+        # 주점 오프셋. u = fx·x/z + cx 이므로 2u/w-1 = (2fx/w)·x/z + (2cx/w - 1).
+        p[0, 2] = 2.0 * cx / w - 1.0
+        p[1, 2] = 2.0 * cy / h - 1.0
+        # 깊이 [znear, zfar] → [0, 1]
+        p[2, 2] = zfar / (zfar - znear)
+        p[2, 3] = -zfar * znear / (zfar - znear)
+        p[3, 2] = 1.0
+        return p
+
+    def fov_deg(self) -> tuple[float, float]:
+        fx, fy = self.K[0, 0], self.K[1, 1]
+        return (
+            float(np.degrees(2 * np.arctan(self.width / (2 * fx)))),
+            float(np.degrees(2 * np.arctan(self.height / (2 * fy)))),
+        )
+
+
+def camera_pose(frame: Frame, calib: CameraCalib, channel: str) -> CameraPose:
+    """한 프레임 + 그 채널의 캘리브 → CameraPose."""
+    ego2global = rt_to_matrix(quat_to_matrix(frame.ego_rotation), frame.ego_translation)
+    cam2ego = rt_to_matrix(quat_to_matrix(calib.rotation), calib.translation)
+    return CameraPose(
+        channel=channel,
+        timestamp=frame.timestamp,
+        c2w=ego2global @ cam2ego,
+        K=np.asarray(calib.intrinsic, dtype=np.float64),
+        width=calib.width,
+        height=calib.height,
+        filename=frame.filename,
+    )
+
+
+def scene_poses(scene, cameras=None, keyframes_only: bool = False) -> list[CameraPose]:
+    """씬 전체의 카메라 포즈를 시간순으로. 3DGS 학습기의 입력이 되는 형태다."""
+    from nusim import CAMERAS
+
+    out: list[CameraPose] = []
+    for cam in cameras or CAMERAS:
+        calib = scene.calib.get(cam)
+        if calib is None:
+            continue
+        frames = scene.keyframes(cam) if keyframes_only else scene.frames.get(cam, ())
+        out.extend(camera_pose(f, calib, cam) for f in frames)
+    out.sort(key=lambda p: (p.timestamp, p.channel))
+    return out
+
+
+def ego_trajectory(scene, channel: str = "CAM_FRONT") -> np.ndarray:
+    """(N, 8) 배열: t[s], x, y, z, qw, qx, qy, qz.
+
+    closed-loop 시작 상태와 원본 궤적 비교(오픈루프 기준선)에 쓴다.
+    """
+    frames = scene.frames.get(channel, [])
+    if not frames:
+        raise ValueError(f"{scene.name} 에 {channel} 프레임이 없습니다")
+    t0 = frames[0].timestamp
+    return np.array(
+        [
+            [(f.timestamp - t0) / 1e6, *f.ego_translation, *f.ego_rotation]
+            for f in frames
+        ]
+    )

src/nusim/nusim/io/__init__.py

@@ -0,0 +1,5 @@
+"""직렬화 계층 — 대용량 JSON 스트리밍, 3DGS .ply 입출력."""
+
+from nusim.io.jsonstream import iter_json_array, load_table
+
+__all__ = ["iter_json_array", "load_table"]

src/nusim/nusim/io/jsonstream.py

@@ -0,0 +1,103 @@
+"""nuScenes 테이블을 위한 스트리밍 JSON 리더.
+
+왜 필요한가:
+    v1.0-trainval 의 sample_data.json 은 1.3 GB, ego_pose.json 은 645 MB 다.
+    json.load() 로 읽으면 파이썬 객체 그래프가 원본의 4~5배로 부풀어
+    sample_data 하나에 6 GB 안팎을 먹는다. 게다가 이 파일들은 NFS 위에 있어
+    전체를 읽는 것 자체가 비싸다.
+
+    여기서는 최상위 배열의 원소를 하나씩 흘려보낸다. 호출자가 필요한 것만
+    골라 담으면 피크 메모리가 '버퍼 크기 + 고른 것' 으로 떨어진다.
+    실측: sample_data.json 전체 순회 시 피크 ~60 MB.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from pathlib import Path
+from typing import Any, Callable, Iterator
+
+# 원소 사이의 공백과 쉼표. raw_decode 는 idx 가 값의 첫 글자를 가리켜야 한다.
+_GAP = re.compile(r"[\s,]*")
+
+_CHUNK = 1 << 22  # 4 MiB
+# 버퍼 앞쪽의 소비된 부분을 잘라내는 임계치. 매 원소마다 자르면 슬라이스 복사가
+# O(n²) 가 되고, 아예 안 자르면 버퍼가 파일 크기만큼 자란다.
+_COMPACT_AT = 1 << 21  # 2 MiB
+
+
+def iter_json_array(path: str | Path, chunk_size: int = _CHUNK) -> Iterator[Any]:
+    """최상위가 JSON 배열인 파일의 원소를 하나씩 내놓는다.
+
+    nuScenes 의 모든 테이블이 이 모양이다. 다른 모양이면 ValueError 를 낸다.
+    """
+    path = Path(path)
+    dec = json.JSONDecoder()
+
+    with path.open("r", encoding="utf-8") as f:
+        buf = f.read(chunk_size)
+        if not buf:
+            return
+
+        start = buf.find("[")
+        if start < 0:
+            raise ValueError(f"{path}: 최상위 JSON 배열이 아닙니다")
+        pos = start + 1
+
+        while True:
+            pos = _GAP.match(buf, pos).end()
+
+            # 버퍼가 바닥났으면 더 읽는다.
+            if pos >= len(buf):
+                more = f.read(chunk_size)
+                if not more:
+                    return  # 닫는 ']' 없이 끝남 — 잘린 파일이지만 얻은 건 이미 냈다
+                buf = buf[pos:] + more
+                pos = 0
+                continue
+
+            if buf[pos] == "]":
+                return
+
+            try:
+                obj, pos = dec.raw_decode(buf, pos)
+            except ValueError:
+                # 원소가 버퍼 경계에 걸쳤다. 더 읽어서 다시 시도한다.
+                more = f.read(chunk_size)
+                if not more:
+                    raise ValueError(f"{path}: 파일 끝에서 JSON 이 잘렸습니다") from None
+                buf += more
+                continue
+
+            yield obj
+
+            if pos > _COMPACT_AT:
+                buf = buf[pos:]
+                pos = 0
+
+
+def load_table(
+    path: str | Path,
+    keep: Callable[[dict], bool] | None = None,
+    fields: tuple[str, ...] | None = None,
+) -> list[dict]:
+    """테이블을 읽되 원하는 행과 열만 남긴다.
+
+    keep:   행 필터. None 이면 전부.
+    fields: 남길 키. None 이면 전부. 큰 테이블에서는 이걸 주는 게 메모리를 크게 줄인다.
+    """
+    out: list[dict] = []
+    for row in iter_json_array(path):
+        if keep is not None and not keep(row):
+            continue
+        out.append({k: row[k] for k in fields} if fields else row)
+    return out
+
+
+def index_table(path: str | Path, key: str = "token", fields: tuple[str, ...] | None = None) -> dict[str, dict]:
+    """테이블을 key(기본 'token') 로 찾을 수 있는 dict 로 만든다."""
+    out: dict[str, dict] = {}
+    for row in iter_json_array(path):
+        out[row[key]] = {k: row[k] for k in fields} if fields else row
+    return out

src/nusim/nusim/io/ktx2.py

@@ -0,0 +1,139 @@
+"""KTX2 (Khronos Texture 2.0) 쓰기/읽기 — Vulkan 렌더러에 큐브맵·LUT 를 넘기는 포맷.
+
+https://registry.khronos.org/KTX/specs/2.0/ktxspec.v2.html
+필요한 것만: 2D / 큐브맵, mip 체인, 초압축 없음(supercompression 0).
+블록 압축(BC6H) 데이터는 이미 압축된 바이트를 그대로 담는다.
+
+파일 안 데이터 순서는 스펙대로 **작은 mip 부터** 큰 mip 순이고, 각 mip 안에서는 면 0~5 순서다.
+레벨 인덱스는 mip 0(가장 큰 것)부터 적는다.
+"""
+
+from __future__ import annotations
+
+import math
+import struct
+from dataclasses import dataclass
+from pathlib import Path
+
+IDENTIFIER = b"\xabKTX 20\xbb\r\n\x1a\n"
+
+# 쓰는 VkFormat
+VK_FORMAT_R16G16_SFLOAT = 83
+VK_FORMAT_R16G16B16A16_SFLOAT = 97
+VK_FORMAT_BC6H_UFLOAT_BLOCK = 143
+
+_BLOCK = {VK_FORMAT_BC6H_UFLOAT_BLOCK: (4, 4, 16)}  # 블록 가로, 세로, 바이트
+_TEXEL = {VK_FORMAT_R16G16_SFLOAT: 4, VK_FORMAT_R16G16B16A16_SFLOAT: 8}
+
+
+def level_size(vk_format: int, w: int, h: int) -> int:
+    if vk_format in _BLOCK:
+        bw, bh, nb = _BLOCK[vk_format]
+        return ((w + bw - 1) // bw) * ((h + bh - 1) // bh) * nb
+    return w * h * _TEXEL[vk_format]
+
+
+def _dfd(vk_format: int) -> bytes:
+    """기본 데이터 형식 서술자(DFD). 뷰어는 vkFormat 만 보지만 외부 도구 호환을 위해 넣는다."""
+    # KHR_DF_MODEL: RGBSDA=1, BC6H=131 / 전송 함수 LINEAR=1 / 원색 BT709=1
+    if vk_format == VK_FORMAT_BC6H_UFLOAT_BLOCK:
+        model, dims, plane0 = 133, (3, 3, 0, 0), 16  # KHR_DF_MODEL_BC6H (131 은 BC4)
+        # 샘플 1개: 128 비트 블록 전체, 채널 COLOR(0), FLOAT 플래그(0x80)
+        samples = [(0, 127, 0x80, 0, 0x3F800000)]  # sampleUpper = 1.0f (ktx validate 기준)
+    elif vk_format in (VK_FORMAT_R16G16_SFLOAT, VK_FORMAT_R16G16B16A16_SFLOAT):
+        n = 2 if vk_format == VK_FORMAT_R16G16_SFLOAT else 4
+        model, dims, plane0 = 1, (0, 0, 0, 0), 2 * n
+        chan = [0, 1, 2, 15][:n]  # R, G, B, A
+        # FLOAT(0x80) | SIGNED(0x40). 범위 -1..1 의 float 비트
+        samples = [(16 * i, 15, 0xC0, chan[i], (0xBF800000, 0x3F800000)) for i in range(n)]
+    else:
+        raise ValueError(f"DFD 미지원 vkFormat {vk_format}")
+    body = b""
+    for s in samples:
+        off, length, flags, ch, rng = s if len(s) == 5 else (*s, 0)
+        lower, upper = rng if isinstance(rng, tuple) else (0, rng)
+        body += struct.pack("<HBBBBBBII", off, length, (flags | ch) & 0xFF, 0, 0, 0, 0, lower, upper)
+    block_size = 24 + len(body)
+    header = struct.pack("<IHH", 0, 2, block_size)  # vendorId KHRONOS(0)+descriptorType 0, version 2, 블록 크기
+    header += struct.pack("<BBBB", model, 1, 1, 0)  # colorModel, primaries BT709, transfer LINEAR, flags
+    header += struct.pack("<BBBB", *dims)
+    header += struct.pack("<8B", plane0, 0, 0, 0, 0, 0, 0, 0)
+    block = header + body
+    return struct.pack("<I", 4 + len(block)) + block
+
+
+@dataclass
+class Ktx2:
+    vk_format: int
+    width: int
+    height: int
+    faces: int
+    levels: list[list[bytes]]  # levels[mip][face] — mip 0 이 가장 크다
+    kv: dict[str, str] | None = None
+
+
+def write_ktx2(path: str | Path, tex: Ktx2) -> Path:
+    path = Path(path)
+    nlev = len(tex.levels)
+    for m, lv in enumerate(tex.levels):
+        w, h = max(1, tex.width >> m), max(1, tex.height >> m)
+        for f in lv:
+            if len(f) != level_size(tex.vk_format, w, h):
+                raise ValueError(f"mip {m} 크기 {len(f)} != 기대 {level_size(tex.vk_format, w, h)}")
+    dfd = _dfd(tex.vk_format)
+    kvd = b""
+    for k, v in (tex.kv or {}).items():
+        kv = k.encode() + b"\0" + v.encode() + b"\0"
+        kvd += struct.pack("<I", len(kv)) + kv + b"\0" * ((-len(kv)) % 4)
+
+    type_size = 1 if tex.vk_format in _BLOCK else 2
+    # 스펙: mip 데이터 정렬은 정확히 lcm(텍셀/블록 바이트, 4). 더 크게 잡으면 ktx validate 가 거부한다.
+    unit = _BLOCK[tex.vk_format][2] if tex.vk_format in _BLOCK else _TEXEL[tex.vk_format]
+    align = unit * 4 // math.gcd(unit, 4)
+    head_len = 12 + 4 * 9 + 4 * 4 + 8 * 2 + 24 * nlev
+    dfd_off = head_len
+    kvd_off = dfd_off + len(dfd)
+    data_start = kvd_off + len(kvd)
+    data_start += (-data_start) % align
+    # 작은 mip 부터 배치
+    offsets = [0] * nlev
+    blob = b""
+    pos = data_start
+    for m in reversed(range(nlev)):
+        pad = (-pos) % align
+        blob += b"\0" * pad
+        pos += pad
+        offsets[m] = pos
+        lvl = b"".join(tex.levels[m])
+        blob += lvl
+        pos += len(lvl)
+
+    out = IDENTIFIER
+    out += struct.pack("<9I", tex.vk_format, type_size, tex.width, tex.height, 0, 0, tex.faces, nlev, 0)
+    out += struct.pack("<4I", dfd_off, len(dfd), kvd_off if kvd else 0, len(kvd))
+    out += struct.pack("<2Q", 0, 0)
+    for m in range(nlev):
+        n = len(b"".join(tex.levels[m]))
+        out += struct.pack("<3Q", offsets[m], n, n)
+    out += dfd + kvd
+    out += b"\0" * (data_start - len(out))
+    out += blob
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_bytes(out)
+    return path
+
+
+def read_ktx2(path: str | Path) -> Ktx2:
+    b = Path(path).read_bytes()
+    if b[:12] != IDENTIFIER:
+        raise ValueError(f"{path}: KTX2 가 아닙니다")
+    vk_format, _ts, w, h, _d, _layers, faces, nlev, sc = struct.unpack_from("<9I", b, 12)
+    if sc:
+        raise ValueError(f"{path}: 초압축(supercompression {sc}) 미지원")
+    nlev = max(nlev, 1)
+    levels = []
+    for m in range(nlev):
+        off, n, _ = struct.unpack_from("<3Q", b, 12 + 36 + 16 + 16 + 24 * m)
+        per = n // faces
+        levels.append([b[off + f * per: off + (f + 1) * per] for f in range(faces)])
+    return Ktx2(vk_format, w, h, faces, levels)

src/nusim/nusim/io/ply.py

@@ -0,0 +1,170 @@
+"""표준 3DGS .ply 입출력 — 학습기와 Vulkan 렌더러 사이의 유일한 접점.
+
+포맷은 원본 3DGS (Kerbl et al. 2023) 구현이 쓰는 그대로다. 그래서 SIBR 뷰어,
+SuperSplat 같은 외부 도구로도 열린다. binary_little_endian, vertex 하나에 float32:
+
+    x y z                    위치 (씬 원점 기준, 아래 참고)
+    nx ny nz                 항상 0. 원본 포맷에 자리만 있다
+    f_dc_0..2                SH 0차 계수 (RGB)
+    f_rest_0..3(K-1)-1       SH 고차 계수. **채널 우선** — R 의 K-1 개, G, B 순서
+    opacity                  logit (sigmoid 전)
+    scale_0..2               log (exp 전)
+    rot_0..3                 쿼터니언 (w,x,y,z), 정규화 전
+
+씬 원점: nuScenes 전역 좌표는 수천 m 단위라 float32 로 담으면 cm 이하가 뭉개진다.
+그래서 위치는 씬 원점을 뺀 값으로 저장하고, 원점은 헤더의 `comment nusim_origin`
+에 float64 로 남긴다. 표준 리더는 comment 를 무시하므로 호환성이 깨지지 않는다.
+전역 좌표 = 저장된 위치 + origin.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+
+import numpy as np
+
+_ORIGIN_TAG = "nusim_origin"
+
+
+@dataclass
+class Gaussians:
+    """가우시안 집합. 전부 활성화 전(raw) 파라미터다 — 학습기 내부 표현과 같다."""
+
+    means: np.ndarray  # (N,3) 씬 원점 기준
+    scales: np.ndarray  # (N,3) log
+    quats: np.ndarray  # (N,4) wxyz
+    opacities: np.ndarray  # (N,) logit
+    sh0: np.ndarray  # (N,1,3)
+    shN: np.ndarray  # (N,K-1,3), K = (deg+1)^2. deg 0 이면 (N,0,3)
+    origin: np.ndarray = field(default_factory=lambda: np.zeros(3))  # float64, 전역 좌표
+
+    def __len__(self) -> int:
+        return len(self.means)
+
+    @property
+    def sh_degree(self) -> int:
+        k = 1 + self.shN.shape[1]
+        deg = int(round(np.sqrt(k))) - 1
+        if (deg + 1) ** 2 != k:
+            raise ValueError(f"SH 계수 개수 {k} 가 (deg+1)^2 꼴이 아닙니다")
+        return deg
+
+
+def _attr_names(n_rest: int) -> list[str]:
+    return (
+        ["x", "y", "z", "nx", "ny", "nz"]
+        + [f"f_dc_{i}" for i in range(3)]
+        + [f"f_rest_{i}" for i in range(n_rest)]
+        + ["opacity"]
+        + [f"scale_{i}" for i in range(3)]
+        + [f"rot_{i}" for i in range(4)]
+    )
+
+
+def write_ply(path: str | Path, g: Gaussians) -> Path:
+    path = Path(path)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    n = len(g)
+    # (N,K-1,3) → (N,3,K-1) → 평탄화. 원본 3DGS 의 f_rest 순서가 이것이다.
+    rest = np.ascontiguousarray(g.shN.transpose(0, 2, 1)).reshape(n, -1)
+    cols = [
+        g.means, np.zeros((n, 3)), g.sh0.reshape(n, 3), rest,
+        g.opacities.reshape(n, 1), g.scales, g.quats,
+    ]
+    data = np.concatenate([np.asarray(c, dtype=np.float32) for c in cols], axis=1)
+    names = _attr_names(rest.shape[1])
+    assert data.shape[1] == len(names)
+
+    o = np.asarray(g.origin, dtype=np.float64)
+    header = "\n".join(
+        ["ply", "format binary_little_endian 1.0",
+         f"comment {_ORIGIN_TAG} {o[0]!r} {o[1]!r} {o[2]!r}",
+         f"element vertex {n}"]
+        + [f"property float {a}" for a in names]
+        + ["end_header"]
+    ) + "\n"
+
+    tmp = path.with_suffix(path.suffix + ".tmp")
+    with open(tmp, "wb") as f:
+        f.write(header.encode("ascii"))
+        f.write(data.astype("<f4", copy=False).tobytes())
+    tmp.replace(path)  # 렌더러가 반쯤 쓰인 파일을 읽지 않게
+    return path
+
+
+def read_origin(path: str | Path) -> np.ndarray:
+    """헤더만 읽어 씬 원점을 돌려준다. 가우시안 200만 개짜리 ply 를 다 읽지 않으려고."""
+    with open(path, "rb") as f:
+        for raw in f:
+            tok = raw.decode("ascii", "replace").split()
+            if tok[:2] == ["comment", _ORIGIN_TAG] and len(tok) == 5:
+                return np.array([float(t) for t in tok[2:5]])
+            if tok[:1] == ["end_header"]:
+                break
+    return np.zeros(3)
+
+
+def read_count(path: str | Path) -> int:
+    """헤더만 읽어 가우시안 수 (element vertex)."""
+    with open(path, "rb") as f:
+        for raw in f:
+            tok = raw.decode("ascii", "replace").split()
+            if tok[:2] == ["element", "vertex"]:
+                return int(tok[2])
+            if tok[:1] == ["end_header"]:
+                break
+    raise ValueError(f"{path}: element vertex 가 없다")
+
+
+def read_ply(path: str | Path) -> Gaussians:
+    path = Path(path)
+    with open(path, "rb") as f:
+        if f.readline().strip() != b"ply":
+            raise ValueError(f"{path}: ply 파일이 아닙니다")
+        names: list[str] = []
+        n = None
+        origin = np.zeros(3)
+        while True:
+            line = f.readline()
+            if not line:
+                raise ValueError(f"{path}: end_header 가 없습니다")
+            tok = line.decode("ascii").split()
+            if not tok:
+                continue
+            if tok[0] == "format" and tok[1] != "binary_little_endian":
+                raise ValueError(f"{path}: {tok[1]} 는 지원하지 않습니다")
+            elif tok[0] == "comment" and len(tok) == 5 and tok[1] == _ORIGIN_TAG:
+                origin = np.array([float(t) for t in tok[2:5]])
+            elif tok[0] == "element":
+                if tok[1] != "vertex":
+                    raise ValueError(f"{path}: vertex 외 element({tok[1]}) 는 지원하지 않습니다")
+                n = int(tok[2])
+            elif tok[0] == "property":
+                if tok[1] != "float":
+                    raise ValueError(f"{path}: float 가 아닌 속성 {tok[1]} {tok[2]}")
+                names.append(tok[2])
+            elif tok[0] == "end_header":
+                break
+        if n is None:
+            raise ValueError(f"{path}: vertex 개수가 없습니다")
+        data = np.frombuffer(f.read(n * len(names) * 4), dtype="<f4").reshape(n, len(names))
+
+    col = {a: i for i, a in enumerate(names)}
+
+    def pick(prefix: str, k: int) -> np.ndarray:
+        return data[:, [col[f"{prefix}{i}"] for i in range(k)]]
+
+    n_rest = sum(1 for a in names if a.startswith("f_rest_"))
+    if n_rest % 3:
+        raise ValueError(f"{path}: f_rest 개수 {n_rest} 가 3의 배수가 아닙니다")
+    rest = pick("f_rest_", n_rest).reshape(n, 3, n_rest // 3).transpose(0, 2, 1)
+    return Gaussians(
+        means=data[:, [col["x"], col["y"], col["z"]]].copy(),
+        scales=pick("scale_", 3).copy(),
+        quats=pick("rot_", 4).copy(),
+        opacities=data[:, col["opacity"]].copy(),
+        sh0=pick("f_dc_", 3).reshape(n, 1, 3).copy(),
+        shN=np.ascontiguousarray(rest),
+        origin=origin,
+    )

src/nusim/nusim/jobs.py

@@ -0,0 +1,116 @@
+"""작업 정의(JSON) 실행기 — `nusim run <configs/jobs/이름.json>`.
+
+실험마다 셸 대기열 스크립트(cache/queue_*.sh)를 새로 쓰던 것을 대신한다. 작업 파일 형식:
+
+    {
+      "name": "quality_2026-10-05",
+      "vars": {"iters": "15000", "base": "--strategy mcmc --depth-lambda 0.1 --objects agents"},
+      "steps": [
+        {"name": "pilot-${s}", "foreach": {"s": ["scene-0184", "scene-0402"]},
+         "clean": ["outputs/gs_day/${s}"],
+         "run": "recon batch --scenes ${s} --no-sky --iters ${iters}"},
+        {"name": "exp-fullres", "run": "recon train scene-0003 ${base} --iters ${iters} --downscale 1 --out outputs/gs_exp/fullres"}
+      ]
+    }
+
+- run: nusim 하위 명령 (문자열이면 공백으로 나눈다, 목록도 된다). ${변수} 는 vars·foreach 값으로 바꾼다.
+- foreach: 변수마다 값 목록 — 단계가 값 수만큼 펼쳐진다 (여러 변수면 곱). 값이 객체면 ${e.id}, ${e.args} 처럼.
+- clean: 실행 전에 지울 디렉터리 (다시 만들 결과).
+- continue_on_error: 실패해도 다음 단계로 (기본 true — 밤새 도는 대기열이 한 단계 때문에 멈추지 않게).
+상태는 outputs/jobs/<name>/state.json — 같은 이름·같은 명령으로 끝난 단계는 다시 실행하지 않는다 (이어 하기).
+단계마다 로그 outputs/jobs/<name>/<단계>.log.
+"""
+
+from __future__ import annotations
+
+import itertools
+import json
+import logging
+import re
+import shlex
+import shutil
+import subprocess
+import time
+from pathlib import Path
+
+LOG = logging.getLogger(__name__)
+_VAR = re.compile(r"\$\{(\w+(?:\.\w+)*)\}")
+
+
+def _subst(x, env: dict):
+    if isinstance(x, str):
+        def one(m):
+            v = env
+            for part in m.group(1).split("."):  # ${e.args} — foreach 값이 객체일 때
+                if not isinstance(v, dict) or part not in v:
+                    raise ValueError(f"정의되지 않은 변수: ${{{m.group(1)}}}")
+                v = v[part]
+            return str(v)
+        return _VAR.sub(one, x)
+    if isinstance(x, list):
+        return [_subst(v, env) for v in x]
+    if isinstance(x, dict):
+        return {k: _subst(v, env) for k, v in x.items()}
+    return x
+
+
+def expand(job: dict) -> list[dict]:
+    """foreach 를 펼치고 변수를 채운 단계 목록."""
+    base_env = {k: _subst(v, {}) if isinstance(v, str) and "${" not in v else v for k, v in job.get("vars", {}).items()}
+    # vars 끼리 참조할 수 있게 한 번 더
+    base_env = {k: _subst(v, base_env) for k, v in base_env.items()}
+    out = []
+    for st in job["steps"]:
+        loops = st.get("foreach", {})
+        keys = list(loops)
+        for combo in itertools.product(*(loops[k] for k in keys)) if keys else [()]:
+            env = dict(base_env, **dict(zip(keys, combo)))
+            s = _subst({k: v for k, v in st.items() if k != "foreach"}, env)
+            run = s["run"]
+            s["run"] = shlex.split(run) if isinstance(run, str) else list(run)
+            s.setdefault("name", " ".join(s["run"][:3]))
+            out.append(s)
+    names = [s["name"] for s in out]
+    dup = {n for n in names if names.count(n) > 1}
+    if dup:
+        raise ValueError(f"단계 이름이 겹칩니다 (상태 기록 키): {sorted(dup)}")
+    return out
+
+
+def run_job(path: Path, dry: bool = False, log=LOG.info) -> int:
+    from nusim.config import load
+    from nusim.paths import output_dir, workspace_root
+
+    job = load(path)
+    steps = expand(job)
+    wdir = output_dir() / "jobs" / job["name"]
+    wdir.mkdir(parents=True, exist_ok=True)
+    state_path = wdir / "state.json"
+    state = json.loads(state_path.read_text()) if state_path.exists() else {}
+    fails = 0
+    for k, st in enumerate(steps):
+        name, cmd = st["name"], st["run"]
+        if state.get(name, {}).get("state") == "done" and state[name].get("run") == cmd:
+            log(f"[{k + 1}/{len(steps)}] {name} — 이미 끝남, 건너뜀")
+            continue
+        log(f"[{k + 1}/{len(steps)}] {name}: nusim {' '.join(cmd)}")
+        if dry:
+            continue
+        for c in st.get("clean", []):
+            p = Path(c) if Path(c).is_absolute() else workspace_root() / c
+            if p.exists():
+                shutil.rmtree(p)
+        t0 = time.time()
+        safe = re.sub(r"[^\w.-]+", "_", name)
+        with open(wdir / f"{safe}.log", "w") as f:
+            r = subprocess.run(["nusim", *cmd], stdout=f, stderr=subprocess.STDOUT, cwd=workspace_root())
+        rec = {"run": cmd, "state": "done" if r.returncode == 0 else "failed", "returncode": r.returncode,
+               "seconds": round(time.time() - t0)}
+        state[name] = rec
+        state_path.write_text(json.dumps(state, indent=2, ensure_ascii=False))
+        log(f"    {rec['state']} ({rec['seconds'] / 60:.0f}분)")
+        if r.returncode != 0:
+            fails += 1
+            if not st.get("continue_on_error", job.get("continue_on_error", True)):
+                break
+    return 1 if fails else 0

src/nusim/nusim/log.py

@@ -0,0 +1,67 @@
+"""프로젝트 공용 로그.
+
+모든 모듈은 `logging.getLogger(__name__)` (= "nusim.recon.train" 같은 이름)로 남긴다.
+`setup()` 이 한 번 불리면:
+    콘솔   HH:MM:SS 메시지                         (사람이 보는 진행 상황)
+    파일   날짜 시각.ms 레벨 모듈 | 메시지          (outputs/logs/<명령>_<시각>.log — 나중에 추적용)
+`run_log(path)` 는 학습 같은 긴 작업의 결과 디렉터리에 같은 로그를 한 벌 더 남긴다.
+
+함수들이 받는 `log=` 인자(진행 메시지 콜백)의 기본값은 모듈 로거의 info 다 — print 가 아니다.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import logging
+import sys
+import time
+from pathlib import Path
+
+ROOT = "nusim"
+_FILE_FMT = "%(asctime)s.%(msecs)03d %(levelname)-5s %(name)s | %(message)s"
+_CONSOLE_FMT = "%(asctime)s %(message)s"
+
+
+def get(name: str) -> logging.Logger:
+    return logging.getLogger(name if name.startswith(ROOT) else f"{ROOT}.{name}")
+
+
+def setup(log_dir: Path | None = None, tag: str = "nusim", level: int = logging.INFO,
+          debug_file: bool = True) -> Path | None:
+    """콘솔 + 파일 핸들러를 건다. 두 번 불려도 핸들러가 중복되지 않는다. 로그 파일 경로를 돌려준다."""
+    root = logging.getLogger(ROOT)
+    root.setLevel(logging.DEBUG if debug_file else level)
+    root.propagate = False
+    for h in list(root.handlers):
+        root.removeHandler(h)
+    con = logging.StreamHandler(sys.stdout)
+    con.setLevel(level)
+    con.setFormatter(logging.Formatter(_CONSOLE_FMT, "%H:%M:%S"))
+    root.addHandler(con)
+    path = None
+    if log_dir is not None:
+        log_dir.mkdir(parents=True, exist_ok=True)
+        path = log_dir / f"{tag}_{time.strftime('%Y%m%d-%H%M%S')}.log"
+        fh = logging.FileHandler(path, encoding="utf-8")
+        fh.setLevel(logging.DEBUG if debug_file else level)
+        fh.setFormatter(logging.Formatter(_FILE_FMT, "%Y-%m-%d %H:%M:%S"))
+        root.addHandler(fh)
+    return path
+
+
+@contextlib.contextmanager
+def run_log(path: Path):
+    """with run_log(out_dir / "run.log"): ... — 그 안의 nusim 로그를 이 파일에도 (DEBUG 포함) 남긴다."""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    fh = logging.FileHandler(path, encoding="utf-8")
+    fh.setLevel(logging.DEBUG)
+    fh.setFormatter(logging.Formatter(_FILE_FMT, "%Y-%m-%d %H:%M:%S"))
+    root = logging.getLogger(ROOT)
+    if not root.handlers:  # setup() 없이 라이브러리로 쓰인 경우에도 콘솔에는 나오게
+        setup()
+    root.addHandler(fh)
+    try:
+        yield path
+    finally:
+        root.removeHandler(fh)
+        fh.close()

src/nusim/nusim/paths.py

@@ -0,0 +1,154 @@
+"""데이터셋/작업공간 경로 해석.
+
+컨테이너 안에서는 nuScenes 가 /data/nuscenes 에 읽기전용으로 마운트되고,
+컨테이너 밖(호스트)에서는 NAS 원본 경로를 그대로 쓴다.
+코드가 두 경우를 모두 견디도록 여기 한 곳에서만 결정한다.
+
+우선순위:  명시 인자  >  환경변수 NUSCENES_ROOT  >  config/paths.yaml  >  알려진 후보
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from pathlib import Path
+
+# 컨테이너 마운트 경로가 먼저, 그 다음이 호스트 NAS 경로.
+_ROOT_CANDIDATES = (
+    "/data/nuscenes",
+    "/home/mm/nas2/nuscenes_original_junhan/nuscenes/original/full",
+)
+
+# 루트가 맞는지 판정하는 기준. 이 세 가지가 전부 있어야 우리가 쓰는 파이프라인이 돈다.
+_ROOT_MARKERS = ("v1.0-trainval", "samples", "maps")
+
+
+def workspace_root() -> Path:
+    """프로젝트 루트. 컨테이너에서는 /workspace, 밖에서는 소스 트리를 거슬러 찾는다."""
+    if env := os.environ.get("VKGS_WORKSPACE"):
+        return Path(env)
+    # .../src/nusim/nusim/paths.py → 3단계 위가 프로젝트 루트
+    return Path(__file__).resolve().parents[3]
+
+
+def _looks_like_nuscenes(p: Path) -> bool:
+    return all((p / m).exists() for m in _ROOT_MARKERS)
+
+
+def nuscenes_root(explicit: str | os.PathLike | None = None) -> Path:
+    """nuScenes 데이터셋 루트를 돌려준다. 못 찾으면 무엇을 찾았는지 알려주며 실패한다."""
+    tried: list[str] = []
+
+    for cand in (explicit, os.environ.get("NUSCENES_ROOT")):
+        if not cand:
+            continue
+        p = Path(cand)
+        if _looks_like_nuscenes(p):
+            return p
+        tried.append(f"{p}  (지정됐으나 {_ROOT_MARKERS} 중 일부가 없음)")
+
+    cfg = workspace_root() / "config" / "paths.yaml"
+    if cfg.exists():
+        try:
+            import yaml
+
+            data = yaml.safe_load(cfg.read_text()) or {}
+            if cand := data.get("nuscenes_root"):
+                p = Path(cand)
+                if _looks_like_nuscenes(p):
+                    return p
+                tried.append(f"{p}  (config/paths.yaml)")
+        except Exception as e:  # yaml 이 없거나 깨진 경우 — 치명적이지 않다
+            tried.append(f"{cfg}  (읽기 실패: {e})")
+
+    for cand in _ROOT_CANDIDATES:
+        p = Path(cand)
+        if _looks_like_nuscenes(p):
+            return p
+        tried.append(str(p))
+
+    raise FileNotFoundError(
+        "nuScenes 루트를 찾지 못했습니다. 시도한 경로:\n  "
+        + "\n  ".join(tried)
+        + "\n\n루트에는 다음이 있어야 합니다: "
+        + ", ".join(_ROOT_MARKERS)
+        + "\n환경변수 NUSCENES_ROOT 로 지정하거나 config/paths.yaml 을 고치세요."
+    )
+
+
+@dataclass(frozen=True)
+class DatasetPaths:
+    """nuScenes 루트 아래의 하위 경로 모음. 경로 문자열을 코드 곳곳에 흩지 않기 위함."""
+
+    root: Path
+    version: str = "v1.0-trainval"
+    # 카메라 이미지만 다른 곳에서 읽을 때 (같은 상대 경로) — 예: 밤·비 → 낮으로 바꾼 영상 (nusim.aug.translate).
+    # 라이다·메타·지도는 그대로 root 에서.
+    image_root: Path | None = None
+
+    @property
+    def images(self) -> Path:
+        return self.image_root or self.root
+
+    @property
+    def meta(self) -> Path:
+        """scene.json / sample_data.json 등 테이블이 있는 곳."""
+        return self.root / self.version
+
+    @property
+    def samples(self) -> Path:
+        """키프레임 센서 데이터 (2 Hz)."""
+        return self.root / "samples"
+
+    @property
+    def sweeps(self) -> Path:
+        """비키프레임 센서 데이터 (카메라 12 Hz). 3DGS 재구성에 핵심이다 —
+        키프레임만 쓰면 뷰가 너무 성겨서 가우시안이 수렴하지 않는다."""
+        return self.root / "sweeps"
+
+    @property
+    def maps(self) -> Path:
+        return self.root / "maps"
+
+    @property
+    def map_expansion(self) -> Path:
+        """singapore-onenorth.json 등 벡터 맵. 차선 그래프의 출처다."""
+        return self.root / "maps" / "expansion"
+
+    @property
+    def can_bus(self) -> Path:
+        """scene-XXXX_pose.json 등. ego_pose.json 보다 훨씬 조밀한 자차 상태로,
+        closed-loop 차량 모델 튜닝에 쓴다."""
+        return self.root / "can_bus"
+
+    def check(self) -> dict[str, tuple[bool, Path]]:
+        """각 하위 경로의 존재 여부. 진단(vkgs-doctor)에서 쓴다."""
+        return {
+            name: (path.exists(), path)
+            for name, path in (
+                ("meta", self.meta),
+                ("samples", self.samples),
+                ("sweeps", self.sweeps),
+                ("maps", self.maps),
+                ("map_expansion", self.map_expansion),
+                ("can_bus", self.can_bus),
+            )
+        }
+
+
+def dataset(explicit: str | os.PathLike | None = None, version: str = "v1.0-trainval") -> DatasetPaths:
+    return DatasetPaths(root=nuscenes_root(explicit), version=version)
+
+
+def cache_dir() -> Path:
+    """파생 산출물(씬 인덱스 등). NAS 가 아니라 로컬 디스크여야 한다 —
+    NFS 왕복이 인덱스 조회보다 비싸면 캐시의 의미가 없다."""
+    d = Path(os.environ.get("VKGS_CACHE", workspace_root() / "cache"))
+    d.mkdir(parents=True, exist_ok=True)
+    return d
+
+
+def output_dir() -> Path:
+    d = Path(os.environ.get("VKGS_OUTPUT", workspace_root() / "outputs"))
+    d.mkdir(parents=True, exist_ok=True)
+    return d

src/nusim/nusim/render/__init__.py

@@ -0,0 +1,9 @@
+"""Vulkan 렌더러(src/vkgs/vkgs_viewer) 와의 접점.
+
+    export.py   카메라 리그·맵 선·평가 뷰를 뷰어가 읽는 텍스트 파일로
+    compare.py  같은 카메라에서 학습기(gsplat) 렌더 vs Vulkan 렌더 픽셀 비교 (roadmap 2단계 기준)
+
+    nusim render export  scene-0003     # rig.txt / map.txt / test_views.txt
+    nusim render compare scene-0003     # 오프스크린 렌더 후 PSNR / 평균 오차
+    nusim render view    scene-0003     # 창 모드 뷰어 실행
+"""

src/nusim/pyproject.toml

@@ -0,0 +1,25 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "nusim"
+version = "0.1.0"
+description = "nuScenes 싱가포르 맵 기반 Vulkan 3DGS closed-loop 시뮬레이터"
+requires-python = ">=3.10"
+
+# 실제 설치는 docker/requirements.txt 가 담당한다 (Dockerfile 이 --no-deps 로 건다).
+# 여기 목록은 컨테이너 밖에서 쓸 때를 위한 문서 겸 사양이다.
+dependencies = [
+  "numpy<2.0", "scipy", "Pillow", "opencv-python-headless",
+  "pyquaternion", "shapely<2.0", "cachetools", "matplotlib",
+  "plyfile", "pyyaml", "typer", "rich", "tqdm",
+]
+
+[project.scripts]
+vkgs-doctor = "nusim.cli.doctor:main"
+nusim = "nusim.cli.main:main"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["nusim*"]

src/vkgs/CMakeLists.txt

@@ -0,0 +1,168 @@
+cmake_minimum_required(VERSION 3.22)
+project(vkgs LANGUAGES C CXX)
+
+# 3DGS compute 래스터라이저는 C++20 의 designated initializer 와 <bit> 를 쓴다.
+set(CMAKE_CXX_STANDARD 20)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+set(CMAKE_EXPORT_COMPILE_COMMANDS ON)   # clangd 용
+
+if(NOT CMAKE_BUILD_TYPE)
+  set(CMAKE_BUILD_TYPE RelWithDebInfo)
+endif()
+
+find_package(Vulkan REQUIRED)
+message(STATUS "Vulkan: ${Vulkan_LIBRARY} (헤더 ${Vulkan_INCLUDE_DIR})")
+
+# ---------------------------------------------------------------- 셰이더 컴파일
+# glslc(shaderc) 를 선호하되 없으면 glslangValidator 로 폴백한다.
+# jammy 에서 glslc 는 별도 패키지라 항상 있다고 가정할 수 없다.
+# FindVulkan 이 glslc 를 찾아 주면 그걸 쓰고, 아니면 PATH 에서 찾는다.
+if(Vulkan_GLSLC_EXECUTABLE)
+  set(GLSLC ${Vulkan_GLSLC_EXECUTABLE})
+else()
+  find_program(GLSLC glslc)
+endif()
+find_program(GLSLANG glslangValidator)
+
+if(GLSLC)
+  # -I: gs_common.glsl 같은 공통 헤더를 #include 하기 위함
+  set(SHADER_CMD ${GLSLC} --target-env=vulkan1.2 -O -I ${CMAKE_CURRENT_SOURCE_DIR}/shaders)
+  message(STATUS "셰이더 컴파일러: ${GLSLC}")
+elseif(GLSLANG)
+  # -V 를 반드시 준다. --target-env 만으로 SPIR-V 가 나온다고 기대하면 안 된다 —
+  # 버전에 따라 검증만 하고 -o 를 무시해 빈 파일이 남는다.
+  set(SHADER_CMD ${GLSLANG} -V --target-env vulkan1.2 -I${CMAKE_CURRENT_SOURCE_DIR}/shaders)
+  message(STATUS "셰이더 컴파일러: ${GLSLANG} (glslc 없음)")
+else()
+  message(FATAL_ERROR "glslc 도 glslangValidator 도 없습니다. glslang-tools 를 설치하세요.")
+endif()
+set(SHADER_OUT_FLAG -o)
+
+set(SPIRV_DIR ${CMAKE_BINARY_DIR}/shaders)
+file(MAKE_DIRECTORY ${SPIRV_DIR})
+
+# GLSL 하나를 SPIR-V 로 굽는다. 결과는 빌드 디렉터리의 shaders/ 아래에 놓인다.
+function(vkgs_add_shader SRC)
+  get_filename_component(NAME ${SRC} NAME)
+  set(OUT ${SPIRV_DIR}/${NAME}.spv)
+  add_custom_command(
+    OUTPUT ${OUT}
+    COMMAND ${SHADER_CMD} ${CMAKE_CURRENT_SOURCE_DIR}/${SRC} ${SHADER_OUT_FLAG} ${OUT}
+    # 컴파일러가 조용히 빈 파일을 남기는 경우가 있어 여기서 걸러낸다.
+    COMMAND ${CMAKE_COMMAND} -E cat ${OUT} > /dev/null
+    DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/${SRC} ${CMAKE_CURRENT_SOURCE_DIR}/shaders/gs_common.glsl ${CMAKE_CURRENT_SOURCE_DIR}/shaders/ibl_common.glsl
+            ${CMAKE_CURRENT_SOURCE_DIR}/shaders/depth_common.glsl ${CMAKE_CURRENT_SOURCE_DIR}/shaders/bindless.glsl
+            ${CMAKE_CURRENT_SOURCE_DIR}/shaders/gs_radix_common.glsl ${CMAKE_CURRENT_SOURCE_DIR}/shaders/weather_common.glsl
+    COMMENT "SPIR-V: ${NAME}"
+    VERBATIM)
+  list(APPEND VKGS_SPIRV ${OUT})
+  set(VKGS_SPIRV ${VKGS_SPIRV} PARENT_SCOPE)
+endfunction()
+
+vkgs_add_shader(shaders/smoke.comp)
+vkgs_add_shader(shaders/gs_preprocess.comp)
+vkgs_add_shader(shaders/gs_sort.comp)
+vkgs_add_shader(shaders/gs_radix_hist.comp)
+vkgs_add_shader(shaders/gs_radix_scan.comp)
+vkgs_add_shader(shaders/gs_radix_scatter.comp)
+vkgs_add_shader(shaders/gs_splat.vert)
+vkgs_add_shader(shaders/gs_splat.frag)
+vkgs_add_shader(shaders/line.vert)
+vkgs_add_shader(shaders/line.frag)
+vkgs_add_shader(shaders/env.vert)
+vkgs_add_shader(shaders/env.frag)
+vkgs_add_shader(shaders/pbr.vert)
+vkgs_add_shader(shaders/pbr.frag)
+vkgs_add_shader(shaders/weather.comp)
+vkgs_add_shader(shaders/fxaa.comp)
+vkgs_add_shader(shaders/camera_mode.comp)
+vkgs_add_shader(shaders/precip.vert)
+vkgs_add_shader(shaders/precip.frag)
+vkgs_add_shader(shaders/sky_sim.frag)
+vkgs_add_shader(shaders/pbr_gltf.vert)
+vkgs_add_shader(shaders/pbr_gltf.frag)
+vkgs_add_shader(shaders/shadow.vert)
+vkgs_add_shader(shaders/shadow.frag)
+
+# 셰이더 그래프 (configs/shader_graphs/*.json) → scripts/shader_graph.py 가 GLSL 로 펼침 → SPIR-V.
+# 그래프 JSON·노드 라이브러리(shaders/nodes/*.glsl)·생성기가 바뀌면 다시 만든다. 매개변수 표(.params.json)는
+# SPIR-V 옆에 놓여 뷰어가 슬라이더·초깃값에 쓴다.
+find_program(VKGS_PYTHON NAMES python3 python REQUIRED)
+set(GRAPH_DIR ${CMAKE_CURRENT_SOURCE_DIR}/../../configs/shader_graphs)
+set(GRAPH_GEN ${CMAKE_CURRENT_SOURCE_DIR}/../../scripts/shader_graph.py)
+file(GLOB VKGS_SHADER_GRAPHS CONFIGURE_DEPENDS ${GRAPH_DIR}/*.json)
+file(GLOB VKGS_NODE_LIBS CONFIGURE_DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/shaders/nodes/*.glsl)
+foreach(G ${VKGS_SHADER_GRAPHS})
+  get_filename_component(GNAME ${G} NAME_WE)
+  set(GSRC ${SPIRV_DIR}/gen/${GNAME}.comp)
+  set(GOUT ${SPIRV_DIR}/${GNAME}.comp.spv)
+  add_custom_command(
+    OUTPUT ${GSRC} ${SPIRV_DIR}/${GNAME}.params.json
+    COMMAND ${VKGS_PYTHON} ${GRAPH_GEN} ${G} --shaders ${CMAKE_CURRENT_SOURCE_DIR}/shaders --out ${SPIRV_DIR}/gen
+    COMMAND ${CMAKE_COMMAND} -E copy ${SPIRV_DIR}/gen/${GNAME}.params.json ${SPIRV_DIR}/${GNAME}.params.json
+    DEPENDS ${G} ${GRAPH_GEN} ${VKGS_NODE_LIBS}
+    COMMENT "셰이더 그래프: ${GNAME}"
+    VERBATIM)
+  add_custom_command(
+    OUTPUT ${GOUT}
+    COMMAND ${SHADER_CMD} ${GSRC} ${SHADER_OUT_FLAG} ${GOUT}
+    DEPENDS ${GSRC} ${CMAKE_CURRENT_SOURCE_DIR}/shaders/bindless.glsl
+    COMMENT "SPIR-V: ${GNAME}.comp (셰이더 그래프)"
+    VERBATIM)
+  list(APPEND VKGS_SPIRV ${GOUT} ${SPIRV_DIR}/${GNAME}.params.json)
+endforeach()
+add_custom_target(vkgs_shaders ALL DEPENDS ${VKGS_SPIRV})
+
+# ---------------------------------------------------------------- 실행파일
+# vkgs_probe: 컨테이너의 Vulkan 경로가 진짜로 동작하는지 끝까지 확인한다.
+#   장치 열거 → 큐 생성 → SPIR-V 로드 → 컴퓨트 디스패치 → 결과 읽기
+# 이 중 하나라도 조용히 실패하면 렌더러는 검은 화면만 낸다.
+add_executable(vkgs_probe src/probe.cpp)
+target_link_libraries(vkgs_probe PRIVATE Vulkan::Vulkan)
+target_compile_definitions(vkgs_probe PRIVATE VKGS_SPIRV_DIR="${SPIRV_DIR}")
+add_dependencies(vkgs_probe vkgs_shaders)
+
+# vkgs_voxcarve: 레이캐스트 센서용 복셀 월드의 빈 공간 깎기 (nusim/sim/voxels.py 가 부른다)
+add_executable(vkgs_voxcarve src/voxcarve.cpp)
+find_package(Threads REQUIRED)
+target_link_libraries(vkgs_voxcarve PRIVATE Threads::Threads)
+
+# vkgs_viewer: 3DGS .ply 를 그린다 (오프스크린 PNG / GLFW 창). roadmap 2a.
+find_package(glfw3 3.3 REQUIRED)
+# Dear ImGui (MIT) — 뷰어 안 슬라이더 UI (합성 날씨·조도). third_party/imgui (v1.91.9)
+set(IMGUI_DIR ${CMAKE_CURRENT_SOURCE_DIR}/../../third_party/imgui)
+# SPIRV-Reflect (Khronos, Apache-2.0) — 셰이더 리플렉션 (src/shader_reflect.*)
+set(SPVR_DIR ${CMAKE_CURRENT_SOURCE_DIR}/../../third_party/SPIRV-Reflect)
+add_executable(vkgs_viewer src/viewer.cpp src/ply.cpp src/gltf.cpp src/shader_reflect.cpp src/render_graph.cpp ${SPVR_DIR}/spirv_reflect.c
+               ${IMGUI_DIR}/imgui.cpp ${IMGUI_DIR}/imgui_draw.cpp ${IMGUI_DIR}/imgui_tables.cpp
+               ${IMGUI_DIR}/imgui_widgets.cpp ${IMGUI_DIR}/backends/imgui_impl_glfw.cpp
+               ${IMGUI_DIR}/backends/imgui_impl_vulkan.cpp)
+# GLFW 헤더가 OpenGL 헤더(GL/gl.h)를 끌어오지 않게 — 우리는 Vulkan 만 쓴다
+set_source_files_properties(${IMGUI_DIR}/backends/imgui_impl_glfw.cpp PROPERTIES COMPILE_DEFINITIONS GLFW_INCLUDE_NONE)
+target_include_directories(vkgs_viewer PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/../../third_party/stb
+                                               ${CMAKE_CURRENT_SOURCE_DIR}/../../third_party/cgltf
+                                               ${IMGUI_DIR} ${IMGUI_DIR}/backends
+                                               ${CMAKE_CURRENT_SOURCE_DIR}/../../third_party
+                                               ${SPVR_DIR})
+target_link_libraries(vkgs_viewer PRIVATE Vulkan::Vulkan glfw)
+target_compile_definitions(vkgs_viewer PRIVATE VKGS_SPIRV_DIR="${SPIRV_DIR}"
+                           VKGS_CONFIG_DEFAULT="${CMAKE_CURRENT_SOURCE_DIR}/../../configs/sim.json"
+                           VKGS_RENDER_GRAPH_DEFAULT="${CMAKE_CURRENT_SOURCE_DIR}/../../configs/render_graph.json"
+                           VKGS_TRACY_PROFILER_DEFAULT="${CMAKE_BINARY_DIR}/tracy-profiler/tracy-profiler")
+add_dependencies(vkgs_viewer vkgs_shaders)
+
+# Tracy 프로파일러 클라이언트 (third_party/tracy v0.11.1, BSD-3). ON_DEMAND: 프로파일러가 붙어 있을 때만 기록 —
+# 평소 실행 비용은 거의 없다. 프로파일러 GUI·캡처 도구 빌드는 scripts/build_tracy.sh.
+option(VKGS_TRACY "Tracy 프로파일링 (CPU·GPU 구간)" ON)
+if(VKGS_TRACY)
+  set(TRACY_DIR ${CMAKE_CURRENT_SOURCE_DIR}/../../third_party/tracy)
+  target_sources(vkgs_viewer PRIVATE ${TRACY_DIR}/public/TracyClient.cpp)
+  target_include_directories(vkgs_viewer PRIVATE ${TRACY_DIR}/public)
+  target_compile_definitions(vkgs_viewer PRIVATE TRACY_ENABLE TRACY_ON_DEMAND)
+  target_link_libraries(vkgs_viewer PRIVATE dl pthread)
+else()
+  target_include_directories(vkgs_viewer PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/../../third_party/tracy/public)
+endif()
+
+install(TARGETS vkgs_probe vkgs_viewer vkgs_voxcarve RUNTIME DESTINATION bin)
+install(DIRECTORY ${SPIRV_DIR}/ DESTINATION share/vkgs/shaders)

src/vkgs/shaders/bindless.glsl

@@ -0,0 +1,20 @@
+// 전역 bindless descriptor set (set 0) — viewer.cpp 의 Bindless 와 같은 binding·슬롯 번호.
+// 모든 파이프라인이 이 set 하나와 같은 push constant 범위를 쓴다. 리소스는 '배열 + 번호' 로 고른다:
+//   binding 0  SSBO[]          셰이더마다 필요한 타입으로 같은 binding 을 별칭 선언한다
+//   binding 1  UBO[]
+//   binding 2  sampler2D[]     glTF 재질 텍스처, BRDF LUT
+//   binding 3  samplerCube[]   IBL specular·irradiance, 학습된 하늘
+//   binding 4  image2D[] 4채널     렌더 타겟·날씨 결과·배경·강수 (형식 없는 storage — 형식은 렌더 그래프 JSON)
+//   binding 5  image2D[] 1~2채널   거리 누적 (RG: Σzα, Σα — depth_common.glsl)
+// 하나뿐인 리소스는 고정 슬롯 (아래 상수), 여러 개인 리소스(재질·텍스처·큐브)는 push constant 나 전역 상수의 번호.
+#extension GL_EXT_nonuniform_qualifier : require
+
+const uint kSsboGlobals = 0u, kSsboGauss = 1u, kSsboSplats = 2u, kSsboKeys = 3u, kSsboDraw = 4u;
+const uint kUboCamera = 0u, kUboWeather = 1u;
+const uint kImgTarget = 0u, kImgPost = 1u;  // rgba32f
+const uint kImgDepthAcc = 0u;               // r32f
+
+layout(set = 0, binding = 2) uniform sampler2D gTex2D[];
+layout(set = 0, binding = 3) uniform samplerCube gCube[];
+// 전역 상수 (SSBO 슬롯 0): ibl = (specular 큐브, irradiance 큐브, BRDF LUT 2D, 학습된 하늘 큐브) 번호
+layout(std430, set = 0, binding = 0) readonly buffer GlobalsBuf { ivec4 ibl; ivec4 pad; } gGlobals[];

src/vkgs/shaders/depth_common.glsl

@@ -0,0 +1,19 @@
+// 거리 누적 버퍼 (렌더 패스 색 첨부 1, RG32F) — 날씨 후처리(weather.comp)·강수 입자(precip.frag)가 쓴다.
+// 그리는 것마다 (z·α, α) 를 색과 같은 premultiplied over 로 쌓는다:
+//   R = Σ z·α·T (카메라 z, m),  G = Σ α·T = 배경을 뺀 덮임 정도 (0 = 배경만, 1 = 불투명한 것이 다 가림)
+// 배경(하늘·환경맵)은 (0, 0) 을 α = 1 로 쓴다 — 앞의 누적을 지우고 덮임 0 에서 시작. 지운 값도 0.
+// 표면 깊이 = R / G, 배경이 보이는 비율 = 1 − G (accum_depth / accum_cover).
+// (2026-10-05 전까지는 R 하나에 배경 1000 m 를 섞어 '기대 깊이' 로 썼다 — 반투명이 3%만 남아도 30 m 가 더해져
+//  빗방울 가림·안개·노면 판정이 틀렸다.)
+const float kNear = 0.2, kFar = 2000.0;  // viewer.cpp RenderCam 기본값과 같다
+const float kSkyDepth = 1000.0;
+
+// Vulkan [0,1] 깊이(gl_FragCoord.z) → 카메라 z (m). viewer.cpp projection() 의 역.
+float linear_depth(float zndc) {
+    return kFar * kNear / (kFar - zndc * (kFar - kNear));
+}
+
+// 누적 버퍼 값 (R, G) → 표면 카메라 z (m). 덮임이 거의 없으면 kSkyDepth.
+float accum_depth(vec2 rg) { return rg.y > 0.02 ? rg.x / rg.y : kSkyDepth; }
+float accum_cover(vec2 rg) { return clamp(rg.y, 0.0, 1.0); }
+

src/vkgs/shaders/env.frag

@@ -0,0 +1,21 @@
+#version 450
+#extension GL_GOOGLE_include_directive : require
+// 환경맵 배경. 3DGS 가 비어 있는(알파 < 1) 곳으로 보인다 — 스플랫이 뒤에 그려지며 덮는다.
+#include "ibl_common.glsl"
+#include "depth_common.glsl"
+layout(location = 0) in vec2 vPix;
+layout(location = 0) out vec4 outColor;
+layout(push_constant) uniform PC {
+    mat4 c2w_rot;
+    vec4 intr;
+    vec4 size;
+    ivec4 idx;      // x = 배경으로 쓸 큐브 번호 (IBL specular 또는 학습된 하늘)
+} pc;
+void main() {
+    vec3 dc = vec3((vPix.x - pc.intr.z) / pc.intr.x, (vPix.y - pc.intr.w) / pc.intr.y, 1.0);
+    vec3 dw = normalize(mat3(pc.c2w_rot) * dc);
+    vec3 lin = textureLod(gCube[pc.idx.x], dw, pc.size.z).rgb;
+    // size.w = 1: 학습된 하늘(sky.ktx2) — LDR 정준 색을 선형으로 담았을 뿐이라 하이라이트 압축을 하지 않는다
+    vec3 c = pc.size.w > 0.5 ? lin : compress_highlights(lin);
+    outColor = vec4(linear_to_srgb(c), 1.0);
+}

src/vkgs/shaders/env.vert

@@ -0,0 +1,14 @@
+#version 450
+// 화면을 덮는 삼각형 하나. 픽셀 → 시선 방향은 프래그먼트에서.
+layout(location = 0) out vec2 vPix;
+layout(push_constant) uniform PC {
+    mat4 c2w_rot;   // 카메라 → 씬 회전 (OpenCV 축)
+    vec4 intr;      // fx fy cx cy
+    vec4 size;      // w h lod -
+    ivec4 idx;      // env.frag 참고
+} pc;
+void main() {
+    vec2 uv = vec2((gl_VertexIndex << 1) & 2, gl_VertexIndex & 2);
+    gl_Position = vec4(uv * 2.0 - 1.0, 1.0, 1.0);
+    vPix = uv * pc.size.xy;
+}

src/vkgs/shaders/fxaa.comp

@@ -0,0 +1,80 @@
+#version 450
+#extension GL_GOOGLE_include_directive : require
+#extension GL_EXT_shader_image_load_formatted : require
+// FXAA (Lottes 3.11 품질 프리셋을 줄인 것) — 화면 공간 안티에일리어싱, 컴퓨트 한 패스.
+// MSAA 는 스플랫 블렌딩을 샘플 수만큼 곱하므로(4× 이면 래스터 4배) 쓰지 않는다. 3DGS 는 원래 부드럽고,
+// 계단은 메시(차량)·맵 선 가장자리에 생긴다 — 그 가장자리만 루마 대비로 찾아 그 방향으로 섞는다.
+// 입력 post(sRGB) → 출력 color(이 시점엔 다 쓴 장면 색 이미지를 빌려 쓴다) → 렌더 그래프가 다시 post 로 복사.
+layout(local_size_x = 8, local_size_y = 8) in;
+#include "bindless.glsl"
+layout(set = 0, binding = 4) uniform image2D gImgF4[];
+#define uIn gImgF4[kImgPost]
+#define uOut gImgF4[kImgTarget]
+
+const float EDGE_MIN = 1.0 / 24.0;    // 어두운 곳에서 이보다 작은 대비는 무시
+const float EDGE_REL = 1.0 / 8.0;     // 주변 최대 루마 대비 상대 임계값
+const float SUBPIX = 0.75;            // 픽셀 이하 계단 완화 정도
+const int STEPS = 8;
+
+ivec2 gSize;
+vec3 at(ivec2 p) { return imageLoad(uIn, clamp(p, ivec2(0), gSize - 1)).rgb; }
+// 양선형 샘플 (storage image 라 직접 섞는다)
+vec3 bilerp(vec2 p) {
+    p -= 0.5;
+    ivec2 i = ivec2(floor(p));
+    vec2 f = p - vec2(i);
+    return mix(mix(at(i), at(i + ivec2(1, 0)), f.x), mix(at(i + ivec2(0, 1)), at(i + ivec2(1, 1)), f.x), f.y);
+}
+float luma(vec3 c) { return dot(c, vec3(0.299, 0.587, 0.114)); }
+
+void main() {
+    gSize = imageSize(uIn);
+    ivec2 p = ivec2(gl_GlobalInvocationID.xy);
+    if (p.x >= gSize.x || p.y >= gSize.y) return;
+    vec4 src = imageLoad(uIn, p);
+    float lM = luma(src.rgb);
+    float lN = luma(at(p + ivec2(0, -1))), lS = luma(at(p + ivec2(0, 1)));
+    float lW = luma(at(p + ivec2(-1, 0))), lE = luma(at(p + ivec2(1, 0)));
+    float lo = min(lM, min(min(lN, lS), min(lW, lE))), hi = max(lM, max(max(lN, lS), max(lW, lE)));
+    float range = hi - lo;
+    if (range < max(EDGE_MIN, hi * EDGE_REL)) { imageStore(uOut, p, src); return; }
+
+    float lNW = luma(at(p + ivec2(-1, -1))), lNE = luma(at(p + ivec2(1, -1)));
+    float lSW = luma(at(p + ivec2(-1, 1))), lSE = luma(at(p + ivec2(1, 1)));
+    // 픽셀 이하 혼합량
+    float avg = (2.0 * (lN + lS + lW + lE) + lNW + lNE + lSW + lSE) / 12.0;
+    float sub = clamp(abs(avg - lM) / range, 0.0, 1.0);
+    sub = smoothstep(0.0, 1.0, sub);
+    sub = sub * sub * SUBPIX;
+    // 가장자리 방향: 가로(위아래로 바뀜) 또는 세로
+    float eH = abs(lNW + lNE - 2.0 * lN) + 2.0 * abs(lW + lE - 2.0 * lM) + abs(lSW + lSE - 2.0 * lS);
+    float eV = abs(lNW + lSW - 2.0 * lW) + 2.0 * abs(lN + lS - 2.0 * lM) + abs(lNE + lSE - 2.0 * lE);
+    bool horz = eH >= eV;
+    float l1 = horz ? lN : lW, l2 = horz ? lS : lE;
+    float g1 = abs(l1 - lM), g2 = abs(l2 - lM);
+    bool steep1 = g1 >= g2;
+    float grad = 0.25 * max(g1, g2);
+    vec2 stepN = horz ? vec2(0.0, steep1 ? -1.0 : 1.0) : vec2(steep1 ? -1.0 : 1.0, 0.0);
+    float lEdge = 0.5 * (lM + (steep1 ? l1 : l2));
+    vec2 c = vec2(p) + 0.5 + 0.5 * stepN;
+    vec2 along = horz ? vec2(1.0, 0.0) : vec2(0.0, 1.0);
+    // 가장자리를 따라 양쪽 끝 찾기
+    vec2 a = c - along, b = c + along;
+    float da = luma(bilerp(a)) - lEdge, db = luma(bilerp(b)) - lEdge;
+    bool doneA = abs(da) >= grad, doneB = abs(db) >= grad;
+    for (int k = 0; k < STEPS && !(doneA && doneB); ++k) {
+        float s = k < 3 ? 1.0 : 2.0;
+        if (!doneA) { a -= along * s; da = luma(bilerp(a)) - lEdge; doneA = abs(da) >= grad; }
+        if (!doneB) { b += along * s; db = luma(bilerp(b)) - lEdge; doneB = abs(db) >= grad; }
+    }
+    vec2 here = vec2(p) + 0.5;
+    float distA = horz ? here.x - a.x : here.y - a.y, distB = horz ? b.x - here.x : b.y - here.y;
+    bool nearA = distA < distB;
+    float dist = min(distA, distB), len = distA + distB;
+    bool smaller = lM - lEdge < 0.0;
+    bool ok = ((nearA ? da : db) < 0.0) != smaller;
+    float off = ok ? 0.5 - dist / len : 0.0;
+    off = max(off, sub);
+    vec3 col = bilerp(here + stepN * off);
+    imageStore(uOut, p, vec4(col, src.a));
+}

src/vkgs/shaders/gs_common.glsl

@@ -0,0 +1,32 @@
+// 3DGS 셰이더 공통 정의. 수식과 상수는 gsplat 1.4.0 (학습기)과 똑같이 맞춘다 —
+// 다르면 학습기 렌더와 Vulkan 렌더가 픽셀 단위로 어긋난다 (roadmap 2단계 합격 기준 < 2%).
+
+// 가우시안 하나 = vec4 15개 (240 B). 3D 공분산은 로드 시 CPU 에서 미리 계산한다.
+struct Gaussian {
+    vec4 pos_opacity;   // xyz = 씬 원점 기준 위치, w = sigmoid 적용된 불투명도
+    vec4 cov_a;         // Σ xx, xy, xz, yy
+    vec4 cov_b;         // Σ yz, zz, -, -
+    vec4 sh[12];        // SH 계수 16개 × RGB = 48 float. sh 계수 k 의 채널 c 는 [k*3+c]
+};
+
+// 화면공간 스플랫 = vec4 3개
+//   [0] = (u, v, radius, opacity)  u,v 는 픽셀 좌표 (gsplat 과 같이 픽셀 중심이 +0.5)
+//   [1] = (conic.xyz, -)            2D 공분산의 역행렬 (a, b, c)
+//   [2] = (rgb, -)
+
+#include "bindless.glsl"
+
+layout(std140, set = 0, binding = 1) uniform Camera {
+    mat4 w2c;          // 씬 원점 기준 world → camera (OpenCV: x 우, y 하, z 전방)
+    vec4 intr;         // fx, fy, cx, cy (픽셀)
+    vec4 size;         // width, height, near, far
+    vec4 campos;       // xyz = 카메라 위치 (씬 원점 기준), w = 높이 클립 (이보다 높은 가우시안은 안 그림)
+    uvec4 counts;      // N, N_pow2, sh_degree, -
+    mat4 obj_xform;    // 객체 에셋(자차 등) 로컬 → 씬 좌표. obj.x 번째 가우시안부터 적용
+    uvec4 obj;         // x = 객체 시작 인덱스 (없으면 N), y = 보이기(1)/숨기기(0)
+    uvec4 objs;        // 장면 객체(차량 에셋 등, 별도 버퍼): x = 가우시안 SSBO 슬롯, y = 객체 번호 SSBO 슬롯,
+                       // z = 객체 표 SSBO 슬롯, w = 객체 가우시안 수. 전역 번호 counts.x + j 가 객체 가우시안 j
+    uvec4 mode;        // 카메라 모드 (camera_mode.comp): x = 0 RGB · 1 깊이 · 2 시맨틱 · 3 흑백,
+                       // y = 시맨틱 차량 색 (RGBA8, 객체 에셋), z = 시맨틱 하늘 색 (RGBA8), w = 깊이 최대 거리 m (float 비트)
+} gCamera[];
+#define cam gCamera[kUboCamera]

src/vkgs/shaders/gs_preprocess.comp

@@ -0,0 +1,145 @@
+#version 450
+#extension GL_GOOGLE_include_directive : require
+// 가우시안마다: 투영 → 2D 공분산 → conic/반지름 → SH 색 → 정렬 키.
+// gsplat fully_fused_projection_fwd.cu / spherical_harmonics.cuh 를 그대로 옮겼다.
+
+layout(local_size_x = 256) in;
+
+#include "gs_common.glsl"
+
+layout(std430, set = 0, binding = 0) readonly buffer Gaussians { Gaussian g[]; } bGauss[];
+layout(std430, set = 0, binding = 0) writeonly buffer Splats { vec4 splat[]; } bSplats[];
+layout(std430, set = 0, binding = 0) writeonly buffer Keys { uvec2 keys[]; } bKeys[];
+layout(std430, set = 0, binding = 0) buffer DrawArgs {
+    uint vertexCount; uint instanceCount; uint firstVertex; uint firstInstance;
+} bDraw[];
+#define g bGauss[kSsboGauss].g
+// 장면 객체 (차량 에셋): 객체 가우시안 j 의 객체 번호, 객체 표 (박스 로컬 → 씬, 보이기)
+layout(std430, set = 0, binding = 0) readonly buffer ObjGaussians { Gaussian og[]; } bObjGauss[];
+layout(std430, set = 0, binding = 0) readonly buffer ObjIds { uint id[]; } bObjIds[];
+struct ObjInstance { mat4 xform; vec4 flags; };  // flags.x = 보이기
+layout(std430, set = 0, binding = 0) readonly buffer ObjTable { ObjInstance inst[]; } bObjTable[];
+#define splat bSplats[kSsboSplats].splat
+#define keys bKeys[kSsboKeys].keys
+#define draw bDraw[kSsboDraw]
+
+const float EPS2D = 0.3;   // gsplat rasterization(eps2d=0.3) — 저역 통과 블러
+
+vec3 sh_color(in Gaussian G, vec3 dir, uint degree) {
+    // sh_coeffs_to_color_fast 와 같은 순서/상수
+    vec3 c[16];
+    for (int k = 0; k < 16; ++k) {
+        int f = k * 3;
+        c[k] = vec3(G.sh[f / 4][f % 4], G.sh[(f + 1) / 4][(f + 1) % 4], G.sh[(f + 2) / 4][(f + 2) % 4]);
+    }
+    vec3 r = 0.2820947917738781 * c[0];
+    if (degree < 1) return r;
+    vec3 d = normalize(dir);
+    float x = d.x, y = d.y, z = d.z;
+    r += 0.48860251190292 * (-y * c[1] + z * c[2] - x * c[3]);
+    if (degree < 2) return r;
+    float z2 = z * z;
+    float fTmp0B = -1.092548430592079 * z;
+    float fC1 = x * x - y * y;
+    float fS1 = 2.0 * x * y;
+    r += (0.5462742152960395 * fS1) * c[4] + (fTmp0B * y) * c[5]
+       + (0.9461746957575601 * z2 - 0.3153915652525201) * c[6]
+       + (fTmp0B * x) * c[7] + (0.5462742152960395 * fC1) * c[8];
+    if (degree < 3) return r;
+    float fTmp0C = -2.285228997322329 * z2 + 0.4570457994644658;
+    float fTmp1B = 1.445305721320277 * z;
+    float fC2 = x * fC1 - y * fS1;
+    float fS2 = x * fS1 + y * fC1;
+    r += (-0.5900435899266435 * fS2) * c[9] + (fTmp1B * fS1) * c[10]
+       + (fTmp0C * y) * c[11] + (z * (1.865881662950577 * z2 - 1.119528997770346)) * c[12]
+       + (fTmp0C * x) * c[13] + (fTmp1B * fC1) * c[14] + (-0.5900435899266435 * fC2) * c[15];
+    return r;
+}
+
+void main() {
+    uint i = gl_GlobalInvocationID.x;
+    uint n = cam.counts.x;
+    if (i >= n + cam.objs.w) return;
+    // 전역 번호 i: [0, n) 배경 (+ 자차 에셋), [n, n + objs.w) 장면 객체 (별도 버퍼, 객체마다 자세)
+    Gaussian G;
+    mat4 X = cam.obj_xform;
+    bool is_obj = false;
+    if (i >= n) {
+        uint j = i - n;
+        G = bObjGauss[cam.objs.x].og[j];
+        ObjInstance oi = bObjTable[cam.objs.z].inst[bObjIds[cam.objs.y].id[j]];
+        if (oi.flags.x < 0.5) return;  // 지웠거나 이 시각에 없는 객체
+        X = oi.xform;
+        is_obj = true;
+    } else {
+        G = g[i];
+        // 객체 에셋(자차): 박스 로컬 좌표 → 이번 프레임의 자차 포즈
+        is_obj = i >= cam.obj.x;
+        if (is_obj && cam.obj.y == 0u) return;
+    }
+    vec3 p = G.pos_opacity.xyz;
+    if (is_obj) p = (X * vec4(p, 1.0)).xyz;
+    // BEV 에서 나무 캐노피가 지면을 덮지 않도록 일정 높이 위는 뺀다
+    if (p.z > cam.campos.w) return;
+    vec3 t = (cam.w2c * vec4(p, 1.0)).xyz;
+    float near = cam.size.z, far = cam.size.w;
+    if (t.z < near || t.z > far) return;
+
+    // world 공분산 → camera 공분산
+    vec4 a = G.cov_a, b = G.cov_b;
+    mat3 S = mat3(a.x, a.y, a.z,
+                  a.y, a.w, b.x,
+                  a.z, b.x, b.y);
+    if (is_obj) {
+        mat3 Ro = mat3(X);
+        S = Ro * S * transpose(Ro);
+    }
+    mat3 W = mat3(cam.w2c);
+    mat3 Sc = W * S * transpose(W);
+
+    // persp_proj: 화면 밖 멀리 있는 가우시안의 야코비안이 폭주하지 않게 x/z 를 자른다
+    float fx = cam.intr.x, fy = cam.intr.y, cx = cam.intr.z, cy = cam.intr.w;
+    float w = cam.size.x, h = cam.size.y;
+    float tan_fovx = 0.5 * w / fx, tan_fovy = 0.5 * h / fy;
+    float lim_x_pos = (w - cx) / fx + 0.3 * tan_fovx;
+    float lim_x_neg = cx / fx + 0.3 * tan_fovx;
+    float lim_y_pos = (h - cy) / fy + 0.3 * tan_fovy;
+    float lim_y_neg = cy / fy + 0.3 * tan_fovy;
+    float rz = 1.0 / t.z, rz2 = rz * rz;
+    float tx = t.z * min(lim_x_pos, max(-lim_x_neg, t.x * rz));
+    float ty = t.z * min(lim_y_pos, max(-lim_y_neg, t.y * rz));
+    vec3 j0 = vec3(fx * rz, 0.0, -fx * tx * rz2);
+    vec3 j1 = vec3(0.0, fy * rz, -fy * ty * rz2);
+    float c00 = dot(j0, Sc * j0) + EPS2D;
+    float c01 = dot(j0, Sc * j1);
+    float c11 = dot(j1, Sc * j1) + EPS2D;
+
+    float det = c00 * c11 - c01 * c01;
+    if (det <= 0.0) return;
+    vec3 conic = vec3(c11, -c01, c00) / det;
+
+    float bb = 0.5 * (c00 + c11);
+    float v1 = bb + sqrt(max(0.01, bb * bb - det));
+    float radius = ceil(3.0 * sqrt(v1));
+    vec2 mean2d = vec2(fx * t.x * rz + cx, fy * t.y * rz + cy);
+    if (mean2d.x + radius <= 0.0 || mean2d.x - radius >= w ||
+        mean2d.y + radius <= 0.0 || mean2d.y - radius >= h) return;
+
+    vec3 rgb;
+    if (cam.mode.x == 2u) {  // 시맨틱 카메라: 라벨 색 (ply.cpp 가 semantic.rgba 를 cov_b.w 에 넣는다). 객체 에셋 = 차량 색
+        rgb = is_obj ? unpackUnorm4x8(cam.mode.y).rgb : unpackUnorm4x8(floatBitsToUint(G.cov_b.w)).rgb;
+    } else {
+        rgb = sh_color(G, p - cam.campos.xyz, cam.counts.z);
+        rgb = max(rgb + 0.5, vec3(0.0));   // gsplat: clamp_min(colors + 0.5, 0)
+    }
+
+    splat[3 * i + 0] = vec4(mean2d, radius, G.pos_opacity.w);
+    splat[3 * i + 1] = vec4(conic, 0.0);
+    splat[3 * i + 2] = vec4(rgb, t.z);  // w = 카메라 깊이 — 메시(PBR)와 깊이 합성용
+
+    // 뒤에서 앞으로 그리므로 먼 것이 먼저 오도록 깊이를 뒤집는다.
+    // 양수 float 의 비트 패턴은 값과 단조 관계라 uint 비교로 정렬된다.
+    // 보이는 것만 앞쪽에 모은다 (정렬은 [0, 보이는 수) 만 한다 — gs_radix_*.comp, bitonic 은 뒤를 채워서)
+    uint slot = atomicAdd(draw.instanceCount, 1u);
+    keys[slot] = uvec2(0xFFFFFFFEu - floatBitsToUint(t.z), i);
+}

src/vkgs/shaders/gs_radix_common.glsl

@@ -0,0 +1,19 @@
+// GPU radix 정렬 (LSD, 8비트 자릿수 × 4패스) 공통 — gs_radix_hist / scan / scatter.comp.
+// 정렬 대상: keys[0, 보이는 수) 의 (key, index). 보이는 수는 GPU 의 인다이렉트 인자에서 읽는다 (CPU 왕복 없음).
+// 워크그룹 수 G 는 고정이고, 워크그룹 g 는 연속 블록 [g·B, (g+1)·B) 를 맡는다 (B = 보이는 수 / G 를 256 배수로 올림).
+// 패스마다 원본 ↔ 임시 버퍼를 오가므로 4패스 뒤 결과는 다시 keys 에 있다. 안정 정렬이다.
+#include "bindless.glsl"
+layout(std430, set = 0, binding = 0) buffer Keys { uvec2 keys[]; } bKeys[];
+layout(std430, set = 0, binding = 0) buffer Hist { uint h[]; } bHist[];
+layout(std430, set = 0, binding = 0) readonly buffer DrawArgs {
+    uint vertexCount; uint instanceCount; uint firstVertex; uint firstInstance;
+} bDraw[];
+// shift = 이번 자릿수 위치, flip = 0 이면 keys → tmp, 1 이면 tmp → keys, groups = G, slots = (keys, tmp, hist)
+layout(push_constant) uniform Radix { uint shift; uint flip; uint groups; uint pad; uvec4 slots; } pc;
+#define SRC bKeys[pc.flip == 0u ? pc.slots.x : pc.slots.y].keys
+#define DST bKeys[pc.flip == 0u ? pc.slots.y : pc.slots.x].keys
+#define HIST bHist[pc.slots.z].h
+const uint RADIX = 256u;
+
+uint radix_count() { return bDraw[kSsboDraw].instanceCount; }
+uint radix_block(uint count) { return ((count + pc.groups - 1u) / pc.groups + 255u) / 256u * 256u; }

src/vkgs/shaders/gs_radix_hist.comp

@@ -0,0 +1,19 @@
+#version 450
+#extension GL_GOOGLE_include_directive : require
+#extension GL_EXT_nonuniform_qualifier : require
+// radix 1/3: 워크그룹마다 자기 블록의 자릿수 히스토그램 → HIST[g·256 + d]
+layout(local_size_x = 256) in;
+#include "gs_radix_common.glsl"
+
+shared uint s_hist[RADIX];
+
+void main() {
+    uint t = gl_LocalInvocationID.x, g = gl_WorkGroupID.x;
+    s_hist[t] = 0u;
+    barrier();
+    uint count = radix_count(), block = radix_block(count);
+    uint b0 = min(g * block, count), b1 = min(b0 + block, count);
+    for (uint i = b0 + t; i < b1; i += 256u) atomicAdd(s_hist[(SRC[i].x >> pc.shift) & 255u], 1u);
+    barrier();
+    HIST[g * RADIX + t] = s_hist[t];
+}

src/vkgs/shaders/gs_radix_scan.comp

@@ -0,0 +1,30 @@
+#version 450
+#extension GL_GOOGLE_include_directive : require
+#extension GL_EXT_nonuniform_qualifier : require
+// radix 2/3 (워크그룹 하나): HIST[g·256 + d] → 그 (자릿수, 워크그룹) 의 출력 시작 위치.
+// 순서는 자릿수 먼저, 같은 자릿수 안에서 워크그룹 순 — 그래서 안정 정렬이 된다.
+layout(local_size_x = 256) in;
+#include "gs_radix_common.glsl"
+
+shared uint s_sum[RADIX];
+
+void main() {
+    uint d = gl_LocalInvocationID.x;
+    uint total = 0u;
+    for (uint g = 0u; g < pc.groups; ++g) total += HIST[g * RADIX + d];
+    s_sum[d] = total;
+    barrier();
+    // 자릿수 합의 배타적 누적 (Hillis–Steele)
+    for (uint off = 1u; off < RADIX; off <<= 1u) {
+        uint v = d >= off ? s_sum[d - off] : 0u;
+        barrier();
+        s_sum[d] += v;
+        barrier();
+    }
+    uint run = s_sum[d] - total;
+    for (uint g = 0u; g < pc.groups; ++g) {
+        uint c = HIST[g * RADIX + d];
+        HIST[g * RADIX + d] = run;
+        run += c;
+    }
+}

src/vkgs/shaders/gs_radix_scatter.comp

@@ -0,0 +1,53 @@
+#version 450
+#extension GL_GOOGLE_include_directive : require
+#extension GL_EXT_nonuniform_qualifier : require
+#extension GL_KHR_shader_subgroup_basic : require
+#extension GL_KHR_shader_subgroup_ballot : require
+// radix 3/3: 블록을 256개씩 차례로, 같은 자릿수끼리의 순위(안정)를 매겨 제자리로 보낸다.
+// 순위: subgroup ballot 8번으로 '같은 자릿수인 레인' 마스크를 만들고 (WLMS), 그 안에서 앞선 레인 수.
+// subgroup 사이는 공유 메모리의 (subgroup, 자릿수) 개수 누적으로 잇는다. subgroup 크기 16 이상이 필요하다 (뷰어가 검사).
+layout(local_size_x = 256) in;
+#include "gs_radix_common.glsl"
+
+const uint MAX_SG = 16u;  // 256 / 16
+shared uint s_off[RADIX];            // 이 워크그룹의 자릿수별 다음 출력 위치
+shared uint s_sg[MAX_SG][RADIX];     // (subgroup, 자릿수) 개수 → 배타적 누적
+
+void main() {
+    uint t = gl_LocalInvocationID.x, g = gl_WorkGroupID.x;
+    uint nsg = gl_NumSubgroups, sg = gl_SubgroupID;
+    s_off[t] = HIST[g * RADIX + t];
+    uint count = radix_count(), block = radix_block(count);
+    uint b0 = min(g * block, count), b1 = min(b0 + block, count);
+    // 원소 순서 = (subgroup, 레인) 순서 — 안정성을 위해 로드 위치를 그 순서로 정한다
+    uint lane_index = sg * gl_SubgroupSize + gl_SubgroupInvocationID;
+    for (uint c = b0; c < b1; c += 256u) {
+        for (uint s = 0u; s < nsg; ++s) s_sg[s][t] = 0u;
+        barrier();
+        uint i = c + lane_index;
+        bool valid = i < b1;
+        uvec2 kv = valid ? SRC[i] : uvec2(0u);
+        uint d = (kv.x >> pc.shift) & 255u;
+        uvec4 peers = subgroupBallot(valid);
+        for (uint b = 0u; b < 8u; ++b) {
+            bool bit = ((d >> b) & 1u) != 0u;
+            uvec4 bal = subgroupBallot(bit);
+            peers &= bit ? bal : ~bal;
+        }
+        uint rank = subgroupBallotExclusiveBitCount(peers);
+        if (valid && subgroupBallotFindLSB(peers) == gl_SubgroupInvocationID)
+            s_sg[sg][d] = subgroupBallotBitCount(peers);
+        barrier();
+        uint run = 0u;  // 스레드 t = 자릿수 t
+        for (uint s = 0u; s < nsg; ++s) {
+            uint v = s_sg[s][t];
+            s_sg[s][t] = run;
+            run += v;
+        }
+        barrier();
+        if (valid) DST[s_off[d] + s_sg[sg][d] + rank] = kv;
+        barrier();
+        s_off[t] += run;
+        barrier();
+    }
+}

src/vkgs/shaders/gs_sort.comp

@@ -0,0 +1,32 @@
+#version 450
+#extension GL_GOOGLE_include_directive : require
+// bitonic 정렬 한 단계 (k, j). (key, index) 쌍을 key 오름차순으로 — 기준 구현 (기본은 radix, gs_radix_*.comp).
+// 전처리가 보이는 것만 [0, 보이는 수) 에 모으므로, k = 0 인 '채우기' 단계가 먼저 뒤쪽을 안 보임 키로 채운다.
+// N=2^21 이면 231 번 디스패치.
+
+layout(local_size_x = 256) in;
+
+#include "bindless.glsl"
+layout(std430, set = 0, binding = 0) buffer Keys { uvec2 keys[]; } bKeys[];
+layout(std430, set = 0, binding = 0) readonly buffer DrawArgs {
+    uint vertexCount; uint instanceCount; uint firstVertex; uint firstInstance;
+} bDraw[];
+#define keys bKeys[kSsboKeys].keys
+layout(push_constant) uniform Step { uint j; uint k; uint n; } pc;
+
+void main() {
+    uint i = gl_GlobalInvocationID.x;
+    if (i >= pc.n) return;
+    if (pc.k == 0u) {  // 채우기: 보이지 않는 자리 → 정렬 후 맨 뒤
+        if (i >= bDraw[kSsboDraw].instanceCount) keys[i] = uvec2(0xFFFFFFFFu, 0u);
+        return;
+    }
+    uint l = i ^ pc.j;
+    if (l <= i) return;
+    uvec2 a = keys[i], b = keys[l];
+    bool ascending = (i & pc.k) == 0u;
+    if (ascending ? (a.x > b.x) : (a.x < b.x)) {
+        keys[i] = b;
+        keys[l] = a;
+    }
+}

src/vkgs/shaders/gs_splat.frag

@@ -0,0 +1,21 @@
+#version 450
+// gsplat rasterize_to_pixels_fwd.cu 의 픽셀 기여 계산과 같다.
+// 뒤→앞 순서로 premultiplied over 블렌딩 (src ONE, dst ONE_MINUS_SRC_ALPHA).
+// 앞→뒤로 합치는 gsplat 과 수학적으로 같고, 다른 점은 gsplat 의 조기 종료(T ≤ 1e-4) 뿐이다.
+
+layout(location = 0) flat in vec2 vCenter;
+layout(location = 1) flat in vec3 vConic;
+layout(location = 2) flat in vec4 vColor;
+layout(location = 3) flat in float vZ;
+layout(location = 0) out vec4 outColor;
+layout(location = 1) out vec4 outDepth;  // 거리 누적 (depth_common.glsl)
+
+void main() {
+    vec2 d = vCenter - gl_FragCoord.xy;   // gl_FragCoord 는 픽셀 중심(+0.5) — gsplat 의 px 와 같다
+    float sigma = 0.5 * (vConic.x * d.x * d.x + vConic.z * d.y * d.y) + vConic.y * d.x * d.y;
+    if (sigma < 0.0) discard;
+    float alpha = min(0.999, vColor.a * exp(-sigma));
+    if (alpha < 1.0 / 255.0) discard;
+    outColor = vec4(vColor.rgb * alpha, alpha);
+    outDepth = vec4(vZ * alpha, alpha, 0.0, alpha);
+}

src/vkgs/shaders/gs_splat.vert

@@ -0,0 +1,33 @@
+#version 450
+#extension GL_GOOGLE_include_directive : require
+#include "bindless.glsl"
+// 정렬된 순서대로 스플랫마다 화면정렬 쿼드 하나 (3σ 반지름). 인스턴스 = 가우시안.
+
+layout(std430, set = 0, binding = 0) readonly buffer Splats { vec4 splat[]; } bSplats[];
+layout(std430, set = 0, binding = 0) readonly buffer Keys { uvec2 keys[]; } bKeys[];
+#define splat bSplats[kSsboSplats].splat
+#define keys bKeys[kSsboKeys].keys
+layout(push_constant) uniform Viewport { vec2 size; vec2 near_far; } pc;
+
+layout(location = 0) flat out vec2 vCenter;
+layout(location = 1) flat out vec3 vConic;
+layout(location = 2) flat out vec4 vColor;   // rgb, opacity
+layout(location = 3) flat out float vZ;      // 가우시안 중심의 카메라 z (거리 누적 버퍼용)
+
+void main() {
+    uint idx = keys[gl_InstanceIndex].y;
+    vec4 s0 = splat[3 * idx + 0];
+    vCenter = s0.xy;
+    vConic = splat[3 * idx + 1].xyz;
+    vColor = vec4(splat[3 * idx + 2].rgb, s0.w);
+
+    vec2 corner = vec2(float(gl_VertexIndex & 1) * 2.0 - 1.0, float(gl_VertexIndex >> 1) * 2.0 - 1.0);
+    vec2 pix = s0.xy + corner * s0.z;
+    // 픽셀 → Vulkan NDC. y 가 아래로 + 라 뒤집지 않는다 (nusim.data.rig 참고).
+    // 깊이 = 가우시안 중심 깊이를 Vulkan [0,1] 로 (nusim.data.rig projection 과 같은 식).
+    // 메시(PBR 구, glTF)가 먼저 깊이를 쓰면 그 뒤의 스플랫이 깊이 테스트로 가려진다.
+    float n = pc.near_far.x, f = pc.near_far.y, z = splat[3 * idx + 2].w;
+    vZ = z;
+    float zndc = f / (f - n) - f * n / ((f - n) * z);
+    gl_Position = vec4(pix / pc.size * 2.0 - 1.0, zndc, 1.0);
+}

src/vkgs/shaders/ibl_common.glsl

@@ -0,0 +1,36 @@
+// IBL 공통 — nusim/render/ibl.py 와 짝.
+// 큐브맵은 씬 좌표(z 위) 방향 벡터로 바로 샘플링한다 (굽는 쪽이 Vulkan 면 표를 그대로 썼다).
+// 색 공간: 큐브맵은 선형 HDR(근사), 3DGS 는 카메라 sRGB(정준 색). 화면은 3DGS 쪽에 맞춘다.
+
+#include "bindless.glsl"
+#define uSpecular gCube[gGlobals[kSsboGlobals].ibl.x]    // GGX 프리필터, mip = 거칠기 × (mips-1)
+#define uIrradiance gCube[gGlobals[kSsboGlobals].ibl.y]  // 복사조도 / π
+#define uBrdfLut gTex2D[gGlobals[kSsboGlobals].ibl.z]    // (NdotV, 거칠기) → (scale, bias)
+
+vec3 linear_to_srgb(vec3 c) {
+    c = max(c, vec3(0.0));
+    return mix(c * 12.92, 1.055 * pow(c, vec3(1.0 / 2.4)) - 0.055, step(vec3(0.0031308), c));
+}
+
+// 굽기 때의 하이라이트 확장(nusim/render/ibl.py expand_highlights: knee 0.75, gain 6)을 되돌려 카메라가 찍었을
+// 밝기로 — 배경 표시용. 정방향 L = l·(1 + 6x²), x = clamp((l − 0.75)/0.25, 0, 1) 은 l 에 대해 단조 증가라
+// 구간 [0.75, 1] 에서 이분법으로 정확히 푼다 (l ≥ 1 이면 L = 7l).
+// 예전 고정점 반복 l ← L/(1+6x(l)²) 은 L 과 L/7 사이를 오가며 발산했고, 짝수 번(4회) 돌아 입력을 그대로
+// 돌려줬다 — 원래 휘도 0.8~1 인 하늘·반사가 최대 7배 밝게 하얗게 날아갔다 (2026-10-02 리뷰).
+vec3 compress_highlights(vec3 lin) {
+    float L = dot(lin, vec3(0.2126, 0.7152, 0.0722));
+    if (L <= 0.75) return lin;
+    float Li;
+    if (L >= 7.0) {
+        Li = L / 7.0;
+    } else {
+        float lo = 0.75, hi = 1.0;
+        for (int k = 0; k < 14; ++k) {
+            float m = 0.5 * (lo + hi);
+            float x = (m - 0.75) / 0.25;
+            if (m * (1.0 + 6.0 * x * x) < L) lo = m; else hi = m;
+        }
+        Li = 0.5 * (lo + hi);
+    }
+    return lin * (Li / L);
+}

src/vkgs/shaders/line.frag

@@ -0,0 +1,7 @@
+#version 450
+layout(location = 0) in vec4 vColor;
+layout(location = 0) out vec4 outColor;
+
+void main() {
+    outColor = vec4(vColor.rgb * vColor.a, vColor.a);   // premultiplied
+}

src/vkgs/shaders/line.vert

@@ -0,0 +1,17 @@
+#version 450
+#extension GL_GOOGLE_include_directive : require
+// 맵 오버레이(차선, 주행가능영역 경계, 궤적). 3DGS 위에 겹쳐 그린다 (깊이 테스트 없음).
+// 투영은 nusim.data.rig.CameraPose.projection 과 같은 Vulkan clip — 근평면 클리핑은 하드웨어가 한다.
+
+#include "bindless.glsl"
+// 정점은 bindless SSBO 에서 직접 읽는다 (vertex pulling): LineVertex = 위치 xyz(씬 원점 기준) + 색 rgba = float 7개
+layout(std430, set = 0, binding = 0) readonly buffer LineVerts { float lv[]; } gLineVerts[];
+layout(push_constant) uniform PC { mat4 viewProj; ivec4 idx; } pc;  // idx.x = 정점 SSBO 슬롯
+layout(location = 0) out vec4 vColor;
+
+void main() {
+    uint b = uint(gl_VertexIndex) * 7u, s = uint(pc.idx.x);
+    vec3 inPos = vec3(gLineVerts[s].lv[b], gLineVerts[s].lv[b + 1u], gLineVerts[s].lv[b + 2u]);
+    vColor = vec4(gLineVerts[s].lv[b + 3u], gLineVerts[s].lv[b + 4u], gLineVerts[s].lv[b + 5u], gLineVerts[s].lv[b + 6u]);
+    gl_Position = pc.viewProj * vec4(inPos, 1.0);
+}

src/vkgs/shaders/nodes/isp.glsl

@@ -0,0 +1,82 @@
+// 셰이더 그래프 노드 라이브러리 — 카메라 ISP (scripts/shader_graph.py 가 읽는다).
+//
+// 함수 하나 = 노드 하나. 이름이 n_<op> 인 함수만 노드다. 시그니처가 곧 노드 정의다:
+//   반환형 n_<op>(입력..., Ctx x, 매개변수...)
+//   - Ctx 앞의 인자 = 입력 포트 (다른 노드의 출력과 타입이 맞아야 한다)
+//   - Ctx 뒤의 float 인자 = 매개변수 (실행 중 슬라이더로 바꾼다 — 매개변수 버퍼에서 읽는다)
+//   - Ctx 가 없으면 입력만 받는 순수 함수
+// 매개변수의 기본값·범위는 바로 위 주석 '// @param 이름 기본값 최솟값 최댓값' 으로 준다 (없으면 0, 0~1).
+// 노드는 픽셀 하나만 본다 (이웃 픽셀을 읽지 않는다) — 그래서 결과를 같은 이미지에 덮어써도 안전하다.
+
+struct Ctx {
+    ivec2 px;    // 픽셀
+    vec2 uv;     // 0~1
+    vec2 size;   // 폭, 높이
+    float time;  // 시뮬레이션 시각 s
+    uint frame;  // 프레임 번호 (노이즈 씨앗)
+};
+
+// sRGB 부호화 ↔ 선형. 렌더 결과(post)는 sRGB 로 부호화돼 있다 (학습 이미지가 JPEG).
+vec3 n_to_linear(vec3 c) { return mix(c / 12.92, pow((max(c, 0.0) + 0.055) / 1.055, vec3(2.4)), step(vec3(0.04045), c)); }
+vec3 n_to_srgb(vec3 c) {
+    c = max(c, vec3(0.0));
+    return mix(c * 12.92, 1.055 * pow(c, vec3(1.0 / 2.4)) - 0.055, step(vec3(0.0031308), c));
+}
+
+// 노출 (EV, 선형 색에)
+// @param ev 0 -3 3
+vec3 n_exposure(vec3 c, Ctx x, float ev) { return c * exp2(ev); }
+
+// 화이트밸런스 — 색온도(+ 따뜻하게 / - 차갑게)·틴트(+ 마젠타 / - 초록) 이득 (선형 색에)
+// @param temperature 0 -1 1
+// @param tint 0 -1 1
+vec3 n_white_balance(vec3 c, Ctx x, float temperature, float tint) {
+    vec3 g = vec3(1.0 + 0.3 * temperature, 1.0 - 0.2 * tint, 1.0 - 0.3 * temperature);
+    return c * g / dot(g, vec3(0.2126, 0.7152, 0.0722));  // 밝기는 유지
+}
+
+// 채도 (1 = 그대로, 0 = 흑백)
+// @param saturation 1 0 2
+vec3 n_saturation(vec3 c, Ctx x, float saturation) {
+    float y = dot(c, vec3(0.2126, 0.7152, 0.0722));
+    return max(mix(vec3(y), c, saturation), 0.0);
+}
+
+// 대비 (중간 회색 기준, sRGB 부호화 색에)
+// @param contrast 1 0.5 1.5
+vec3 n_contrast(vec3 c, Ctx x, float contrast) { return max((c - 0.5) * contrast + 0.5, 0.0); }
+
+// 비네팅 — 렌즈 주변 감광 cos^4 (선형 색에). 시야각은 화면 대각 기준 근사
+// @param vignette 0 0 1
+vec3 n_vignette(vec3 c, Ctx x, float vignette) {
+    vec2 d = (x.uv - 0.5) * vec2(x.size.x / x.size.y, 1.0);
+    float cos_t = inversesqrt(1.0 + dot(d, d) * 1.2);
+    return c * mix(1.0, pow(cos_t, 4.0), vignette);
+}
+
+// 센서 노이즈 — 샷 노이즈(밝기에 비례) + 읽기 노이즈 (선형 색에). 프레임마다 다르다
+// @param shot_noise 0 0 0.05
+// @param read_noise 0 0 0.02
+vec3 n_sensor_noise(vec3 c, Ctx x, float shot_noise, float read_noise) {
+    uvec3 s = uvec3(uvec2(x.px), x.frame);
+    // PCG 해시 3개 → 근사 정규분포 (균등 둘의 합)
+    vec3 n = vec3(0.0);
+    for (int k = 0; k < 2; ++k) {
+        s = s * 1664525u + 1013904223u;
+        s.x += s.y * s.z; s.y += s.z * s.x; s.z += s.x * s.y;
+        s ^= s >> 16u;
+        s.x += s.y * s.z; s.y += s.z * s.x; s.z += s.x * s.y;
+        n += vec3(s) * (1.0 / 4294967296.0) - 0.5;
+    }
+    n *= 2.449;  // 분산 1 로
+    return max(c + n * (shot_noise * sqrt(max(c, 0.0)) + read_noise), 0.0);
+}
+
+// 두 갈래 섞기
+// @param amount 0.5 0 1
+vec3 n_mix(vec3 a, vec3 b, Ctx x, float amount) { return mix(a, b, amount); }
+
+// 밝기 (float 출력 — 타입 검사 예시·마스크용)
+float n_luma(vec3 c) { return dot(c, vec3(0.2126, 0.7152, 0.0722)); }
+// 회색으로 (float → vec3)
+vec3 n_gray(float y) { return vec3(y); }

src/vkgs/shaders/pbr.frag

@@ -0,0 +1,45 @@
+#version 450
+#extension GL_GOOGLE_include_directive : require
+// split-sum IBL (Karis 2013): 확산 = 복사조도·알베도, 정반사 = 프리필터(R, 거칠기)·(F0·A + B)
+#include "ibl_common.glsl"
+#include "depth_common.glsl"
+layout(location = 0) in vec3 vWorld;
+layout(location = 1) in vec3 vNormal;
+layout(location = 0) out vec4 outColor;
+layout(location = 1) out vec4 outDepth;  // 거리 누적 (depth_common.glsl)
+layout(push_constant) uniform PC {
+    mat4 viewProj;
+    vec4 center_radius;
+    vec4 albedo_rough;
+    vec4 metal;
+    vec4 campos;
+    ivec4 idx;
+} pc;
+
+vec3 fresnel_schlick_roughness(float cosT, vec3 F0, float r) {
+    return F0 + (max(vec3(1.0 - r), F0) - F0) * pow(1.0 - cosT, 5.0);
+}
+
+void main() {
+    vec3 N = normalize(vNormal);
+    vec3 V = normalize(pc.campos.xyz - vWorld);
+    vec3 R = reflect(-V, N);
+    float NdotV = max(dot(N, V), 1e-4);
+    vec3 albedo = pc.albedo_rough.rgb;
+    float rough = clamp(pc.albedo_rough.a, 0.0, 1.0);
+    float metallic = pc.metal.x;
+    vec3 F0 = mix(vec3(0.04), albedo, metallic);
+
+    float mips = float(textureQueryLevels(uSpecular));
+    vec3 pref = textureLod(uSpecular, R, rough * (mips - 1.0)).rgb;
+    vec2 ab = texture(uBrdfLut, vec2(NdotV, rough)).rg;
+    vec3 spec = pref * (F0 * ab.x + ab.y);
+
+    vec3 kS = fresnel_schlick_roughness(NdotV, F0, rough);
+    vec3 kD = (1.0 - kS) * (1.0 - metallic);
+    vec3 diffuse = texture(uIrradiance, N).rgb * albedo;
+    vec3 lin = kD * diffuse + spec;
+    // 3DGS 와 같은 카메라 sRGB 공간으로. 하이라이트 확장도 되돌려 장면 밝기와 맞춘다.
+    outColor = vec4(linear_to_srgb(compress_highlights(lin)), 1.0);
+    outDepth = vec4(linear_depth(gl_FragCoord.z), 1.0, 0.0, 1.0);
+}

src/vkgs/shaders/pbr.vert

@@ -0,0 +1,25 @@
+#version 450
+#extension GL_GOOGLE_include_directive : require
+#include "bindless.glsl"
+// IBL 검증용 PBR 메시 (구). glTF 차량도 같은 셰이더 경로로 들어올 것이다.
+// 정점은 bindless SSBO 에서 (vertex pulling): 위치 xyz + 법선 xyz = float 6개
+layout(std430, set = 0, binding = 0) readonly buffer SphereVerts { float sv[]; } gSphereVerts[];
+layout(push_constant) uniform PC {
+    mat4 viewProj;
+    vec4 center_radius;     // 구 중심(씬 좌표), 반지름
+    vec4 albedo_rough;      // rgb 알베도(선형), 거칠기
+    vec4 metal;             // x 금속성
+    vec4 campos;            // 카메라 위치
+    ivec4 idx;              // x = 정점 SSBO 슬롯
+} pc;
+layout(location = 0) out vec3 vWorld;
+layout(location = 1) out vec3 vNormal;
+void main() {
+    uint b = uint(gl_VertexIndex) * 6u, s = uint(pc.idx.x);
+    vec3 inPos = vec3(gSphereVerts[s].sv[b], gSphereVerts[s].sv[b + 1u], gSphereVerts[s].sv[b + 2u]);
+    vec3 inNormal = vec3(gSphereVerts[s].sv[b + 3u], gSphereVerts[s].sv[b + 4u], gSphereVerts[s].sv[b + 5u]);
+    vec3 w = pc.center_radius.xyz + inPos * pc.center_radius.w;
+    vWorld = w;
+    vNormal = inNormal;
+    gl_Position = pc.viewProj * vec4(w, 1.0);
+}

src/vkgs/shaders/pbr_gltf.frag

@@ -0,0 +1,128 @@
+#version 450
+#extension GL_GOOGLE_include_directive : require
+// glTF metallic-roughness + clearcoat + transmission(근사), split-sum IBL.
+#include "ibl_common.glsl"
+#include "depth_common.glsl"
+
+layout(location = 0) in vec3 vWorld;
+layout(location = 1) in vec3 vNormal;
+layout(location = 2) in vec2 vUV0;
+layout(location = 3) in vec2 vUV1;
+layout(location = 4) in vec4 vTangent;
+layout(location = 0) out vec4 outColor;
+layout(location = 1) out vec4 outDepth;  // 거리 누적 (depth_common.glsl)
+
+layout(push_constant) uniform PC {
+    mat4 model;
+    mat4 viewProj;
+    vec4 campos;
+    ivec4 idx;        // x = 재질 SSBO 슬롯, y = 재질 번호
+} pc;
+
+struct Material {     // std430 — viewer.cpp add_gltf 의 MatGPU 와 같은 순서 (304 B)
+    vec4 base;        // 기본색 계수 (선형)
+    vec4 emissive;    // rgb × emissive_strength
+    vec4 mrno;        // metallic, roughness, normal_scale, occlusion_strength
+    vec4 alpha;       // cutoff, mode(0 불투명 1 마스크 2 블렌드), transmission, has_normal_tex
+    vec4 cc;          // clearcoat, clearcoat_roughness, -, -
+    ivec4 tc0;        // texcoord 번호: base, metal-rough, normal, occlusion
+    ivec4 tc1;        // emissive, -, -, -
+    vec4 xf[10];      // KHR_texture_transform: 슬롯마다 2행 (a b c), (d e f)
+    ivec4 tex0;       // 2D 텍스처 번호: base, metal-rough, normal, occlusion (없으면 흰색)
+    ivec4 tex1;       // emissive, -, -, -
+};
+layout(std430, set = 0, binding = 0) readonly buffer Materials { Material m[]; } gMaterials[];
+Material mat;
+#define tBase gTex2D[mat.tex0.x]
+#define tMetalRough gTex2D[mat.tex0.y]
+#define tNormal gTex2D[mat.tex0.z]
+#define tOcclusion gTex2D[mat.tex0.w]
+#define tEmissive gTex2D[mat.tex1.x]
+
+vec2 uv_of(int slot) {
+    int tc = slot < 4 ? mat.tc0[slot] : mat.tc1.x;
+    vec3 uv = vec3(tc == 0 ? vUV0 : vUV1, 1.0);
+    return vec2(dot(mat.xf[2 * slot].xyz, uv), dot(mat.xf[2 * slot + 1].xyz, uv));
+}
+
+vec3 fresnel_schlick_roughness(float cosT, vec3 F0, float r) {
+    return F0 + (max(vec3(1.0 - r), F0) - F0) * pow(1.0 - cosT, 5.0);
+}
+
+vec3 ibl_specular(vec3 R, float rough, vec3 F0, float NdotV) {
+    float mips = float(textureQueryLevels(uSpecular));
+    vec3 pref = textureLod(uSpecular, R, rough * (mips - 1.0)).rgb;
+    vec2 ab = texture(uBrdfLut, vec2(NdotV, rough)).rg;
+    return pref * (F0 * ab.x + ab.y);
+}
+
+void main() {
+    mat = gMaterials[pc.idx.x].m[pc.idx.y];
+    vec4 base = mat.base * texture(tBase, uv_of(0));  // sRGB 뷰라 샘플링이 선형으로 돌려준다
+    if (mat.alpha.y == 1.0 && base.a < mat.alpha.x) discard;
+
+    vec4 mr = texture(tMetalRough, uv_of(1));
+    float metallic = clamp(mat.mrno.x * mr.b, 0.0, 1.0);
+    float rough = clamp(mat.mrno.y * mr.g, 0.03, 1.0);
+    float occ = 1.0 + mat.mrno.w * (texture(tOcclusion, uv_of(3)).r - 1.0);
+    vec3 emissive = mat.emissive.rgb * texture(tEmissive, uv_of(4)).rgb;
+
+    vec3 N = normalize(vNormal);
+    if (!gl_FrontFacing) N = -N;   // 양면 재질 (차 메시는 컬링 없이 그린다)
+    vec3 V = normalize(pc.campos.xyz - vWorld);
+    if (mat.alpha.w > 0.5) {
+        vec3 T, B;
+        if (abs(vTangent.w) > 0.5) {
+            T = normalize(vTangent.xyz - N * dot(N, vTangent.xyz));
+            B = cross(N, T) * vTangent.w;
+        } else {  // 탄젠트가 없으면 화면 미분으로 (cotangent frame)
+            vec3 dp1 = dFdx(vWorld), dp2 = dFdy(vWorld);
+            vec2 uv = uv_of(2);
+            vec2 du1 = dFdx(uv), du2 = dFdy(uv);
+            vec3 dp2perp = cross(dp2, N), dp1perp = cross(N, dp1);
+            T = dp2perp * du1.x + dp1perp * du2.x;
+            B = dp2perp * du1.y + dp1perp * du2.y;
+            float inv = inversesqrt(max(dot(T, T), dot(B, B)) + 1e-12);
+            T *= inv;
+            B *= inv;
+        }
+        vec3 nt = texture(tNormal, uv_of(2)).xyz * 2.0 - 1.0;
+        nt.xy *= mat.mrno.z;
+        N = normalize(mat3(T, B, N) * nt);
+    }
+
+    float NdotV = max(dot(N, V), 1e-4);
+    vec3 R = reflect(-V, N);
+    vec3 F0 = mix(vec3(0.04), base.rgb, metallic);
+    vec3 spec = ibl_specular(R, rough, F0, NdotV);
+    vec3 kS = fresnel_schlick_roughness(NdotV, F0, rough);
+    vec3 kD = (1.0 - kS) * (1.0 - metallic);
+    vec3 diffuse = texture(uIrradiance, N).rgb * base.rgb;
+
+    // 투과(유리) 근사: 뒤쪽 장면 대신 환경맵을 시선 방향으로 비춘다 + 반투명 블렌딩
+    float tr = mat.alpha.z;
+    vec3 body = kD * diffuse * (1.0 - tr);
+    if (tr > 0.0) {
+        float mips = float(textureQueryLevels(uSpecular));
+        body += tr * (1.0 - kS) * textureLod(uSpecular, -V, rough * (mips - 1.0)).rgb * base.rgb;
+    }
+    vec3 lin = (body + spec) * occ + emissive;
+
+    // 클리어코트: 거칠기 낮은 유전체(F0 0.04) 층이 위에 한 겹 더 (차 도장)
+    float cc = mat.cc.x;
+    if (cc > 0.0) {
+        float ccr = clamp(mat.cc.y, 0.03, 1.0);
+        vec3 Fc = fresnel_schlick_roughness(NdotV, vec3(0.04), ccr);
+        lin = lin * (1.0 - cc * Fc) + cc * ibl_specular(reflect(-V, normalize(vNormal) * (gl_FrontFacing ? 1.0 : -1.0)),
+                                                       ccr, vec3(0.04), NdotV);
+    }
+
+    lin *= pc.campos.w;
+    vec3 c = linear_to_srgb(compress_highlights(lin));
+    float a = 1.0;
+    if (mat.alpha.y == 2.0) a = base.a;
+    if (tr > 0.0) a = mix(1.0, 0.35, tr) + 0.5 * kS.g * tr;  // 유리: 정면은 비치고 비스듬하면 반사
+    a = clamp(a, 0.0, 1.0);
+    outColor = vec4(c * a, a);   // premultiplied
+    outDepth = vec4(linear_depth(gl_FragCoord.z) * a, a, 0.0, a);
+}