splat-transform

背景

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

环境需求

• Node.js >= 20.19.0
• Windows: Windows 22H2+，x86_64，D3D12 或 Vulkan 兼容显卡。需要 GPU 功能时，建议使用独立显卡。
• Linux: x86_64，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[] }>; // 局部变换的列表
}

使用方式

如何安装

npm install @manycore/aholo-splat-transform -g

CLI 模式

splat-transform create <input> <output> # 转换3DGS格式
splat-transform lod:auto --ratio <ratio> <input> <output> # 简化3DGS到指定比例 ratio [0-1]
splat-transform lod:auto-chunk --type <type:ply,spz,splat,sog> --max-chunk-counts <count> <input> <output> # 生成可以被调度的多级别lod数据，--max-chunk-counts 最大分块大小

pipeline 模式(推荐)

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

                
Array<{
    precision: number,
    scaleBoost: number
}>
                
            

                
[
    { precision: 1.0, scaleBoost: 1 },
    { precision: 0.5, scaleBoost: 1 },
    { precision: 0.25, scaleBoost: 1 },
    { precision: 0.05, scaleBoost: 1.01 },
    { precision: 0.01, scaleBoost: 1.02 },
]
                
            

                
{
    minCorner: [number, number, number],
    maxCorner: [number, number, number]
}
                
            

                
{
    minCorner: [-100, -100, -100],
    maxCorner: [100, 100, 100]
}
                
            

                
{
    height: number,
    radius: number
}
                
            

                
{
    x: number,
    y: number,
    z: number
}
                
            

使用样例

• 把 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
                  }
              }
          }
      ]
  }

注意事项

• 当需要生成SOG或者使用GPU生成Voxel时，推荐使用性能较好的独立显卡。当转换比较大的数据到SOG时，需要10GB以上显存。
• 当生成chunk-lod时(既使用AutoChunkLod或者lod:auto-chunk生成)，推荐使用spz输出，在分块和多级lod后，会存在数据量很少数据量比较小的块，对于这些块sog压缩率表现不如spz，也可以配置forceSpzFormatThreshold来控制小于某个数量的块强制使用spz
• chunk-lod生成过程中对资源消耗比较大，推荐使用配置比较高的机器配置。对于大型数据推荐内存 >= 32GB, CPU核心数>=16(含超线程)。当无法直接生成时，可以先进行简单的块分割再生成，之后合并lod-meta.json，合并可以使用来自@manycore/aholo-splat-dev-server@>=1.0.1的merge-lod指令。