Data models¶
Typed specs and results passed through the pipeline.
Results¶
Bases: BaseModel
Strict pickle-free retargeting checkpoint.
Methods:
| Name | Description |
|---|---|
resampled |
Return this result sampled on a new FPS grid. |
save_npz |
Save result to |
load_npz |
Load the current strict |
Attributes:
| Name | Type | Description |
|---|---|---|
model_config |
|
|
schema_version |
int
|
|
name |
str
|
|
status |
RunStatus
|
|
qpos |
FloatArray
|
|
fps |
float
|
|
cost |
FloatArray | None
|
|
human_joints |
FloatArray | None
|
|
human_vocabulary |
VocabularyManifest | None
|
|
robot_link_positions |
FloatArray | None
|
|
run |
RetargetingRunReport | None
|
|
playback |
ResultPlaybackSpec | None
|
|
warnings |
tuple[str, ...]
|
|
provenance |
dict[str, Any]
|
|
frame_count |
int
|
Number of frames. |
Attributes¶
class-attribute
instance-attribute
¶
model_config = ConfigDict(arbitrary_types_allowed=True)
class-attribute
instance-attribute
¶
human_vocabulary: VocabularyManifest | None = None
class-attribute
instance-attribute
¶
robot_link_positions: FloatArray | None = None
class-attribute
instance-attribute
¶
provenance: dict[str, Any] = Field(default_factory=dict)Functions¶
resampled(fps: float, *, name: str | None = None) -> RetargetingResultReturn this result sampled on a new FPS grid.
classmethod
¶
load_npz(path: str | Path) -> RetargetingResultLoad the current strict .npz checkpoint schema.
Bases: BaseModel
Evaluation metrics for a result.
Attributes:
| Name | Type | Description |
|---|---|---|
status |
RunStatus
|
Overall evaluation outcome. |
source_name |
str | None
|
Human-readable name of the evaluated result or clip. |
frame_count |
int | None
|
Number of frames in the evaluated motion. |
qpos_dimension |
int | None
|
Robot |
fps |
float | None
|
Sampling rate of the evaluated result. |
task_kind |
str | None
|
Scene task kind string when available. |
robot_name |
str | None
|
Robot preset or asset name. |
motion_name |
str | None
|
Source human motion name. |
metrics |
dict[str, float]
|
Scalar metric values keyed by name. |
metric_units |
dict[str, str]
|
Unit strings aligned with |
details |
dict[str, Any]
|
Structured diagnostic payloads (curves, thresholds, …). |
warnings |
tuple[str, ...]
|
Non-fatal evaluation messages. |
Methods:
| Name | Description |
|---|---|
save_json |
Save report as JSON. |
Bases: BaseModel
Manifest written by batch evaluation runs.
Attributes:
| Name | Type | Description |
|---|---|---|
schema_version |
int
|
On-disk manifest format version. |
created_at |
datetime
|
UTC timestamp when the manifest was first created. |
updated_at |
datetime
|
UTC timestamp of the most recent update. |
total |
int
|
Number of records in |
success_count |
int
|
Records with :attr: |
partial_count |
int
|
Records with :attr: |
skipped_count |
int
|
Records with :attr: |
failed_count |
int
|
Records with :attr: |
records |
tuple[EvaluationRecord, ...]
|
Per-result evaluation entries. |
Methods:
| Name | Description |
|---|---|
from_records |
Build a summary manifest from per-result records. |
load |
Load a batch evaluation manifest JSON file. |
save_json |
Save manifest JSON. |
Attributes¶
class-attribute
instance-attribute
¶
model_config = ConfigDict(arbitrary_types_allowed=True)Functions¶
classmethod
¶
from_records(records: Iterable[EvaluationRecord]) -> EvaluationManifestBuild a summary manifest from per-result records.
classmethod
¶
load(path: str | Path) -> EvaluationManifestLoad a batch evaluation manifest JSON file.
Bases: BaseModel
Recorded outcome for evaluating one retargeting result.
Attributes:
| Name | Type | Description |
|---|---|---|
result_path |
Path
|
Path to the evaluated |
status |
RunStatus
|
Per-result evaluation outcome. |
report_path |
Path | None
|
Optional JSON report written for this result. |
job_id |
str | None
|
Batch or scheduler job identifier. |
source_name |
str | None
|
Human-readable clip or run name. |
frame_count |
int | None
|
Frame count observed during evaluation. |
message |
str
|
Error or skip explanation when |
metrics |
dict[str, float]
|
Scalar metrics copied from the report. |
warnings |
tuple[str, ...]
|
Warnings surfaced during evaluation. |
Scene & motion¶
dataclass
¶
SceneObservation(
name: str,
timeline: SampleTimeline,
world_frame: FrameConvention,
actor: MotionSequence[Any],
landmarks: tuple[PointTrack, ...] = (),
rigid_bodies: tuple[PoseTrack, ...] = (),
objects: tuple[ObservedObject, ...] = (),
contacts: SemanticContactSequence | None = None,
terrain: TerrainSpec | None = None,
alignment_reports: tuple[AlignmentReport, ...] = (),
provenance: dict[str, object] = dict(),
)Shared-timeline result of capture processing before robot adaptation.
Methods:
| Name | Description |
|---|---|
landmark |
Return a semantic landmark track. |
observed_object |
Return an observed object. |
save_npz |
Explicitly save this observation checkpoint without pickle. |
load_npz |
Load an explicit observation checkpoint. |
Attributes:
| Name | Type | Description |
|---|---|---|
name |
str
|
|
timeline |
SampleTimeline
|
|
world_frame |
FrameConvention
|
|
actor |
MotionSequence[Any]
|
|
landmarks |
tuple[PointTrack, ...]
|
|
rigid_bodies |
tuple[PoseTrack, ...]
|
|
objects |
tuple[ObservedObject, ...]
|
|
contacts |
SemanticContactSequence | None
|
|
terrain |
TerrainSpec | None
|
|
alignment_reports |
tuple[AlignmentReport, ...]
|
|
provenance |
dict[str, object]
|
|
Attributes¶
class-attribute
instance-attribute
¶
alignment_reports: tuple[AlignmentReport, ...] = ()
class-attribute
instance-attribute
¶
provenance: dict[str, object] = field(default_factory=dict)Functions¶
observed_object(role: ObservationRole) -> ObservedObjectReturn an observed object.
save_npz(path: str | Path) -> PathExplicitly save this observation checkpoint without pickle.
classmethod
¶
load_npz(path: str | Path) -> SceneObservationLoad an explicit observation checkpoint.
dataclass
¶
ObservedObject(
role: ObservationRole,
pose: PoseTrack,
geometry: ObjectSpec,
provenance: dict[str, object] = dict(),
)Observed object geometry and pose, independent of a target robot.
Attributes:
| Name | Type | Description |
|---|---|---|
role |
ObservationRole
|
|
pose |
PoseTrack
|
|
geometry |
ObjectSpec
|
|
provenance |
dict[str, object]
|
|
dataclass
¶
SemanticContactSequence(
timeline: SampleTimeline,
tracks: tuple[SemanticContactTrack, ...],
support: SupportPlane | None = None,
provenance: dict[str, object] = dict(),
)Robot-independent semantic contacts and support geometry.
Methods:
| Name | Description |
|---|---|
resolve |
Resolve semantic subjects to concrete robot links. |
Attributes:
| Name | Type | Description |
|---|---|---|
timeline |
SampleTimeline
|
|
tracks |
tuple[SemanticContactTrack, ...]
|
|
support |
SupportPlane | None
|
|
provenance |
dict[str, object]
|
|
Attributes¶
class-attribute
instance-attribute
¶
provenance: dict[str, object] = field(default_factory=dict)Functions¶
resolve(link_mapping: Mapping[ContactSubject, Sequence[RobotLink]]) -> ContactPlanResolve semantic subjects to concrete robot links.
Bases: BaseModel
Scene configuration for a retargeting run.
Attributes:
| Name | Type | Description |
|---|---|---|
task_kind |
TaskKind
|
High-level workflow (robot-only, object interaction, climbing). |
object |
ObjectSpec | None
|
Manipulated or climbable object definition. |
terrain |
TerrainSpec | None
|
Static ground or climbable terrain definition. |
ground_range |
tuple[float, float]
|
XY extent of the procedural ground grid (meters). |
ground_size |
int
|
Number of samples per axis for :meth: |
provenance |
dict[str, Any]
|
Origin and processing history for the scene. |
Methods:
| Name | Description |
|---|---|
robot_only |
Create a robot-only ground scene. |
object_interaction |
Create an object interaction scene. |
climbing |
Create a climbing or terrain-interaction scene. |
has_dynamic_object |
Whether qpos should include appended object poses. |
resampled |
Return a scene with dynamic trajectories sampled on a new FPS grid. |
ground_points |
Create an xy grid of ground points. |
Attributes¶
class-attribute
instance-attribute
¶
model_config = ConfigDict(arbitrary_types_allowed=True)
class-attribute
instance-attribute
¶
provenance: dict[str, Any] = Field(default_factory=dict)Functions¶
classmethod
¶
robot_only() -> SceneSpecCreate a robot-only ground scene.
Returns:
| Name | Type | Description |
|---|---|---|
SceneSpec |
SceneSpec
|
|
classmethod
¶
object_interaction(object_spec: ObjectSpec) -> SceneSpecCreate an object interaction scene.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
object_spec
|
ObjectSpec
|
Manipulated object definition. |
required |
Returns:
| Name | Type | Description |
|---|---|---|
SceneSpec |
SceneSpec
|
|
classmethod
¶
climbing(
terrain: TerrainSpec | None = None, object_spec: ObjectSpec | None = None
) -> SceneSpecCreate a climbing or terrain-interaction scene.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
terrain
|
TerrainSpec | None
|
Climbable terrain mesh or samples. |
None
|
object_spec
|
ObjectSpec | None
|
Optional climbable object instead of terrain. |
None
|
Returns:
| Name | Type | Description |
|---|---|---|
SceneSpec |
SceneSpec
|
|
has_dynamic_object() -> boolWhether qpos should include appended object poses.
Bases: BaseModel
Object asset and sampling information.
Attributes:
| Name | Type | Description |
|---|---|---|
name |
str
|
Object identifier referenced by the scene and optimizer. |
mesh_path |
Path | None
|
Optional triangle mesh file for visualization or sampling. |
urdf_path |
Path | None
|
Optional URDF describing articulated object geometry. |
asset_scale |
tuple[float, float, float]
|
Scale applied to asset-local geometry. |
visual_parts |
tuple[ObjectVisualPart, ...]
|
Optional visual mesh parts with typed materials. |
sample_points |
FloatArray | None
|
Precomputed asset-local surface points with shape |
sample_space |
ObjectSampleSpace
|
Coordinate space for |
trajectory |
ObjectTrajectory | None
|
Time-varying object pose track. |
qpos_mode |
ObjectQposMode
|
Whether the trajectory is appended to qpos or treated as an external scene pose. |
provenance |
dict[str, Any]
|
Origin and processing history for the object. |
Methods:
| Name | Description |
|---|---|
scaled_sample_points |
Return object sample points in the active object-local geometry frame. |
Attributes¶
class-attribute
instance-attribute
¶
model_config = ConfigDict(arbitrary_types_allowed=True)
class-attribute
instance-attribute
¶
asset_scale: tuple[float, float, float] = (1.0, 1.0, 1.0)
class-attribute
instance-attribute
¶
provenance: dict[str, Any] = Field(default_factory=dict)Functions¶
scaled_sample_points(default: FloatArray | None = None) -> FloatArray | NoneReturn object sample points in the active object-local geometry frame.
Bases: BaseModel
Dynamic object poses over time.
Attributes:
| Name | Type | Description |
|---|---|---|
poses |
PoseSequence
|
Per-frame object rigid transform track. |
name |
str
|
Object label used in scene exports and logs. |
Methods:
| Name | Description |
|---|---|
identity |
Return an identity object trajectory. |
resampled |
Return this object trajectory sampled on a new FPS grid. |
Attributes¶
Functions¶
classmethod
¶
identity(
frame_count: int, *, fps: float = 30.0, name: str = "object"
) -> ObjectTrajectoryReturn an identity object trajectory.
resampled(fps: float) -> ObjectTrajectoryReturn this object trajectory sampled on a new FPS grid.
Bases: BaseModel
Static terrain information.
Attributes:
| Name | Type | Description |
|---|---|---|
name |
str
|
Terrain label used in scene exports and logs. |
mesh_path |
Path | None
|
Optional terrain mesh file. |
sample_points |
FloatArray | None
|
Precomputed terrain surface points with shape |
provenance |
dict[str, Any]
|
Origin and processing history for terrain. |
Bases: BaseModel, Generic[JointT]
Canonical shared-timeline actor motion with a concrete joint vocabulary.
Attributes:
| Name | Type | Description |
|---|---|---|
name |
str
|
|
joints |
tuple[JointT, ...]
|
|
joint_positions |
FloatArray
|
|
timeline |
SampleTimeline
|
|
root_poses |
PoseSequence | None
|
|
provenance |
dict[str, Any]
|
|
Bases: BaseModel, Generic[JointT]
Concrete source-motion vocabulary and storage conventions.
Methods:
| Name | Description |
|---|---|
joint_index |
Return the index of a typed joint. |
Attributes:
| Name | Type | Description |
|---|---|---|
model_config |
|
|
name |
str
|
|
joint_vocabulary |
type[JointT]
|
|
root_joint |
JointT
|
|
quaternion_order |
QuaternionOrder
|
|
frame_convention |
FrameConvention
|
|
default_fps |
float
|
|
default_height_m |
float | None
|
|
description |
str
|
|
joints |
tuple[JointT, ...]
|
Ordered joints declared by this format. |
Attributes¶
class-attribute
instance-attribute
¶
model_config = ConfigDict(arbitrary_types_allowed=True)
class-attribute
instance-attribute
¶
frame_convention: FrameConvention = Z_UP_RIGHT_HANDEDFunctions¶
load_motion(
path: str | Path,
motion_format: MotionFormatKind | MotionFormatSpec,
*,
name: str | None = None,
) -> MotionSequenceLoad a motion sequence using a registered format and suffix loader.
The returned sequence is converted to :attr:~retarget.core.enums.FrameConvention.Z_UP_RIGHT_HANDED.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
path
|
str | Path
|
Motion file path; the suffix selects the loader. |
required |
motion_format
|
MotionFormatKind | MotionFormatSpec
|
Typed registered motion format key or a concrete format specification. |
required |
name
|
str | None
|
Optional sequence name; defaults to the file stem. |
None
|
Returns:
| Name | Type | Description |
|---|---|---|
MotionSequence |
MotionSequence
|
Parsed motion in Z-up world coordinates. |
Raises:
| Type | Description |
|---|---|
KeyError
|
If the format name or file suffix is not registered. |
ValueError
|
If the file content fails validation. |
Robots¶
Bases: BaseModel, Generic[JointT, LinkT, GeometryT, RoleT]
Robot description that preserves enum identity until backend compilation.
Methods:
| Name | Description |
|---|---|
joint_index |
Return the actuated index for a typed joint. |
joint_for_role |
Resolve a semantic robot role to an actuated joint. |
link_for_role |
Resolve a semantic robot role to a link. |
links_for_role |
Resolve a semantic robot role to one or more links. |
qpos_size |
Return qpos size for this robot and object setting. |
load |
Load a robot spec whose config names concrete enum vocabulary classes. |
resolve_paths |
Return a copy with relative asset paths resolved against |
save_json |
Save a JSON representation with explicit vocabulary references. |
limits_array |
Return joint limits in joint order. |
Attributes:
| Name | Type | Description |
|---|---|---|
model_config |
|
|
name |
str
|
|
height_m |
float
|
|
vocabulary |
RobotVocabulary[JointT, LinkT, GeometryT, RoleT]
|
|
joints |
tuple[JointT, ...]
|
|
links |
tuple[LinkT, ...]
|
|
contact_links |
tuple[LinkT, ...]
|
|
geometries |
tuple[GeometryT, ...]
|
|
joint_limits |
dict[JointT, tuple[float, float]]
|
|
joint_roles |
dict[RoleT, JointT]
|
|
link_roles |
dict[RoleT, LinkT]
|
|
link_groups |
dict[RoleT, tuple[LinkT, ...]]
|
|
mujoco_body_aliases |
dict[LinkT, str]
|
|
simple_kinematics |
dict[LinkT, SimpleKinematicPoint[JointT]]
|
|
urdf_path |
Path | None
|
|
mujoco_xml_path |
Path | None
|
|
qpos_layout |
QposLayout
|
|
provenance |
dict[str, Any]
|
|
dof |
int
|
Number of actuated joints. |
Attributes¶
class-attribute
instance-attribute
¶
model_config = ConfigDict(arbitrary_types_allowed=True)
class-attribute
instance-attribute
¶
joint_limits: dict[JointT, tuple[float, float]] = Field(default_factory=dict)
class-attribute
instance-attribute
¶
joint_roles: dict[RoleT, JointT] = Field(default_factory=dict)
class-attribute
instance-attribute
¶
link_roles: dict[RoleT, LinkT] = Field(default_factory=dict)
class-attribute
instance-attribute
¶
link_groups: dict[RoleT, tuple[LinkT, ...]] = Field(default_factory=dict)
class-attribute
instance-attribute
¶
mujoco_body_aliases: dict[LinkT, str] = Field(default_factory=dict)
class-attribute
instance-attribute
¶
simple_kinematics: dict[LinkT, SimpleKinematicPoint[JointT]] = Field(
default_factory=dict
)
class-attribute
instance-attribute
¶
qpos_layout: QposLayout = Field(default_factory=QposLayout)
class-attribute
instance-attribute
¶
provenance: dict[str, Any] = Field(default_factory=dict)Functions¶
joint_for_role(role: RoleT) -> JointTResolve a semantic robot role to an actuated joint.
links_for_role(role: RoleT) -> tuple[LinkT, ...]Resolve a semantic robot role to one or more links.
qpos_size(*, has_object: bool = False) -> intReturn qpos size for this robot and object setting.
classmethod
¶
load(path: str | Path) -> RobotSpec[Any, Any, Any, Any]Load a robot spec whose config names concrete enum vocabulary classes.
resolve_paths(base_dir: str | Path) -> RobotSpec[JointT, LinkT, GeometryT, RoleT]Return a copy with relative asset paths resolved against base_dir.
save_json(path: str | Path) -> PathSave a JSON representation with explicit vocabulary references.
limits_array() -> tuple[list[float], list[float]]Return joint limits in joint order.
Bases: BaseModel
Convention for serialized qpos vectors.
Methods:
| Name | Description |
|---|---|
qpos_size |
Return qpos size for this layout. |
joint_slice |
Return the slice containing actuated robot joints. |
object_slice |
Return the slice containing an appended object pose. |
Attributes:
| Name | Type | Description |
|---|---|---|
root_position |
tuple[int, int]
|
|
root_quaternion |
tuple[int, int]
|
|
joint_start |
int
|
|
object_pose_size |
int
|
|
Attributes¶
Functions¶
qpos_size(robot_dof: int, *, has_object: bool = False) -> intReturn qpos size for this layout.
joint_slice(robot_dof: int) -> sliceReturn the slice containing actuated robot joints.
object_slice(robot_dof: int) -> sliceReturn the slice containing an appended object pose.
Mesh¶
InteractionMeshBuilder(
spec: InteractionMeshSpec | None = None,
*,
topology: MeshTopology | str | None = None,
k_neighbors: int | None = None,
)Build an interaction mesh from human and object/terrain points.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
spec
|
InteractionMeshSpec | None
|
Full mesh configuration; mutually exclusive with keyword overrides. |
None
|
topology
|
MeshTopology | str | None
|
Override topology when |
None
|
k_neighbors
|
int | None
|
Neighbor count for |
None
|
Raises:
ValueError: If spec is combined with explicit mesh keyword options.
Methods:
| Name | Description |
|---|---|
build |
Build an interaction mesh from human and optional environment points. |
Attributes:
| Name | Type | Description |
|---|---|---|
spec |
|
Attributes¶
instance-attribute
¶
spec = InteractionMeshSpec(
topology=resolved_topology,
k_neighbors=k_neighbors if k_neighbors is not None else 4,
)
Functions¶
build(
human_points: FloatArray, environment_points: FloatArray | None = None
) -> InteractionMeshBuild an interaction mesh from human and optional environment points.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
human_points
|
FloatArray
|
Body or joint sample sites with shape |
required |
environment_points
|
FloatArray | None
|
Object or terrain sites stacked after human points. |
None
|
Returns:
| Name | Type | Description |
|---|---|---|
InteractionMesh |
InteractionMesh
|
Combined vertex set and simplex connectivity. |
Raises:
| Type | Description |
|---|---|
ValueError
|
If point arrays have invalid rank or shape. |
Bases: BaseModel
Configuration for interaction mesh construction.
Attributes:
| Name | Type | Description |
|---|---|---|
topology |
MeshTopology
|
Graph construction policy. |
k_neighbors |
int
|
Neighbor count when |
laplacian_weighting |
LaplacianWeighting
|
Neighbor weighting used by Laplacian objectives. |
laplacian_epsilon |
float
|
Small positive value used by distance-weighted Laplacians. |
Attributes¶
class-attribute
instance-attribute
¶
laplacian_weighting: LaplacianWeighting = UNIFORM