Overview#

omni.kit.stage_templates enables custom stage template management for the Omniverse Kit USD workflow. The extension allows users to register, unregister, and select from a variety of stage templates when creating new stages. With support for both built-in and user-defined templates, it streamlines stage initialization by providing synchronous, callback-based, and asynchronous creation options.

Concepts#

Custom Templates: Define preset stage configurations that tailor how a new USD stage is created.
Callback & Async Operations: Functions are provided to execute stage creation with optional callbacks and asynchronous behavior.
User Templates: In addition to built-in templates, user-defined templates are loaded from configurable file system paths.

Functionality#

Template Registration: Exported APIs (e.g., register_template, unregister_template) allow dynamic management of stage templates.
Template Retrieval: Functions such as get_stage_template, get_stage_template_list, and get_default_template facilitate lookup and selection of templates.
Stage Creation: new_stage, new_stage_with_callback, and new_stage_async provide flexible methods to instantiate new stages using the chosen template.
User-defined Loading: load_user_templates reads template scripts from user-specified directories, creating template directories if they are missing.

Configuration#

The default new stage template is specified in settings (e.g., persistent.app.newStage.defaultTemplate is set to “sunlight”).
Templates are loaded from paths defined in persistent.app.newStage.templatePath.
Stage-specific parameters like time code range (persistent.app.stage.timeCodeRange) help standardize stage initialization.

Relationships#

Dependencies: This extension builds on omni.kit.stage_template.core, omni.kit.commands, omni.usd, omni.kit.actions.core, and omni.kit.primitive.mesh.
It integrates into the Omniverse Kit USD workflow, ensuring that both built-in and user-defined templates contribute to a consistent stage creation process.

Considerations#

Ensure that the template path directories are accessible and contain valid template scripts.
When unregistering templates, rebuilding the stage template menu is necessary to keep the UI consistent.
The extension expects a synchronous initialization of templates at startup while offering asynchronous options for non-blocking stage creation workflows.