0.5.8

Browser API, Node.js CLI, and library for converting GraphDECO or KHR-native Gaussian Splatting PLY files into 3D Tiles, or simplifying a PLY directly into a smaller PLY. Browser work runs locally in a Web Worker; the existing Node.js interfaces retain their memory-budgeted workspace behavior.

Explore converted 3D Tiles examples ↗

Install

npm install 3dgs-ply-3dtiles-converter

Requires Node.js 18 or newer.

CLI

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

Example:

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

You can also run it without installing globally:

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

From a cloned repository:

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

Self-test:

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

Simplify a PLY

Use the separate simplify command when only one reduced PLY is needed:

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

--ratio defaults to 0.5 and is applied after invalid-splat and opacity filtering. Use either --ratio or --target-count, not both. The command uses memory-budgeted KD partitions internally, but does not create LODs, tiles, GLB, or SPZ output.

Run 3dgs-ply-3dtiles-converter simplify --help for the dedicated option list.

By default, conversion removes the existing output_dir before rebuilding and opens the generated tileset in 3dtiles-inspector after success. Temporary workspace files are created under output_dir unless --tmp-dir is provided. Use --continue to resume from a preserved failed workspace, and use --no-open-inspector for batch or CI runs.

Output

Generated output includes:

• tileset.json - compact explicit 3D Tiles tileset.
• build_summary.json - compact conversion metadata, timings, settings, checkpoint state, and placement fields.
• tiles/{level}/{x}.glb - SPZ-compressed tile content.

Generated tileset.json files declare top-level 3DTILES_content_gltf extension metadata so CesiumJS can detect KHR_gaussian_splatting and KHR_gaussian_splatting_compression_spz_2 content. Every GLB and tileset also records 3dgs-ply-3dtiles-converter and its package version as generator metadata.

EXT Splat Opacity Viewer Support Experimental

Conversion writes optional version 2 EXT_splat_opacity data by default for splats with merged opacity above 1. It stores two bytes of source opacity and two bytes of pre-boost shape ratio per splat, plus the applied boost method and strength. Compatible viewers can retain or reduce that boost without iterative size reconstruction. Use --no-ext-splat-opacity or API option extSplatOpacity: false to disable it.

The SPZ payload always keeps the normal coverage boost, whose default remains 0.75 with or without the extension. Viewers such as Cesium that do not implement version 2 render that SPZ fallback. The current 3D-Tiles-RendererJS-3DGS-Plugin reads version 2 and can use its metadata to retarget the coverage scales directly.

For the draft extension details, see EXT_splat_opacity.md.

Source Coordinates

The converter inspects PLY header comments for coordinate metadata. Files with geospatial or metric offset metadata are treated as source Z-up data. Files without usable coordinate metadata keep the default GraphDECO/COLMAP camera-style basis.

The resolved source coordinate system is written to build_summary.json as source_coordinate_system, with source and reason fields for auditability.

Node.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) returns:

The Node.js library API accepts the same option names as the CLI, using camelCase fields. For example, --memory-budget 4 maps to { memoryBudget: 4 }. Pass silent: true to suppress converter logs, or pass a custom logger with line, info, ok, warn, and error methods.

simplify(inputPath, outputPath, options) returns absolute input/output paths, sourceSplatCount, the post-filter validSplatCount, final splatCount, source/effective SH degree, and normalized args. Both paths must use the .ply extension and must be different.

Browser API

Import the ESM-only browser entry from the npm package. It accepts File, Blob, ArrayBuffer, and typed-array inputs:

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 returns a ZIP Blob containing tileset.json, SPZ-compressed GLB tiles, and build_summary.json. simplify returns a binary PLY Blob. Both resolve to { blob, outputName, mimeType, outputBytes, result }; downloading or previewing the result is left to the calling application.

The third argument accepts fileName, signal, and onProgress. Progress events report input bytes, pipeline current / total, log messages, and current in-memory workspace usage. AbortSignal cancellation terminates only that call's Worker. The Worker is bundled into the ESM browser entry, so applications do not need to copy a Worker asset or configure its URL.

Browser option names match the camelCase Node.js API subset. Filesystem paths, memoryBudget, tmpDir, checkpoint controls, Inspector settings, and logger objects are not available. Simplification accepts ratio or targetCount directly; they are mutually exclusive.

Browser mode does not use OPFS, IndexedDB, disk-backed temporary files, or uploads. Its in-memory workspace grows until the job completes or allocation fails. Memory failures reject with BrowserConversionError and error.code === 'MEMORY_EXHAUSTED'.

To build the package's ESM browser entry with its inline Worker from a source checkout:

npm run build:browser

The generated ESM bundle and source map are ignored by Git and produced automatically during npm pack / npm publish. The browser's usable heap is usually lower than the machine's installed RAM; peak usage includes the input, parsed fields, partition/LOD data, generated content, and final output Blob.

Options

Use --help to print the CLI usage text.

Simplify options

The standalone PLY command accepts only options relevant to input decoding, simplification, partitioning, and PLY output:

LOD, geometric-error, transform, color-space, inspector, EXT opacity, and self-test options are intentionally rejected by the simplify command.

--sh is an upper limit. If the input contains a lower SH degree, the converter keeps the input degree instead of synthesizing missing coefficients. For example, --sh 0 ignores every f_rest_* value and emits SPZ/GLB content with SH degree 0.

Gaussian Splats Simplify

The converter builds simplified Gaussian splat content for parent LOD tiles instead of only dropping points. Lower-detail tiles keep stable coverage and recognizable structure at distance while loading less data.

For the complete simplification algorithm, see Splat-Simplify.md.

Use --sampling-rate-per-level to control how aggressively parent LODs are reduced. Use --coverage-boost-scale to adjust visual coverage for simplified splats, or set it to 0 to disable that boost. Experimental EXT_splat_opacity output is enabled by default; use --no-ext-splat-opacity when it is not wanted.

The standalone simplify command uses the same exact voxel simplifier. It distributes one global target across memory-sized KD subtrees and reduces upward only when child results still exceed a parent budget. Each exact pass retains at least half of its current input, and its unboosted output becomes the next pass's input; for example, 25% runs as 50% then 50%, while 30% runs as 50% then 60%. Coverage boost is applied only while streaming the final binary little-endian PLY, so boosted display scales never feed back into later merges.

Tiling and Performance

The converter partitions input splats into an adaptive tile tree and writes LOD tiles for browser viewers. Use --aabb for axis-aligned bounds or --obb for oriented bounds.

Large PLY files can spill working data into a temporary workspace. The workspace defaults to output_dir/.tmp-ply-partitions; with --tmp-dir <dir>, it is created as <dir>/.tmp-ply-partitions. Successful conversions remove the workspace. Failed conversions preserve it so a later run with --continue and the same temp directory can reuse checkpoints.

Standalone simplification uses a separate .tmp-ply-simplify/<output-hash> workspace under the output directory or --tmp-dir. It writes the final PLY beside the destination under a temporary name and replaces the destination only after the complete file has been written. Failures preserve the checkpoint and remove the incomplete staged output; --continue reuses compatible scan, KD partition, and reduction work, while a fingerprint mismatch rebuilds it. Success removes the simplify workspace.

--memory-budget controls how much memory the converter should plan around. Larger budgets can improve throughput on large datasets.

Geometric Error

The converter writes geometricError values so 3D Tiles viewers can decide when to refine from coarse tiles to detailed tiles. Defaults are chosen automatically for typical Gaussian splat datasets.

Use these options when the default refinement behavior needs tuning:

• --lod-multiplier chooses the base parent-child refinement curve. Larger numeric values make viewers request detailed child tiles from farther away. Use presets such as low, medium, high, or max when you want the converter to pick a dataset-size-aware curve.
• --geometric-error-layer-multiplier adjusts the already chosen curve. 1 keeps the base curve unchanged; values above 1 increase coarse-level errors, and values below 1 reduce them. Use it for fine tuning without changing the selected --lod-multiplier mode.
• --geometric-error-scale applies a global manual adjustment.
• --min-geometric-error sets the deepest emitted level's target.

If the root transform contains scale, the converter adjusts emitted geometric errors automatically.

Global Placement

When the tileset needs geospatial placement, use one placement option:

• --coordinate "[lat,long,height]" or { coordinate: [lat, long, height] } anchors the tileset origin at a WGS84 coordinate and generates a standard ENU transform.
• --transform "[...16 numbers...]" or { transform: [...] } writes tileset.root.transform directly.

transform is interpreted in final 3D Tiles tile coordinates, not raw glTF Y-up node space. If the root transform contains scale, the converter adjusts emitted geometricError values automatically. Standard --coordinate placement does not change geometric error.

Examples:

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,
});

Inspector

By default, a successful conversion opens the generated tileset in 3dtiles-inspector. Use it to inspect loading behavior, adjust placement and geometric-error settings, crop Gaussian splats, and save supported edits. Disable the inspector with --no-open-inspector or openInspector: false for batch runs.

To crop Gaussian splats, click Draw Region in the inspector, then drag around the splats you want to remove. Adjust the handles, click Confirm, then click Save to update the affected tileset files.

Errors

Conversion and simplification failures throw ConversionError. Common causes include invalid option values, missing input/output paths, unsupported PLY fields, or missing required Gaussian PLY properties.

Citation

If you use this project in your research, please cite:

@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}
}