Omniverse Gaussian Splat To Usd

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:

1. User-provided source path to a .ply or .spz file.
2. User-provided output path ending in .usd, .usda, .usdc, or .usdz.
3. User-provided conversion options: --name, --up-axis, --rotate-x, --rotate-y, --rotate-z, --generateSh, or --generateScales.
4. 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

1. Confirm whether the user wants to run a conversion, inspect converter behavior, or get usage guidance.
2. Validate source and destination formats before invoking the tool: input must be .ply or .spz; output must be .usd, .usda, .usdc, or .usdz.
3. 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 --generateScales when scale channels are absent.
4. Run the conversion with usd-convert-gsplat -i <input> -o <output> plus selected flags when the user asks for execution and paths are available.
5. 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.
6. 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>
- <warnings or validation results, if any>

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

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

Python API

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

GaussianSplatData contains:

@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

For raw PLY access:

from usd_convert_gsplat.ply_reader import read_ply_raw

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

Limitations

• --generateScales requires SciPy and may be slower on large splat sets because it estimates neighborhood spacing.
• .spz inputs already store coefficients in vec3-major order; do not transpose them as if they were PLY channel-major data.
• The OpenUSD UsdVol.ParticleField3DGaussianSplat schema requires OpenUSD 26.03+; older builds use Omniverse fallback behavior.
• This skill covers Gaussian Splat conversion only. It does not convert meshes, CAD, URDF, materials, or arbitrary USD assets.

Troubleshooting

Codebase Map