第 10 章 — 新手模式

位置

工作流上方,始终可见。

技术细节

在整个流水线 (图像质量 → SfM → 训练) 上方显示 一条水平进度条,各阶段所占比例为: 图像质量占 0–5 % (阶段 3.11,非常短) 、SfM 占 0–30 %、训练占 30–100 %。 旁边显示状态文本和按阶段命名的百分比 ("SfM 41 %"、 "Training 12 500/20 000"),这样用户不会把表面上的回退 "SfM 41 % → Training 25 %" 误读为错误 — 进度条显示的是整个 流水线的进度,而不是子阶段。ETA 只有在测得足够的训练速度后 才会开始计算 (通常在前 100 次迭代之后)。专家模式中的同一进度条 也用于检查器上方。

位置

导入步骤的左侧,大的虚线矩形带符号。在新手模式 中显示标签 "Drop photos or a video here"。

技术细节

拖放区域,当拖拽项悬停在上方时,符号会短暂跳动 并改变背景色。接受 JPG、PNG、TIFF、HEIC、MP4、MOV、PLY、SPZ、 .splat、.radiancescene 包以及目录。按类型路由: 图像被收集并按 顺序传入,视频触发帧采样路径,Splat 文件直接打开预览,Scene 包 被读入。目录被枚举,所有包含的图像都会被导入。安全范围书签 (Security-scoped Bookmarks) 在沙盒环境下被正确获取与释放。 不支持的扩展名会以警告横幅显示 5 秒。

位置

拖放区域内,显著按钮。

技术细节

打开 macOS 文件对话框的按钮,支持多选,文件类型 为 JPG、PNG、TIFF、MP4、MOV、文件夹以及软件自有的 Scene 格式。 结果 URL 受安全范围保护,并通过与拖放相同的导入路径转发。如果用户 选择了文件夹,会递归枚举其中的图像。

位置

拖放区域内,仅在软件包内包含示例场景且尚未导入 图像/Splat 时显示。

技术细节

仅在以下条件同时满足时出现: (a) 软件包中存在 sample-scene.splat、.spz 或 .ply ; 并且 (b) 还未导入任何 图像/视频且没有点云。点击后会加载现成的点云 (优先最小格式 — .splat ~3 MB、.spz ~1.4 MB、回退到 .ply ),并在 400 ms 后 将相机硬编码到示例场景原始元数据的位姿,以提供有美感的入场视角。

位置

拖放区域内,紧挨 "Try Sample Scene";相同的 可见条件。

技术细节

触发下载 (来自仓库 github.com/bkindler/radiancekit-sample-photos),约 427 MB, 包含 960 张全分辨率帧,并导入软件。下载期间按钮被禁用。进度显示 在顶部进度条上,作为独立阶段标记 "Downloading X %" — 因为这个阶段保留自己的 0–100 % 刻度,不会与后续的 SfM 阶段重叠。

位置

导入覆盖层的悬浮底部工具栏,在开始按钮左侧。

技术细节

标签为 "Quality" 的控件,按类别 (Classic / MCMC / Custom) 分组可用预设。内置预设按类别分组;分段标题硬编码。 自定义预设仅在存在时可见。锁定状态: 不在免费列表 (Quick + Preview) 中的预设,若用户未购买,名称后会带 "🔒" 后缀; 选中后选择器会跳回 Preview 并自动打开购买窗口。选中时应用 预设,这会替换整个训练配置。

位置

导入覆盖层的悬浮底部工具栏,在预设选择器右侧。

技术细节

按钮在既无图像也无视频导入时保持灰色。点击后启动 流水线,并将阶段状态机切换为 图像质量 → SfM → 训练 顺序。按钮本身 没有进一步状态;正在运行的处理流程会以独立的处理画面呈现。

位置

右侧图像列表,仅在导入了视频 (而非图像) 时可见。

技术细节

滑块范围 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 结果 及所有缓存;阶段回到导入。点 Cancel 则全部保留。对话框默认指向 非破坏性路径 (破坏性按钮标为红色)。

位置

右侧图像列表,每个条目。

技术细节

带左滑删除的导入图像列表。每张图像一行,显示 图标、文件名、分辨率 ("1920 × 1080") 与文件大小 (格式化为 KB/MB)。分辨率来自元数据缓存,从图像头异步填充,以避免阻塞 UI。 删除操作支持典型的 macOS 左滑删除 (在某一行上用触控板向左滑动) 以及在选中行时按 Delete 键。提示: 带显式减号按钮、Backspace 与 ⌘Z 撤销的扩展图像删除路径仅在专家模式的项目导航器中提供 — 新手模式里依然只是左滑删除。

位置

图像列表下方,Clear All 按钮上方。

技术细节

基于已导入图像数量的三级连续阈值 (仅在有图像 且无视频时激活): - < 3 张图像: 红色横幅 (红色八角形),文本 "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 张图像: 橙色横幅 (警告三角形), 文本 "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 重新 处理图像。文本格式 workspace (cameras.txt) 与 ETH3D 导出走相同 路径。详见第 9 章后端 Q6。新手模式与专家模式效果相同。

位置

进度环背后的全屏背景,中止或出错时隐藏。

技术细节

装饰性动画,根据流水线进度 (0…1) 渲染逐渐增多 的小型动画 Splat 粒子。数据源是一个计算得到的进度值,SfM 阶段 映射到 0–0.2,训练映射到 0.2–1.0 (图像质量映射到 0–0.05)。 这样训练运行时 Splat 视觉上 "构建" 起来。纯装饰性 — 显示并不 反映当前训练的真实中间结果 (那是专家模式中的实时预览)。出现 Cancel 或失败时隐藏,只保留状态环。

位置

处理画面中央,220 × 220 像素。

技术细节

两个重叠环: 外圈是淡化的轨道环,内圈是填充的 进度环,描边为强调色或红色 (出错时红色)。环内有阶段图标 (训练 为大脑、SfM 为相机、视频抽帧为胶片、图像质量为闪光) 、阶段 标题以及实时动画的百分比,使用 32 点圆角字体。处理运行时图标 会轻柔脉动。显示以 30 Hz 定时器平滑插值至当前真实进度 — 采用恒定爬升 (0.0003/帧) 加比例分量 (差值的 4 %) 以及软上限 (设定为下一个预期里程碑的 80 %, SfM 来自硬编码的里程碑表)。 这样即便真实 SfM 更新每隔数秒才发生一次,进度看起来也是流畅的。

位置

处理画面左上角,32 × 32 像素。

技术细节

带材质背景的简单按钮。切换信息面板的显隐。 图标在 Info 圆形描边与填充之间切换 (激活时为填充)。柔和的淡入 动画。工具提示为 "Show detailed processing metrics"。

位置

处理画面左下,仅当 showProcessingInfo == true 时可见。

技术细节

带超薄材质背景的两列面板。左列: 阶段特定的信息行 — SfM 显示状态文本与百分比;训练显示迭代次数、合并 Loss、L1 Loss、D-SSIM Loss、Gaussian 计数 (橙色)、速度 (it/s) 、已用时间、 计算的 ETA、SH 度数与学习率。右列: 状态文本、时间信息字符串、 内联 Loss 图表 (见 C-28) 与可发现性提示 (见 C-32)。所有值都从 训练状态中读取,每一次训练 tick 都会更新。

位置

底部导航栏,仅在训练阶段 (不在 SfM) 且处理进行中时显示。

技术细节

带边框按钮。按状态调用 Pause 或 Resume。 标签在 "Pause" (带暂停图标) 与 "Resume" (播放图标) 之间切换。 SfM 阶段不显示该按钮,因为 Apple Photogrammetry 不具有暂停语义。 暂停状态完整保留迭代、Gaussian 状态与优化器动量 — Resume 从 之前停下的地方继续。

位置

底部导航栏,在处理 (SfM 或训练) 运行期间可见。

技术细节

红色带边框按钮。打开标题为 "Stop and discard progress?" 的确认对话框,按钮 "Discard Progress" (破坏性) 与 "Keep Running" (取消)。确认后会设置 cancel 标志、结束训练任务、 必要时结束 SfM 子进程,并在 JSONL 日志中写入带 cancel 状态的 summary 行。与 Pause 不同,训练缓冲与状态会被丢弃。

位置

底部导航栏,在流水线失败时可见 (SfM 状态以 "SfM failed" 开头,或训练处于错误状态)。

技术细节

强调色按钮。重新启动整个流水线。启动前会检查 是否仍有已导入的图像/视频。之前的错误日志保留在 JSONL 目录中; 新的运行会以当前时间戳写入新的日志文件。

位置

信息面板右列,仅在训练且历史非空时可见。

技术细节

紧凑绘图区域 (高 40 像素),将 Loss 历史作为 1 像素宽的线条以强调色绘制。数据按有限值过滤 (NaN 保护, 针对不稳定训练)。最小/最大值在整个历史上计算 — 因此图表会 自动缩放到值域。最新 Loss 值显示在图表右上方。历史本身在每次 训练 tick 时由软件状态积累 (通常每 100 次迭代)。

位置

信息面板右列底部,仅在训练且新手模式下 可见。

技术细节

带眼睛图标的小一行,文本 "Switch to Expert Mode (⌘2) for live splat preview",采用柔和色调与 10 点字体。 非交互元素,仅作提示。点击无反应 — 用户必须实际按 ⌘2 或点击 菜单 Mode → Expert Mode。

位置

预览步骤的全屏背景。

技术细节

基于 Metal 的 3D 视口,渲染完成的点云。 渲染器为带 RadianceKit 补丁 (用于消除 popping/flickering) 的 本地 vendored MetalSplatter fork。基于 tile 的渲染管线, 具有顺序无关透明度。如果渲染器无法初始化 (例如系统不支持 Metal) ,会改为显示带 "Metal not available" 文本的黑色背景。 视图忽略安全区,因此模型可延伸到窗口边缘。

位置

视口上方,悬浮。

技术细节

紧凑的 UI 覆盖层,包含自动旋转 (Turntable)、 Reset 相机、背景选择 (Gray/Black/White)、Save Screenshot、 切换 Info Panel 的按钮。绑定到相机参数 (距离、方位角、俯仰、 目标、FOV) 并控制自动转盘。训练运行时 (用户在专家模式下想看 视口同步) ,覆盖层会额外显示一行紧凑的训练状态。

位置

Z3 中的底部导航栏。

技术细节

带标签 "Export" 和分享图标的强调色按钮。点击 触发切换到 Z4。在此之前,父视图会检查是否解锁了完整版 — 如未解锁,会显示锁定视图而非导出阶段 (见 U-06)。

位置

导出步骤的左侧主区。

技术细节

两个弹性列、12 点间距的卡片网格。遍历新手模式 所提供的格式 — 是完整格式列表的过滤子集,只包含 6 个最重要的 格式: PLY、SPZ、glTF、.splat、Orbit Video、Web Viewer。 Compressed-PLY 与 SOG 仅在专家模式中提供。

位置

网格中的每张卡片。

技术细节

带卡片布局的简单按钮: 顶部图标 (例如 PLY 为文档压缩、SPZ 为档案盒、Orbit Video 为视频图标)、格式名作 标题、描述文字 (截至 2 行) ,下方为估计文件大小 (由格式、Gaussian 数与 SH 度数实时计算,并格式化为 KB/MB)。点击时选中该格式。 选中的卡片会获得强调色背景、强调色边框,右上角带勾。工具提示 为格式描述。

位置

格式网格下方,仅当选择了视频格式 (Orbit Video 或 Social Video) 时显示。

技术细节

滑块范围 3–30 秒,步长 1 秒,绑定到软件状态中的 视频长度。最大宽度 300 像素。仅当选中视频格式时显示。在非视频 格式时滑块完全从视图中移除 — 没有死空间。

位置

格式网格下方 (若选择视频则在 Duration 滑块下方)。

技术细节

大的强调色按钮。标签: "Export {格式名}",带分享 图标。点击时打开 macOS 保存对话框,带格式对应的扩展名与默认文件名 "scene.{ext}" ;确认后将导出写入所选 URL。在没有训练结果或已有 导出正在进行时禁用。

位置

Export 按钮下方,仅在导出运行时可见。

技术细节

进度显示,最大宽度 300 像素,下方为说明文字 "Exporting… N %"。值从 0 到 1,并在写入期间更新 — PLY 按 10 000 Gaussian 一块更新,SPZ 在量化后一次性更新,Orbit Video 按帧间隔更新。

位置

进度条下方,仅在最近一次导出出现错误时可见。

技术细节

带警告图标和错误文本的红色一行。红色 8 % 背景 透明度,圆角。最大宽度 400 像素。常见错误原因: SOG 期望系统 PATH 中有 cwebp (不符合 App Store) ;磁盘已满时的写入错误; 保存目标位于沙盒许可范围外时的沙盒错误。

位置

导出步骤的右侧。

技术细节

导出历史列表 (持久化为 UserDefaults 中的 JSON, 每次成功导出后维护)。每行显示格式徽章 (小,强调色)、时间戳 (HH:mm)、文件名 (单行截断) 与格式化的文件大小。点击某行会在 Finder 中打开并选中该文件。空状态: "No exports yet"。

位置

右键点击 History 行。

技术细节

每个列表项的上下文菜单含两个动作: "Reveal in Finder" (在 Finder 中选中该文件,与单击效果相同) 与 "Copy Path" (将完整文件路径作为文本放入剪贴板)。后者对拖入 其他软件或传递给命令行很有用。