제 3 장 — 설정

위치

Settings → General → Interface → Default Mode 선택기. 연결: AppState.defaultMode. 기본값: .simple.

기술적 설명

다음 시작 후 앱이 두 UI 모드 중 어느 것으로 열릴지를 제어합니다. "Simple Mode"는 4단계 가이드형 마법사 워크플로 (가져오기 → 처리 → 미리보기 → 내보내기, 제 10 장 Z1–Z4에 문서화) 이고, "Expert Mode"는 제 2 장의 Navigator, 3D 뷰포트, Expert 인스펙터가 있는 고전적인 3 패널 레이아웃입니다. 값은 재시작 간에 기억됩니다. 메뉴 Mode → Simple Mode (⌘1) / Mode → Expert Mode (⌘2) 와 효과가 동일하지만, 메뉴는 실행 중인 세션을 전환하는 반면 이 선택기는 향후 세션의 기본값을 설정합니다. 두 모드 모두 동일한 프로젝트 상태에 접근합니다 — 모드 전환 시 프로젝트, 카메라, 학습 구성은 유지됩니다. 모드별 툴바 버튼은 즉시 다시 렌더링됩니다.

위치

Settings → General → Interface → Language 선택기. 연결: AppState.language. 기본값: .system (macOS 언어를 따름).

기술적 설명

macOS 시스템 언어와 독립적으로 전체 앱 UI의 표시 언어를 선택합니다. RadianceKit은 17개 언어 (de, en, pl, en-AU, ar-SA와 추가 12개) 로 현지화되어 있습니다. "System"의 경우 앱은 macOS 언어를 따릅니다. 명시적 선택의 경우 언어 설정은 재시작 간에 기억됩니다. 완전한 적용은 보통 앱 재시작이 필요합니다. 현지화 번들은 시작 시에만 로드되기 때문입니다. 프로젝트에 문서화된 298개의 현지화 키는 모두 고려됩니다. 모든 하위 보기와 도움말 도구 설명의 텍스트가 포함됩니다.

위치

Settings → General → Viewport → Background 선택기. 연결: AppState.viewportBackground. 기본값: .darkGray (RGB 0.1, 0.1, 0.1).

기술적 설명

3D 뷰포트의 기본 배경색을 설정합니다. 세 가지 옵션: "Dark Gray" (RGB 0.1, 0.1, 0.1 — 기본값), "Black" (0, 0, 0), "White" (1, 1, 1). 설정은 재시작 간에 새 프로젝트와 세션의 기본값을 영구화하면서 실행 중인 Metal 렌더러도 즉시 업데이트합니다. 동일한 옵션이 메뉴 Viewport → Background (M21, M22, M23) 에 있지만, Settings 선택기는 기본값을 설정하는 반면 메뉴는 실행 중인 표시를 전환합니다. 스크린샷과 데모 비디오에 중요: 흰색 배경은 녹색/파란색 플로터를 더 강하게 강조하고, 어두운 배경은 깨끗한 렌더 촬영에 더 좋습니다.

위치

Settings → General → Viewport → "Auto-Rotate After Training" 토글. 연결: AppState.autoRotateAfterTraining. 기본값: false.

기술적 설명

학습 종료 직후 장면 무게 중심을 중심으로 뷰포트 카메라의 연속 턴테이블 회전 (표준 회전율 ~0.3 rad/s) 을 시작합니다. 데모 세션, A/B 비교, 그리고 360° 시점에서 장면 가장자리에 "플로터"가 생성되었는지 직접 평가하는 데 유용합니다. 효과는 메뉴 Viewport → Toggle Auto-Rotation (M16, ⌘⌥T) 과 시각적으로 동일하지만, 여기 토글은 수동 대신 학습 종료 후 자동으로 동작을 트리거합니다. 나중에 언제든지 메뉴를 통해 또는 뷰포트 클릭 (회전 일시 정지) 으로 중단할 수 있습니다. 학습 성능에 영향을 주지 않습니다 — 회전은 학습이 완료된 후에만 실행됩니다.

위치

Settings → General → Training → Live Preview 선택기. 연결: AppState.trainingConfig.livePreviewInterval. 기본값: 0 (Off).

기술적 설명

실행 중인 학습 스냅샷이 3D 뷰포트에 렌더링되는 반복 간격을 결정합니다. 네 가지 이산 값: 0 ("Off"), 50, 250, 1000 반복. Live Preview 활성 시 트레이너는 Gaussian 버퍼를 GPU에서 별도의 렌더 버퍼로 복사하고 뷰포트 재그리기를 트리거합니다. "Off"의 경우 뷰포트는 학습 완료 후에만 업데이트됩니다. 성능 비용: M3 Ultra에서 50회 반복마다 ~5–10% 느려짐, 250회 반복마다 ~1–2% 느려짐, 1000회 반복마다 측정 불가. 스냅샷 버퍼의 메모리 오버헤드는 간격과 관계없이 일정 ~2 GB. 값은 새 학습의 기본값으로 사용됩니다. 학습 시작 후에는 Training 인스펙터가 이 학습의 실제 실시간 값을 표시합니다. 간격 50에서 시각적 인상은 점 구름의 매끄러운 "성장"이고, 1000에서는 끊기게 느껴집니다.

위치

Settings → General → Training → Throttle 선택기. 연결: AppState.trainingConfig.throttleDelayMs. 기본값: 0 (Off).

기술적 설명

학습 반복 사이에 인위적인 지연을 밀리초 단위로 삽입합니다. 네 가지 이산 값: 0 ("Off"), 2 ("Light"), 5 ("Moderate"), 10 ("Eco"). 의의: 더 긴 학습 (몇 시간) 의 경우 GPU가 그렇지 않으면 100% 사용됩니다. 이는 눈에 띄게 느린 시스템 UI를 야기합니다 (마우스 포인터가 끊김, 다른 앱이 느려짐). Throttle 지연은 다른 작업이 실행될 수 있는 GPU 휴식을 제공합니다. 성능 비용은 상당합니다. 5 ms Throttle에서 일반적인 40K 학습은 Throttle 없을 때보다 약 50–80% 더 오래 걸립니다. 성능 모드 "Eco" (10 ms) 에서는 반복당 지연이 반복 자체보다 더 깁니다 — 2–3배 느림. Throttle 활성 시 선택기 아래에 "Throttle is on. Training will be slower than usual."이라는 힌트가 나타납니다. 앱 자체는 눈에 띄게 더 잘 반응하지 않습니다 — 다른 앱만 혜택을 봅니다.

위치

Settings → General → Experimental — Outdoor Floater Reduction → "Sky Masking" 토글. 연결: AppState.trainingConfig.skyMaskingEnabled. 기본값: false.

기술적 설명

학습 전 Apple Vision 기반 하늘 픽셀 세분화를 활성화합니다. 학습 시작 전 각 입력 카메라의 하늘 영역이 Apple Vision Foreground Mask (Sky = Background) 를 통해 추출되어 해당 카메라의 픽셀별 마스크로 할당됩니다. 학습 중 픽셀당 Loss 기여는 하늘 마스크의 보수와 곱해집니다 — 하늘 픽셀은 그래디언트에 0으로 기여하므로 하늘로 투영되는 Gaussian은 최적화 신호를 받지 않고 따라서 "더 밀도가 높아지거나" "더 밝아지지" 않습니다. 야외/드론 장면의 플로터 (하늘의 어두운 덩어리) 를 상당히 줄입니다. 고전적 40K 학습에서 ~3% L1 회귀 비용이 발생합니다 (memory/dev_outdoor-floater-reduction.md 참고). 명확하게 인식 가능한 하늘이 있는 야외 장면에서만 의미가 있습니다. 실내 장면 또는 흰색 배경에서는 하늘 세분화가 잘못된 영역을 식별하고 유효한 Loss 신호를 차단합니다. 다른 실험적 토글과 달리 값은 앱 재시작 간에 기억되지 않습니다 — 다음 앱 시작 시 다시 꺼져 있습니다.

위치

Settings → General → Experimental — Outdoor Floater Reduction → "Mid-Training Floater Cleanup" 토글. 연결: AppState.midTrainingCleanup. 기본값: false.

기술적 설명

Classic 40K 학습 (프리셋 "P4 Quality") 에서 두 가지 추가 Density Control 패스를 켭니다: 반복 20 000과 30 000. 두 패스는 세 가지 기준으로 모든 Gaussian을 검색합니다: (a) 매우 낮은 Opacity (표준 0.005), (b) 작은 Screen Space 크기, (c) 지난 1000회 반복 동안 Loss 기여 없음. 세 조건을 모두 충족하는 Gaussian은 정리됩니다. 효과: 학습 종료 시 ~5–15% 적은 Gaussian, 드론/야외 장면의 하늘에서 어두운 덩어리가 눈에 띄게 적음. 클로즈업 실내 장면에서 ~1–3% L1 회귀 비용이 발생하므로 기본값으로 활성화되지 않습니다. 값은 재시작 간에 기억됩니다 (S7과 달리). 두 정리 반복 (20K, 30K) 은 단단히 정의되어 있으며 현재 UI를 통해 변경할 수 없습니다. 더 짧은 학습 (예: P2 Preview 5K) 에서는 토글이 반복 표시에 도달하지 않으므로 효과가 없습니다. 자세한 내용: memory/dev_outdoor-floater-reduction.md.

위치

Settings → General → Experimental — Outdoor Floater Reduction → "Reduce Elongated Gaussians" 토글. 연결: AppState.scaleRegularization. 기본값: false.

기술적 설명

Loss 항에 추가 비등방성 정규화를 활성화합니다. 최적화 중에 각 Gaussian에 대해 가장 큰 스케일 축과 가장 작은 스케일 축의 비율로 비등방성이 계산됩니다. 비율이 임곗값 (AppState.anisotropyThreshold, 표준 10.0) 을 초과하면 초과량에 비례하여 확장되는 페널티 항이 Loss에 추가됩니다. 효과: 잔디와 짙은 잎의 교차 해치 및 줄무늬 아티팩트에 일반적인 바늘 모양 Gaussian은 학습 중에 더 둥근 모양으로 강제되거나 정리됩니다. 대가로 표준 실내 장면에서 ~6% L1 회귀, 엄격한 객체 캡처에서는 효과 없음. 스위트 스폿은 식물 위 드론 비행 촬영입니다. AppState에 작성되며 UserDefaults를 통해 영구화됩니다. optimizer.metal에 그래디언트 계산의 추가 페널티로 구현됩니다. 프로젝트 메모리의 참고 사항 확인: V549d가 출시 버전이었고, 더 공격적인 Scale-Reg가 있는 이후 V549f는 catastrophic regression 때문에 다시 revert되었습니다. 자세한 내용: memory/dev_outdoor-floater-reduction.md 와 memory/dev_v549f-needle-reduction.md.

위치

Settings → General → Experimental — Outdoor Floater Reduction → "Reconstruct Sky Dome" 토글. 연결: AppState.skyDomeEnabled. 기본값: false.

기술적 설명

학습 전 하늘 돔 투영 (V549e MVP) 을 활성화합니다. SfM 후, 학습 시작 전에 각 입력 카메라에 대해 S7과 공유된 Apple Vision 하늘 마스크가 이미지에서 추출되고, 하늘 픽셀은 카메라 인트린식과 함께 가상 구체 표면 (표준 반경 8× 장면 반경) 으로 역투영됩니다. 이 구체에서 ~5000개의 새 Gaussian이 투영된 하늘 픽셀의 평균 색상값, 매우 큰 스케일 (장면 단위 1.0), 초기 Opacity 0.95로 초기화됩니다. 이 5000개의 Gaussian은 고전적 의미의 Sky Mask가 아닙니다 — 다른 것들과 마찬가지로 학습되지만 높은 초기 Opacity를 통해 얇은 껍질로 남습니다. 결과: 야외/드론 장면의 360° 새 시점에서 어두운 컨페티 덩어리 대신 실제 하늘 색상과 구름 구조가 나타납니다. 값은 재시작 간에 기억됩니다. 최소 360° 카메라 커버리지가 있는 야외 장면에서만 의미가 있습니다. 하늘 뷰가 없는 순수 객체 캡처에서는 효과가 없습니다. 상태: 실험적, 추가 야외 세트에 대한 더 폭넓은 A/B 검증이 아직 남아 있습니다.

위치

Settings → AI Helpers → 첫 번째 섹션 → "AI Helpers enabled" 토글. 연결: AppState.aiHelpersEnabled. 기본값: true.

기술적 설명

파이프라인의 모든 AI Helpers 기능에 대한 마스터 스위치. 꺼져 있으면 가져오기 및 SfM 파이프라인이 모든 ML 기반 전처리 단계를 완전히 건너뜁니다 — Apple Vision 호출 없음, CoreML 모델 로드 없음, NPU 깨우기 없음. 켜져 있으면 개별 하위 토글 (S12–S14) 이 참조됩니다. 값은 재시작 간에 기억됩니다. 다음 단계에 영향을 줍니다: (a) SfM 전 프레임 품질 사전 점검 (S12), (b) 루프 폐쇄 감지 (S13), (c) 새 학습의 기본값으로의 자동 하늘 마스킹 (S14). 중요: 꺼져 있으면 세 하위 토글이 비활성화되고 시각적으로 회색이 됩니다. 푸터 힌트는 모든 AI Helpers가 엄격하게 온디바이스에서 실행됨을 강조합니다 — 이미지 업로드 없음, 클라우드 처리 없음. 개인 정보 보호 보장은 Apple Vision 프레임워크 (Neural Engine의 로컬) 와 앱 번들에 직접 위치한 CoreML 모델을 독점적으로 사용함으로써 달성됩니다.

위치

Settings → AI Helpers → Available 섹션 → "Frame quality check" 토글. 연결: AppState.aiHelpersFrameQualityCheck. 기본값: true.

기술적 설명

SfM 호출 전 각 가져온 프레임을 분석하는 Frame Quality Screener (Phase 3.11) 를 활성화합니다. 프레임당 파이프라인 단계: (a) Apple Vision의 Laplacian Variance 필터 (블러 감지 — 임곗값 ~150), (b) 히스토그램 기반 과/저노출 점검 (임곗값: 픽셀의 >5%가 0 또는 255), (c) 빈 프레임 감지 (모든 픽셀에 대한 표준 편차 < 5). 세 점검을 모두 통과한 프레임은 곧바로 통과합니다. 적어도 하나의 점검을 실패한 프레임은 문제가 있는 각 프레임을 썸네일과 이유와 함께 나열하고 제거할지 묻는 모달 확인 대화창을 트리거합니다. 중요: 자동 삭제 없음 — 대화창이 항상 필요하며, 사용자가 최종 결정을 유지합니다. 성능: M3 Ultra에서 프레임당 ~50 ms, 병렬 실행. 꺼져 있으면 모든 프레임이 점검 없이 SfM에 전달됩니다. 마스터 (S11) 가 비활성화되면 이 토글은 시각적으로 회색이고 효과가 없습니다. 메모리에 따른 출시 상태: SHIPPED 2026-05-23.

위치

Settings → AI Helpers → Available 섹션 → "Loop closure detection" 토글. 연결: AppState.aiHelpersLoopClosure. 기본값: true.

기술적 설명

Apple Vision Feature Print 기반 루프 폐쇄 감지를 활성화합니다. 각 가져온 프레임에 대해 이미지 콘텐츠의 신경 임베딩을 나타내는 ~768차원 특징 벡터가 계산됩니다. 그 후 모든 Feature Print는 Cosine Similarity로 쌍별 비교됩니다. Similarity > 0.85이고 프레임 인덱스 거리 > 50 인 쌍 (즉 비인접 프레임) 은 "루프 폐쇄 후보"로 식별되어 프로젝트 폴더의 사이드카 JSONL 파일에 기록됩니다. 정보용만 — 가져온 이미지 시퀀스는 수정되지 않습니다. 의의: SfM 솔버 (특히 COLMAP) 에 이 프레임들이 3D 공간에서 함께 클러스터에 속한다는 힌트를 제공합니다. Native SfM의 경우 사이드카 정보는 현재 문서용일 뿐입니다. COLMAP은 커스텀 matches 파일을 통해 내부적으로 힌트를 사용합니다 (수동 통합 가능, 자동으로 연결되지 않음). 성능: M3 Ultra에서 프레임당 ~200 ms, 병렬 실행. 꺼져 있으면 Feature Print가 생성되지 않습니다. 마스터 (S11) 가 비활성화되면 시각적으로 회색입니다.

위치

Settings → AI Helpers → Available 섹션 → "Auto sky masking" 토글. 연결: UserDefaults.standard.bool(forKey: "aiHelpersSkyMaskingDefault") (커스텀 바인딩을 통해). 기본값: false.

기술적 설명

새 학습 구성에서 S7의 하늘 마스킹 설정의 기본값을 설정합니다. S11–S13과 달리 실제 하늘 마스킹 설정은 학습 세션별로 살아 있고 앱 재시작 간에 기억되지 않습니다 (S7 참고). AI Helpers UI가 그럼에도 "새 학습"의 영구 기본값을 제공할 수 있도록 이 그림자 값이 있습니다. 재시작 간에 기억되고 새 학습 설정 시 (예: 새 프로젝트 가져오기) 하늘 마스킹의 초기 기본값으로 적용됩니다. 마스터 (S11) 가 비활성화되면 시각적으로 회색입니다.