Real-to-simulation motion prototypes

Real-to-simulation motion prototypes#

These interfaces normalize explicitly annotated joint and TCP data into a source-owned motion unit. Prepared bundles preserve source arrays, frame and time decisions and a content digest. A prototype is a motion reference; the host remains responsible for initial-state preparation, collision and physical effect validation, execution and recording.

The source accepts qpos-only references for fixed-scene replay. Cartesian transfer needs explicit TCP poses and supports tabletop XY/yaw changes. A prototype generated from a synthetic reference remains marked synthetic.

Source-independent real-to-simulation trajectory preparation.

Classes:

`JointSpec`	One target joint and its optional linear mimic relationship.
`NormalizationReport`	Auditable normalization decisions and corrections.
`NormalizedReal2SimUnit`	Canonical full-joint motion and source evidence on one control grid.
`PhaseAnnotation`	A named half-open sample range and its authorized motion edits.
`Real2SimTrajectory`	One explicitly annotated source unit before conversion.
`SkillMotionPrototype`	A normalized skill unit with frozen object and target references.
`TrajectoryTimeMap`	Source brackets and weights for each normalized execution sample.

Functions:

`build_motion_prototype`(unit)	Create a prototype from one explicitly phased normalized skill unit.
`load_prototype`(manifest, *[, max_samples, ...])	Verify a portable prototype and reconstruct its canonical contract.
`load_trajectory`(manifest)	Load and validate one bounded, hash-checked trajectory bundle.
`normalize_trajectory`(source, *, joints, ...)	Convert a labeled motion to canonical joints, frames and control time.
`prepare_prototype`(source, *, joints, ...[, ...])	Normalize, freeze and publish a portable prototype bundle.
`retarget_motion_prototype`(prototype, *[, ...])	Transfer prototype TCP poses to tabletop object and target references.
`save_trajectory`(source, directory)	Write one immutable trajectory bundle and return its manifest path.

class embodichain.data_pipeline.real2sim.JointSpec[source]

One target joint and its optional linear mimic relationship.

Input joint values use the units declared by the source; mimic parameters use canonical radians or metres. A non-mimic joint missing from the input needs an explicit canonical initial_hold.

Methods:

__init__(name, kind[, mimic_driver, ...])

__init__(name, kind, mimic_driver=None, mimic_multiplier=1.0, mimic_offset=0.0, initial_hold=None)

class embodichain.data_pipeline.real2sim.NormalizationReport[source]

Auditable normalization decisions and corrections.

Methods:

__init__(joint_source_indices, corrections, ...)

__init__(joint_source_indices, corrections, time_map, initial_state_origin)

class embodichain.data_pipeline.real2sim.NormalizedReal2SimUnit[source]

Canonical full-joint motion and source evidence on one control grid.

Methods:

__init__(source, joint_names, qpos, ...)

__init__(source, joint_names, qpos, initial_qpos, timestamps, phases, world_tcp, raw_qvel, report)

class embodichain.data_pipeline.real2sim.PhaseAnnotation[source]

A named half-open sample range and its authorized motion edits.

Methods:

__init__(name, start, stop, kind, reference)

__init__(name, start, stop, kind, reference, allowed_operators=(), authority=None)

class embodichain.data_pipeline.real2sim.Real2SimTrajectory[source]

One explicitly annotated source unit before conversion.

eef_poses, when provided, is (N, 7) position and quaternion in pose_frame. The transforms convert from that frame to world and from the observed link to TCP. Object and target anchors are world-frame rigid transforms in metres. origin=measured identifies qpos and optional qvel as observed state. origin=synthetic_reference identifies them as a design reference; synthetic measured rollout state belongs in a separate typed artifact. Neither is evidence of the commands actually submitted. Command alignment independently identifies a submitted stream or a sample-aligned synthetic design reference.

Methods:

__init__(source_id, source_revision, ...[, ...])

Attributes:

`command_semantics`	Distinguish recorded submissions from synthetic sample references.
`qpos_semantics`	Describe the qpos stream from the explicitly declared source origin.
`qvel_semantics`	Describe the preserved raw velocity stream, when one was supplied.

__init__(source_id, source_revision, unit_id, skill_id, origin, joint_names, joint_units, qpos, timestamps, time_unit, phases, eef_poses=None, pose_length_unit=None, quaternion_order=None, world_from_pose_frame=None, observed_link_to_tcp=None, object_pose=None, target_pose=None, qvel=None, initial_observed_qpos=None, commands=None, command_representation=None, command_alignment=None, calibration_revision='unverified', annotation_revision='unverified', pose_origin=None, robot_geometry_sha256=None, object_geometry_sha256=None, target_geometry_sha256=None)

property command_semantics: Literal['actual_submission', 'design_reference'] | None: Distinguish recorded submissions from synthetic sample references.

property qpos_semantics: Literal['measured_state', 'design_reference']: Describe the qpos stream from the explicitly declared source origin.

property qvel_semantics: Literal['measured_state', 'design_reference'] | None: Describe the preserved raw velocity stream, when one was supplied.

class embodichain.data_pipeline.real2sim.SkillMotionPrototype[source]

A normalized skill unit with frozen object and target references.

The stored world TCP trajectory is evidence, not an executable plan. A robot-specific host still has to perform continuous IK, connection planning, complete-plan construction and physical validation.

Methods:

__init__(unit, object_to_tcp)

__init__(unit, object_to_tcp)

class embodichain.data_pipeline.real2sim.TrajectoryTimeMap[source]

Source brackets and weights for each normalized execution sample.

Methods:

__init__(left, right, weight, ...)

__init__(left, right, weight, source_event_indices, execution_event_indices, max_event_error_s)

embodichain.data_pipeline.real2sim.build_motion_prototype(unit)[source]

Create a prototype from one explicitly phased normalized skill unit.

Pick derives the grasp relation at the first lift sample; transport and place derive it at their initial held-object sample. The caller must supply the object’s world pose at that exact event; it is never inferred from the TCP trajectory or an object category.

Parameters:: unit (NormalizedReal2SimUnit) – Normalized source unit with explicit object and TCP poses.
Return type:: SkillMotionPrototype
Returns:: An immutable prototype whose interaction reference is frozen.
Raises:: ValueError – Required phases, anchors or TCP poses are absent.

embodichain.data_pipeline.real2sim.load_prototype(manifest, *, max_samples=1000000, max_output_bytes=268435456)[source]

Verify a portable prototype and reconstruct its canonical contract.

Parameters:

manifest (str | Path) – Path to the prepared prototype manifest.
max_samples (int) – Reader-owned normalized sample budget; the manifest cannot enlarge it.
max_output_bytes (int) – Reader-owned estimated normalization memory budget.

Return type:

SkillMotionPrototype

Returns:

An independently owned skill motion prototype.

Raises:

ValueError – A source, manifest or prepared array does not verify.

embodichain.data_pipeline.real2sim.load_trajectory(manifest)[source]

Load and validate one bounded, hash-checked trajectory bundle.

Parameters:: manifest (str | Path) – Path to a trajectory JSON manifest.
Return type:: Real2SimTrajectory
Returns:: Typed source trajectory with independently owned arrays.
Raises:: ValueError – Manifest, NPZ, digest or source contract is invalid.

embodichain.data_pipeline.real2sim.normalize_trajectory(source, *, joints, control_dt, event_tolerance_s=1e-06, mimic_tolerance=1e-06, max_samples=1000000, max_output_bytes=268435456)[source]

Convert a labeled motion to canonical joints, frames and control time.

Phase starts and the final sample are hard event anchors. They must lie on the destination control grid within event_tolerance_s; short phases are rejected instead of erased. Duplicate stationary samples are coalesced only when neither sample is an event and all recorded payloads agree.

Parameters:

source (Real2SimTrajectory) – Explicitly labeled source trajectory and frame declarations.
joints (Sequence[JointSpec]) – Complete ordered simulator joint layout and mimic contracts.
control_dt (float) – Destination command period in seconds.
event_tolerance_s (float) – Maximum time displacement of a hard event.
mimic_tolerance (float) – Canonical-unit tolerance for redundant mimic evidence.
max_samples (int) – Maximum generated control-grid sample count.
max_output_bytes (int) – Budget for a conservative estimate of generated numeric arrays and working buffers, excluding the already loaded source. This is not a process-RSS or third-party allocator peak bound.

Return type:

NormalizedReal2SimUnit

Returns:

Canonical unit with an auditable source-to-grid mapping.

Raises:

ValueError – The source, calibration, timing or phase contract is invalid.

embodichain.data_pipeline.real2sim.prepare_prototype(source, *, joints, control_dt, directory, event_tolerance_s=1e-06, mimic_tolerance=1e-06, max_samples=1000000, max_output_bytes=268435456)[source]

Normalize, freeze and publish a portable prototype bundle.

The complete source is copied into the bundle, so loading never depends on the original source path. The final manifest is written only after its NPZ and source manifest exist. Existing output is not replaced.

Parameters:

source (Real2SimTrajectory) – Annotated source trajectory.
joints (tuple[JointSpec, ...]) – Complete ordered target-joint layout.
control_dt (float) – Destination command period in seconds.
directory (str | Path) – New or empty output directory.
event_tolerance_s (float) – Maximum hard-event clock error.
mimic_tolerance (float) – Tolerance for redundant mimic values.
max_samples (int) – Maximum normalized sample count before publishing files.
max_output_bytes (int) – Estimated normalization array/work-buffer budget.

Return type:

Path

Returns:

The prepared prototype manifest path.

embodichain.data_pipeline.real2sim.retarget_motion_prototype(prototype, *, object_pose=None, target_pose=None, held_object_to_tcp=None, object_supported_regrasp=False)[source]

Transfer prototype TCP poses to tabletop object and target references.

Pick uses the frozen object pose for approach and close. Lift follows a gravity-aligned rigid transform, preserving world-up displacement instead of taking the relative pose to the moving object. Transport and place use the target reference; a changed held relation is applied in object space.

Parameters:

prototype (SkillMotionPrototype) – Prepared prototype containing normalized world TCP poses.
object_pose (ndarray[tuple[int, ...], dtype[float64]] | None) – Current world object pose for Pick.
target_pose (ndarray[tuple[int, ...], dtype[float64]] | None) – Current world target pose for transport or Place.
held_object_to_tcp (ndarray[tuple[int, ...], dtype[float64]] | None) – Current verified held relation for transport/place.
object_supported_regrasp (bool) – Permit an explicitly verified Pick from the target support at a different height, with up to two degrees of observed tilt. The host must establish the support relation first.

Return type:

ndarray[tuple[int, ...], dtype[float64]]

Returns:

Owned world-frame TCP poses with shape (N, 4, 4).

Raises:

ValueError – Required references are absent or outside tabletop scope.

embodichain.data_pipeline.real2sim.save_trajectory(source, directory)[source]

Write one immutable trajectory bundle and return its manifest path.

The manifest is published last and contains a digest of the NPZ bytes. An existing destination is rejected, including a partial prior bundle.

Parameters:

source (Real2SimTrajectory) – Typed source trajectory.
directory (str | Path) – New or empty destination directory.

Return type:

Path

Returns:

Path to the saved manifest.

Typed source and normalization evidence for annotated motion units.

Classes:

`JointSpec`	One target joint and its optional linear mimic relationship.
`NormalizationReport`	Auditable normalization decisions and corrections.
`NormalizedReal2SimUnit`	Canonical full-joint motion and source evidence on one control grid.
`PhaseAnnotation`	A named half-open sample range and its authorized motion edits.
`Real2SimTrajectory`	One explicitly annotated source unit before conversion.
`TrajectoryTimeMap`	Source brackets and weights for each normalized execution sample.

class embodichain.data_pipeline.real2sim.contracts.JointSpec[source]

One target joint and its optional linear mimic relationship.

Input joint values use the units declared by the source; mimic parameters use canonical radians or metres. A non-mimic joint missing from the input needs an explicit canonical initial_hold.

Methods:

__init__(name, kind[, mimic_driver, ...])

__init__(name, kind, mimic_driver=None, mimic_multiplier=1.0, mimic_offset=0.0, initial_hold=None)

class embodichain.data_pipeline.real2sim.contracts.NormalizationReport[source]

Auditable normalization decisions and corrections.

Methods:

__init__(joint_source_indices, corrections, ...)

__init__(joint_source_indices, corrections, time_map, initial_state_origin)

class embodichain.data_pipeline.real2sim.contracts.NormalizedReal2SimUnit[source]

Canonical full-joint motion and source evidence on one control grid.

Methods:

__init__(source, joint_names, qpos, ...)

__init__(source, joint_names, qpos, initial_qpos, timestamps, phases, world_tcp, raw_qvel, report)

class embodichain.data_pipeline.real2sim.contracts.PhaseAnnotation[source]

A named half-open sample range and its authorized motion edits.

Methods:

__init__(name, start, stop, kind, reference)

__init__(name, start, stop, kind, reference, allowed_operators=(), authority=None)

class embodichain.data_pipeline.real2sim.contracts.Real2SimTrajectory[source]

One explicitly annotated source unit before conversion.

eef_poses, when provided, is (N, 7) position and quaternion in pose_frame. The transforms convert from that frame to world and from the observed link to TCP. Object and target anchors are world-frame rigid transforms in metres. origin=measured identifies qpos and optional qvel as observed state. origin=synthetic_reference identifies them as a design reference; synthetic measured rollout state belongs in a separate typed artifact. Neither is evidence of the commands actually submitted. Command alignment independently identifies a submitted stream or a sample-aligned synthetic design reference.

Methods:

__init__(source_id, source_revision, ...[, ...])

Attributes:

`command_semantics`	Distinguish recorded submissions from synthetic sample references.
`qpos_semantics`	Describe the qpos stream from the explicitly declared source origin.
`qvel_semantics`	Describe the preserved raw velocity stream, when one was supplied.

__init__(source_id, source_revision, unit_id, skill_id, origin, joint_names, joint_units, qpos, timestamps, time_unit, phases, eef_poses=None, pose_length_unit=None, quaternion_order=None, world_from_pose_frame=None, observed_link_to_tcp=None, object_pose=None, target_pose=None, qvel=None, initial_observed_qpos=None, commands=None, command_representation=None, command_alignment=None, calibration_revision='unverified', annotation_revision='unverified', pose_origin=None, robot_geometry_sha256=None, object_geometry_sha256=None, target_geometry_sha256=None)

property command_semantics: Literal['actual_submission', 'design_reference'] | None: Distinguish recorded submissions from synthetic sample references.

property qpos_semantics: Literal['measured_state', 'design_reference']: Describe the qpos stream from the explicitly declared source origin.

property qvel_semantics: Literal['measured_state', 'design_reference'] | None: Describe the preserved raw velocity stream, when one was supplied.

class embodichain.data_pipeline.real2sim.contracts.TrajectoryTimeMap[source]

Source brackets and weights for each normalized execution sample.

Methods:

__init__(left, right, weight, ...)

__init__(left, right, weight, source_event_indices, execution_event_indices, max_event_error_s)

Normalize annotated source units without constructing a simulator.

Functions:

normalize_trajectory(source, *, joints, ...)

Convert a labeled motion to canonical joints, frames and control time.

embodichain.data_pipeline.real2sim.normalize.normalize_trajectory(source, *, joints, control_dt, event_tolerance_s=1e-06, mimic_tolerance=1e-06, max_samples=1000000, max_output_bytes=268435456)[source]

Convert a labeled motion to canonical joints, frames and control time.

Phase starts and the final sample are hard event anchors. They must lie on the destination control grid within event_tolerance_s; short phases are rejected instead of erased. Duplicate stationary samples are coalesced only when neither sample is an event and all recorded payloads agree.

Parameters:

source (Real2SimTrajectory) – Explicitly labeled source trajectory and frame declarations.
joints (Sequence[JointSpec]) – Complete ordered simulator joint layout and mimic contracts.
control_dt (float) – Destination command period in seconds.
event_tolerance_s (float) – Maximum time displacement of a hard event.
mimic_tolerance (float) – Canonical-unit tolerance for redundant mimic evidence.
max_samples (int) – Maximum generated control-grid sample count.
max_output_bytes (int) – Budget for a conservative estimate of generated numeric arrays and working buffers, excluding the already loaded source. This is not a process-RSS or third-party allocator peak bound.

Return type:

NormalizedReal2SimUnit

Returns:

Canonical unit with an auditable source-to-grid mapping.

Raises:

ValueError – The source, calibration, timing or phase contract is invalid.

Frozen-reference demonstration prototypes and tabletop pose transfer.

Classes:

SkillMotionPrototype

A normalized skill unit with frozen object and target references.

Functions:

`build_motion_prototype`(unit)	Create a prototype from one explicitly phased normalized skill unit.
`retarget_motion_prototype`(prototype, *[, ...])	Transfer prototype TCP poses to tabletop object and target references.

class embodichain.data_pipeline.real2sim.prototype.SkillMotionPrototype[source]

A normalized skill unit with frozen object and target references.

The stored world TCP trajectory is evidence, not an executable plan. A robot-specific host still has to perform continuous IK, connection planning, complete-plan construction and physical validation.

Methods:

__init__(unit, object_to_tcp)

__init__(unit, object_to_tcp)

embodichain.data_pipeline.real2sim.prototype.build_motion_prototype(unit)[source]

Create a prototype from one explicitly phased normalized skill unit.

Pick derives the grasp relation at the first lift sample; transport and place derive it at their initial held-object sample. The caller must supply the object’s world pose at that exact event; it is never inferred from the TCP trajectory or an object category.

Parameters:: unit (NormalizedReal2SimUnit) – Normalized source unit with explicit object and TCP poses.
Return type:: SkillMotionPrototype
Returns:: An immutable prototype whose interaction reference is frozen.
Raises:: ValueError – Required phases, anchors or TCP poses are absent.

embodichain.data_pipeline.real2sim.prototype.retarget_motion_prototype(prototype, *, object_pose=None, target_pose=None, held_object_to_tcp=None, object_supported_regrasp=False)[source]

Transfer prototype TCP poses to tabletop object and target references.

Pick uses the frozen object pose for approach and close. Lift follows a gravity-aligned rigid transform, preserving world-up displacement instead of taking the relative pose to the moving object. Transport and place use the target reference; a changed held relation is applied in object space.

Parameters:

prototype (SkillMotionPrototype) – Prepared prototype containing normalized world TCP poses.
object_pose (ndarray[tuple[int, ...], dtype[float64]] | None) – Current world object pose for Pick.
target_pose (ndarray[tuple[int, ...], dtype[float64]] | None) – Current world target pose for transport or Place.
held_object_to_tcp (ndarray[tuple[int, ...], dtype[float64]] | None) – Current verified held relation for transport/place.
object_supported_regrasp (bool) – Permit an explicitly verified Pick from the target support at a different height, with up to two degrees of observed tilt. The host must establish the support relation first.

Return type:

ndarray[tuple[int, ...], dtype[float64]]

Returns:

Owned world-frame TCP poses with shape (N, 4, 4).

Raises:

ValueError – Required references are absent or outside tabletop scope.

Bounded JSON and non-pickle NPZ persistence for source trajectories.

Functions:

`load_prototype`(manifest, *[, max_samples, ...])	Verify a portable prototype and reconstruct its canonical contract.
`load_trajectory`(manifest)	Load and validate one bounded, hash-checked trajectory bundle.
`prepare_prototype`(source, *, joints, ...[, ...])	Normalize, freeze and publish a portable prototype bundle.
`save_trajectory`(source, directory)	Write one immutable trajectory bundle and return its manifest path.

embodichain.data_pipeline.real2sim.io.load_prototype(manifest, *, max_samples=1000000, max_output_bytes=268435456)[source]

Verify a portable prototype and reconstruct its canonical contract.

Parameters:

manifest (str | Path) – Path to the prepared prototype manifest.
max_samples (int) – Reader-owned normalized sample budget; the manifest cannot enlarge it.
max_output_bytes (int) – Reader-owned estimated normalization memory budget.

Return type:

SkillMotionPrototype

Returns:

An independently owned skill motion prototype.

Raises:

ValueError – A source, manifest or prepared array does not verify.

embodichain.data_pipeline.real2sim.io.load_trajectory(manifest)[source]

Load and validate one bounded, hash-checked trajectory bundle.

Parameters:: manifest (str | Path) – Path to a trajectory JSON manifest.
Return type:: Real2SimTrajectory
Returns:: Typed source trajectory with independently owned arrays.
Raises:: ValueError – Manifest, NPZ, digest or source contract is invalid.

embodichain.data_pipeline.real2sim.io.prepare_prototype(source, *, joints, control_dt, directory, event_tolerance_s=1e-06, mimic_tolerance=1e-06, max_samples=1000000, max_output_bytes=268435456)[source]

Normalize, freeze and publish a portable prototype bundle.

The complete source is copied into the bundle, so loading never depends on the original source path. The final manifest is written only after its NPZ and source manifest exist. Existing output is not replaced.

Parameters:

source (Real2SimTrajectory) – Annotated source trajectory.
joints (tuple[JointSpec, ...]) – Complete ordered target-joint layout.
control_dt (float) – Destination command period in seconds.
directory (str | Path) – New or empty output directory.
event_tolerance_s (float) – Maximum hard-event clock error.
mimic_tolerance (float) – Tolerance for redundant mimic values.
max_samples (int) – Maximum normalized sample count before publishing files.
max_output_bytes (int) – Estimated normalization array/work-buffer budget.

Return type:

Path

Returns:

The prepared prototype manifest path.

embodichain.data_pipeline.real2sim.io.save_trajectory(source, directory)[source]

Write one immutable trajectory bundle and return its manifest path.

The manifest is published last and contains a digest of the NPZ bytes. An existing destination is rejected, including a partial prior bundle.

Parameters:

source (Real2SimTrajectory) – Typed source trajectory.
directory (str | Path) – New or empty destination directory.

Return type:

Path

Returns:

Path to the saved manifest.

Original DROID recordings retain measured joint states, optional measured velocities, submitted commands and both acquisition clocks as separate streams. The adapter requires explicit manual phases and base/flange/TCP calibration. Its reported Cartesian poses are FK-derived, not independent TCP measurements. Typed evidence archives the original streams alongside the self-contained HDF5; missing velocities are not reconstructed as observations.

Bounded ingestion of original DROID HDF5 observations and submissions.

DROID Cartesian observations are robot-reported forward kinematics, rather than independent optical TCP measurements. The adapter retains the reported link and requires an explicit link-to-TCP calibration when making a source unit.

Classes:

DroidEpisode

Owned original robot streams, including commands that were skipped.

Functions:

`build_droid_trajectory`(episode, *, ...[, ...])	Build one manually annotated unit from original observed states.
`load_droid_episode`(trajectory, *[, ...])	Read selected original streams without loading embedded images.
`save_droid_unit_evidence`(episode, ...)	Save original typed streams and annotation/calibration for one unit.
`verify_droid_unit_evidence`(evidence, ...)	Verify original HDF5, typed streams and the exact imported source unit.

class embodichain.data_pipeline.real2sim.droid.DroidEpisode[source]#

Owned original robot streams, including commands that were skipped.

Gripper values are normalized closed fractions, not joint positions or metres. A calibrated embodiment must convert the observed fraction to its joint coordinates independently of the submitted command. Raw arm velocity remains available even when a full-layout source cannot express missing gripper velocity. Times are original millisecond clock offsets converted to seconds; they are not replaced by the nominal DROID frame rate.

Parameters:

sha256 (str) – Digest of the original HDF5 bytes.
arm_qpos (ndarray) – Observed seven-joint arm positions in radians.
arm_qvel (ndarray | None) – Observed arm velocities, or None when absent.
reported_poses (ndarray) – Robot-reported link position and XYZW quaternion.
gripper_closed_fraction (ndarray) – Observed normalized gripper position.
arm_commands (ndarray) – Submitted/computed arm position targets in radians.
gripper_commands (ndarray) – Submitted/computed normalized gripper targets.
submitted (ndarray) – Whether the record actually submitted its action.
timestamps (ndarray) – State-read clock offsets in seconds.
command_timestamps (ndarray) – Control-start clock offsets on the same clock.

Methods:

__init__(sha256, arm_qpos, arm_qvel, ...)

__init__(sha256, arm_qpos, arm_qvel, reported_poses, gripper_closed_fraction, arm_commands, gripper_commands, submitted, timestamps, command_timestamps)#

embodichain.data_pipeline.real2sim.droid.build_droid_trajectory(episode, *, source_id, unit_id, skill_id, start, stop, arm_joint_names, gripper_joint_names, gripper_joint_units, observed_gripper_qpos, phases, world_from_base, reported_link_to_tcp, object_pose, target_pose, calibration_revision, annotation_revision, robot_geometry_sha256=None, object_geometry_sha256=None, target_geometry_sha256=None)[source]#

Build one manually annotated unit from original observed states.

Parameters:

episode (DroidEpisode) – Original bounded DROID evidence.
source_id (str) – Stable episode identity from published metadata.
unit_id (str) – Unique annotated unit within this episode.
skill_id (Literal['pick_up', 'move_held_object', 'place']) – Existing Pick, held-motion or Place Atomic Skill identity.
start (int) – First included original observation index.
stop (int) – First excluded original observation index.
arm_joint_names (Sequence[str]) – Seven names in original DROID arm order.
gripper_joint_names (Sequence[str]) – Explicit names for calibrated gripper observations.
gripper_joint_units (Sequence[str]) – Units of those calibrated joint coordinates.
observed_gripper_qpos (ndarray) – Converted observed gripper stream for the full episode, not converted command targets. Conversion provenance belongs in the annotation/calibration sidecar.
phases (Sequence[PhaseAnnotation]) – Contiguous, unit-local annotated phase ranges.
world_from_base (ndarray) – Explicit source-base to world calibration.
reported_link_to_tcp (ndarray) – Explicit reported-link to physical TCP transform.
object_pose (ndarray) – Annotated frozen world object pose in metres.
target_pose (ndarray | None) – Annotated frozen target pose, if used by this skill.
calibration_revision (str) – Pinned coordinate and gripper calibration identity.
annotation_revision (str) – Pinned phase/object annotation identity.
robot_geometry_sha256 (str | None) – Qualified robot model digest, if available.
object_geometry_sha256 (str | None) – Qualified physical proxy digest, if available.
target_geometry_sha256 (str | None) – Qualified support proxy digest, if available.

Return type:

Real2SimTrajectory

Returns:

A measured source unit preserving independent original commands.

Raises:

ValueError – The range includes skipped submissions or invalid mappings.

embodichain.data_pipeline.real2sim.droid.load_droid_episode(trajectory, *, max_samples=200000, max_array_bytes=134217728)[source]#

Read selected original streams without loading embedded images.

Parameters:

trajectory (str | Path) – Original trajectory.h5 file, not an RLDS conversion.
max_samples (int) – Maximum input observations, checked before array reads.
max_array_bytes (int) – Limit on selected decoded source-array bytes.

Return type:

DroidEpisode

Returns:

Immutable state and command evidence on the original clock.

Raises:

ValueError – Required streams, shapes, clocks or budgets are invalid.

embodichain.data_pipeline.real2sim.droid.save_droid_unit_evidence(episode, destination, *, source_id, unit_id, start, stop, arm_joint_names, calibrated_gripper_qpos, annotation, calibration)[source]#

Save original typed streams and annotation/calibration for one unit.

Raw arm velocity and skipped submissions remain source evidence; they are never padded into simulation observations or a full-layout measured velocity. The original HDF5 is pinned separately by episode.sha256.

Parameters:

episode (DroidEpisode) – Original observed/command streams.
destination (str | Path) – New NPZ file, published without replacing prior evidence.
source_id (str) – Published original episode identity.
unit_id (str) – Unit identity used by the prepared prototype.
start (int) – Original first observation index.
stop (int) – Original first excluded observation index.
arm_joint_names (Sequence[str]) – Seven canonical names in original DROID order.
calibrated_gripper_qpos (ndarray) – Whole-episode conversion of observed aperture.
annotation (Mapping[str, object]) – JSON-compatible human annotations and conversion provenance.
calibration (Mapping[str, object]) – JSON-compatible calibration including world_from_base and reported_link_to_tcp matrices.

Return type:

Path

Returns:

Published typed evidence path.

embodichain.data_pipeline.real2sim.droid.verify_droid_unit_evidence(evidence, original_recording, source)[source]#

Verify original HDF5, typed streams and the exact imported source unit.

Parameters:

evidence (str | Path) – NPZ produced by save_droid_unit_evidence().
original_recording (str | Path) – Original immutable DROID HDF5 recording.
source (Real2SimTrajectory) – Measured source unit reconstructed from the prototype bundle.

Raises:

ValueError – Source identity, original streams, crop, commands or explicit calibration differ, or required raw velocity evidence is missing.

Return type:

None

Read-only replay export verifies each episode’s matching complete recorder journal, receipt identities, source bundles and attachment digests. It retains failed attempts and creates no new collection or submission identities.

Read-only replay indexes over committed Real2Sim recording attachments.

Functions:

export_real2sim_replay_manifest(datasets, ...)

Export verified recording references without executing or resubmitting.

embodichain.data_pipeline.real2sim.replay.export_real2sim_replay_manifest(datasets, destination, *, source_assets=None)[source]#

Export verified recording references without executing or resubmitting.

Existing candidate, attempt, commit, submission and episode identities are retained. A confirmed receipt is necessary, along with a complete recorder journal and matching source/trace/evidence digests. The index does not turn an unexecuted target path into a physical execution or certify dynamics. Failed attempts are retained separately even for datasets with no commits.

Parameters:

datasets (Sequence[str | Path]) – Local recorder roots, each containing meta/info.json.
destination (str | Path) – New JSON index; existing exports are never overwritten.
source_assets (Mapping[str, Mapping[str, str]] | None) – Optional named original videos or calibration evidence, each with a local absolute path and pinned sha256. These are read-only source references, not additional collection sessions.

Return type:

Path

Returns:

Absolute path of the newly published replay index.

Raises:

ValueError – A recording, identity, source or necessary attachment cannot be verified. Nothing is written to any input dataset.
FileExistsError – The destination already exists.

Nominal motion is selected before native planning. The corresponding atomic skill owns effect and command construction. Sampled collision evidence is separate from a physical outcome; an unverified collision check cannot certify the resulting rollout.

Transport-neutral nominal motion supplied to an atomic skill.

Classes:

`InstantiatedSkillMotion`	An external full-joint motion with explicit skill-stage boundaries.
`NominalMotionSource`	Provide motion for one grounded invocation without owning its effects.

class embodichain.lab.sim.atomic_actions.nominal.InstantiatedSkillMotion[source]

An external full-joint motion with explicit skill-stage boundaries.

The skill owns semantic effects and command assembly. A source cannot commit held state or step the environment. grasp_pose is an optional world-frame candidate used by skills with an acquisition boundary. IK smoothing records both its total iterations and any hold-phase feasibility iterations. Those adjustments precede the frozen plan used by trajectory expansion.

Methods:

`__init__`(trajectory, success, ...[, ...])
`provenance`()	Return stable source evidence for the assembled plan.

__init__(trajectory, success, segment_lengths, initial_qpos, source_id, source_revision, unit_id, origin, authority='qpos', collision_evidence='unverified', pose_origin='unknown', qpos_semantics='unknown', source_command_semantics=None, fk_position_error_m=None, fk_rotation_error_rad=None, gripper_mode='recorded', initial_state_origin='unknown', calibration_revision='unverified', annotation_revision='unverified', prototype_sha256=None, source_time_map=None, source_sample_offset=0, ik_smoothing_iterations=0, ik_hold_smoothing_iterations=0, object_supported_regrasp=False, semantic_anchor_position_correction_m=0.0, semantic_anchor_rotation_correction_rad=0.0, phase_permissions=<factory>, grasp_pose=None, joint_names=(), refinement_report=<factory>, refinement_original_tcp=None, refinement_target_tcp=None)

provenance()[source]

Return stable source evidence for the assembled plan.

Return type:: dict[str, object]

class embodichain.lab.sim.atomic_actions.nominal.NominalMotionSource[source]

Provide motion for one grounded invocation without owning its effects.

Methods:

`__init__`(args, *kwargs)
`instantiate`(request, context)	Create a side-effect-free motion candidate for the current scene.

__init__(*args, **kwargs)

instantiate(request, context)[source]

Create a side-effect-free motion candidate for the current scene.

Return type:: InstantiatedSkillMotion

Fixed-geometry prototype motion sources for atomic-skill planning.

Classes:

PrototypeMotionProvider

Instantiate a prototype with an explicit motion authority.

class embodichain.lab.sim.atomic_actions.prototype_source.PrototypeMotionProvider[source]

Instantiate a prototype with an explicit motion authority.

qpos requires the source object and target poses. eef_pose retargets tabletop XY/yaw changes through IK, and hybrid uses the authority declared for every phase. The host must independently establish that robot and object geometry are compatible: entity poses and joint names alone do not prove asset identity. Environment lifecycle and persistence remain host-owned.

Parameters:

prototype (SkillMotionPrototype) – Prepared, normalized source prototype.
object_entity_id (str) – Scene entity carrying the source object pose.
target_entity_id (str | None) – Scene entity carrying the source target pose when one is declared by the prototype.
target_entity_to_reference (ndarray | None) – Optional rigid transform from that entity to the prototype’s target reference frame.
pose_tolerance (float) – Absolute matrix tolerance for fixed scene references.
gripper_mode (Literal['recorded', 'semantic']) – Use recorded values or reconstruct semantic commands.
authority (Literal['qpos', 'eef_pose', 'hybrid']) – Authoritative joint or TCP path, globally or by phase.
motion_generator (object | None) – Robot motion services for IK and collision checking.
require_collision_validation (bool) – Require the backend’s sampled checker.
prototype_sha256 (str | None) – Optional content-addressed source identity.
object_support_validator (Callable[[PlanningContext], bool] | None) – Optional trusted host check for regrasping an object currently resting on the target support.
ik_smoothing_trigger_fraction (float | None) – Optional fraction of the motion policy’s acceleration limit at which to seek a lower-acceleration nominal path without changing protected samples or the TCP error tube.
joint_acceleration_limits (tuple[float, ...] | None) – Optional full-robot joint limits supplied by the host. Nominal feasibility uses the tighter of these limits and the motion policy; final plan and observed-effect checks still run.
refinement (MotionRefinementCfg | None) – Optional bounded Cartesian interaction repair before the expansion baseline. Only explicit eef_pose authority supports it.
grasp_pose_generators (Mapping[str, GraspPoseGenerator] | None) – Existing runtime gripper services keyed by the configured grasp control part; required for Pick refinement.
refinement_release_validator (Callable[[PlanningContext, ndarray, MotionRefinementCfg], Mapping[str, object]] | None) – Host-owned physical support check for refined Place targets. It must verify footprint and release gap.

A required acceleration-feasibility pass can adjust Cartesian-authoritative hold interiors before the nominal geometry baseline is frozen. Its FK error is checked and its iterations are recorded. Optional headroom smoothing never changes contact or hold samples.

Methods:

`__init__`(prototype, object_entity_id[, ...])
`instantiate`(request, context)	Build a fixed-scene nominal motion for the active invocation.

__init__(prototype, object_entity_id, target_entity_id=None, target_entity_to_reference=None, pose_tolerance=1e-05, gripper_mode='recorded', authority='qpos', motion_generator=None, require_collision_validation=True, prototype_sha256=None, object_support_validator=None, ik_smoothing_trigger_fraction=None, joint_acceleration_limits=None, refinement=None, grasp_pose_generators=None, refinement_release_validator=None)

instantiate(request, context)[source]

Build a fixed-scene nominal motion for the active invocation.

Return type:: InstantiatedSkillMotion

Adapt normalized fixed-scene source units to expansion templates.

Classes:

Real2SimSourceAdapter

Export a normalized qpos unit under explicit controlled-joint ownership.

class embodichain.lab.sim.motion.expansion.real2sim.Real2SimSourceAdapter[source]

Export a normalized qpos unit under explicit controlled-joint ownership.

This adapter does not move a scene, validate the initial state, or certify a grasp. The host must ensure that source geometry and initial state match; changing object poses requires a separate Cartesian replan.

Parameters:

controlled_joint_indices (tuple[int, ...]) – Full-layout joints authorized for expansion.
validator_id (str) – Host-owned physical validation contract identifier.

Methods:

`__init__`(controlled_joint_indices[, ...])
`export_template`(source, *, context)	Return an owned, explicitly phased full-joint trajectory template.

__init__(controlled_joint_indices, validator_id='default')

export_template(source, *, context)[source]

Return an owned, explicitly phased full-joint trajectory template.

Return type:: TrajectoryTemplate

Control-grid retiming with explicit hard-event and derivative mapping.

Classes:

MappedRetimeResult

A retimed trajectory and source brackets for its new control grid.

Functions:

retime_with_time_map(template, *, ...[, ...])

Retime authorized phase interiors while preserving protected stencils.

class embodichain.lab.sim.motion.expansion.mapped_timing.MappedRetimeResult[source]

A retimed trajectory and source brackets for its new control grid.

Methods:

__init__(template, time_map)

__init__(template, time_map)

embodichain.lab.sim.motion.expansion.mapped_timing.retime_with_time_map(template, *, duration_scale, control_dt, protected_indices=(), max_samples=1000000)[source]

Retime authorized phase interiors while preserving protected stencils.

Source control intervals must already equal control_dt. Each selected phase’s total duration is scaled and rounded up to a control interval; protected intervals retain their duration and editable gaps absorb the difference. A one-sample neighborhood of every protected event remains on its original local time grid. Only the gaps between those neighborhoods are retimed. Every output sample records its source bracket; protected samples have exact mappings. This is a sampled geometric transform, not a collision or dynamics check.

Parameters:

template (TrajectoryTemplate) – Full-joint source with explicitly authorized retime phases.
duration_scale (float) – Positive scale applied to eligible phase interiors.
control_dt (float) – Authoritative control period in seconds.
protected_indices (tuple[int, ...]) – Additional source samples that must remain exact.
max_samples (int) – Upper bound on the output sample count.

Return type:

MappedRetimeResult

Returns:

Retimed template and its source-to-output mapping.

Raises:

ValueError – Timing, permissions, protected samples or budget are invalid.

Mapped retiming scales each authorized free phase’s total elapsed time to the next control interval while leaving protected event neighborhoods and contact-phase durations fixed. If those constraints cannot fit the requested duration, it rejects the proposal instead of changing the physics timestep.

The synchronous B=1 sink accepts an explicitly validated rollout with its terminal observation, source artifacts and action-to-plan trace. It closes buffered LeRobot writers and checks the existing journal and artifact digests before confirming a receipt. Callers must provide the task-specific acceptance checks, collision and asset-compatibility evidence, and coordinate Gym reset. The Gym submission helper can apply a receipt to an existing expansion session; its coverage advances only after confirmation. A failed write retains its payload for the existing idempotent retry and repair boundary.

real2sim_lineage in episode metadata declares a scene revision, compiled program SHA-256, source bundles and a digest-checked NPZ trace. The trace has one step_call_index and step_plan_index for each submitted action; -1 marks a runtime hold without a plan sample. For each call_<index>, left, right and weight map expanded-plan samples to the original plan, while source_events and plan_events map exact phase boundaries. The call’s source_sample_offset separates added connection samples from the normalized source, whose own source map stays in the archived prototype. The sink rejects missing plan samples, unexpressible hard events and mismatched artifact hashes. The B=1 scene integration can opt into action tracing through the Task Program bridge. The caller must assemble the trace artifact, establish that it describes submitted commands and supply independent physical evidence.

Synchronous durable recording for source-qualified B=1 episodes.

Classes:

Real2SimLeRobotEpisodeSink

Commit accepted, sensor-free episodes through a synchronous recorder.

Functions:

`build_real2sim_execution_trace`(...[, ...])	Build a typed action-to-plan sidecar from acknowledged B=1 actions.
`capture_real2sim_episode`(env, *, identity, ...)	Capture one actual B=1 Gym rollout before reset or buffer clearing.
`submit_and_discard_real2sim_episode`(env, ...)	Submit one owned rollout and prevent Gym from committing it twice.

class embodichain.lab.gym.envs.managers.real2sim_sink.Real2SimLeRobotEpisodeSink[source]

Commit accepted, sensor-free episodes through a synchronous recorder.

The sink closes the SDK’s buffered writers and verifies the existing recording journal before confirming each receipt. It reopens the same dataset for the next episode. It never steps or resets the environment. Source bundles, the terminal observation and an explicit action-to-plan trace are copied as typed artifacts. An absent, incomplete or unmappable trace prevents a confirmed receipt; runtime holds must be identified instead of being attributed to an invented source sample.

Parameters:

recorder (LeRobotRecorder) – A synchronous B=1 LeRobot recorder without image/video data.
observation_fields (Mapping[str, tuple[str, ...]]) – Explicit source observation keys to TensorDict paths expected by the recorder, such as ("robot", "qpos").
action_representation (str) – Exact recorded action representation.
required_check_ids (tuple[str, ...]) – Explicit host-owned motion, collision and task evidence that must all be present and passing before submission.

Methods:

`__init__`(recorder, *, observation_fields, ...)
`submit`(episode, *, submission_id)	Commit one accepted episode and return its disk-verified receipt.

__init__(recorder, *, observation_fields, action_representation, required_check_ids)[source]

submit(episode, *, submission_id)[source]

Commit one accepted episode and return its disk-verified receipt.

Return type:: CommitReceipt

embodichain.lab.gym.envs.managers.real2sim_sink.build_real2sim_execution_trace(consumed_actions, motions, *, retime_maps=None)[source]

Build a typed action-to-plan sidecar from acknowledged B=1 actions.

The bridge records only actions consumed by env.step. A -1 plan index identifies a runtime or post-policy action without a source-plan sample; repeated plan indices retain effect-gate and terminal commands. Retime maps describe expanded plan samples in the nominal plan grid.

Parameters:

consumed_actions (Sequence[Mapping[str, object]]) – Ordered rows from TaskProgramDemoBridge.execution_trace.
motions (Mapping[int, InstantiatedSkillMotion]) – Captured source motions keyed by compiled call occurrence.
retime_maps (Mapping[int, TrajectoryTimeMap] | None) – Optional plan-to-nominal maps for retimed occurrences.

Return type:

dict[str, ndarray]

Returns:

NPZ-compatible, non-object arrays accepted by the Real2Sim sink.

Raises:

ValueError – If a step, call, event or source-plan sample is missing.

embodichain.lab.gym.envs.managers.real2sim_sink.capture_real2sim_episode(env, *, identity, validation, episode_id, commit_id, observation_fields, action_representation, metadata, phases=())[source]

Capture one actual B=1 Gym rollout before reset or buffer clearing.

Every returned observation includes the seeded post-action terminal frame. A full buffer without space for that observation is rejected instead of synthesizing a state. The caller supplies independent validation evidence.

Return type:: ExpertEpisode

embodichain.lab.gym.envs.managers.real2sim_sink.submit_and_discard_real2sim_episode(env, sink, episode, *, submission_id, session=None, reset_on_confirmed=True)[source]

Submit one owned rollout and prevent Gym from committing it twice.

The buffer is made ineligible for normal reset-time persistence. By default a confirmed receipt resets with save_data=False; a host that must publish additional confirmation evidence first can set reset_on_confirmed=False and owns the later reset. Unconfirmed submissions retain their blocked buffer for diagnosis. If a session is supplied, the initial submission reserves measured coverage before writing and applies the returned receipt afterwards. For a retry, obtain the payload and next submission ID from session.retry_write; a retry never re-executes the episode.

Return type:: CommitReceipt

For fixed tabletop geometry, the sampled collision checker loads the complete robot URDF collision geometry and requires an explicit scene-object pose at every sample. Contact exemptions and maximum penetration are declared per phase; adjacent robot links are excluded using URDF joint topology. The host checks geometry fingerprints and projects commanded gripper closure to a sampled first contact. Execution must still be checked against measured states; these interfaces do not establish continuous-time or hardware feasibility.

Sampled collision checks for annotated, fixed-geometry manipulation.

The host owns the actual scene and supplies one world pose per object and sample. In particular, held and released object poses must come from the appropriate grasp relation and release policy, or from measured simulation state. The checker does not infer a missing object path or advance physics.

Classes:

`BoxCollisionBody`	One physical box attached to a scene body, in metres.
`CollisionPhase`	A half-open interval with explicit allowed contact pairs and depths.
`PlaneCollisionBody`	A fixed plane with occupied half-space along its local negative Z.
`SampledCollisionReport`	Result for the supplied samples; no continuous-path claim is made.
`SampledRobotCollisionChecker`	Check full robot and scene geometry at B=1 trajectory samples.

class embodichain.lab.sim.motion.expansion.real2sim_collision.BoxCollisionBody[source]

One physical box attached to a scene body, in metres.

uid is the scene body ID; its collision entity ID is body:<uid>. The host must obtain dimensions and local pose from physical geometry, rather than a visual mesh. Static-static pairs are not evaluated.

Methods:

`__init__`(uid, half_extents, local_pose[, ...])
`from_rigid_object`(obj, *[, env_id])	Read a single physical box from a live scene object.

Attributes:

geometry_sha256

Identify box geometry independent of its pose, role and scene ID.

__init__(uid, half_extents, local_pose, is_static=False)

classmethod from_rigid_object(obj, *, env_id=0)[source]

Read a single physical box from a live scene object.

Other shapes or multi-shape bodies are rejected; replacing them with a guessed bounding box would not establish collision compatibility.

Return type:: BoxCollisionBody

property geometry_sha256: str: Identify box geometry independent of its pose, role and scene ID.

class embodichain.lab.sim.motion.expansion.real2sim_collision.CollisionPhase[source]

A half-open interval with explicit allowed contact pairs and depths.

Pair names use robot:<URDF link> and body:<scene uid>. Contact exemptions are symmetric and only apply within this phase. Maximum penetration is measured by the collision backend in metres.

Methods:

__init__(name, start, stop, allowed_contacts)

__init__(name, start, stop, allowed_contacts)

class embodichain.lab.sim.motion.expansion.real2sim_collision.PlaneCollisionBody[source]

A fixed plane with occupied half-space along its local negative Z.

Methods:

__init__(uid, local_pose[, is_static])

__init__(uid, local_pose, is_static=True)

class embodichain.lab.sim.motion.expansion.real2sim_collision.SampledCollisionReport[source]

Result for the supplied samples; no continuous-path claim is made.

Methods:

__init__(accepted, sample_count, geometry_sha256)

__init__(accepted, sample_count, geometry_sha256, first_failure_sample=None, first_failure_phase=None, first_failure_pair=None, first_failure_penetration_m=None, reason=None, allowed_contact_samples=0)

class embodichain.lab.sim.motion.expansion.real2sim_collision.SampledRobotCollisionChecker[source]

Check full robot and scene geometry at B=1 trajectory samples.

Robot collision meshes are read once from the full assembled URDF. The sampled joint names must exactly match its scalar joints. Same-rigid-body and directly connected joint pairs are excluded from self-collision; those topology exclusions are available in excluded_self_pairs. All other robot self pairs and robot/scene pairs are evaluated. Object paths are explicit per-sample world poses and are never silently frozen.

geometry_sha256 identifies named joints and collision content without assembly headers or cache locations. Source validation supports exact v1 byte identities and independently pinned aliases for portable rebuilds.

Parameters:

urdf_path (str | Path) – Full fixed-base robot URDF including its end effector.
joint_names (Sequence[str]) – Complete simulator joint order, including mimic joints.
bodies (Sequence[BoxCollisionBody | PlaneCollisionBody]) – Physical scene boxes and fixed planes to include in each sample.
world_from_base (object) – Fixed world pose of the URDF root.

Methods:

`__init__`(urdf_path, *, joint_names, bodies, ...)
`first_link_body_contact`(start, end, *, link, ...)	Locate the first sampled contact of any declared link along a sweep.
`validate`(joint_positions, *, body_poses, phases)	Evaluate every supplied full-joint and object pose sample.
`validate_prismatic_link`(link, joint_name)	Require a declared finger to be attached to its prismatic joint.
`validate_source_geometry`(source, *, object_uid)	Require source geometry identities to match this live model.

Attributes:

bodies

Return the immutable physical geometry declarations.

__init__(urdf_path, *, joint_names, bodies, world_from_base)[source]

property bodies: tuple[BoxCollisionBody | PlaneCollisionBody, ...]: Return the immutable physical geometry declarations.

first_link_body_contact(start, end, *, link, body_uid, body_pose, iterations=24)[source]

Locate the first sampled contact of any declared link along a sweep.

This is a geometric estimate for a grasp command, not evidence that a physical controller will attain or maintain contact. The caller must A sequence of links shares one full-joint sweep and stops at the first contact of any member. This preserves a coupled gripper’s single drive coordinate. Search uses 64 coarse intervals followed by bisection. Contacts entering and leaving between coarse samples may not be detected.

Return type:: float
Returns:: The last non-contact fraction in [0, 1].
Raises:: ValueError – The pair, input, or endpoint contact is unavailable.

validate(joint_positions, *, body_poses, phases)[source]

Evaluate every supplied full-joint and object pose sample.

Body poses must be (T, 4, 4) and cover every configured body; callers must explicitly repeat a frozen pose. Phase intervals must cover every sample once. A failed result identifies the first pair in deterministic sample/pair order.

Return type:: SampledCollisionReport

validate_prismatic_link(link, joint_name)[source]

Require a declared finger to be attached to its prismatic joint.

Return type:: None

validate_source_geometry(source, *, object_uid, target_uid=None)[source]

Require source geometry identities to match this live model.

The source must have been captured with independent asset identities; joint-name or pose equality is not sufficient. Legacy unqualified sources are rejected and can still be used in explicit diagnostics.

Return type:: None

Gripper contact projection is explicitly selected by the host. Independent prismatic fingers retain their existing projection. Coupled mimic grippers advance one driver and all followers together until the first contact of any declared finger link. Measured coupling tolerances never relax command coupling. Internal mechanism collision pairs and their depth bounds must be named.

Explicit independent and URDF-mimic gripper contact projection.

Projection predicts where a closing command first meets the object. It is separate from measured post-execution contact/effect validation and never changes the submitted controller targets.

Classes:

`GripperContactProjectionCfg`	Select contact prediction from explicitly declared gripper mechanics.
`GripperContactProjector`	Predict a contact-limited joint path without mutating a nominal plan.

class embodichain.lab.sim.motion.expansion.gripper_contact.GripperContactProjectionCfg[source]#

Select contact prediction from explicitly declared gripper mechanics.

Parameters:

kind (str) – Independent prismatic fingers or a single URDF mimic drive.
driver_joint (str | None) – Required independent drive for coupled mimic mechanics.
mechanism_contacts (tuple[tuple[str, str, float], ...]) – Explicit internal linkage contacts and depth bounds in metres, separate from object/environment contact permissions.
measured_coupling_tolerance (float) – Maximum observed follower error in joint units. Command paths always retain the strict 1e-6 coupling check.

Methods:

`__init__`([kind, driver_joint, ...])
`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__(kind=<factory>, driver_joint=<factory>, mechanism_contacts=<factory>, measured_coupling_tolerance=<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.

class embodichain.lab.sim.motion.expansion.gripper_contact.GripperContactProjector[source]#

Predict a contact-limited joint path without mutating a nominal plan.

The coupled route obtains mimic multipliers and offsets from the exact collision URDF, validates its complete descendant layout, and advances every linked joint with one drive coordinate. Only explicitly selected deployments are qualified; this representation alone does not establish physical contact.

Parameters:

cfg (GripperContactProjectionCfg) – Explicit contact model selection.
checker (SampledRobotCollisionChecker) – Collision checker with this robot’s full joint layout.
urdf_path (str | Path | None) – Same assembled URDF used by the checker.
joint_names (Sequence[str]) – Complete source-order joint layout.
finger_links (Sequence[str]) – Collision links that may establish initial grasp contact.
finger_joints (Sequence[str]) – Complete gripper drive/follower joint declaration.
closing_directions (Sequence[int]) – Closing sign of each declared joint.

Methods:

`__init__`(cfg, checker, *, urdf_path, ...)
`project_close`(positions, *, start, stop, ...)	Predict the first closing contact and preserve all joint couplings.
`project_held`(positions, measured_qpos)	Limit closing predictions to the currently observed held configuration.

Attributes:

mechanism_contacts

Return explicitly bounded internal linkage contact permissions.

__init__(cfg, checker, *, urdf_path, joint_names, finger_links, finger_joints, closing_directions)[source]#

property mechanism_contacts: MappingProxyType#: Return explicitly bounded internal linkage contact permissions.

project_close(positions, *, start, stop, object_uid, object_pose)[source]#

Predict the first closing contact and preserve all joint couplings.

Parameters:

positions (ndarray) – Full nominal command path; returned data owns its storage.
start (int) – First close-phase sample.
stop (int) – First sample after the stationary close phase.
object_uid (str) – Physical object’s collision ID.
object_pose (ndarray) – Frozen world object pose at closure.

Return type:

ndarray

Returns:

A separately owned collision-only joint path, including later holds.

project_held(positions, measured_qpos)[source]#

Limit closing predictions to the currently observed held configuration.

Parameters:

positions (ndarray) – Nominal full-joint commands, including opening/retract.
measured_qpos (ndarray) – Current measured full-joint state from the host.

Return type:

ndarray

Returns:

A separate collision prediction; opening commands remain free to open.

Host-owned sampled collision validation for tabletop Real2Sim plans.

Classes:

`TabletopCollisionGuardFactory`	Validate both the source plan and any episode-owned plan transform.
`TabletopPrototypeCollisionValidator`	Check one source-backed Pick, transport or Place plan at every sample.

class embodichain.lab.task_program.integrations.simulation.real2sim_collision.TabletopCollisionGuardFactory[source]

Validate both the source plan and any episode-owned plan transform.

Parameters:

validator (TabletopPrototypeCollisionValidator) – Phase-aware sampled tabletop collision validator.
delegate (object | None) – Optional call-scoped expansion transform factory.
velocity_limits (Sequence[float] | None) – Optional full-joint speed limits.
acceleration_limits (Sequence[float] | None) – Optional full-joint acceleration limits.
ik_smoothing_trigger_fraction (float | None) – Optional nominal IK headroom threshold; only free phases authorized for task-space variation are adjusted.

Methods:

`__init__`(validator[, delegate, ...])
`create_plan_transform`(request, *, engine)	Build one call's validator and optional expansion transform.

Attributes:

`motion_metrics`	Return checked finite-difference ratios for final call plans.
`motion_targets`	Return the validated motion endpoint for each call occurrence.
`nominal_joint_acceleration_limits`	Return full-layout nominal feasibility bounds without changing them.
`phase_samples`	Return nominal and final sample counts for each semantic phase.
`release_targets`	Return FK-predicted object release poses for collision diagnostics.
`segments`	Return the final validated plan's phase boundaries by occurrence.
`semantic_release_targets`	Return requested world object poses, including all IK/FK goal error.

__init__(validator, delegate=None, *, velocity_limits=None, acceleration_limits=None, ik_smoothing_trigger_fraction=None)[source]

create_plan_transform(request, *, engine)[source]

Build one call’s validator and optional expansion transform.

Return type:: Callable[[ResolvedActionRequest, PlanningContext, ActionPlan], ActionPlan]

property motion_metrics: Mapping[int, Mapping[str, float]]: Return checked finite-difference ratios for final call plans.

property motion_targets: Mapping[int, tuple[str, tuple[int, ...]]]: Return the validated motion endpoint for each call occurrence.

property nominal_joint_acceleration_limits: tuple[float, ...] | None: Return full-layout nominal feasibility bounds without changing them.

property phase_samples: Mapping[int, tuple[tuple[str, int, int], ...]]: Return nominal and final sample counts for each semantic phase.

property release_targets: Mapping[int, ndarray]: Return FK-predicted object release poses for collision diagnostics.

property segments: Mapping[int, tuple[tuple[str, int, int], ...]]: Return the final validated plan’s phase boundaries by occurrence.

property semantic_release_targets: Mapping[int, ndarray]: Return requested world object poses, including all IK/FK goal error.

class embodichain.lab.task_program.integrations.simulation.real2sim_collision.TabletopPrototypeCollisionValidator[source]

Check one source-backed Pick, transport or Place plan at every sample.

The collision model and prototype identities are validated when the host constructs the validator. Pick assumes the object remains at its observed pose until lift; later samples use the grasp relation at lift entry. Transport uses the verified held relation. Place follows that relation through release and places the object on a horizontal support for retract. These are geometric predictions, not a dynamics or continuous-collision guarantee. Hosts must still verify actual task outcomes and object states.

Methods:

`__init__`(*, robot, checker, prototypes, ...)
`object_supported_by_target`(context)	Check the current object's footprint and height on the fixed support.
`phase_policy`(skill_id, phase_name, start, ...)	Describe permitted contacts for a declared skill interval.
`validate`(request, context, plan)	Check source identity, contact permissions and sampled geometry.
`validate_observed`(joint_positions, *, ...)	Check measured robot and object poses using explicit phase ranges.
`validate_refinement_support`(context, ...)	Check the semantic release target against the actual physical boxes.

Attributes:

reports

Return nominal and variant validation results in execution order.

__init__(*, robot, checker, prototypes, object_uid, target_uid, ground_uid, finger_links, finger_joints, closing_directions, base_link, contact_depth_m, base_ground_depth_m, gripper_contact=None)[source]

object_supported_by_target(context)[source]

Check the current object’s footprint and height on the fixed support.

Parameters:: context (PlanningContext) – Current B=1 planning observation.
Return type:: bool
Returns:: Whether the object is supported within the declared contact depth.

phase_policy(skill_id, phase_name, start, stop, *, object_supported_by_target=False)[source]

Describe permitted contacts for a declared skill interval.

A subsequent Pick can start on the target support. Its object/support contact is allowed only when the caller has verified that initial support relation, and remains subject to the configured depth bound.

Parameters:

skill_id (str) – Atomic skill owning the phase.
phase_name (str) – Declared skill phase name.
start (int) – First included sample.
stop (int) – First excluded sample.
object_supported_by_target (bool) – Whether the current object footprint has been verified on the target support.

Return type:

CollisionPhase

Returns:

Phase-specific allowed contact pairs and penetration limits.

property reports: tuple[tuple[str, SampledCollisionReport], ...]: Return nominal and variant validation results in execution order.

validate(request, context, plan)[source]

Check source identity, contact permissions and sampled geometry.

Return type:: SampledCollisionReport

validate_observed(joint_positions, *, object_poses, target_pose, phases)[source]

Check measured robot and object poses using explicit phase ranges.

The target is fixed for the episode; the object must supply a separate measured world pose for every robot sample. No grip projection or inferred object motion is applied to these observations.

Return type:: SampledCollisionReport

validate_refinement_support(context, object_pose, cfg)[source]

Check the semantic release target against the actual physical boxes.

Parameters:

context (PlanningContext) – Current immutable B=1 scene observation.
object_pose (ndarray) – Desired world object pose at release, before falling.
cfg (MotionRefinementCfg) – Explicit footprint margin and maximum allowed release gap.

Return type:

Mapping[str, object]

Returns:

Geometry identities and signed gap/footprint evidence.

Raises:

ValueError – Support is tilted, the object overhangs, penetrates, or the requested release gap exceeds the explicit budget.

The run-task owner captures actual observations and actions before submitting them to the synchronous sink. An unconfirmed write retains a no-pickle staged episode, so a retry uses the same payload instead of executing again. When observed collision validation is required, the sink also verifies and archives the measured T+1 object poses, fixed support pose and timestamps.

Transaction owner for source-qualified Gym and run-task collection.

Classes:

`Real2SimCaptureRequest`	Host-measured acceptance, identity and typed artifact references.
`Real2SimRunTaskOwner`	Own one B=1 source-backed attempt and its persistence transaction.

Functions:

load_staged_real2sim_episode(path)

Recover a bounded no-pickle pending payload for write-only repair.

class embodichain.lab.gym.envs.managers.real2sim_collection.Real2SimCaptureRequest[source]

Host-measured acceptance, identity and typed artifact references.

Observations and actions are intentionally absent: the owner captures them from the actual Gym rollout immediately before submitting to the sink.

Methods:

__init__(identity, validation, episode_id, ...)

__init__(identity, validation, episode_id, commit_id, observation_fields, action_representation, metadata, phases=())

class embodichain.lab.gym.envs.managers.real2sim_collection.Real2SimRunTaskOwner[source]

Own one B=1 source-backed attempt and its persistence transaction.

Trusted host callbacks prepare a traced segment sequence and provide measured validation plus source/trace attachments after execution. The sink verifies those attachments before confirming a receipt. An unconfirmed payload stays owned here for repair or a write-only retry; preparing a new attempt while it exists is rejected.

Methods:

`__init__`(sink, *, prepare_attempt, ...[, ...])
`commit`(env, result)	Capture actual T+1 observations and submit a measured successful run.
`finalize`()	Finalize the owned synchronous recorder without executing again.
`prepare`(env, *, episode_index, attempt_id)	Prepare one source-traced segment stream before any Gym step.
`record_failure`(env, result, *[, error])	Retain host failure evidence before the attempt is reset.
`retry_write`(env, *[, submission_id])	Resume the retained write, including exceptions without a receipt.
`write_collection_report`(*, expected_episodes)	Verify durable receipts, journal entries and attachments for a run.

Attributes:

`confirmed_receipts`	Return receipts durably published by this owner.
`last_receipt`	Return the latest finalized submission result.
`pending_episode`	Return the retained payload after an unconfirmed submission.
`staged_path`	Return durable failed-write evidence, absent after confirmation.

__init__(sink, *, prepare_attempt, capture_request, record_failed_attempt=None, session=None)[source]

commit(env, result)[source]

Capture actual T+1 observations and submit a measured successful run.

Return type:: CommitReceipt

property confirmed_receipts: tuple[CommitReceipt, ...]: Return receipts durably published by this owner.

finalize()[source]

Finalize the owned synchronous recorder without executing again.

Return type:: None

property last_receipt: CommitReceipt | None: Return the latest finalized submission result.

property pending_episode: ExpertEpisode | None: Return the retained payload after an unconfirmed submission.

prepare(env, *, episode_index, attempt_id)[source]

Prepare one source-traced segment stream before any Gym step.

Return type:: Iterable[DemoSegment]

record_failure(env, result, *, error=None)[source]

Retain host failure evidence before the attempt is reset.

Return type:: None

retry_write(env, *, submission_id=None)[source]

Resume the retained write, including exceptions without a receipt.

Parameters:

env (object) – Environment originally captured by this owner.
submission_id (int | None) – Optional expected outstanding/next submission ID. An interrupted call reuses its ID; a final failed receipt advances it. Omit this argument when only publishing a confirmed receipt.

Return type:

CommitReceipt

Returns:

The receipt for this exact pending episode, without another rollout.

property staged_path: Path | None: Return durable failed-write evidence, absent after confirmation.

write_collection_report(*, expected_episodes)[source]

Verify durable receipts, journal entries and attachments for a run.

Return type:: Path

embodichain.lab.gym.envs.managers.real2sim_collection.load_staged_real2sim_episode(path)[source]

Recover a bounded no-pickle pending payload for write-only repair.

The sink must revalidate the source bundles, trace, checks and journal on submission. Loading a pending payload does not confirm persistence.

Return type:: ExpertEpisode

Configured tabletop collection supplies explicit layouts, recipes, collision policy and per-joint motion limits. Its runtime owner coordinates scene setup, source-bound planning, measured verification and one durable episode receipt. Sequential Pick, MoveHeldObject and Place occurrences, including bounded repeats, each require a pinned source. The host separately checks each Pick, held interval and Place. A Pick from an observed support permits a change in height and at most two degrees of tilt only after checking the support footprint; lift remains gravity-aligned. Cartesian Place aligns its release anchor to the semantic target and reports the applied correction. An optional directed yaw tolerance checks observed object +X against the requested object pose, including solver error. The default remains disabled. retime_phase_allowlist can narrow source and skill time permissions; a short protected free phase can retain its original grid while other phases stretch.

Configure one B=1 tabletop Real2Sim owner for the run-task lifecycle.

Classes:

Real2SimTabletopCollectionCfg

Explicit scene, collision policy and deterministic episode recipes.

Functions:

`install_real2sim_tabletop_owner`(env, ...)	Install a configured source, collision and recorder owner on Gym.
`load_real2sim_tabletop_profile`(path)	Load and strictly validate an inert YAML/JSON collection profile.

class embodichain.lab.task_program.integrations.simulation.real2sim_collection.Real2SimTabletopCollectionCfg[source]

Explicit scene, collision policy and deterministic episode recipes.

Each layout supplies id, object_xyyaw and target_xyyaw; offsets are metres and radians. Recipes are selected in listed order for every layout. Acceleration budgets must declare their provenance; a synthetic assumption does not establish real-device capability.

Methods:

`__init__`([kind, scene_revision, object_uid, ...])
`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.

Attributes:

`placement_yaw_tolerance_deg`	Optional directed object-heading tolerance against each Place target.
`retime_phase_allowlist`	Optional per-skill time permissions, intersected with source/skill phases.
`source_artifacts`	Call-scoped original DROID recording and typed source evidence references.

__init__(kind=<factory>, scene_revision=<factory>, object_uid=<factory>, target_uid=<factory>, object_entity_id=<factory>, target_entity_id=<factory>, base_link=<factory>, finger_links=<factory>, finger_joints=<factory>, closing_directions=<factory>, gripper_contact=<factory>, source_artifacts=<factory>, contact_depth_m=<factory>, base_ground_depth_m=<factory>, velocity_limits=<factory>, velocity_limit_origin=<factory>, acceleration_limits=<factory>, acceleration_limit_origin=<factory>, motion_headroom_fraction=<factory>, retime_phase_allowlist=<factory>, layouts=<factory>, recipes=<factory>, seed=<factory>, placement_xy_tolerance_m=<factory>, placement_height_tolerance_m=<factory>, placement_yaw_tolerance_deg=<factory>, minimum_lift_m=<factory>, maximum_drift_m=<factory>, held_translation_tolerance_m=<factory>, held_rotation_tolerance_deg=<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.

placement_yaw_tolerance_deg: float | None: Optional directed object-heading tolerance against each Place target.

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.

retime_phase_allowlist: dict[str, tuple[str, ...]] | None: Optional per-skill time permissions, intersected with source/skill phases.

source_artifacts: dict[int, dict[str, dict[str, str]]]: Call-scoped original DROID recording and typed source evidence references.

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.lab.task_program.integrations.simulation.real2sim_collection.install_real2sim_tabletop_owner(env, profile, *, dataset_dir)[source]

Install a configured source, collision and recorder owner on Gym.

The source bindings come from the integration’s configured runtime services, never from the Task Program. Physical geometry is obtained from the current scene and must match each prototype’s captured identity.

Return type:: Real2SimRunTaskOwner

embodichain.lab.task_program.integrations.simulation.real2sim_collection.load_real2sim_tabletop_profile(path)[source]

Load and strictly validate an inert YAML/JSON collection profile.

Return type:: Real2SimTabletopCollectionCfg

Grasp-pose and constrained qpos operators requiring downstream validation.

Functions:

validate_motion_samples(positions, dt, *, ...)

Check full-joint sampled positions and intervals against motion limits.

embodichain.lab.sim.motion.expansion.operators.validate_motion_samples(positions, dt, *, velocity_limits, acceleration_limits)[source]

Check full-joint sampled positions and intervals against motion limits.

The first interval must be zero; later intervals are strictly positive. This finite-difference check does not establish continuous-time dynamics.

Return type:: ValidationResult

Real-to-simulation motion prototypes

Contents

Real-to-simulation motion prototypes#