splat-transform

背景

splat-transform 是面向 Aholo Viewer 的 3DGS 处理工具，用于格式转换、数据简化、LOD 生成和体素碰撞体生成。

环境需求

• Node.js >= 20.19.0
• Windows: Windows 22H2+，D3D12 或 Vulkan 兼容显卡。需要 GPU 功能时，建议使用独立显卡。
• Linux: glibc >= 2.34，libstdc++ >= 3.4.30，Vulkan 兼容显卡。需要 GPU 功能时，建议使用独立显卡。
• macOS: 暂不支持。

需要 GPU 的功能

• SOG 生成。
• Voxel 生成，且 backend 设置为 gpu。

格式说明

输入格式

• ply
• sog
• ksplat
• splat
• spz
• lcc
• compressed.ply，即 supersplat 压缩 ply
• meta.json，即 sog 未打包 meta 数据

输出格式

• ply
• spz
• uspz，即未 gzip 的 spz
• splat
• sog

modify 格式说明

{
  isRowMatrix: boolean; // 是否使用行矩阵，默认 true
  transform: number[]; // model 级别的变换
  deletedIndices: number[]; // 删除下标，bitmap 形式
  indicesTransform: Array<{ indices: number[]; transform: number[] }>; // 局部变换列表
}

使用方式

CLI 模式

pnpm splat-transform create <input> <output>
pnpm splat-transform lod:auto --ratio <ratio> <input> <output>
pnpm splat-transform lod:auto-chunk --type <type:ply,spz,splat,sog> --max-chunk-counts <count> <input> <output>

pipeline 模式（推荐）

pnpm splat-transform pipeline.json

pipeline 描述文件（pipeline.json）

{
  "version": 1,
  "tasks": [
    {
      "id": "0",
      "type": "Read",
      "config": { "inputs": ["a.ply"], "output": "cache0" }
    },
    {
      "id": "1",
      "type": "AutoChunkLod",
      "config": { "input": "cache0", "output": "cache0", "type": "spz" }
    },
    {
      "id": "2",
      "type": "Write",
      "config": { "input": "cache0", "output": "a-lod" }
    }
  ]
}

Task

名称	功能	关键参数
Read	读取多个 Gaussian Splatting 文件，并合并为一个 SplatData 对象。	inputs: string[]，output: string
Write	将 SplatData 按指定格式写入磁盘。	input: string，output: string，compressLevel?: number
Modify	根据 modify JSON 修改 SplatData。	input: string，output: string，modifyPaths?: string[]
AutoLod	生成融合高斯结果。	input: string，output: string，counts?: number，ratio?: number
AutoChunkLod	生成分块融合高斯结果，需要结合 LOD 调度模块使用。	input: string，output: string，type: string，maxChunkCounts?: number，levels?: Array<{ precision: number; scaleBoost: number }>
Voxel	生成体素碰撞体。	input: string，output: string，voxelResolution?: number，opacityCutoff?: number，`backend?: “cpu"

AutoChunkLod 的 type 应使用输出格式中的一种。低数量 chunk 使用 sog 时压缩率可能较差，可通过 forceSpzFormatThreshold 强制小 chunk 输出为 spz，实际接入中常见起点为 200000。

Voxel 支持 box、navCapsule 和 navSeed 等范围控制参数。离群点会显著影响体素化性能，建议按业务场景限制体素生成范围。

使用样例

将 a.ply 和 b.ply 应用修改后转换为 c.spz：

{
  "version": 1,
  "tasks": [
    {
      "id": "0",
      "type": "Read",
      "config": { "inputs": ["a.ply", "b.ply"], "output": "cache0" }
    },
    {
      "id": "1",
      "type": "Modify",
      "config": { "input": "cache0", "output": "cache0", "modifyPaths": ["a.json", "b.json"] }
    },
    {
      "id": "2",
      "type": "Write",
      "config": { "input": "cache0", "output": "c.spz" }
    }
  ]
}

对 a.ply 应用修改后生成 auto chunk LOD：

{
  "version": 1,
  "tasks": [
    {
      "id": "0",
      "type": "Read",
      "config": { "inputs": ["a.ply"], "output": "cache0" }
    },
    {
      "id": "1",
      "type": "Modify",
      "config": { "input": "cache0", "output": "cache0", "modifyPaths": ["a.json"] }
    },
    {
      "id": "2",
      "type": "AutoChunkLod",
      "config": { "input": "cache0", "output": "cache0", "type": "spz" }
    },
    {
      "id": "3",
      "type": "Write",
      "config": { "input": "cache0", "output": "a-lod" }
    }
  ]
}

生成体素碰撞体：

{
  "version": 1,
  "tasks": [
    {
      "id": "0",
      "type": "Read",
      "config": { "inputs": ["input.ply"], "output": "cache0" }
    },
    {
      "id": "1",
      "type": "Voxel",
      "config": {
        "input": "cache0",
        "output": "voxel-output",
        "voxelResolution": 0.05,
        "opacityCutoff": 0.1,
        "navCapsule": { "height": 1.4, "radius": 0.2 },
        "navSeed": { "x": 0, "y": 0, "z": 0 }
      }
    }
  ]
}