Setup#

This guide installs everything you need to run the AIF Pipeline tools:

  1. Kit Installation - NVIDIA Omniverse Kit application (USD Composer)

  2. AIF Pipeline CLI - command-line tool for converting, optimizing, and validating USD assets

  3. Asset Processor - browser-based front-end for building Scene Optimizer presets

After completing this page, continue to Quickstart to configure Kit paths and run your first pipeline.

Prerequisites#

  • Windows 10/11 or Linux (Ubuntu 20.04+)

  • 16 GB+ RAM recommended

  • NVIDIA RTX GPU

  • Git - Required to clone the repository (git-scm.com)

  • Python 3.10 - 3.12 - uv can download this automatically during setup, so manual installation is optional

  • PowerShell execution policy (Windows only) - The setup script requires permission to run .ps1 scripts. If you see an UnauthorizedAccess error, open PowerShell and run:

Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned

Kit Installation#

Choose one of the following methods to install USD Composer.

Option 1: Kit App Template (Quickstart)#

Recommended for most users - Uses the official NVIDIA kit-app-template with automated setup.

Follow the Kit App Template Quickstart.

Note

If you encounter permission errors, run your terminal with elevated privileges (Administrator on Windows, sudo on Linux).

Warning

Some corporate/enterprise environments have network restrictions that can prevent this method from working. If you encounter issues, use Option 2 below.

Tip

If you used Option 1, skip ahead to AIF Pipeline CLI Installation. The remaining steps in this section apply only to Option 2.

Option 2: Manual Setup Through NGC (Air-Gapped/Offline)#

Use this method for air-gapped or offline environments.

Step 1: Download Kit Components

  1. Navigate to the NGC Kit SDK Air Gap page for your platform:

  2. Download Kit SDK Air Gap: Click File Browser > Actions (triple dot) > Download File

  3. Download Kit Extensions Registry: Navigate to Kit Extensions Registry (PB 25h2), then File Browser > Actions > Download File

    Note

    This is a large download (several GB) and will take time.

Step 2: Extract Components

tar -xf D:/downloads/kit-sdk-airgap.zip -C D:/build/ngc/109.0.3

tar -xf D:/downloads/kit-extensions-registry.zip -C D:/build/ngc/109.0.3_extsregistry

Tip

tar is built into Windows 10+ and is significantly faster than Expand-Archive for large archives. If tar is not available, you can use Expand-Archive instead:

Expand-Archive D:/downloads/kit-sdk-airgap.zip -DestinationPath D:/build/ngc/109.0.3

unzip kit-sdk-airgap.zip -d ~/build/ngc/109.0.3

unzip kit-extensions-registry.zip -d ~/build/ngc/109.0.3_extsregistry

Step 3: Create USD Composer Project

Navigate to the extracted Kit SDK and run the new project script:

cd D:/build/ngc/109.0.3

.\new_project.bat

cd ~/build/ngc/109.0.3

./new_project.sh

Follow the prompts:

  1. Accept governing terms

  2. Path to new repository: Enter path for USD Composer application (example: D:/build/ngc/USD_Composer_109.0.3)

Step 4: Configure USD Composer Template

Navigate to the new USD Composer repository and create the application template:

cd D:/build/ngc/USD_Composer_109.0.3

.\repo.bat template new

cd ~/build/ngc/USD_Composer_109.0.3

./repo.sh template new

Follow the prompts:

  1. Accept governing terms

  2. Choose Application

  3. Choose USD Composer

  4. Press Enter six times (accept all defaults)

  5. Add application layers? > Choose No

Note

Keeping defaults simplifies usage with the AIF Pipeline Samples code.

Step 5: Configure Extensions Registry

Before building, add the local extensions registry to the project configuration. Open repo.toml in your USD Composer project directory, find the [repo_precache_exts] section, and add the registries array (adjust paths to match where you extracted the registry):

[repo_precache_exts]
registries = [
     { name = "ngc_registry", url = "D:/build/ngc/109.0.3_extsregistry" },
]
# Apps to run and precache
apps = ["${root}/source/apps/my_company.my_usd_composer.kit"]
# Generate a simple Kit file to pull some build-time extensions
generated_app_path = "${root}/_build/exts.deps.generated.kit"

[repo_precache_exts]
registries = [
     { name = "ngc_registry", url = "/home/<your-username>/build/ngc/109.0.3_extsregistry" },
]
# Apps to run and precache
apps = ["${root}/source/apps/my_company.my_usd_composer.kit"]
# Generate a simple Kit file to pull some build-time extensions
generated_app_path = "${root}/_build/exts.deps.generated.kit"

Note

Replace /home/<your-username>/ with your actual home directory path.

Save and close the file.

Step 6: Build USD Composer

.\repo.bat build

./repo.sh build

Wait for the build to complete (can take several minutes on the first build).

Step 7: Launch USD Composer

.\repo.bat launch

./repo.sh launch

On first launch:

  • Accept firewall notification (if prompted)

  • RTX Loading can take longer on the first run

  • USD Composer interface should appear

AIF Pipeline CLI Installation#

Naming note

AIF Pipeline Samples (aif-pipeline-samples) is the repository containing scripts, presets, and the CLI source code. AIF Pipeline CLI (aif-pipeline) is the command-line tool installed from the cli/ directory inside that repo. The CLI wraps Omniverse Kit extensions (Scene Optimizer, Asset Validator, CAD Converter) into a single aif-pipeline command.

Windows users

All commands below are for PowerShell (not Command Prompt / CMD). If you are using CMD, switch to PowerShell first: type powershell and press Enter.

Shell differences (Windows compared to Linux)

  • Running commands: use uv run <command> on both platforms (no manual activation needed)

  • Manual activation: PowerShell uses .\.venv\Scripts\Activate.ps1. Linux uses source .venv/bin/activate.

  • Environment variables: PowerShell uses $env:VAR. Linux uses $VAR.

Python Version Requirements#

Supported versions - Python 3.10, 3.11, and 3.12.

uv handles Python version selection automatically - uv sync reads the version constraint from pyproject.toml and downloads a compatible Python if needed. You do not need to install Python manually, and adding Python to your system PATH is not required. uv discovers and manages Python installations independently.

Note

Python 3.13+ is not yet supported by all dependencies (notably usd-core). If your system default is 3.13+, this is not a problem - uv sync automatically selects a compatible version within the >=3.10,<3.13 range.

Step 1: Get the Repository#

Clone the repository into a directory of your choice. This can be any location on your system - it is recommended to keep it outside of your Kit/Composer installation directory to avoid confusion.

cd D:\projects

Clone through SSH:

git clone git@github.com:NVIDIA-Omniverse/aif-pipeline-samples.git

Or through HTTPS:

git clone https://github.com/NVIDIA-Omniverse/aif-pipeline-samples.git

Enter the repo root:

cd aif-pipeline-samples

cd ~/projects

Clone through SSH:

git clone git@github.com:NVIDIA-Omniverse/aif-pipeline-samples.git

Or through HTTPS:

git clone https://github.com/NVIDIA-Omniverse/aif-pipeline-samples.git

Enter the repo root:

cd aif-pipeline-samples

Important

You are now in the repo root (aif-pipeline-samples/). All remaining commands on this page and in the Quickstart assume you are in this directory. Do not run these commands from a Kit app template directory.

After cloning, the repository layout is:

aif-pipeline-samples/            <-- repo root ($AIF_PIPELINE_SAMPLES_ROOT)
├── pyproject.toml               <-- workspace definition (uv sync reads this)
├── cli/                         <-- CLI source (installed as editable workspace member)
├── asset_processor/             <-- Asset Processor web app
│   └── server.py
├── oav/                         <-- Asset validators (workspace member)
├── so/                          <-- Scene Optimizer presets
├── docs/
├── setup.ps1                    <-- Automated setup (Windows)
├── setup.sh                     <-- Automated setup (Linux)
└── .venv/                       <-- created by setup script or uv sync

Step 2: Install Everything#

Choose one of the two options below. Option A is recommended for most users.

Option B: Manual Steps#

Use this if the automated script does not work in your environment (for example, restricted network access that blocks the uv installer).

Step 2a: Install uv

uv is a fast Python package manager that handles virtual environment creation and dependency installation.

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

curl -LsSf https://astral.sh/uv/install.sh | sh

Verify:

uv --version

Note

These commands pipe the uv installer script directly into the shell. If you prefer to inspect the script before running it, download it first:

  • Windows: irm https://astral.sh/uv/install.ps1 -OutFile uv-install.ps1, review it, then run .\uv-install.ps1

  • Linux: curl -LsSf https://astral.sh/uv/install.sh -o uv-install.sh, review it, then run sh uv-install.sh

uv is open source: github.com/astral-sh/uv

Step 2b: Set Environment Variable

The AIF_PIPELINE_SAMPLES_ROOT environment variable points to the repository root. It enables:

  1. Dynamic preset discovery - Scene Optimizer Python processors can find and run presets without hardcoded paths.

  2. External Python modules - Scene Optimizer Python processors can load shared code from a library folder (for example, so/generic/lib/).

[System.Environment]::SetEnvironmentVariable('AIF_PIPELINE_SAMPLES_ROOT', $PWD.Path, 'User')

Set it for the current session as well:

$env:AIF_PIPELINE_SAMPLES_ROOT = $PWD.Path

Verify:

echo $env:AIF_PIPELINE_SAMPLES_ROOT

The output should show your repo root (for example, D:\projects\aif-pipeline-samples). If it is blank, close and reopen your terminal.

Add to ~/.bashrc or ~/.zshrc:

export AIF_PIPELINE_SAMPLES_ROOT="$(pwd)"

Reload:

source ~/.bashrc

Verify:

echo $AIF_PIPELINE_SAMPLES_ROOT

The output should show your repo root (for example, /home/user/projects/aif-pipeline-samples).

Tip

The repository can live anywhere on your system. As long as AIF_PIPELINE_SAMPLES_ROOT points to the correct root, commands will work regardless of the install location.

Step 2c: Install Dependencies

Run uv sync from the repo root. This single command:

  • Creates a .venv/ virtual environment with a compatible Python version

  • Installs the CLI in editable mode (from cli/)

  • Installs Asset Processor dependencies (Flask and others)

  • Installs the asset validators (from oav/)

  • Generates a uv.lock lockfile for reproducible builds

uv sync

You should see uv creating the virtual environment and installing packages. When it finishes, the last line reads something like Installed N packages in Xs. A .venv/ directory now exists in the repo root.

Verify the Installation#

Whether you used Option A or Option B, verify that the CLI works:

Activate the virtual environment (not needed if you use uv run instead):

.\.venv\Scripts\Activate.ps1

Activate the virtual environment (not needed if you use uv run instead):

source .venv/bin/activate

aif-pipeline --version

aif-pipeline --help

You should see the CLI version number and a list of available commands.

Note

Activate the virtual environment each time you open a new terminal. Alternatively, you can prefix any command with uv run to skip activation entirely - for example, uv run aif-pipeline --help or uv run python asset_processor/server.py. uv run automatically discovers and uses the workspace .venv/ so you do not need to activate it first.

External Script Library Pattern

Place reusable Python scripts in a library folder (such as so/generic/lib/). In your Scene Optimizer Python Script processor, use this pattern to load and execute them:

import os

lib_path = os.path.join(os.environ["AIF_PIPELINE_SAMPLES_ROOT"], "so", "generic", "lib")
script_file = os.path.join(lib_path, "my_script.py")

exec(compile(open(script_file).read(), script_file, 'exec'))

process(stage)

Why use exec(compile(...)) instead of import?

Python’s import system caches modules in sys.modules. During development, if you edit your script and re-run the processor, the cached version runs instead of your updated code. The exec(compile(...)) pattern:

  • Reads the file fresh from disk every time

  • Avoids all import caching issues

  • Provides proper error tracebacks (using compile() with filename)

  • Works reliably in Scene Optimizer’s embedded Python environment

After your scripts are stable, you can switch to standard imports if preferred, but you need to restart Kit/USD Composer to pick up changes.

Updating dependencies

uv sync installs the versions pinned in uv.lock for reproducibility. To update a specific dependency to its latest release (for example, the Omni Asset Validator):

uv lock --upgrade-package omniverse-asset-validator
uv sync

To update all dependencies at once:

uv lock --upgrade
uv sync

What You Have Now#

After completing this page you have:

  • USD Composer (Kit) installed and built

  • The aif-pipeline-samples repository cloned

  • AIF_PIPELINE_SAMPLES_ROOT environment variable set

  • A .venv/ virtual environment with the CLI, Asset Processor dependencies, and validators installed

  • aif-pipeline --version prints a version number

The CLI does not yet know where your Kit installation lives. The Quickstart walks you through launching the Asset Processor, adding your Kit configuration, and running your first optimization.

Next Steps#