第10章 — 新手模式

位置

位于窗口顶部的工具栏中，模式切换按钮的左侧。仅在 入门模式下可见。

技术细节

以一串相连的按钮显示流水线的六个阶段，每个按钮 带有图标和名称，之间用箭头符号分隔：导入 → 帧质量 → 相机 → 训练 → 预览 → 导出。当前阶段以完全的颜色显示，已经历过的 阶段呈半透明状态，尚未到达的阶段为灰色。已完成的阶段可以 点击并跳回；当前阶段以及所有尚未到达的阶段均处于禁用状态， 在处理进行期间，整条链也会被禁用。已经不再有贯穿整条流水线 的百分比进度条了——正在进行的阶段的进度显示在处理界面 （C-19）上的大圆圈中。

位置

导入步骤的左侧，一个带图标的大型虚线矩形。在入门 模式下会显示标签"Drop photos or a video here"。

技术细节

一个拖放区域，当拖拽项悬停在该区域上方时，图标 会短暂弹跳，背景也会变色。支持 JPG、PNG、TIFF、HEIC、MP4、MOV、 PLY、SPZ、.splat、.radiancescene 包以及目录。按类型进行拖放 路由：图片会被收集并按顺序传递，视频会触发帧采样路径， splat 文件会直接打开预览，场景包会被读取。目录会被枚举， 其中包含的所有图片都会被导入。适用于沙盒的 security-scoped 书签会被正确获取和释放。不支持的扩展名 会以警告横幅的形式显示 5 秒钟。

位置

位于拖放区域内部，是一个醒目的按钮。

技术细节

该按钮会打开 macOS 文件对话框，支持多选， 可选文件类型为 JPG、PNG、TIFF、MP4、MOV、文件夹以及应用自身的 场景格式。得到的 URL 是 security-scoped 的，并通过与拖放相同的 导入路径转发。如果用户选择了文件夹，会对其进行递归枚举以 查找图片。

位置

位于拖放区域内部，仅当应用包内包含示例场景且 尚未导入图片/splat 时才可见。

技术细节

仅当满足以下两个条件时才会出现：(a) 应用包内 存在 sample-scene.splat、.spz 或 .ply，并且 (b) 尚未 导入图片/视频，也尚不存在点云。点击后会加载已完成的点云 （优先使用最小的格式——.splat 约 3 MB，.spz 约 1.4 MB， 回退到 .ply），并在 400 毫秒后从原始花卉场景的元数据中 设置硬编码的相机参数，以呈现一个美观合理的初始视角。

位置

位于拖放区域内部，紧挨着"Try Sample Scene"； 可见条件相同。

技术细节

从互联网下载 RadianceKit 提供的一个示例素材： 约 427 MB、960 张全分辨率帧，随后会被解压并直接导入应用。 只要有其他处理正在进行，该按钮就会被禁用，下载也不会开始。 界面上不会以百分比形式显示下载进度；下载完成后，你可以看到 右侧的图片列表被 960 帧填满，以此判断下载已完成。

位置

导入覆盖层下方悬浮的工具栏，位于启动按钮左侧。

技术细节

带有标签"Quality"的菜单选择器，将内置的预设 按类别分成四个部分："Classic"、"MCMC (fewer Gaussians, slower)"、 "Hybrid (sharp detail, compact)"以及"Capture — curated real-world (Drone / 360° / Photo)"。一旦完整版被解锁并且 用户至少保存了一个自定义预设，第五个部分"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）。分辨率来自一个元数据缓存， 该缓存会异步地从图片文件头中填充，以免阻塞界面。删除 操作通过 macOS 典型的滑动删除方式进行（在某一行上 用触控板向左滑动）；列表本身没有行选择功能，因此这里 没有键盘删除功能。 提示：带有明确减号按钮、Backspace 以及 Cmd-Z 撤销功能的高级图片删除路径 仅在 专家模式 下的 Project Navigator 中提供——在入门模式 中，仍然只能通过滑动删除。

位置

位于图片列表下方，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 次以上训练实验的经验数据。

位置

拖放文件夹时——没有可见的按钮，而是一种识别 逻辑。

技术细节

拖放一个目录时，应用会检查其中是否存在三种 标准工作区布局之一：sparse/0/cameras.bin、 sparse/cameras.bin 或直接位于根目录下的 cameras.bin。如果符合条件，标准的图片枚举会被中止， 取而代之的是一个模态提示，询问用户是使用现有的重建 结果，还是让图片重新经过 Apple Photogrammetry 处理。 同样的路径也适用于文本格式的工作区（cameras.txt） 以及 ETH3D 导出。详情见第 9 章后端 Q6。在入门模式和 专家模式下的表现是相同的。

位置

进度圆圈后方的铺满全屏的背景，在中止或出错时会隐藏。

技术细节

装饰性动画，根据流水线进度（0…1）渲染数量逐渐增加的小型动画 Splat 粒子。数据源是一个计算出的进度值，将 SfM 阶段映射到 0–0.2，将训练阶段映射到 0.2–1.0（帧质量检测映射到 0–0.05）。 这样一来，Splat 会在训练进行时可见地「构建」出来。 纯粹是装饰性的 — 该显示不展示当前训练的真实中间结果（那属于 Expert 模式下的实时预览）。取消或失败时它会被隐藏，只留下状态圆圈可见。

位置

处理界面中央，尺寸为 220 × 220 像素。

技术细节

两个叠加渲染的圆环：外层是柔和的轨道环，内层是填充的进度环， 带有强调色或红色描边（出错时为红色）。该环直接跟随当前阶段的真实进度 （通过短暂的柔和淡入/淡出动画），以便与 Expert 模式的进度行保持一致。 圆圈内部有一个阶段图标（训练用大脑图标，SfM 用相机图标，视频帧提取用胶片图标， 帧质量检测用闪光图标，360° 素材展开用地球图标）、阶段标题和进度数字。 这个数字在训练期间是迭代计数器（「12 500/20 000」），在其他所有阶段是 百分比数字。只要处理仍在进行，图标就会轻柔地脉动。出错时，标题会切换为 失败的阶段（「Structure from Motion Failed」、「Training Failed」）， 圆环和数字变为红色。中止后，圆圈会显示一个橙色的叉号，上面写着「Cancelled!」。

位置

处理界面左上角，尺寸为 32 × 32 像素。

技术细节

带有材质背景的简洁按钮。用于开关信息面板。图标在信息圆圈轮廓 和实心信息圆圈之间切换，激活时为实心。有柔和的淡入动画。工具提示为 「Show detailed processing metrics」。

位置

处理界面左下角，只有在处理详情被展开时才可见。

技术细节

双栏面板，采用超薄材质背景。左栏：阶段专属的信息行 — 对于 SfM 显示状态文本和百分比；对于训练显示迭代数、综合 Loss、L1-Loss、 D-SSIM-Loss、Gaussian 数量（以橙色显示）、速度（it/s）、已用时间、计算出的 剩余时间、SH-Degree 和学习率。右栏：状态文本、时间信息字符串、内嵌 Loss 图表（见 C-28）以及一个可发现性提示（见 C-32）。所有数值均来自训练状态， 在每次训练更新周期都会刷新。

位置

底部导航栏，仅在训练阶段（不包括 SfM 阶段）且处理正在进行时可见。

技术细节

带边框的按钮。根据当前状态调用暂停或继续。标签在「Pause」 （带暂停图标）和「Resume」（播放图标）之间切换。在 SfM 步骤期间不显示 此按钮，因为 Apple Photogrammetry 不支持暂停语义。暂停状态会完整保留 迭代数、Gaussian 状态和优化器动量 — 继续时会从之前中断的地方接着进行。

位置

底部导航栏，在处理（SfM 或训练）进行时可见。

技术细节

红色带边框按钮。会打开一个确认对话框，标题为「Stop and discard progress?」，按钮为「Discard Progress」（破坏性操作）和 「Keep Running」（取消）。确认后会设置取消标志，结束训练任务， 在需要时终止 SfM 子进程，并向 JSONL 日志写入带有中止状态的摘要行。 与暂停不同，训练缓冲区和状态会被丢弃。

位置

底部导航栏，当流水线失败时可见（SfM 状态以「SfM failed」 开头，或训练处于错误状态）。

技术细节

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

位置

信息面板右栏，仅在训练期间且历史记录非空时可见。

技术细节

紧凑的绘图区域（高 40 像素），以强调色绘制的 1 像素线条呈现 Loss 历史记录。数据会被过滤为有限值（对不稳定训练的 NaN 保护）。最小值/最大值基于整个历史记录计算 — 因此图表会 自动缩放到该数值范围。最新的 Loss 值显示在图表右上方。历史记录本身 在应用状态中随每次训练更新周期构建（通常每 100 次迭代一次）。

位置

信息面板右栏下方，仅在训练期间且处于新手模式时可见。

技术细节

带有眼睛图标和说明文字「Switch to Expert Mode (⌘2) for live splat preview」的小行，采用低调的色调和 10 号字体。不是 交互元素，仅作提示。点击不会有反应 — 用户必须实际按下 Cmd+2 或点击菜单 Mode → Expert Mode。

位置

预览步骤的全屏背景。

技术细节

基于Metal的3D视口，渲染最终的点云。渲染器是RadianceKit自己的 ForwardPass光栅化器 — 与训练期间渲染Splat所用的完全相同 — 因此实现真正的所见即所得 （训练的内容与显示、导出的内容完全一致）。基于Tile的渲染管线，支持顺序无关的透明度处理。 如果渲染器无法初始化（例如系统不支持Metal），会显示黑色背景并带有 "Metal not available"文字提示。该视图忽略安全区域，使模型延伸至窗口边缘。

位置

悬浮于视口上方：左上角两个图标按钮，其下左下角为信息面板。

技术细节

悬浮控件仅由两个按钮组成："Scene Info"可切换显示/隐藏左下角的信息面板， 第二个按钮可在"Orbit"（围绕目标点环绕）与"Fly-Through"（自由飞行）之间切换相机模式。 信息面板显示帧率、Gaussian数量、相机模式、视角、渲染分辨率和采样情况； 在训练进行中会额外显示训练状态行，训练结束后显示完成提示行。场景加载失败或 正在加载会作为独立状态行显示，与信息开关无关。自动旋转、重置相机、 背景颜色和截图并非悬浮按钮，而是"Viewport"菜单中的条目。

位置

Z3下方的导航栏。

技术细节

带有"Export"标签和分享图标的强调色按钮。点击后触发跳转至Z4。 在此之前，上级视图会检查完整版是否已解锁 — 若未解锁，则不显示导出界面， 而是显示锁定视图（参见U-06）。

位置

导出步骤的左侧主区域。

技术细节

两列弹性布局的卡片网格，间距 12 点。遍历新手模式中 提供的格式 — 这是完整格式列表中经过筛选的子集，只包含 6 种 最重要的格式：PLY、SPZ、glTF、.splat、环绕视频、Web 查看器。 其余格式仅在专家模式中提供。

位置

网格中的每张卡片。

技术细节

简洁的卡片式布局按钮：上方是图标（例如 PLY 用文档压缩图标， SPZ 用归档盒图标，环绕视频用视频图标），格式名称作为标题， 描述性说明文字（缩略为两行），下方是预估文件大小（根据格式、 Gaussian 数量和 SH 度数实时计算并格式化为 KB/MB）。点击即选中该 格式。选中的卡片会获得强调色背景、强调色边框以及右上角的对勾图标。 提示文字是该格式的描述。

位置

格式网格下方，仅当选择了视频格式（环绕视频或社交视频） 时可见。

技术细节

滑块范围 3–30 秒，以 1 秒为步进，绑定到应用状态中的 视频长度。最大宽度 300 像素。仅在选中视频格式时才会显示。 对于非视频格式，滑块会从视图中完全移除 — 不留空白。

位置

格式网格下方（若选择了视频，则在时长滑块下方）。

技术细节

大号强调色按钮。标签：「Export {格式名称}」， 附带分享图标。点击后会弹出 macOS 保存对话框，并带有与格式匹配的 文件扩展名。建议的文件名来自当前场景的名称；如果尚未设置名称 （例如场景从未被保存过），则默认为「scene」。确认后，导出内容 将写入所选位置。如果没有训练结果，或已有导出正在进行中， 按钮将被禁用。按钮下方显示结果的关键指标 （「2,991 Gaussians • SH degree 3」）。

位置

导出按钮下方，仅在导出进行中时可见。

技术细节

进度指示器，最大宽度 300 像素，下方带有说明文字 「Exporting… N %」。数值从 0 到 1 变化，并在写入过程中持续更新 — PLY 按每 10,000 个 Gaussians 分块更新，SPZ 在量化后一次性更新， 环绕视频按帧间隔更新。

位置

进度条下方，仅当上一次导出出错时可见。

技术细节

红色行，带警告三角形图标和文字「Export failed: …」以及错误描述。红色背景，8% 不透明度，圆角。最大宽度 400 像素。常见错误原因：磁盘空间不足导致写入失败； 保存目标超出允许范围导致沙盒错误。

位置

导出步骤的右侧。

技术细节

导出历史列表（永久保存在应用设置中，每次成功导出后 更新）。每一行显示格式徽章（小型，强调色）、时间戳（HH:mm）、 文件名（缩略为一行）以及格式化的文件大小。点击某一行会在 Finder 中打开并选中该文件。空状态提示：「No exports yet」。

位置

在历史记录的某一行上点击右键。

技术细节

每个列表项都有一个包含两个操作的右键菜单： 「Reveal in Finder」（在 Finder 中打开并选中文件，与单击效果相同） 以及「Copy Path」（将完整文件路径以文本形式复制到剪贴板）。 后者适用于拖放到其他应用中，或传递给命令行使用。