第 4 章 — 辅助窗口

除主窗口 (3D 视口加检查器) 外,RadianceKit 还管理七个其他窗口, 全部通过 Help 菜单打开。从上到下:User Guide (⌘?)、Keyboard Shortcuts (⌘/)、Open Training Logs… (不打开应用窗口,而是 Finder; 因此此处不再赘述)、Manage Storage…、Pareto Dashboard… (⇧⌘D)、 Holdout Analysis… (⇧⌘H)、BayesOpt Console… (⇧⌘B)。其中三个 —— Dashboard、Holdout、BayesOpt —— 是独立的分析工具。它们各有 自己的 View Model 栈,在磁盘上读写 JSON 文件,并且每个都有一个 CLI 参数,可在应用启动时让该窗口立即指向特定文件 (–dashboard-dir、–holdout-file、–bayesopt-autorun)。

四个简单窗口 (User Guide、Keyboard Shortcuts、Manage Storage, 以及子菜单项 Open Training Logs / Open Exports Folder) 每个控件 得到一个简短条目。三个分析窗口记录得更详细 —— 每个都有一个 引言,解释您在窗口中看到什么、何时应打开它,以及如何解读所示 图像。

本章末尾有一个指向主窗口检查器的交叉引用部分:训练运行时您 能从实时 Loss 图和 Gaussian Count 显示中合理读到什么。

User Guide (W1–W4)

这是什么: 一个内置帮助窗口,渲染应用附带的 guide_<语言>.md。语言从设置 (General → Language) 派生, 或当选择"System"时从 macOS 语言偏好派生。布局经典:左侧 含所有标题的侧栏,右侧正文。

当您需要对某一点的快速提醒时 —— 即作为 关键词替代。详细参考是本手册;内置帮助窗口更像是命令行上的 –help。每个应用版本随之更新,但内容上保持较表层。

W1NavigationSplitView (侧栏 + 详情)

位置

Help → User Guide (⌘?)。

技术细节

两列布局,带窄侧栏 (至少 180 pt 宽) 用于内容树,以及带可滚动详情区的实际 Markdown 内容区。窗口最小尺寸 700 × 500 pt。首次打开时,窗口从应用 bundle 加载相应的 guide_<lang>.md (回退 guide_en.md), 将其解析为 Block 记录 (标题 H1–H4、段落、列表、表格、分隔线), 并单独提取标题结构用于侧栏。内联格式 (粗体、斜体、Code Span) 通过内置 Markdown 引擎渲染。语言从应用设置读取,中文 (zh-Hans) 和巴西葡萄牙语 (pt-BR) 作为特殊情况以完整 locale 标签保留, 因为这些变体与 zh 或 pt 不同。

W2List (标题侧栏)

位置

User Guide 窗口的左栏。

技术细节

当前 Markdown 文档中所有 H2 和 H3 标题的列表。H2 条目无缩进,中等字重显示;H3 条目 带 16 pt 左缩进和减弱前景样式。H4 及更深的级别被忽略, 否则深度会让侧栏失去概览。锚 ID 从标题文本通过 slug 化生成 (小写 + 空格转破折号 + 过滤为字母/数字/破折号 —— 与 GitHub 用于 Markdown 锚的算法相同,因此外部文档 URL 可能落在相同 的锚上)。列表使用原生 macOS 样式。

W3Button (标题 → 锚跳转)

位置

每个侧栏行一个按钮。

技术细节

每个侧栏条目是一个按钮, 设置当前锚,但外观上像列表条目。一个观察者变量随后触发到 相应锚的滚动跳转,带 0.3 秒的柔和动画。跳转后锚值被重置, 以便下次单击相同锚时再次触发 (否则观察者不会重新触发, 因为值未改变)。

W4ScrollView (详情内容)

位置

右栏。

技术细节

可滚动、垂直堆叠的内容 区域,带 Lazy Rendering,因为较长的 Guide 容易超过 200 个 Markdown Block —— 非 lazy 变体会同时实例化所有。每个 block 获得自己的 ID,要么是标题锚 (对可跳转的 H1–H3),要么是 索引占位符。最大宽度 720 pt,Padding 32 水平 / 24 垂直, 使长行保持良好可读布局。表格按单元格用水平堆栈和分隔线渲染; 内联代码通过内置 Markdown 引擎。真正的代码块当前作为段落 处理 —— 帮助窗口的已知限制。

Keyboard Shortcuts (W5–W6)

五个部分的静态参考列表。 Navigation: Mouse Drag (Orbit/Fly)、Shift+Drag/Right-Drag (Pan)、Scroll (Zoom)、WASD (Fly-Through 移动)、Q/E (Up/Down)、 F (Toggle Orbit/Fly)、双击 (Re-center)、Cmd+Scroll (FoV 调整)。 Views: R (重置相机)、T (自动旋转)、P (相机回放)、B (背景循环)、0–9 (跳到训练相机 1=10%/5=50%/0=最后)、左/右 箭头 (上一个/下一个相机)。Capture: S (截图到桌面)、 V (Turntable 视频)、C (复制相机信息)。Editor: Tab (编辑模式)、Click/Drag (Paint-Select)、Option+Click (取消选择)、 X / Delete (删除选择)、Cmd-Z (撤销上次删除)、[ / ] (画笔 更小/更大)、Esc (取消选择)。Training: Start、 Pause/Resume、Cancel、Continue +5K/+10K/+20K 通过 M9–M14 的菜单快捷键。

这是什么: 一个所有快捷键的简单静态概览 —— Navigation、Views、Capture、Editor、Training。内容硬编码, 无 Markdown 加载。

当您寻找在视口中做某事的最快方式时。 WASD Fly-Through、R 重置相机、B 循环背景 —— 全都在这里。

W5ScrollView (内容区)

位置

Help → Keyboard Shortcuts (⌘/)。

技术细节

一个内有垂直列表的简单 滚动区。Padding 20 周围,无侧栏导航树 (列表足够短)。内容 分为五个部分 (Navigation、Views、Capture、Editor、Training)。 每组按键一行,两列均为可翻译文本。左列 (按键代码) 固定为 180 pt 宽度,使右侧描述保持垂直对齐。除滚动外无交互 —— 单击行不触发任何操作,快捷键是菜单和视口上的真正键盘修饰。

W6VStack (快捷键部分)

位置

ScrollView 内部。

技术细节

左对齐堆叠的部分, 16 pt 间距。五个部分内分别为标题 + 行序列。标题使用次要 Subheadline 样式 —— 故意不用 Title 格式,因为部分不必可导航。 内容故意扁平 (无 Disclosure、无搜索、无过滤),使组件在每个 macOS 版本上一致工作,并保持文件可读。

Manage Storage (W7–W12)

RadianceKit 管理的 所有文件的表格视图。标题统计 693 个项目,16.74 GB 总大小。 顶部工具栏:"Show in Finder" + "Refresh"。每行:PLY 图标、 文件名 (例如 training_20260527T211321Z.ply)、导出日期、 大小 (从 7 KB 到 218 MB 不等)、放大镜图标 (Reveal) 和回收站 图标 (Move to Trash)。文件按日期排序,最新在上。在此演示 截图中,PLY 导出占主导,因为大量使用了 –benchmark。

这是什么: 对 RadianceKit 在 ~/Documents/RadianceKit/ 下存储的一切的磁盘使用概览 —— Logs、Exports、Scenes、Capture Bundles (来自 iOS 伴侣)、Imports (输入图像的暂存副本)。每个 条目一个字节大小和两个按钮:"在 Finder 中显示"和"移到 回收站"。不是自动清理 —— 应用本身什么都不删;您按条目 决定。

磁盘满时。尤其是 Logs 会积累 (每次训练尝试 一个 JSONL,加上 _qualityMetrics.json);Exports 自然也是 (PLY 100% 原始数据,每次导出一个)。崩溃后也有用,如果 Imports 暂存目录中还有输入图像的旧副本 (参见 dev_v549f-needle-reduction.md 中的"Disk-pressure incident")。

W7按钮"Show in Finder"

位置

Storage 浏览器窗口右上角的标题。

技术细节

在 Finder 中打开整个 RadianceKit 目录 (~/Documents/RadianceKit/),使您能直接 看到文件夹结构,并可用 Finder 本身操作。该操作打开一个新 Finder 窗口,不切换到应用沙盒容器 —— ~/Documents/RadianceKit/ 是应用正常可访问的 Documents 域,不是沙盒容器路径。

W8按钮"Refresh"

位置

标题,Finder 按钮旁。

技术细节

触发一个在用户启动的 异步任务上运行的后台扫描,以使大型目录树扫描不阻塞 UI。 实际遍历访问每个已知子文件夹 (Logs、Exports、Scenes、 Captures、Imports),并为每个直接子项生成一个 Storage 条目。 每个条目确定递归大小 —— 优选实际磁盘使用 (包括 APFS 硬链接共享),回退到逻辑文件大小。

W9List (Storage 条目)

位置

标题下方的主内容。

技术细节

每行此布局的列表: 类别特定的 SF Symbol 图标 (Logs 文档、Exports 上传箭头、 Scenes 立方体、Imports 托盘)、名称 + 副标题 (Kind 标签 + 格式化修改日期)、右侧字节计数器 (右对齐,monospaced)、 Reveal 按钮 (放大镜符号)、Trash 按钮 (回收站)。排序:首要 按 Kind (Scenes 首先,然后 Exports、Logs、Captures、Imports、 Other),次要按修改日期降序 (最新在上)。如果扫描仍在运行, 位置改为显示"Scanning…"进度。如果未找到内容,显示带 托盘图标的空状态显示。

W10行按钮"Reveal in Finder"

位置

每行,右侧放大镜符号。

技术细节

打开 Finder 并选中特定 项 (文件或文件夹)。与 W7 不同:W7 打开根目录;W10 精确标记 这一个条目。实际工作流:识别一个大条目,单击放大镜,然后 例如将其复制到外部卷。

W11行按钮"Move to Trash"

位置

每行,放大镜旁的回收站符号。

技术细节

触发确认对话框 (W12)。 仅在确认后,标准 macOS 操作"移到回收站"运行 (即可逆, 非直接删除)。Trash 成功后,条目从列表中移除,总字节计数 更新。出错时显示模态错误对话框。

W12ConfirmationDialog (删除确认)

位置

由 W11 触发,呈现为 macOS 表单。

技术细节

标准确认对话框,带动态 标题"Delete <name>?"和一行消息,明确指出条目落入回收站 并可从那里恢复 (直到回收站被清空)。两个按钮:"Move to Trash"作为破坏性操作 (红色显示),以及自动 Esc 绑定的 "Cancel"。该对话框在某种意义上是非模态的,仅阻塞此窗口, 不阻塞整个应用 —— 这是 macOS 对可逆删除的标准。

Pareto Dashboard (W13–W22)

空状态 (首次打开后) —— 带"Open Reports Folder…"行动召唤 的空状态。一旦加载了训练报告,数据点出现,见下张截图。

标题工具栏显示"129 reports of 129" (选定文件夹中所有报告成功解析 —— 21 个额外文件因较旧 格式无法解析,见右侧提示列表)。坐标轴:X 轴选择器为 Gaussians,Y 轴选择器为 PSNR (dB)。散点图:绿色点 = Classic 策略,蓝色点 = MCMC。虚线 Pareto Front 沿最佳达到 的 PSNR 值延伸,从约 500K Gaussians 起在 PSNR≈30 dB 形成 平台。右侧过滤芯片:7 个场景 (bicycle、bonsai、family、 flowers、kitchen、stump、truck),2 种策略 (classic、mcmc), 3 个 Mip Splatting 选项 (All、On、Off)。当前所有过滤器 都打开,因此点的密集集群。

这是什么: 一个多运行比较工具。您过去训练了多个 场景或同一场景使用不同预设 —— 每次训练运行 (如果您带了 –benchmark 或通过 Benchmark 功能调用) 都产生一个 JSON 报告文件,其中包含最终 PSNR、SSIM、LPIPS、Gaussian Count 和挂钟时间等。该 Dashboard 一次读取这样一个整个文件夹, 并将它们作为 2D 散点图绘制,坐标轴可选。此外,Pareto Front (非支配点的集合) 以虚线绘制。

在您创建了至少三或四个训练报告之后。 点更少时,前沿线无意义。典型用例:您试图重建一个户外场景, 依次跑了 P3 Balanced (Classic)、P4 Quality (Classic)、P7 MCMC Quality 和 P9 Outdoor (tuned) —— 现在您要知道哪种配置在 每秒训练时间内提供最佳 PSNR,或哪个需要最少 Gaussians 达到 给定 PSNR。

两个轴都可自由选择 (X 轴:、、psnr、 ssim、lpips 等;Y 轴同样)。ParetoFront2D.indices 中的 Pareto Front 逻辑知道每个指标是"越小越好" (例如 LPIPS、 Loss、Time) 还是"越大越好" (PSNR、SSIM) —— 因此线视轴 选择从左下到右上或从左上到右下,始终沿最佳达到的组合。 一个点是 Pareto 最优的,当且仅当 没有 其他点在 两个维度都至少同样好 (即没有其他支配它)。Pareto 最优点 位于线上,其他点在右/上 (视轴方向)。线上的点是"最佳预设" 的真正候选;远离线的点是浪费的训练时间。

您可以将选择限制到特定场景 (例如当您 只想比较户外运行时)、特定策略 (Classic 或 MCMC),或 Mip-Splatting 开/关 (在 Q1.5 阶段后相关,其中 Mip 保留为 opt-in 高级标志)。

您有"truck"场景的三个报告在 ~/Documents/RadianceKit/Reports/:Run A (P4 Quality、40K iter、524K Gs、105 s、PSNR 23.4)、Run B (P7 MCMC、200K iter、 150K Gs、693 s、PSNR 24.6)、Run C (P9 Outdoor、100K iter、 1.25M Gs、312 s、PSNR 25.8)。设 X 轴为 trainingTime,Y 轴 为 PSNR。Run B 在右上,Run C 在更右上,Run A 在左下。 Pareto Front 连接 A 和 C —— 都非支配。Run B "丢失" (C 在 Time 和 PSNR 上都更好)。洞察:对"truck",MCMC 默认不 值得;要么快+还行 (A) 要么长+非常好 (C)。将 C 的配置存为 自己的预设 (检查器 → I1 Save Preset)。

下一步行动: 将最佳配置保存为预设。具体:查看 Pareto 点 (Hover 显示 PSNR/SSIM/LPIPS/Gs/Time 工具提示), 决定哪个在 Time vs Quality 折衷上最适合您,打开相应的 报告 (文件名含运行时间戳),将其训练配置在新运行中复制, 或在下次训练会话后通过检查器保存为预设。

W13按钮"Open Reports Folder…"

位置

左上角工具栏。

技术细节

打开一个文件夹选择 对话框,提示"Select a folder containing benchmark .json reports"。确认后,后台任务顺序解析文件夹中所有 .json 文件。错误报告 (损坏的 JSON、错误的 schema) 被收集并在 侧栏底部显示为"N file failed to parse" —— 不崩溃。如果在 第一次加载仍在运行时进行第二次单击,前一个任务被取消, 以使不会有两个结果同时写入状态。

也通过 CLI:–dashboard-dir /路径/到/reports 在应用启动 时立即加载文件夹。

W14选择器"X-Axis"

位置

图表上方,左侧。

技术细节

带 Dashboard 模块所有 可用指标轴 (PSNR、SSIM、LPIPS、Gaussian Count、训练时间 等) 的菜单选择器。默认是 Gaussian Count。切换时已悬停的 点被重置,因为旧轴坐标系中之前突出显示的位置在轴切换后 无意义。选择器限于内容宽度,以使其不横跨整个宽度。

W15选择器"Y-Axis"

位置

图表上方,X-Axis 旁。

技术细节

与 W14 相同,只是默认 是 PSNR。轴选择独立保存,因此用户也可选择无意义组合 (X=PSNR、Y=PSNR —— 会将所有点投到对角线上)。但此类组合 不被捕获;有意决策,因为"SSIM vs PSNR"比较确实有趣, 用于看指标行为有多一致。

W16开关"Show Pareto Front"

位置

轴选择器旁右侧。

技术细节

标准 macOS 开关。 活动时,Pareto 图表中除点云外还绘制一条带计算出的 2D Pareto Front 的线。样式:虚线 (4-4 模式)、灰色半透明、 线宽 1.5 pt。Pareto 计算在主线程上运行 —— 对典型的报告 数量 (≤ ~50) 无问题快速。开关关闭时,线被省略,只剩 纯点。

W17Chips "Scene" 过滤器

位置

Dashboard 窗口右侧栏。

技术细节

加载报告中出现的每个 场景的过滤芯片。自有 Flow 布局,一旦宽度耗尽自动将芯片 打包到多行。活动芯片获得 Accent 背景,不活动的获得中性 标准 Material 背景。可多选 (Set 语义);如果没有芯片选中, 所有场景都视为"通过" —— 即 Set 逻辑是"空选 = 一切", 不是"空选 = 无"。

W18Chips "Strategy" 过滤器

位置

侧栏中 Scene Filter 下方。

技术细节

与 W17 一样,但用于 训练策略 —— 通常是两个值"classic"和"mcmc",从基准报告 JSON 的 Strategy 字段派生。当您混合了两种策略的报告并只想 看一种时有帮助 (例如"只显示 MCMC 运行,因为我已经排除 Classic")。

W19Chips "Mip-Splatting" 过滤器

位置

侧栏中 Strategy Filter 下方。

技术细节

三值过滤器 (而非 W17/W18 那样的 Set):"All" / "On" / "Off"。背景:Mip-Splatting 在阶段 Q1.5 中被评估为实验性多尺度改进,最终裁定是"全程 无明显胜利;保留为 opt-in 标志"。当您做 Mip 开/关比较时, 通常想能非常清晰地分离。因此专用的三元过滤器,带状态 "全部通过"、"仅 Mip 开"、"仅 Mip 关"。侧栏部分仅在 数据集中至少有一个 Mip 报告 和 一个非 Mip 报告时显示 (否则过滤无意义)。

W20ChipButton (Filter Toggle,all/on/off)

位置

辅助组件,用于 W17/W18/W19。

技术细节

极简的按钮包装。内容: 带 Caption 字号和 Padding 10 水平 / 5 垂直的标签文本。 背景条件化:活动时 → 应用 Accent 颜色带白色文本;否则 中性标准 Material 背景带黑色文本。形状是 Capsule (药丸状)。 Plain Button 样式,使 Capsule Material 不被系统边框覆盖。

W21Chart (Pareto Scatter)

位置

Dashboard 中央区域。

技术细节

带两层的 Swift Charts 图表:1. 每个报告一个点 —— 位置来自选定的 X 和 Y 指标, 颜色按 Strategy,符号按 Mip 状态。Symbol 大小常规 80, 突出 200 (如果 ID 对应当前悬停的报告)。2. 仅当开关打开时 绘制 Pareto Front 线。

Chart Overlay:一个透明矩形注册鼠标移动;每帧确定 Plot Frame 中欧几里得最近的点位置,如果距离低于 24 px 则更新 悬停的报告 (否则重置)。这样您无需单击就获得工具提示 —— 悬停就够。

W22Tooltip (Hover 详情)

位置

图表下方,Hover 时显示。

技术细节

水平栈:场景名 (Headline)、 Strategy 标签 (Caption)、分隔线、然后 PSNR/SSIM/LPIPS/Gs/Time 指标各为一个小垂直组 (标签 + monospaced 值)。如果 Mip 激活, 另外一个 Accent 颜色"Mip"Capsule 标签。背景半透明 Blur, 8 pt 半径圆角矩形。仅在鼠标确实在点上时显示。离开时自动 消失。

Holdout Analysis (W23–W29)

带空状态和行动召唤"Open transforms.json…"的空状态。接受 NeRF Studio 和 Instant NGP 格式。

空状态 (首次打开后) —— 一旦加载 transforms.json, 相机标记出现,见下张截图。

标题显示加载的文件 (transforms_train.json) 和相机数 ("100 cameras")。左侧 栏:策略选择器,两个选项 —— Angular (longitudinal) 活动 (按球面上的经度/纬度扇区对折,使每个测试折几何上密集) 与 Linear (round-robin) (基于顺序,每第 k 帧作为测试集)。 k-Folds 滑块在 5,Test-Fold 选择器在 Fold 1。Export 按钮 生成用于 Nerfstudio/Instant-NGP 的 fold-assignment.json。 中间面板:所有 100 个相机的 3D 球面投影 —— 绿色点 = Train, 红色点 = 当前 Test Fold (Fold 1 含 20 相机)。右侧栏 (Angular Correlation):每折 20 个相机 + 平均最近角 (Fold 1: 7.9°、Fold 2:7.8°、Fold 3:7.7°、Fold 4:7.0°、Fold 5: 6.3°) —— 值越小意味着此折内的相机紧密相邻,即 Holdout 分割空间连贯。

这是什么: 您相机布置的 3D 可视化器,带交叉验证 逻辑。您加载一个 transforms.json (Nerfstudio / Instant-NGP 对相机位姿的标准格式),应用读取所有相机,将它们的视线 方向投影到单位球面上,并在虚拟球体上显示为小球面标记。 然后将相机分成 k 折 (按所选策略:angular 或 linear), 标记绿色为训练部分,红色为测试部分 (Holdout),并为每折 计算一个 Angular Correlation 分数,告诉您测试折在视角空间 中距训练折多远。

当您要做 Holdout 评估时 —— 即:您的 模型对未见视角的泛化有多好?训练中的标准是"每第 8 个视图 作为 Holdout" (Mip-NeRF360 约定),但这是非常线性的拆分。 如果您的图像例如按时间聚类 (先物体一侧,然后另一侧), 则"每第 8"不具代表性 —— 随机序列位置落入测试集,但其 所有邻居在训练集,这太容易。使用"angular"则在视角空间 上分层:每折包含轨道所有区域的相机,使测试真正测试泛化 空隙。

Angular vs Linear:- Angular (标准): 按经度角 (绕 Y 轴的 φ 坐标) 将相机分成 k 个相等扇区。 Fold 0 是 φ ∈ [0°, 360/k°) 的相机,Fold 1 是接下来, 依此类推。优点:每折覆盖轨道的部分扇区;测试折空间紧凑 但在世界数据集上广泛分布。适合经典轨道拍摄。- Linear (Round-Robin):Fold-Index = (image_index modulo k)。这 是简单的"每第 k 个"拆分。在图像顺序没有空间偏差时 (例如随机排序的无人机拍摄) 工作。在图像按时间聚类时 工作不佳。

在 3D 球面中您立即看到:绿色点 (训练) 和红色点 (测试)。 如果红色点都聚集在一角,Holdout 不好 (不是好的泛化测试)。 如果它们均匀分布在绿色之间,则好。每折的 Angular Correlation 分数 (右侧栏,以度) 另外告诉:更小值 = 测试 靠近训练 (每个测试相机有一个近邻训练相机,容易测试); 更大值 = 测试远离训练 (更难泛化)。

您用 251 张图像拍摄了 Truck 场景, 通过菜单项 M33 (Export SfM transforms.json) 导出一个 nerfstudio 文件。打开 Holdout 窗口 (⇧⌘H),通过"Open transforms.json…"加载 JSON,查看球面。k=5 (默认) 给您 5 折。单击"Fold 3" —— 看红色标记是否相对均匀。如果是: "Export fold-assignment.json",将导出的文件放在 Reports 文件夹中,下次带 –benchmark 的训练运行 (或相应的检查器 设置) 将使用这个折划分作为 Test-Holdout —— 替代默认 的"每第 8"。

W23按钮"Open transforms.json…"

位置

左上角工具栏。

技术细节

打开一个限于 JSON 文件的文件选择对话框。确认后,Holdout 模块加载文件。 加载器解析 nerfstudio 格式 (相机内参加上带图像路径和 Transform 矩阵的帧列表) 和 instant-ngp 格式 (相同结构)。 每帧从 Transform 矩阵提取视线方向 (相机本地基的 z 轴) 并保存。如果解析失败,在状态区显示错误消息。

也通过 CLI:–holdout-file /路径/到/transforms.json 直接启动窗口并加载文件。

W24选择器"Strategy" (angular/linear)

位置

左侧栏,上方。

技术细节

带两个选项的 Radio 选择器:Angular 和 Linear。策略切换自动触发折的重新计算。 视线方向是球面上 3D 单位向量的列表;Angular 策略投影到 经度角 φ 并排序,Linear 策略简单按帧索引做模运算划分。

W25滑块"k Folds"

位置

左侧栏,中部。

技术细节

从 3 到 10 的滑块, 步进 1。更改时折计算自动重新触发,使折列表、训练/测试 索引和每折分数立即重新计算。所选值显示为标签右侧的 monospaced 数字文本。

经验法则:k=5 是标准 (给您每折 20% 测试,这是交叉验证 的常用值)。k=10 当您有非常多数据且需要更多折以获得 统计意义时。k=3 当您数据少时。

W26选择器"Test Fold"

位置

左侧栏,k 滑块下方。

技术细节

菜单选择器。选项动态 为 0..<k,标签"Fold 1"到"Fold N" (即 UI 中 1 索引, 内部 0 索引)。如果之前所选索引 ≥ k (例如因为您将 k 从 10 减到 5),它自动重置为 0。所选 Test Fold 在球面中显示 为红色,所有其他显示为绿色。

W27按钮"Export fold-assignment.json"

位置

左侧栏,下方。

技术细节

打开默认文件名为 fold-assignment.json 的保存对话框。确认后,Holdout 模块 将当前划分编码为 JSON schema (按帧的折分配加 Strategy 元块)。该文件随后可在下次带 –benchmark 的训练中带上, 使相同的 Holdout 用于最终指标评估。写错误显示为错误文本; 成功显示为绿色文本"Saved to (filename)"。

W28SCNView (3D 相机球面)

位置

Holdout 窗口中央面板。

技术细节

SceneKit 球面视图。 场景包括:线框球 (半径 1.0、36 段、深灰色)、三个彩色 轴端柱 (红/绿/蓝代表 X/Y/Z,长 1.2)、每个相机一个小标记 球 (半径 0.03) 位于单位球面上相应视线方向位置 (略在外面, 以使其不消失在线框球内)。标记在每次折更改时 不 重新构建 —— 仅在帧列表更改时 (即加载了新 JSON) 需要重建。 相反,每次更新运行就地更新材质颜色:Test 索引红色, Training 绿色,既不也不浅灰色。这样即使在 N > 1000 相机时滑块刻度也保持高性能。

相机控制激活 —— 您可用鼠标旋转、缩放、平移球面。光照 确保标记不显平。背景深灰。

W29FoldCard (单击选择折)

位置

右侧栏,"Angular Correlation"部分。

技术细节

每折一个卡片视图 —— 6 pt 半径圆角矩形,Padding 10,垂直布局两行 (上"Fold N" + 相机数,下"Mean nearest angle:" + 度数值)。背景颜色 条件化:活动折 = Accent 颜色半透明,不活动 = 中性标准 Material。点击选择折,球面实时重新着色。

"Mean nearest angle"分数是每个 Test 相机到最近 Training 相机的平均最小角 (内部以弧度计算,UI 中以度显示)。

BayesOpt Console (W30–W39)

带 Search Space 选择器 (RadianceKit defaults (6-dim))、 Trial Budget 滑块 (默认 40)、Random Seed (42) 和 Convergence 图、Trial Log 与 Search Space 参数列表三个空面板的空状态。

空状态 (首次打开后) —— 一旦启动运行,Convergence 图和 Trial 表填满,见下张截图。

右上方状态"Finished — best 0.9943 after 40 trials"。左侧栏:Search Space 选择器为 RadianceKit defaults (6-dim)、Trial Budget 40、Random Seed 42。Parameter 列表显示要调优的六个超参数及其值范围: mipSmoothing3DScale [0.05, 0.5]、mipFilter2DVariance [0.1, 0.6]、 densifyGradThreshold [5e-07, 5e-06]、ssimWeight [0.05, 0.5]、 mcmcNoiseScale [1e-05, 0.0001]、mcmcRelocationInterval [50, 200]。 中间:Convergence 图 (X = Trial Index 1–40,Y = Objective Value 0–1) —— 灰色点 = 初始样本 (LHS),蓝色点 = BayesOpt Acquisition,橙色点 = Restart Trials (#22 和 #31)。 Best-Value 线陡升到 Trial ~7,然后到 Trial 15 仅边际改进, 从此处起在 0.99+ 平台。右侧栏:Trial Log #1–#34 含 Score + 标签 (init/bo/restart)。右上方的 Save Best Config 按钮写入 bayesopt-best.json。

这是什么: 一个用于超参数搜索的贝叶斯优化控制台。 贝叶斯优化是一种自动方法,尝试用尽可能少的实验找到一个 未知函数的最优点 —— 通常是:"哪个 mcmcMaxGaussians、 capMultiplier、ssimWeight 和 gradThreshold 组合为我的场景 类提供最佳 PSNR?"BayesOpt 不是 6^4 = 1296 次试验的网格, 而是尝试约 40–100 次信息化试验,从而接近最优。

重要: 应用当前交付的版本不针对真实训练运行执行 优化 (那会耗费数天),而是针对一个合成的演示目标 —— 带 Hill-Climbing 特性的多模态地形加轻微噪声。这是有意的: 该窗口应向您展示优化器的行为 (收敛走势、采样点、 Best-So-Far),并让您理解 Search Space 定义。对于真实 的训练驱动 BayesOpt 运行 (如阶段 Q7 中为 Scene-Class 预设进行的),使用独立的离线 CLI 工作流;该窗口是实时 UI 变体。

三种用例:1. 您要理解 BayesOpt 如何 工作 —— 启动演示运行并观察 Convergence 图。2. 您计划 新的场景类 (例如"水族馆"或"古董家具"),内置的 10 个 预设不完美匹配。在心中定义搜索空间,在此处用"Bowl demo" 或"Densify"预设检查,然后将 Best Config 导出为 JSON 并用作真实训练运行的起点。3. 您要检查 RKBayesOpt 包中 定义的默认 Search Space (Mip Subset、RadianceKit Defaults) —— 它们在左侧栏的 Parameter 面板中列出。

- Convergence 图 (中间列): Y = 迄今最佳达到的目标函数值。X = Trial Index。开始陡升 (BayesOpt 随机尝试初始样本,其中一些幸运),然后越来越 平,因为近最优区域已用尽。如果线持续 20+ 次试验平稳, 您可停止运行 —— 进一步试验不再带来收益。图中的单个点 是单独的 Trial 值 (不是"迄今最佳"),按阶段着色:灰色

初始样本,蓝色 = bayesopt acquisition,橙色 = restart。

- Trial 表 (右栏):#1、#2、#3 等,每个带值 和阶段标签。迄今最佳 Trial 标记为黄色星星。从表中您可 识别 Best Trial 并在导出时查看其参数值。- Search Space 检查器 (左侧栏):对所选预设显示所有参数名及其 搜索范围 [lo, hi]。当您在预设"RadianceKit defaults (6-dim)"上时,您看到例如"densifyGradThreshold [5e-7, 5e-6]" —— 即在这两个值之间 log-uniform。

选择预设"RadianceKit defaults (6-dim)"、 Trial Budget 40、Seed 42。单击"Start"。观察:前 8 次 试验为灰色 (初始样本、LHS 拉丁超立方),后续为蓝色 (BayesOpt 获取)。Convergence 图陡升到 Trial ~15,然后 平缓。在 Trial ~30–40 时最佳值稳定。单击"Save Best Config" —— 一个 bayesopt-best.json 保存,含预设名、 Trial Index、值和解码的参数值。然后您可将该 JSON 手动 采纳到您的预设定义中。

W30按钮"Start"

位置

左工具栏,在 Idle/Finished 状态。

技术细节

重置 Trial 列表, 切换到 Running 状态,生成新的 Run ID (用于多次 Start 单击的 Stale 检测) 并创建一个新的 Pause Gate。然后启动 一个后台任务,作为异步流执行优化器。初始样本大小由 min(8, budget / 4 + 1) 得出 —— 即在 Budget ≥ 28 时 典型为 8 个拉丁超立方样本,在小预算下更少。Trial 更新 增量接收并附加到列表。Stale Run 保护:如果期间第二次 Start 单击重设 Run ID,旧 Run 的更新被丢弃。

Primary Action 样式用于突出的按钮外观。

W31按钮"Pause"

位置

左工具栏,在 Running 状态。

技术细节

激活 Pause Gate 并 切换到 Paused 状态。实际效果:Runner 在 50 ms 轮询循环 中等待,然后才评估下一个 Objective 函数。这意味着正在 运行的 Trial 完成 (它是合成的且仅耗时微秒),但不会启动 下一个 Trial。一旦 Resume 运行,它从中断处继续。

W32按钮"Stop"

位置

左工具栏,在 Running 和 Paused 状态。

技术细节

取消 Runner 任务, 清空引用,解除 Pause Gate (如果仍 paused),并切换到 Finished 状态 (如果存在 Trial) 或 Idle 状态 (如果没有)。 已计算的 Trial 在列表中保留可见 —— Stop 不删除它们。 破坏性按钮角色让按钮显示为红色,因为它中断运行。

W33按钮"Resume"

位置

左工具栏,在 Paused 状态。

技术细节

解除 Pause Gate 并 切换回 Running 状态。Runner 任务已经在运行 (它在轮询 循环中等待);一旦循环注意到 Pause 被解除,它继续并 启动下一个 Trial。

W34按钮"Save Best Config"

位置

右工具栏,始终可见 (但无 bestTrial 时禁用)。

技术细节

打开默认文件名为 bayesopt-best.json 的保存对话框,限于 JSON。确认后 构建 Payload 字典:预设名、Trial Index、值 (Objective Score)、Parameters (解码的参数名 → 值的字典)。解码将 归一化的搜索空间坐标 [0,1]^d 投影回原始值范围 (按 log-uniform/linear/integer 比例)。JSON 输出 pretty-printed 且键排序。写错误 (在当前演示版本中) 静默忽略 —— 无 错误 UI,因为这是演示路径。

按钮在没有 Trial 运行过时保持灰显。

W35选择器"Search Space"预设

位置

左侧栏,上方。

技术细节

带四个预设选项的菜单 选择器:- "RadianceKit defaults (6-dim)" —— 含所有 Q7 超参数的完整标准搜索空间。- "Mip subset (2-dim)" —— 仅 mipSmoothing3DScale [0.05, 0.5] log-uniform 和 mipFilter2DVariance [0.1, 0.6] linear。当您要为场景类 调优 Mip-Splatting 时有用。- "densify-until + ssim-weight + grad-thresh" —— 三个 Densify 相关参数 (densifyGradThreshold log-uniform、ssimWeight linear、densifyUntilIter integer)。 - "Bowl demo (1-dim)" —— "BayesOpt 这样工作"演示的教学 性单参数搜索空间。

运行活动时不能切换搜索空间 (会混乱优化器)。

W36滑块"Trial Budget"

位置

左侧栏,Search Space 选择器下方。

技术细节

从 10 到 200 的滑块, 步进 5。默认 40。意味着:BayesOpt 最多可做 N 次试验。 其中前若干次是初始样本 (拉丁超立方),其余是真正的 BayesOpt 试验。实用经验法则:具有 d 维度的搜索空间需要 约 10d 到 20d 次试验以获得好的最优。在 6 维默认 中即 60–120,在 2 维 Mip 子集中 20–40,在 1 维 Bowl 演示中 10–20。

运行期间滑块禁用。

W37滑块"Random Seed"

位置

左侧栏,Budget 滑块下方。

技术细节

从 1 到 100 的滑块, 步进 1。默认 42。种子被传递给初始拉丁超立方样本以及 演示 Objective 的噪声组件。可重复性:相同种子 + 相同 搜索空间 + 相同预算产生完全相同的试验序列。对"如果 同事们重建演示,他们能否获得相同运行?"有用。运行期间 禁用。

W38Chart (Convergence)

位置

窗口中间列。

技术细节

带两层的 Swift Charts 图表:1. 每次试验"迄今最佳值"的线 —— Accent 颜色的 单调递增或保持线。2. 每次试验一个点,带单独 Objective 值,按阶段着色。Symbol 大小 40。三个阶段标签:"init" (灰色)、"bo" (蓝色)、"restart" (橙色)。

一个小图例在左上方显示阶段颜色。如果 Trial 列表为空 (首次启动前),改为显示带 Chart 图标和提示"Press Start to begin a BayesOpt run." 的空状态显示。

W39Table (Trial Log)

位置

窗口右列。

技术细节

含 lazy 堆叠 Trial 行的滚动区。每行一个水平栈:Trial 编号 (3 位 monospaced, 左)、值 (monospaced、右对齐、70 pt 宽)、阶段标签 (Capsule, 25% Opacity 阶段颜色填充),可选黄色星星 (如果该试验 为当前最佳)。自动滚动机制在新 Trial 到达时自动跳到末尾 —— 使您能在屏幕底部跟读实时走势,而无需自己滚动。

主窗口:Loss 走势和 Gaussian Count (I39–I41,交叉引用)

主窗口检查器中的三个显示值得单独解释,因为它们在训练运行 时持续可见,并且关于走势何时看起来健康有重要经验法则。 显示在检查器中的"Loss Chart"部分 (见第 2 章 —— 检查器), 并补充上面辅助窗口中的 Holdout 分析。

何时 Loss 曲线健康? 健康的 Loss 曲线显示三个阶段: (1) Warmup —— 前 200–500 次迭代 Loss 从高 (L1+SSIM 组合视场景典型 0.15–0.25) 陡降到约一半。如果 该阶段中 Loss 不下降,通常输入错误 (图像损坏、SfM 位姿 差、初始 Gaussian 数太少)。(2) Densification —— 在 ~500 与 densifyUntilIteration (Classic 15K,MCMC 到 20K 或 25K) 之间,Loss 继续下降,当 Densify 操作插入新 Gaussians 且 Optimizer 利用它们时常带小跳跃。Gaussian Count 在该阶段增长。(3) Refinement —— 之后 Loss 进入 逐渐平缓的尾。典型最终值:Tanks-&-Temples Truck 用 P4 Quality 落在 L1 ≈ 0.023,Horse 用 Full Classic V546 在 L1 ≈ 0.0230,户外 Mip-NeRF360 场景往往更差 (0.04–0.07)。

平台意味着什么? 平台 (Loss 曲线在数千次迭代中 水平延伸) 有两种解读:(a) 模型已收敛,继续训练不带来 什么 —— 这是好情况。(b) 模型卡住 (局部最小、糟糕的梯度 信息、缓冲区限制的 Cap) —— 坏情况。两者在图中看起来相同。 区分:查看 Gaussian Count。如果它也平稳 并且 接近 MCMC Cap (例如 .fullMCMC 上 150K 中 150K),您已达到极限 —— 要么提高 Cap,要么接受平台。如果 Gaussian Count 仍 增长但 Loss 不下降,则卡住了。

何时中止 vs 继续训练? 经验法则:10K 迭代无 Min-Loss 改进 → 中止,进一步迭代浪费。在此之前:您可通过 Cmd+T (Training 菜单 → Continue Training → +5K iterations) 再附加一个延长,如果您看到边际改进。注意:在 MCMC 中 平台往往是真的 —— Cap 是自然边界。

Gaussian Count 平台 不 是"完成"信号。 它 仅意味着 MCMC 达到了 Cap 或 Classic Densification 已用尽。 真正的"完成"问题仅由 Holdout 分析回答 —— 在独立测试集 上的 PSNR/SSIM/LPIPS,通过 Holdout 窗口 (W23–W29) 或 –benchmark 标志评估。

PSNR/Holdout 是真理,Loss 仅代理。 Loss 是相对 指标:它在您的模型适应训练视图时下降。但低 Loss 并不 自动表示好模型 —— 如果模型记住了训练图像 (过拟合), Loss 会小,但在未见视图 (Holdout) 上的 PSNR 会差。因此: 对最终质量评估始终看 Holdout 指标,而不是仅看最终 Loss。

经验法则盒

- User Guide 和 Keyboard Shortcuts 是静态帮助 —— 对关键词 问题快速,深入则使用此手册。 - 当磁盘剩余空间低于 10% 时打开 Manage Storage。Logs 和 Imports 暂存通常是罪魁。 - Pareto Dashboard 在至少三或四个训练报告之后才有意义。 X 轴 = 成本 (Time / Gs),Y 轴 = 质量 (PSNR / SSIM)。 Pareto Front 显示高效组合。 - 在向其他人发布 PSNR 基准之前使用 Holdout Analysis —— 确保您的测试集真正具有代表性。 - BayesOpt 控制台主要是搜索空间定义的学习和检查工具。 对真实训练驱动的超参数调优使用离线 CLI 工作流。 - Loss 平台和 Gaussian Count 平台需分别解读。Cap 限制 不是"完成"信号。真正质量仅由 Holdout PSNR 测量。 - 10K 迭代无 Min-Loss 改进 → 停止训练。