gsplat-optimizer

Gaussian Splat 优化器

使用 Metal 优化 3D Gaussian Splatting 场景，以便在 Apple 平台（iOS、macOS、visionOS）上实时渲染。

使用场景

• 为移动设备或 Apple GPU 目标优化 .ply 或 .splat 文件
• 为提升性能减少高斯数量（剪枝策略）
• 为大型场景实现细节层次（LOD）
• 在带宽或存储受限时压缩 splat 数据
• 分析并优化 Metal 渲染性能
• 针对 Apple 硬件设定特定的 FPS 目标

快速开始

输入：提供 .ply/.splat 文件路径、目标设备类别和 FPS 目标。

# Analyze a splat file
python ~/.claude/skills/gsplat-optimizer/scripts/analyze_splat.py scene.ply --device iphone --fps 60

输出：该技能会提供：

1. 点/高斯剪枝方案（不透明度、大小、误差阈值）
2. LOD 方案建议（距离分档、高斯子集）
3. 压缩建议（带宽或存储受限时）
4. Metal 性能分析清单，包含着色器/计算提示

优化工作流

第 1 步：分析场景

首先了解场景特征：

• 高斯数量：splat 总数
• 不透明度分布：不透明度值直方图
• 大小分布：高斯尺度统计信息
• 内存占用：预估 GPU 内存使用量

第 2 步：确定目标设备

设备类别	GPU 预算	最大高斯数（60 fps）	存储模式
iPhone（A15+）	4-6 GB 统一内存	~2-4M	共享
iPad Pro（M1+）	8-16 GB 统一内存	~6-8M	共享
Mac（M1-M3）	8-24 GB 统一内存	~8-12M	共享/托管
Vision Pro	16 GB 统一内存	~4-6M（立体渲染）	共享
Mac（独立 GPU）	8-24 GB VRAM	~10-15M	专用

第 3 步：应用剪枝

如果高斯数量超过设备预算：

1. 不透明度阈值：移除不透明度 < 0.01-0.05 的高斯
2. 大小剔除：移除小于像素的高斯（在目标分辨率下 < 1 px）
3. 重要性剪枝：使用 LODGE 算法进行误差代理选择
4. 注视点渲染：对于 Vision Pro，降低周边视野中的密度

详情请见 references/pruning-strategies.md。

第 4 步：实现 LOD（大型场景）

对于超出单帧预算的场景：

1. 距离分档：近（0-10 m）、中（10-50 m）、远（50 m 以上）
2. 层次结构：使用八叉树或 LoD 树进行空间查询
3. 分块流式加载：根据摄像机位置加载/卸载
4. 平滑过渡：在分块边界处混合不透明度

详情请见 references/lod-schemes.md。

第 5 步：应用压缩（如有需要）

对于带宽或存储受限的情况：

方法	压缩率	使用场景
SOGS	20x	Web 分发，中等画质
SOG	24x	Web 分发，更佳画质
CodecGS	30x+	最大程度压缩
C3DGS	31x	优先快速渲染

详情请见 references/compression.md。

第 6 步：分析并优化 Metal

1. 选择存储模式：静态数据使用 Private，动态数据使用 Shared
2. 优化着色器：函数常量、线程占用率
3. 使用 Xcode 进行性能分析：GPU Frame Capture、Metal System Trace
4. 迭代：测量、优化、重复

详情请见 references/metal-profiling.md。

常见问题

1. 点云密度不匹配

**问题：**高斯数量与场景复杂度不匹配，导致视觉伪影或浪费 GPU 资源。

• **过于稀疏（欠采样）：**出现可见间隙、块状感，细节丢失
• **过于密集（过采样）：**超出设备预算，导致帧率下降和 GPU 资源争用

调试：

# Analyze gaussian distribution
python ~/.claude/skills/gsplat-optimizer/scripts/analyze_splat.py scene.ply --histogram

# Check against device budget
# Compare total_gaussians vs. device_max in the output table

策略：

• 从第 2 步的设备预算开始（例如，iPhone 为 4M）
• 如果场景超出预算 >20%，请在训练前进行剪枝
• 如果剪枝后画质下降过多，请考虑使用 LOD 或分块
• 使用按重要性加权的采样（LODGE）移除贡献较低的高斯，而不只是移除不透明的高斯

---

2. 训练不稳定（梯度爆炸、发散）

问题： 优化期间（如果在设备上进行微调），高斯参数会发散，导致：

• 损失突然变为 NaN
• 高斯消失或尺寸爆炸
• 模型在会话中途变得无法恢复

调试：

# Monitor loss during training
tail -f training.log | grep -E "loss|nan|inf"

# Check gradient magnitudes
python -c "
import numpy as np
from plyfile import PlyData
ply_data = PlyData.read('scene.ply')
scales = ply_data['vertex']['scale_0'].data
print(f'Scale range: {scales.min():.6f} to {scales.max():.6f}')
print(f'Any NaN: {np.isnan(scales).any()}')
"

策略：

• 梯度裁剪： 将每步的梯度更新幅度限制在 ±0.1
• 学习率衰减： 从 1e-4 开始，每个 epoch 衰减 0.95
• 损失正则化： 对尺寸幅度添加 L2 惩罚，以防止爆炸
• 提前保存检查点： 每 10 次迭代保存状态；如果损失骤增则回滚
• 冻结协方差： 如果已收敛，在训练完成 80% 后停止更新尺寸／旋转
• 设备训练： 如果不稳定问题仍然存在，请减小批次大小或分辨率

---

3. 内存限制（大型场景发生 OOM 错误）

问题： 场景超出可用统一内存，导致分配失败或 GPU 停滞。

• iPhone：应用与 GPU 共用 4–6GB
• iPad Pro：共用 8–16GB
• Vision Pro：16GB（但立体渲染会使高斯数量翻倍）

调试：

# Estimate memory footprint
python << 'EOF'
num_gaussians = 5_000_000  # Your count
bytes_per_gaussian = 56  # pos (12) + scale (12) + rot quaternion (16) + opacity (4) + SH DC (12)
total_mb = (num_gaussians * bytes_per_gaussian) / (1024 ** 2)
print(f"Est. memory: {total_mb:.1f} MB")
print(f"Safe for iPhone A15: {total_mb < 2000}")  # Leave headroom for app
EOF

# Monitor live memory in Xcode
# Memory graph + Allocations instrument during scene load

策略：

• 大型场景分块： 拆分为 1–4M 个高斯的区块，并根据相机距离进行流式加载
• 量化： 使用 FP16 而非 FP32 存储高斯（内存减少 2 倍）
• 先进行剪枝： 将数据传输到设备前，移除不透明度 <0.01 或尺寸小于像素的高斯
• 延迟加载： 内存中仅保留活跃的 LOD 层级；卸载较远的区块
• 考虑 Vision Pro： 双眼渲染 = 2 倍高斯数量；将每只眼睛的数量限制在 4M

---

4. 质量／速度权衡（对单一指标过度优化）

问题： 过度优化某项指标会损害另一项：

• 最大化 FPS → 视觉伪影： 过度剪枝会移除重要几何体
• 最大化质量 → 掉帧： 高斯数量对目标设备来说过多
• 最小化内存 → 色带／色调分离： 过度量化或 LOD 剔除

调试：

# Profile before/after each change
python << 'EOF'
metrics = {
  "original": {"fps": 60, "gaussians": 5_000_000, "artifacts": "none"},
  "after_pruning": {"fps": 58, "gaussians": 3_500_000, "artifacts": "block edges visible"},
}
for label, m in metrics.items():
    print(f"{label}: {m['fps']}fps, {m['gaussians']/1e6:.1f}M, {m['artifacts']}")
EOF

策略：

• 确定优先级： 该设备侧重速度（AR、实时渲染）还是画质（预览）？
• 测量基线： 先分析未经优化的原始场景
• 逐步迭代： 每次只应用一项优化（剪枝或压缩或 LOD），测量后再决定
• 保留质量指标： 保存 PSNR／SSIM 分数；如果画质下降超过 1dB，则停止剪枝
• 目标范围： 预留 50–60fps 的余量（不要恰好达到 60fps 上限；设备会降频）

---

5. 实时渲染失败（掉帧、着色器编译）

问题： 尽管高斯数量较少，渲染管线仍会停滞：

• 首帧（冷启动）：着色器编译期间延迟 2–5s
• 场景中途：加载新的 LOD 层级时掉帧激增
• 播放流畅 → 30–60s 后出现卡顿

调试：

# Capture Metal frame statistics
# In Xcode: Product > Scheme > Edit > Run > Diagnostics
# Enable: Metal API Validation, GPU Frame Capture

# Check shader compilation time
python ~/.claude/skills/gsplat-optimizer/scripts/metal_profile.py \
  --capture-shader-compile \
  --target iphone14

# Monitor frame time distribution
tail -f xcode.log | grep -E "frame_time|stutter"

策略：

• 预热着色器缓存： 首次加载时编译所有函数变体（避免运行时卡顿）
• 限制 LOD 转换： 如果使用多个 LOD 层级，将每帧转换次数限制为 2 次
• 异步流式加载： 在后台线程加载新的几何区块，并在帧间上传
• 针对设备进行调优：
  • iPhone：绘制调用保持在 50 次以内，每次调用的几何体少于 500K 个高斯
  • Mac：限制更宽松；每次绘制调用目标为少于 2M 个高斯
  • Vision Pro：考虑立体渲染；有效容量为预算的一半
• 性能分析流程： 每次优化前后运行 Metal System Trace；跟踪：
  • GPU 利用率（目标为 70–85%）
  • 着色器耗时（目标为 <10ms）
  • 内存带宽（目标为 <50GB/s）

---

关键指标

指标	目标	测量方法
帧耗时	16.6ms（60fps）	Metal System Trace
GPU 内存	< 设备预算	Xcode Memory Graph
带宽	< 50GB/s	GPU Counters
着色器耗时	< 10ms	GPU Frame Capture

参考实现

MetalSplatter 是 Swift/Metal 高斯溅射的主要参考实现：

• 仓库：https://github.com/scier/MetalSplatter
• 支持 iOS、macOS、visionOS
• 通过 v1.1 优化，容量约为 800 万个溅射点
• 支持 Vision Pro 立体渲染

开始使用 MetalSplatter

git clone https://github.com/scier/MetalSplatter.git
cd MetalSplatter
open SampleApp/MetalSplatter_SampleApp.xcodeproj
# Set to Release scheme for best performance

资源

参考文档

• 剪枝策略 - 高斯缩减技术
• LOD 方案 - 细节层次方案
• 压缩 - 带宽和存储优化
• Metal 性能分析 - Apple GPU 优化

研究论文

• LODGE - 面向大规模场景的 LOD
• FLoD - 适用于不同硬件的灵活 LOD
• Voyager - 城市规模的移动端渲染
• 3DGS 压缩综述

Apple 开发者资源

• Metal 最佳实践指南
• Metal 着色器性能（技术讲座）
• 优化 GPU 渲染器（WWDC23）