用户指南

第 4 章 — 辅助窗口

除了主窗口(3D 视口加 Inspector)之外,RadianceKit 还管理着另外三个窗口,它们都可以通过帮助菜单打开。该菜单共有五个条目,从上到下依次是:User Guide (⌘?)、Keyboard Shortcuts (⌘/)、Open Training Logs… (⇧⌘L)、Open Exports Folder…、Manage Storage…。这两个「Open …」条目并不会打开 App 窗口,而是打开 Finder;因此本章不再对它们做进一步说明。

三个简单窗口(User Guide、Keyboard Shortcuts、Manage Storage)以及两个文件夹菜单项(Open Training Logs / Open Exports Folder)每个控件都配有一条简短说明。

本章末尾有一个交叉引用小节,涉及主窗口的 Inspector:在训练进行过程中,你可以从实时 Loss 图表和 Gaussian 计数显示中读出哪些有意义的信息。

用户指南 (W1–W4)

User-Guide-Fenster mit Sidebar links und gerendertem Markdown-Inhalt rechts
用户指南窗口,左侧为侧边栏,右侧为渲染后的 Markdown 内容

这是什么: 一个内置的帮助窗口,用于渲染随应用一起提供的 guide_<sprache>.md。语言来自设置(General 选项卡 → Language),若该处设置为「系统」,则从 macOS 的语言偏好中推导得出。布局采用经典方式:左侧为包含所有标题的侧边栏,右侧为正文内容。

当你需要快速回忆某个单一要点时 — 也就是作为速查笔记的替代品。详尽的参考资料是本手册;内置的帮助窗口是用于快速查阅的简明版本。它会随每次应用发布同步更新,但内容保持得较为简略。

W1NavigationSplitView(侧边栏 + 详情)

位置

Help → User Guide (⌘?)。

技术细节

双栏布局,包含一个用于内容树的窄侧边栏 (至少 180 pt 宽)和一个用于实际 Markdown 内容的可滚动详情区域。窗口的 最小尺寸为 700 × 500 pt。首次打开时,窗口会 从应用包中加载对应的 guide_<lang>.md(回退为 guide_en.md),将其解析为若干块记录(标题 H1–H4、 段落、列表、表格、分隔线),并单独提取 标题结构用于侧边栏。行内格式(粗体、 斜体、代码片段)通过内置的 Markdown 引擎渲染。 语言从应用设置中读取,特殊情况是 简体中文(zh-Hans)和巴西葡萄牙语(pt-BR),它们 会保留为完整的 Locale 标签,因为这两个变体与 zh 或 pt 有所不同。

W2List(标题侧边栏)

位置

用户指南窗口的左栏。

技术细节

列出当前 Markdown 文档的所有 H2 和 H3 标题的列表。H2 条目不带缩进,以中等字重显示; H3 条目左侧缩进 16 pt,前景样式减弱。所有其他层级 — 无论是 H1 还是 H4 及更深层级 — 都不会出现在侧边栏中,因为这样会 使其显得杂乱。锚点 ID 通过对 标题文本进行 slug 化生成(转小写 + 空格替换为连字符 + 仅保留字母/数字/连字符 — 与 GitHub 用于其 Markdown 锚点的算法相同,因此指向文档的外部 URL 也有可能落到同一个锚点上)。该列表采用 原生 macOS 风格。

W3Button(标题 → 锚点跳转)

位置

每一行侧边栏都对应一个按钮。

技术细节

每个侧边栏条目都是一个按钮,点击后会设置 当前锚点,但外观上看起来像一个普通的列表项。一个 观察变量随后会触发滚动跳转到对应的 锚点,并伴有 0.3 秒的平滑动画。跳转完成后, 锚点值会被重置,以便下一次点击同一个锚点时 能再次触发(否则观察者不会再次触发,因为 该值没有发生变化)。

W4ScrollView(详情内容)

位置

右栏。

技术细节

可滚动、垂直堆叠的内容区域, 采用惰性渲染,因为较长的指南很容易超过 200 个 Markdown 块 — 若采用非惰性方案,则会同时实例化所有内容。每个 块都有自己的 ID,要么是标题锚点(每个标题 都会获得一个锚点,与层级无关),要么是索引占位符。 最大宽度为 720 pt,内边距为水平 32 / 垂直 24, 以便长文本行保持良好的可读布局。表格 按单元格渲染,使用水平堆叠和分隔线;行内 代码则通过内置的 Markdown 引擎渲染。真正的代码块目前 会被当作普通段落处理 — 这是帮助窗口 的一个已知限制。

键盘快捷键 (W5–W6)

Keyboard Shortcuts Fenster — fünf Gruppen Navigation/Views/Capture/Editor/Training mit Hotkey-Spalte links und Beschreibung rechts
键盘快捷键窗口 — 五个分组 Navigation/Views/Capture/Editor/Training,左侧是快捷键列, 右侧是说明

分为五个部分的静态参考列表。 Navigation: 鼠标拖拽(Orbit/Fly)、 Shift+Drag/Right-Drag(Pan)、Scroll(缩放)、WASD(飞行穿越移动)、 Q/E(上/下)、F(切换 Orbit/Fly)、双击(重新居中)、 Cmd+Scroll(调整视场角)。Views: R(重置相机)、T (自动旋转)、P(相机回放)、B(背景循环)、0–9 (跳转到训练相机 1=10%/5=50%/0=最后一个)、Left/Right Arrow (上/下一个相机)。Capture: S(截图到桌面)、V (转台视频)、C(复制相机信息)。Editor: Tab (编辑模式)、点击/拖拽(画笔选择)、Option+Click(取消选择)、 X / Delete(删除选区)、Cmd-Z(撤销上次删除)、 [ / ](画笔缩小/放大)、Esc(取消选区)。 Training: Option+Space(暂停/继续训练)、Cmd+E (导出场景)。这里没有更多内容 — 开始、取消以及 延长训练要通过训练菜单进行(第 1 章)。

这是什么: 一份简单的静态总览,列出所有快捷键 — Navigation、Views、Capture、Editor、Training。内容是固定内建的, 不会从文件中动态加载。

当你想找到在 Viewport 中做某事最快的方法时。 WASD 飞行穿越、R 重置相机、B 背景循环 — 都列在这里。

W5ScrollView(内容区域)

位置

Help → Keyboard Shortcuts (⌘/)。

技术细节

一个简单的滚动区域,里面是一个 纵向列表。四周留白 20 pt,没有 侧边栏导航树(列表足够短)。内容分为 五个部分(Navigation、Views、Capture、Editor、Training)。 每个快捷键组合占一行,两列都是可翻译文本。 左侧列(按键代码)固定宽度为 180 pt,使 右侧的说明保持纵向对齐。除了滚动之外没有其他交互 — 点击某一行不会触发任何操作,快捷键 是菜单和 Viewport 上真实的键盘修饰键。

W6VStack(快捷键分组)

位置

位于 ScrollView 内部。

技术细节

左对齐堆叠的各分组,间距 16 pt。 在这五个分组内部,各自是标题 + 一系列行。 标题使用次级 Subheadline 样式 — 有意不使用 Title 格式,因为这些分组不需要可导航。内容 有意保持扁平(没有 Disclosure、没有 Search、没有 Filter), 以便该组件在每个 macOS 版本上都能保持不变运行, 且文件本身保持可读。

管理存储空间(W7–W12)

Manage Storage 窗口 — 标题栏显示「1,356 items · 55.1 GB total」,表格中列出按日期排序的导出 PLY 文件,每项包含图标 + 文件名 + 大小 + 日期
Manage Storage 窗口 — 标题栏显示「1,356 items · 55.1 GB total」,表格中列出按日期排序的导出 PLY 文件,每项包含 图标 + 文件名 + 大小 + 日期

这是 RadianceKit 管理的所有文件的表格视图。标题栏显示共 1,356 项,总大小 55.1 GB。上方工具栏: 「Show in Finder」+「Refresh」。每一行包含:导出图标、文件名(例如 training_20260718T194416Z.ply)、导出日期、大小(此处从 7.8 MB 到 2.24 GB 不等)、 放大镜图标(Reveal)和垃圾桶图标(Move to Trash)。排序首先按类别分组, 类别内部再按日期排序,最新的在最上面。这张截图中以 PLY 导出文件为主, 因为这个存储位置主要保存的是训练结果。

这是什么: 一个磁盘占用总览,涵盖 RadianceKit 存放在 ~/Documents/RadianceKit/ 下的所有内容 — 日志、导出文件、场景、 (来自 iOS 伴侣应用的)采集包、导入(输入图片的暂存副本)。每一项都显示 以字节为单位的大小,以及两个按钮:「在 Finder 中显示」和 「移到废纸篓」。这功能不是自动清理 — 应用本身不会删除任何东西; 你需要逐项自行决定。这个窗口已本地化:中文界面中标题为「管理存储空间」, 标题栏的两个按钮名为「在 Finder 中显示」和「刷新」,行内按钮名为 「在 Finder 中显示」和「移到废纸篓」。下方各条目中出现的英文名称 是英文版界面中的对应名称。

当磁盘空间快用完的时候。首先会堆积起来的通常是日志 (每次训练尝试对应一个 JSONL 文件,外加 _qualityMetrics.json); 导出文件当然也会累积(PLY 是 100% 原始数据,每次导出一个文件)。 在崩溃之后也很有用,此时导入暂存目录里可能还残留着输入图片的旧副本。

W7「Show in Finder」按钮

位置

存储浏览器窗口标题栏右上角。

技术细节

在 Finder 中打开 RadianceKit 的数据文件夹 — 也就是这个窗口所列内容对应的目录。这样你可以直接看到文件夹结构 (日志、导出、场景、采集、导入),也可以直接用 Finder 移动或复制 文件。此操作会打开一个新的 Finder 窗口;窗口中的列表本身不会因此 更新 — 这就是「Refresh」(W8)存在的原因。

W8「Refresh」按钮

位置

标题栏,紧邻 Finder 按钮。

技术细节

触发一次后台扫描,运行在用户发起的异步任务上, 以确保扫描大型目录树不会阻塞界面。实际的遍历过程会依次检查所有已知的 子文件夹(日志、导出、场景、采集、导入),并为每个直接子项生成一条 存储条目。每一条都会计算递归大小 — 优先使用实际磁盘占用量 (包含 APFS 硬链接共享),若不可用则回退到逻辑文件大小。

W9List(存储条目列表)

位置

标题栏下方的主要内容区域。

技术细节

列表中每一行的布局如下:类别专属的 SF Symbol 图标 (日志对应文档图标,导出对应上传箭头,场景对应立方体,采集包对应 iPhone 图标,导入对应托盘图标)、名称 + 副标题 (种类标签 + 格式化的修改日期)、右侧的字节数(右对齐,等宽字体)、 Reveal 按钮(放大镜图标)、Trash 按钮(垃圾桶图标)。排序规则: 首先按种类排序(场景在前,其次是导出、日志、采集、导入、其他), 其次按修改日期降序排列(最新的在上面)。如果扫描仍在进行, 该区域会改为显示「Scanning…」进度提示。如果没有找到任何内容, 会显示带托盘图标的空状态提示。

W10行按钮「Reveal in Finder」

位置

每行右侧的放大镜图标。

技术细节

打开 Finder 并选中该具体项目(文件或文件夹)。 与 W7 的区别:W7 打开的是根目录;W10 精确定位到这一个条目。 实用工作流程:先找出一个占用较大的条目,点击放大镜图标,然后可以 将其复制到例如外部存储卷。

W11行按钮「Move to Trash」

位置

每行放大镜图标右侧的垃圾桶图标。

技术细节

触发确认对话框(W12)。只有确认之后才会执行 macOS 标准的「移到废纸篓」操作(因此是可撤销的,不是直接删除)。 成功移入废纸篓后,该条目会从列表中移除,总字节数计数器也会随之更新。 出现错误时会弹出模态错误对话框。

W12ConfirmationDialog(删除确认)

位置

由 W11 触发,以 macOS 表单(sheet)形式呈现。

技术细节

标准确认对话框,带有动态标题「Delete <name>?」 以及一行提示文字,明确说明该条目会被放入废纸篓,并可以从那里恢复 (直到废纸篓被清空为止)。两个按钮:「Move to Trash」作为破坏性操作 (以红色显示)和「Cancel」,并自动绑定 Esc 键。该对话框是非模态的, 意义在于它只会阻塞这一个窗口,而不是整个应用 — 这是 macOS 对 可撤销删除操作的标准做法。

主窗口:损失曲线与高斯计数(I39–I41,交叉引用)

主窗口中有三个 Inspector 显示项值得单独说明,因为它们在训练过程中会持续显示,而且关于何时曲线看起来是健康的,存在一些重要的经验法则。这些显示项位于 Inspector 的 进度 区块中,在可展开的 损失曲线 分组里(参见第 2 章——Inspector),并为判断训练进度提供补充信息。

Loss 曲线什么时候算健康? 一条健康的 Loss 曲线会呈现三个阶段:(1) 预热(Warmup)——最初的 200–500 次迭代中,Loss 会从较高值(根据场景不同,L1+SSIM 组合通常在 0.15–0.25 之间)陡降到大约一半。如果这个阶段 Loss 没有下降,通常是输入有问题(图像损坏、SfM 位姿不佳、初始高斯数量太少)。(2) 致密化(Densification)——在大约 500 次迭代到 densifyUntilIteration(经典方式通常为 15K,MCMC 则到 20K 或 25K)之间,Loss 会持续下降,常伴有小幅跳降——这是致密化操作插入新高斯、优化器随后加以利用的结果。高斯计数在此阶段会上升。(3) 精修(Refinement)——此后 Loss 会进入逐渐趋于平缓的尾段。作为参考的典型终值:一个光照良好的物体场景(例如使用 P4 Quality 预设的 Tanks-&-Temples Truck)最终 L1 ≈ 0.023,而像 Mip-NeRF 360 那样的大范围室外场景自然会更高(0.04–0.07)。

平台期意味着什么? 平台期(Loss 曲线在数千次迭代中保持水平)有两种解读:(a) 模型已经收敛,继续训练不会再有提升——这是好的情况。(b) 模型卡住了(陷入局部极小值、梯度信息不佳、达到了缓冲区上限的 Cap)——这是不好的情况。这两种情况在图表上看起来完全一样。区分方法:看高斯计数。如果它也是平的,并且接近 MCMC 的 Cap(例如在 P8 Quality (MCMC) 预设下达到 150K 中的 150K),那你已经到达上限——要么提高 Cap,要么接受这个平台期。如果高斯计数还在增长,但 Loss 不再下降,那就是卡住了。

什么时候该中止,什么时候该继续训练? 经验法则:如果 10K 次迭代内最小 Loss 没有任何改善 → 中止,继续训练是在浪费时间。在此之前:可以通过训练菜单 → Continue Training → “+5,000 iterations” 追加一段训练,如果你看到的是边际性的改善(这个操作没有对应的快捷键)。注意:在 MCMC 模式下,这种平台期往往是真实的——Cap 就是自然的边界。

高斯计数达到平台期 不是 “完成”的信号。 它只说明 MCMC 已经达到 Cap,或者经典致密化(Classic Densification)已经用尽了潜力。 真正回答“是否完成”这个问题的,是在独立测试集上的 PSNR/SSIM/LPIPS。 独立测试集还会显示你的相机集合是否能够合理地划分为训练视角和测试视角。

PSNR/Holdout 才是真相,Loss 只是代理指标。 Loss 是一个相对指标:随着模型逐渐拟合训练视角,它会不断下降。但低 Loss 并不自动意味着模型好——如果模型把训练图像“背了下来”(过拟合),Loss 会很小,但在未见过的视角(Holdout)上的 PSNR 会很差。因此:进行最终质量评估时,务必参考 Holdout 指标,而不要只看最终 Loss。

经验法则框

  • User Guide 和 Keyboard Shortcuts 是静态帮助 — 关键词式问题查得快,深入内容请使用本手册。
  • 一旦磁盘剩余空间低于 10%,就打开 Manage Storage。日志和导入暂存区通常是罪魁祸首。
  • Loss 平台期和 Gaussian 数量平台期需要分开解读。Cap 上限并不是“完成”信号。真正的质量只能通过 Holdout-PSNR 衡量。
  • 若 10K 次迭代内 Min-Loss 都没有改善 → 应停止训练。