[isaacsim.asset.transformer] Isaac Sim Asset Transformer#

Version: 1.2.3

Overview#

The isaacsim.asset.transformer extension provides the core framework for transforming USD assets through configurable rule pipelines. It defines the rule interface, profile model, rule registry, and execution manager that orchestrate ordered sequences of transformation rules over USD stages.

Key Components#

RuleInterface#

Abstract base class that all transformation rules must subclass. A rule receives a source Usd.Stage, a package root directory, a destination path, and a parameter dictionary. Subclasses implement process_rule() to read from the source stage, write opinions to destination layers, and optionally return a new stage path for subsequent rules in the pipeline.

RuleRegistry#

A singleton registry that maps fully qualified rule class names to their implementation classes. Rules register themselves on extension startup (typically in isaacsim.asset.transformer.rules) and are resolved by the manager at execution time.

AssetTransformerManager#

Coordinates the execution of a RuleProfile against a USD stage. The manager:

Opens the input stage and creates a flattened base layer in the output package
Collects external asset dependencies into the package directory
Canonicalizes orientation quaternions for deterministic output
Iterates through enabled rules in profile order, instantiating each rule class and calling process_rule()
Supports mid-pipeline stage replacement when a rule returns a new stage path
Produces an ExecutionReport with per-rule logs, affected stages, and success/error status

Data Models#

RuleSpec — Specification for a single rule: type, display name, destination path, parameters, and enabled flag
RuleProfile — Ordered collection of RuleSpec entries plus global settings (output root, base name, flatten option)
RuleConfigurationParam — Descriptor for a rule’s configurable parameter (name, type, default, description)
ExecutionReport / RuleExecutionResult — Structured output from a profile run, including timing, logs, and error details

Usage#

from isaacsim.asset.transformer import AssetTransformerManager, RuleProfile

manager = AssetTransformerManager()
profile = RuleProfile.from_json("path/to/profile.json")
report = manager.run("input.usd", profile, package_root="/tmp/output")

for result in report.results:
    print(f"{result.rule.name}: {'OK' if result.success else result.error}")

Enable Extension#

The extension can be enabled (if not already) in one of the following ways:

Command-line interface

Define the next entry as an application argument from a terminal.

APP_SCRIPT.(sh|bat) --enable isaacsim.asset.transformer

Experience/extension configuration

Define the next entry under [dependencies] in an experience (.kit) file or an extension configuration (extension.toml) file.

[dependencies]
"isaacsim.asset.transformer" = {}

Extension Manager UI

Open the Window > Extensions menu in a running application instance and search for isaacsim.asset.transformer. Then, toggle the enable control button if it is not already active.

Python API#

models

`RuleConfigurationParam`	Descriptor for a single rule configuration parameter.
`RuleSpec`	Specification for a single rule in a profile.
`RuleProfile`	Collection of rules and metadata for a transformation run.
`RuleExecutionResult`	Outcome of running a single rule.
`ExecutionReport`	Report for a full transformation run.

rule_interface

RuleInterface

Abstract base class for asset transformation rules.

manager

`RuleRegistry`
`AssetTransformerManager`	Coordinates execution of a `RuleProfile` over USD stages.

Models#

class RuleConfigurationParam( name: str, display_name: str, param_type: type, description: str | None = None, default_value: object | None = None, )#

Bases: object

Descriptor for a single rule configuration parameter.

Parameters:

name – Unique parameter name.
display_name – Human-readable label.
param_type – Expected Python type for the parameter.
description – Optional description of the parameter.
default_value – Default value for the parameter.

default_value: object | None = None#: Default value for the parameter.

description: str | None = None#: Optional description of the parameter.

display_name: str#

name: str#

param_type: type#

class RuleSpec( name: str, type: str, destination: str | None = None, params: dict[str, ~typing.Any] = <factory>, enabled: bool = True, )#

Bases: object

Specification for a single rule in a profile.

Parameters:

name – Rule display name.
type – Fully qualified rule class path.
destination – Optional output path override.
params – Rule parameter overrides.
enabled – Whether the rule is active.

static from_dict( data: dict[str, Any], ) → RuleSpec#

Create a RuleSpec from a dictionary.

Parameters:: data – Mapping with rule fields.
Returns:: Parsed RuleSpec instance.
Raises:: ValueError – If required fields are missing.

Example:

spec = RuleSpec.from_dict(
    {"name": "MoveMeshes", "type": "my.rule.Class", "params": {"scope": "/World"}}
)

to_dict() → dict[str, Any]#

Convert this specification to a plain dictionary.

Returns:: Dictionary suitable for JSON serialization.

Example:

>>> spec = RuleSpec(
...     name="MoveMeshes",
...     type="isaacsim.asset.transformer.rules.perf.geometries.GeometriesRoutingRule",
...     params={"scope": "/World"},
... )
>>> isinstance(spec.to_dict(), dict)
True

destination: str | None = None#: Optional output path override.

enabled: bool = True#: Whether the rule is active.

name: str#

params: dict[str, Any]#

type: str#

class RuleProfile( profile_name: str, version: str | None = None, rules: list[~isaacsim.asset.transformer.models.RuleSpec] = <factory>, interface_asset_name: str | None = None, output_package_root: str | None = None, flatten_source: bool = False, base_name: str | None = None, )#

Bases: object

Collection of rules and metadata for a transformation run.

Parameters:

profile_name – Display name for the profile.
version – Optional profile version string.
rules – Rule specifications to execute.
interface_asset_name – Optional interface asset identifier.
output_package_root – Optional output root for packages.
flatten_source – Whether to flatten source stages before rules.
base_name – Optional base name for generated outputs.

static from_dict( data: dict[str, Any], ) → RuleProfile#

Parse a RuleProfile from a dictionary.

Parameters:: data – Mapping with profile fields.
Returns:: Parsed RuleProfile instance.
Raises:: ValueError – If required fields are missing.

Example:

profile = RuleProfile.from_dict({"profile_name": "Default", "rules": []})

static from_json( json_str: str, ) → RuleProfile#

Parse a RuleProfile from a JSON string.

Parameters:: json_str – JSON payload encoding a profile.
Returns:: Parsed RuleProfile instance.

Example:

profile = RuleProfile.from_json('{"profile_name":"Default","rules":[]}')

to_dict() → dict[str, Any]#

Serialize profile to a dictionary.

Returns:: Dictionary suitable for JSON serialization.

Example:

payload = profile.to_dict()

to_json() → str#

Serialize profile to a deterministic JSON string.

Returns:: JSON string with sorted keys and no trailing spaces.

Example:

json_str = profile.to_json()

base_name: str | None = None#: Optional base name for generated outputs.

flatten_source: bool = False#: Whether to flatten source stages before rules.

interface_asset_name: str | None = None#: Optional interface asset identifier.

output_package_root: str | None = None#: Optional output root for packages.

profile_name: str#

rules: list[RuleSpec]#

version: str | None = None#: Optional profile version string.

class RuleExecutionResult( rule: ~isaacsim.asset.transformer.models.RuleSpec, success: bool, log: list[dict[str, ~typing.Any]] = <factory>, affected_stages: list[str] = <factory>, error: str | None = None, started_at: str = <factory>, finished_at: str | None = None, )#

Bases: object

Outcome of running a single rule.

Parameters:

rule – Rule specification that was executed.
success – Whether the rule completed successfully.
log – Log entries recorded during execution.
affected_stages – Identifiers of affected stages.
error – Error message if the rule failed.
started_at – Start timestamp in ISO format.
finished_at – Finish timestamp in ISO format.

close() → None#

Mark the result as finished by setting the finished_at timestamp.

Example:

result.close()

affected_stages: list[str]#

error: str | None = None#: Error message if the rule failed.

finished_at: str | None = None#: Finish timestamp in ISO format.

log: list[dict[str, Any]]#

rule: RuleSpec#

started_at: str#

success: bool#

class ExecutionReport( profile: ~isaacsim.asset.transformer.models.RuleProfile, input_stage_path: str, package_root: str, started_at: str = <factory>, finished_at: str | None = None, results: list[~isaacsim.asset.transformer.models.RuleExecutionResult] = <factory>, output_stage_path: str | None = None, )#

Bases: object

Report for a full transformation run.

Parameters:

profile – Profile used for the run.
input_stage_path – Path to the input stage.
package_root – Package output root path.
started_at – Start timestamp in ISO format.
finished_at – Finish timestamp in ISO format.
results – Rule execution results.
output_stage_path – File path of the final working stage after all rules have executed. Callers can use this to load the transformed asset.

close() → None#

Mark the report as finished by setting the finished_at timestamp.

Example:

report.close()

to_dict() → dict[str, Any]#

Serialize the report to a dictionary suitable for JSON.

Returns:: Dictionary with execution details.

Example:

payload = report.to_dict()

to_json() → str#

Serialize the report to a deterministic JSON string.

Returns:: JSON string with sorted keys and compact separators.

Example:

json_str = report.to_json()

finished_at: str | None = None#: Finish timestamp in ISO format.

input_stage_path: str#

output_stage_path: str | None = None#: File path of the final working stage after all rules have executed. Callers can use this to load the transformed asset.

package_root: str#

profile: RuleProfile#

results: list[RuleExecutionResult]#

started_at: str#

Rule Interface#

class RuleInterface( source_stage: pxr.Usd.Stage, package_root: str, destination_path: str, args: dict[str, Any], )#

Bases: ABC

Abstract base class for asset transformation rules.

Implementations operate on a source pxr.Usd.Stage and may write opinions to a destination pxr.Usd.Stage. Subclasses should record human-readable log messages and any identifiers for stages or layers they affect so the manager can produce comprehensive reports.

Rules may request a stage replacement by returning a stage identifier (file path) from process_rule(). The manager will open the new stage and use it for subsequent rules in the pipeline.

Stage mutation contract:

args["input_stage"] is informational only and must be treated as read-only in every respect, including its session layer. Rules that need to author overrides while reading from the original input must open a private Usd.Stage from args["input_stage_path"] and author into that stage’s session layer; they must not write to either layer of any caller-owned Stage.

Two reasons for this:

args["input_stage"] may be a caller-owned Stage (e.g. the editor’s active Stage). Its session layer commonly carries user-driven overrides such as visibility toggles, purpose settings, and camera opinions; rule authoring or cleanup there would corrupt user state.
The root pxr.Sdf.Layer of an input opened by path is shared via USD’s process-wide layer cache with every Stage observing the same file – including the editor’s active Stage when the user runs the transformer on the open stage. Authoring to that root layer (or calling Reload() on it) fires change notifications on the editor’s Stage that have been observed to invalidate Hydra render product prims mid-frame and crash the renderer.

Parameters:

source_stage – Input stage providing opinions to read from.
package_root – Root directory for output files.
destination_path – Relative path for rule outputs.
args – Mapping of parameters including keys such as destination and params.

add_affected_stage(stage_identifier: str) → None#

Record an identifier for a stage or layer affected by this rule.

Parameters:: stage_identifier – Logical label, file path, or layer id that was created, modified, or otherwise affected by the rule.

Example:

rule.add_affected_stage("/tmp/output.usda")

get_affected_stages() → list[str]#

Return identifiers for stages or layers affected by this rule.

Returns:: List of unique identifiers provided via add_affected_stage().

Example:

affected = rule.get_affected_stages()

abstract get_configuration_parameters() → list[RuleConfigurationParam]#

Return the configuration parameters for this rule.

Returns:: List of configuration parameters.

Example:

params = rule.get_configuration_parameters()

get_operation_log() → list[str]#

Return the accumulated operation log messages.

Returns:: List of log message strings in chronological order.

Example:

messages = rule.get_operation_log()

log_operation(message: str) → None#

Append a human-readable message to the operation log.

Parameters:: message – Message to record in the rule execution log.

Example:

rule.log_operation("Copied prim /World")

abstract process_rule() → str | None#

Execute the rule logic.

This method must be implemented by subclasses. Implementations should emit log messages via log_operation() and record any affected stage or layer identifiers via add_affected_stage().

Returns:: The file path of the stage to be used by subsequent rules. Return None if the current working stage should continue to be used. If a path is returned and differs from the current working stage, the manager will open the new stage for subsequent rules.

Example:

from pxr import Usd
from isaacsim.asset.transformer import RuleInterface

class NoOpRule(RuleInterface):
    def process_rule(self) -> None:
        self.log_operation("noop")

stage = Usd.Stage.CreateInMemory()
NoOpRule(stage, "/tmp", "", {"destination": "out.usda"}).process_rule()

Manager#

RuleRegistry#: alias of getinstance

class AssetTransformerManager(registry: RuleRegistry | None = None)#

Bases: object

Coordinates execution of a RuleProfile over USD stages.

The manager creates a flattened and collected copy of the input stage at {package_root}/base.usda. External assets are copied to {package_root}/assets/ with paths updated to local references. All rules execute against this self-contained working copy.

Parameters:: registry – Optional registry instance. Currently ignored in favor of the global singleton registry.

run( input_stage: str | Usd.Stage, profile: RuleProfile, package_root: str | None = None, ) → ExecutionReport#

Execute a rule profile against a USD stage and return an execution report.

Parameters:

input_stage – Path to the source USD stage or layer, or an already-opened pxr.Usd.Stage. When a stage object is passed it is used directly and its root layer path is used as the internal input_stage.
profile – Rule profile specifying ordered rules to run.
package_root – Destination root directory for outputs.

Returns:

Execution report including per-rule logs and status.

Raises:

KeyError – If a rule type is not registered.
RuntimeError – If stage loading or export fails.

Example:

manager = AssetTransformerManager()
report = manager.run("input.usd", profile, package_root="/tmp/package")

property registry: getinstance#

Return the singleton rule registry.

Returns:: The manager’s internal RuleRegistry instance.

Example:

registry = manager.registry

Python API

[isaacsim.asset.transformer] Isaac Sim Asset Transformer#

Overview#

Key Components#

RuleInterface#

RuleRegistry#

AssetTransformerManager#

Data Models#

Usage#

Related Extensions#

Enable Extension#

Python API#

Models#

Rule Interface#

Manager#