Object Config

In GenManip, Object Config defines an abstraction layer called a Meta Object, which can be referenced in both Generation Config and Layout Config, providing a flexible way to construct scenes.

Essentially, object_config is a dictionary where each key is the name of a Meta Object, and the value is another dictionary containing its configuration.

Example:

object_config:
  apple:
    type: existed_object
    uid_list:
    - 1fdc84a7be2c4348b281490c89d76062
  banana:
    filter_rule: []
    max_cached_num: 50
    option: []
    path: object_usds/bananas
    type: load_object_from_path
  container:
    option: []
    path: object_usds/objaverse_usd/f8a2cdc9970846da95585a428697d173.usd
    type: add_additional_object_from_path

This example shows three Meta Object types. Let’s explain each one in turn.

Existed Object

An Existed Object represents an object that already exists in the scene — for instance, predefined items in the simulation. You must provide a uid_list that lists the UIDs of those objects (found under /scene_uid/obj_<uid>).

apple:
  type: existed_object
  uid_list:
  - 1fdc84a7be2c4348b281490c89d76062
  - 1fdc84a7be2c4348b281490c89d76063
  - 1fdc84a7be2c4348b281490c89d76064

During runtime, GenManip maps Meta Objects to real instances (meta → fine). Each time it will randomly map apple to one UID in the list — e.g., placing a specific apple on top of a container. If you want to select two different apples randomly, you can define two Meta Objects (apple1, apple2) and GenManip will ensure they don’t map to the same instance.

Load Object from Path

This type loads multiple objects from a folder and activates one randomly during each run.

banana:
  filter_rule: []
  max_cached_num: 50
  option: []
  path: object_usds/bananas
  type: load_object_from_path

When initialized, up to max_cached_num objects are preloaded. Each run randomly activates one banana. If max_cached_num exceeds the number of files in the folder, all are loaded.

Since these assets (e.g., from Objaverse) vary in size, resizing is needed. Resizing rules are governed by the scale field in the object annotation (see Domain Randomization).

Filter Rule

filter_rule allows selective filtering based on attributes in the object annotations (shape, material, color, graspability, etc.).

Example:

apple:
  filter_rule:
  - can_grasp
  - retrieve_category_food
  - retrieve_shape_sphere
  - retrieve_not_material_metal
  - retrieve_not_material_plastic
  - retrieve_color_red
  - retrieve_scale_less_than_0.5
  - retrieve_scale_greater_than_0.3
  max_cached_num: 50
  option: []
  path: object_usds/apples
  type: load_object_from_path

This loads red, graspable, spherical apples (not metal or plastic) whose size lies between 0.3 and 0.5 m and category is “food”.

Scaling Options

In addition to the scale field from annotations, GenManip allows several overrides:

• clip_range: Clips the original scale range.
• fixed_size: Explicit [x, y, z] in meters.
• fixed_scale: Scales by a constant multiplier.

Example:

apple:
  clip_range: [0.3, 0.5]

Add Additional Object from Path

This loads one or multiple USD objects (from a file or folder) directly into the scene, similar to existed_object.

Example:

container:
  option: []
  path: object_usds/objaverse_usd/f8a2cdc9970846da95585a428697d173.usd
  type: add_additional_object_from_path

If path is a folder, you can control the number of objects loaded via max_cached_num. Scaling settings are the same as in load_object_from_path.

How Meta Object Works

The image above illustrates how Meta Object works.

In GenManip’s implementation, Meta Object serves as an intermediate layer and exhibits different configurations during different stages of GenManip.

In the Config Stage, the Config defines the mapping relationship for Meta Config. Object Configs with identical content share the same Hash, allowing them to share preloaded objects in the Preload Stage (e.g., if 50 apples are preloaded, all Apple Meta Objects with identical content will share these 50 apples, rather than loading n×50 apples).

In the Preload Stage, the Object Pool is constructed, and the above Meta Config is supported through a dict mapping. For the scenario in the image, there exists a meta_to_fine_object_dict containing:

{
  "apple": [
    "apple1",
    "apple2"
  ],
  "banana": [
    "banana1",
    "banana2",
    "banana3"
  ],
  "pot":[
    "pot"
  ]
}

In the Demogen Stage, for each meta object, a fine object is randomly selected from meta_to_fine_object_dict, and all references to that meta object (in layout config and generation object) have their UIDs replaced with the fine object. For different meta objects that reference the same queue (because they share hash values), the system ensures they map to different objects. Additionally, features like load_object_from_path take effect at this stage — non-selected objects are deactivated (shown in gray in the image).

The Demogen Stage executes repeatedly at runtime, randomly mapping from meta object to fine object each time, while managing the large object pool.