Is this page helpful?

Configuration File Guide#

This guide describes how to configure the Isaac Sim Replicator Agent (IRA) for simulation and synthetic data generation. The configuration controls the environment, sensor generation and placement, character/robot agents, behaviors, and data generation.

Concepts and Workflow#

Before diving into detailed configuration, review the general workflow and key concepts of an IRA simulation.

Workflow Overview#

  1. Environment Setup: Define the static 3D environment where the simulation takes place.

  2. Agent & Sensor Definition: Configure characters, robots, and cameras (sensors) to populate the environment.

  3. Behavior Configuration: Assign routines (weighted random actions like walking, idling) and triggers (reactive behaviors like when a collision occurs) to actors. Alternatively, drive a group with a behavior tree instead of routines and triggers (experimental; available for both character and robot groups).

  4. Data Generation: Configure the Replicator writers to generate ground-truth data (RGB, segmentation).

Key Concepts#

  • Environment: The static 3D world (USD stage) loaded for the simulation. It also defines the NavMesh for navigation.

  • Agents (Actors): Dynamic entities in the scene, which can be Characters (humans) or Robots.

  • Behaviors: Atomic actions an actor can perform, such as wander, patrol, or idle.

  • Routines: A collection of behaviors assigned to an actor group. Actors randomly select behaviors from this pool based on assigned weights.

  • Triggers: Conditional logic that interrupts normal routines. When a condition is met (for example, a specific time or event), the trigger executes its defined list of behaviors in sequence. Once the trigger sequence is complete, the agent resumes its standard routine until another trigger activates.

  • Behavior Tree (experimental): An alternative to the routine-trigger system. A character or robot group may specify a behavior_tree JSON asset instead of routines / triggers; all of the group’s logic is then authored inside the tree. See Behavior Tree Character Group (Experimental) and Behavior Tree Robot Group (Experimental).

  • Sensors: Cameras placed in the scene to observe the simulation.

  • Replicator: The system responsible for rendering frames and writing annotated data (ground truth) to disk or cloud storage.

Top-level Structure#

Configs are YAML files with a single root key isaacsim.replicator.agent:

isaacsim.replicator.agent:
  version: 1.6.0
  environment: { ... }            # required
  seed: 123456789                 # optional; 32-bit (0..4294967295); autogenerated if omitted
  simulation_duration: 60.0       # optional; defaults to 60.0
  character: { ... }              # optional
  robot: { ... }                  # optional
  sensor: { ... }                 # optional
  replicator: { ... }             # optional

Root Parameters#

  • version (required): Semantic version of the configuration schema (for example, “1.0.0”).

  • environment (required): Defines the simulation world.

  • seed (optional): A 32-bit unsigned integer (0..4,294,967,295). - Used to initialize random number generators for deterministic simulations (for example, character spawn locations, routine variations). - If omitted, a seed is generated based on the current system time.

  • simulation_duration (optional): The total run time of the simulation in seconds (must be >= 0). - The simulation runs with the timeline’s per-tick dt set to 1/30 s and the application’s loop rate-limited to 30 Hz, giving an effective 30 FPS playback rate. - Defaults to 60.0 seconds.

  • character (optional): Configures human agents (appearance, behaviors like wander/patrol, and triggers).

  • robot (optional): Configures robot agents (config path, behaviors/commands, data collection).

  • sensor (optional): Configures static cameras using placement strategies (for example, aim at targets, coverage).

  • replicator (optional): Configures data writers (for example, output directory, annotators like RGB/segmentation).

Quick Start (Minimal)#

isaacsim.replicator.agent:
  version: 1.6.0
  environment:
    base_stage_asset_path: "Isaac/Environments/Simple_Warehouse/full_warehouse.usd"

Sections#

Environment#

Defines the static 3D environment and additional assets to load.

  • base_stage_asset_path (required): Path or URL to the main USD stage. - Supports http(s):// (including S3 presigned URLs), Windows/UNC paths, and local filesystem paths. - Also supports paths relative to the Isaac Sim Assets root.

  • prop_asset_paths (optional): A list of additional USD assets to load as sublayers into the stage. This is useful for adding props or lighting to a base environment without modifying it. Supports paths relative to the Isaac Sim Assets root.

Example:

environment:
  base_stage_asset_path: "Isaac/Environments/Simple_Warehouse/full_warehouse.usd"
  prop_asset_paths:
    - "Isaac/Props/Conveyors/ConveyorBelt_A08.usd"

Character#

Defines groups of human characters, their appearance, and their behavior.

  • root_prim_path (optional): Root path for spawning characters (default: /World/Characters).

  • motion_library_path (optional): Path to a custom motion library file. Supports paths relative to the Isaac Sim Assets root. Default: Isaac/People/MotionLibrary/HumanMotionLibrary.usd.

  • groups: Dictionary of character groups.

There are two types of Character Groups:

  • BaseCharacterGroup that define Behaviors on Routine-Trigger manners.

  • BehaviorTreeGroup (experimental) that receives a behavior tree json file.

Base Character Group#

Group Parameters#

  • num (required): Number of characters to spawn (>= 0).

  • asset_path (optional): USD path to character assets. Supports paths relative to the Isaac Sim Assets root. Default: Isaac/People/Characters/.

  • spawn_areas (optional): List of NavMesh area names where characters can spawn. If empty, spawns anywhere on the NavMesh.

  • semantic_labels (optional): List of [type, data] pairs for semantic segmentation. Default: [["class", "character"]].

  • routines (optional): List of behaviors the characters will execute. Default: [{ wander: {} }].

  • triggers (optional): List of event-based triggers that interrupt routines.

  • colliders (optional): List of colliders to be spawned under the characters.

Behaviors#

Behaviors are defined in the routines list. Common fields:

  • weight (default 1): Probability weight for selecting this behavior.

  • repeat (default 1): How many times to repeat this behavior before choosing a new one.

Supported Behaviors:

  1. wander: Randomly walk and idle.

    • walk: - speed_range: [min, max] m/s (default [1.0, 1.0]). - distance_range: [min, max] distance to travel per walk leg (default [5.0, 15.0]). - navigation_areas: List of allowed NavMesh area tags. Each entry must be a unique, non-empty string.

    • idle: Array of idle options. - animation: Name of the animation (must exist in motion lib). - time_range: [min, max] duration in seconds (default [2.0, 5.0]). - weight: Selection probability.

  2. patrol: Follow a specific path.

    • speed_range: [min, max] m/s (default [1.0, 1.0]).

    • Exactly one of (required): - path_points: List of 3D points [[x,y,z], [x,y,z], ...]. - target_prims: List of prim paths to visit.

      Note

      Both path_points and target_prims must be on the NavMesh and reachable by the actors.

  3. stop: Stop and idle in place for a random duration.

    • time_range: [min, max] duration in seconds (default [5.0, 5.0]).

Colliders#

Characters can define a list of colliders to spawn and attach under their root. These colliders are to be used together with collision_trigger (details in Trigger section below) to create scenarios where characters perform behaviors when they are entering or exiting other colliders.

When the following two types of colliders supported are spawned, the collider prim will be applied with PhysicsRigidBodyAPI, PhysicsCollisionAPI and PhysxTriggerAPI:

  • box: The collider from UsdGeom.Cube.

    • dimension: The dimension of the cube in x, y, z order (for example, [1.0, 1.0, 1.0]). Value type is Array.

  • cylinder: The collider from UsdGeom.Cylinder.

    • radius: The cylinder radius. Value type is Float.

../../_images/isim_6.0_full_ext-isaacsim.replicator.agent-6.0.0_viewport_IRA_box_collider.png

Box collider with size 2x2x2#
../../_images/isim_6.0_full_ext-isaacsim.replicator.agent-6.0.0_viewport_IRA_cylinder_collider.png

Cylinder collider with radius 1.5#

Each colldier also defines a name. This name will be translated into a custom USD String attribute metro:collider:name on the collider, to be used in self_collider or other_colliders from collision_trigger for collision filtering.

The spawned colliders will generate overlap events with other colliders that have PhysicsCollisionAPI. collision_trigger will further filter them by checking if they have the custom USD String attribute metro:collider:name.

However, Collision triggering between two characters will not be detected because Physx does not support triggering between two PhysxTriggerAPI.

The recommended workflow is to pre-define colliders in stage, adding metro:collider:name to them, then set up colliders and collision_trigger in the config file.

character:
  groups:
    Worker:
      asset_path: "Isaac/People/Characters/"
      num: 10
      colliders:
       # Spawn a cylinder collider for each worker
        - cylinder:
            name: worker_collider_0
            radius: 1.2
      triggers:
        # Worker will pause a few sceonds when it walks into colldiers with name "loading_zone" or "unloading_zone" in stage
        - collision_trigger:
            self_collider: worker_collider_0
            other_colliders: loading_zone;unloading_zone
            behavior:
              - stop:
                  time_range: [2.0, 4.0]

Triggers#

Triggers define events that interrupt normal routines to execute a list of reaction behavior.

Each actor can specify a list of triggers to listen to.

  • priority (default 1): Higher priority triggers override lower ones. Must be >= 1.

  • behavior: List of behaviors to execute in sequence when triggered.

Note

Every trigger variant is strict: unknown keys inside a trigger block fail validation.

Tip

Authoring a specific sequence of actions

Routines select behaviors randomly based on weights, so they are not suited for deterministic sequences. If you need actors to perform actions in a specific order (for example, walk to point A, idle for five seconds, then walk to point B), use a trigger instead. A trigger’s behavior list is always executed in order, making it the right tool for scripted sequences. Use a time_trigger with time: 0 to start the sequence immediately when the simulation begins.

Trigger Types:

  • event_trigger: Fires on a named carb event.

    • event: The carb event name. Value type is String; must be non-empty.

  • time_trigger: Fires after a specific time after play.

    • time: The time in seconds. Value type is Float; must be >= 0.

  • collision_trigger: Fires after a specific collider under this actor begins or ends overlapping with other colliders.

    • self_collider: The name of the collider on this actor to use (spawned by the colliders field in the group setting). Value type is String; must be non-empty.

    • other_colliders: (Optional) Semicolon-separated name list of other colliders to react to. Value type is String; defaults to "" (react to any collider on the overlap partner).

    • trigger_enter: (Optional) Trigger when entering the overlap. Value type is Boolean. Default is True.

    • trigger_exit: (Optional) Trigger when exiting the overlap. Value type is Boolean. Default is False.

    Tip

    Dispatching Events from Python

    # Send out a custom event named 'my_test_event'
import carb
carb.eventdispatcher.get_eventdispatcher().dispatch_event(event_name="my_test_event")

# Actors spawned by trigger setting will react to `my_test_event`.
# triggers:
#   - event_trigger:
#     event: my_test_event
#     priority: 10
#     behavior: [...]

Example:

character:
  root_prim_path: "/World/Characters"
  groups:
    warehouse_workers:
      asset_path: "Isaac/People/Characters/"
      num: 10
      spawn_areas: ["warehouse_floor"]
      routines:
        - wander:
            walk:
              speed_range: [0.8, 1.5]
              distance_range: [5.0, 10.0]
            idle:
              - animation: look_around
                time_range: [2.0, 5.0]
      triggers:
        - time_trigger:
            time: 30.0
            priority: 10
            behavior:
              - patrol: # Move to break room
                  speed_range: [1.0, 1.2]
                  target_prims: ["/World/BreakRoom"]
        - event_trigger:
            event: test_event
            priority: 10
            behavior:
              - patrol:
                  speed_range: [5.0, 5.5]
                  path_points:
                    - [0, 0, 0]
                    - [0, -5, 0]
        # Pause a few sceonds when it walks into colldiers with name "loading_zone" or "unloading_zone"
        - collision_trigger:
            self_collider: worker_sensing_collider
            other_colliders: loading_zone;unloading_zone
            behavior:
              - stop:
                  time_range: [2.0, 4.0]
      colliders:
        - cylinder:
            name: worker_sensing_collider  # A collider to represent the sensing range of the worker
            radius: 10.0

Behavior Tree Character Group (Experimental)#

Warning

Behavior tree character support is experimental and may change in future releases.

When a character group contains a behavior_tree key instead of routines and triggers, IRA treats it as a behavior-tree character group. In this mode, all behavior logic is defined inside the referenced behavior tree rather than through the IRA routine-trigger system.

A single configuration can mix both group types. For example, one group using IRA routines and another using a behavior tree.

Note

routines and triggers fields are not available for behavior-tree groups. Any reactive or conditional logic must be authored as nodes inside the behavior tree itself.

Behavior-Tree-Specific Parameters:

  • behavior_tree (required): Path or URL to a JSON behavior tree asset. Supports Isaac asset-root-relative paths (for example, Isaac/...), absolute filesystem paths, and paths relative to the config file directory. The tree must reference node libraries such as omni.behavior.tree.core and omni.anim.behavior.tree.

  • overrides (optional): A YAML multi-line string containing JSON that overrides node port values at runtime without modifying the original tree file. The JSON follows the omni.behavior.tree override schema with schemaVersion and instanceOverrides keys. Refer to the Behavior Tree’s User Guide for more details on instance overrides.

Shared Parameters (same as IRA character groups):

  • num (required): Number of characters to spawn (>= 0).

  • asset_path (optional): USD path to character assets. Default: Isaac/People/Characters/.

  • spawn_areas (optional): List of NavMesh area names where characters can spawn.

  • semantic_labels (optional): List of [type, data] pairs. Default: [["class", "character"]].

  • motion_library_path (optional): Path to a custom motion library file.

  • colliders (optional): List of collider objects for the character group.

Minimal Example:

character:
  groups:
    bt_workers:
      num: 3
      asset_path: "Isaac/People/Characters/"
      behavior_tree: ../sample_behavior_tree/character_wander.json

Example with Overrides:

The overrides field is a JSON string (written as a YAML multi-line block scalar with |) that lets you adjust node parameters per-group without editing the tree file. The JSON structure has two keys:

  • schemaVersion (required): Must be "2.0.0".

  • instanceOverrides (required): A dictionary mapping node paths (for example, /Root/MoveTo:RandomNavMeshPoint) to port overrides, which is a dictionary of port name to its type and overriden value.

For example, to change the wander radius of a RandomNavMeshPoint modifier node:

character:
  groups:
    bt_workers:
      num: 3
      asset_path: "Isaac/People/Characters/"
      behavior_tree: ../sample_behavior_tree/character_wander.json
      overrides: |
        {
          "schemaVersion": "2.0.0",
          "instanceOverrides": {
            "/Root/MoveTo:RandomNavMeshPoint": {
              "radius": {
                "type": "carb::Float2",
                "value": [2.0, 10.0]
              }
            }
          }
        }

Mixed Configuration Example (IRA + Behavior Tree):

character:
  root_prim_path: "/World/Characters"
  groups:
    ira_wanderers:
      num: 5
      routines:
        - wander:
            walk:
              speed_range: [0.8, 1.5]
    bt_patrol_group:
      num: 3
      behavior_tree: ../sample_behavior_tree/character_wander.json

Robot#

Defines robot agents.

  • root_prim_path (optional): Root path for robots (default: /World/Robots).

  • groups: Dictionary of robot groups.

Robot Group Parameters#

  • num (required): Number of robots (>= 1).

  • config_file_path (required): Path to the robot agent YAML configuration file for this robot type. Supports absolute paths or paths relative to the built-in sample config folder (data/sample_configs/ within the isaacsim.anim.robot.core extension).

  • spawn_areas (optional): NavMesh areas for spawning.

  • agent_radius (optional): Radius in meters used for NavMesh queries. Must be > 0 when set. If omitted, defaults to 0.5 at runtime.

  • write_data (optional): If true, enables data collection from the robot’s onboard cameras.

  • camera_prim_paths (optional): List of specific camera prims on the robot to use. If empty and write_data is true, all cameras on the robot are used. Requires write_data to be true.

  • semantic_labels (optional): Default [["class", "robot"]].

  • semantic_label_path (optional): Relative path under the robot prim to apply semantics.

  • routines (optional): List of robot behaviors. Default: [{ wander: {} }].

  • triggers (optional): List of triggers that interrupt routines. Robots support event_trigger, time_trigger, and collision_trigger.

  • colliders (optional): List of colliders to spawn and attach under each robot (same schema as character colliders; refer to the Colliders section). Used together with collision_trigger to drive behaviors when the robot enters or exits other colliders.

Robot Behaviors#

  • wander: - move: { distance_range: [min, max] (default [10.0, 15.0]), navigation_areas: list of allowed NavMesh area tags, each entry must be a unique, non-empty string (default []) } - idle: { time_range: [min, max] (default [2.0, 5.0]) }

  • patrol (exactly one of path_points or target_prims is required): - path_points: List of 3D points [[x,y,z], [x,y,z], ...]. - target_prims: List of prim paths to visit.

    Note

    Both path_points and target_prims must be on the NavMesh and reachable by the robots.

  • halt: - time_range: [min, max] seconds to remain halted (default [5.0, 5.0]).

Behavior Tree Robot Group (Experimental)#

Warning

Behavior tree robot support is experimental and may change in future releases.

When a robot group contains a behavior_tree key instead of routines and triggers, IRA treats it as a behavior-tree robot group. In this mode, all behavior logic is defined inside the referenced behavior tree rather than through the IRA routine-trigger system, and the robot is driven by Animated Robot Behavior Tree Nodes (RobotMoveTo, RobotTurn, RobotIdle, RobotPlayAnimation, and the RobotIsInState modifier).

A single configuration can mix both group types. For example, one routine-driven group and another behavior-tree-driven group.

Note

routines, triggers, and colliders are not available for behavior-tree robot groups. Any reactive or conditional logic must be authored as nodes inside the behavior tree itself.

Behavior-Tree-Specific Parameters:

  • behavior_tree (required): Path or URL to a JSON behavior tree asset. Supports Isaac asset-root-relative paths (for example, Isaac/...), absolute filesystem paths, and paths relative to the config file directory.

  • overrides (optional): A YAML multi-line string containing JSON that overrides node port values at runtime without modifying the original tree file. Follows the omni.behavior.tree override schema (schemaVersion + instanceOverrides); see Behavior Tree Character Group (Experimental) for an example.

Shared Parameters (same as IRA robot groups):

  • num (required): Number of robots to spawn (>= 1).

  • config_file_path (optional): Path to the per-robot agent YAML (default: nova_carter.yaml).

  • spawn_areas (optional): List of NavMesh area names where robots can spawn.

  • agent_radius (optional): NavMesh query radius in meters (must be > 0 when set).

  • semantic_labels (optional): Default [["class", "robot"]].

  • semantic_label_path (optional): Relative path under the robot prim to apply semantics.

Minimal Example:

robot:
  groups:
    bt_carters:
      num: 2
      config_file_path: nova_carter.yaml
      behavior_tree: ../sample_behavior_tree/robot_wander.json

Sensor#

Defines static cameras in the scene. Cameras are organized into named groups.

  • root_prim_path (optional): Absolute prim path where all camera groups will be created (default: /World/Cameras).

  • groups: A dictionary where keys are group names and values define the camera configuration.

Group Configuration#

Each group must specify num (number of cameras) and one placement strategy (aim_at_targets OR maximum_coverage). - For aim_at_targets, num must be >= 0. - For maximum_coverage, num can be >= -1. If -1, the number of cameras is automatically calculated based on the grid resolution and coverage ratio.

1. Placement Strategy: aim_at_targets

Places cameras to look at specific targets.

  • targets (optional): List of target prim paths (for example, /World/Characters) or identifiers.

  • raycast_density (optional): Density of rays used to find valid camera positions. Higher values are more precise but slower.

  • yaw_range (optional): [min, max] degrees (0..360) for the camera’s rotation around the target.

  • occlusion_threshold (optional): Threshold for filtering occluded views (-1 to disable).

2. Placement Strategy: maximum_coverage

Places cameras to maximize visual coverage of the environment.

  • target_coverage_ratio (optional): Desired coverage ratio (0.0 to 1.0). Default 0.9.

  • grid_resolution (optional): Size of the grid cells (in meters) used for coverage calculation. Default 1.0.

Shared Parameters

These apply to all placement strategies:

  • height_range: [min, max] height in meters (Z-axis).

  • look_down_angle_range: [min, max] pitch angle in degrees (0 = horizontal, 90 = straight down).

  • focal_length_range: [min, max] focal length in millimeters.

  • distance_range: [min, max] distance from the camera to its target or interest point in meters.

Example:

sensor:
  root_prim_path: "/World/Cameras"
  groups:
    ceiling_cameras:
      num: 20
      aim_at_targets:
        targets: ["/World/Characters"]
        distance_range: [5, 10]
        height_range: [7, 10]
        focal_length_range: [10, 15]
        look_down_angle_range: [30, 45]
    coverage_cameras:
      num: 5
      maximum_coverage:
        target_coverage_ratio: 0.8
        height_range: [2, 5]

Replicator#

Controls the generation of synthetic data (images, annotations) using Omniverse Replicator.

  • writers (required): Dictionary of writer configurations.

  • hide_debug_visualization (optional, default true): Hides debug visualizations (NavMesh, skeletons, lights) during data capture.

Writer Configuration#

Supported writers: IRABasicWriter, CosmosIRAWriter, SceneGraphWriter, CustomWriter.

Note

In previous releases, the stock Replicator BasicWriter appeared as its own entry in the Add Writer dropdown and could be used directly as a writer key (for example, BasicWriter:). Starting with version 1.6.1 of isaacsim.replicator.agent.core, BasicWriter has been removed from the UI dropdown and is no longer accepted as a top-level writer key in the configuration. If you need the stock BasicWriter, use a CustomWriter entry with writer_name: "BasicWriter" instead. Refer to the CustomWriter section below for details.

Common Settings per Writer:

  • Timing: - start_frame / end_frame: Frame-based control (inclusive/exclusive). Defaults to start_frame: 30 if not specified. - start_time / end_time: Time-based control (seconds).

  • Sensors: - sensor_prim_list: Optional list of cameras to use. If omitted, uses all cameras defined in sensor.root_prim_path.

Output Settings:

  • output_dir: Local directory for output. Defaults to ~/IRA_output if not set.

  • s3_bucket, s3_region, s3_endpoint: For direct S3 upload.

Common Annotators (Parameters):

  • rgb: RGB Image.

  • bounding_box_2d_tight / loose: 2D Bounding boxes.

  • bounding_box_3d: 3D Bounding boxes.

  • semantic_segmentation: Pixel-wise semantic class IDs.

  • instance_segmentation: Pixel-wise instance IDs.

  • distance_to_camera: Depth map.

  • normals: Surface normals.

  • motion_vectors: Pixel motion.

  • colorize_*: For example, colorize_semantic_segmentation (save as visible color map compaired to raw ID).

Specialized Writers#

  1. IRABasicWriter:

    The foundational writer for Agent simulations, derived from Replicator’s BasicWriter. It organizes output into separate folders per annotator and consolidates object and agent metadata into object_detection.json.

    • Key Features:

      • Folder Structure: Outputs each annotator’s data into separate folders for better readability.

      • Object Detection: Consolidates bounding box and skeleton data into a single file named object_detection.json.

      • Default Semantic Filter: class:character|robot;id:* (captures characters and robots).

      • Action data output: When object detection is enabled (object_info or agent_info annotators are on), the action data for each IRA actor will be included as well.

    • Overwritten Annotators: The following standard annotators are replaced by specialized object_info_* versions and written to object_detection.json:

      • bounding_box_2d_tight

      • bounding_box_2d_loose

      • bounding_box_3d

      • skeleton_data (replaced by agent_info_skeleton_data)

    • Defaults:

      • rgb: Enabled.

      • camera_params: Enabled.

      • S3-related parameters: Disabled.

    • Special Parameters:

      • video_rendering_annotator_list: Generates .mp4 videos for specified annotators (for example, ["rgb", "semantic_segmentation"]).

      • agent_info_skeleton_data: Exports 2D/3D skeleton joints for characters.

    • Action data:

      Action data is for describing the current behavior of each actor. It is in object_detection.json under the metro_agent_data section. Data includes:

      • prim path: The prim path of the actor schema is applied.

      • agent_type: The actor schema type.

      • agent_name: The name of the actor.

      • agent_group: The group name of the actor.

      • world_position: Actor position (vec3) in world space.

      • world_rotation: Actor rotation (quaternion) in world space.

      • world_moving_direction: Actor moving direction (vec3) in world space. null means actor is not moving.

      • world_facing_direction: Actor facing direction (vec3) in world space.

      • speed: The actor moving speed.

      • current_task_name: Actor’s current action name (not behavior name).

      • asset_url: The asset URL of the actor.

    IRABasicWriter example:

    replicator:
  writers:
    IRABasicWriter:
      output_dir: "<your_output_directory>"
      start_frame: 0
      end_frame: 300
      rgb: true
      camera_params: true
      bounding_box_2d_tight: true
      semantic_segmentation: true
      agent_info_skeleton_data: true
      video_rendering_annotator_list: ["rgb", "semantic_segmentation"]

  2. CosmosIRAWriter:

    • Adds “Cosmos” Specific post-processing.

    • shaded_seg: Shaded segmentation visualization.

    • canny_edge: Canny edge detection filter (with canny_threshold_low/high).

  3. SceneGraphWriter:

    Writes per-frame scene captions alongside the standard output. This writer is provided by the Isaacsim.Replicator.Caption extension; for configuration and a complete example, refer to Use Isaacsim.Replicator.Caption in Isaacsim.Replicator.Agent.

  4. CustomWriter:

    A flexible wrapper that delegates to any writer registered in omni.replicator.core.WriterRegistry. Use CustomWriter when you want to use a third-party writer, a writer from another extension, or your own omni.replicator.core.Writer subclass without modifying the IRA codebase.

    • Required parameters:

      • writer_name (string, required): The registry name of the target writer (for example, "BasicWriter", "KittiWriter", or a user-defined name). Any writer registered in WriterRegistry can be referenced here, including the stock Replicator BasicWriter.

    • Optional parameters:

      • writer_scope (string, optional): A flexible field for discovering and registering writers that are not yet in the WriterRegistry. It accepts three input modes, auto-detected by the system:

        • Package or module path (for example, "omni.replicator.core"): scans all submodules for concrete Writer subclasses and batch-registers them.

        • Full class path (for example, "my_extension.writers.MyWriter"): imports and registers a single specific writer class.

        • Filesystem path to a .py file (for example, "<path/to/your_writers.py>"): loads the file and registers all Writer subclasses defined in it.

        Use writer_name to select the specific writer from the discovered set.

    • Additional parameters: All other key-value pairs in the YAML block are passed directly to the target writer’s initialize(**kwargs) call. Only parameters you explicitly list override the writer’s built-in defaults; unlisted parameters keep the writer’s own default values.

    How parameter discovery works

    When a CustomWriter entry is loaded, the system introspects the target writer’s __init__ signature to discover all accepted parameters along with their types and default values. A typed Pydantic model is dynamically generated from this signature, which enables:

    • Type validation: Supplied parameter values are checked against the writer’s expected types before the simulation starts.

    • UI integration: In the Configuration Editor UI, each discoverable parameter appears as an addable field with the correct widget type. Click Add Parameter to override a default, or remove a parameter to revert to the writer’s own default.

    Parameters whose types cannot be represented in JSON (for example, custom backend objects) are excluded from the dynamic model and the UI but can still be passed in YAML.

    Note

    Some writers accept width and height parameters that configure the writer’s output dimensions but do not modify the underlying RenderProduct resolution. To change the actual rendered resolution, first adjust the RenderProduct Resolution in the CustomWriter UI panel, then set the writer’s width and height parameters to match.

    Auto-registration using writer scope

    If the writer class is not yet in the WriterRegistry when the config is loaded, provide writer_scope to have IRA discover and register it automatically. The system auto-detects which mode to use based on the value:

    • File path (contains /, \, or ends with .py): loads the .py file from disk and registers all Writer subclasses found in it.

    • Single class path (last segment starts with an uppercase letter, for example "my_extension.writers.MyWriter"): imports and registers that one class.

    • Package scan (for example "omni.replicator.core"): recursively walks the package and registers all concrete Writer subclasses.

    Already-registered writers are skipped silently. After resolution, select the target writer using the writer_name field.

    If writer_scope is omitted, the writer must already be registered (for example, by enabling the extension that provides it).

    Using CustomWriter in the UI

    When adding a CustomWriter through the Configuration Editor:

    1. Click Add Writer and select CustomWriter from the type list.

    2. A dedicated dialog appears with two fields:

      • Writer Name: A dropdown listing all writers currently in the WriterRegistry. Select the target writer.

      • Writer Scope: An optional text field that accepts a package path, a dotted class path, or a filesystem path to a .py file. Click Register to discover, validate, and register writers from the scope, which also refreshes the Writer Name dropdown.

    3. Click OK to confirm. The editor displays the writer’s name as a read-only label and lists all currently set parameters with their values.

    4. Use the Add Parameter dropdown at the bottom to override additional defaults from the writer’s __init__ signature.

    Important

    Always click OK to confirm after selecting or registering a writer. The CustomWriter is not added until you confirm the dialog.

    Note

    The Writer Scope field in the UI replaces the former Class Path field. It accepts all three input modes (package path, class path, and file path) and the system auto-detects which mode to use.

    Note

    Parameter names displayed in the UI are derived automatically from the writer’s __init__ signature (for example, sensorSetName in RTSPStreamWriter). Because users can import custom or third-party writers, no specific naming format is enforced. The UI capitalizes the first letter of each name for readability (for example, sensorSetName appears as SensorSetName), but the original name is used when passing values to the writer.

    Multiple CustomWriter instances

    You can configure multiple CustomWriter entries in the same config. Append a numeric suffix to create unique keys:

    replicator:
  writers:
    CustomWriter:
      writer_name: "<your_writer_name>"
      <writer_param>: <your_value>
    CustomWriter_1:
      writer_name: "<your_other_writer_name>"
      <writer_param>: <your_value>

    The suffix (_1, _2, and so on) is stripped when resolving the writer type; the writer_name field determines which registry writer is used.

    For a step-by-step walkthrough that uses CustomWriter to set up live RTSP streaming, refer to Example: RTSP streaming with CustomWriter.

    CustomWriter examples:

    # Use a registered writer, overriding only specific defaults
replicator:
  writers:
    CustomWriter:
      writer_name: "<your_writer_name>"
      <writer_param>: <your_value>

    # Auto-register a writer class by its dotted import path
replicator:
  writers:
    CustomWriter:
      writer_name: "<your_writer_name>"
      writer_scope: "<your_package.module.ClassName>"
      <writer_param>: <your_value>

    # Discover all writers from a package
replicator:
  writers:
    CustomWriter:
      writer_name: "<your_writer_name>"
      writer_scope: "<your_package>"
      <writer_param>: <your_value>

    # Load writers from a standalone .py file
replicator:
  writers:
    CustomWriter:
      writer_name: "<your_writer_name>"
      writer_scope: "<path/to/your_writers.py>"
      <writer_param>: <your_value>