# 3dgs-ply-3dtiles-converter 中文文档 规范地址：https://npmcn.com/package/3dgs-ply-3dtiles-converter/ 版本：0\.6\.5 npm 元数据更新时间：2026-08-31T03:01:01.761Z 中文译文更新时间：2026-11-06T20:19:30.790Z 软件包许可：Apache-2\.0 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/3dgs-ply-3dtiles-converter 原文对照：https://npmcn.com/package/3dgs-ply-3dtiles-converter/?lang=original 项目主页：https://github.com/WilliamLiu-1997/3DGS-PLY-3DTiles-Converter#readme 源码仓库：https://github.com/WilliamLiu-1997/3DGS-PLY-3DTiles-Converter ## 关键信息（来自 npm 元数据） - 包体积（解压后）：4.2 MB，84 个文件 - 模块格式：ESM + CJS - TypeScript 类型：包内自带 - Node.js 要求：\>=18\.0\.0 - 运行依赖：1 个 - 首次发布：2026-04-16T05:08:01.251Z - 最新版本发布：2026-08-31T03:01:01.377Z - 近 30 天下载量：2378（2026-10-04 至 2026-11-02，npm 官方下载统计） - 已发布版本数：52（近 12 个月 52 个） ## 中文简介 将高斯平板PLY文件转换为3D平板或简化为更小的PLY文件. ## 安装 ```sh npm install 3dgs-ply-3dtiles-converter ``` 也可以使用：`pnpm add 3dgs-ply-3dtiles-converter`、`yarn add 3dgs-ply-3dtiles-converter`、`bun add 3dgs-ply-3dtiles-converter` ## README # 3DGS-PLY-3 调和器 **将高斯平板PLY文件转换为由SPZ压缩的GLB内容的3D平板.** [![npm version](https://img.shields.io/npm/v/3dgs-ply-3dtiles-converter)](https://www.npmjs.com/package/3dgs-ply-3dtiles-converter) [![CI](https://github.com/WilliamLiu-1997/3DGS-PLY-3DTiles-Converter/actions/workflows/ci.yml/badge.svg)](https://github.com/WilliamLiu-1997/3DGS-PLY-3DTiles-Converter/actions/workflows/ci.yml) [![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](https://npmcn.com/package/3dgs-ply-3dtiles-converter/LICENSE) ![3DGS-PLY-3DTiles-Converter](https://raw.githubusercontent.com/WilliamLiu-1997/3DGS-PLY-3DTiles-Converter/main/3DGS-PLY-3DTiles-Converter.png) 浏览器API,Node.js CLI,并用于将GraphDECO或KHR-native Gaussian Splating PLY文件转换为3D Tiles,或将PLY直接简化为更小的PLY的库. 浏览器工作在Web Worker中本地运行;现有的Node.js接口保留了内存预算的工作空间行为. **[探索已转换的 三维平面示例](https://3d-tiles-rendererjs-3dgs-plugin.vercel.app/)** ## 安装 ```bash npm install 3dgs-ply-3dtiles-converter ``` 要求节点.js 18或更新. ## 国 际 ```bash 3dgs-ply-3dtiles-converter [options] ``` 示例 ```bash 3dgs-ply-3dtiles-converter scene.ply out_tiles ``` 您也可以不在全球安装而运行 : ```bash npx 3dgs-ply-3dtiles-converter scene.ply out_tiles ``` 从克隆寄存器 : ```bash node ./bin/3dgs-ply-3dtiles-converter.js scene.ply out_tiles ``` 自试: ```bash 3dgs-ply-3dtiles-converter --self-test out_self_test --no-open-inspector ``` ### 简化 PLY 使用单独的 `simplify` 当只需要减少一个 PLY 时命令 : ```bash 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- 涂料](https://github.com/WilliamLiu-1997/3D-Tiles-RendererJS-3DGS-Plugin) 读取第2版,并可以使用它的元数据直接重定覆盖尺度的目标. 延期细节草案见 [EXT splat opacity.md (中文(简体) )](https://npmcn.com/package/3dgs-ply-3dtiles-converter/EXT_splat_opacity.md)。 。 。 . ## 源代码 转换器检查了PLY头评论,以获取坐标元数据. 带有地理空间或度量抵消元数据的文件作为源Z-up数据处理. 没有可用坐标元数据的文件保留默认 GraphDECO/COLMAP相机风格的基础. 解析源坐标系统写入 `build_summary.json` 作为 `source_coordinate_system`,具有可审计性的来源和理由字段. ## 节点.js API ```js 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)` 返回 : | 外地 | 说明 | | --- | --- | | `inputPath` | 绝对输入 PLY 路径 . | | `outputDir` | 绝对输出目录 . | | `splatCount` | 粉碎了的花板计数. | | `sourceShDegree` | 输入 PLY 中存在的球-相声学位. | | `shDegree` | 在输出中保留有效的球-相声分级. | | `args` | 常态化转换参数. 若为 `coordinate` 提供, `args.transform` 包含生成的 ENU 根变换. | 节点.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`,并输入阵列输入: ```js 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'`。 。 。 . 为构建包的无害环境管理浏览器条目,其内置工作人从源检出: ```bash npm run build:browser ``` 生成的无害环境管理捆绑和源映射被 Git 忽略,并在 `npm pack` 编号 : `npm publish`。浏览器可用的堆积通常低于机器安装的RAM;峰值使用包括输入,解析字段,分区/LOD数据,生成的内容,以及最终输出 `Blob`。 。 。 . ## 选项 | 国 际 | API 密码 | 默认 | 页:1 | | --- | --- | --- | --- | | `--input-convention ` | `inputConvention` | `graphdeco` | 使用 `graphdeco` 或者说 `khr_native` 源数据. | | `--opacity-filter ` | `opacityFilter` | `0.05` | 丢弃非常透明的花板; `0` 禁用过滤. | | `--linear-scale-input` | `linearScaleInput` | `false` | 将输入缩放字段视为线性值. | | `--color-space ` | `colorSpace` | `srgb_rec709_​display` | 使用 `lin_rec709_display` 或者说 `srgb_rec709_display`。 。 。 . | | `--sh <0|1|2|3>` | `sh` | `3` | 在输入解码、LOD简化和输出过程中保留限制SH; `0` 只保留 SH0 (`f_dc_*`) (中文(简体) ). | | `--max-depth ` | `maxDepth` | `auto` | 限制排放的LOD深度. | | `--max-leaf-limit ` | `maxLeafLimit` | `50000` | 控制最深层的瓷砖预算. | | `--min-leaf-limit ` | `minLeafLimit` | `auto` | 当普通的瓦片分拆可以停止时的控制. | | `--coverage-boost-scale ` | `coverageBoostScale` | `0.75` | 调整简化平板的覆盖范围; `0` 禁用助推器. | | `--ext-splat-opacity` 编号 : `--no-ext-splat-opacity` | `extSplatOpacity` | `true` | 写入可选 v2 源不规则和覆盖-boost 元数据 . | | `--min-geometric-error ` | `minGeometricError` | `null` | 设定最深射出几何- error 目标 . | | `--geometric-error-layer-multiplier ` | `geometricError​LayerMultiplier` | `1.0` | 选取基 LOD 曲线后,调整后粗度误差. | | `--geometric-error-scale ` | `geometricErrorScale` | `1.0` | 应用全球几何-误差调整. | | `--lod-multiplier ` | `lodMultiplier` | `high` | 选择 LOD 级别之间的父子几何- error 阶梯 . | | `--transform ` | `transform` | `null` | 写作 `tileset.root.transform` 直接说. | | `--coordinate ` | `coordinate` | `null` | 将平板放在WGS84坐标上. | | `--sampling-rate-per-level ` | `samplingRate​PerLevel` | `0.5` | 控制母 LOD 保存多少内容 . | | `--obb` 或者说 `--aabb` | `orientedBounding​Boxes` | `false` | 选择面向或轴相接的平板边框. | | `--memory-budget ` | `memoryBudget` | `4` | 设置近似转换内存预算 . | | `--tmp-dir ` | `tmpDir` | `output_dir` | 临时工作空间文件的根目录 . | | `--open-inspector` 或者说 `--no-open-inspector` | `openInspector` | `true` | 打开生成的平板 `3dtiles-inspector` 成功之后,我们继续. | | `--self-test-count ` | `selfTestCount` | `1000000` | 使用时的合成花板数量 `--self-test`。 。 。 . | | `--clean` 或者说 `--continue` | `clean` | `true` | 保留检查站并恢复失败运行 `--continue` 已使用. | 使用 `--help` 以打印 CLI 使用文本. ### 简化选项 独立的 PLY 命令只接受与输入解码,简化,分区和 PLY 输出相关的选项 : | 国 际 | API 密码 | 默认 | 页:1 | | --- | --- | --- | --- | | `--ratio <0..1>` | `ratio` | `0.5` | 过滤后最后保留比例 . | | `--target-count ` | `targetCount` | `null` | 准确的最终目标;相互排斥 `ratio`。 。 。 . | | `--input-convention ` | `inputConvention` | `graphdeco` | 产出PLY遵循同样的不透明度与四角公约. | | `--opacity-filter ` | `opacityFilter` | `0.05` | 解出目标计数前应用. | | `--linear-scale-input` | `linearScaleInput` | `false` | 阅读和写作 `scale_*` 作为线性值. | | `--sh <0|1|2|3>` | `sh` | `3` | 帽子保留并释放了SH数据. | | `--coverage-boost-scale ` | `coverageBoostScale` | `0.75` | 仅产出覆盖调整; `0` 关闭它. | | `--obb` 或者说 `--aabb` | `orientedBoundingBoxes` | `false` | 控制 KD 分区方向 . | | `--memory-budget ` | `memoryBudget` | `4` | 大小分区,缓冲,工人,以及活动任务. | | `--tmp-dir ` | `tmpDir` | 输出目录 | 孤立工作空间的根 . | | `--clean` 或者说 `--continue` | `clean` | `true` | 开始清理或恢复匹配的检查站. | LOD、几何-更硬化、变相、色相空间、检查员、EXT不透明以及自我测试等选项,被 `simplify` 命令. `--sh` 是一个上限。 如果输入包含较低的SH度,则 转换器保持输入度,而不是合成缺失系数. 譬如说, `--sh 0` 忽略每个 `f_rest_*` 值和发射SPZ/GLB 内容为 SH 度 0. ## 高斯平板电脑简化 转换器为母体LOD瓦片构建了简化的高斯克平板内容,而不只是抛出点. 下行-细瓦保持了稳定的覆盖和可识别的结构相距相距,同时加载的数据较少. 关于完整的简化算法,见 [平面简化.md](https://npmcn.com/package/3dgs-ply-3dtiles-converter/Splat-Simplify.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时应用了覆盖助推法,因此被增强的显示平面从未反馈回后期合并. ![Gaussian splats simplification overall comparison](https://raw.githubusercontent.com/WilliamLiu-1997/3DGS-PLY-3DTiles-Converter/main/overall-compare.png) _高斯平板简化后的总体比较._ ![Gaussian splats simplification detail comparison](https://raw.githubusercontent.com/WilliamLiu-1997/3DGS-PLY-3DTiles-Converter/main/detail-compare.png) _详细比较显示本地结构保存._ ## 倾斜和性能 转换器分区会将平板输入到可适应的平板树上并给浏览器取景者写出LOD平板. 使用 `--aabb` 用于轴相匹配的边框或 `--obb` 为方向界限. 大型的PLY文件可以将工作数据溢入临时工作空间. 工作空间默认为 `output_dir/.tmp-ply-partitions`; 与 `--tmp-dir `,它被创建为 `/.tmp-ply-partitions`。成功转换可以删除工作空间。 转换失败后保留它, 以便稍后运行 `--continue` 同样的临时目录可以重新使用检查站. 独立的简化使用单独的 `.tmp-ply-simplify/` 输出目录下的工作空间或 `--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` 放置不会改变几何错误. 实例: ```bash 3dgs-ply-3dtiles-converter scene.ply out_tiles --coordinate "[31.2304,121.4737,30]" --no-open-inspector ``` ```js await convert('scene.ply', './out_tiles', { coordinate: [31.2304, 121.4737, 30], openInspector: false, }); ``` ### 检查员 默认情况下,一个成功的转换打开了生成的平板 [3dtiles 检查器](https://github.com/WilliamLiu-1997/3DTiles-Inspector)。用它来检查加载行为,调整放置和几何-误差设置,裁剪高斯平板,并保存所支持的编辑。 禁用检查器 `--no-open-inspector` 或者说 `openInspector: false` 用于批量运行. ![3DTiles-Inspector](https://raw.githubusercontent.com/WilliamLiu-1997/3DGS-PLY-3DTiles-Converter/main/3DTiles-Inspector.png) 裁剪高斯平板,单击 `Draw Region` 在检查官,然后拖 周围的花板,你想删除。 调整手柄,单击 `Confirm`,然后单击 `Save` 以更新受影响的平板文件. ![3DTiles-Inspector Crop Regions](https://raw.githubusercontent.com/WilliamLiu-1997/3DGS-PLY-3DTiles-Converter/main/region.png) ## 错误 转换和简化失败 `ConversionError`。常见的原因包括选项值无效,缺少输入/输出路径,不支持的 PRY 字段,或缺少所需的 Gaussian PRY 属性. ## 引用 如果您在研究中使用该项目,请说明: ```bibtex @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} } ``` ## 常见问题 ### 3dgs-ply-3dtiles-converter 是什么？ 将高斯平板PLY文件转换为3D平板或简化为更小的PLY文件\. ### 如何安装 3dgs-ply-3dtiles-converter？ 在项目目录运行 npm install 3dgs-ply-3dtiles-converter，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 3dgs-ply-3dtiles-converter，可以用 npx 3dgs-ply-3dtiles-converter 直接运行。 ### 3dgs-ply-3dtiles-converter 支持 TypeScript 吗？ 支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。 ### 3dgs-ply-3dtiles-converter 支持 ESM 还是 CommonJS？ 同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。 ### 3dgs-ply-3dtiles-converter 需要什么版本的 Node\.js？ package\.json 的 engines 字段要求 Node\.js \>=18\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。 ### 3dgs-ply-3dtiles-converter 可以商用吗？ 3dgs-ply-3dtiles-converter 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。 ### 3dgs-ply-3dtiles-converter 的下载量有多少？ 根据 npm 官方下载统计，3dgs-ply-3dtiles-converter 在 2026/10/04 – 2026/11/02 这 30 天内被下载 2,378 次，日均约 79 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### 3dgs-ply-3dtiles-converter 还在维护吗？ 最新版本 0\.6\.5 发布于 2026/08/31（2 个月前）；至今共发布 52 个版本，其中过去 12 个月发布了 52 个；首次发布于 2026/04/16。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。