CLI 参考
按 --help 分组列出全部选项。操作示例见概览、流式 SOG、碰撞和图像渲染。
命令语法
splat-transform [GLOBAL] input [ACTIONS] ... output [ACTIONS]
- 输入成为工作集，操作顺序执行。
- 最后文件为输出，其后操作修改最终结果。
- null 丢弃输出，适合 --stats 只分析。
- 输入可为 http(s) URL，按需下载；mjs 生成器必须本地。
支持格式
按扩展名识别：
| 格式 | 输入 | 输出 | 说明 |
|---|---|---|---|
.ply | ✅ | ✅ | 标准 PLY |
.sog | ✅ | ✅ | 推荐，打包 SOG |
meta.json | ✅ | ✅ | 非打包，伴随 WebP，输出必须此名 |
lod-meta.json | ✅ | ✅ | 多 LOD 流式 SOG，必须此名 |
.compressed.ply | ✅ | ✅ | 自动识别解压 |
.spz | ✅ | ✅ | Niantic SPZ，v2–4 |
.lcc | ✅ | ❌ | XGRIDS |
.lcc2 | ✅ | ❌ | XGRIDS 八叉树 |
.ksplat | ✅ | ❌ | mkkellogg 压缩 |
.splat | ✅ | ❌ | antimatter15 压缩 |
.mjs | ✅ | ❌ | 脚本生成，测试版 |
.glb | ❌ | ✅ | KHR_gaussian_splatting 二进制 glTF，引擎可直接加载 |
.csv | ❌ | ✅ | 逗号分隔表格 |
.html | ❌ | ✅ | 基于 SOG 的单文件或非打包查看器 |
.voxel.json | ❌ | ✅ | 稀疏体素八叉树，见碰撞，名称必须以 .voxel.json 结尾，前缀任意 |
.webp | ❌ | ✅ | GPU 无损图像，见渲染 |
null | ❌ | ✅ | 丢弃输出，适合分析 |
抗锯齿与 2DGS
读取时标记抗锯齿训练或 2DGS，输出格式支持时保留，--info 的 model 报告。
- 读取：PLY 的 Brush
comment SplatRenderMode: default | mip | 2dgs或 Postshot anti_aliasing=1，最后出现优先；SPZ 位；SOG model。PLY 有 scale_0/1 无 scale_2 时，无论注释均为 2DGS，补零厚度轴以保持管线。 - 写入：PLY/压缩 PLY 用 Brush 注释，SOG 用 antialiased/2dgs model，SPZ 设置抗锯齿位但不能表示 2DGS并警告。2DGS PLY 再删 scale_2。其他格式静默丢标记。
- 渲染：抗锯齿场景使用训练滤波，默认 0.1 px²，aa-filter-size 可改，替代 0.3 扩张，缩放不透明度保质量，与引擎一致。
- 合并：标记冲突警告，结果不标记。
其他 PLY 注释也保留，PLY 写回 comment，SOG v3 写 comments。不解释含义，因此坐标类注释不随变换更新。
大于 1 的不透明度
简化合并保质量，可能大于 1，最高 1.5625 以不透明核心绘制。PLY 用单个属性：常规 opacity logit 最大 1；简化或超单位 SOG v3 用 opacity_linear 原值替代。旧工具可能不识别，--ply-logit-opacity 可截断后写标准值。读取时优先 linear。SOG v3 直接保留，v2 和其他格式截断到 1。
操作
按顺序，可重复，可出现在任意输入或输出后：
-t, --translate <x,y,z> 按 (x,y,z) 平移
-r, --rotate <x,y,z> 按欧拉角旋转，单位为度
-s, --scale <factor> 统一缩放
-H, --filter-harmonics <0|1|2|3|4> 移除高于 n 阶的球谐
-N, --filter-nan 移除 NaN、多数 Inf 和零范数不可渲染四元数；
保留 scale_* 的 -Infinity
-B, --filter-box <x,y,z,X,Y,Z> 移除最小/最大角定义的盒外单元
-S, --filter-sphere <x,y,z,radius> 移除中心/半径定义的球外单元
-V, --filter-value <name,cmp,value> 保留满足 <name> <cmp> <value> 的单元
cmp ∈ {lt,lte,gt,gte,eq,neq}
opacity、scale_*、f_dc_* 使用变换后值：线性
不透明度（合并后可大于 1）、线性缩放、0–1 线性颜色。
加 _raw 使用原始 PLY 值，例如 opacity_raw 为 logit。
-d, --decimate <n|n%> 通过合并简化为 n 个，所有区域统一移除比例。
n% 保留百分比；内存更少，适合均匀尺寸、纹理、
单对象或雪，在深度简化时效果更好。
--decimate-adaptive <n|n%> 改按局部误差分配移除，天空等混合尺度更好，内存更高。
两者均为受内存预算限制的流式处理，可到亿级。
必须末操作，输出 .ply，其他格式需再调用转换。
--scratch-dir <path> 深度简化超内存时的中间层目录，未设不写磁盘。
-F, --filter-floaters [size,op,min] 移除不贡献任何实心体素的单元，在占用体素中心求值。
默认 size=0.05、opacity=0.1、min=0.004（1/255）。
不带值使用全部默认。
-C, --filter-cluster [res,op,min] 仅保留 --seed-pos 所在连通簇。
GPU 粗体素化，res 为每体素世界尺寸。
默认 res=1.0、opacity=0.999、min=0.1；不带值用默认。
-p, --params <key=val,...> 向 mjs 生成器传参数
-l, --tag-lod <n> 标记 LOD n，n >= 0，-1 为环境
--stats [text|json] 标准输出文件信息、逐列统计和填充/过度绘制比，默认 text
--info [text|json] 标准输出格式、各 LOD 数量、额外列，默认 text
-m, --morton-order 按 Morton Z 序重排
CLI 选项
配置整次运行，而非数据操作，多数组只适用于特定格式读写。
通用
-h, --help 显示帮助并退出
-v, --version 显示版本并退出
-q, --quiet 抑制非错误输出
--verbose 显示调试诊断
--memory 进度中显示峰值内存
--tty 交互进度条，TTY 默认开，--no-tty 禁用
-w, --overwrite 覆盖已有输出
--webp-effort <0-9> 图像、SOG、HTML、LOD 的无损 WebP 压缩投入。
越高越努力减体积，默认 libwebp 无损设置。
GPU
选择计算设备，见功能要求。
--list-gpus 列出可用 GPU 并退出
-g, --gpu <n|cpu> 适配器索引或 cpu，后者禁用 GPU，
与 --filter-cluster 等 GPU 专用功能不兼容
--gpu-backend <name> 强制 vulkan | d3d12 | metal，默认平台后端。
例如 Windows 可用 vulkan 绕过 Dawn D3D12 问题。
哪些需要 GPU
均经 WebGPU，下列不能无 GPU 运行：
- --filter-cluster、--filter-floaters。
- .voxel.json 和 --collision-mesh。
- .webp，包括相机轨迹序列。
以下默认 GPU，也可 -g cpu：
- --decimate、--decimate-adaptive。
- SOG、meta.json、lod-meta.json、HTML。只有球谐 k-means 聚类用 GPU，无球谐输入或 filter-harmonics 0 全 CPU；有球谐也可 CPU，但常慢 5–10 倍。
选择设备
# List available GPU adapters
splat-transform --list-gpus
# Let WebGPU automatically choose the best GPU (default behavior)
splat-transform input.ply output.sog
# Explicitly select a GPU adapter by index
splat-transform -g 0 input.ply output.sog # Use first listed adapter
splat-transform -g 1 input.ply output.sog # Use second listed adapter
# Use the CPU instead (much slower for SH compression, but always available)
splat-transform -g cpu input.ply output.sog
# Force the Vulkan backend (e.g. to work around Dawn D3D12 bugs on Windows)
splat-transform --gpu-backend vulkan input.ply output.sog
未指定 -g 时自动最佳 GPU。--list-gpus 列索引名称，顺序与可用性依系统驱动。gpu-backend 也影响列举，仅显示对应后端。
服务器 NVIDIA 配置见 Docker。
SOG 压缩选项
适用于 SOG、meta、lod-meta 和 HTML。
-i, --sh-iterations <n> 球谐压缩迭代，越多越好，默认 10
--sh-palette-size <n> SOG/meta 调色板条目，越多越好但更慢。
v3 最高 262144，v2 65536。
默认单元数向下取 2 的幂，最大 65536。
--max-workers <n> SOG 和图像序列编码线程，0 内联串行，默认 4
--sog-version <2|3> 默认 3，2 兼容旧查看器，丢弃大于 1 的不透明度、
盲数据和四阶球谐；HTML 始终内嵌 v2。
--sog-blind <field>[,...] v3 列存为盲数据，每次标志一张纹理，依次填 RGBA 四字节。
field = <col>[:<enc>]
enc：u8/u16/u24/u32 整数，f16/f32 浮点位模式，
unorm8/unorm16 为 [0,1]，也可 unorm8[min,max]。
默认能容纳的最少字节 uint，可重复：--sog-blind id
--sog-blind a:unorm8,b:unorm8,depth:f16。
未指定时保留输入盲数据原编码；none 不保存。
--sog-extras <file.json> 将 JSON 存为 extras，仅 v3 的 meta/lod-meta，类似 glTF。
默认沿用输入 extras（若存在）。
SPZ 输出
写 .spz 时。
--spz-version <3|4> SPZ 输出版本，默认 4
PLY 输出
写 .ply 时。
--ply-logit-opacity 即使有不透明度大于 1，也截断后写标准 logit，
替代 opacity_linear，兼容不识别该属性的工具。
HTML 查看器输出
写 .html 时。
--viewer-settings <settings.json> HTML 查看器设置 JSON
--unbundled 生成文件分离的非打包 HTML 查看器
备注
--viewer-settings 数据结构见 Viewer 设置。写前验证，非法会失败，不生成空白查看器。
LOD 输入
读取 lod-meta、LCC、LCC2 时。
-L, --select-lod <n,n,...> 从流式 SOG/LCC/LCC2 读取的 LOD，逗号分隔
LOD 输出
写 lod-meta 时。
--lod-chunk-count <n> 每块近似单元数，单位 K，默认 512
--lod-chunk-extent <n> 每块近似世界尺寸，米，默认 16
--lod-chunk-min <n> 少于此数量不按范围分割，单位 K，默认 8
超过 lod-chunk-count，或宽于 extent 且数量超过 min 时分块。最小数避免天空远景被切成大量近空块，低于它时不论多宽都保持一块，密集区不受影响。
完整流程见生成流式 SOG。
体素输出
写 .voxel.json，详细调优见碰撞。
--voxel-size <n> 体素大小，默认 0.05
--voxel-opacity <n> 体素不透明度阈值，默认 0.1
--voxel-external-fill [size] 边界洪水填充外部，适合室内。
size 为填充前封小墙缝的世界膨胀距离，默认 1.6。
检查种子是否封闭，若外部可达则跳过。
--voxel-floor-fill [size] 从底部逐柱向上填到实心，适合室外。
只修补 2*size 内被地面包围的 XZ 区，保留大空域。
默认 size=1.6。
--voxel-carve [h,r] 从种子用胶囊洪水雕刻可导航空间，默认高 1.6、半径 0.2
--seed-pos <x,y,z> 填充、雕刻、簇过滤的种子，默认 0,0,0
--collision-mesh [smooth|faces] 生成 .collision.glb，默认 smooth
图像输出
写 GPU 无损 WebP，效果示例见图像渲染。
--projection <pinhole|equirect> 默认 pinhole；equirect 从 camera-pos 生成
360×180 度全景，不可指定 camera-fov，需 2:1 分辨率，
默认 2048x1024。
--camera-pos <x,y,z> 世界位置，默认 2,1,-2
--camera-target <x,y,z> 观察目标，默认 0,0,0
--camera-up <x,y,z> 世界向上，默认 0,1,0
--camera-fov <degrees> 垂直角，默认 60，全景拒绝此项
--resolution <WxH> 默认透视 1280x720、全景 2048x1024，例如 1920x1080
--camera-near <n> 近裁剪，默认 0.2，与参考 3DGS 一致
--background <r,g,b[,a]> 0–1 背景，默认 0,0,0,1
--no-compensation 将简化产生的大于 1 不透明度截断到 1，
所有单元按不超过 1 绘制，供调试对比。
--aa-filter-size <px²> 抗锯齿训练模型的屏幕滤波，替代 0.3 px² 扩张，默认 0.1
--f-stop <N> 摄影光圈，例如 2.8/5.6/11，启用散焦，越小越模糊。
仅透视，默认禁用。
--focus-distance <n> 焦平面相机 Z，世界单位，默认到 target 距离。
仅透视，需配 f-stop。
--dof-samples <n> 每时刻光圈样本数，默认 32，越多伪影越少、开销越高。
与 motion-samples 组合时相乘。
--sensor-size <n> 世界单位垂直传感器高度，赋予光圈物理意义。
默认 0.024，单位米时为 35mm 全画幅。
单位分米用 0.24，毫米用 24。
--camera-pos-end <x,y,z> 结束位置，启用运动模糊，从初始到结束跨快门平均，默认禁用
--camera-target-end <x,y,z> 结束目标，默认初始，仅与 pos-end 配合
--camera-up-end <x,y,z> 结束向上，默认初始，仅与 pos-end 配合
--shutter <0..1> 围绕运动中点平均的比例，默认 0.5。
轨迹中表示每帧间隔比例，默认关闭，1 全间隔，0.5 为 180 度。
--motion-samples <n> 快门内均匀时刻的渲染平均数，默认 16，开销 N 倍。
过少且间隔运动超数像素时显示离散副本。
--camera-track <path> 动画序列：编辑器解压项目目录/document.json，
含 animTracks 的 settings.json，或
JSON { frameRate, frames: [{ position, target, fov, up }] }。
输出 <name>.NNNN.webp，替代 pos/target；目标也是焦点。
up 控倾斜，缺失用 camera-up；配 shutter 进行逐帧运动模糊。
--frames <a[-b]> 含两端的轨迹帧范围，默认全部