USD Project Structure and File Organization Best Practices

Naming conventions, folder hierarchies, and layer organization that keep a multi-terabyte OpenUSD project searchable, mergeable, and collaboration-ready.

Imagine inheriting a 5TB OpenUSD project with 10,000+ files scattered across dozens of folders named things like final_FINAL_v2_fixed.OpenUSDa and layer_backup_copy_copy_WORKING.OpenUSDa.

  • 3 hours to find the right material library
  • 2 days debugging broken variants
  • 1 week untangling circular references
  • Missed deadlines because no one knows the "source of truth"

This tutorial prevents that nightmare.

In modern 3D pipelines, a solid project structure is the foundation for scalability, collaboration, and maintainability. This tutorial shows you how to start simple, learn by doing, and scale up using proven OpenUSD naming and organization conventions—without getting stuck chasing perfection. Use your POC's and MVP as a learning path, adapt as you go, and involve your team for long-term success.

Table of Contents

GOAL

Establish robust OpenUSD project architectures with clear naming conventions, logical layer hierarchies, and scalable folder structures that prevent composition conflicts and enable collaborative workflows.

NOTES

ItemDetails
PrerequisitesBasic familiarity with OpenUSD concepts and file formats
Time Investment30–60 minutes for POC, more for scaling
Special SourcesNaming Conventions Unified
WarningDon't over-engineer your first attempt—iterate and improve

Learning Objectives

things you will know

  • Build a minimal OpenUSD project structure for rapid prototyping
  • Understand the value of iteration and reflection in pipeline design
  • Apply best practices for scaling and stakeholder involvement
  • Reference and implement unified naming conventions for advanced use
  • Set up project templates that enforce organizational standards
  • Organize materials, variants, and overrides for efficient iteration
  • Structure layer references for maintainable asset pipelines

INTRO

LevelLevel 2 – Intermediate
Target AudiencePipeline engineers, technical artists, digital twin developers
SourcesOpenOpenUSD docs, industry best practices, unified conventions guide
Tutorial StatusProduction-Ready
Version3.0
Tested WithKIT 107.3, OpenUSD 24.05
DifficultyLevel 2 - Intermediate

Info — ## Quick-Start

Don't let perfect be the enemy of good enough!

Start with a minimal structure, learn by doing, and iterate as you go.

Minimal POC Structure:

CODE

/POC_Project/
├── Root_.OpenUSDa
├── Assets/
│   ├── GMESH_SampleAsset.OpenUSDa
│   └── MLIBS_SampleMaterial.OpenUSDa
├── Layers/
│   └── YREFS_EquipmentReference.OpenUSDa
└── README.md
  • Use this as a sandbox to test, break, and improve your OpenUSD project structure.
  • Document what works, what doesn't, and adapt as you scale.
  • Use layers when needed, do not overcomplicate things and avoid layers when they are not needed!

Quick Deep Dive

Understanding the Why Behind OpenUSD Project Structure

A well-structured OpenUSD project isn’t just about neat folders—it’s about leveraging OpenUSD’s composition engine for scalable, collaborative, and error-resistant workflows. Here’s what you need to know:

1. OpenUSD’s Layered Composition Model

OpenUSD scenes are built from layers, each with a specific role:

  • Root Layer: The entry point for your stage (e.g., 01_Root.OpenUSDa).
  • Asset Layers: Contain geometry, materials, and reusable components.
  • Reference Layers: Bring together assets and define relationships.
  • Override/Adjustment Layers: Apply non-destructive changes or variants.

Key Principle:

Lower-numbered layers (e.g., 10_Base_Project.OpenUSDa) have higher override strength. This mirrors the LIVRPS model—Local, Inherits, Variant, Reference, Payload, Specializes.

2. Naming and Numbering: Not Just for Looks

  • Prefixing (e.g., GMESH_, MLIBS_, YREFS_) instantly communicates file purpose.
  • Numbering (e.g., 10_, 20_, 30_) encodes composition order and override strength.
  • Y-Prefix (e.g., YREFS_Assets.OpenUSDa) signals a composition layer, making debugging and automation easier.

3. Folder Structure Mirrors Workflow

  • /Assets/ for geometry, materials, and reusable components.
  • /Layers/ for composition and adjustment layers.
  • /Textures/, /Scripts/, /Archive/ for supporting resources and versioning.

Why?

This separation allows teams to work in parallel, supports automation, and makes onboarding new team members much faster.

4. Collaboration and Automation

  • Nucleus Sync: Stable paths and modular layers prevent sync conflicts.
  • Version Control: Modular files and clear naming make merges and rollbacks safer.
  • Automation: Consistent structure enables scripting for validation, publishing, and asset management.

5. Common Pitfalls (and How to Avoid Them)

  • Broken References: Avoid renaming files after referencing; use stable names.
  • Composition Conflicts: Use layer numbering and Y-prefixed layers to control override order.
  • Over-Engineering: Start simple, iterate, and only add complexity as needed.

Bottom Line:

A thoughtful OpenUSD project structure is your best defense against chaos as your project and team grow. It’s the foundation for scalable, maintainable, and collaborative 3D pipelines.

General Overview

A well-structured OpenUSD project is the backbone of any scalable 3D pipeline. This tutorial introduces practical strategies for structuring OpenUSD projects, from quick POC to production-ready pipelines. Start simple, iterate, and scale up using proven conventions. For advanced/production-ready structure and naming, see:

Naming Conventions Unified Guide

Overview

This guide unifies the most robust naming and organization systems for OpenUSD projects, blending:

  • 5-digit asset type prefixes (automation-ready, human/machine readable)
  • Pixar/OpenOpenUSD and department/numbered conventions (industry alignment)
  • Digital twin/industrial/IoT patterns (specialized for manufacturing, compliance, and smart facilities)

Use this as a modular reference:

  • Core system for general pipelines
  • Industry/discipline extensions for specialized domains
  • Studio/department patterns for large teams

1. Core Asset Prefix System (5-Digit, Modular)

Asset Type Prefixes

PrefixCategoryExample Usage
GMESHGeometry MeshGMESH_ConveyorBelt_001.OpenUSDa
MLIBSMaterial LibraryMLIBS_IndustrialMaterials_v2.OpenUSDa
THDRIHDRI TextureTHDRI_FactoryLighting_8K.exr
ARIGSAnimation RigsARIGS_RoboticArm_6DOF.OpenUSDa
YROOTRoot LayerYROOT_FactoryMaster.OpenUSDa
BCOMPAssembly Comp.BCOMP_AssemblyStation_A.OpenUSDa
DPROPSData PropertiesDPROPS_ManufacturingSchema.OpenUSDa
VSETSVariant SetsVSETS_ProductVariants_2024.OpenUSDa
GSPLTGaussian SplatsGSPLT_SceneCapture_3DGRUT_v1.OpenUSDa
  • Rationale:

    • Human/machine readable
    • Consistent, extensible
    • Supports automation and search

2. Layer Naming Conventions (All Styles)

A. 5-Digit Role-Based (Y-prefix)

PrefixPurposeExampleNotes
YREFSReference LayerYREFS_EquipmentReference.OpenUSDa
YPAYLPayload LayerYPAYL_HeavyMachinery_Payload.OpenUSDa….maybe
YVARIVariant LayerYVARI_DesignOptions_Variants.OpenUSDa
YOVRDOverride LayerYOVRD_SessionOverrides.OpenUSDa
MaterialAdjust Layer

p.s. The Root is a 'Layer', but at the base, therefore we should give it a name like:

ROOTRoot LayerROOT_FactoryMaster.OpenUSDa
  • Best for: Automation, large-scale projects, clear role separation

NoteWhy 'Y' for Layers?

The prefix 'Y' is used for layers to avoid conflicts and confusion with other asset categories—especially lighting, which traditionally uses the 'L' prefix. In many pipelines, 'L' is already reserved for lighting assets (e.g., LRIGS, LAREA), and using it for both would create ambiguity in file naming, automation, and search.

The choice of 'Y' is intentional:

  • It is visually and phonetically distinct from other prefixes, minimizing the risk of overlap or misclassification.
  • 'Y' can be associated with 'hierarchY' or 'laYer', making it mnemonic and easy to remember for both humans and automated tools.
  • It is rarely used as a prefix in other asset categories, ensuring clarity and uniqueness in large, complex projects.

This approach supports best practices for scalable, maintainable OpenUSD scene graphs and robust pipeline automation.

B. Pixar/OpenOpenUSD Prefixes

PrefixPurposeExample
attr_Attribute-specificattr_visibility.OpenUSDa
base_Foundation/base layersbase_geometry.OpenUSDa
payload_Payload layerspayload_heavy_geo.OpenUSDa
ref_Reference layersref_character_rig.OpenUSDa
v_Variant/version layersv_lod_high.OpenUSDa
meta_Metadatameta_project_info.OpenUSDa
sub_Sublayerssub_lighting_setup.OpenUSDa
clip.Animation clipsclip.walk_cycle.OpenUSDa
  • Best for: Industry alignment, onboarding, cross-studio work

C. Digital Twin/Industrial Prefixes

PrefixPurposeExample
dt_Digital Twin definitiondt_factory_layout.OpenUSDa
iot_IoT sensor integrationiot_temperature_sensors.OpenUSDa
sim_Simulation scenariossim_stress_test.OpenUSDa
cad_CAD geometry importcad_assembly_v01.OpenUSDa
proc_Process workflowsproc_assembly_line.OpenUSDa
maint_Maintenance proceduresmaint_schedule_q1.OpenUSDa
config_Configuration variantsconfig_production_setup.OpenUSDa
test_Testing scenariostest_quality_control.OpenUSDa
safety_Safety protocolssafety_emergency_stop.OpenUSDa
perf_Performance metricsperf_throughput_analysis.OpenUSDa
  • Best for: Digital twins, manufacturing, IoT, compliance

Guidance:

  • Use the system that best fits your pipeline and team. For mixed environments, prefix with both (e.g., YREFS_iot_temperature_sensors.OpenUSDa).

3. Folder/Project Structure Patterns

A. Asset-Type Driven (Modern, Automation-Ready)

CODE

/Assets/
├── Geometry/GMESH_*.OpenUSDa
├── Materials/MLIBS_*.OpenUSDa
├── Textures/THDRI_*.exr
├── Animation/ARIGS_*.OpenUSDa
├── Assembly/BCOMP_*.OpenUSDa
├── Data/DPROPS_*.OpenUSDa
├── Industry/GSPLT_*.OpenUSDa

--------------------------------- or even ----------------------------
/Assets/
├── GMESH_*.OpenUSDa
├── MLIBS_*.OpenUSDa
├── THDRI_*.exr
├── ARIGS_*.OpenUSDa
├── BCOMP_*.OpenUSDa
├── DPROPS_*.OpenUSDa
├── GSPLT_*.OpenUSDa
  • Best for: Automated pipelines, large teams, searchability

B. Department/Numbered/Classic (Pixar/Studio)

CODE

ProjectName/
├── 01_Root.OpenUSDa
├── Assets/Characters/Hero_Model.OpenUSDa
├── Layers/Base/10_Geometry.OpenUSDa
├── Layers/Departments/Animation/
├── Libraries/Materials/03_MatLib.OpenUSDa
├── Sequences/Seq010/Shot010/
├── Tools/
└── Documentation/
  • Best for: Cross-departmental, VFX/animation, onboarding

C. Facility/Plant/Smart Building (Industrial)

CODE

ManufacturingFacility/
├── 00_DigitalTwin_Root.OpenUSDa
├── Systems/Production/ProductionLine_A/ASSET_Robot_Welder_V01.OpenUSDa
├── Assets/Machinery/ROBOT_ABB_IRB6700_V01.OpenUSDa
├── Processes/Assembly/PROC_Assembly_Main_V01.OpenUSDa
├── Simulations/Performance/
├── Data/Sensors/IOT_Temperature_Grid_V01.OpenUSDa
└── Documentation/Specifications/
  • Best for: Digital twins, smart buildings, compliance

4. Industry/Discipline Extensions

  • Digital Twin/Industrial: Use DT_, PROC_, ASSET_, SIM_, MAINT_, etc. for discipline-specific clarity
  • VFX/Animation: Use CHAR_, PROP_, ENV_, VEH_, MAT_, etc. for classic asset types
  • IoT/Smart Building: Use IOT_, SYS_, CTRL_, FLOOR_, etc. for sensors and systems

5. Best Practices & Automation

  • Versioning:

    • For referenced assets, use stable filenames (e.g., Asset.OpenUSDa).
    • Track changes and major updates using your version control system and asset management tools, not by renaming files.
    • Only use versioned filenames (e.g., Asset_v03.OpenUSDa) for deliverables, snapshots, or archival purposes—not for day-to-day pipeline references.
    • Major updates should be documented in commit comments, changelogs, or asset management metadata.
    • For published/approved assets, use a publish/ or approved/ folder, or a postfix like _main or _latest if needed.
Use CaseFilename ExampleVersioning Method
Referenced AssetAsset.OpenUSDaVCS/asset management
Published/Approvedpublish/Asset.OpenUSDaTag, folder, or metadata
Deliverable/SnapshotAsset_v03.OpenUSDaFilename version
  • Automation: Use prefix parsing in pipeline tools for routing and validation
  • Documentation: Maintain README/quick reference in each major folder
  • Team Adoption: Train, audit, and update conventions regularly

Versioning Best Practice: For all referenced assets, use stable filenames (e.g., Asset.OpenUSDa). Track changes and major updates using your version control system and asset management tools, not by renaming files. Only use versioned filenames (e.g., Asset_v03.OpenUSDa) for deliverables, snapshots, or archival purposes—not for day-to-day pipeline references. This ensures reference stability, reduces breakage, and aligns with industry best practices.

6. Quick Reference Tables

A. Asset Prefixes (Unified)

PrefixCategoryExample
GMESHGeometry MeshGMESH_ConveyorBelt_001.OpenUSDa
MLIBSMaterial LibraryMLIBS_IndustrialMaterials_v2.OpenUSDa
.........

B. Layer Prefixes (All Styles)

PrefixPurposeExample
YREFSReference LayerYREFS_EquipmentReference.OpenUSDa
base_Base Layerbase_geometry.OpenUSDa
dt_Digital Twindt_factory_layout.OpenUSDa
.........

C. Folder Patterns

PatternBest For
Asset-TypeAutomation, search
DepartmentStudio, onboarding
Facility/PlantIndustrial, compliance

Choose the system(s) that best fit your project, and document your choices for team clarity and future onboarding.

Overview

This guide unifies the most robust naming and organization systems for OpenUSD projects, blending:

  • 5-digit asset type prefixes (automation-ready, human/machine readable)
  • Pixar/OpenOpenUSD and department/numbered conventions (industry alignment)
  • Digital twin/industrial/IoT patterns (specialized for manufacturing, compliance, and smart facilities)

Use this as a modular reference:

  • Core system for general pipelines
  • Industry/discipline extensions for specialized domains
  • Studio/department patterns for large teams

Core Principles for OpenUSD Project Structure

  • Composition-Aware Structure:

    Organize folders and files to reflect OpenUSD's layered composition system.

    Example: Place foundational assets in /Assets/, and use /Layers/ for Y-prefixed composition layers (e.g., YREFS_Assets.OpenUSDa).

  • LIVRPS-Informed Numbering:

    Use layer numbering (e.g., 10_Base_Project.OpenUSDa, 20_Materials.OpenUSDa) to mirror override strength and composition order.

  • Collaboration-First Design:

    Structure for Nucleus sync, version control, and parallel team workflows.

    Example: Use stable asset names and folders for shared resources.

A More Detailed Understanding

  • Explore the unified naming conventions for asset types, layers, and folders.
  • Learn how to adapt the structure to your team's needs, whether VFX, digital twins, or industrial applications.
  • Use the modular approach: start with the POC, then layer on best practices as your project grows.
  • Understand the rationale behind each convention and how it supports automation, collaboration, and maintainability.

NoteLayer Numbering Best Practice

Use numbers to indicate layer strength and override order, following LIVRPS principles:

  • 10_Base_Project.OpenUSDa (strongest, local opinions)
  • 20_Materials.OpenUSDa (material definitions)
  • 25_MatAdjustment.OpenUSDa (overrides)
  • 30_VarAdjustment.OpenUSDa (variants)

This makes the composition stack predictable and maintainable. </aside>

Why Numbering Matters:

Layer numbering is not just for organization—it's a direct reflection of OpenUSD's composition engine. Lower numbers (e.g., 10, 20) are stronger and override higher numbers (e.g., 30, 40). This prevents accidental overrides, circular references, and makes debugging much easier in large projects.

Getting Started

Example Project Structures

Production-Scale

CODE

OpenUSD_Project/
├── 01_Root.OpenUSDa
├── Assets/
│   ├── GMESH_MainProduct.OpenUSDa
│   └── MLIBS_Materials.OpenUSDa
├── Layers/
│   ├── YREFS_Assets.OpenUSDa
│   ├── YPAYL_HeavyAssets.OpenUSDa
│   └── YVARI_Options.OpenUSDa
├── Textures/
├── Scripts/
└── Archive/

Use for large teams, production, and automation. Scales well and supports clear separation of concerns.

Minimal POC

CODE

POC_Project/
├── 01_Root.OpenUSDa
├── Assets/GMESH_SampleAsset.OpenUSDa
├── Layers/YROOT_POC.OpenUSDa
└── README.md

Best for rapid prototyping, learning, and experimentation. Expand as you grow.

Industrial Digital Twin

CODE

Factory_DigitalTwin/
├── 00_DigitalTwin_Root.OpenUSDa
├── Systems/Production/GMESH_Robot_ABB.OpenUSDa
├── Processes/PROC_Assembly_Main.OpenUSDa
├── Simulations/SIM_StressTest.OpenUSDa
└── Data/IOT_TemperatureGrid.OpenUSDa

Ideal for manufacturing, IoT, and compliance-heavy projects. Supports discipline-specific extensions.

  1. Create a new project folder using the POC structure above.
  2. Add a root layer (01_Root.OpenUSDa) and a minimal asset (e.g., GMESH_SampleAsset.OpenUSDa).
  3. Experiment with adding, referencing, and composing layers.
  4. Iterate: Try breaking things, then fix and document what you learn.
  5. Expand: As your needs grow, reference the unified conventions to add more structure and automation.

Asset Organization Strategy

  • Asset Libraries: Store reusable assets in /Assets/ with clear, stable names (e.g., GMESH_MainProduct.OpenUSDa).
  • Variants: Use dedicated variant layers (e.g., YVARI_Options.OpenUSDa) and folders for product options, configurations, or states.
  • Overrides: Place overrides in their own layers (e.g., 25_MatAdjustment.OpenUSDa) to keep changes modular and non-destructive.
  • Material Libraries: Centralize materials in /Assets/MLIBS_Materials.OpenUSDa or /Materials/ for easy reuse and updates.
  • Documentation: Include a README.md in each major folder to explain structure and conventions.

Collaborative Workflows

  • Nucleus Sync: Organize for Omniverse Nucleus or similar cloud sync. Use stable, predictable paths and avoid renaming referenced files.
  • Version Control: Use Git, Perforce, or similar systems. Track changes via commit messages and tags, not by renaming files.
  • Parallel Development: Structure so multiple teams can work on different layers/assets without conflicts. Use modular layers and asset libraries.
  • Asset Management: Integrate with asset management tools for tracking, approvals, and publishing.

Project Templates

OpenUSD Project Template Checklist:

  • /01_Root.OpenUSDa as the stage entry point
  • /Assets/ for reusable components (geometry, materials, variants)
  • /Layers/ for composition layers (Y-prefixed, numbered)
  • /Textures/ for all texture resources
  • /Scripts/ for automation tools
  • /Archive/ for version history and snapshots
  • README.md in each major folder
  • Use stable filenames for all referenced assets
  • Document all naming conventions and structure choices

Industry Adaptation

  • Use discipline-specific prefixes for industrial/digital twin projects:

    Prefix Purpose Example: DT_ Digital Twin | DT_Factory_Layout.OpenUSDa IOT_ IoT Sensor Data | IOT_TemperatureGrid.OpenUSDa SIM_ Simulation | SIM_StressTest.OpenUSDa PROC_ Process Workflow | PROC_Assembly_Main.OpenUSDa

  • For more, see 02.4_Naming_Conventions_Unified.md

  • Digital Twins/Industrial: Use discipline-specific prefixes and folder patterns (see unified guide)

  • VFX/Animation: Use classic asset types and department folders

  • IoT/Smart Building: Integrate sensor and system naming conventions

  • Hybrid Teams: Combine or prefix as needed (e.g., YREFS_iot_temperature_sensors.OpenUSDa)

Best Practices

  • Iterate, don't over-engineer: Your first structure is a learning tool, not the final product.
  • Reflect and document: After each iteration, note what worked and what didn't.
  • Involve stakeholders: The best structure is one your whole team can use and maintain.
  • Leverage automation: Use naming conventions and folder patterns that support scripting and search.
  • Scale intentionally: As your project grows, adopt more of the unified conventions for clarity and maintainability.

Validation Tools & Extensions

  • OpenUSD Structure Validation:

    • Use OpenUSDchecker (command-line) to validate composition and structure: OpenUSDchecker --composition ./01_Root.OpenUSDa
    • Use OpenUSDview for quick load and structure checks: OpenUSDview --no-render ./01_Root.OpenUSDa
    • For Omniverse users, explore available extensions or apps for project structure validation (e.g., Nucleus browser, Omniverse extensions for consistency checking).
    • Consider integrating validation scripts into your CI/CD pipeline for automated checks.

TipHow to Know You Succeeded

  • You can find any asset or material in seconds, not hours.

  • Adding a new variant or override doesn't break the project.

  • Team members can onboard quickly and contribute with confidence.

  • Your structure scales from POC to production without chaos.

  • Success Metrics:

    • Find any asset in <10 seconds
    • No broken references after a week of team edits
    • New team members can contribute within their first day

FAQ

Q: How should I start structuring a new OpenUSD project?

A: Begin with a minimal, clear folder structure (Root, Assets, Layers, README). Start simple, iterate as you learn, and expand as your needs grow. Use the POC structure as a sandbox for experimentation.

Q: What are the most important naming conventions for OpenUSD projects?

A: Use clear, stable, and consistent names for all assets and layers. Prefix files by type (e.g., GMESH_, MLIBS_, YREFS_) and use numbers to indicate composition order and override strength (e.g., 10_Base_Project.OpenUSDa, 20_Materials.OpenUSDa).

Q: How do I avoid broken references and composition conflicts?

A: Always use stable filenames and folder paths for referenced assets. Avoid renaming files after they are referenced. Use layer numbering and Y-prefixed layers to make the composition stack predictable.

Q: How do I organize for team collaboration and version control?

A: Structure your project for Nucleus sync or version control (Git, Perforce). Use modular layers and asset libraries so multiple teams can work in parallel. Track changes via commit messages, not by renaming files.

Q: What tools can help validate my OpenUSD project structure?

A: Use OpenUSDchecker (CLI), OpenUSDview, and Omniverse Composer for structure and reference validation. Integrate validation scripts into your CI/CD pipeline for automated checks.

Q: How do I scale my project from POC to production?

A: Start with a minimal structure, document what works, and gradually adopt more unified conventions as your project grows. Involve stakeholders and reflect after each iteration.

Q: Where can I find more examples or templates?

A: See the “Related Resources” section at the end of this tutorial for links to official documentation, community guides, and real-world case studies.

Notes & References

Community Resources

Official Documentation:

Community Support:

  • NVIDIA Developer Forums: Technical questions and troubleshooting
  • OpenUSD Interest Group: Industry working group for standards
  • Discord Communities: Real-time chat with practitioners

Training Programs:

  • NVIDIA DLI: Deep Learning Institute OpenUSD courses
  • SIGGRAPH Sessions: Annual conference presentations
  • Vendor Training: Maya, Houdini, Blender OpenUSD-specific training

When OpenUSD+Omniverse is Right for You

Strong Fit Indicators:

  • ✅ Multi-tool workflows with conversion pain
  • ✅ Team collaboration challenges
  • ✅ XR/digital twin requirements
  • ✅ Performance needs at scale
  • ✅ Future-proofing against vendor lock-in

Consider Alternatives When:

  • ❌ Single-tool, single-user workflows
  • ❌ Simple file sharing needs
  • ❌ Legacy system integration constraints
  • ❌ Limited technical resources for learning curve

Series Navigation

Previous: Benefits of USD and how it integrates into Omniverse and Nucleus server

Next: Benefits of USD and how it integrates into Omniverse and Nucleus server

Series Index: Authoring and optimizing USD workflows for industrial use with Omniverse

Reference Guides

🔗 External Documentation

Project Examples