第 3 章 — 设置

位置

设置 → General → Interface → Default Mode 选择器。 绑定:。默认:.simple。

技术细节

控制应用下次启动时以两种 UI 模式中的 哪一种打开。"Simple Mode"是分四步的引导式向导流程 (导入 → 处理 → 预览 → 导出,记录于第 10 章 Z1–Z4), "Expert Mode"则是第 2 章描述的带导航器、3D 视口和专家检查器 的经典三面板布局。该值在重启后保留。与菜单 Mode → Simple Mode (⌘1) / Mode → Expert Mode (⌘2) 作用相同,只不过菜单切换的是 当前会话,而此选择器为未来会话设置默认值。两种模式访问相同的 项目状态 —— 切换模式时项目、相机和训练配置保持不变。模式特定 的工具栏按钮会立即重新渲染。

位置

设置 → General → Interface → Language 选择器。绑定:。默认:.system (跟随 macOS 语言)。

技术细节

选择整个应用 UI 的显示语言, 独立于 macOS 系统语言。RadianceKit 本地化为 17 种语言 (de、en、pl、en-AU、ar-SA 以及 12 种其他)。 选择"System"时应用跟随 macOS 语言。明确选择时该语言设置 在重启后保留;完整效果通常需要重启应用,因为本地化 bundle 仅在启动时加载。项目中 298 个已记录的本地化键全部纳入,包含 所有子视图和帮助提示中的文本。

位置

设置 → General → Viewport → Background 选择器。绑定:。默认:.darkGray (RGB 0.1, 0.1, 0.1)。

技术细节

设置 3D 视口的默认背景颜色。三种选项: "Dark Gray" (RGB 0.1, 0.1, 0.1 —— 默认)、"Black" (0, 0, 0) 和 "White" (1, 1, 1)。该设置在重启后保留新项目和新会话的默认值, 同时立即更新正在运行的 Metal 渲染器。与菜单 Viewport → Background (M21、M22、M23) 中相同的选项,但设置选择器设定默认值,而菜单 切换当前显示。对截图和演示视频很重要:白色背景会更突出绿色/蓝色 漂浮物,深色背景更适合干净的渲染效果。

位置

设置 → General → Viewport → 开关"Auto-Rotate After Training"。绑定:。默认:false。

技术细节

训练结束后立即开始视口相机围绕场景重心的 连续转台旋转 (标准旋转速率 ~0.3 rad/s)。在演示会话、A/B 对比 中,以及直接从 360° 视角判断场景边缘是否出现"漂浮物"时很实用。 视觉效果与菜单 Viewport → Toggle Auto-Rotation (M16、⌘⌥T) 相同,只不过这个开关让此行为在训练结束后自动触发而非手动触发。 之后随时可通过菜单或点击视口 (会暂停旋转) 中断。对训练性能 没有影响 —— 旋转只在训练完成后才运行。

位置

设置 → General → Training → Live Preview 选择器。 绑定:AppState.trainingConfig.livePreviewInterval。默认:0 (Off)。

技术细节

决定运行中的训练快照以多少迭代间隔渲染 到 3D 视口中。四个离散值:0 ("Off")、50、250、1000 次迭代。 启用 Live Preview 时,训练器将 Gaussian 缓冲区从 GPU 复制到一个 单独的渲染缓冲区,并触发视口重绘。"Off"时视口仅在训练完成后才 更新。性能开销:每 50 次迭代在 M3 Ultra 上慢约 5–10%,每 250 次迭代慢 ~1–2%,每 1000 次迭代不可测量。Snapshot 缓冲区的内存 开销恒定 ~2 GB,与间隔无关。该值用作新训练的默认值;训练开始 后,训练检查器显示该训练的实时值。间隔 50 时的视觉印象是点云 流畅"生长",间隔 1000 时显得卡顿。

位置

设置 → General → Training → Throttle 选择器。绑定: AppState.trainingConfig.throttleDelayMs。默认:0 (Off)。

技术细节

在训练迭代之间人为插入毫秒级的延迟。 四个离散值:0 ("Off")、2 ("Light")、5 ("Moderate")、10 ("Eco")。 意义:在较长的训练中 (数小时),GPU 否则会被 100% 占用,导致 系统 UI 明显变慢 (鼠标卡顿,其他应用变慢)。Throttle 延迟给 GPU 让出空隙,让其他任务可以执行。性能开销很大:在 5 ms 节流下, 典型的 40K 训练比无节流时长 50–80%。在性能模式"Eco" (10 ms) 下,每次迭代的延迟比迭代本身还长 —— 慢 2–3 倍。启用节流时, 选择器下方出现提示:"Throttle is on. Training will be slower than usual."。应用本身不会有明显改善 —— 受益的只有其他应用。

位置

设置 → General → Experimental — Outdoor Floater Reduction → 开关"Sky Masking"。绑定: AppState.trainingConfig.skyMaskingEnabled。默认:false。

技术细节

启用训练前基于 Apple Vision 的天空像素 分割。在训练开始前,对每个输入相机通过 Apple Vision Foreground Mask 提取天空区域 (Sky = Background),并作为各相机的逐像素掩码 关联。训练过程中,每个像素的 Loss 贡献乘以天空掩码的补集 —— 天空像素对梯度贡献为 0,因此投影到天空中的 Gaussians 不会收到 任何优化信号,也就不会变"更密"或"更亮"。能在户外/无人机场景 中显著减少漂浮物 (天空中的暗团)。在经典 40K 训练中代价是约 3% 的 L1 回归 (见 memory/dev_outdoor-floater-reduction.md)。 仅在可清晰识别天空的户外场景中有用;在室内场景或白色背景中, 天空分割会识别错误区域,屏蔽有效的 Loss 信号。与其他实验性 开关不同,该值不在应用重启后保留 —— 下次启动时默认关闭。

位置

设置 → General → Experimental — Outdoor Floater Reduction → 开关"Mid-Training Floater Cleanup"。 绑定:。默认:false。

技术细节

在 Classic 40K 训练 (预设"P4 Quality") 中 启用两个额外的密度控制 Pass:在第 20,000 和第 30,000 次迭代时。 两次 Pass 都按三个条件搜索所有 Gaussians:(a) 极低的 Opacity (标准 0.005),(b) 微小的屏幕空间尺寸,(c) 过去 1000 次迭代中 没有 Loss 贡献。满足所有三个条件的 Gaussians 会被清除。效果: 训练结束时 Gaussians 减少 ~5–15%,在无人机/户外场景中明显 减少天空中的暗团。在近景室内场景中代价约 1–3% L1 回归,因此 不作为默认启用。该值在重启后保留 (与 S7 相反)。两次清理迭代 (20K、30K) 被硬编码,目前无法通过 UI 更改;在较短的训练中 (例如 P2 Preview 5K),该开关无效,因为永远到不了这些迭代标记。 详情:memory/dev_outdoor-floater-reduction.md。

位置

设置 → General → Experimental — Outdoor Floater Reduction → 开关"Reduce Elongated Gaussians"。绑定:。默认:false。

技术细节

在 Loss 项中启用额外的各向异性 正则化。优化期间,为每个 Gaussian 计算最大与最小缩放轴之间的 比值作为各向异性度量。如果该比值超过阈值 (,标准 10.0),则向 Loss 添加一个与超出量成比例 的惩罚项。效果:针状 Gaussians (草、密叶中典型的交叉网纹和条纹 伪影来源) 在训练期间要么被迫变为更圆的形状,要么被清除。代价 是在标准室内场景中 ~6% 的 L1 回归,在严格的物体扫描中无效果。 甜点在植被上方的无人机飞行拍摄。写入,通过持久化。 在 optimizer.metal 中作为梯度计算中的额外惩罚实现。请参见 项目内存中的提示:V549d 是已交付的版本,后来 V549f (带更激进的 Scale-Reg) 因灾难性回归被回滚。 详情:memory/dev_outdoor-floater-reduction.md 和 memory/dev_v549f-needle-reduction.md。

位置

设置 → General → Experimental — Outdoor Floater Reduction → 开关"Reconstruct Sky Dome"。绑定:。默认:false。

技术细节

启用训练前的 Sky-Dome 投影 (V549e MVP)。 在 SfM 之后、训练开始之前,对每个输入相机从图像中提取与 S7 共享的 Apple Vision 天空掩码;天空像素用相机内参反投影到一个 虚拟球面 (标准半径为 8× 场景半径)。在该球面上初始化 ~5000 个 新 Gaussians,其颜色均值来自投影的天空像素,具有非常大的缩放 (在场景单位中为 1.0) 和初始 Opacity 0.95。这 5000 个 Gaussians 并不是经典意义上的 Sky-Mask —— 它们与所有其他 Gaussians 一样 被训练,但通过高初始 Opacity 保留在一个薄壳上。结果:在户外/ 无人机场景的 360° 新视角中,出现的是真实的天空颜色和云结构, 而不是黑色的彩屑团块。该值在重启后保留。仅在至少 360° 相机 覆盖的户外场景中有用;在没有天空视野的纯物体扫描中无效。 状态:实验性,在更多户外集上的更广泛 A/B 验证仍待进行。

位置

设置 → AI Helpers → 第一节 → 开关"AI Helpers enabled"。绑定:。默认:true。

技术细节

流水线中所有 AI Helpers 功能的主开关。 关闭时,导入和 SfM 流水线完全跳过所有基于 ML 的预处理阶段 —— 没有 Apple Vision 调用,没有 CoreML 模型加载,不会唤醒 NPU。 启用时,会咨询各个子开关 (S12–S14)。该值在重启后保留。 影响以下阶段:(a) SfM 之前的帧质量预检 (S12),(b) 回环检测 (S13),(c) 作为新训练默认值的自动 Sky-Masking (S14)。重要: 关闭时,三个子开关被禁用并在视觉上灰显。底部提示强调,所有 AI Helpers 严格在设备端运行 —— 不上传图像,不进行云处理。 隐私保证来自于仅使用 Apple Vision Framework (本地运行在 Neural Engine 上) 和直接位于应用 bundle 中的 CoreML 模型。

位置

设置 → AI Helpers → Available 部分 → 开关"Frame quality check"。绑定:。默认:true。

技术细节

启用帧质量筛选器 (阶段 3.11), 在 SfM 调用前分析每个导入的帧。每帧的流水线步骤: (a) Apple Vision 的拉普拉斯方差滤波器 (模糊检测 —— 阈值 ~150), (b) 基于直方图的过曝/欠曝检查 (阈值:>5% 像素为 0 或 255), (c) 空白帧检测 (所有像素的标准差 < 5)。通过所有三项检查的帧 直接通过。未通过至少一项检查的帧会触发一个模态确认对话框, 对话框列出每个有问题的帧及其缩略图和原因,并询问是否移除。 重要:不会自动删除 —— 始终需要对话框,最终决定权在用户。 性能:在 M3 Ultra 上每帧 ~50 ms,并行运行。关闭时所有帧 未经检查传递给 SfM。主开关 (S11) 关闭时该开关在视觉上灰显 且无效。根据 Memory,已交付状态:SHIPPED 2026-05-23。

位置

设置 → AI Helpers → Available 部分 → 开关"Loop closure detection"。绑定:。默认:true。

技术细节

启用基于 Apple Vision Feature Print 的 回环检测。对每个导入的帧计算一个 ~768 维的特征向量,代表图像 内容的神经嵌入。然后通过余弦相似度对所有 Feature Print 进行 两两比较。相似度 > 0.85 且帧索引距离 > 50 (即非相邻帧) 的 对被识别为"回环候选",并写入项目文件夹中的一个 Sidecar JSONL 文件。仅信息性 —— 不修改导入的图像序列。意义:向 SfM 求解器 (尤其是 COLMAP) 提示这些帧在 3D 空间中应该聚类在一起。对于 原生 SfM,Sidecar 信息目前仅作为文档;COLMAP 通过自定义 matches 文件在内部使用这些提示 (可手动集成,未自动关联)。性能:在 M3 Ultra 上每帧 ~200 ms,并行运行。关闭时不生成 Feature Print。 主开关 (S11) 关闭时视觉上灰显。

位置

设置 → AI Helpers → Available 部分 → 开关"Auto sky masking"。绑定: UserDefaults.standard.bool(forKey: "aiHelpersSkyMaskingDefault") (通过自定义绑定)。默认:false。

技术细节

为新训练配置设置 S7 中 Sky-Masking 设置的默认值。与 S11–S13 不同,实际的 Sky-Masking 设置存在于 训练会话级别,且不在应用重启后保留 (见 S7)。为了让 AI Helpers UI 仍能为"新训练"提供持久默认值,存在这个影子值:它在重启后 保留,在设置新训练 (例如新项目导入) 时被用作 Sky-Masking 的 初始默认值。主开关 (S11) 关闭时视觉上灰显。