XPD File Format Plugin for USD

A USD file format plugin that enables direct reading of Autodesk Maya XGen primitive files (.xpd and .xuv) as USD layers. This plugin integrates XGen groom data seamlessly into USD pipelines without requiring manual conversion.

Features

• Direct USD Integration: Read .xpd and .xuv files directly in USD applications (usdview, Houdini Solaris, etc.)
• Lightweight Dependencies: Only requires XGen's libAdskXpd library, not the full Maya runtime
• No Qt Conflicts: Works with usdview and other Qt-based USD tools without library conflicts
• Preserved Metadata: Maintains XGen-specific attributes like face IDs and UV locations

Prerequisites

• Maya (2022 or later) - Required for XGen's libAdskXpd.dylib library
• USD (0.20.05 or later) - Pixar's Universal Scene Description

Supported Platforms

• macOS (Apple Silicon and Intel)
• Linux (experimental)
• Windows (experimental)

Quick Start

1. Build the Plugin

# Clone the repository
git clone https://github.com/user/xpdToUsd.git
cd xpdToUsd

# Build (auto-detects Maya and requires USD at ~/work/Usd)
./scripts/build_local.sh

2. Set Environment Variables

# Option A: Source the generated setup script
source install/setup_env.sh

# Option B: Set manually
export PXR_PLUGINPATH_NAME=/path/to/xpdToUsd/install/lib/usd
export DYLD_LIBRARY_PATH=/Applications/Autodesk/maya2026/plug-ins/xgen/lib:$HOME/work/Usd/lib

3. Use the Plugin

# View XPD in usdview
./scripts/usdview.sh /path/to/groom.xpd

# Or use USD tools directly
usdcat /path/to/groom.xpd
usdview /path/to/groom.xpd

Building

Local Development Build

The scripts/build_local.sh script is configured for local development with USD installed at ~/work/Usd:

./scripts/build_local.sh [OPTIONS]

Options:
  --clean          Clean build directory before building
  --skip-install   Skip the install step
  --verbose        Show verbose build output
  --install-path   Override install path (default: ./install)
  --help, -h       Show help message

Manual CMake Build

mkdir build && cd build
cmake .. \
  -DCMAKE_INSTALL_PREFIX=../install \
  -DPXR_USD_LOCATION=/path/to/USD \
  -DMAYA_LOCATION=/Applications/Autodesk/maya2026
make -j8
make install

Build Requirements

Dependency	Environment Variable	Example Path
USD	PXR_USD_LOCATION	~/work/Usd
Maya	MAYA_LOCATION	/Applications/Autodesk/maya2026

Usage

Using usdview.sh

The included scripts/usdview.sh script sets up the environment and launches usdview:

./scripts/usdview.sh /path/to/groom.xpd [usdview options]

Python API

from pxr import Sdf, Usd

# Open an XPD file as a USD layer
layer = Sdf.Layer.FindOrOpen('/path/to/groom.xpd')
print(layer.ExportToString())

# Open as a USD stage
stage = Usd.Stage.Open('/path/to/groom.xpd')
for prim in stage.Traverse():
    print(prim.GetPath())

# Convert XPD to USDA
layer = Sdf.Layer.FindOrOpen('/path/to/groom.xpd')
layer.Export('/path/to/output.usda')

Command Line Tools

# View XPD structure
usdcat /path/to/groom.xpd

# Convert to USDA format
usdcat /path/to/groom.xpd -o /path/to/output.usda

# Interactive viewer
usdview /path/to/groom.xpd

Data Mapping

XPD Files → USD BasisCurves

XPD Data	USD Representation
Curve geometry	UsdGeomBasisCurves primitives
Face IDs	xpd:faceIds (VtArray)
UV locations	xpd:uvLocations (VtArray)
Curve widths	Standard widths attribute

XUV Files → USD Points

XUV Data	USD Representation
Point positions	UsdGeomPoints primitives
Face IDs	xpd:faceIds (VtArray)
UV locations	xpd:uvLocations (VtArray)
Point IDs	xpd:xuvids (VtArray)

Runtime Dependencies

The plugin only requires XGen's libAdskXpd.dylib at runtime - not the full Maya installation. This is achieved by:

1. Minimal linking: The plugin links only to USD libraries and libAdskXpd
2. Runtime symbol resolution: Python symbols are resolved at runtime via -undefined dynamic_lookup
3. No Qt conflicts: Avoids linking Maya's Qt libraries that conflict with usdview's PySide

Set DYLD_LIBRARY_PATH to include the XGen lib directory:

export DYLD_LIBRARY_PATH=/Applications/Autodesk/maya2026/plug-ins/xgen/lib:$USD_LIB_PATH

Running Tests

cd build
ctest --verbose

# Or run directly
./test_xpd_file_format

Troubleshooting

Plugin Not Found

Error: File format plugin for extension 'xpd' not found

Solution: Set PXR_PLUGINPATH_NAME to the plugin install directory:

export PXR_PLUGINPATH_NAME=/path/to/install/lib/usd

XGen Library Not Found

Library not loaded: @rpath/libAdskXpd.dylib

Solution: Add XGen's lib directory to the library path:

export DYLD_LIBRARY_PATH=/Applications/Autodesk/maya2026/plug-ins/xgen/lib:$DYLD_LIBRARY_PATH

Maya Not Found During Build

Maya not found. Set MAYA_LOCATION environment variable...

Solution: Set MAYA_LOCATION to your Maya installation:

export MAYA_LOCATION=/Applications/Autodesk/maya2026

Exporting XPD from XGen

In Maya's XGen:

1. Select your XGen description
2. Change renderer to "XPD"
3. Set the output directory
4. Click "Create XPD File"

Pipeline Integration

Houdini Solaris

# In a USD Import LOP, reference directly:
/path/to/groom.xpd

Custom Pipeline Tools

from pxr import Usd
import glob

# Batch convert XPD files to USDA
for xpd_file in glob.glob("*.xpd"):
    stage = Usd.Stage.Open(xpd_file)
    stage.Export(xpd_file.replace('.xpd', '.usda'))

Notes on USD→XPD Conversion

XPD is a groom-centric format designed for XGen instancing. When converting USD back to XPD, certain attributes are required:

• xpd:faceIds (VtArray): Per-curve OSD patch index for curve root placement
• xpd:uvLocations (VtArray): Per-curve UV coordinates on the OSD patch
• Uniform CV count: XGen requires all curves to have the same number of control vertices

License

See LICENSE file for details.