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

Version: 1.0.3

Python-only extension providing asset transformation utilities

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.

API#

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: Any, description: str | None = None, default_value: Any = 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: Any = None#

description: str | None = None#

display_name: str#

name: str#

param_type: Any#

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#

enabled: bool = True#

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#

flatten_source: bool = False#

interface_asset_name: str | None = None#

output_package_root: str | None = None#

profile_name: str#

rules: list[RuleSpec]#

version: str | None = None#

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#

finished_at: str | None = None#

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#

input_stage_path: str#

output_stage_path: str | None = None#

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.

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_path: str, profile: RuleProfile, package_root: str | None = None, ) → ExecutionReport#

Execute a profile from an input stage path and return an execution report.

Parameters:

input_stage_path – Path to the source USD stage or layer.
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.

Example:

registry = manager.registry