Usage Examples

Register Custom Stage Template

import omni.kit.stage_templates
from pxr import Usd, UsdGeom, Sdf

# Define a custom stage template function
def create_basic_cube_stage(rootname):
    """Create a stage with a basic cube at the origin"""
    # Get the current context
    usd_context = omni.usd.get_context()
    stage = usd_context.new_stage()
    
    # Create a default prim
    default_prim = stage.DefinePrim(Sdf.Path(rootname), "Xform")
    stage.SetDefaultPrim(default_prim)
    
    # Create a cube
    cube_path = f"{rootname}/Cube"
    cube = UsdGeom.Cube.Define(stage, Sdf.Path(cube_path))
    
    # Set cube size
    cube.CreateSizeAttr(2.0)
    
    return stage

# Register the custom template
omni.kit.stage_templates.register_template(
    name="basic_cube",
    new_stage_fn=create_basic_cube_stage,
    group=0,  # Group 0 is the default group
    rebuild=True  # This will rebuild the template menu
)

# Later, when you're done with this template, you can unregister it
omni.kit.stage_templates.unregister_template(
    name="basic_cube",
    rebuild=True
)

---

Get Template Information

import omni.kit.stage_templates

# Get the default template name
default_template = omni.kit.stage_templates.get_default_template()
print(f"Default template: {default_template}")

# Get a list of all stage templates
template_groups = omni.kit.stage_templates.get_stage_template_list()
print("Available template groups:")
for group_index, template_group in enumerate(template_groups):
    print(f"Group {group_index}:")
    for template_name, template_fn in template_group.items():
        print(f"  - {template_name}")

# Get a specific template
template_name = "empty"  # This is a built-in template
template = omni.kit.stage_templates.get_stage_template(template_name)
if template:
    print(f"Found template: {template[0]} (function: {template[1].__name__ if template[1] else None})")
else:
    print(f"Template '{template_name}' not found")

---

Create New Stage with Callback

import omni.kit.stage_templates
from pxr import Usd

# Define a callback function to run after stage creation
def on_stage_created(stage, error_message=None):
    """Callback function to run after stage creation"""
    if error_message:
        print(f"Error creating stage: {error_message}")
        return
    
    print(f"Stage created with default prim: {stage.GetDefaultPrim().GetPath().pathString}")
    
    # You can perform additional setup on the stage here
    # For example, add metadata or properties
    stage.SetStartTimeCode(1)
    stage.SetEndTimeCode(100)

# Create a new stage with the "empty" template and our callback
stage = omni.kit.stage_templates.new_stage(
    on_new_stage_fn=on_stage_created,
    template="empty"  # Using the built-in empty template
)

# Alternative syntax using new_stage_with_callback
stage = omni.kit.stage_templates.new_stage_with_callback(
    on_new_stage_fn=on_stage_created,
    template="default stage"  # Using the built-in default stage template
)

---

Create Stage Asynchronously

import omni.kit.stage_templates
import asyncio
import omni.usd
from pxr import UsdGeom

async def create_and_modify_stage():
    # Create a new stage using the "sunlight" template asynchronously
    # This is useful when you need to wait for the stage to be created
    await omni.kit.stage_templates.new_stage_async(template="sunlight")
    
    # Get the context and stage after creation
    usd_context = omni.usd.get_context()
    stage = usd_context.get_stage()
    
    if stage:
        # Get the default prim path
        default_prim = stage.GetDefaultPrim()
        
        if default_prim:
            rootname = default_prim.GetPath().pathString
            
            # Add a new sphere to the stage
            sphere_path = f"{rootname}/Sphere"
            sphere = UsdGeom.Sphere.Define(stage, sphere_path)
            
            # Set sphere radius
            sphere.CreateRadiusAttr(5.0)
            
            print(f"Added sphere to stage at {sphere_path}")

# Run the async function
asyncio.ensure_future(create_and_modify_stage())

---

Load User Templates from File System

import omni.kit.stage_templates
import os
import carb

# Load user-defined templates from the file system
# This will scan template directories and execute any .py template scripts found
omni.kit.stage_templates.load_user_templates()

# You can check if your custom templates were loaded
custom_template_name = "my_custom_template"  # Replace with your template name
template = omni.kit.stage_templates.get_stage_template(custom_template_name)

if template:
    print(f"Found custom template: {template[0]}")
    
    # You can use the template to create a new stage
    stage = omni.kit.stage_templates.new_stage(template=custom_template_name)
else:
    print(f"Custom template '{custom_template_name}' not found")
    
    # Get template paths to see where user templates should be placed
    settings = carb.settings.get_settings()
    template_paths = settings.get("/persistent/app/newStage/templatePath")
    
    print("Template directories:")
    for path in template_paths:
        resolved_path = carb.tokens.get_tokens_interface().resolve(path)
        print(f"  - {resolved_path}")