GenSim scene adapters

These existing entry points adapt GenSim’s editable Y-up layouts and asset files to shared numerical geometry and arena-local scene services. They retain diagnostic output and generation/edit orchestration. GenSim still owns model clients, asset preparation, temporary simulator lifecycle and export formats. Support selection, polygon search, greedy packing and SLSQP are CPU strategies owned by sim.scene. Their reusable tensor operations use compute.geometry; kernel CUDA support does not migrate these pipelines to GPU.

embodichain.gen_sim.scene_engine.pipeline.utils.assets_group_layout_optimizer

Preserves the generation path’s greedy AABB separation strategy and Y-up output; numeric offsets come from the shared scene CPU packing strategy.

AssetsSupportLayoutOptimizerConfig	alias of AABBLayoutConfig
AssetsSupportLayoutOptimizer	Greedily separate AABBs while retaining arbitrary support containment.

Classes:

AssetsSupportLayoutOptimizer	Greedily separate AABBs while retaining arbitrary support containment.
AssetsSupportLayoutOptimizerConfig	alias of AABBLayoutConfig

class embodichain.gen_sim.scene_engine.pipeline.utils.assets_group_layout_optimizer.AssetsSupportLayoutOptimizer

Greedily separate AABBs while retaining arbitrary support containment.

This reuses the previous packing algorithm’s pairwise strategy: detect an overlap, try the two separating directions on both XY axes, and choose the lowest-displacement valid push. Unlike the old path, every candidate is validated against the actual Polygon/MultiPolygon support region instead of a largest internal rectangle.

Methods:

__init__(*, support_region, ...[, ...])	Configure deterministic greedy separation.
optimize()	Resolve overlap through shared geometry and adapt offsets to Y-up.
save_overlap_optimization_debug_images()	Optionally save diagnostics for the most recent optimization.

__init__(*, support_region, assets_aabb_2d_z_up_world_corners_by_id, assets_layout, debug_output_root=None, config=None)

Configure deterministic greedy separation.

Parameters:

config (AABBLayoutConfig | None) – Boundary, clearance and search budget parameters.

optimize()

Resolve overlap through shared geometry and adapt offsets to Y-up.

Return type:

list[dict[str, object]]

save_overlap_optimization_debug_images()

Optionally save diagnostics for the most recent optimization.

Return type:

bool

embodichain.gen_sim.scene_engine.pipeline.utils.assets_group_layout_optimizer.AssetsSupportLayoutOptimizerConfig

alias of AABBLayoutConfig

embodichain.gen_sim.scene_engine.pipeline.utils.assets_group_support_clamp

Applies a shared support-valid group translation to Y-up layouts. Existing Polygon/MultiPolygon, hole and diagnostic-image behavior remains available.

SupportGeometry	Represent a PEP 604 union type
AssetsGroupSupportClampConfig	alias of GroupSupportClampConfig
AssetsGroupSupportClamp	Find a small shared XY shift that places all AABBs on a support region.

Classes:

AssetsGroupSupportClamp	Find a small shared XY shift that places all AABBs on a support region.
AssetsGroupSupportClampConfig	alias of GroupSupportClampConfig

class embodichain.gen_sim.scene_engine.pipeline.utils.assets_group_support_clamp.AssetsGroupSupportClamp

Find a small shared XY shift that places all AABBs on a support region.

Each AABB gets a feasible-centre map obtained by binary erosion of the safe support mask. A candidate translation is valid only when it is feasible for every asset, then it must pass exact Shapely containment. This supports concave polygons, holes, and disconnected MultiPolygon regions.

Methods:

__init__(*, support_region, ...[, ...])	Set margin and raster resolution for support placement.
clamp()	Return y-up layouts after one rigid, support-valid XY translation.
save_group_clamp_debug_images()	Optionally save diagnostics for the support-valid group translation.

__init__(*, support_region, assets_aabb_2d_z_up_world_corners_by_id, assets_layout, debug_output_root=None, config=None)

Set margin and raster resolution for support placement.

Parameters:

config (GroupSupportClampConfig | None) – Search parameters.

clamp()

Return y-up layouts after one rigid, support-valid XY translation.

Return type:

list[dict[str, object]]

save_group_clamp_debug_images()

Optionally save diagnostics for the support-valid group translation.

Return type:

bool

embodichain.gen_sim.scene_engine.pipeline.utils.assets_group_support_clamp.AssetsGroupSupportClampConfig

alias of GroupSupportClampConfig

embodichain.gen_sim.scene_engine.pipeline.utils.assets_group_table_aligner

Measures transformed geometry, uses the shared group-height offset and converts the resulting layout back to Y-up without changing relative poses.

AssetsGroupTableAlignerConfig	Controls for the initial vertical gap above the table.
AssetsGroupTableAligner	Place every asset as one rigid vertical group above a table AABB top.

Classes:

AssetsGroupTableAligner	Place every asset as one rigid vertical group above a table AABB top.
AssetsGroupTableAlignerConfig	Controls for the initial vertical gap above the table.

class embodichain.gen_sim.scene_engine.pipeline.utils.assets_group_table_aligner.AssetsGroupTableAligner

Place every asset as one rigid vertical group above a table AABB top.

Methods:

__init__(*, table_layout, assets_layout, ...)
align()	Return y-up layouts with the complete asset group above the table.

__init__(*, table_layout, assets_layout, geometry_root, config=None)

align()

Return y-up layouts with the complete asset group above the table.

Input and output layouts use y-up, matching the GLBs on disk. The group is temporarily measured in z-up coordinates and every asset receives the same vertical translation. This preserves all asset-to-asset relative poses.

Return type:

tuple[dict[str, object], list[dict[str, object]]]

class embodichain.gen_sim.scene_engine.pipeline.utils.assets_group_table_aligner.AssetsGroupTableAlignerConfig

Controls for the initial vertical gap above the table.

Methods:

__init__([clearance_m])
copy(**kwargs)	Return a new object replacing specified fields with new values.
replace(**kwargs)	Return a new object replacing specified fields with new values.
to_dict()	Convert an object into dictionary recursively.
validate([prefix])	Check the validity of configclass object.

__init__(clearance_m=<factory>)

copy(**kwargs)

Return a new object replacing specified fields with new values.

This is especially useful for frozen classes. Example usage:

@configclass(frozen=True)
class C:
    x: int
    y: int

c = C(1, 2)
c1 = c.replace(x=3)
assert c1.x == 3 and c1.y == 2

Parameters:

• obj (object) – The object to replace.

• **kwargs – The fields to replace and their new values.

Return type:

object

Returns:

The new object.

replace(**kwargs)

Return a new object replacing specified fields with new values.

This is especially useful for frozen classes. Example usage:

@configclass(frozen=True)
class C:
    x: int
    y: int

c = C(1, 2)
c1 = c.replace(x=3)
assert c1.x == 3 and c1.y == 2

Parameters:

• obj (object) – The object to replace.

• **kwargs – The fields to replace and their new values.

Return type:

object

Returns:

The new object.

to_dict()

Convert an object into dictionary recursively.

Note

Ignores all names starting with “__” (i.e. built-in methods).

Parameters:

obj (object) – An instance of a class to convert.

Raises:

ValueError – When input argument is not an object.

Return type:

dict[str, Any]

Returns:

Converted dictionary mapping.

validate(prefix='')

Check the validity of configclass object.

This function checks if the object is a valid configclass object. A valid configclass object contains no MISSING entries.

Parameters:

• obj (object) – The object to check.

• prefix (str) – The prefix to add to the missing fields. Defaults to ‘’.

Return type:

list[str]

Returns:

A list of missing fields.

Raises:

TypeError – When the object is not a valid configuration object.

embodichain.gen_sim.scene_engine.pipeline.utils.gravity_settler

Owns its temporary simulation and asset materialization. Fixed-step settling remains the default; optional convergence settings request measured stability through shared scene validation.

GravitySettlerConfig	Physics controls for one caller-defined gravity-settlement pass.
GravitySettleBody	One scene object and its latest complete y-up pipeline layout.
GravitySettler	Settle caller-selected dynamic assets against a mandatory table body.

Classes:

GravitySettleBody	One scene object and its latest complete y-up pipeline layout.
GravitySettler	Settle caller-selected dynamic assets against a mandatory table body.
GravitySettlerConfig	Physics controls for one caller-defined gravity-settlement pass.

class embodichain.gen_sim.scene_engine.pipeline.utils.gravity_settler.GravitySettleBody

One scene object and its latest complete y-up pipeline layout.

Methods:

__init__(scene_object, y_up_layout)

__init__(scene_object, y_up_layout)

class embodichain.gen_sim.scene_engine.pipeline.utils.gravity_settler.GravitySettler

Settle caller-selected dynamic assets against a mandatory table body.

All supplied layouts use Scene Engine’s y-up pipeline convention. The settler converts them to z-up only at the simulation boundary. The caller explicitly classifies every participant as dynamic or static; static participants and the table are kinematic collision bodies.

Methods:

__init__(*, table_body, participant_bodies, ...)
settle()	Return final y-up poses for dynamic participants only.

__init__(*, table_body, participant_bodies, dynamic_asset_ids, static_asset_ids, config=None)

settle()

Return final y-up poses for dynamic participants only.

Input layouts are used as-is. Placement clearance and support-surface alignment remain the responsibility of the calling layout optimizer. Static participants and every object’s scale are unchanged, so they are deliberately omitted from the result.

Return type:

dict[str, dict[str, list[float]]]

class embodichain.gen_sim.scene_engine.pipeline.utils.gravity_settler.GravitySettlerConfig

Physics controls for one caller-defined gravity-settlement pass.

Methods:

__init__([settle_steps, physics_dt, ...])

__init__(settle_steps=300, physics_dt=0.01, sim_device='cpu', settling=None)

embodichain.gen_sim.scene_engine.pipeline.utils.parent_surface_layout_optimizer

Translates per-parent support problems into shared scene layout inputs. The Scene Engine caller retains hierarchy order, edit selection and pose propagation.

ParentSurfaceLayoutProblem	All geometry and layout-state inputs for one parent-surface solve.
ParentSurfaceLayoutOptimizerConfig	Numerical controls for one non-table parent-surface sibling solve.
ParentSurfaceLayoutOptimizer	Solve direct on children inside one parent's current XY footprint.

Classes:

ParentSurfaceLayoutOptimizer	Solve direct on children inside one parent's current XY footprint.
ParentSurfaceLayoutOptimizerConfig	Numerical controls for one non-table parent-surface sibling solve.
ParentSurfaceLayoutProblem	All geometry and layout-state inputs for one parent-surface solve.

class embodichain.gen_sim.scene_engine.pipeline.utils.parent_surface_layout_optimizer.ParentSurfaceLayoutOptimizer

Solve direct on children inside one parent’s current XY footprint.

Methods:

__init__(*[, config])
optimize(problem)	Adapt GenSim semantics to the shared arena-frame layout service.
settle_dynamic_children(*, table, parent, ...)	Settle variable children against their parent and fixed siblings.

__init__(*, config=None)

optimize(problem)

Adapt GenSim semantics to the shared arena-frame layout service.

Return type:

dict[str, list[float]]

settle_dynamic_children(*, table, parent, problem, dynamic_child_ids)

Settle variable children against their parent and fixed siblings.

Children must already have been placed 2cm above parent by the caller. The physical table remains mandatory, while the parent and unedited siblings become kinematic collision bodies for this pass.

Return type:

dict[str, dict[str, list[float]]]

class embodichain.gen_sim.scene_engine.pipeline.utils.parent_surface_layout_optimizer.ParentSurfaceLayoutOptimizerConfig

Numerical controls for one non-table parent-surface sibling solve.

Methods:

__init__([relation_clearance_m, ...])

__init__(relation_clearance_m=0.03, collision_margin_m=0.02, max_slsqp_iterations=500, slsqp_ftol=1e-06, max_collision_rounds=8, max_added_collision_pairs=64, imported_seed_weight=5.0, min_center_distance_m=0.01, min_center_distance_weight=0.05)

class embodichain.gen_sim.scene_engine.pipeline.utils.parent_surface_layout_optimizer.ParentSurfaceLayoutProblem

All geometry and layout-state inputs for one parent-surface solve.

Methods:

__init__(assets_by_id, child_ids, ...[, ...])
from_layout_problem(*, layout_problem, ...)	Build one parent-surface problem without mutating layout state.

__init__(assets_by_id, child_ids, child_seed_xy_by_id, imported_child_ids, fixed_child_xy_by_id, parent_aabb_xy, parent_top_z, child_relations, support_uid='parent')

classmethod from_layout_problem(*, layout_problem, group, current_xy_by_id)

Build one parent-surface problem without mutating layout state.

Return type:

ParentSurfaceLayoutProblem

embodichain.gen_sim.scene_engine.pipeline.utils.table_support_surface

Keeps file-independent mesh input and optional support-detection plots; the shared scene CPU detector owns surface selection.

SupportSurfaceConfig	Parameters for conservative single-level table-top detection.
TableSupportRegion	alias of DetectedSupportSurface
TableSupportSurfaceDetector	Detect one main upward table surface and render auditable diagnostics.

Classes:

TableSupportRegion	alias of DetectedSupportSurface
TableSupportSurfaceDetector	Detect one main upward table surface and render auditable diagnostics.

embodichain.gen_sim.scene_engine.pipeline.utils.table_support_surface.TableSupportRegion

alias of DetectedSupportSurface

class embodichain.gen_sim.scene_engine.pipeline.utils.table_support_surface.TableSupportSurfaceDetector

Detect one main upward table surface and render auditable diagnostics.

The input mesh must be standing on x-y plane of the z-up world coordinates. This class deliberately returns only the largest outer 2D contour because the current layout stage models one main tabletop; the original support triangles remain available for 3D diagnostics.

Methods:

__init__(*, table_world_mesh[, ...])
detect()	Detect support through the shared Z-up geometry implementation.
save_support_surface_debug_images(*[, ...])	Optionally save standard 3D and 2D support-detection diagnostics.

__init__(*, table_world_mesh, debug_output_root=None, config=None)

detect()

Detect support through the shared Z-up geometry implementation.

Return type:

DetectedSupportSurface

save_support_surface_debug_images(*, save_3d=True, save_2d=True, output_3d_path=None, output_2d_path=None)

Optionally save standard 3D and 2D support-detection diagnostics.

Return type:

bool

embodichain.gen_sim.scene_engine.pipeline.utils.table_surface_layout_optimizer

Translates the existing tabletop problem into shared layout constraints while retaining its compatibility settings and debug output.

TableSurfaceLayoutProblem	All scene-graph and geometry inputs for one table-surface solve.
TableSurfaceLayoutOptimizerConfig	Numerical controls for one direct-table sibling layout solve.
TableSurfaceLayoutOptimizer	Solve direct table children with table, relation, and collision constraints.

Classes:

TableSurfaceLayoutOptimizer	Solve direct table children with table, relation, and collision constraints.
TableSurfaceLayoutOptimizerConfig	Numerical controls for one direct-table sibling layout solve.
TableSurfaceLayoutProblem	All scene-graph and geometry inputs for one table-surface solve.

class embodichain.gen_sim.scene_engine.pipeline.utils.table_surface_layout_optimizer.TableSurfaceLayoutOptimizer

Solve direct table children with table, relation, and collision constraints.

Methods:

__init__(*[, config])
optimize(problem)	Adapt GenSim semantics to the shared arena-frame layout service.

__init__(*, config=None)

optimize(problem)

Adapt GenSim semantics to the shared arena-frame layout service.

Return type:

dict[str, list[float]]

class embodichain.gen_sim.scene_engine.pipeline.utils.table_surface_layout_optimizer.TableSurfaceLayoutOptimizerConfig

Numerical controls for one direct-table sibling layout solve.

Methods:

__init__([relation_clearance_m, ...])

__init__(relation_clearance_m=0.03, collision_margin_m=0.02, max_slsqp_iterations=500, slsqp_ftol=1e-06, max_collision_rounds=8, max_added_collision_pairs=64, imported_seed_weight=5.0, min_center_distance_m=0.01, min_center_distance_weight=0.05)

class embodichain.gen_sim.scene_engine.pipeline.utils.table_surface_layout_optimizer.TableSurfaceLayoutProblem

All scene-graph and geometry inputs for one table-surface solve.

Methods:

__init__(assets_by_id, root_ids, ...[, ...])
from_layout_problem(*, layout_problem, ...)	Build one table-surface problem without mutating layout state.

__init__(assets_by_id, root_ids, root_seed_xy_by_id, imported_root_ids, fixed_root_xy_by_id, root_table_regions_by_id, table_optimization_rect_xy, root_relations, support_uid='table')

classmethod from_layout_problem(*, layout_problem, group, current_xy_by_id)

Build one table-surface problem without mutating layout state.

Return type:

TableSurfaceLayoutProblem