USD Project Structure and File Organization Best Practices

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

INTRO

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

• Rationale:

  • Human/machine readable

  • Consistent, extensible

  • Supports automation and search

2. Layer Naming Conventions (All Styles)

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

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

• Best for: Automation, large-scale projects, clear role separation

Why '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

• Best for: Industry alignment, onboarding, cross-studio work

C. Digital Twin/Industrial Prefixes

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

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

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)

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.

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

B. Layer Prefixes (All Styles)

C. Folder Patterns

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.

Layer 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

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

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

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.

How 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

• Naming Conventions Unified — Unified asset, layer, and folder conventions

• OpenOpenUSD Documentation: https://openusd.org/

• Digital Twin/Industrial Best Practices: See industry extension sections in the unified guide

Community Resources

Official Documentation:

• OpenOpenUSD.org: Pixar's official OpenUSD documentation

• docs.omniverse.nvidia.com: NVIDIA Omniverse guides

• OpenUSD Survival Guide: Community-driven practical guide

• Awesome OpenUSD: Matias Codesal

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

Related Resources

Reference Guides

• Naming Conventions Unified

• Global Glossary

🔗 External Documentation

• OpenOpenUSD Official Documentation

• NVIDIA Omniverse Platform Overview

• OpenUSD Survival Guide

• Pixar's OpenUSD Pipeline Story

Project Examples

• Download examples in Omniverse Launcher → Library

• Real-world case studies: BMW, Siemens, Zaha Hadid Architects