embodichain.lab.sim.scene.expansion

Scene expansion describes changes to a base scene before a new task execution. The initial API provides immutable existing-entity pose proposals and a bounded source of authored candidates. Task Program and GenSim hosts can share these contracts without introducing their execution or generation dependencies into the proposal package.

The core owns no physical restoration, task semantics, simulator stepping, episode acceptance, or dataset writes. Public imports use the normal embodichain.lab.sim initialization and require the simulation dependencies; constructing these values creates no simulation world.

SceneExpansionCfg	Limits and permissions for a scene candidate source.
ScenePoseChange	A proposed pose for one existing physical entity.
SceneVariant	An immutable scene proposal with reproducible proposal identity.
FixedSceneCandidateSource	Snapshot a bounded prefix of authored proposals for repeatable iteration.

Frames and proposal identity

ScenePoseChange.arena_pose is a proper homogeneous 4x4 transform from the entity frame into its local Z-up arena. It excludes replication offsets and does not use a robot chain-root frame. Nested numeric input is copied into immutable tuples; nonfinite, reflected, nonorthonormal, or malformed transforms are rejected.

SceneVariant.variant_id includes the original scene identity, seed, ordinal, proposed geometry, and provenance. Entity and provenance ordering is canonicalized. A proposal ID is separate from the actual initial-state identity captured after physical settling, and neither certifies task completion. The seed reproduces a proposal schedule; it does not promise identical physics across engines or versions.

Bounded fixed candidates

FixedSceneCandidateSource snapshots at most max_candidates entries from its input iterable. It leaves later entries untouched, permits changes only to declared movable entity UIDs, and returns the same immutable candidates on each iteration. An empty pose-change tuple is an explicit nominal candidate; an empty source generates no candidates.

from embodichain.lab.sim.scene.expansion import (
    FixedSceneCandidateSource,
    SceneExpansionCfg,
    ScenePoseChange,
)

source = FixedSceneCandidateSource(
    SceneExpansionCfg(seed=7, max_candidates=1, movable_entity_ids=("cube",)),
    parent_scene_id="pick-place-scene:revision-1",
    candidates=[
        (
            ScenePoseChange(
                entity_uid="cube",
                arena_pose=(
                    (1, 0, 0, 0.35),
                    (0, 1, 0, 0.10),
                    (0, 0, 1, 0.76),
                    (0, 0, 0, 1),
                ),
            ),
        ),
    ],
    metadata=(("source", "authored-layout"),),
)
variant = source.variants[0]

This only constructs a proposal. Support, manipulation reachability, collision checks, and task semantics remain explicit host responsibilities. To evaluate one proposal through the shared Task Program executor, use embodichain.lab.task_program.integrations.scene_expansion.

Compatibility imports from embodichain.lab.sim.scene_expansion remain available and refer to the same classes and proposal identities. New code should use embodichain.lab.sim.scene.expansion.

Public contracts

class embodichain.lab.sim.scene.expansion.SceneExpansionCfg

Limits and permissions for a scene candidate source.

Parameters:

• seed (int) – Nonnegative proposal-generation seed; not a physical replay seed.

• max_candidates (int) – Positive maximum candidates consumed from the source.

• movable_entity_ids (tuple[str, ...]) – Unique physical UIDs allowed to change pose. An empty tuple permits only nominal candidates with no pose changes.

Execution and persistence budgets remain owned by the host integration. Calling a scene expansion integration opts in; ordinary execution paths do not consult this configuration.

class embodichain.lab.sim.scene.expansion.ScenePoseChange

A proposed pose for one existing physical entity.

Parameters:

• entity_uid (str) – Stable physical entity UID, independent of environment slots.

• arena_pose (tuple[tuple[float, ...], ...]) – Homogeneous 4x4 transform from the entity frame into its local Z-up arena frame. Inputs are copied into immutable tuples.

Attention

An arena pose excludes replication offsets. The host converts it to backend coordinates when applying the candidate. This contract does not establish support, collision freedom, or manipulation feasibility.

Methods:

__init__(entity_uid, arena_pose)

__init__(entity_uid, arena_pose)

class embodichain.lab.sim.scene.expansion.SceneVariant

An immutable scene proposal with reproducible proposal identity.

Parameters:

• parent_scene_id (str) – Content/revision identity of the original scene.

• seed (int) – Nonnegative proposal-generation seed.

• ordinal (int) – Nonnegative position in the candidate source.

• pose_changes (tuple[ScenePoseChange, ...]) – Unique existing entities and their proposed arena poses.

• metadata (tuple[tuple[str, str], ...]) – Unique string key/value provenance entries. Entries and pose changes are sorted so equivalent input ordering has one identity.

Attention

variant_id identifies a proposal, not a settled initial state or a successful execution. Hosts record those identities and evidence separately. Metadata describes provenance, not executable operations. Since ordinal participates in the hash, consuming the same layout at a different source position changes variant_id. File-backed consumers should retain the original layout identity and proposal ordinal in metadata for provenance across selection orders; this ID is not a geometry-only deduplication key.

Methods:

__init__(parent_scene_id, seed, ordinal, ...)

Attributes:

variant_id

Return a stable identity including geometry, source, seed, and ordinal.

__init__(parent_scene_id, seed, ordinal, pose_changes, metadata=())

property variant_id: str

Return a stable identity including geometry, source, seed, and ordinal.

Returns:

SHA-256 identity independent of Python hash randomization and temporary physical environment assignments.

class embodichain.lab.sim.scene.expansion.FixedSceneCandidateSource

Snapshot a bounded prefix of authored proposals for repeatable iteration.

Parameters:

• cfg (SceneExpansionCfg) – Proposal budget and allowed physical entity UIDs.

• parent_scene_id (str) – Identity of the scene the proposals modify.

• candidates (Iterable[Iterable[ScenePoseChange]]) – Iterable of pose-change iterables. At most cfg.max_candidates entries are consumed; later entries are deliberately untouched. An empty pose-change iterable describes an explicit nominal proposal.

• metadata (tuple[tuple[str, str], ...]) – Immutable string key/value provenance added to each proposal.

The source owns no simulator, retries, or execution state. Configuration is revalidated at this boundary and no mutable caller configuration is retained. Every fresh iteration returns the same immutable proposals.

Methods:

__init__(cfg, parent_scene_id, candidates, *)

Attributes:

variants

Return the bounded, immutable snapshot of candidate proposals.

__init__(cfg, parent_scene_id, candidates, *, metadata=())

property variants: tuple[SceneVariant, ...]

Return the bounded, immutable snapshot of candidate proposals.

Returns:

Candidates in source order, with consecutive zero-based ordinals.

Implementation module exports

SceneExpansionCfg

Limits and permissions for a scene candidate source.

ScenePoseChange	A proposed pose for one existing physical entity.
SceneVariant	An immutable scene proposal with reproducible proposal identity.

FixedSceneCandidateSource

Snapshot a bounded prefix of authored proposals for repeatable iteration.