Object Config

在 GenManip 中，object_config 定义了一层称为 Meta Object 的抽象。Meta Object 可以在 generation_config 与 layout_config 中被引用，从而灵活地构造场景。

本质上，object_config 是一个字典（Dict），键为 Meta Object 的名称，值为该 Meta Object 的配置字典。

示例：

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

上例展示了三种 Meta Object 的类型：existed_object、load_object_from_path、add_additional_object_from_path。下面逐项说明。

Existed Object（场景中已存在的对象）

existed_object 表示该对象已存在于 USD 场景中（位于 /scene_uid/obj_<uid> 下）。你需要提供 uid_list，列出可能被映射的 UID（可以包含多个 UID，运行时会从中随机选择）。

示例：

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

运行时，系统会执行 meta → fine 的映射：每次从 uid_list 中选取一个 UID 映射给 apple。若想在同一次场景中随机挑选两个不同的苹果，可定义 apple1 与 apple2 两个 Meta Object（系统会避免把不同的 Meta Object 映射到同一 fine object）。

对应的 Goal 例子：

- - obj1_uid:
    - apple1
    obj2_uid:
    - container
    position:
    - top
  - obj1_uid:
    - apple2
    obj2_uid:
    - container
    position:
    - top

Load Object from Path（从文件夹加载对象并随机激活）

此类型会从指定文件夹中预加载若干对象（由 max_cached_num 控制），在每次采集时随机激活其中的一个到场景中。

示例：

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

说明：

程序将在初始化时预加载最多 max_cached_num 个物体（若 max_cached_num 大于文件夹内文件数，则加载全部）。
这些物体通常来自像 Objaverse 这样的公共数据集，尺寸不一，因此需要进行缩放（scale）处理，具体规则见 Domain Randomization 中的 Object Annotation 与 scale 字段。

Filter Rule（过滤规则）

filter_rule 用于基于物体标注（annotation）字段来筛选物体（如 shape、material、color、can_grasp、is_container、category_list、scale 等）。它是一个字符串列表，列表内为且关系（所有条件需同时满足）。

示例：

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

该配置会在 object_usds/apples 中加载：可抓取（can_grasp）、类别为 food、形状为球体、材质不是金属或塑料、颜色为红色、且尺寸在 0.3–0.5 米之间的苹果。

对于 is_container 字段，对应的 filter_rule 为 is_container。

Scales（缩放相关覆盖）

除了使用 object annotation 中的 scale 字段，GenManip 支持在 object_config 中额外指定缩放相关字段来覆盖或约束原始标注：

clip_range: [min, max]，将原始 scale 的区间裁剪到该范围内。
fixed_size: [x, y, z]（以米为单位），把物体强制缩放到指定的长宽高。
fixed_scale: 浮点数，按给定比例缩放原始大小（例如 0.5 表示缩小到原始的 0.5 倍）。

示例：

apple:
  clip_range: [0.3, 0.5]

Add Additional Object from Path（从路径添加附加对象）

该类型会把指定文件或文件夹内的 USD 对象加载到场景中，并将它们视作场景中的对象（类似于 existed_object 的效果），便于在运行时动态添加或替换场景物体。

示例（单一 USD 文件）：

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

示例（文件夹）：若 path 指向文件夹，可用 max_cached_num 控制加载数量，加载后这些物体会同时存在于场景中（或按后续逻辑激活/布局）。

如果你希望将几个已知的苹果等价地实现为 existed_object 的效果，也可以把它们放入一个文件夹并使用 add_additional_object_from_path，例如：

apple:
  max_cached_num: 3
  option: []
  path: object_usds/apples
  type: add_additional_object_from_path

load_object_from_path 支持的缩放/过滤等设置在 add_additional_object_from_path 中同样适用。

Meta Object 的工作方式

上图描述了 Meta Object 的工作方式。

在 GenManip 的实现中，Meta Object 实现一个一个中间层，并且在 GenManip 的不同阶段包含了体现出不同的配置。

在 Config Stage 中，Config 中定义 Meta Config 的映射关系，对于内容一样的 Object Config 来说，它们具有相同的 Hash，从而在 Preload Stage 中共享预加载的物体（如预加载了 50 个苹果，那么所有内容一样的 Apple Meta Object 都会共享这 50 个苹果，而不会加载 n*50 个苹果）。

在 Preload Stage 中，Object Pool 被构建，并且通过 dict 的映射来支持上述的 Meta Config，此时对于图中的情况来说，存在 meta_to_fine_object_dict，包含：

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

在 demogen stage 中，对于每一个 meta object，将从 meta_to_fine_object_dict 中随机选择一个 fine object，并将全部提及该 meta object 的信息处（layout config 以及 generation object）的 uid 替换为 fine object，对于同时引用一个队列的不同 meta object 来说（因为共享 hash 值），会确保它们彼此映射到不同的物体。同时在这一阶段，如 load_object_from_path 的特性也会生效，即，将非选中的物体 deactive 掉（即图中灰色）。

Demogen stage 在运行时会反复执行，从而每一次随机从 meta object 到 fine object 进行映射，并且管理庞大的 object pool。