사용자 가이드

Kapitel 4 — Aux-Fenster

메인 윈도우(3D 뷰포트와 Inspector) 외에도 RadianceKit은 세 개의 추가 윈도우를 관리하며, 이들 모두 Help 메뉴에서 열 수 있다. 이 메뉴에는 위에서 아래로 다섯 개의 항목이 있다: User Guide (⌘?), Keyboard Shortcuts (⌘/), Open Training Logs… (⇧⌘L), Open Exports Folder…, Manage Storage…. 두 개의 "Open …" 항목은 앱 윈도우가 아니라 Finder를 여는 것이므로, 여기서는 더 다루지 않는다.

세 개의 단순한 윈도우(User Guide, Keyboard Shortcuts, Manage Storage)와 두 개의 폴더 메뉴 항목(Open Training Logs / Open Exports Folder)은 각 조작 요소마다 짧은 항목으로 정리되어 있다.

이 장의 끝에는 메인 윈도우의 Inspector에 대한 상호 참조 섹션이 있다: 트레이닝이 진행되는 동안 Live Loss 차트와 Gaussian Count 표시에서 어떤 정보를 유의미하게 읽어낼 수 있는지에 대한 내용이다.

사용자 가이드 (W1–W4)

User-Guide-Fenster mit Sidebar links und gerendertem Markdown-Inhalt rechts
왼쪽에 사이드바, 오른쪽에 렌더링된 마크다운 콘텐츠가 있는 사용자 가이드 창

이것은: 앱과 함께 제공되는 guide_<sprache>.md를 렌더링하는 내장 도움말 창이다. 언어는 설정(General 탭 → Language)에서, 그리고 그곳에 "System"으로 되어 있으면 macOS 언어 설정에서 유추된다. 레이아웃은 클래식하다: 왼쪽에 모든 제목을 담은 사이드바, 오른쪽에 본문.

특정 항목에 대한 빠른 상기가 필요할 때 — 즉 키워드 대체용으로. 상세한 레퍼런스는 이 매뉴얼이며, 내장 도움말 창은 빠르게 찾아볼 수 있는 요약본이다. 앱 릴리스마다 함께 업데이트되지만 내용은 더 피상적으로 유지된다.

W1NavigationSplitView (사이드바 + 디테일)

위치

Help → User Guide (⌘?).

기술적 설명

콘텐츠 트리를 위한 좁은 사이드바(최소 180 pt 너비)와 실제 마크다운 콘텐츠를 위한 스크롤 가능한 디테일 영역으로 구성된 2단 레이아웃. 창은 최소 크기 700 × 500 pt를 가진다. 처음 열 때 창은 앱 번들에서 알맞은 guide_<lang>.md를 로드하고(폴백 guide_en.md), 이를 블록 레코드(H1–H4 제목, 단락, 목록, 표, 구분선)로 파싱하며, 사이드바를 위해 제목 구조를 별도로 추출한다. 인라인 서식(굵게, 기울임, 코드 스팬)은 내장된 마크다운 엔진을 통해 렌더링된다. 언어는 앱 설정에서 읽어오는데, 중국어(zh-Hans)와 브라질 포르투갈어 (pt-BR)의 경우 특수하게 처리되어 전체 로케일 태그로 유지된다. 이 변형들은 각각 zh, pt와 구별되기 때문이다.

W2List (제목 사이드바)

위치

사용자 가이드 창의 왼쪽 열.

기술적 설명

현재 마크다운 문서의 모든 H2, H3 제목에 대한 목록. H2 항목은 들여쓰기 없이 중간 굵기의 글꼴로 나타나며, H3 항목은 왼쪽에 16 pt 들여쓰기와 축소된 전경 스타일로 나타난다. 다른 모든 레벨 — H1은 물론 H4 이하도 — 사이드바에 나타나지 않는데, 이는 그렇지 않으면 사이드바가 복잡해지기 때문이다. 앵커 ID는 제목 텍스트에서 슬러그화를 통해 생성된다(소문자 변환 + 공백을 대시로 + 문자/숫자/대시로 필터링 — GitHub가 마크다운 앵커에 사용하는 것과 동일한 알고리즘이며, 따라서 문서에 대한 외부 URL도 잠재적으로 같은 앵커에 도달할 수 있다). 목록은 네이티브 macOS 스타일을 사용한다.

W3Button (제목 → 앵커 이동)

위치

사이드바 행마다 하나의 버튼.

기술적 설명

모든 사이드바 항목은 현재 앵커를 설정하는 버튼이지만, 시각적으로는 목록 항목처럼 보인다. 그러면 관찰자 변수가 0.3초에 걸친 부드러운 애니메이션으로 해당 앵커로의 스크롤 이동을 트리거한다. 이동 후 앵커 값은 다시 초기화되는데, 그래야 같은 앵커를 다시 클릭했을 때도 다시 발동하기 때문이다(그렇지 않으면 값이 변하지 않아서 관찰자가 다시 트리거되지 않는다).

W4ScrollView (디테일 콘텐츠)

위치

오른쪽 열.

기술적 설명

지연 렌더링을 사용하는 스크롤 가능한 수직 스택 콘텐츠 영역. 더 긴 가이드는 200개가 넘는 마크다운 블록을 가질 수 있기 때문이다 — 지연 렌더링을 사용하지 않는 방식은 모든 블록을 동시에 인스턴스화해야 할 것이다. 각 블록은 고유한 ID를 받는데, 제목 앵커(레벨과 무관하게 모든 제목이 받음) 또는 인덱스 플레이스홀더 중 하나다. 최대 너비는 720 pt, 패딩은 가로 32 / 세로 24로, 긴 줄도 읽기 좋은 레이아웃을 유지한다. 표는 셀 단위로 수평 스택과 구분선으로 렌더링되며, 인라인 코드는 내장 마크다운 엔진을 통해 렌더링된다. 실제 코드 블록은 현재 단락으로 처리된다 — 도움말 창의 알려진 제약 사항이다.

키보드 단축키 (W5–W6)

Keyboard Shortcuts 창 — Navigation/Views/Capture/Editor/Training 다섯 그룹, 왼쪽에 단축키 열, 오른쪽에 설명
Keyboard Shortcuts 창 — Navigation/Views/Capture/Editor/Training 다섯 그룹, 왼쪽에 단축키 열, 오른쪽에 설명

다섯 섹션으로 나뉜 정적인 참조 목록. Navigation: Mouse Drag (Orbit/Fly), Shift+Drag/Right-Drag (Pan), Scroll (Zoom), WASD (Fly-Through 이동), Q/E (Up/Down), F (Toggle Orbit/Fly), Double-click (Re-center), Cmd+Scroll (FoV 조정). Views: R (Reset Camera), T (Auto-Rotation), P (Camera Playback), B (Background-Cycle), 0–9 (Training-Cam으로 점프 1=10%/5=50%/0=last), Left/Right Arrow (Prev/Next Cam). Capture: S (Screenshot to Desktop), V (Turntable-Video), C (Copy Camera Info). Editor: Tab (Edit 모드), Click/Drag (Paint-Select), Option+Click (Deselect), X / Delete (선택 항목 삭제), Cmd-Z (마지막 삭제 되돌리기), [ / ] (브러시 크기 축소/확대), Esc (선택 해제). Training: Option+Space (트레이닝 일시정지/재개), Cmd+E (장면 내보내기). 여기에는 이게 전부다 — Start, Cancel과 연장 기능은 Training 메뉴에서 이용할 수 있다 (1장 참고).

무엇인지: 모든 단축키를 한눈에 보여주는 단순한 정적 개요 — Navigation, Views, Capture, Editor, Training. 내용은 코드에 고정되어 있으며 파일에서 불러오지 않는다.

뷰포트에서 뭔가를 가장 빠르게 처리할 방법을 찾을 때. WASD Fly-Through, 카메라 리셋용 R, 배경 순환용 B — 전부 여기 있다.

W5ScrollView (콘텐츠 영역)

위치

Help → Keyboard Shortcuts (⌘/).

기술적 설명

세로 목록이 담긴 단순한 스크롤 영역이다. 사방에 20 pt의 패딩이 있고, 사이드바 내비게이션 트리는 없다 (목록이 충분히 짧기 때문이다). 내용은 다섯 섹션(Navigation, Views, Capture, Editor, Training)으로 그룹화되어 있다. 단축키 조합마다 한 줄씩, 양쪽 열에 번역 가능한 텍스트가 들어간다. 왼쪽 열(키 코드)은 180 pt 너비로 고정되어 있어 오른쪽 설명이 수직으로 정렬된 상태를 유지한다. 스크롤 외에는 상호작용이 없다 — 줄을 클릭해도 아무 일도 일어나지 않으며, 실제 단축키는 메뉴와 뷰포트에서 작동하는 진짜 키보드 모디파이어다.

W6VStack (단축키 섹션)

위치

ScrollView 내부.

기술적 설명

16 pt 간격으로 왼쪽 정렬되어 쌓인 섹션들이다. 다섯 섹션 각각에 제목과 줄 시퀀스가 들어간다. 제목은 보조적인 Subheadline 스타일을 사용한다 — 섹션이 탐색 가능할 필요가 없기 때문에 의도적으로 Title 서식을 쓰지 않았다. 내용은 의도적으로 평평하게 구성되어 있다(Disclosure도, Search도, Filter도 없음). 그래야 이 컴포넌트가 어떤 macOS 버전에서도 변함없이 작동하고 파일도 가독성을 유지할 수 있다.

저장 공간 관리 (W7–W12)

Manage Storage 창 — 헤더에 „1,356 items · 55.1 GB total”가 표시되고, 날짜순으로 정렬된 Export-PLY 파일 테이블에 각각 아이콘 + 파일명 + 크기 + 날짜가 표시됨
Manage Storage 창 — 헤더에 „1,356 items · 55.1 GB total"가 표시되고, 날짜순으로 정렬된 Export-PLY 파일 테이블에 각각 아이콘 + 파일명 + 크기 + 날짜가 표시됨

RadianceKit이 관리하는 모든 파일의 테이블 뷰. 헤더에는 1,356개 항목, 총 55.1 GB가 표시됨. 상단 툴바: „Show in Finder" + „Refresh". 각 행에는 Export 아이콘, 파일명 (예: training_20260718T194416Z.ply), Export 날짜, 크기(이 예시에서는 7.8 MB부터 2.24 GB까지 다양함), 돋보기 아이콘(Reveal), 휴지통 아이콘 (Move to Trash)이 표시됨. 정렬은 먼저 카테고리별로, 카테고리 안에서는 날짜순(최신이 위)으로 이뤄짐. 이 화면에서는 PLY-Export가 대부분인데, 이 보관함에는 주로 트레이닝 결과물이 저장되었기 때문이다.

무엇인가: RadianceKit이 ~/Documents/RadianceKit/ 아래에 저장하는 모든 것 — 로그, Export, Scene, Capture-Bundle(iOS 동반 앱에서 온 것), Import(입력 이미지의 스테이징 사본) — 에 대한 디스크 사용량 개요. 각 항목에는 바이트 단위 크기와 두 개의 버튼이 있다: "Finder에서 보기"와 "휴지통으로 이동". 이것은 자동 정리 기능이 아니다 — 앱이 스스로 아무것도 삭제하지 않으며, 항목별로 직접 결정한다. 이 창은 번역되어 있다: 독일어로는 „Speicher verwalten"이라고 하며, 헤더의 두 버튼은 „Im Finder anzeigen"과 „Aktualisieren", 행의 버튼은 „Im Finder anzeigen"과 „In den Papierkorb legen"이라고 부른다. 아래 항목에 나오는 영어 이름은 영어판에서 사용하는 명칭이다.

디스크가 가득 찰 때. 특히 로그가 쌓이기 쉽다(트레이닝 시도마다 JSONL 하나, 그리고 _qualityMetrics.json); Export도 물론 마찬가지다(PLY는 원본 데이터 100%이며, Export당 하나씩 생성됨). 충돌 발생 후에도 유용한데, Import 스테이징 디렉터리에 입력 이미지의 오래된 사본이 남아 있을 수 있기 때문이다.

W7„Show in Finder" 버튼

위치

저장소 브라우저 창의 헤더 오른쪽 위.

기술적 설명

RadianceKit 데이터 폴더를 Finder에서 연다 — 바로 이 창이 나열하고 있는 내용이 담긴 디렉터리다. 이를 통해 폴더 구조(Logs, Exports, Scenes, Captures, Imports)를 직접 확인할 수 있고, 파일을 Finder에서 직접 이동하거나 복사할 수도 있다. 이 동작은 새 Finder 창을 열며, 이 창의 목록 자체는 그에 따라 갱신되지 않는다 — 그것을 위해 "Refresh"(W8)가 있다.

W8„Refresh" 버튼

위치

헤더, Finder 버튼 옆.

기술적 설명

백그라운드 스캔을 트리거하며, 사용자가 시작한 비동기 작업에서 실행되어 대형 디렉터리 트리를 스캔하더라도 UI가 멈추지 않는다. 실제 순회는 알려진 모든 하위 폴더(Logs, Exports, Scenes, Captures, Imports)를 거치며, 직접적인 자식 항목마다 저장소 항목을 하나씩 생성한다. 항목별로 재귀적 크기를 계산하는데 — 가능하면 실제 디스크 사용량(APFS 하드링크 공유를 포함)을 우선하고, 그렇지 않으면 논리적 파일 크기로 대체한다.

W9List (저장소 항목 목록)

위치

헤더 아래 메인 콘텐츠.

기술적 설명

각 행마다 다음과 같은 레이아웃을 가진 목록: 종류별 SF Symbol 아이콘(Logs는 문서, Exports는 업로드 화살표, Scenes는 큐브, Capture-Bundle은 iPhone, Imports는 트레이), 이름 + 부제목 (종류 라벨 + 형식화된 수정 날짜), 오른쪽의 바이트 카운터(오른쪽 정렬, 고정폭 글꼴), Reveal 버튼(돋보기 아이콘), Trash 버튼(휴지통). 정렬은 1차로 종류별(Scenes 먼저, 그다음 Exports, Logs, Captures, Imports, Other), 2차로 수정 날짜 내림차순(최신이 위)이다. 스캔이 아직 진행 중이면 해당 자리에 대신 "Scanning…" 진행 표시가 나타난다. 아무것도 찾지 못하면 트레이 아이콘과 함께 빈 상태 화면이 표시된다.

W10행 버튼 „Reveal in Finder"

위치

각 행, 오른쪽 돋보기 아이콘.

기술적 설명

Finder를 열고 해당 특정 항목(파일 또는 폴더)을 선택한다. W7과의 차이: W7은 루트 디렉터리를 열지만, W10은 정확히 이 하나의 항목을 선택한다. 실용적인 사용 흐름: 큰 항목을 확인하고, 돋보기를 클릭한 다음, 예를 들어 외부 볼륨으로 복사한다.

W11행 버튼 „Move to Trash"

위치

각 행, 돋보기 옆의 휴지통 아이콘.

기술적 설명

확인 대화상자(W12)를 실행시킨다. 확인 후에야 비로소 macOS의 표준 "휴지통으로 이동" 동작이 실행된다(즉 되돌릴 수 있으며, 직접 삭제되지 않는다). 휴지통 이동이 성공하면 항목이 목록에서 제거되고 전체 바이트 카운터가 갱신된다. 오류가 발생하면 모달 오류 대화상자가 표시된다.

W12ConfirmationDialog (삭제 확인)

위치

W11에 의해 실행되며, macOS Sheet 형태로 표시됨.

기술적 설명

동적 제목 „Delete <name>?"과 함께, 항목이 휴지통으로 이동하며 그곳에서(휴지통을 비우기 전까지는) 복원 가능하다는 점을 명시적으로 알려주는 메시지 줄이 있는 표준 확인 대화상자다. 버튼은 두 개: 파괴적 동작으로 표시되는(빨간색) „Move to Trash"와 자동 Esc 바인딩이 있는 „Cancel". 이 대화상자는 이 창만 차단하고 앱 전체를 차단하지는 않는다는 의미에서 비모달(non-modal)이다 — 이는 되돌릴 수 있는 삭제에 대한 macOS 표준 방식이다.

메인 윈도우: 손실 곡선과 Gaussian 개수 (I39–I41, 상호 참조)

메인 윈도우의 Inspector 표시 항목 중 세 가지는 별도의 설명이 필요하다. 학습이 진행되는 동안 계속 보이는 항목들이며, 곡선이 건강해 보이는지 판단하는 데 중요한 경험칙이 있기 때문이다. 이 표시들은 Inspector의 진행 상황 섹션, 펼쳐지는 손실 곡선 그룹 안에 있으며 (2장 — Inspector 참고), 학습 진행 상황을 해석하는 데 도움이 된다.

손실 곡선은 언제 건강한가? 건강한 손실 곡선은 세 단계를 보여준다. (1) 워밍업 — 처음 200–500회 반복 동안 손실이 높은 값(씬에 따라 L1+SSIM 결합 기준 일반적으로 0.15–0.25)에서 가파르게 떨어져 대략 절반이 된다. 이 단계에서 손실이 떨어지지 않는다면 대개 입력이 잘못된 것이다(이미지 손상, SfM 포즈 불량, 초기 Gaussian 개수가 너무 적음 등). (2) Densification — 약 500회부터 densifyUntilIteration (클래식은 15K, MCMC는 20K 또는 25K까지)까지 손실은 계속 떨어지며, Densify 연산이 새로운 Gaussian을 추가하고 옵티마이저가 이를 활용할 때 종종 작은 하락 폭이 나타난다. 이 단계에서 Gaussian 개수가 증가한다. (3) Refinement — 이후 손실은 점점 평평해지는 꼬리 구간으로 접어든다. 참고할 만한 전형적인 최종 값: 조명이 잘 갖춰진 오브젝트 씬(예: P4 Quality의 Tanks-&-Temples Truck)은 L1 ≈ 0.023에 도달하며, Mip-NeRF 360의 넓은 야외 씬은 태생적으로 그보다 높은 값(0.04–0.07)에 머문다.

플래토(Plateau)는 무엇을 의미하는가? 플래토(손실 곡선이 수천 회 반복 동안 수평으로 유지되는 상태)에는 두 가지 해석이 있다. (a) 모델이 수렴했고 더 이상 학습해도 개선이 없는 경우 — 좋은 경우다. (b) 모델이 갇혀 있는 경우(지역 최솟값, 나쁜 그래디언트 정보, 버퍼 한도에 도달)이다 — 나쁜 경우다. 두 경우는 차트상으로는 동일하게 보인다. 구분하는 방법: Gaussian 개수를 확인하라. 이것도 평평하고 MCMC Cap에 근접해 있다면(예: 프리셋 P8 Quality (MCMC)에서 150K 중 150K), 한계에 도달한 것이다 — Cap을 높이거나 플래토를 받아들여야 한다. Gaussian 개수는 계속 증가하는데 손실이 떨어지지 않는다면, 이는 갇힌 상태(stuck)다.

언제 중단하고 언제 계속 학습해야 하는가? 경험칙: 10K회 반복 동안 최소 손실이 개선되지 않으면 → 중단하라, 추가 반복은 낭비다. 그 전이라면: Training 메뉴 → Continue Training → "+5,000 iterations"를 통해 경계선상의 개선이 보일 경우 학습을 연장할 수 있다(이에 대한 단축키는 없다). 주의: MCMC의 경우 플래토가 실제로 진짜인 경우가 많다 — Cap이 자연스러운 한계이기 때문이다.

Gaussian 개수 플래토는 "완료" 신호가 아니다. 이는 단지 MCMC가 Cap에 도달했거나 Classic Densification이 한계에 다다랐음을 의미할 뿐이다. 진짜 "완료" 여부에 대한 질문에 답하는 것은 독립적인 테스트 세트에서 측정한 PSNR/SSIM/LPIPS뿐이다. 독립적인 테스트 세트는 카메라 세트가 학습용과 테스트용 시점으로 공정하게 나뉠 수 있는지도 보여준다.

PSNR/Holdout이 진실이고, 손실은 단지 대리 지표(Proxy)일 뿐이다. 손실은 상대적인 지표다. 모델이 학습용 View에 적응해 가는 동안 떨어진다. 하지만 손실이 낮다고 해서 자동으로 좋은 모델을 의미하지는 않는다 — 모델이 학습 이미지를 그대로 암기해버렸다면(Overfitting), 손실은 작겠지만 본 적 없는 View(Holdout)에 대한 PSNR은 나쁠 것이다. 따라서 최종 품질 평가에는 항상 End-Loss만이 아니라 Holdout 지표를 확인해야 한다.

요령 상자

- User Guide와 Keyboard Shortcuts는 정적인 도움말입니다 — 키워드로 빠르게 찾을 때 유용하고, 깊이 있는 내용은 이 매뉴얼을 참고하세요. - 디스크의 여유 공간이 10% 아래로 떨어지면 바로 Manage Storage를 여세요. 로그와 Imports 스테이징이 흔히 범인입니다. - Loss 정체 구간과 Gaussian 개수 정체 구간은 따로 해석해야 합니다. Cap 한계는 "완료" 신호가 아닙니다. 진짜 품질은 오직 Holdout PSNR로만 측정됩니다. - Min-Loss 개선 없이 1만 회 반복 → 트레이닝을 중단하세요.