Event Functors

Event Functors#

This page lists all available event functors that can be used with the Event Manager. Event functors are configured using EventCfg and can be triggered at different stages: startup, reset, or interval.

Tip

Using an AI coding agent? Use the /add-functor skill to scaffold a new event or randomization functor with the correct signature (env, env_ids, ...), function or class style, and module placement. Use /add-test to generate mock-based tests.

Physics Randomization#

Physics Randomization Functors#

Functor Name

Description

randomize_rigid_object_mass()

Randomize object masses within a specified range. Supports both absolute and relative mass randomization.

{"func": "randomize_rigid_object_mass", "mode": "reset",
 "params": {"entity_cfg": {"uid": "bottle"},
            "mass_range": [0.01, 0.1], "relative": false}}

randomize_rigid_object_center_of_mass()

Randomize the center of mass of rigid objects by applying position offsets. Only works with dynamic objects.

{"func": "randomize_rigid_object_center_of_mass", "mode": "reset",
 "params": {"entity_cfg": {"uid": "bottle"},
            "com_range": [[-0.01, -0.01, -0.01], [0.01, 0.01, 0.01]]}}

randomize_articulation_mass()

Randomize articulation link masses within a specified range. Supports regex-based link selection via the link_names parameter, and both absolute and relative mass randomization.

{"func": "randomize_articulation_mass", "mode": "reset",
 "params": {"entity_cfg": {"uid": "CobotMagic"},
            "mass_range": [0.8, 1.2], "relative": true,
            "link_names": ".*link.*"}}

Visual Randomization#

Visual Randomization Functors#

Functor Name

Description

randomize_visual_material

Randomize textures, base colors, and material properties (metallic, roughness, IOR) for rigid objects and articulations. The default path retains each asset’s original material instance and creates a working instance from the same material template; randomization swaps the render body between those instances without creating a new VisualMaterial template.

{"func": "randomize_visual_material",
 "mode": "interval", "interval_step": 10,
 "params": {"entity_cfg": {"uid": "table"},
            "texture_path": "CocoBackground/coco",
            "p_original": 0.2,
            "p_library": 0.5,
            "p_solid": 0.3,
            "solid_texture_count": 32,
            "shared": false,
            "base_color_range": [[0.2, 0.2, 0.2], [1.0, 1.0, 1.0]]}}

p_original, p_library, and p_solid select the original instance, a library texture on the working instance, or a solid-color texture on the working instance. When all three are omitted, the defaults are 0, random_texture_prob, and 1 - random_texture_prob; the default random_texture_prob is 0.5. If no texture library is loaded, the library probability is added to the solid probability. Explicit probabilities are normalized, and any omitted member of an explicit set is treated as zero.

Rigid-object mesh segments share one working instance per environment. Articulations use one working instance and sample one tier per selected link. Set shared=true to reuse one state, plan, and link-tier selection across all environments. Solid textures come from a bounded palette created during initialization; solid_texture_count controls its size and defaults to 32. Set fallback_to_new=true to force the legacy create-and-replace path. The functor also falls back automatically when the asset material cannot be reused. The default plane is always randomized in place.

randomize_light()

Vary light position, color, intensity, and direction within specified ranges.

.. note:: position_range is ignored for global scene lights ("sun", "direction"). Use direction_range instead for these types.

.. note:: direction_range is only applicable for directional light types ("sun", "direction", "spot", "rect", "mesh").

{"func": "randomize_light",
 "mode": "interval", "interval_step": 10,
 "params": {"entity_cfg": {"uid": "light_1"},
            "position_range": [[-0.5, -0.5, 2], [0.5, 0.5, 2]],
            "color_range": [[0.6, 0.6, 0.6], [1, 1, 1]],
            "intensity_range": [50.0, 100.0],
            "direction_range": [[-0.1, -0.1, -0.1], [0.1, 0.1, 0.1]]}}

randomize_emission_light()

Randomize global emission light color and intensity. Applies the same emission light properties across all environments.

{"func": "randomize_emission_light",
 "mode": "interval", "interval_step": 10,
 "params": {"color_range": [[0.6, 0.6, 0.6], [1, 1, 1]],
            "intensity_range": [0.5, 2.0]}}

randomize_indirect_lighting

Randomize indirect (IBL) lighting or emissive light. Implemented as a Functor class. Operates in one of two mutually exclusive modes — configuring both raises a ValueError:

HDR mode — provide path pointing to a folder of .hdr files. A random file is selected on each call and applied as the environment map. The path is resolved via get_data_path, supporting absolute paths, data-root-relative paths, and dataset-class paths.

{"func": "randomize_indirect_lighting",
 "mode": "interval", "interval_step": 10,
 "params": {"path": "EnvMapHDR/EnvMapHDR"}}

Emissive mode — provide emissive_color_range (pair of RGB lists) and/or emissive_intensity_range (pair of floats). Color and intensity are sampled uniformly on each call and applied via set_emission_light.

{"func": "randomize_indirect_lighting",
 "mode": "interval", "interval_step": 10,
 "params": {"emissive_color_range": [[0.8, 0.8, 0.8], [1.0, 1.0, 1.0]],
            "emissive_intensity_range": [80.0, 150.0]}}

Applies the same lighting to all environments.

randomize_camera_extrinsics()

Randomize camera poses for viewpoint diversity. Supports both attach mode (pos/euler perturbation) and look_at mode (eye/target/up perturbation).

{"func": "randomize_camera_extrinsics", "mode": "reset",
 "params": {"entity_cfg": {"uid": "cam_high"}, "mode": "look_at",
            "eye_range": [[-0.1, -0.1, -0.1], [0.1, 0.1, 0.1]]}}

randomize_camera_intrinsics()

Vary focal length (fx, fy) and principal point (cx, cy) within specified ranges.

{"func": "randomize_camera_intrinsics", "mode": "reset",
 "params": {"entity_cfg": {"uid": "cam_high"},
            "fx_range": [400, 500], "fy_range": [400, 500]}}

set_rigid_object_visual_material()

Set a rigid object’s visual material deterministically (non-random). Useful for configs that want fixed colors/materials during reset.

{"func": "set_rigid_object_visual_material", "mode": "reset",
 "params": {"entity_cfg": {"uid": "cup"}, "base_color": [0.8, 0.2, 0.2]}}

set_rigid_object_group_visual_material()

Set a rigid object group’s visual material deterministically (non-random). Useful for configs that want fixed colors/materials during reset.

{"func": "set_rigid_object_group_visual_material", "mode": "reset",
 "params": {"entity_cfg": {"uid": "objects"}, "base_color": [0.8, 0.2, 0.2]}}

Spatial Randomization#

Spatial Randomization Functors#

Functor Name

Description

randomize_rigid_object_pose()

Randomize object positions and orientations. Supports both relative and absolute pose randomization.

{"func": "randomize_rigid_object_pose", "mode": "reset",
 "params": {"entity_cfg": {"uid": "bottle"},
            "position_range": [[-0.08, -0.12, 0.0], [0.08, 0.04, 0.0]],
            "relative_position": true}}

randomize_robot_eef_pose()

Vary end-effector initial poses by solving inverse kinematics. The randomization is performed relative to the current end-effector pose.

{"func": "randomize_robot_eef_pose", "mode": "reset",
 "params": {"entity_cfg": {"uid": "CobotMagic",
            "control_parts": ["left_arm", "right_arm"]},
            "position_range": [[-0.01, -0.01, -0.01], [0.01, 0.01, 0]]}}

randomize_robot_qpos()

Randomize robot joint configurations. Supports both relative and absolute joint position randomization, and can target specific joints.

{"func": "randomize_robot_qpos", "mode": "reset",
 "params": {"entity_cfg": {"uid": "CobotMagic"},
            "qpos_range": [[-0.1], [0.1]], "relative": true}}

randomize_articulation_root_pose()

Randomize the root pose (position and rotation) of an articulation. Supports both relative and absolute pose randomization. Similar to randomize_rigid_object_pose but for multi-link rigid body systems.

{"func": "randomize_articulation_root_pose", "mode": "reset",
 "params": {"entity_cfg": {"uid": "cabinet"},
            "position_range": [[-0.05, -0.05, 0], [0.05, 0.05, 0]],
            "relative_position": true}}

randomize_target_pose()

Randomize a virtual target pose and store it in env state. Generates random target poses without requiring a physical object in the scene.

{"func": "randomize_target_pose", "mode": "reset",
 "params": {"position_range": [[0.5, -0.2, 0.8], [0.8, 0.2, 0.8]],
            "target_pose_key": "goal_pose"}}

planner_grid_cell_sampler

Sample grid cells for object placement without replacement. Implemented as a Functor class. Divides a planar region into a regular 2D grid and samples cells to place objects at their centers.

{"func": "planner_grid_cell_sampler", "mode": "reset",
 "params": {"grid_origin": [0.5, -0.3], "grid_size": [0.4, 0.6],
            "grid_res": [4, 6], "entity_cfg": {"uid": "objects"}}}

randomize_anchor_height

Randomize the height of an anchor object and shift other objects by the same delta. Implemented as a Functor class. Samples a per-environment height delta (uniform range or discrete candidates), moves the anchor object relative to its configured initial position, and adds the same delta to the Z component of every other included object while preserving XY and rotation.

{"func": "randomize_anchor_height", "mode": "reset",
 "params": {"anchor_uid": "table",
            "height_delta_range": [[-0.05], [0.05]],
            "exclude_uids": ["floor"]}}

Geometry Randomization#

Geometry Randomization Functors#

Functor Name

Description

randomize_rigid_object_scale()

Randomize a rigid object’s body scale factors (multiplicative). Supports uniform scaling across all axes or independent per-axis scaling.

{"func": "randomize_rigid_object_scale", "mode": "reset",
 "params": {"entity_cfg": {"uid": "cup"},
            "scale_range": [[0.8, 0.8, 0.8], [1.2, 1.2, 1.2]]}}

randomize_rigid_objects_scale()

Randomize body scale factors for multiple rigid objects. Supports shared sampling (same scale for all objects) or independent sampling per object.

{"func": "randomize_rigid_objects_scale", "mode": "reset",
 "params": {"entity_cfg": {"uid": "objects"},
            "scale_range": [[0.8, 0.8, 0.8], [1.2, 1.2, 1.2]]}}

Asset Management#

Asset Management Functors#

Functor Name

Description

replace_assets_from_group

Swap object models from a folder on reset for visual diversity. Currently supports RigidObject assets with mesh-based shapes.

{"func": "replace_assets_from_group", "mode": "reset",
 "params": {"entity_cfg": {"uid": "cup"}, "group_uid": "cups_group"}}

prepare_extra_attr

Set up additional object attributes dynamically. Supports both static values and callable functions. Useful for setting up affordance data and other custom attributes.

{"func": "prepare_extra_attr", "mode": "reset",
 "params": {"attrs": [
   {"name": "object_lengths", "mode": "callable",
    "entity_uids": "all_objects", "func_name": "compute_object_length",
    "func_kwargs": {"is_svd_frame": true, "sample_points": 5000}}]}}

register_entity_attrs()

Register entity attributes to a registration dict in the environment. Supports fetching attributes from both entity properties and prepare_extra_attr functor.

{"func": "register_entity_attrs", "mode": "reset",
 "params": {"entity_cfg": {"uid": "bottle"},
            "attrs": ["mass"], "registration": "object_info"}}

register_entity_pose()

Register entity poses to a registration dict. Supports computing relative poses between entities and transforming object-frame poses to arena frame.

{"func": "register_entity_pose", "mode": "reset",
 "params": {"entity_cfg": {"uid": "bottle"},
            "pose_register_params": {"compute_relative": false,
                                     "to_matrix": true}}}

register_info_to_env()

Batch register multiple entity attributes and poses using a registry list. Combines register_entity_attrs and register_entity_pose functionality.

{"func": "register_info_to_env", "mode": "reset",
 "params": {"registry": [
   {"entity_cfg": {"uid": "bottle"},
    "pose_register_params": {"compute_relative": false,
      "compute_pose_object_to_arena": true, "to_matrix": true}}],
  "registration": "affordance_datas", "sim_update": true}}

drop_rigid_object_group_sequentially()

Drop objects from a rigid object group one by one from a specified height with position randomization.

{"func": "drop_rigid_object_group_sequentially", "mode": "reset",
 "params": {"entity_cfg": {"uid": "objects"},
            "drop_height": 0.5,
            "position_range": [[-0.1, -0.1], [0.1, 0.1]]}}

set_detached_uids_for_env_reset()

Set UIDs of objects that should be detached from automatic reset. Useful for objects that need custom reset handling.

{"func": "set_detached_uids_for_env_reset", "mode": "reset",
 "params": {"uids": ["ground_plane"]}}

Recording#

Recording Functors#

Functor Name

Description

record_camera_data

Record RGB frames from a dedicated camera and save them as an MP4 video when an episode resets. This is useful for debugging, qualitative evaluation, and demo capture. The functor creates its own camera from the configured pose and intrinsics, captures frames during interval execution, and writes one video per episode.

{"func": "record_camera_data", "mode": "interval", "interval_step": 1,
 "params": {"name": "debug_cam",
            "resolution": [640, 480],
            "eye": [1.0, 0.0, 1.2],
            "target": [0.0, 0.0, 0.5],
            "up": [0.0, 0.0, 1.0],
            "save_path": "./outputs/videos"}}

record_camera_data_async

Record RGB frames for several environments independently, then merge them into a single tiled MP4 once each tracked environment finishes an episode. This variant is useful when you want side-by-side qualitative comparison across vectorized environments.

{"func": "record_camera_data_async", "mode": "interval", "interval_step": 1,
 "params": {"name": "overview_async_cam",
            "resolution": [640, 480],
            "eye": [1.0, 0.0, 1.2],
            "target": [0.0, 0.0, 0.5],
            "up": [0.0, 0.0, 1.0],
            "save_path": "./outputs/videos"}}

record_camera_data#

The record_camera_data functor lives under the record manager module, but it is configured through the event pipeline because it runs periodically during stepping and flushes video output at episode reset.

Note

This is separate from Dataset Functors. Use dataset functors when you need training data such as observations and actions. Use record_camera_data when you need human-viewable videos for debugging or demos.

Typical Usage#

  • Set mode="interval" so the camera captures frames during stepping.

  • Use interval_step=1 to record every environment step, or increase it to reduce file size.

  • Choose a fixed third-person camera pose with eye, target, and up.

  • Save output videos with save_path.

Parameters#

record_camera_data Parameters#

Parameter

Description

name

Camera name used for the internally created sensor and output file naming. Default: "default".

resolution

Output image size as [width, height]. Default: [640, 480].

eye

Camera position in world coordinates. Default: [0, 0, 2].

target

Look-at target in world coordinates. Default: [0, 0, 0].

up

Up vector for the camera pose. Default: [0, 0, 1].

intrinsics

Camera intrinsics as [fx, fy, cx, cy]. Defaults to values derived from the configured resolution.

max_env_num

Maximum number of environments to tile into one frame when recording vectorized environments.

save_path

Output directory for generated MP4 files. Default: ./outputs/videos.

Behavior Notes#

  • In vectorized environments, frames from multiple environments are tiled into a single composite image before video encoding.

  • Videos are flushed during episode initialization for environments that are resetting, not by the Dataset Manager.

  • If the process exits without another reset, the final episode may not be flushed to disk.

  • This functor captures RGB imagery for visualization. It does not record actions, rewards, or structured training data.

record_camera_data_async#

The record_camera_data_async functor is the multi-environment variant of record_camera_data. It tracks a small set of environments independently, waits until each one has completed an episode, and then writes a single tiled video that combines them.

Typical Usage#

  • Use this variant when you want one comparison video spanning multiple vectorized environments.

  • Configure it with mode="interval" just like record_camera_data.

  • Keep the number of tracked environments modest; the current implementation records up to four environments.

  • Use the same camera pose parameters as the single-environment recorder.

Parameters#

The async recorder accepts the same parameters as record_camera_data:

  • name

  • resolution

  • eye

  • target

  • up

  • intrinsics

  • max_env_num

  • save_path

Behavior Notes#

  • Frames are buffered separately for each tracked environment and merged later into one tiled video.

  • The current implementation tracks at most four environments, even if num_envs is larger.

  • Output is written only after all tracked environments have completed an episode, so video generation may lag behind individual resets.

  • This variant is meant for qualitative inspection and comparison, not structured dataset export.

Usage Example#

from embodichain.lab.gym.envs.managers.cfg import EventCfg, SceneEntityCfg

# Example: Randomize object mass on reset
events = {
    "randomize_mass": EventCfg(
        func="randomize_rigid_object_mass",
        mode="reset",
        params={
            "entity_cfg": SceneEntityCfg(uid="cube"),
            "mass_range": (0.1, 2.0),
            "relative": False,
        },
    ),
}