Metadata-Version: 2.4
Name: gsplat2USD
Version: 0.1.5
Summary: NVIDIA 3D Gaussian Splat to USD Converter
Project-URL: Homepage, https://docs.omniverse.nvidia.com/kit/docs/gsplat-converter
Project-URL: Documentation, https://docs.omniverse.nvidia.com/kit/docs/gsplat-converter
Author: NVIDIA
License: Apache-2.0
Requires-Python: <3.13,>=3.10
Requires-Dist: numpy==2.3.1
Provides-Extra: usd
Requires-Dist: usd-core>=22.11; extra == 'usd'
Description-Content-Type: text/markdown

# Omniverse Gaussian Splat Converter

A pip-installable Python package for converting 3D Gaussian Splat data (PLY and SPZ formats) to USD
using the `ParticleField3DGaussianSplat` schema.

## Installation

```bash
pip install gsplat2USD
```

For USD support (if not already installed):

```bash
pip install gsplat2USD[usd]
```

## Building From Source

The converter package lives in `source/python` and builds with standard Python
packaging tools.

Use Python 3.11 or 3.12. Python 3.10 is not compatible with the pinned `numpy==2.3.1` dependency.

```bash
cd source/python
python -m pip install --upgrade pip build
python -m build
```

The build writes both source and wheel distributions to `dist/`:

```text
dist/gsplat2usd-<version>.tar.gz
dist/gsplat2usd-<version>-py3-none-any.whl
```

Replace `<version>` with the package version generated by your build.

To install and smoke test the local source tree:

```bash
python -m venv .venv
source .venv/bin/activate  # Windows PowerShell: .\.venv\Scripts\Activate.ps1
python -m pip install ".[usd]"
python -m gsplat2USD --help
python -m gsplat2USD -i input.ply -o output.usda
```

You can also test the built wheel directly:

```bash
python -m pip install "dist/gsplat2usd-<version>-py3-none-any.whl[usd]"
gsplat2USD -i input.ply -o output.usda
```

## Usage

### Command Line

```bash
# Convert a PLY file to USDZ
gsplat2USD -i input.ply -o output.usdz

# Convert an SPZ file to USDA with Z-up axis
gsplat2USD -i input.spz -o output.usda --up-axis Z

# Generate spherical harmonics and scales from raw PLY
gsplat2USD -i input.ply -o output.usdz --generateSh --generateScales
```

You can also run via `python -m`:

```bash
python -m gsplat2USD -i input.ply -o output.usdz
```

### Python API

```python
from gsplat2USD import read_ply, read_spz, write_gaussian_splat_usd

# Read a PLY file
splat_data = read_ply("scene.ply")

# Write to USD
write_gaussian_splat_usd(splat_data, "scene.usdz", source_file="scene.ply")

# Read an SPZ file
splat_data = read_spz("scene.spz")

# Write to USD with options
write_gaussian_splat_usd(
    splat_data,
    "scene.usda",
    source_file="scene.spz",
    up_axis="Z",
    rotation_degrees=(90.0, 0.0, 0.0),
)
```
