Convert 3D Gaussian Splat scene files (.ply or .spz) into Pixar USD artifacts for Omniverse and USD-based pipelines. Use when documenting, invoking, or troubleshooting gsplat-to-USD conversion workflows.
Convert 3D Gaussian Splat scene files (.ply or .spz) into Pixar USD artifacts for Omniverse and USD-based pipelines. Use when documenting, invoking, or troubleshooting gsplat-to-USD conversion workflows.
license
Apache-2.0 AND CC-BY-4.0
version
0.1.0
author
NVIDIA OpenUSD
compatibility
Requires Python package install from ./source/python. USD writing requires ./source/python[usd] and compatible OpenUSD runtime. --generateScales requires SciPy. OpenUSD 26.03+ is preferred for UsdVol.ParticleField3DGaussianSplat.
tags
["omniverse","openusd","gsplat","conversion"]
tools
["Read","Shell"]
Omniverse Gaussian Splat to USD
Use the usd-convert-gsplat Python library and CLI to convert 3D Gaussian Splat scene files into Pixar USD artifacts for Omniverse and USD-based pipelines.
When to Use
Use this skill when a user asks to:
Convert .ply or .spz Gaussian Splat content to .usd, .usda, .usdc, or .usdz.
Choose the right usd-convert-gsplat CLI flags for orientation, up-axis, RGB-to-SH generation, or scale generation.
Explain or troubleshoot the converter's Python API, input expectations, output schema, or code locations.
Map converter behavior to Omniverse/OpenUSD concepts such as ParticleField3DGaussianSplat.
Do not use this skill for unrelated USD conversion tasks such as CAD, URDF, mesh, material, or texture conversion unless Gaussian Splat content is the source data.
Inputs
Accept whichever inputs are available, in this precedence:
User-provided source path to a .ply or .spz file.
User-provided output path ending in .usd, .usda, .usdc, or .usdz.
Repository context, if the user asks for API guidance or code navigation instead of running a conversion.
If required input or output paths are missing and the user expects an actual conversion, ask for the missing path before running commands.
Instructions
Confirm whether the user wants to run a conversion, inspect converter behavior, or get usage guidance.
Validate source and destination formats before invoking the tool: input must be .ply or .spz; output must be .usd, .usda, .usdc, or .usdz.
Choose CLI flags from the user's intent. Use --rotate-x/y/z for orientation correction, --up-axis Z for Z-up stages, --generateSh when RGB exists but SH DC coefficients are absent, and when scale channels are absent.
--generateScales
Run the conversion with usd-convert-gsplat -i <input> -o <output> plus selected flags when the user asks for execution and paths are available.
Inspect command output or errors. If conversion fails, identify whether the issue is installation, unsupported input properties, missing optional dependencies, missing USD support, or bad file paths.
Return a concise result that includes the command used, output file path, relevant options, and any follow-up validation or troubleshooting notes.
Output Format
For a completed conversion, return:
Converted `<input>` to `<output>` with `usd-convert-gsplat`.
Command:
`usd-convert-gsplat -i <input> -o <output> [options]`
Notes:
-<orientation/up-axis/SH/scale choices, if any>-<warningsorvalidationresults, ifany>
For usage guidance or troubleshooting, return a short explanation with the exact CLI command, Python API call, or code location the user needs.
Prerequisites
Build repository first if generated packaging files are missing:
repo.bat build
./repo.sh build
Install Python package:
pip install ./source/python
Install USD-enabled extra when writing USD through the Python package:
pip install "./source/python[usd]"
Install SciPy-capable environment before using --generateScales.
Converter Behavior
usd-convert-gsplat reads .ply or .spz Gaussian Splat files and writes ParticleField3DGaussianSplat USD prims.
The preferred schema is UsdVol.ParticleField3DGaussianSplat from OpenUSD 26.03+. Older builds use the Omniverse usd_particle_field fallback.
Preserved data:
Positions: (N, 3) float32 XYZ centers.
Scales: (N, 3) float32, exponentiated from log-scale.
Orientations: (N, 4) quaternion (w, x, y, z), normalized.
Opacities: (N,) float32, sigmoid-applied from raw logit.
Spherical harmonics: DC coefficients always written; higher-order coefficients written when present.
Display color: derived from DC SH coefficients for viewport preview.
Supported Formats
Input
Notes
.ply
Standard 3DGS format, binary little/big-endian or ASCII. Expected properties include x y z, scale_0/1/2, rot_0..3, opacity, f_dc_0/1/2, and optional f_rest_0..N. Use --generateSh for red/green/blue fallback.
.spz
Compressed Gaussian Splat format. Coefficients are stored in vec3-major order, so no transpose is needed.
Output
Format
.usd
Generic USD
.usda
ASCII USD
.usdc
Binary USD crate
.usdz
Zip-packaged USD
CLI Usage
# Basic conversion
usd-convert-gsplat -i scene.ply -o scene.usda
# SPZ input
usd-convert-gsplat -i scene.spz -o scene.usdc
# With orientation correction, for example COLMAP Y-down data
usd-convert-gsplat -i scene.ply -o scene.usda --rotate-x 180
# Generate SH from RGB when f_dc is not present
usd-convert-gsplat -i scene.ply -o scene.usda --generateSh
# Generate scales from neighborhood spacing when scale_0/1/2 are not present
usd-convert-gsplat -i scene.ply -o scene.usda --generateScales
# Z-up output stage
usd-convert-gsplat -i scene.ply -o scene.usda --up-axis Z
# Custom prim name
usd-convert-gsplat -i scene.ply -o scene.usda --name MyScene
Flag
Default
Description
-i / --input
required
Path to .ply or .spz.
-o / --output
required
Path to .usd, .usda, .usdc, or .usdz.
-n / --name
input stem
USD prim name.
--generateSh
false
Convert red/green/blue to SH DC when f_dc is absent.
--generateScales
false
Estimate scales from KNN neighborhood; requires SciPy.
--up-axis
Y
Stage up-axis: Y or Z.
--rotate-x/y/z
0.0
Euler rotation in degrees, XYZ order, applied before writing.
