Object Bin Packing（IRO bin_pack harmonizer）
用途
将大量 3D 物体程序化码放到长方体容器（bin / pallet / container / carton）中，并渲染合成数据（RGB、2D/3D 框、分割图）。它是 object-simulation-sdg 的专门化分支，建立在 IRO 的 bin_pack harmonizer（isaacsim.replicator.object）之上。放置具有重力稳定性：箱子自底向上放置，且只能落在箱底或由下方物体支撑，因此不会有箱子悬空。
建议先阅读 object-simulation-sdg（描述文件 schema、运行模式、输出布局）以及 action-and-event-data-generation（启动器与环境约定）。本技能仅覆盖其上的码箱专门化内容。
限制
需要 isaacsim.replicator.object（IRO）；码放运行在实时 Isaac Sim 内，而非离线。
bin_pack 在容器内以重力稳定方式放置物体；它不模拟码放动作，因此产出的是终态布局，而非操作轨迹。
除非配置固定了种子，否则每次运行的布局都会变化。
此处仅对 scripts/bin_pack_config.py 生成器做了离线验证；实时无头 IRO 渲染依赖 demo_bin_pack 产出的箱子集合。
何时使用（与同类技能对比）
当需要按包围盒将静态物体密集码放/堆叠进一个 bin 时使用——如仓储包裹、托盘纸箱、周转箱。
若需要一般性的随机散布放置（非码放）、桌面掉落或非箱体几何，直接使用 object-simulation-sdg。
移动的人/机器人使用 actor-simulation-sdg；罕见事件（倾倒/洒落）使用 event-generation。
前置条件
已安装 Isaac Sim 及 Action and Event Data Generation 应用（$ISAAC_SIM_DIR），包含 isaacsim.replicator.object.core。假定具备重力稳定码放与 fill_ratio；二者均存在于该应用所固定的构建中。
实际渲染需要 NVIDIA GPU + 当前驱动（离线生成器两者均不需要）。
来自 isaac-sim-orchestrator 的环境约定：$ISAAC_SIM_DIR、$WORKSPACE_DIR、$AEDG_OUTPUT。
可用脚本
脚本 | 用途 | 参数
scripts/bin_pack_config.py | 生成自包含的 IRO 码箱描述（离线）；可选 --validate 校验 | 通过 argparse 的 CLI 标志（--help）
该生成器码放从内容服务器流式获取的 SimReady 纸箱——无需本地资源，也不使用 PATH_TO_BOXES。它通过 --from-ext 从你的构建推导配置版本以保持同步，内联定义内容服务器宏链（便于无头运行自包含），并写入相机 + 穹顶光 + 输出开关，使配置可直接渲染。
生成可运行配置（版本与你的构建匹配）
python3 scripts/bin_pack_config.py --from-ext "$ISAAC_SIM_DIR"
--output-path "$AEDG_OUTPUT/iro_bin_pack" > scene_bin_pack.yaml
部分装载的 bin（约占箱体积 60%）、更大的 bin、放大箱数
python3 scripts/bin_pack_config.py --from-ext "$ISAAC_SIM_DIR" --output-path "$AEDG_OUTPUT/iro_bin_pack"
--bin-size 500 250 250 --fill-ratio 0.6 --scale-counts 1.5 > scene_bin_pack.yaml
离线门禁：确认配置可在 IRO 上运行（不启动）——打印 OK / problems
python3 scripts/bin_pack_config.py --from-ext "$ISAAC_SIM_DIR"
--output-path "$AEDG_OUTPUT/iro_bin_pack" --validate
在带技能执行辅助的智能体运行时中：run_script("scripts/bin_pack_config.py", args=["--help"])。
bin_pack harmonizer
harmonizer 关联多个 mutable 如何一起随机化。bin_pack 按每个物体的轴对齐包围盒，将所有引用它的几何组码放进一个长方体：
isaacsim.replicator.object: version: EXT_VERSION # 来自已安装扩展；用 --from-ext 推导
... 设置、相机、光照 ...
bin_pack_H: harmonizer_type: bin_pack bin_size: [400, 200, 200] # 长方体尺寸 fill_ratio: 0.6 # 可选 (0, 1]：将码放总体积限制为箱体积的该比例
boxes: count: 16 type: geometry subtype: mesh tracked: true # 仅 tracked 的 mutable 出现在标签/分割/3D 框中 transform_operators: - transform: # <-- 放置来自 harmonizer distribution_type: harmonized harmonizer_name: bin_pack_H pitch: local_aabb - scale: distribution_type: range start: [1.2, 1.2, 1.2] end: [1.25, 1.25, 1.25] usd_path: $[/cardboard_boxes_root]/White_A/WhiteCorrugatedBox_A08_30x30x30cm_PR_NVD_01.usd
关键行为：
重力稳定放置——最底-最左下填充，带底部支撑 + 质心约束；箱子落在箱底或其下方箱子上，绝不悬空。
fill_ratio（可选，(0, 1]）——将码放箱子总体积限制为箱体积的该比例，用于部分装载的 bin。非法值在加载时被拒绝。
布局多样性——放置带种子，因此按种子可复现，但逐帧变化；不同种子给出不同码放。
溢出——放不下的物体被移出视野（它们仍存在于 stage 中）。
尺寸多样性来自选择不同尺寸的资源，而非逐轴缩放取巧；生成器精选了一套棕/白箱子，跨度从约 15 cm 扁箱到约 77 cm 立方体。
运行（无头）
cd "$ISAAC_SIM_DIR"
./isaac-sim.sh --no-window --allow-root
--enable isaacsim.replicator.object.core
--/log/level=warn --/windowless=True
--/config/file="$PWD/scene_bin_pack.yaml"
或在 Object SDG 面板中（启用 isaacsim.replicator.object.core + .ui）：在 Simulate 下方的下拉框选择 demo_bin_pack（无需本地资源）并点击 Simulate。扩展日志行带有标签 [METROPERF][isaacsim.replicator.object.core:<version>]。
验证是否成功
IRO 在 output_path 下为每个启用的输出开关写一个文件夹（不是每相机一个）：
for d in images labels segmentation; do n=$(ls "$AEDG_OUTPUT/iro_bin_pack/$d" 2>/dev/null | wc -l); echo "$d: $n files" done
images/ 非空且箱子码放进 bin（检查时无品红/黑色箱子、无悬空箱子）即表示成功。images/ 为空表示本次运行未捕获任何内容——检查各组的 tracked: true 以及版本是否与你的构建匹配。
集成点
消费：来自内容服务器的 SimReady 纸箱（$[/cardboard_boxes_root]/...）；或你自己的 usd_path 箱体 USD。
产出：output_path 下的 RGB + 2D/3D 框 + 分割；也可在运行中通过 caption_writer: CombinedIROSceneGraphWriter 输出说明文字（见 vlm-scene-captioning）。
父级：object-simulation-sdg（schema、运行模式）→ action-and-event-data-generation。
故障排查
箱子悬空——码放器回退到仅相交检查，说明所解析的 isaacsim.replicator.object.core 早于重力稳定码放。请运行 .kit 固定该扩展的应用，而非临时 --enable。
品红或近乎黑色的箱子——White_A/Flat_A 箱体资源通过 payload 挂载材质，并经 scene_instance 缓存实例化。固定构建会自动为此类资源禁用实例化；若仍遇到，在该箱组上设置 is_instance: false。
bin 看起来稀疏——物体占地相对 bin_size 偏大；可增大 --bin-size、提高 --scale-counts，或添加更小的箱体资源（放不下的箱子会被传送到视野外，因此仅提高数量不会增加密度）。
物理后布局未保持——physics: rigidbody 会让箱子掉落/重排，丢弃码箱布局；要保留码放排列就省略 physics。
PATH_TO_BOXES 错误——随附的 demo_bin_pack.yaml 与本生成器无需本地资源；其他 demo（demo_bins_of_bins*、demo_table）仍需要 PATH_TO_BOXES。
版本不匹配——将 version 设为已安装的 isaacsim.replicator.object.core（使用 --from-ext "$ISAAC_SIM_DIR"）；随附示例可能滞后。