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.

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). Implemented as a Functor class. Supports both RigidObject and Articulation assets.

{"func": "randomize_visual_material",
 "mode": "interval", "interval_step": 10,
 "params": {"entity_cfg": {"uid": "table"},
            "random_texture_prob": 0.5,
            "texture_path": "CocoBackground/coco",
            "base_color_range": [[0.2, 0.2, 0.2], [1.0, 1.0, 1.0]]}}

randomize_light()

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

{"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]}}

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_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"}}}

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"]}}

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,
        },
    ),
}
Contents