제 10 장 — 초보자 모드

위치

워크플로 위, 항상 표시.

기술적 설명

Stage Allocation이 있는 전체 파이프라인 (Frame-Quality → SfM → Training) 에 걸친 수평 진행률 표시줄을 표시합니다: Frame-Quality는 0–5% (Phase 3.11, 매우 짧음) 를 차지하고, SfM은 표시줄의 0–30%, Training은 30–100%. 그 옆에 상태 텍스트와 단계 이름 백분율 표시 ("SfM 41%", "Training 12 500/20 000") 가 있어 사용자가 "41% SfM → 25% Training" 의 명백한 후퇴를 오류로 읽지 않도록 합니다 — 표시줄은 전체 파이프라인 진행을 보여 주며 하위 단계가 아닙니다. ETA 계산은 충분한 학습 속도가 측정된 즉시 시작됩니다 (일반적으로 처음 100 반복 후). 같은 표시는 Expert 모드의 인스펙터 위에서도 사용됩니다.

위치

Import 단계의 왼쪽, 기호가 있는 큰 점선 직사각형. 초보자 모드에서는 레이블 "Drop photos or a video here"와 함께 표시됩니다.

기술적 설명

드래그 항목이 필드 위에 떠 있는 즉시 기호를 잠시 뛰게 하고 배경을 채색하는 드롭 영역. JPG, PNG, TIFF, HEIC, MP4, MOV, PLY, SPZ, .splat, .radiancescene 번들과 디렉터리를 받아들입니다. 유형별 드롭 라우팅: 이미지는 수집되고 정렬되어 전달되며, 비디오는 프레임 샘플링 경로를 트리거하고, Splat 파일은 미리보기를 직접 열고, Scene 번들은 읽힙니다. 디렉터리는 열거되고 포함된 모든 이미지가 가져옵니다. Sandbox 호환 액세스를 위한 Security Scoped Bookmark가 올바르게 가져와지고 해제됩니다. 지원되지 않는 확장자는 5초 동안 경고 배너로 표시됩니다.

위치

드롭 영역 내, 두드러진 버튼.

기술적 설명

JPG, PNG, TIFF, MP4, MOV, 폴더, 앱 자체 Scene 형식의 파일 유형과 다중 선택으로 macOS 파일 대화창을 여는 버튼. 결과 URL은 Security Scoped이며 드래그 앤 드롭과 같은 가져오기 경로를 통해 전달됩니다. 사용자가 폴더를 선택하면 이미지에 대해 재귀적으로 열거됩니다.

위치

드롭 영역 내, 앱 번들이 Sample 장면을 포함하고 아직 이미지/Splat이 가져오지 않은 경우에만 표시됩니다.

기술적 설명

(a) 앱 번들에 sample-scene.splat, .spz 또는 .ply가 있고 그리고 (b) 아직 이미지/비디오가 가져오지 않았고 점 구름이 없는 경우에만 나타납니다. 클릭 시 완성된 점 구름 (가장 작은 형식 선호 — .splat ~3 MB, .spz ~1.4 MB, 폴백 .ply) 을 로드하고 400 ms 후 미적으로 의미 있는 입력 시점을 위해 꽃 장면의 원본 메타데이터에서 하드코딩된 카메라 값을 설정합니다.

위치

드롭 영역 내, "Try Sample Scene" 옆; 동일한 가시성 조건.

기술적 설명

Repo github.com/bkindler/radiancekit-sample-photos에서 다운로드를 트리거하여 약 427 MB의 960개 전체 해상도 프레임을 로드하고 앱에 공급합니다. 다운로드 중에는 버튼이 비활성화됩니다. 진행은 상단 진행 표시줄에 "Downloading X %"로 자체 단계로 표시됩니다. 이 단계는 자체 0–100% 스케일을 유지하고 이후 SfM 단계와 겹치지 않습니다.

위치

Import Overlay의 떠 있는 하단 도구 모음, Start 버튼 왼쪽.

기술적 설명

레이블 "Quality"가 있는 조작 요소는 사용 가능한 프리셋을 카테고리별로 (Classic / MCMC / Custom) 그룹화합니다. 내장 프리셋은 카테고리별로 그룹화됩니다. 섹션 헤더는 하드코딩되어 있습니다. Custom 프리셋은 존재하는 경우에만 표시됩니다. Locked 상태: Free 목록 (Quick + Preview) 에 없는 프리셋은 사용자가 구매하지 않은 경우 이름에 "🔒" 접미사를 받습니다. 선택 시 선택기가 Preview로 되돌아가고 자동으로 Purchase Sheet를 엽니다. 선택 시 프리셋이 적용되어 전체 학습 구성이 대체됩니다.

위치

Import Overlay의 떠 있는 하단 도구 모음, Preset 선택기 오른쪽.

기술적 설명

이미지나 비디오가 가져오지 않은 동안 회색으로 유지되는 버튼. 클릭 시 파이프라인이 시작되고 단계 머신이 Frame-Quality → SfM → Training 순서로 전환됩니다. 버튼 자체에는 추가 상태가 없습니다. 실행 중인 처리는 대신 별도의 처리 화면으로 나타납니다.

위치

오른쪽 이미지 목록, 비디오 (이미지 대신) 가 가져왔을 때만 표시.

기술적 설명

0.5 fps에서 30 fps의 슬라이더, 0.5 단계. 변경 시 프레임 밀도가 업데이트되고 추가로 대상 프레임 수 (최소 10) 가 밀도와 비디오 길이에서 계산됩니다. 슬라이더는 이미지 목록 밖에 있습니다. 목록 요소가 슬라이더의 마우스 이벤트를 차단하기 때문입니다. 슬라이더 아래에는 계산된 대상 프레임 ("247 frames") 과 비디오 길이 ("1m23s video") 가 있습니다. 도구 설명은 다음과 같이 경고합니다: "Doubling the density doubles the number of frames and increases SfM time by ~100%."

위치

오른쪽 이미지 목록, 오른쪽 아래; 이미지가 가져왔을 때만 표시.

기술적 설명

빨간색 버튼. 클릭은 "Clear all imported files?" 제목과 "N images will be removed." 메시지가 있는 확인 대화 상자를 엽니다. 확인은 모든 가져온 이미지/비디오, 스테이징 디렉터리, 점 구름, 학습 상태, SfM 결과, 모든 캐시를 비웁니다. 단계가 Import로 돌아갑니다. Cancel에서는 모든 것이 유지됩니다. 대화 상자는 파괴 없는 기본 경로 (파괴 버튼이 빨간색으로 표시) 로 구성됩니다.

위치

오른쪽 이미지 목록, 각 항목.

기술적 설명

Swipe to Delete가 있는 가져온 이미지 목록. 이미지당 아이콘, 파일 이름, 해상도 ("1920 × 1080"), 파일 크기 (KB/MB로 형식화) 가 있는 한 줄. 해상도는 인터페이스를 차단하지 않도록 이미지 헤더에서 비동기적으로 채워지는 메타데이터 캐시에서 옵니다. 삭제 동작은 macOS 스타일 Swipe Delete (줄에서 트랙패드 스와이프 왼쪽) 와 선택된 줄에서 키보드 Delete를 제공합니다. 참고: 명시적 마이너스 버튼, Backspace, Cmd-Z로 되돌리기가 있는 확장된 이미지 삭제 경로는 Expert 모드만 의 Project Navigator에 추가되었습니다 — 초보자 모드에서는 Swipe Delete로 남아 있습니다.

위치

이미지 목록 아래, Clear All 버튼 위.

기술적 설명

가져온 이미지 수 (이미지가 있고 비디오가 없을 때만 활성) 를 기반으로 한 세 가지 연속 임곗값: - < 3 이미지: 빨간색 배너 (red octagon), 텍스트 "At least 3 images are required. Camera alignment cannot be computed from fewer images." - 3–9 이미지: 빨간색 배너, 텍스트 "With fewer than 10 images, SfM often fails and the trained scene tends to overfit […]. 15–20 images minimum recommended; 30+ for object captures." - 10–19 이미지: 주황색 배너 (warning triangle), 텍스트 "Workable, but quality usually improves with 20+ images and good coverage around the scene."

20개 이미지부터 배너가 사라집니다. 임곗값은 하드코딩되어 있고 경험적 560+ 학습 실험을 기반으로 합니다.

위치

폴더 드롭 시 — 보이는 버튼이 아니라 감지 로직.

기술적 설명

디렉터리 드롭 시 세 표준 Workspace 레이아웃 중 하나가 포함되어 있는지 확인됩니다: sparse/0/cameras.bin, sparse/cameras.bin 또는 루트에 직접 cameras.bin. 해당되면 표준 이미지 열거가 중단되고 대신 사용자에게 기존 재구성을 사용할지 또는 이미지를 Apple Photogrammetry를 통해 다시 보낼지 묻는 모달 경고가 열립니다. Text Format Workspace (cameras.txt) 와 ETH3D 내보내기에도 같은 경로. 자세한 내용은 제 9 장 Backend Q6 참고. Expert 모드와 마찬가지로 초보자 모드에서도 작동합니다.

위치

진행 원 뒤의 전체 화면 배경, 중단이나 오류 시 숨겨짐.

기술적 설명

파이프라인 진행 (0…1) 에 따라 점점 더 많은 작은 애니메이션 Splat 입자를 렌더링하는 장식 애니메이션. 소스는 SfM 단계를 0–0.2에, 학습을 0.2–1.0에 (Frame-Quality를 0–0.05에) 매핑하는 계산된 진행 값입니다. 따라서 학습이 실행되는 동안 Splat이 가시적으로 "구축"됩니다. 순수 장식 — 표시는 현재 학습의 실제 중간 결과를 보여 주지 않습니다 (그것은 Expert 모드의 Live Preview). Cancel이나 Failure 시 숨겨지고 상태 원만 보이게 됩니다.

위치

처리 화면 중앙, 220 × 220 픽셀.

기술적 설명

두 개의 겹친 링: 외부에 절제된 트랙 링, 내부에 강조 또는 빨강 스트로크가 있는 채워진 진행 링 (오류 시 빨강). 원 안에 단계 아이콘 (학습용 뇌, SfM용 카메라, 비디오 프레임 추출용 필름, Frame-Quality용 Sparkles), 단계 제목, 32 포인트 Rounded 폰트의 실시간 애니메이션 백분율 숫자. 처리가 활성인 동안 아이콘이 부드럽게 펄스합니다. 표시는 30 Hz 타이머에서 실제 현재 진행 방향으로 부드럽게 보간합니다 — Constant Creep (프레임당 0.0003) 과 Proportional 부분 (Gap의 4%), 다음 예상 마일스톤의 80%에 설정하는 Soft Ceiling (SfM의 경우 하드코딩된 마일스톤 테이블에서). 따라서 실제 SfM 업데이트가 몇 초마다만 도착해도 진행이 유연하게 보입니다.

위치

처리 화면 왼쪽 위, 32 × 32 픽셀.

기술적 설명

Material Background가 있는 단순한 버튼. 정보 패널을 켜고 끕니다. 활성일 때 아이콘이 Info Circle Outline과 Info Circle Filled 사이에서 변경됩니다. 부드러운 페이드 인 애니메이션. 도구 설명 "Show detailed processing metrics".

위치

처리 화면 왼쪽 아래, showProcessingInfo == true 일 때만 표시.

기술적 설명

Ultra Thin Material Background가 있는 2열 패널. 왼쪽 열: 단계별 정보 줄 — SfM의 경우 상태 텍스트와 백분율. 학습의 경우 Iteration, 결합된 Loss, L1 Loss, D-SSIM Loss, Gaussian Count (주황색으로 표시), Speed (it/s), Elapsed Time, 계산된 ETA, SH Degree, Learning Rate. 오른쪽 열: 상태 텍스트, Time Info String, 인라인 Loss 차트 (C-28 참고), Discoverability Nudge (C-32 참고). 모든 값은 각 학습 틱에서 업데이트되는 학습 상태에서 읽힙니다.

위치

하단 내비게이션 표시줄, 학습 단계 동안만 (SfM 동안 아님) 처리가 실행되는 동안에만 표시.

기술적 설명

Bordered 버튼. 상태에 따라 Pause 또는 Resume를 호출합니다. 레이블은 "Pause" (Pause 아이콘과 함께) 와 "Resume" (Play 아이콘) 사이에서 변경됩니다. SfM 단계 동안에는 버튼이 표시되지 않습니다. Apple Photogrammetry가 Pause 의미론을 알지 못하기 때문에. Pause 상태는 Iteration, Gaussian 상태, Optimizer Momentum을 완전히 유지합니다 — Resume은 이전에 중지된 곳에서 계속합니다.

위치

하단 내비게이션 표시줄, 처리 (SfM 또는 학습) 가 실행되는 동안 표시.

기술적 설명

빨간색 Bordered 버튼. "Stop and discard progress?" 제목과 "Discard Progress" (파괴) 및 "Keep Running" (Cancel) 버튼이 있는 확인 대화 상자를 엽니다. 확인 시 Cancel 플래그가 설정되고 학습 작업이 종료되며 필요한 경우 SfM 서브 프로세스가 종료되고 중단 상태가 있는 요약 줄이 JSONL 로그에 기록됩니다. Pause와 달리 학습 버퍼와 상태가 폐기됩니다.

위치

하단 내비게이션 표시줄, 파이프라인이 실패한 경우 표시 (SfM 상태가 "SfM failed"로 시작하거나 학습이 오류 상태).

기술적 설명

강조 버튼. 전체 파이프라인을 새로 시작합니다. 시작 전에 가져온 이미지/비디오가 아직 있는지 확인됩니다. 이전 오류 로그는 JSONL 디렉터리에 유지됩니다. 새 실행은 현재 타임스탬프가 있는 새 로그 파일을 작성합니다.

위치

Info Panel, 오른쪽 열, 비어 있지 않은 진행 기록이 있는 학습 동안에만 표시.

기술적 설명

콤팩트한 드로잉 영역 (40 픽셀 높이), Loss History를 강조 색상의 1픽셀 선으로 그립니다. 데이터는 유한 값에 대해 필터링됩니다 (불안정한 학습의 NaN 보호). Min/Max는 전체 History에 대해 계산됩니다 — 따라서 차트는 값 범위에 자동 줌됩니다. 마지막 Loss 값은 차트 위 오른쪽 위에 있습니다. History 자체는 각 학습 틱에서 앱 상태에서 구축됩니다 (일반적으로 100 반복마다).

위치

Info Panel, 오른쪽 열 아래, 학습 중이고 초보자 모드일 때만 표시.

기술적 설명

눈 아이콘과 Caption 텍스트 "Switch to Expert Mode (⌘2) for live splat preview"가 있는 작은 줄, 절제된 톤과 10 포인트 글꼴. 상호작용 요소 없음, 힌트만. 클릭에 반응하지 않음 — 사용자가 실제로 Cmd+2를 누르거나 Mode → Expert Mode 메뉴를 클릭해야 합니다.

위치

Preview 단계의 전체 화면 배경.

기술적 설명

완성된 점 구름을 렌더링하는 Metal 기반 3D 뷰포트. 렌더러는 Popping/Flickering을 위한 RadianceKit 수정이 있는 벤더링된 MetalSplatter 포크입니다. Order Independent Transparency를 사용하는 타일 기반 렌더링 파이프라인. 렌더러를 초기화할 수 없는 경우 (예: 시스템에서 Metal을 사용할 수 없음) 대신 "Metal not available" 텍스트가 있는 검은색 배경이 나타납니다. 뷰는 Safe Area를 무시하므로 모델이 창 가장자리까지 도달합니다.

위치

뷰포트 위, 떠 있음.

기술적 설명

Auto-Rotation (Turntable), Reset-Camera, 배경 선택 (Gray/Black/White), Save-Screenshot, Toggle-Info-Panel 버튼이 있는 콤팩트한 UI 오버레이. 카메라 매개변수 (거리, 방위각, Elevation, Target, FOV) 에 바인딩하고 자동 Turntable을 제어합니다. 학습 중 (사용자가 Expert 모드에서 뷰포트가 실행되는 것을 보고 싶을 때) 오버레이는 추가로 콤팩트한 학습 상태 줄을 표시합니다.

위치

Z3의 하단 내비게이션 표시줄.

기술적 설명

레이블 "Export"와 Share 아이콘이 있는 강조 버튼. 클릭은 Z4로의 전환을 트리거합니다. 그 전에 상위 보기는 정식 버전이 잠금 해제되었는지 확인합니다 — 그렇지 않으면 Export 단계 대신 잠금 보기가 표시됩니다 (U-06 참고).

위치

Export 단계의 왼쪽 메인 페이지.

기술적 설명

두 개의 유연한 열과 12 포인트 간격이 있는 카드 그리드. 초보자 모드에서 제공되는 형식 위에서 반복합니다 — 가장 중요한 6개 형식만 포함하는 전체 형식 목록의 필터링된 하위 집합: PLY, SPZ, glTF, .splat, Orbit Video, Web Viewer. Compressed PLY와 SOG는 Expert 모드에서만 제공됩니다.

위치

그리드의 각 카드.

기술적 설명

카드 레이아웃이 있는 단순한 버튼: 위에 아이콘 (예: PLY용 Document Zipper, SPZ용 Archive Box, Orbit Video용 Video Icon), Format Name을 Headline으로, 설명 캡션 (2줄로 단축), 그 아래에 추정 파일 크기 (형식, Gaussian Count, SH Degree에서 실시간으로 계산되고 KB/MB로 형식화). 클릭 시 형식이 선택됩니다. 선택된 카드는 강조 배경, 강조 테두리, 오른쪽 위의 체크 마크 아이콘을 받습니다. 도구 설명은 형식 설명입니다.

위치

Format Grid 아래, 비디오 형식 (Orbit Video 또는 Social Video) 이 선택된 경우에만 표시.

기술적 설명

3–30초 슬라이더, 1초 단계, 앱 상태의 Video Length에 바인딩. 최대 폭 300 픽셀. 비디오 형식이 선택된 경우에만 표시됩니다. 비디오가 아닌 형식에서는 슬라이더가 보기에서 완전히 제거됩니다 — 죽은 공간 없음.

위치

Format Grid 아래 (그리고 비디오가 선택된 경우 Duration Slider 아래).

기술적 설명

큰 강조 버튼. 레이블: "Export {Format Name}", Share Icon. 클릭 시 형식에 맞는 확장자와 기본 파일 이름 "scene.{ext}" 가 있는 macOS 저장 대화 상자가 열립니다. 확인 시 내보내기가 선택된 URL에 작성됩니다. 학습 결과가 없거나 내보내기가 이미 실행 중인 경우 비활성화됩니다.

위치

Export 버튼 아래, 내보내기가 실행되는 동안에만 표시.

기술적 설명

최대 폭 300 픽셀의 진행 표시, 그 아래에 캡션 "Exporting… N %". 값은 0에서 1로 실행되며 쓰기 중에 업데이트됩니다 — PLY의 경우 10 000 Gaussian의 청크로, SPZ의 경우 양자화 후 한 번, Orbit Video의 경우 프레임 간격으로.

위치

Progress Bar 아래, 마지막 내보내기에서 오류가 발생한 경우에만 표시.

기술적 설명

Warning Icon과 오류 텍스트가 있는 빨간색 줄. 빨간색 8% 배경 Opacity, 둥근 모서리. 최대 폭 400 픽셀. 일반적인 오류 원인: SOG는 시스템 PATH에 cwebp를 기대 (App Store 호환 아님). 가득 찬 디스크 공간에서의 쓰기 오류. 허용된 영역 외부의 저장 대상에서의 Sandbox 오류.

위치

Export 단계의 오른쪽.

기술적 설명

내보내기 기록 (UserDefaults에 JSON으로 영구적으로 저장되고 각 성공적인 내보내기 후 유지) 에 대한 목록. 각 줄은 형식 배지 (작음, 강조 색상), 타임스탬프 (HH:mm), 파일 이름 (1줄로 단축), 형식화된 파일 크기를 표시합니다. 줄 클릭은 Finder를 선택된 파일과 함께 엽니다. 빈 상태: "No exports yet".

위치

History 줄 마우스 오른쪽 클릭.

기술적 설명

두 동작이 있는 각 목록 항목의 컨텍스트 메뉴: "Reveal in Finder" (Finder를 선택된 파일과 함께 엽니다. 단순 클릭과 같음) 및 "Copy Path" (전체 파일 경로를 텍스트로 클립보드에 둠). 후자는 다른 앱으로의 드래그 앤 드롭 또는 명령줄에의 전달에 유용합니다.