3DGS-PLY-3 调和器

将高斯平板PLY文件转换为由SPZ压缩的GLB内容的3D平板.

浏览器API,Node.js CLI,并用于将GraphDECO或KHR-native Gaussian Splating PLY文件转换为3D Tiles,或将PLY直接简化为更小的PLY的库. 浏览器工作在Web Worker中本地运行;现有的Node.js接口保留了内存预算的工作空间行为.

探索已转换的 三维平面示例

安装

npm install 3dgs-ply-3dtiles-converter

要求节点.js 18或更新.

国 际

3dgs-ply-3dtiles-converter [options] <input.ply> <output_dir>

示例

3dgs-ply-3dtiles-converter scene.ply out_tiles

您也可以不在全球安装而运行 :

npx 3dgs-ply-3dtiles-converter scene.ply out_tiles

从克隆寄存器 :

node ./bin/3dgs-ply-3dtiles-converter.js scene.ply out_tiles

自试:

3dgs-ply-3dtiles-converter --self-test out_self_test --no-open-inspector

简化 PLY

使用单独的 simplify 当只需要减少一个 PLY 时命令 :

3dgs-ply-3dtiles-converter simplify scene.ply scene_half.ply
3dgs-ply-3dtiles-converter simplify --target-count 250000 scene.ply scene_250k.ply

--ratio 默认为 0.5 ,并在无效和不透明过滤后应用。 使用其中之一 --ratio 或者说 --target-count而不是两个。 命令内部使用内存预算的KD分区,但不创建LOD,平板,GLB,或SPZ输出.

运行 3dgs-ply-3dtiles-converter simplify --help 用于指定选项列表.

默认情况下,转换将删除已有的 output_dir 在重建并打开在 3dtiles-inspector 成功后,我们继续 临时工作空间文件创建于 output_dir 除非 --tmp-dir 提供。 使用 --continue 从保存的已失效的工作空间恢复,并使用 --no-open-inspector 用于批量或CI运行.

产出

生成的产出包括:

• tileset.json - 紧凑的三维平板.
• build_summary.json - 紧凑转换元数据、计时、设置、检查站状态和放置字段.
• tiles/{level}/{x}.glb - SPZ压缩瓦片内容.

已生成 tileset.json 文件声明顶级 3DTILES_content_gltf 扩展元数据,使 CesiumJS 能够检测 KHR_gaussian_splatting 财务报告和审定财务报表 KHR_gaussian_splatting_compression_spz_2 内容。 每个 GLB 和平板电脑也记录 3dgs-ply-3dtiles-converter 及其作为生成元数据的软件包版本.

EXT 平板不透明查看器支持 Experimental

转换写入可选版本 2 EXT_splat_opacity 以上不透明合并的平板块默认数据 1. 它每个平板存储了2个字节的源不透明和2个字节的前起子形状比,加上应用的助推法和强度. 相容的取景者可以保留或减少这种助推而无需迭代大小重建. 使用 --no-ext-splat-opacity aPI 选项 extSplatOpacity: false 来禁用它.

SPZ有效载荷始终保持正常的覆盖助推力,其默认值仍然存在 0.75 不管有没有扩展。 不执行版本2的Cesium等查看器使SPZ倒置. 当前 3D- Tiles- 渲染器JS-3DGS- 涂料 读取第2版,并可以使用它的元数据直接重定覆盖尺度的目标.

延期细节草案见 EXT splat opacity.md (中文(简体) )。 。 。 .

源代码

转换器检查了PLY头评论,以获取坐标元数据. 带有地理空间或度量抵消元数据的文件作为源Z-up数据处理. 没有可用坐标元数据的文件保留默认 GraphDECO/COLMAP相机风格的基础.

解析源坐标系统写入 build_summary.json 作为 source_coordinate_system,具有可审计性的来源和理由字段.

节点.js API

const { convert, simplify } = require('3dgs-ply-3dtiles-converter');

(async () => {
  const result = await convert('data/scene.ply', './out/tileset', {
    memoryBudget: 4,
    sh: 2,
    openInspector: false,
  });

  console.log(result.outputDir, result.splatCount);

  const simplified = await simplify(
    'data/scene.ply',
    './out/scene_250k.ply',
    { targetCount: 250000, memoryBudget: 4 },
  );
  console.log(simplified.outputPath, simplified.splatCount);
})();

convert(inputPath, outputDir, options) 返回 :

节点.js库 API 接受与 CLI 相同的选项名称,使用 Came Case 字段. 譬如说, --memory-budget 4 地图到 { memoryBudget: 4 }。通过 silent: true 以压制转换器日志,或通过自定义 logger 与 line, (中文(简体) ), info, (中文(简体) ), ok, (中文(简体) ), warn,以及 error 方法。 。 .

simplify(inputPath, outputPath, options) 返回绝对输入/输出路径, sourceSplatCount,后过滤器 validSplatCount最终 splatCount,源/有效SH学位,并规范化 args两条路径必须使用 .ply 扩展并必须是不同的.

浏览器 API

从 npm 包中导入只使用无害环境管理的浏览器条目 。 它接受 File, (中文(简体) ), Blob, (中文(简体) ), ArrayBuffer,并输入阵列输入:

import {
  convert,
  simplify,
  BrowserConversionError,
} from '3dgs-ply-3dtiles-converter/browser';

const controller = new AbortController();
const converted = await convert(
  selectedFile,
  { sh: 2, maxLeafLimit: 50000 },
  {
    signal: controller.signal,
    onProgress(event) {
      if (event.type === 'pipeline') {
        console.log(event.label, event.current, event.total);
      }
    },
  },
);

console.log(converted.outputName, converted.outputBytes, converted.result);
const downloadUrl = URL.createObjectURL(converted.blob);

const reduced = await simplify(selectedFile, { targetCount: 250000 });
console.log(reduced.blob, reduced.result.splatCount);

convert 返回 ZIP Blob 包含 tileset.json,SPZ压缩的GLB平板,以及 build_summary.json。 。 。 . simplify 返回二进制 PLY Blob双方决心 { blob, outputName, mimeType, outputBytes, result };下载或预览结果留待调用应用程序处理.

第三个论点接受 fileName, (中文(简体) ), signal,以及 onProgress进度报告输入字节,管道 current 编号 : total,日志消息,以及当前模拟工作空间的使用. AbortSignal 取消只能终止那个叫"工人"的电话。 Worker被捆绑入ESM浏览器条目,因此应用程序不需要复制Worker资产或配置其URL.

浏览器选项名称符合 Case Node.js API 子集 。 文件系统路径, memoryBudget, (中文(简体) ), tmpDir、检查器设置和日志对象。 简化接受 ratio 或者说 targetCount 它们是相互排斥的.

浏览器模式不使用OPFS,索引DB,磁盘后置的临时文件,也不使用上传. 它的内幕工作空间会扩大,直到工作完成或分配失败. 内存失败拒绝 BrowserConversionError 财务报告和审定财务报表 error.code === 'MEMORY_EXHAUSTED'。 。 。 .

为构建包的无害环境管理浏览器条目,其内置工作人从源检出:

npm run build:browser

生成的无害环境管理捆绑和源映射被 Git 忽略,并在 npm pack 编号 : npm publish。浏览器可用的堆积通常低于机器安装的RAM;峰值使用包括输入,解析字段,分区/LOD数据,生成的内容,以及最终输出 Blob。 。 。 .

选项

使用 --help 以打印 CLI 使用文本.

简化选项

独立的 PLY 命令只接受与输入解码,简化,分区和 PLY 输出相关的选项 :

LOD、几何-更硬化、变相、色相空间、检查员、EXT不透明以及自我测试等选项,被 simplify 命令.

--sh 是一个上限。 如果输入包含较低的SH度,则 转换器保持输入度,而不是合成缺失系数. 譬如说, --sh 0 忽略每个 f_rest_* 值和发射SPZ/GLB 内容为 SH 度 0.

高斯平板电脑简化

转换器为母体LOD瓦片构建了简化的高斯克平板内容,而不只是抛出点. 下行-细瓦保持了稳定的覆盖和可识别的结构相距相距,同时加载的数据较少.

关于完整的简化算法,见 平面简化.md。 。 。 .

使用 --sampling-rate-per-level 控制父母的LOD减少的程度。 使用 --coverage-boost-scale 以调整简化平板的视觉覆盖,或设置为 0 以禁用助推器。 实验 EXT_splat_opacity 默认启用输出; 使用 --no-ext-splat-opacity 当它不被想要.

独立 simplify 命令使用同样准确的 Voxel 简化字。 它将一个全球目标分配给了内存大小的KD子树上,只有在儿童结果仍然超过父母预算时才会向上减少。 每个精确的通过保留了至少一半的当前输入,其未启动的输出成为下个通过输入;例如,25%运行为50%再运行为50%,而30%运行为50%再运行为60%. 只在流出最后的二进制小endian PLY时应用了覆盖助推法,因此被增强的显示平面从未反馈回后期合并.

高斯平板简化后的总体比较.


详细比较显示本地结构保存.

倾斜和性能

转换器分区会将平板输入到可适应的平板树上并给浏览器取景者写出LOD平板. 使用 --aabb 用于轴相匹配的边框或 --obb 为方向界限.

大型的PLY文件可以将工作数据溢入临时工作空间. 工作空间默认为 output_dir/.tmp-ply-partitions; 与 --tmp-dir <dir>,它被创建为 <dir>/.tmp-ply-partitions。成功转换可以删除工作空间。 转换失败后保留它, 以便稍后运行 --continue 同样的临时目录可以重新使用检查站.

独立的简化使用单独的 .tmp-ply-simplify/<output-hash> 输出目录下的工作空间或 --tmp-dir。它会用临时名称在目的地旁边写最后的 PLY ,并且只有在完整文件写完后才替换目的地。 未能保留检查站并去除未完成的分阶段产出; --continue 再利用相容扫描,KD分区和还原工作,而指纹不匹配则重建. 成功移除了简化的工作空间.

--memory-budget 控制转换器应规划多少内存。 较大的预算可以提高大数据集的吞吐量.

几何错误

转换器写 geometricError 值,所以3D平面取景器可以决定从粗瓦到细瓦的精度. 典型高斯平板数据集自动选择默认值.

当默认的改进行为需要调试时使用这些选项:

• --lod-multiplier 选择父子关系改进曲线。 更大的数值使观看者从更远的地方请求详细的儿童牌. 使用诸如 low, (中文(简体) ), medium, (中文(简体) ), high,或 max 当您想要转换器选择一个数据集大小-认识曲线时.
• --geometric-error-layer-multiplier 调整已选择的曲线. 1 基准曲线保持不变;值高于 1 增加粗度误差,并增加以下值 1 减少它们。 使用它进行微调,而不修改选中的 --lod-multiplier 模式.
• --geometric-error-scale 应用全局人工调整.
• --min-geometric-error 设定最深排放水平的目标.

如果根变换包含尺度,转换器会自动调整所发射的几何误差.

全球安置

当平板电脑需要地理空间布置时,使用一个布置选项:

• --coordinate "[lat,long,height]" 或者说 { coordinate: [lat, long, height] } 将平板原产地固定在WGS84坐标上并生成标准的ENU变换.
• --transform "[...16 numbers...]" 或者说 { transform: [...] } 写入 tileset.root.transform 直接说.

transform 在最后3D平地平地坐标中解释,而不是原始 glTF Y-up 节点空间. 如果根变换包含比例,转换器会调整所发射的 geometricError 自动值。 标准 --coordinate 放置不会改变几何错误.

实例:

3dgs-ply-3dtiles-converter scene.ply out_tiles --coordinate "[31.2304,121.4737,30]" --no-open-inspector

await convert('scene.ply', './out_tiles', {
  coordinate: [31.2304, 121.4737, 30],
  openInspector: false,
});

检查员

默认情况下,一个成功的转换打开了生成的平板 3dtiles 检查器。用它来检查加载行为,调整放置和几何-误差设置,裁剪高斯平板,并保存所支持的编辑。 禁用检查器 --no-open-inspector 或者说 openInspector: false 用于批量运行.

裁剪高斯平板,单击 Draw Region 在检查官,然后拖 周围的花板,你想删除。 调整手柄,单击 Confirm,然后单击 Save 以更新受影响的平板文件.

错误

转换和简化失败 ConversionError。常见的原因包括选项值无效,缺少输入/输出路径,不支持的 PRY 字段,或缺少所需的 Gaussian PRY 属性.

引用

如果您在研究中使用该项目,请说明:

@software{liu2026_3dgs_ply_3dtiles_converter,
  author = {Liu, Yuzhi},
  title = {{3DGS-PLY-3DTiles-Converter}},
  version = {0.6.5},
  year = {2026},
  url = {https://github.com/WilliamLiu-1997/3DGS-PLY-3DTiles-Converter}
}