omniverse-gaussian-splat-to-usd

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.

Jump to install

Repository: NVIDIA-Omniverse/usd-convert-gsplat
Last source activity: May 22, 2026 at 02:25
Detected SKILL.md language: English
Stars: 14
Forks: 3

Install options

The review-first prompt is selected by default. You can switch to a direct command or download a local copy.

Review the source files

Read SKILL.md and any companion files shown by SkillsMP before deciding whether to install.

Back to search Back to installation

name	omniverse-gaussian-splat-to-usd
description	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.
User-provided conversion options: --name, --up-axis, --rotate-x, --rotate-y, --rotate-z, --generateSh, or --generateScales.
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

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>
- <warnings or validation results, if any>

repo.bat build
./repo.sh build

pip install ./source/python

pip install "./source/python[usd]"

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.

# 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.

from usd_convert_gsplat.ply_reader import read_ply
from usd_convert_gsplat.spz_reader import read_spz
from usd_convert_gsplat.usd_writer import write_gaussian_splat_usd, convertPlyUSD

splat_data = read_ply("scene.ply")
# or:
splat_data = read_spz("scene.spz")

write_gaussian_splat_usd(
    splat_data,
    output_path="scene.usda",
    source_file="scene.ply",
    prim_name="MyScene",
    up_axis="Y",
    rotation_degrees=(180, 0, 0),
    progress_fn=lambda f, msg: print(f"{f:.0%} {msg}"),
)

# PLY-only reference path that preserves raw vertex data.
convertPlyUSD(
    input_file="scene.ply",
    output_file="scene.usda",
    prim_name="MyScene",
    generateSh=False,
    generateScales=False,
    up_axis="Y",
    rotation_degrees=(0, 0, 0),
)

@dataclass
class GaussianSplatData:
    positions: np.ndarray
    scales: np.ndarray
    rotations: np.ndarray
    opacities: np.ndarray
    f_dc: np.ndarray
    f_rest: Optional[np.ndarray]
    count: int

from usd_convert_gsplat.ply_reader import read_ply_raw

data, vertex_count, property_names = read_ply_raw("scene.ply")

Symptom	Likely cause	Fix
`usd-convert-gsplat` command not found	Package is not installed in active Python environment	Run `pip install ./source/python` and verify with `python -m pip show usd-convert-gsplat`.
USD import or writer failure	USD extras or compatible OpenUSD runtime missing	Install with `pip install "./source/python[usd]"` and verify OpenUSD version/plugin availability.
Missing SH coefficients	PLY contains RGB but no `f_dc_*` fields	Re-run with `--generateSh`.
Missing scale channels	PLY has no `scale_0/1/2` properties	Re-run with `--generateScales` in an environment with SciPy.
Scene orientation is wrong	Source data uses different up-axis or camera convention	Use `--up-axis Z` or `--rotate-x/y/z` flags.

File	Role
`source/python/usd_convert_gsplat/ply_reader.py`	PLY parser to `GaussianSplatData`.
`source/python/usd_convert_gsplat/spz_reader.py`	SPZ parser to `GaussianSplatData`.
`source/python/usd_convert_gsplat/usd_writer.py`	`GaussianSplatData` to USD stage.
`source/python/usd_convert_gsplat/cli.py`	`usd-convert-gsplat` entry point.
`source/extensions/omni.kit.converter.gsplat/`	Omniverse Kit UI extension that calls the library.