Full reference

Complete API for the retarget package (all public members). For a guided tour, start with the overview.

Public API for the retarget research toolkit.

Modules:

Name	Description
assets	Asset manifests and stores.
capture	Typed native recordings and capture processing.
cli	CLI package.
core	Core primitives shared across retarget.
export	Export utilities.
kinematics	Kinematics backends.
mesh	Mesh utilities.
metrics	Evaluation metrics.
motion	Motion specs, registries, and loaders.
observation	Target-independent scene observations.
optimization	Optimization models and solvers.
pipeline	Retargeting pipeline.
recipes	Built-in observation and retargeting recipes.
results	Result schemas.
robots	Robot specs and registry.
scene	Scene configuration.
visualization	Visualization adapters.

Classes:

Name	Description
AssetInstallManifest	Human-editable manifest describing assets to install or reference.
AssetManifest	Collection of asset records.
AssetRecord	One tracked asset.
AssetRequirement	One asset declared by a human-editable install manifest.
AssetStore	Local manifest-backed asset store.
AlignmentError	Registration failure carrying the rejected quality report.
AlignmentReport	Quality report for one temporal or spatial registration.
CategoricalTrack	A named categorical sequence sampled by nearest neighbor.
ClockTransform	Affine mapping from a native clock into an observation clock.
GvhmrEstimator	Run a configured local GVHMR checkout in an ephemeral workspace.
GvhmrOutputSource	Load existing GVHMR arrays as a native human-pose recording.
HumanPoseEstimator	Estimate a typed human-pose recording from video.
HumanPoseRecording	Estimated or measured human pose in one native clock.
HumanPoseSourceSchema	Map semantic motion-joint vocabularies to source array columns.
InMemorySource	Source returning an already constructed recording.
JointTrack	A native or estimated human-joint trajectory.
MarkerTrack	A native motion-capture marker trajectory.
MocapRecording	Joints, rigid bodies, and markers sampled in one native mocap clock.
ObservationSource	Load one native recording without creating a shared timeline.
PointTrack	A named 3D point trajectory.
PoseTrack	A named rigid-body pose trajectory.
RigidBodyTrack	A native motion-capture rigid-body trajectory.
RigidTransform	Rigid point transform target = source @ rotation.T + translation.
SampleTimeline	Strictly increasing sample timestamps in one recording's native clock.
TemporalRegistrationConfig	Quality and search policy for offset registration.
ViconBagSource	Read a ROS 2 Vicon bag directly into a native mocap recording.
ViconBagTopics	ROS topics carrying Vicon rigid-body transforms and marker samples.
ViconRecordingSource	Load a preconverted Vicon recording directly into typed tracks.
ViconSourceSchema	Map Vicon table names into typed native vocabularies.
VideoPoseSource	Compose a video recording source with a pose estimator.
VideoRecording	A video stream and its native frame timeline.
AssetKind	Types of assets tracked by an asset manifest.
Constraint	Built-in constraint term registry keys.
ConstraintKind	Base enum for constraint registrations.
ContactLayerKind	Persisted contact layer storage kind.
ContactPatch	Base enum for contact patch labels.
ContactState	Base enum for symbolic contact state labels.
ContactSubject	Base enum for contact subjects such as feet, shoes, or hands.
ConvergenceMode	SQP inner-loop convergence policy.
CropPolicy	How a shared observation timeline handles source support.
ExporterKind	Base enum for exporter registrations.
ExportFormat	Built-in exporter registry keys.
FrameConvention	Coordinate frame conventions understood by the package.
HumanoidRobotRole	Standard semantic roles exposed by humanoid robot specs.
KinematicsBackendName	Built-in kinematics backend registry keys.
KinematicsKind	Base enum for kinematics-backend registrations.
MetricKind	Base enum for metric registrations.
MetricName	Built-in evaluation metric names.
MocapMarker	Base enum for native motion-capture marker names.
MocapRigidBody	Base enum for native motion-capture rigid-body names.
MotionFormat	Built-in motion format registry keys.
MotionFormatKind	Base enum for motion-format registrations.
MotionJoint	Base enum for source motion joint names.
MotionLoaderKind	Base enum for motion-loader registrations.
MotionLoaderSuffix	Built-in motion loader suffix registry keys.
NameEnum	Base class for user-defined symbolic vocabularies.
NominalFallback	Fallback target for nominal qpos tracking.
NonPenetrationSource	Sources used by the non-penetration constraint.
Objective	Built-in objective term registry keys.
ObjectiveKind	Base enum for objective registrations.
ObjectQposMode	How a dynamic object trajectory participates in qpos.
ObjectSampleSpace	Coordinate space for object sample points.
ObservationRecipeKind	Built-in observation-recipe kinds for declarative run configs.
ObservationRecipeKindBase	Base enum for observation-recipe registrations.
ObservationRole	Base enum for target-independent semantic observation roles.
QposVariableKind	Which qpos coordinates the optimizer may change.
QuaternionOrder	Quaternion storage order.
RetargetEnum	Base class for string-valued retarget enums.
RetargetingRecipeKind	Built-in robot-adaptation recipe kinds for declarative run configs.
RetargetingRecipeKindBase	Base enum for retargeting-recipe registrations.
Robot	Built-in robot registry keys.
RobotGeometry	Base enum for robot collision and visual geometry names.
RobotJoint	Base enum for robot joint names.
RobotKind	Base enum for robot registrations.
RobotLink	Base enum for robot link names.
RobotProviderKind	Base enum for robot-provider registrations.
RobotProviderName	Built-in robot provider registry keys.
RobotRole	Base enum for semantic roles resolved by a robot specification.
RunStatus	Retargeting or evaluation lifecycle state.
SceneGeometry	Base enum for target-independent scene geometry groups.
SolverBackend	Optimization backend choices.
SolverKind	Base enum for solver registrations.
TaskKind	Supported high-level retargeting workflows.
TimelineSelection	Native timeline selected as the observation sampling grid.
VisualizerKind	Base enum for visualizer registrations.
VisualizerName	Built-in visualizer registry keys.
Pose	Rigid transform from a local frame into a named world convention.
PoseSequence	Time-indexed sequence of poses.
ConstraintTerm	Optimization constraint term.
Exporter	Export a retargeting result to an external workflow format.
KinematicsBackend	Robot kinematics operations needed by retargeting and metrics.
Metric	Evaluate one metric.
MotionLoader	Load a motion file into a MotionSequence.
ObjectiveTerm	Optimization objective term.
RobotProvider	Resolve robot specs from names or external asset locations.
Solver	Solve a quadratic retargeting subproblem.
Visualizer	Render or summarize a retargeting result.
ExportResult	Summary of an export operation.
ExportSpec	Configuration for exporting a retargeting result.
GeometryDistance	Signed or unsigned distance between two geometry-like objects.
GeometryDistanceJacobian	Linearized distance row for a geometry pair.
InteractionMeshBuilder	Build an interaction mesh from human and object/terrain points.
InteractionMeshSpec	Configuration for interaction mesh construction.
LaplacianWeighting	Neighbor weighting policy for Laplacian coordinates.
MeshTopology	Interaction mesh topology policy.
ContactFrame	Per-frame view of a :class:ContactPlan.
ContactPlan	Typed contact states and support geometry for a retargeting problem.
ContactTrack	One semantic subject's typed contact state over time.
LafanMotionJoint
LinkTargetPlan	Validated frame-aligned targets using one robot-link vocabulary.
LinkTargetSample	One active typed robot-link target at one frame.
LinkTargetTrack	World-space target trajectory for one typed robot link.
MinimalMotionJoint
MocapMotionJoint
NominalQposFrame	Per-frame view of a nominal qpos trajectory.
NominalQposPlan	Frame-aligned nominal generalized-coordinate trajectory.
SmplhMotionJoint
SmplxMotionJoint
SupportPlane	Planar support surface used by contact-aware terms.
TargetFrame	Per-frame view of link targets.
MotionFormatSpec	Concrete source-motion vocabulary and storage conventions.
MotionSequence	Canonical shared-timeline actor motion with a concrete joint vocabulary.
FootSupportClassificationConfig	Thresholds for ground and moving-object foot support.
FootSupportStates	Typed categorical values emitted by support classification.
ObservedObject	Observed object geometry and pose, independent of a target robot.
SceneObservation	Shared-timeline result of capture processing before robot adaptation.
SemanticContactSequence	Robot-independent semantic contacts and support geometry.
SemanticContactTrack	Categorical contact state for one observed subject and patch.
ConstraintContribution	Bounds and linear constraints from one constraint term.
ObjectiveContribution	Least-squares contribution from one objective term.
TermContext	Per-frame data available to objective and constraint terms.
ConstraintConfig	Base class for constraint configs keyed by an extensible enum member.
DiagonalRegularizationObjectiveConfig	Penalize selected qpos variables toward zero with diagonal weights.
FootLockConstraintConfig	Pin exact typed support links or subjects during configured windows.
FootStickingConstraintConfig	Constrain active support links near their previous tangent-plane position.
JointLimitsConstraintConfig	Box limits on actuated joints.
LaplacianObjectiveConfig	Interaction-mesh Laplacian deformation objective.
LinkTrackingObjectiveConfig	Track robot links to a typed target plan.
NominalTrackingObjectiveConfig	Track a nominal posture for typed robot joints or explicit qpos coordinates.
NonPenetrationConstraintConfig	Separate selected typed robot links from support and explicit geometry.
ObjectiveConfig	Base class for objective configs keyed by an extensible enum member.
OptimizationProfile	Reusable typed objective/constraint composition.
SelfCollisionConstraintConfig	Maintain minimum separation between explicit typed robot geometry pairs.
SmoothnessObjectiveConfig	Penalize changes from the previous frame.
SolverSpec	Solver selection and common options.
TrustRegionConstraintConfig	Cap the Euclidean norm of each SQP update.
QposVariableSpec	Configuration describing which qpos coordinates the optimizer may change.
ResolvedQposVariables	Resolved qpos coordinates used as one SQP subproblem variable.
BatchJob	One retargeting job in a batch run.
BatchManifest	Manifest written by resumable batch runs.
BatchRunner	Execute jobs with resume-aware manifest updates.
BatchRunRecord	Recorded outcome for one batch job.
InteractionMeshRetargetingEngine	Backend-agnostic interaction-mesh SQP retargeter.
RetargetingExperiment	Compose observation processing, robot adaptation, and optimization.
RetargetingProblem	Complete typed run specification before backend compilation.
ObservationRecipe	Process native recordings into a target-independent observation.
RetargetingRecipe	Adapt a scene observation to one target robot.
SceneRecipe	Build target-independent runtime scene data from an observation.
Retargeter	Run a RetargetingProblem and return a typed result.
MotionFileObservationRecipe	Load a registered motion file into a typed scene observation.
RobotOnlySceneRecipe	Build a flat-ground robot-only scene.
RoleRetargetingRecipe	Resolve typed motion joints through semantic robot roles.
StaticSceneRecipe	Return a predeclared target-independent scene specification.
EvaluationManifest	Manifest written by batch evaluation runs.
EvaluationRecord	Recorded outcome for evaluating one retargeting result.
EvaluationReport	Evaluation metrics for a result.
RetargetingResult	Strict pickle-free retargeting checkpoint.
JointLimit	Position bounds for one typed actuated joint.
QposLayout	Convention for serialized qpos vectors.
RobotSpec	Robot description that preserves enum identity until backend compilation.
RobotVocabulary	Concrete enum classes used by one robot specification.
SimpleKinematicPoint	Explicit fixture kinematics for one robot link.
ObjectSpec	Object asset and sampling information.
ObjectTrajectory	Dynamic object poses over time.
ObjectVisualPart	A renderable object mesh part with optional material styling.
SceneSpec	Scene configuration for a retargeting run.
TerrainSpec	Static terrain information.

Functions:

Name	Description
estimate_clock_offset	Estimate an offset mapping moving_timeline into reference_timeline.
register_rigid_points	Estimate a Kabsch rigid transform from corresponding finite points.
convert_points_frame	Convert point coordinates between supported right-handed frame conventions.
frame_transform_matrix	Return the rotation matrix that maps coordinates from source to target.
reorder_quaternion	Convert quaternion storage order without changing the represented rotation.
reorder_quaternions	Convert quaternion storage order along one array axis.
resample_linear	Linearly resample an array whose first axis is time.
resampling_times	Return source and target sample times for endpoint-preserving interpolation.
sample_mesh_points	Return deterministic surface samples for a mesh file.
classify_foot_support	Classify feet as air, ground, or supported by an observed object.

Attributes:

Name	Type	Description
exporters	Registry[ExporterKind, Exporter]
kinematics_backends	Registry[KinematicsKind, KinematicsBackendFactory]	Registry of kinematics backend factories keyed by backend name.
motion_formats	Registry[MotionFormatKind, MotionFormatSpec]	Registry of built-in :class:~retarget.motion.spec.MotionFormatSpec entries.
motion_loaders	Registry[MotionLoaderKind, MotionLoader]	Registry of file-suffix :class:~retarget.core.protocols.MotionLoader implementations.
constraint_terms	Registry[ConstraintKind, ConstraintTerm[Any]]	Registry of built-in and user-registered constraint terms keyed by name.
objective_terms	Registry[ObjectiveKind, ObjectiveTerm[Any]]	Registry of built-in and user-registered objective terms keyed by name.
solver_factories	Registry[SolverKind, SolverFactory]	Registry of solver factories keyed by :class:~retarget.core.enums.SolverBackend name.
ConstraintConfigUnion	TypeAlias
ObjectiveConfigUnion	TypeAlias
robot_providers	Registry[RobotProviderKind, RobotProvider]

Attributes

exporters module-attribute

exporters: Registry[ExporterKind, Exporter] = Registry(
    "exporter", ExporterKind, decorator_transform=_exporter_from_decorator
)

kinematics_backends module-attribute

kinematics_backends: Registry[KinematicsKind, KinematicsBackendFactory] = Registry(
    "kinematics backend", KinematicsKind
)

Registry of kinematics backend factories keyed by backend name.

motion_formats module-attribute

motion_formats: Registry[MotionFormatKind, MotionFormatSpec] = Registry(
    "motion format", MotionFormatKind, decorator_transform=_motion_format_from_decorator
)

Registry of built-in :class:~retarget.motion.spec.MotionFormatSpec entries.

motion_loaders module-attribute

motion_loaders: Registry[MotionLoaderKind, MotionLoader] = Registry(
    "motion loader", MotionLoaderKind, decorator_transform=_motion_loader_from_decorator
)

Registry of file-suffix :class:~retarget.core.protocols.MotionLoader implementations.

constraint_terms module-attribute

constraint_terms: Registry[ConstraintKind, ConstraintTerm[Any]] = Registry(
    "constraint term",
    ConstraintKind,
    decorator_transform=_constraint_term_from_decorator,
)

Registry of built-in and user-registered constraint terms keyed by name.

objective_terms module-attribute

objective_terms: Registry[ObjectiveKind, ObjectiveTerm[Any]] = Registry(
    "objective term", ObjectiveKind, decorator_transform=_objective_term_from_decorator
)

Registry of built-in and user-registered objective terms keyed by name.

solver_factories module-attribute

solver_factories: Registry[SolverKind, SolverFactory] = Registry(
    "solver factory", SolverKind
)

Registry of solver factories keyed by :class:~retarget.core.enums.SolverBackend name.

ConstraintConfigUnion module-attribute

ConstraintConfigUnion: TypeAlias = (
    JointLimitsConstraintConfig
    | TrustRegionConstraintConfig
    | FootStickingConstraintConfig
    | FootLockConstraintConfig
    | NonPenetrationConstraintConfig
    | SelfCollisionConstraintConfig
)

ObjectiveConfigUnion module-attribute

ObjectiveConfigUnion: TypeAlias = (
    LaplacianObjectiveConfig
    | LinkTrackingObjectiveConfig
    | SmoothnessObjectiveConfig
    | NominalTrackingObjectiveConfig
    | DiagonalRegularizationObjectiveConfig
)

robot_providers module-attribute

robot_providers: Registry[RobotProviderKind, RobotProvider] = Registry(
    "robot provider",
    RobotProviderKind,
    decorator_transform=_robot_provider_from_decorator,
)

Classes

AssetInstallManifest

Bases: BaseModel

Human-editable manifest describing assets to install or reference.

Attributes:

Name	Type	Description
schema_version	int	Manifest format version (default 1).
assets	tuple[AssetRequirement, ...]	Assets to install or reference.
provenance	dict[str, Any]	Origin and processing history for the manifest.

Methods:

Name	Description
load	Load a TOML, YAML, or JSON install manifest.
resolve_sources	Return a copy with local relative sources resolved.

Attributes

schema_version class-attribute instance-attribute

schema_version: int = 1

assets class-attribute instance-attribute

assets: tuple[AssetRequirement, ...] = ()

provenance class-attribute instance-attribute

provenance: dict[str, Any] = Field(default_factory=dict)

Functions

load classmethod

load(path: str | Path) -> AssetInstallManifest

Load a TOML, YAML, or JSON install manifest.

resolve_sources

resolve_sources(base_dir: Path) -> AssetInstallManifest

Return a copy with local relative sources resolved.

AssetManifest

Bases: BaseModel

Collection of asset records.

Attributes:

Name	Type	Description
records	list[AssetRecord]	Installed or referenced assets tracked by the store.

Methods:

Name	Description
find	Return the first record by name.

Attributes

records class-attribute instance-attribute

records: list[AssetRecord] = Field(default_factory=list)

Functions

find

find(name: str) -> AssetRecord | None

Return the first record by name.

AssetRecord

Bases: BaseModel

One tracked asset.

Attributes:

Name	Type	Description
name	str	Unique asset name in the store manifest.
kind	AssetKind	Asset category (robot, object, terrain, motion, fixture).
path	Path	Resolved on-disk path to the asset file or directory.
source	str | None	Original import path or download URL, if recorded.
sha256	str | None	Expected or verified SHA-256 hex digest for file assets.
license	str | None	SPDX identifier or short license note.
notice	str | None	Attribution or NOTICE text.
installed_at	datetime | None	UTC timestamp when the asset was registered or installed.
provenance	dict[str, Any]	Origin and processing history for the asset.

Attributes

name instance-attribute

name: str

kind instance-attribute

kind: AssetKind

path instance-attribute

path: Path

source class-attribute instance-attribute

source: str | None = None

sha256 class-attribute instance-attribute

sha256: str | None = None

license class-attribute instance-attribute

license: str | None = None

notice class-attribute instance-attribute

notice: str | None = None

installed_at class-attribute instance-attribute

installed_at: datetime | None = None

provenance class-attribute instance-attribute

provenance: dict[str, Any] = Field(default_factory=dict)

AssetRequirement

Bases: BaseModel

One asset declared by a human-editable install manifest.

Attributes:

Name	Type	Description
name	str	Asset name to register in the store.
kind	AssetKind	Asset category (robot, object, terrain, motion, fixture).
source	str	Local path or HTTP(S) URL to fetch or reference.
copy_to_store	bool	When True (TOML key copy), copy into the store instead of referencing in place.
destination	Path | None	Optional store-relative or absolute install path.
sha256	str | None	Expected SHA-256 hex digest for file assets.
license	str | None	SPDX identifier or short license note.
notice	str | None	Attribution or NOTICE text.
provenance	dict[str, Any]	Origin and processing history supplied by the manifest.

Methods:

Name	Description
resolve_source	Resolve local relative sources against a manifest directory.

Attributes

model_config class-attribute instance-attribute

model_config = ConfigDict(populate_by_name=True)

name instance-attribute

name: str

kind instance-attribute

kind: AssetKind

source instance-attribute

source: str

copy_to_store class-attribute instance-attribute

copy_to_store: bool = Field(default=False, alias='copy')

destination class-attribute instance-attribute

destination: Path | None = None

sha256 class-attribute instance-attribute

sha256: str | None = None

license class-attribute instance-attribute

license: str | None = None

notice class-attribute instance-attribute

notice: str | None = None

provenance class-attribute instance-attribute

provenance: dict[str, Any] = Field(default_factory=dict)

is_download property

is_download: bool

Whether source is an HTTP(S) URL.

Functions

resolve_source

resolve_source(base_dir: Path) -> AssetRequirement

Resolve local relative sources against a manifest directory.

AssetStore

AssetStore(root: str | Path = '.retarget_assets')

Local manifest-backed asset store.

Methods:

Name	Description
load	Load manifest, returning an empty manifest if none exists.
save	Persist manifest.
list	List tracked assets.
import_path	Track or copy an asset path into the store.
install	Install or reference one manifest requirement.
install_manifest	Install every asset in a manifest.

Attributes:

Name	Type	Description
root
manifest_path

Attributes

root instance-attribute

root = Path(root)

manifest_path instance-attribute

manifest_path = root / 'manifest.json'

Functions

load

load() -> AssetManifest

Load manifest, returning an empty manifest if none exists.

save

save(manifest: AssetManifest) -> None

Persist manifest.

list

list() -> list[AssetRecord]

List tracked assets.

import_path

import_path(
    source: str | Path,
    *,
    name: str,
    kind: AssetKind,
    copy: bool = False,
    target_path: str | Path | None = None,
    sha256: str | None = None,
    license: str | None = None,
    notice: str | None = None,
    provenance: dict[str, Any] | None = None,
) -> AssetRecord

Track or copy an asset path into the store.

install

install(requirement: AssetRequirement, *, allow_downloads: bool = False) -> AssetRecord

Install or reference one manifest requirement.

install_manifest

install_manifest(
    manifest: AssetInstallManifest | str | Path, *, allow_downloads: bool = False
) -> list[AssetRecord]

Install every asset in a manifest.

AlignmentError

AlignmentError(message: str, report: AlignmentReport)

Bases: ValueError

Registration failure carrying the rejected quality report.

Attributes:

Name	Type	Description
report

Attributes

report instance-attribute

report = report

AlignmentReport dataclass

AlignmentReport(
    strategy: str,
    accepted: bool,
    score: float,
    sample_count: int,
    overlap_s: float | None = None,
    clock_transform: ClockTransform | None = None,
    rms_error: float | None = None,
    diagnostics: dict[str, object] = dict(),
)

Quality report for one temporal or spatial registration.

Attributes:

Name	Type	Description
strategy	str
accepted	bool
score	float
sample_count	int
overlap_s	float | None
clock_transform	ClockTransform | None
rms_error	float | None
diagnostics	dict[str, object]

Attributes

strategy instance-attribute

strategy: str

accepted instance-attribute

accepted: bool

score instance-attribute

score: float

sample_count instance-attribute

sample_count: int

overlap_s class-attribute instance-attribute

overlap_s: float | None = None

clock_transform class-attribute instance-attribute

clock_transform: ClockTransform | None = None

rms_error class-attribute instance-attribute

rms_error: float | None = None

diagnostics class-attribute instance-attribute

diagnostics: dict[str, object] = field(default_factory=dict)

CategoricalTrack dataclass

CategoricalTrack(
    role: NameEnum,
    values: tuple[NameEnum, ...],
    validity: ndarray | None = None,
    provenance: dict[str, object] | None = None,
)

A named categorical sequence sampled by nearest neighbor.

Methods:

Name	Description
resample	Sample this track at the nearest native timestamp.

Attributes:

Name	Type	Description
role	NameEnum
values	tuple[NameEnum, ...]
validity	ndarray | None
provenance	dict[str, object] | None
sample_count	int	Number of samples.

Attributes

role instance-attribute

role: NameEnum

values instance-attribute

values: tuple[NameEnum, ...]

validity class-attribute instance-attribute

validity: ndarray | None = None

provenance class-attribute instance-attribute

provenance: dict[str, object] | None = None

sample_count property

sample_count: int

Number of samples.

Functions

resample

resample(
    source: SampleTimeline,
    target: SampleTimeline,
    *,
    clock: ClockTransform | None = None,
) -> Self

Sample this track at the nearest native timestamp.

ClockTransform dataclass

ClockTransform(
    scale: float = 1.0,
    offset_s: float = 0.0,
    source_clock: str = "native",
    target_clock: str = "observation",
)

Affine mapping from a native clock into an observation clock.

The mapping is observation_time = scale * native_time + offset_s.

Methods:

Name	Description
apply	Map timestamps into the target clock.
timeline	Map a complete timeline into the target clock.
inverse	Return the inverse clock mapping.

Attributes:

Name	Type	Description
scale	float
offset_s	float
source_clock	str
target_clock	str

Attributes

scale class-attribute instance-attribute

scale: float = 1.0

offset_s class-attribute instance-attribute

offset_s: float = 0.0

source_clock class-attribute instance-attribute

source_clock: str = 'native'

target_clock class-attribute instance-attribute

target_clock: str = 'observation'

Functions

apply

apply(timestamps: Any) -> FloatArray

Map timestamps into the target clock.

timeline

timeline(timeline: SampleTimeline) -> SampleTimeline

Map a complete timeline into the target clock.

inverse

inverse() -> ClockTransform

Return the inverse clock mapping.

GvhmrEstimator dataclass

GvhmrEstimator(
    checkout: Path,
    command: tuple[str, ...],
    schema: HumanPoseSourceSchema,
    fps: float,
    frame: FrameConvention = Y_UP_RIGHT_HANDED,
    source_height_m: float | None = None,
)

Run a configured local GVHMR checkout in an ephemeral workspace.

Command entries may contain {video}, {workspace}, {output}, and {checkout} placeholders. The configured command must write joints.npy into {output}.

Methods:

Name	Description
estimate	Run GVHMR and load its output before deleting temporary files.

Attributes:

Name	Type	Description
checkout	Path
command	tuple[str, ...]
schema	HumanPoseSourceSchema
fps	float
frame	FrameConvention
source_height_m	float | None

Attributes

checkout instance-attribute

checkout: Path

command instance-attribute

command: tuple[str, ...]

schema instance-attribute

schema: HumanPoseSourceSchema

fps instance-attribute

fps: float

frame class-attribute instance-attribute

frame: FrameConvention = Y_UP_RIGHT_HANDED

source_height_m class-attribute instance-attribute

source_height_m: float | None = None

Functions

estimate

estimate(recording: VideoRecording) -> HumanPoseRecording

Run GVHMR and load its output before deleting temporary files.

GvhmrOutputSource dataclass

GvhmrOutputSource(
    path: Path,
    schema: HumanPoseSourceSchema,
    fps: float,
    frame: FrameConvention = Y_UP_RIGHT_HANDED,
    name: str = "",
    source_height_m: float | None = None,
    load_vertices: bool = False,
)

Load existing GVHMR arrays as a native human-pose recording.

Methods:

Name	Description
load	Load GVHMR joint output without creating a synchronized file.

Attributes:

Name	Type	Description
path	Path
schema	HumanPoseSourceSchema
fps	float
frame	FrameConvention
name	str
source_height_m	float | None
load_vertices	bool

Attributes

path instance-attribute

path: Path

schema instance-attribute

schema: HumanPoseSourceSchema

fps instance-attribute

fps: float

frame class-attribute instance-attribute

frame: FrameConvention = Y_UP_RIGHT_HANDED

name class-attribute instance-attribute

name: str = ''

source_height_m class-attribute instance-attribute

source_height_m: float | None = None

load_vertices class-attribute instance-attribute

load_vertices: bool = False

Functions

load

load() -> HumanPoseRecording

Load GVHMR joint output without creating a synchronized file.

HumanPoseEstimator

Bases: Protocol

Estimate a typed human-pose recording from video.

Methods:

Name	Description
estimate	Estimate pose for recording.

Functions

estimate

estimate(recording: VideoRecording) -> HumanPoseRecording

Estimate pose for recording.

HumanPoseRecording dataclass

HumanPoseRecording(
    name: str,
    timeline: SampleTimeline,
    frame: FrameConvention,
    joints: tuple[JointTrack, ...],
    root_pose: PoseTrack | None = None,
    source_height_m: float | None = None,
    vertices: FloatArray | None = None,
    provenance: dict[str, object] | None = None,
)

Estimated or measured human pose in one native clock.

Methods:

Name	Description
joint	Return one joint track.
to_motion_sequence	Materialize the canonical shared-timeline actor motion after fusion.

Attributes:

Name	Type	Description
name	str
timeline	SampleTimeline
frame	FrameConvention
joints	tuple[JointTrack, ...]
root_pose	PoseTrack | None
source_height_m	float | None
vertices	FloatArray | None
provenance	dict[str, object] | None
joint_roles	tuple[NameEnum, ...]	Ordered joint vocabulary.

Attributes

name instance-attribute

name: str

timeline instance-attribute

timeline: SampleTimeline

frame instance-attribute

frame: FrameConvention

joints instance-attribute

joints: tuple[JointTrack, ...]

root_pose class-attribute instance-attribute

root_pose: PoseTrack | None = None

source_height_m class-attribute instance-attribute

source_height_m: float | None = None

vertices class-attribute instance-attribute

vertices: FloatArray | None = None

provenance class-attribute instance-attribute

provenance: dict[str, object] | None = None

joint_roles property

joint_roles: tuple[NameEnum, ...]

Ordered joint vocabulary.

Functions

joint

joint(role: NameEnum) -> JointTrack

Return one joint track.

to_motion_sequence

to_motion_sequence(root_joint: MotionJoint) -> MotionSequence[MotionJoint]

Materialize the canonical shared-timeline actor motion after fusion.

HumanPoseSourceSchema dataclass

HumanPoseSourceSchema(joint_indices: Mapping[MotionJoint, int])

Map semantic motion-joint vocabularies to source array columns.

Attributes:

Name	Type	Description
joint_indices	Mapping[MotionJoint, int]

Attributes

joint_indices instance-attribute

joint_indices: Mapping[MotionJoint, int]

InMemorySource dataclass

InMemorySource(recording: RecordingT)

Bases: Generic[RecordingT]

Source returning an already constructed recording.

Methods:

Name	Description
load	Return the stored recording.

Attributes:

Name	Type	Description
recording	RecordingT

Attributes

recording instance-attribute

recording: RecordingT

Functions

load

load() -> RecordingT

Return the stored recording.

JointTrack dataclass

JointTrack(
    role: NameEnum,
    values: FloatArray,
    validity: ndarray | None = None,
    provenance: dict[str, object] | None = None,
)

Bases: PointTrack

A native or estimated human-joint trajectory.

MarkerTrack dataclass

MarkerTrack(
    role: NameEnum,
    values: FloatArray,
    validity: ndarray | None = None,
    provenance: dict[str, object] | None = None,
)

Bases: PointTrack

A native motion-capture marker trajectory.

MocapRecording dataclass

MocapRecording(
    name: str,
    timeline: SampleTimeline,
    frame: FrameConvention,
    joints: tuple[JointTrack, ...] = (),
    rigid_bodies: tuple[RigidBodyTrack, ...] = (),
    markers: tuple[MarkerTrack, ...] = (),
    provenance: dict[str, object] | None = None,
)

Joints, rigid bodies, and markers sampled in one native mocap clock.

Methods:

Name	Description
rigid_body	Return one rigid-body track.
joint	Return one mocap joint track.
marker	Return one marker track.

Attributes:

Name	Type	Description
name	str
timeline	SampleTimeline
frame	FrameConvention
joints	tuple[JointTrack, ...]
rigid_bodies	tuple[RigidBodyTrack, ...]
markers	tuple[MarkerTrack, ...]
provenance	dict[str, object] | None

Attributes

name instance-attribute

name: str

timeline instance-attribute

timeline: SampleTimeline

frame instance-attribute

frame: FrameConvention

joints class-attribute instance-attribute

joints: tuple[JointTrack, ...] = ()

rigid_bodies class-attribute instance-attribute

rigid_bodies: tuple[RigidBodyTrack, ...] = ()

markers class-attribute instance-attribute

markers: tuple[MarkerTrack, ...] = ()

provenance class-attribute instance-attribute

provenance: dict[str, object] | None = None

Functions

rigid_body

rigid_body(role: NameEnum) -> RigidBodyTrack

Return one rigid-body track.

joint

joint(role: NameEnum) -> JointTrack

Return one mocap joint track.

marker

marker(role: NameEnum) -> MarkerTrack

Return one marker track.

ObservationSource

Bases: Protocol[RecordingT]

Load one native recording without creating a shared timeline.

Methods:

Name	Description
load	Load the recording.

Functions

load

load() -> RecordingT

Load the recording.

PointTrack dataclass

PointTrack(
    role: NameEnum,
    values: FloatArray,
    validity: ndarray | None = None,
    provenance: dict[str, object] | None = None,
)

A named 3D point trajectory.

Methods:

Name	Description
resample	Linearly interpolate this track onto target.

Attributes:

Name	Type	Description
role	NameEnum
values	FloatArray
validity	ndarray | None
provenance	dict[str, object] | None
sample_count	int	Number of samples.

Attributes

role instance-attribute

role: NameEnum

values instance-attribute

values: FloatArray

validity class-attribute instance-attribute

validity: ndarray | None = None

provenance class-attribute instance-attribute

provenance: dict[str, object] | None = None

sample_count property

sample_count: int

Number of samples.

Functions

resample

resample(
    source: SampleTimeline,
    target: SampleTimeline,
    *,
    clock: ClockTransform | None = None,
) -> Self

Linearly interpolate this track onto target.

PoseTrack dataclass

PoseTrack(
    role: NameEnum,
    positions: FloatArray,
    quaternions: FloatArray,
    quaternion_order: QuaternionOrder = WXYZ,
    validity: ndarray | None = None,
    provenance: dict[str, object] | None = None,
)

A named rigid-body pose trajectory.

Methods:

Name	Description
resample	Linearly interpolate translation and SLERP orientation.

Attributes:

Name	Type	Description
role	NameEnum
positions	FloatArray
quaternions	FloatArray
quaternion_order	QuaternionOrder
validity	ndarray | None
provenance	dict[str, object] | None
sample_count	int	Number of samples.

Attributes

role instance-attribute

role: NameEnum

positions instance-attribute

positions: FloatArray

quaternions instance-attribute

quaternions: FloatArray

quaternion_order class-attribute instance-attribute

quaternion_order: QuaternionOrder = WXYZ

validity class-attribute instance-attribute

validity: ndarray | None = None

provenance class-attribute instance-attribute

provenance: dict[str, object] | None = None

sample_count property

sample_count: int

Number of samples.

Functions

resample

resample(
    source: SampleTimeline,
    target: SampleTimeline,
    *,
    clock: ClockTransform | None = None,
) -> Self

Linearly interpolate translation and SLERP orientation.

RigidBodyTrack dataclass

RigidBodyTrack(
    role: NameEnum,
    positions: FloatArray,
    quaternions: FloatArray,
    quaternion_order: QuaternionOrder = WXYZ,
    validity: ndarray | None = None,
    provenance: dict[str, object] | None = None,
)

Bases: PoseTrack

A native motion-capture rigid-body trajectory.

RigidTransform dataclass

RigidTransform(rotation: FloatArray, translation: FloatArray)

Rigid point transform target = source @ rotation.T + translation.

Methods:

Name	Description
apply	Transform points with trailing dimension 3.

Attributes:

Name	Type	Description
rotation	FloatArray
translation	FloatArray

Attributes

rotation instance-attribute

rotation: FloatArray

translation instance-attribute

translation: FloatArray

Functions

apply

apply(points: FloatArray) -> FloatArray

Transform points with trailing dimension 3.

SampleTimeline dataclass

SampleTimeline(timestamps: FloatArray, clock: str = 'native')

Strictly increasing sample timestamps in one recording's native clock.

Methods:

Name	Description
uniform	Create a uniform timeline.
slice	Return a timeline subset.

Attributes:

Name	Type	Description
timestamps	FloatArray
clock	str
sample_count	int	Number of timestamps.
start_s	float	First timestamp.
end_s	float	Last timestamp.
duration_s	float	Duration between first and last timestamps.
nominal_fps	float | None	Median sampling rate, or None for a single sample.

Attributes

timestamps instance-attribute

timestamps: FloatArray

clock class-attribute instance-attribute

clock: str = 'native'

sample_count property

sample_count: int

Number of timestamps.

start_s property

start_s: float

First timestamp.

end_s property

end_s: float

Last timestamp.

duration_s property

duration_s: float

Duration between first and last timestamps.

nominal_fps property

nominal_fps: float | None

Median sampling rate, or None for a single sample.

Functions

uniform classmethod

uniform(
    sample_count: int, fps: float, *, start_s: float = 0.0, clock: str = "native"
) -> SampleTimeline

Create a uniform timeline.

slice

slice(indices: slice | ndarray) -> SampleTimeline

Return a timeline subset.

TemporalRegistrationConfig dataclass

TemporalRegistrationConfig(
    max_abs_offset_s: float,
    min_overlap_s: float = 0.5,
    minimum_score: float = 0.2,
    coarse_steps: int = 1001,
    activity_weighted: bool = True,
)

Quality and search policy for offset registration.

Attributes:

Name	Type	Description
max_abs_offset_s	float
min_overlap_s	float
minimum_score	float
coarse_steps	int
activity_weighted	bool

Attributes

max_abs_offset_s instance-attribute

max_abs_offset_s: float

min_overlap_s class-attribute instance-attribute

min_overlap_s: float = 0.5

minimum_score class-attribute instance-attribute

minimum_score: float = 0.2

coarse_steps class-attribute instance-attribute

coarse_steps: int = 1001

activity_weighted class-attribute instance-attribute

activity_weighted: bool = True

ViconBagSource dataclass

ViconBagSource(
    path: Path,
    schema: ViconSourceSchema,
    topics: ViconBagTopics = ViconBagTopics(),
    frame: FrameConvention = Z_UP_RIGHT_HANDED,
    name: str = "",
    transform_scale_m: float = 1.0,
    marker_scale_m: float = 0.001,
)

Read a ROS 2 Vicon bag directly into a native mocap recording.

The optional capture-ros dependency is imported only when :meth:load runs. The bag is never converted into a persistent table or archive.

Methods:

Name	Description
load	Deserialize configured bag topics into typed Vicon tracks.

Attributes:

Name	Type	Description
path	Path
schema	ViconSourceSchema
topics	ViconBagTopics
frame	FrameConvention
name	str
transform_scale_m	float
marker_scale_m	float

Attributes

path instance-attribute

path: Path

schema instance-attribute

schema: ViconSourceSchema

topics class-attribute instance-attribute

topics: ViconBagTopics = ViconBagTopics()

frame class-attribute instance-attribute

frame: FrameConvention = Z_UP_RIGHT_HANDED

name class-attribute instance-attribute

name: str = ''

transform_scale_m class-attribute instance-attribute

transform_scale_m: float = 1.0

marker_scale_m class-attribute instance-attribute

marker_scale_m: float = 0.001

Functions

load

load() -> MocapRecording

Deserialize configured bag topics into typed Vicon tracks.

ViconBagTopics dataclass

ViconBagTopics(
    transforms: tuple[str, ...] = ("/tf",),
    markers: tuple[str, ...] = ("/vicon/markers",),
)

ROS topics carrying Vicon rigid-body transforms and marker samples.

Attributes:

Name	Type	Description
transforms	tuple[str, ...]
markers	tuple[str, ...]

Attributes

transforms class-attribute instance-attribute

transforms: tuple[str, ...] = ('/tf',)

markers class-attribute instance-attribute

markers: tuple[str, ...] = ('/vicon/markers',)

ViconRecordingSource dataclass

ViconRecordingSource(
    path: Path,
    schema: ViconSourceSchema,
    frame: FrameConvention = Z_UP_RIGHT_HANDED,
    name: str = "",
)

Load a preconverted Vicon recording directly into typed tracks.

Methods:

Name	Description
load	Load vicon.npz without a synchronization intermediate.

Attributes:

Name	Type	Description
path	Path
schema	ViconSourceSchema
frame	FrameConvention
name	str

Attributes

path instance-attribute

path: Path

schema instance-attribute

schema: ViconSourceSchema

frame class-attribute instance-attribute

frame: FrameConvention = Z_UP_RIGHT_HANDED

name class-attribute instance-attribute

name: str = ''

Functions

load

load() -> MocapRecording

Load vicon.npz without a synchronization intermediate.

ViconSourceSchema dataclass

ViconSourceSchema(
    rigid_bodies: Mapping[str, MocapRigidBody],
    markers: Mapping[str, MocapMarker],
    rigid_body_order: tuple[str, ...] | None = None,
    marker_order: tuple[str, ...] | None = None,
)

Map Vicon table names into typed native vocabularies.

Attributes:

Name	Type	Description
rigid_bodies	Mapping[str, MocapRigidBody]
markers	Mapping[str, MocapMarker]
rigid_body_order	tuple[str, ...] | None
marker_order	tuple[str, ...] | None

Attributes

rigid_bodies instance-attribute

rigid_bodies: Mapping[str, MocapRigidBody]

markers instance-attribute

markers: Mapping[str, MocapMarker]

rigid_body_order class-attribute instance-attribute

rigid_body_order: tuple[str, ...] | None = None

marker_order class-attribute instance-attribute

marker_order: tuple[str, ...] | None = None

VideoPoseSource dataclass

VideoPoseSource(video: VideoRecording, estimator: HumanPoseEstimator)

Compose a video recording source with a pose estimator.

Methods:

Name	Description
load	Estimate and return human pose.

Attributes:

Name	Type	Description
video	VideoRecording
estimator	HumanPoseEstimator

Attributes

video instance-attribute

video: VideoRecording

estimator instance-attribute

estimator: HumanPoseEstimator

Functions

load

load() -> HumanPoseRecording

Estimate and return human pose.

VideoRecording dataclass

VideoRecording(
    name: str,
    path: Path,
    timeline: SampleTimeline,
    frame_size: tuple[int, int] | None = None,
    provenance: dict[str, object] | None = None,
)

A video stream and its native frame timeline.

Attributes:

Name	Type	Description
name	str
path	Path
timeline	SampleTimeline
frame_size	tuple[int, int] | None
provenance	dict[str, object] | None

Attributes

name instance-attribute

name: str

path instance-attribute

path: Path

timeline instance-attribute

timeline: SampleTimeline

frame_size class-attribute instance-attribute

frame_size: tuple[int, int] | None = None

provenance class-attribute instance-attribute

provenance: dict[str, object] | None = None

AssetKind

Bases: StrEnum

Types of assets tracked by an asset manifest.

Attributes:

Name	Type	Description
ROBOT	str	Robot model assets.
OBJECT	str	Manipulated object meshes or trajectories.
TERRAIN	str	Terrain / environment geometry.
MOTION	str	Source motion clips.
FIXTURE	str	Scene fixtures and props.

ROBOT member

ROBOT = 'robot'

OBJECT member

OBJECT = 'object'

TERRAIN member

TERRAIN = 'terrain'

MOTION member

MOTION = 'motion'

FIXTURE member

FIXTURE = 'fixture'

Constraint

Bases: ConstraintKind

Built-in constraint term registry keys.

Attributes:

Name	Type	Description
JOINT_LIMITS	str	Enforce joint limits.
TRUST_REGION	str	Limit per-step configuration change.
FOOT_STICKING	str	Foot support consistency constraints.
FOOT_LOCK	str	Lock feet during planted phases.
NON_PENETRATION	str	Prevent interpenetration with scene geometry.
SELF_COLLISION	str	Self-collision avoidance.

Attributes

JOINT_LIMITS class-attribute instance-attribute

JOINT_LIMITS = 'joint_limits'

TRUST_REGION class-attribute instance-attribute

TRUST_REGION = 'trust_region'

FOOT_STICKING class-attribute instance-attribute

FOOT_STICKING = 'foot_sticking'

FOOT_LOCK class-attribute instance-attribute

FOOT_LOCK = 'foot_lock'

NON_PENETRATION class-attribute instance-attribute

NON_PENETRATION = 'non_penetration'

SELF_COLLISION class-attribute instance-attribute

SELF_COLLISION = 'self_collision'

ConstraintKind

Bases: RegistryKind

Base enum for constraint registrations.

ContactLayerKind

Bases: RetargetEnum

Persisted contact layer storage kind.

Members:

Name	Type	Description
BINARY	int	Value 'binary'.
CATEGORICAL	int	Value 'categorical'.

BINARY member

BINARY = 'binary'

CATEGORICAL member

CATEGORICAL = 'categorical'

ContactPatch

Bases: NameEnum

Base enum for contact patch labels.

ContactState

Bases: NameEnum

Base enum for symbolic contact state labels.

ContactSubject

Bases: NameEnum

Base enum for contact subjects such as feet, shoes, or hands.

ConvergenceMode

Bases: RetargetEnum

SQP inner-loop convergence policy.

Members:

Name	Type	Description
STEP_NORM	int	Value 'step_norm'.
COST_PLATEAU	int	Value 'cost_plateau'.
NONE	int	Value 'none'.

STEP_NORM member

STEP_NORM = 'step_norm'

COST_PLATEAU member

COST_PLATEAU = 'cost_plateau'

NONE member

NONE = 'none'

CropPolicy

Bases: RetargetEnum

How a shared observation timeline handles source support.

Members:

Name	Type	Description
OVERLAP	int	Value 'overlap'.
FULL	int	Value 'full'.

OVERLAP member

OVERLAP = 'overlap'

FULL member

FULL = 'full'

ExporterKind

Bases: RegistryKind

Base enum for exporter registrations.

ExportFormat

Bases: ExporterKind

Built-in exporter registry keys.

Attributes:

Name	Type	Description
MUJOCO_NPZ	str	MuJoCo-compatible NPZ export bundle.

Attributes

MUJOCO_NPZ class-attribute instance-attribute

MUJOCO_NPZ = 'mujoco_npz'

FrameConvention

Bases: StrEnum

Coordinate frame conventions understood by the package.

Attributes:

Name	Type	Description
Z_UP_RIGHT_HANDED	str	Z-up, right-handed world frame.
Y_UP_RIGHT_HANDED	str	Y-up, right-handed world frame (common in video/SMPL).

Z_UP_RIGHT_HANDED member

Z_UP_RIGHT_HANDED = 'z_up_right_handed'

Y_UP_RIGHT_HANDED member

Y_UP_RIGHT_HANDED = 'y_up_right_handed'

HumanoidRobotRole

Bases: RobotRole

Standard semantic roles exposed by humanoid robot specs.

Attributes:

Name	Type	Description
PELVIS
TORSO
HEAD
LEFT_HIP
LEFT_KNEE
LEFT_ANKLE
LEFT_FOOT
RIGHT_HIP
RIGHT_KNEE
RIGHT_ANKLE
RIGHT_FOOT
LEFT_HAND
RIGHT_HAND

Attributes

PELVIS class-attribute instance-attribute

PELVIS = 'pelvis'

TORSO class-attribute instance-attribute

TORSO = 'torso'

HEAD class-attribute instance-attribute

HEAD = 'head'

LEFT_HIP class-attribute instance-attribute

LEFT_HIP = 'left_hip'

LEFT_KNEE class-attribute instance-attribute

LEFT_KNEE = 'left_knee'

LEFT_ANKLE class-attribute instance-attribute

LEFT_ANKLE = 'left_ankle'

LEFT_FOOT class-attribute instance-attribute

LEFT_FOOT = 'left_foot'

RIGHT_HIP class-attribute instance-attribute

RIGHT_HIP = 'right_hip'

RIGHT_KNEE class-attribute instance-attribute

RIGHT_KNEE = 'right_knee'

RIGHT_ANKLE class-attribute instance-attribute

RIGHT_ANKLE = 'right_ankle'

RIGHT_FOOT class-attribute instance-attribute

RIGHT_FOOT = 'right_foot'

LEFT_HAND class-attribute instance-attribute

LEFT_HAND = 'left_hand'

RIGHT_HAND class-attribute instance-attribute

RIGHT_HAND = 'right_hand'

KinematicsBackendName

Bases: KinematicsKind

Built-in kinematics backend registry keys.

Attributes:

Name	Type	Description
SIMPLE	str	Lightweight analytic / table backend.
MUJOCO	str	MuJoCo model backend.

Attributes

SIMPLE class-attribute instance-attribute

SIMPLE = 'simple'

MUJOCO class-attribute instance-attribute

MUJOCO = 'mujoco'

KinematicsKind

Bases: RegistryKind

Base enum for kinematics-backend registrations.

MetricKind

Bases: RegistryKind

Base enum for metric registrations.

MetricName

Bases: MetricKind

Built-in evaluation metric names.

Attributes:

Name	Type	Description
OPTIMIZATION_COST	str	Final optimization cost.
FOOT_SLIDING	str	Foot sliding during contact.
CONTACT_PRESERVATION	str	Agreement with input contact signal.
PENETRATION	str	Mesh penetration depth metric.

Attributes

OPTIMIZATION_COST class-attribute instance-attribute

OPTIMIZATION_COST = 'optimization_cost'

FOOT_SLIDING class-attribute instance-attribute

FOOT_SLIDING = 'foot_sliding'

CONTACT_PRESERVATION class-attribute instance-attribute

CONTACT_PRESERVATION = 'contact_preservation'

PENETRATION class-attribute instance-attribute

PENETRATION = 'penetration'

MocapMarker

Bases: NameEnum

Base enum for native motion-capture marker names.

MocapRigidBody

Bases: NameEnum

Base enum for native motion-capture rigid-body names.

MotionFormat

Bases: MotionFormatKind

Built-in motion format registry keys.

Attributes:

Name	Type	Description
MINIMAL	str	Minimal joint-name + qpos arrays.
SMPLH	str	SMPL-H pose parameters.
LAFAN	str	LaFAN1-style skeleton dumps.
MOCAP	str	Generic mocap tables.
SMPLX	str	SMPL-X body pose and shape.

Attributes

MINIMAL class-attribute instance-attribute

MINIMAL = 'minimal'

SMPLH class-attribute instance-attribute

SMPLH = 'smplh'

LAFAN class-attribute instance-attribute

LAFAN = 'lafan'

MOCAP class-attribute instance-attribute

MOCAP = 'mocap'

SMPLX class-attribute instance-attribute

SMPLX = 'smplx'

MotionFormatKind

Bases: RegistryKind

Base enum for motion-format registrations.

MotionJoint

Bases: NameEnum

Base enum for source motion joint names.

MotionLoaderKind

Bases: RegistryKind

Base enum for motion-loader registrations.

MotionLoaderSuffix

Bases: MotionLoaderKind

Built-in motion loader suffix registry keys.

Attributes:

Name	Type	Description
JSON	str	.json loader.
CSV	str	.csv loader.
NPY	str	.npy loader.
NPZ	str	.npz loader.

Attributes

JSON class-attribute instance-attribute

JSON = '.json'

CSV class-attribute instance-attribute

CSV = '.csv'

NPY class-attribute instance-attribute

NPY = '.npy'

NPZ class-attribute instance-attribute

NPZ = '.npz'

NameEnum

Bases: RetargetEnum

Base class for user-defined symbolic vocabularies.

NominalFallback

Bases: RetargetEnum

Fallback target for nominal qpos tracking.

Members:

Name	Type	Description
ZERO	int	Value 'zero'.
CURRENT	int	Value 'current'.

ZERO member

ZERO = 'zero'

CURRENT member

CURRENT = 'current'

NonPenetrationSource

Bases: RetargetEnum

Sources used by the non-penetration constraint.

Members:

Name	Type	Description
SUPPORT	int	Value 'support'.
SCENE_POINTS	int	Value 'scene_points'.
GEOMETRY	int	Value 'geometry'.

SUPPORT member

SUPPORT = 'support'

SCENE_POINTS member

SCENE_POINTS = 'scene_points'

GEOMETRY member

GEOMETRY = 'geometry'

Objective

Bases: ObjectiveKind

Built-in objective term registry keys.

Attributes:

Name	Type	Description
LAPLACIAN	str	Interaction-mesh Laplacian deformation objective.
LINK_TRACKING	str	Track named robot links to per-frame world-space target points.
SMOOTHNESS	str	Temporal smoothness on generalized coordinates.
NOMINAL_TRACKING	str	Track a nominal pose trajectory.
DIAGONAL_REGULARIZATION	str	Penalize selected qpos coordinates toward zero.

Attributes

LAPLACIAN class-attribute instance-attribute

LAPLACIAN = 'laplacian'

LINK_TRACKING class-attribute instance-attribute

LINK_TRACKING = 'link_tracking'

SMOOTHNESS class-attribute instance-attribute

SMOOTHNESS = 'smoothness'

NOMINAL_TRACKING class-attribute instance-attribute

NOMINAL_TRACKING = 'nominal_tracking'

DIAGONAL_REGULARIZATION class-attribute instance-attribute

DIAGONAL_REGULARIZATION = 'diagonal_regularization'

ObjectiveKind

Bases: RegistryKind

Base enum for objective registrations.

ObjectQposMode

Bases: RetargetEnum

How a dynamic object trajectory participates in qpos.

Members:

Name	Type	Description
APPENDED	int	Value 'appended'.
EXTERNAL	int	Value 'external'.

APPENDED member

APPENDED = 'appended'

EXTERNAL member

EXTERNAL = 'external'

ObjectSampleSpace

Bases: RetargetEnum

Coordinate space for object sample points.

Members:

Name	Type	Description
OBJECT_LOCAL	int	Value 'object_local'.
OBJECT_ASSET_LOCAL	int	Value 'object_asset_local'.
SCALED_OBJECT_LOCAL	int	Value 'scaled_object_local'.
WORLD	int	Value 'world'.

OBJECT_LOCAL member

OBJECT_LOCAL = 'object_local'

OBJECT_ASSET_LOCAL member

OBJECT_ASSET_LOCAL = 'object_asset_local'

SCALED_OBJECT_LOCAL member

SCALED_OBJECT_LOCAL = 'scaled_object_local'

WORLD member

WORLD = 'world'

ObservationRecipeKind

Bases: ObservationRecipeKindBase

Built-in observation-recipe kinds for declarative run configs.

Attributes:

Name	Type	Description
MOTION_FILE
SKATEBOARDING
HOLOSOMA_CLIMB

Attributes

MOTION_FILE class-attribute instance-attribute

MOTION_FILE = 'motion_file'

SKATEBOARDING class-attribute instance-attribute

SKATEBOARDING = 'skateboarding'

HOLOSOMA_CLIMB class-attribute instance-attribute

HOLOSOMA_CLIMB = 'holosoma_climb'

ObservationRecipeKindBase

Bases: RegistryKind

Base enum for observation-recipe registrations.

ObservationRole

Bases: NameEnum

Base enum for target-independent semantic observation roles.

QposVariableKind

Bases: RetargetEnum

Which qpos coordinates the optimizer may change.

Members:

Name	Type	Description
ACTUATED	int	Value 'actuated'.
QPOS_SLICE	int	Value 'qpos_slice'.
QPOS_INDICES	int	Value 'qpos_indices'.

ACTUATED member

ACTUATED = 'actuated'

QPOS_SLICE member

QPOS_SLICE = 'qpos_slice'

QPOS_INDICES member

QPOS_INDICES = 'qpos_indices'

QuaternionOrder

Bases: StrEnum

Quaternion storage order.

Attributes:

Name	Type	Description
WXYZ	str	Scalar-first (w, x, y, z) layout.
XYZW	str	Scalar-last (x, y, z, w) layout (common in graphics APIs).

WXYZ member

WXYZ = 'wxyz'

XYZW member

XYZW = 'xyzw'

RetargetEnum

Bases: StrEnum

Base class for string-valued retarget enums.

RetargetingRecipeKind

Bases: RetargetingRecipeKindBase

Built-in robot-adaptation recipe kinds for declarative run configs.

Attributes:

Name	Type	Description
ROLE_MAPPING
SKATEBOARDING
HOLOSOMA_CLIMB

Attributes

ROLE_MAPPING class-attribute instance-attribute

ROLE_MAPPING = 'role_mapping'

SKATEBOARDING class-attribute instance-attribute

SKATEBOARDING = 'skateboarding'

HOLOSOMA_CLIMB class-attribute instance-attribute

HOLOSOMA_CLIMB = 'holosoma_climb'

RetargetingRecipeKindBase

Bases: RegistryKind

Base enum for retargeting-recipe registrations.

Robot

Bases: RobotKind

Built-in robot registry keys.

Attributes:

Name	Type	Description
SYNTHETIC_HUMANOID	str	Lightweight test humanoid.
G1_LIKE	str	Unitree G1-style humanoid preset.
T1_LIKE	str	Booster T1-style humanoid preset.

Attributes

SYNTHETIC_HUMANOID class-attribute instance-attribute

SYNTHETIC_HUMANOID = 'synthetic_humanoid'

G1_LIKE class-attribute instance-attribute

G1_LIKE = 'g1_like'

T1_LIKE class-attribute instance-attribute

T1_LIKE = 't1_like'

RobotGeometry

Bases: NameEnum

Base enum for robot collision and visual geometry names.

RobotJoint

Bases: NameEnum

Base enum for robot joint names.

RobotKind

Bases: RegistryKind

Base enum for robot registrations.

RobotLink

Bases: NameEnum

Base enum for robot link names.

RobotProviderKind

Bases: RegistryKind

Base enum for robot-provider registrations.

RobotProviderName

Bases: RobotProviderKind

Built-in robot provider registry keys.

Attributes:

Name	Type	Description
REGISTRY	str	Load from built-in registry entries.
FILE	str	Load robot spec from a file path.
ASSET_STORE	str	Resolve robot via the asset store manifest.

Attributes

REGISTRY class-attribute instance-attribute

REGISTRY = 'registry'

FILE class-attribute instance-attribute

FILE = 'file'

ASSET_STORE class-attribute instance-attribute

ASSET_STORE = 'asset_store'

HOLOSOMA class-attribute instance-attribute

HOLOSOMA = 'holosoma'

RobotRole

Bases: NameEnum

Base enum for semantic roles resolved by a robot specification.

RunStatus

Bases: StrEnum

Retargeting or evaluation lifecycle state.

Attributes:

Name	Type	Description
SUCCESS	str	Completed successfully.
PARTIAL	str	Completed with recoverable issues.
FAILED	str	Failed before producing a usable result.
SKIPPED	str	Skipped (for example missing inputs).

SUCCESS member

SUCCESS = 'success'

PARTIAL member

PARTIAL = 'partial'

FAILED member

FAILED = 'failed'

SKIPPED member

SKIPPED = 'skipped'

SceneGeometry

Bases: NameEnum

Base enum for target-independent scene geometry groups.

SolverBackend

Bases: SolverKind

Optimization backend choices.

Attributes:

Name	Type	Description
AUTO	str	Pick an available backend at runtime.
NUMPY_LEAST_SQUARES	str	SciPy/NumPy least-squares solver.
CVXPY_CLARABEL	str	CVXPY with Clarabel conic solver.

Attributes

AUTO class-attribute instance-attribute

AUTO = 'auto'

NUMPY_LEAST_SQUARES class-attribute instance-attribute

NUMPY_LEAST_SQUARES = 'numpy_least_squares'

CVXPY_CLARABEL class-attribute instance-attribute

CVXPY_CLARABEL = 'cvxpy_clarabel'

SolverKind

Bases: RegistryKind

Base enum for solver registrations.

TaskKind

Bases: StrEnum

Supported high-level retargeting workflows.

Attributes:

Name	Type	Description
ROBOT_ONLY	str	Retarget humanoid motion without scene props ("robot_only").
OBJECT_INTERACTION	str	Retarget with manipulated objects and contact ("object_interaction").
CLIMBING	str	Climbing / terrain interaction workflow ("climbing").

ROBOT_ONLY member

ROBOT_ONLY = 'robot_only'

OBJECT_INTERACTION member

OBJECT_INTERACTION = 'object_interaction'

CLIMBING member

CLIMBING = 'climbing'

TimelineSelection

Bases: RetargetEnum

Native timeline selected as the observation sampling grid.

Members:

Name	Type	Description
HUMAN_POSE	int	Value 'human_pose'.
MOCAP	int	Value 'mocap'.
UNIFORM	int	Value 'uniform'.

HUMAN_POSE member

HUMAN_POSE = 'human_pose'

MOCAP member

MOCAP = 'mocap'

UNIFORM member

UNIFORM = 'uniform'

VisualizerKind

Bases: RegistryKind

Base enum for visualizer registrations.

VisualizerName

Bases: VisualizerKind

Built-in visualizer registry keys.

Attributes:

Name	Type	Description
DRY_RUN	str	Print summary without opening a viewer.
VISER	str	Interactive Viser web visualizer.

Attributes

DRY_RUN class-attribute instance-attribute

DRY_RUN = 'dry_run'

VISER class-attribute instance-attribute

VISER = 'viser'

Pose

Bases: BaseModel

Rigid transform from a local frame into a named world convention.

Attributes:

Name	Type	Description
translation	FloatArray	World-frame origin offset, shape (3,).
quaternion	FloatArray	Unit quaternion in quaternion_order layout, shape (4,).
quaternion_order	QuaternionOrder	Storage order of quaternion.
frame	FrameConvention	World coordinate convention for translation.

Methods:

Name	Description
identity	Return an identity pose.
quaternion_as	Return the quaternion in the requested storage order.
rotation	Return this pose's rotation as a SciPy Rotation.
matrix	Return a 4x4 homogeneous transform matrix.
inverse	Return the inverse transform.
transform_points	Transform points of shape (..., 3) from local to world coordinates.
inverse_transform_points	Transform points of shape (..., 3) from world to local coordinates.
to_frame	Return this pose represented in another coordinate frame convention.
scaled	Return a copy with translation scaled and rotation preserved.

Attributes

model_config class-attribute instance-attribute

model_config = ConfigDict(arbitrary_types_allowed=True)

translation class-attribute instance-attribute

translation: FloatArray = Field(default_factory=lambda: zeros(3, dtype=float64))

quaternion class-attribute instance-attribute

quaternion: FloatArray = Field(
    default_factory=lambda: array([1.0, 0.0, 0.0, 0.0], dtype=float64)
)

quaternion_order class-attribute instance-attribute

quaternion_order: QuaternionOrder = WXYZ

frame class-attribute instance-attribute

frame: FrameConvention = Z_UP_RIGHT_HANDED

Functions

identity classmethod

identity(*, frame: FrameConvention = Z_UP_RIGHT_HANDED) -> Self

Return an identity pose.

Parameters:

Name	Type	Description	Default
frame	FrameConvention	World coordinate convention for the pose.	Z_UP_RIGHT_HANDED

Returns:

Name	Type	Description
Pose	Self	Identity transform with zero translation and unit rotation.

quaternion_as

quaternion_as(order: QuaternionOrder) -> FloatArray

Return the quaternion in the requested storage order.

Parameters:

Name	Type	Description	Default
order	QuaternionOrder	Desired component layout.	required

Returns:

Name	Type	Description
FloatArray	FloatArray	Unit quaternion with shape (4,) in order.

rotation

rotation() -> Rotation

Return this pose's rotation as a SciPy Rotation.

Returns:

Name	Type	Description
Rotation	Rotation	Orientation in SciPy's scalar-last (x, y, z, w) convention.

matrix

matrix() -> FloatArray

Return a 4x4 homogeneous transform matrix.

Returns:

Name	Type	Description
FloatArray	FloatArray	(4, 4) matrix mapping local homogeneous coordinates to world.

inverse

inverse() -> Pose

Return the inverse transform.

Returns:

Name	Type	Description
Pose	Pose	Transform that maps world coordinates back to the local frame.

transform_points

transform_points(points: Any) -> FloatArray

Transform points of shape (..., 3) from local to world coordinates.

Parameters:

Name	Type	Description	Default
points	Any	Local-frame positions with trailing dimension 3.	required

Returns:

Name	Type	Description
FloatArray	FloatArray	World-frame positions with the same shape as points.

inverse_transform_points

inverse_transform_points(points: Any) -> FloatArray

Transform points of shape (..., 3) from world to local coordinates.

Parameters:

Name	Type	Description	Default
points	Any	World-frame positions with trailing dimension 3.	required

Returns:

Name	Type	Description
FloatArray	FloatArray	Local-frame positions with the same shape as points.

to_frame

to_frame(target: FrameConvention) -> Pose

Return this pose represented in another coordinate frame convention.

Parameters:

Name	Type	Description	Default
target	FrameConvention	Desired world coordinate convention.	required

Returns:

Name	Type	Description
Pose	Pose	Same rigid transform expressed in target.

scaled

scaled(factor: float) -> Pose

Return a copy with translation scaled and rotation preserved.

Parameters:

Name	Type	Description	Default
factor	float	Multiplier applied to translation.	required

Returns:

Name	Type	Description
Pose	Pose	Copy with scaled translation and unchanged orientation.

PoseSequence

Bases: BaseModel

Time-indexed sequence of poses.

Attributes:

Name	Type	Description
poses	tuple[Pose, ...]	Per-frame rigid transforms sharing one frame.
fps	float	Sampling rate in Hz for time-based resampling.

Methods:

Name	Description
quaternions	Stacked quaternions with shape (T, 4).
identity	Return frame_count identity poses.
from_arrays	Build a pose sequence from position and quaternion arrays.
to_frame	Return this sequence represented in another coordinate frame convention.
scaled	Return this sequence with translations scaled and rotations preserved.
resampled	Return this pose sequence sampled on a new FPS grid.

Attributes

model_config class-attribute instance-attribute

model_config = ConfigDict(arbitrary_types_allowed=True)

poses instance-attribute

poses: tuple[Pose, ...]

fps class-attribute instance-attribute

fps: float = 30.0

frame_count property

frame_count: int

Number of poses.

frame property

frame: FrameConvention

Coordinate frame used by every pose.

positions property

positions: FloatArray

Stacked translations with shape (T, 3).

Functions

quaternions

quaternions(order: QuaternionOrder = WXYZ) -> FloatArray

Stacked quaternions with shape (T, 4).

Parameters:

Name	Type	Description	Default
order	QuaternionOrder	Storage order for each frame's quaternion.	WXYZ

Returns:

Name	Type	Description
FloatArray	FloatArray	Quaternion array with shape (T, 4).

identity classmethod

identity(
    frame_count: int, *, fps: float = 30.0, frame: FrameConvention = Z_UP_RIGHT_HANDED
) -> PoseSequence

Return frame_count identity poses.

Parameters:

Name	Type	Description	Default
frame_count	int	Number of frames to create.	required
fps	float	Sampling rate in Hz.	30.0
frame	FrameConvention	World coordinate convention for every pose.	Z_UP_RIGHT_HANDED

Returns:

Name	Type	Description
PoseSequence	PoseSequence	Sequence of identity transforms.

from_arrays classmethod

from_arrays(
    positions: Any,
    quaternions: Any,
    *,
    fps: float = 30.0,
    quaternion_order: QuaternionOrder = WXYZ,
    frame: FrameConvention = Z_UP_RIGHT_HANDED,
) -> PoseSequence

Build a pose sequence from position and quaternion arrays.

Parameters:

Name	Type	Description	Default
positions	Any	Translations with shape (T, 3).	required
quaternions	Any	Orientations with shape (T, 4) in quaternion_order.	required
fps	float	Sampling rate in Hz.	30.0
quaternion_order	QuaternionOrder	Layout of each row in quaternions.	WXYZ
frame	FrameConvention	World coordinate convention for every pose.	Z_UP_RIGHT_HANDED

Returns:

Name	Type	Description
PoseSequence	PoseSequence	One Pose per matched time index.

to_frame

to_frame(target: FrameConvention) -> PoseSequence

Return this sequence represented in another coordinate frame convention.

Parameters:

Name	Type	Description	Default
target	FrameConvention	Desired world coordinate convention.	required

Returns:

Name	Type	Description
PoseSequence	PoseSequence	Copy with each pose converted to target.

scaled

scaled(factor: float) -> PoseSequence

Return this sequence with translations scaled and rotations preserved.

Parameters:

Name	Type	Description	Default
factor	float	Multiplier applied to every pose translation.	required

Returns:

Name	Type	Description
PoseSequence	PoseSequence	Copy with scaled translations and unchanged orientations.

resampled

resampled(fps: float) -> PoseSequence

Return this pose sequence sampled on a new FPS grid.

Parameters:

Name	Type	Description	Default
fps	float	Target sampling rate in Hz.	required

Returns:

Name	Type	Description
PoseSequence	PoseSequence	Endpoint-preserving resample with linear translation and spherical-linear rotation interpolation.

ConstraintTerm

Bases: Protocol[ConstraintConfigT]

Optimization constraint term.

Methods:

Name	Description
describe	Return a short human-readable summary of the term.
build	Build a constraint contribution for one optimization step.

Attributes:

Name	Type	Description
kind	ConstraintKind	Typed registry key for this constraint term.
config_type	type[ConstraintConfigT]	Typed config model consumed by this term.

Attributes

kind property

kind: ConstraintKind

Typed registry key for this constraint term.

config_type property

config_type: type[ConstraintConfigT]

Typed config model consumed by this term.

Functions

describe

describe() -> str

Return a short human-readable summary of the term.

build

build(context: TermContext, config: ConstraintConfigT) -> ConstraintContribution

Build a constraint contribution for one optimization step.

Parameters:

Name	Type	Description	Default
context	TermContext	Shared kinematics and trajectory state.	required
config	ConstraintConfig	Term configuration from the problem spec.	required

Returns:

Name	Type	Description
ConstraintContribution	ConstraintContribution	Linearized inequality or equality block.

Exporter

Bases: Protocol

Export a retargeting result to an external workflow format.

Methods:

Name	Description
export	Write retargeting output to an external format.

Functions

export

export(result: RetargetingResult, spec: ExportSpec) -> ExportResult

Write retargeting output to an external format.

Parameters:

Name	Type	Description	Default
result	RetargetingResult	Solved trajectory and structured reports.	required
spec	ExportSpec	Target format and destination options.	required

Returns:

Name	Type	Description
ExportResult	ExportResult	Paths and status for written artifacts.

KinematicsBackend

Bases: Protocol

Robot kinematics operations needed by retargeting and metrics.

Methods:

Name	Description
forward_kinematics	Compute link poses for the given configuration.
link_positions	Return world-frame link origins.
body_jacobians	Return position, rotation, and full spatial Jacobians for bodies.
body_jacobians_for_qpos_indices	Return body Jacobians with columns selected by qpos indices.
point_jacobians	Return Jacobians for named kinematic points.
point_jacobians_for_qpos_indices	Return point Jacobians with columns selected by qpos indices.
qpos_to_qvel	Finite-difference generalized velocity from two poses.
integrate_qvel	Integrate generalized velocity for one time step.
joint_limits	Return per-joint position limits.
geom_distances	Measure distances between geometry pairs.
collision_candidates	Return geometry pairs within a collision margin.
geom_distance_jacobians	Return linearized geometry distances for qpos-index variables.

Functions

forward_kinematics

forward_kinematics(
    qpos: NDArray[float64], link_names: tuple[str, ...]
) -> NDArray[float64]

Compute link poses for the given configuration.

Parameters:

Name	Type	Description	Default
qpos	NDArray[float64]	Generalized coordinates.	required
link_names	tuple[str, ...]	Links to evaluate.	required

Returns:

Type	Description
NDArray[float64]	NDArray[np.float64]: Flattened pose array for the requested links.

link_positions

link_positions(qpos: NDArray[float64], link_names: tuple[str, ...]) -> NDArray[float64]

Return world-frame link origins.

Parameters:

Name	Type	Description	Default
qpos	NDArray[float64]	Generalized coordinates.	required
link_names	tuple[str, ...]	Links to evaluate.	required

Returns:

Type	Description
NDArray[float64]	NDArray[np.float64]: Positions with shape (len(link_names), 3).

body_jacobians

body_jacobians(
    qpos: NDArray[float64], body_names: tuple[str, ...]
) -> tuple[NDArray[float64], NDArray[float64], NDArray[float64]]

Return position, rotation, and full spatial Jacobians for bodies.

Parameters:

Name	Type	Description	Default
qpos	NDArray[float64]	Generalized coordinates.	required
body_names	tuple[str, ...]	Bodies to differentiate.	required

Returns:

Type	Description
tuple[NDArray[float64], NDArray[float64], NDArray[float64]]	tuple[NDArray[np.float64], NDArray[np.float64], NDArray[np.float64]]: Position Jacobians, rotation Jacobians, and stacked spatial Jacobians.

body_jacobians_for_qpos_indices

body_jacobians_for_qpos_indices(
    qpos: NDArray[float64], body_names: tuple[str, ...], qpos_indices: NDArray[int64]
) -> tuple[NDArray[float64], NDArray[float64], NDArray[float64]]

Return body Jacobians with columns selected by qpos indices.

Parameters:

Name	Type	Description	Default
qpos	NDArray[float64]	Generalized coordinates.	required
body_names	tuple[str, ...]	Bodies to differentiate.	required
qpos_indices	NDArray[int64]	Qpos coordinates used as optimizer variables.	required

Returns:

Type	Description
tuple[NDArray[float64], NDArray[float64], NDArray[float64]]	tuple[NDArray[np.float64], NDArray[np.float64], NDArray[np.float64]]: Positions, translational Jacobians, and rotational Jacobians.

point_jacobians

point_jacobians(
    qpos: NDArray[float64], point_names: tuple[str, ...]
) -> tuple[NDArray[float64], NDArray[float64]]

Return Jacobians for named kinematic points.

Parameters:

Name	Type	Description	Default
qpos	NDArray[float64]	Generalized coordinates.	required
point_names	tuple[str, ...]	Named points on the model.	required

Returns:

Type	Description
tuple[NDArray[float64], NDArray[float64]]	tuple[NDArray[np.float64], NDArray[np.float64]]: Position Jacobians and optional auxiliary Jacobians.

point_jacobians_for_qpos_indices

point_jacobians_for_qpos_indices(
    qpos: NDArray[float64], point_names: tuple[str, ...], qpos_indices: NDArray[int64]
) -> tuple[NDArray[float64], NDArray[float64]]

Return point Jacobians with columns selected by qpos indices.

Parameters:

Name	Type	Description	Default
qpos	NDArray[float64]	Generalized coordinates.	required
point_names	tuple[str, ...]	Named points on the model.	required
qpos_indices	NDArray[int64]	Qpos coordinates used as optimizer variables.	required

Returns:

Type	Description
tuple[NDArray[float64], NDArray[float64]]	tuple[NDArray[np.float64], NDArray[np.float64]]: Positions and qpos-index Jacobians.

qpos_to_qvel

qpos_to_qvel(
    qpos: NDArray[float64], previous_qpos: NDArray[float64], dt: float
) -> NDArray[float64]

Finite-difference generalized velocity from two poses.

Parameters:

Name	Type	Description	Default
qpos	NDArray[float64]	Current configuration.	required
previous_qpos	NDArray[float64]	Previous configuration.	required
dt	float	Time step in seconds.	required

Returns:

Type	Description
NDArray[float64]	NDArray[np.float64]: Generalized velocity matching qpos layout.

integrate_qvel

integrate_qvel(
    qpos: NDArray[float64], qvel: NDArray[float64], dt: float
) -> NDArray[float64]

Integrate generalized velocity for one time step.

Parameters:

Name	Type	Description	Default
qpos	NDArray[float64]	Starting configuration.	required
qvel	NDArray[float64]	Generalized velocity.	required
dt	float	Time step in seconds.	required

Returns:

Type	Description
NDArray[float64]	NDArray[np.float64]: Integrated configuration.

joint_limits

joint_limits() -> dict[str, tuple[float, float]]

Return per-joint position limits.

Returns:

Type	Description
dict[str, tuple[float, float]]	dict[str, tuple[float, float]]: Mapping from joint name to (low, high).

geom_distances

geom_distances(
    qpos: NDArray[float64],
    geom_pairs: tuple[tuple[str, str], ...],
    *,
    max_distance: float = inf,
) -> tuple[GeometryDistance, ...]

Measure distances between geometry pairs.

Parameters:

Name	Type	Description	Default
qpos	NDArray[float64]	Generalized coordinates.	required
geom_pairs	tuple[tuple[str, str], ...]	Explicit pairs to evaluate.	required
max_distance	float	Ignore pairs farther than this threshold.	inf

Returns:

Type	Description
tuple[GeometryDistance, ...]	tuple[GeometryDistance, ...]: Signed distances and contact normals per pair.

collision_candidates

collision_candidates(
    qpos: NDArray[float64],
    *,
    margin: float = 0.0,
    geom_pairs: tuple[tuple[str, str], ...],
) -> tuple[GeometryDistance, ...]

Return geometry pairs within a collision margin.

Parameters:

Name	Type	Description	Default
qpos	NDArray[float64]	Generalized coordinates.	required
margin	float	Distance threshold for candidate inclusion.	0.0
geom_pairs	tuple[tuple[str, str], ...]	Explicit pairs to scan.	required

Returns:

Type	Description
tuple[GeometryDistance, ...]	tuple[GeometryDistance, ...]: Near-contact pairs suitable for constraints.

geom_distance_jacobians

geom_distance_jacobians(
    qpos: NDArray[float64],
    qpos_indices: NDArray[int64],
    geom_pairs: tuple[tuple[str, str], ...],
    *,
    max_distance: float = inf,
) -> tuple[GeometryDistanceJacobian, ...]

Return linearized geometry distances for qpos-index variables.

Parameters:

Name	Type	Description	Default
qpos	NDArray[float64]	Generalized coordinates.	required
qpos_indices	NDArray[int64]	Qpos coordinates used as optimizer variables.	required
geom_pairs	tuple[tuple[str, str], ...]	Explicit pairs to evaluate.	required
max_distance	float	Ignore pairs farther than this threshold.	inf

Returns:

Type	Description
tuple[GeometryDistanceJacobian, ...]	tuple[GeometryDistanceJacobian, ...]: Distance rows suitable for linear constraints.

Metric

Bases: Protocol

Evaluate one metric.

Methods:

Name	Description
evaluate	Compute the metric for a retargeting run.

Attributes:

Name	Type	Description
name	MetricKind	Registry key for this metric.

Attributes

name property

name: MetricKind

Registry key for this metric.

Functions

evaluate

evaluate(result: RetargetingResult, problem: RetargetingProblem | None = None) -> float

Compute the metric for a retargeting run.

Parameters:

Name	Type	Description	Default
result	RetargetingResult	Solved trajectory and diagnostics.	required
problem	RetargetingProblem | None	Original problem, when needed for context.	None

Returns:

Name	Type	Description
float	float	Scalar metric value (lower is typically better).

MotionLoader

Bases: Protocol

Load a motion file into a MotionSequence.

Methods:

Name	Description
load	Load motion from disk.

Functions

load

load(path: Path, spec: MotionFormatSpec, *, name: str | None = None) -> MotionSequence

Load motion from disk.

Parameters:

Name	Type	Description	Default
path	Path	Source file path.	required
spec	MotionFormatSpec	Format descriptor for parsing.	required
name	str | None	Optional clip name override.	None

Returns:

Name	Type	Description
MotionSequence	MotionSequence	Parsed motion sequence.

ObjectiveTerm

Bases: Protocol[ObjectiveConfigT]

Optimization objective term.

Methods:

Name	Description
describe	Return a short human-readable summary of the term.
build	Build objective contributions for one optimization step.

Attributes:

Name	Type	Description
kind	ObjectiveKind	Typed registry key for this objective term.
config_type	type[ObjectiveConfigT]	Typed config model consumed by this term.

Attributes

kind property

kind: ObjectiveKind

Typed registry key for this objective term.

config_type property

config_type: type[ObjectiveConfigT]

Typed config model consumed by this term.

Functions

describe

describe() -> str

Return a short human-readable summary of the term.

build

build(
    context: TermContext, config: ObjectiveConfigT
) -> tuple[ObjectiveContribution, ...]

Build objective contributions for one optimization step.

Parameters:

Name	Type	Description	Default
context	TermContext	Shared kinematics and trajectory state.	required
config	ObjectiveConfig	Term configuration from the problem spec.	required

Returns:

Type	Description
tuple[ObjectiveContribution, ...]	tuple[ObjectiveContribution, ...]: One or more stacked objective blocks.

RobotProvider

Bases: Protocol

Resolve robot specs from names or external asset locations.

Methods:

Name	Description
load	Resolve a robot specification.

Functions

load

load(name: str, **kwargs: Any) -> RobotSpec

Resolve a robot specification.

Parameters:

Name	Type	Description	Default
name	str	Registry key or asset identifier.	required
**kwargs	Any	Provider-specific options (paths, manifests, etc.).	{}

Returns:

Name	Type	Description
RobotSpec	RobotSpec	Loaded robot model description.

Solver

Bases: Protocol

Solve a quadratic retargeting subproblem.

Methods:

Name	Description
solve	Solve a quadratic subproblem.

Functions

solve

solve(problem: QuadraticProblem) -> SolverResult

Solve a quadratic subproblem.

Parameters:

Name	Type	Description	Default
problem	QuadraticProblem	Assembled least-squares or conic problem.	required

Returns:

Name	Type	Description
SolverResult	SolverResult	Primal solution and solver diagnostics.

Visualizer

Bases: Protocol

Render or summarize a retargeting result.

Methods:

Name	Description
view	Open an interactive view or print a summary.

Functions

view

view(result: RetargetingResult) -> None

Open an interactive view or print a summary.

Parameters:

Name	Type	Description	Default
result	RetargetingResult	Retargeting output to display.	required

ExportResult

Bases: BaseModel

Summary of an export operation.

Attributes:

Name	Type	Description
format_name	str	Export format key used for the operation.
path	Path	Written output file path.
frame_count	int	Number of exported frames.
fps	float	Exported playback frame rate.
qpos_dimension	int | None	Exported generalized-position width.
qvel_dimension	int | None	Exported generalized-velocity width.
provenance	dict[str, Any]	Origin information for the export.

Attributes

format_name instance-attribute

format_name: ExporterKind

path instance-attribute

path: Path

frame_count instance-attribute

frame_count: int

fps instance-attribute

fps: float

qpos_dimension class-attribute instance-attribute

qpos_dimension: int | None = None

qvel_dimension class-attribute instance-attribute

qvel_dimension: int | None = None

provenance class-attribute instance-attribute

provenance: dict[str, Any] = Field(default_factory=dict)

ExportSpec

Bases: BaseModel

Configuration for exporting a retargeting result.

Attributes:

Name	Type	Description
format_name	str	Registered export format key (default "mujoco_npz").
output_path	Path	Destination file path for exported data.
output_fps	int | None	Optional resample rate before export; uses result fps when omitted.
kinematics_backend	KinematicsBackend | None	Optional backend for analytic qvel; finite differences when omitted.
provenance	dict[str, Any]	Origin information copied into the export.

Attributes

model_config class-attribute instance-attribute

model_config = ConfigDict(arbitrary_types_allowed=True)

format_name class-attribute instance-attribute

format_name: ExporterKind = MUJOCO_NPZ

output_path instance-attribute

output_path: Path

output_fps class-attribute instance-attribute

output_fps: int | None = None

kinematics_backend class-attribute instance-attribute

kinematics_backend: KinematicsBackend | None = None

provenance class-attribute instance-attribute

provenance: dict[str, Any] = Field(default_factory=dict)

GeometryDistance dataclass

GeometryDistance(
    first: str,
    second: str,
    distance: float,
    point_on_first: NDArray[float64],
    point_on_second: NDArray[float64],
    normal_from_first_to_second: NDArray[float64],
)

Signed or unsigned distance between two geometry-like objects.

Negative distances indicate overlap when the backend can compute signed separation. Backends that only expose point distances should return non-negative values.

Attributes:

Name	Type	Description
first	str	Name of the first body or collision geometry.
second	str	Name of the second body or collision geometry.
distance	float	Separation along normal_from_first_to_second (negative if overlapping).
point_on_first	NDArray[float64]	Closest point on first, shape (3,).
point_on_second	NDArray[float64]	Closest point on second, shape (3,).
normal_from_first_to_second	NDArray[float64]	Unit normal pointing from first to second.

Attributes

first instance-attribute

first: str

second instance-attribute

second: str

distance instance-attribute

distance: float

point_on_first instance-attribute

point_on_first: NDArray[float64]

point_on_second instance-attribute

point_on_second: NDArray[float64]

normal_from_first_to_second instance-attribute

normal_from_first_to_second: NDArray[float64]

GeometryDistanceJacobian dataclass

GeometryDistanceJacobian(distance: GeometryDistance, jacobian: NDArray[float64])

Linearized distance row for a geometry pair.

Attributes:

Name	Type	Description
distance	GeometryDistance	Pair distance and closest-point data.
jacobian	NDArray[float64]	Derivative of distance with respect to the active qpos variable set, shape (variables,).

Attributes

distance instance-attribute

distance: GeometryDistance

jacobian instance-attribute

jacobian: NDArray[float64]

InteractionMeshBuilder

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 spec is omitted.	None
k_neighbors	int | None	Neighbor count for K_NEAREST topology.	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

spec instance-attribute

spec = InteractionMeshSpec(
    topology=resolved_topology,
    k_neighbors=k_neighbors if k_neighbors is not None else 4,
)

Functions

build

build(
    human_points: FloatArray, environment_points: FloatArray | None = None
) -> InteractionMesh

Build an interaction mesh from human and optional environment points.

Parameters:

Name	Type	Description	Default
human_points	FloatArray	Body or joint sample sites with shape (N, 3).	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.

InteractionMeshSpec

Bases: BaseModel

Configuration for interaction mesh construction.

Attributes:

Name	Type	Description
topology	MeshTopology	Graph construction policy.
k_neighbors	int	Neighbor count when topology is K_NEAREST or Delaunay fallback.
laplacian_weighting	LaplacianWeighting	Neighbor weighting used by Laplacian objectives.
laplacian_epsilon	float	Small positive value used by distance-weighted Laplacians.

Attributes

model_config class-attribute instance-attribute

model_config = ConfigDict(extra='forbid')

topology class-attribute instance-attribute

topology: MeshTopology = DELAUNAY

k_neighbors class-attribute instance-attribute

k_neighbors: int = 4

laplacian_weighting class-attribute instance-attribute

laplacian_weighting: LaplacianWeighting = UNIFORM

laplacian_epsilon class-attribute instance-attribute

laplacian_epsilon: float = 1e-06

LaplacianWeighting

Bases: StrEnum

Neighbor weighting policy for Laplacian coordinates.

Attributes:

Name	Type	Description
UNIFORM	str	Average all neighbors equally. This matches Holosoma's default.
INVERSE_DISTANCE	str	Weight closer neighbors more strongly.

UNIFORM member

UNIFORM = 'uniform'

INVERSE_DISTANCE member

INVERSE_DISTANCE = 'inverse_distance'

MeshTopology

Bases: StrEnum

Interaction mesh topology policy.

Attributes:

Name	Type	Description
DELAUNAY	str	Delaunay triangulation over mesh sites.
CHAIN	str	Open chain along ordered sites.
COMPLETE	str	Fully connected graph.
K_NEAREST	str	k-nearest-neighbor edges (uses k_neighbors).

DELAUNAY member

DELAUNAY = 'delaunay'

CHAIN member

CHAIN = 'chain'

COMPLETE member

COMPLETE = 'complete'

K_NEAREST member

K_NEAREST = 'k_nearest'

ContactFrame dataclass

ContactFrame(
    frame_idx: int,
    tracks: tuple[ContactTrack[SubjectT, StateT, PatchT, LinkT], ...],
    support: SupportPlane | None = None,
)

Bases: Generic[SubjectT, StateT, PatchT, LinkT]

Per-frame view of a :class:ContactPlan.

Attributes:

Name	Type	Description
frame_idx	int
tracks	tuple[ContactTrack[SubjectT, StateT, PatchT, LinkT], ...]
support	SupportPlane | None
active_tracks	tuple[ContactTrack[SubjectT, StateT, PatchT, LinkT], ...]	Tracks active at this frame.
support_tracks	tuple[ContactTrack[SubjectT, StateT, PatchT, LinkT], ...]	Tracks touching support at this frame.
active_links	tuple[LinkT, ...]	Typed robot links mapped to active tracks.
support_links	tuple[LinkT, ...]	Typed robot links mapped to support tracks.

Attributes

frame_idx instance-attribute

frame_idx: int

tracks instance-attribute

tracks: tuple[ContactTrack[SubjectT, StateT, PatchT, LinkT], ...]

support class-attribute instance-attribute

support: SupportPlane | None = None

active_tracks property

active_tracks: tuple[ContactTrack[SubjectT, StateT, PatchT, LinkT], ...]

Tracks active at this frame.

support_tracks property

support_tracks: tuple[ContactTrack[SubjectT, StateT, PatchT, LinkT], ...]

Tracks touching support at this frame.

active_links property

active_links: tuple[LinkT, ...]

Typed robot links mapped to active tracks.

support_links property

support_links: tuple[LinkT, ...]

Typed robot links mapped to support tracks.

ContactPlan dataclass

ContactPlan(
    tracks: tuple[ContactTrack[SubjectT, StateT, PatchT, LinkT], ...],
    frame_count: int | None = None,
    support: SupportPlane | None = None,
    provenance: dict[str, object] = dict(),
)

Bases: Generic[SubjectT, StateT, PatchT, LinkT]

Typed contact states and support geometry for a retargeting problem.

Methods:

Name	Description
frame	Return a per-frame view.
resampled	Nearest-neighbor resample contact states.
scaled	Return a copy with positional support geometry scaled.

Attributes:

Name	Type	Description
tracks	tuple[ContactTrack[SubjectT, StateT, PatchT, LinkT], ...]
frame_count	int | None
support	SupportPlane | None
provenance	dict[str, object]

Attributes

tracks instance-attribute

tracks: tuple[ContactTrack[SubjectT, StateT, PatchT, LinkT], ...]

frame_count class-attribute instance-attribute

frame_count: int | None = None

support class-attribute instance-attribute

support: SupportPlane | None = None

provenance class-attribute instance-attribute

provenance: dict[str, object] = field(default_factory=dict)

Functions

frame

frame(frame_idx: int) -> ContactFrame[SubjectT, StateT, PatchT, LinkT]

Return a per-frame view.

resampled

resampled(
    source_fps: float, target_fps: float
) -> ContactPlan[SubjectT, StateT, PatchT, LinkT]

Nearest-neighbor resample contact states.

scaled

scaled(factor: float) -> ContactPlan[SubjectT, StateT, PatchT, LinkT]

Return a copy with positional support geometry scaled.

ContactTrack dataclass

ContactTrack(
    subject: SubjectT,
    states: tuple[StateT, ...],
    links: tuple[LinkT, ...],
    patch: PatchT | None = None,
    active_states: tuple[StateT, ...] = (),
    support_states: tuple[StateT, ...] = (),
    validity: ndarray | None = None,
    provenance: dict[str, object] = dict(),
)

Bases: Generic[SubjectT, StateT, PatchT, LinkT]

One semantic subject's typed contact state over time.

Methods:

Name	Description
active_at	Whether this subject is active at one frame.
support_at	Whether this subject touches support geometry at one frame.
resampled_indices	Return a copy sampled at nearest-neighbor indices.

Attributes:

Name	Type	Description
subject	SubjectT
states	tuple[StateT, ...]
links	tuple[LinkT, ...]
patch	PatchT | None
active_states	tuple[StateT, ...]
support_states	tuple[StateT, ...]
validity	ndarray | None
provenance	dict[str, object]
frame_count	int	Number of frames.
active_mask	ndarray	Valid frames whose state is active.
support_mask	ndarray	Valid frames whose state touches support geometry.

Attributes

subject instance-attribute

subject: SubjectT

states instance-attribute

states: tuple[StateT, ...]

links instance-attribute

links: tuple[LinkT, ...]

patch class-attribute instance-attribute

patch: PatchT | None = None

active_states class-attribute instance-attribute

active_states: tuple[StateT, ...] = ()

support_states class-attribute instance-attribute

support_states: tuple[StateT, ...] = ()

validity class-attribute instance-attribute

validity: ndarray | None = None

provenance class-attribute instance-attribute

provenance: dict[str, object] = field(default_factory=dict)

frame_count property

frame_count: int

Number of frames.

active_mask property

active_mask: ndarray

Valid frames whose state is active.

support_mask property

support_mask: ndarray

Valid frames whose state touches support geometry.

Functions

active_at

active_at(frame_idx: int) -> bool

Whether this subject is active at one frame.

support_at

support_at(frame_idx: int) -> bool

Whether this subject touches support geometry at one frame.

resampled_indices

resampled_indices(indices: ndarray) -> ContactTrack[SubjectT, StateT, PatchT, LinkT]

Return a copy sampled at nearest-neighbor indices.

LafanMotionJoint

Bases: MotionJoint

Attributes:

Name	Type	Description
HIPS
RIGHT_UP_LEG
RIGHT_LEG
RIGHT_FOOT
RIGHT_TOE_BASE
LEFT_UP_LEG
LEFT_LEG
LEFT_FOOT
LEFT_TOE_BASE
SPINE
SPINE1
SPINE2
NECK
HEAD
RIGHT_ARM
RIGHT_FORE_ARM
RIGHT_HAND
LEFT_ARM
LEFT_FORE_ARM
LEFT_HAND

Attributes

HIPS class-attribute instance-attribute

HIPS = 'Hips'

RIGHT_UP_LEG class-attribute instance-attribute

RIGHT_UP_LEG = 'RightUpLeg'

RIGHT_LEG class-attribute instance-attribute

RIGHT_LEG = 'RightLeg'

RIGHT_FOOT class-attribute instance-attribute

RIGHT_FOOT = 'RightFoot'

RIGHT_TOE_BASE class-attribute instance-attribute

RIGHT_TOE_BASE = 'RightToeBase'

LEFT_UP_LEG class-attribute instance-attribute

LEFT_UP_LEG = 'LeftUpLeg'

LEFT_LEG class-attribute instance-attribute

LEFT_LEG = 'LeftLeg'

LEFT_FOOT class-attribute instance-attribute

LEFT_FOOT = 'LeftFoot'

LEFT_TOE_BASE class-attribute instance-attribute

LEFT_TOE_BASE = 'LeftToeBase'

SPINE class-attribute instance-attribute

SPINE = 'Spine'

SPINE1 class-attribute instance-attribute

SPINE1 = 'Spine1'

SPINE2 class-attribute instance-attribute

SPINE2 = 'Spine2'

NECK class-attribute instance-attribute

NECK = 'Neck'

HEAD class-attribute instance-attribute

HEAD = 'Head'

RIGHT_ARM class-attribute instance-attribute

RIGHT_ARM = 'RightArm'

RIGHT_FORE_ARM class-attribute instance-attribute

RIGHT_FORE_ARM = 'RightForeArm'

RIGHT_HAND class-attribute instance-attribute

RIGHT_HAND = 'RightHand'

LEFT_ARM class-attribute instance-attribute

LEFT_ARM = 'LeftArm'

LEFT_FORE_ARM class-attribute instance-attribute

LEFT_FORE_ARM = 'LeftForeArm'

LEFT_HAND class-attribute instance-attribute

LEFT_HAND = 'LeftHand'

LinkTargetPlan dataclass

LinkTargetPlan(
    tracks: tuple[LinkTargetTrack[LinkT], ...],
    frame_count: int | None = None,
    provenance: dict[str, object] = dict(),
)

Bases: Generic[LinkT]

Validated frame-aligned targets using one robot-link vocabulary.

Methods:

Name	Description
frame	Return a per-frame target view.
resampled	Return nearest-neighbor/masked targets on a new time grid.
scaled	Return a copy with all positions scaled.
to_frame	Return this target plan represented in another frame.
from_arrays	Build target tracks from dense (frames, links, 3) arrays.

Attributes:

Name	Type	Description
tracks	tuple[LinkTargetTrack[LinkT], ...]
frame_count	int | None
provenance	dict[str, object]
links	tuple[LinkT, ...]	Robot links targeted by this plan.

Attributes

tracks instance-attribute

tracks: tuple[LinkTargetTrack[LinkT], ...]

frame_count class-attribute instance-attribute

frame_count: int | None = None

provenance class-attribute instance-attribute

provenance: dict[str, object] = field(default_factory=dict)

links property

links: tuple[LinkT, ...]

Robot links targeted by this plan.

Functions

frame

frame(frame_idx: int) -> TargetFrame[LinkT]

Return a per-frame target view.

resampled

resampled(source_fps: float, target_fps: float) -> LinkTargetPlan[LinkT]

Return nearest-neighbor/masked targets on a new time grid.

scaled

scaled(factor: float) -> LinkTargetPlan[LinkT]

Return a copy with all positions scaled.

to_frame

to_frame(source: FrameConvention, target: FrameConvention) -> LinkTargetPlan[LinkT]

Return this target plan represented in another frame.

from_arrays classmethod

from_arrays(
    *,
    links: tuple[LinkT, ...],
    positions: ArrayLike,
    weights: ArrayLike | float = 1.0,
    active_mask: ArrayLike | None = None,
    provenance: Mapping[str, object] | None = None,
) -> LinkTargetPlan[LinkT]

Build target tracks from dense (frames, links, 3) arrays.

LinkTargetSample dataclass

LinkTargetSample(
    link: LinkT,
    position: FloatArray,
    weight: float,
    provenance: dict[str, object] = dict(),
)

Bases: Generic[LinkT]

One active typed robot-link target at one frame.

Attributes:

Name	Type	Description
link	LinkT
position	FloatArray
weight	float
provenance	dict[str, object]

Attributes

link instance-attribute

link: LinkT

position instance-attribute

position: FloatArray

weight instance-attribute

weight: float

provenance class-attribute instance-attribute

provenance: dict[str, object] = field(default_factory=dict)

LinkTargetTrack dataclass

LinkTargetTrack(
    link: LinkT,
    positions: FloatArray,
    weights: FloatArray | float = 1.0,
    active_mask: ndarray | None = None,
    provenance: dict[str, object] = dict(),
)

Bases: Generic[LinkT]

World-space target trajectory for one typed robot link.

Methods:

Name	Description
active_at	Whether this target is active and finite.
sample	Return the sample for one frame when active.
resampled_indices	Return a copy sampled at frame indices.
scaled	Return a copy with positions scaled.
to_frame	Return this track represented in another coordinate frame.

Attributes:

Name	Type	Description
link	LinkT
positions	FloatArray
weights	FloatArray | float
active_mask	ndarray | None
provenance	dict[str, object]
frame_count	int	Number of frames.

Attributes

link instance-attribute

link: LinkT

positions instance-attribute

positions: FloatArray

weights class-attribute instance-attribute

weights: FloatArray | float = 1.0

active_mask class-attribute instance-attribute

active_mask: ndarray | None = None

provenance class-attribute instance-attribute

provenance: dict[str, object] = field(default_factory=dict)

frame_count property

frame_count: int

Number of frames.

Functions

active_at

active_at(frame_idx: int) -> bool

Whether this target is active and finite.

sample

sample(frame_idx: int) -> LinkTargetSample[LinkT] | None

Return the sample for one frame when active.

resampled_indices

resampled_indices(indices: ndarray) -> LinkTargetTrack[LinkT]

Return a copy sampled at frame indices.

scaled

scaled(factor: float) -> LinkTargetTrack[LinkT]

Return a copy with positions scaled.

to_frame

to_frame(source: FrameConvention, target: FrameConvention) -> LinkTargetTrack[LinkT]

Return this track represented in another coordinate frame.

MinimalMotionJoint

Bases: MotionJoint

Attributes:

Name	Type	Description
PELVIS
LEFT_HIP
LEFT_KNEE
LEFT_TOE
RIGHT_HIP
RIGHT_KNEE
RIGHT_TOE
SPINE
HEAD
LEFT_WRIST
RIGHT_WRIST

Attributes

PELVIS class-attribute instance-attribute

PELVIS = 'Pelvis'

LEFT_HIP class-attribute instance-attribute

LEFT_HIP = 'L_Hip'

LEFT_KNEE class-attribute instance-attribute

LEFT_KNEE = 'L_Knee'

LEFT_TOE class-attribute instance-attribute

LEFT_TOE = 'L_Toe'

RIGHT_HIP class-attribute instance-attribute

RIGHT_HIP = 'R_Hip'

RIGHT_KNEE class-attribute instance-attribute

RIGHT_KNEE = 'R_Knee'

RIGHT_TOE class-attribute instance-attribute

RIGHT_TOE = 'R_Toe'

SPINE class-attribute instance-attribute

SPINE = 'Spine'

HEAD class-attribute instance-attribute

HEAD = 'Head'

LEFT_WRIST class-attribute instance-attribute

LEFT_WRIST = 'L_Wrist'

RIGHT_WRIST class-attribute instance-attribute

RIGHT_WRIST = 'R_Wrist'

MocapMotionJoint

Bases: MotionJoint

Attributes:

Name	Type	Description
HIPS
SPINE
SPINE1
NECK
HEAD
LEFT_ARM
LEFT_FORE_ARM
LEFT_HAND
LEFT_HAND_MIDDLE3
RIGHT_ARM
RIGHT_FORE_ARM
RIGHT_HAND
RIGHT_HAND_MIDDLE3
LEFT_UP_LEG
LEFT_LEG
LEFT_FOOT
LEFT_TOE_BASE
RIGHT_UP_LEG
RIGHT_LEG
RIGHT_FOOT
RIGHT_TOE_BASE

Attributes

HIPS class-attribute instance-attribute

HIPS = 'Hips'

SPINE class-attribute instance-attribute

SPINE = 'Spine'

SPINE1 class-attribute instance-attribute

SPINE1 = 'Spine1'

NECK class-attribute instance-attribute

NECK = 'Neck'

HEAD class-attribute instance-attribute

HEAD = 'Head'

LEFT_ARM class-attribute instance-attribute

LEFT_ARM = 'LeftArm'

LEFT_FORE_ARM class-attribute instance-attribute

LEFT_FORE_ARM = 'LeftForeArm'

LEFT_HAND class-attribute instance-attribute

LEFT_HAND = 'LeftHand'

LEFT_HAND_MIDDLE3 class-attribute instance-attribute

LEFT_HAND_MIDDLE3 = 'LeftHandMiddle3'

RIGHT_ARM class-attribute instance-attribute

RIGHT_ARM = 'RightArm'

RIGHT_FORE_ARM class-attribute instance-attribute

RIGHT_FORE_ARM = 'RightForeArm'

RIGHT_HAND class-attribute instance-attribute

RIGHT_HAND = 'RightHand'

RIGHT_HAND_MIDDLE3 class-attribute instance-attribute

RIGHT_HAND_MIDDLE3 = 'RightHandMiddle3'

LEFT_UP_LEG class-attribute instance-attribute

LEFT_UP_LEG = 'LeftUpLeg'

LEFT_LEG class-attribute instance-attribute

LEFT_LEG = 'LeftLeg'

LEFT_FOOT class-attribute instance-attribute

LEFT_FOOT = 'LeftFoot'

LEFT_TOE_BASE class-attribute instance-attribute

LEFT_TOE_BASE = 'LeftToeBase'

RIGHT_UP_LEG class-attribute instance-attribute

RIGHT_UP_LEG = 'RightUpLeg'

RIGHT_LEG class-attribute instance-attribute

RIGHT_LEG = 'RightLeg'

RIGHT_FOOT class-attribute instance-attribute

RIGHT_FOOT = 'RightFoot'

RIGHT_TOE_BASE class-attribute instance-attribute

RIGHT_TOE_BASE = 'RightToeBase'

NominalQposFrame dataclass

NominalQposFrame(frame_idx: int, plan: NominalQposPlan)

Per-frame view of a nominal qpos trajectory.

Methods:

Name	Description
active_at	Whether one qpos coordinate has a finite active nominal target.

Attributes:

Name	Type	Description
frame_idx	int
plan	NominalQposPlan
qpos	FloatArray	Nominal qpos values for this frame.
weights	FloatArray	Per-qpos nominal weights for this frame.
active_mask	ndarray	Per-qpos activity mask for this frame.

Attributes

frame_idx instance-attribute

frame_idx: int

plan instance-attribute

plan: NominalQposPlan

qpos property

qpos: FloatArray

Nominal qpos values for this frame.

weights property

weights: FloatArray

Per-qpos nominal weights for this frame.

active_mask property

active_mask: ndarray

Per-qpos activity mask for this frame.

Functions

active_at

active_at(qpos_index: int) -> bool

Whether one qpos coordinate has a finite active nominal target.

NominalQposPlan dataclass

NominalQposPlan(
    qpos: FloatArray,
    weights: FloatArray | float = 1.0,
    active_mask: ndarray | None = None,
    provenance: dict[str, object] = dict(),
)

Frame-aligned nominal generalized-coordinate trajectory.

Unlike link targets, qpos targets are robot-configuration values. They are resampled in time, but are not spatially scaled with source motion.

Methods:

Name	Description
frame	Return a per-frame nominal-qpos view.
resampled	Return nearest-neighbor nominal qpos on a new time grid.
resampled_indices	Return a copy sampled at frame indices.
with_provenance	Return a copy with additional JSON-safe provenance.
from_array	Build a nominal qpos plan from dense arrays.

Attributes:

Name	Type	Description
qpos	FloatArray
weights	FloatArray | float
active_mask	ndarray | None
provenance	dict[str, object]
frame_count	int	Number of frames in the plan.
qpos_size	int	Number of generalized coordinates in each frame.

Attributes

qpos instance-attribute

qpos: FloatArray

weights class-attribute instance-attribute

weights: FloatArray | float = 1.0

active_mask class-attribute instance-attribute

active_mask: ndarray | None = None

provenance class-attribute instance-attribute

provenance: dict[str, object] = field(default_factory=dict)

frame_count property

frame_count: int

Number of frames in the plan.

qpos_size property

qpos_size: int

Number of generalized coordinates in each frame.

Functions

frame

frame(frame_idx: int) -> NominalQposFrame

Return a per-frame nominal-qpos view.

resampled

resampled(source_fps: float, target_fps: float) -> NominalQposPlan

Return nearest-neighbor nominal qpos on a new time grid.

resampled_indices

resampled_indices(indices: ndarray) -> NominalQposPlan

Return a copy sampled at frame indices.

with_provenance

with_provenance(**items: object) -> NominalQposPlan

Return a copy with additional JSON-safe provenance.

from_array classmethod

from_array(
    qpos: ArrayLike,
    *,
    weights: ArrayLike | float = 1.0,
    active_mask: ArrayLike | None = None,
    provenance: Mapping[str, object] | None = None,
) -> NominalQposPlan

Build a nominal qpos plan from dense arrays.

SmplhMotionJoint

Bases: MotionJoint

Attributes:

Name	Type	Description
PELVIS
LEFT_HIP
LEFT_KNEE
LEFT_ANKLE
LEFT_TOE
RIGHT_HIP
RIGHT_KNEE
RIGHT_ANKLE
RIGHT_TOE
TORSO
SPINE
CHEST
NECK
HEAD
LEFT_SHOULDER
LEFT_ELBOW
LEFT_WRIST
RIGHT_SHOULDER
RIGHT_ELBOW
RIGHT_WRIST

Attributes

PELVIS class-attribute instance-attribute

PELVIS = 'Pelvis'

LEFT_HIP class-attribute instance-attribute

LEFT_HIP = 'L_Hip'

LEFT_KNEE class-attribute instance-attribute

LEFT_KNEE = 'L_Knee'

LEFT_ANKLE class-attribute instance-attribute

LEFT_ANKLE = 'L_Ankle'

LEFT_TOE class-attribute instance-attribute

LEFT_TOE = 'L_Toe'

RIGHT_HIP class-attribute instance-attribute

RIGHT_HIP = 'R_Hip'

RIGHT_KNEE class-attribute instance-attribute

RIGHT_KNEE = 'R_Knee'

RIGHT_ANKLE class-attribute instance-attribute

RIGHT_ANKLE = 'R_Ankle'

RIGHT_TOE class-attribute instance-attribute

RIGHT_TOE = 'R_Toe'

TORSO class-attribute instance-attribute

TORSO = 'Torso'

SPINE class-attribute instance-attribute

SPINE = 'Spine'

CHEST class-attribute instance-attribute

CHEST = 'Chest'

NECK class-attribute instance-attribute

NECK = 'Neck'

HEAD class-attribute instance-attribute

HEAD = 'Head'

LEFT_SHOULDER class-attribute instance-attribute

LEFT_SHOULDER = 'L_Shoulder'

LEFT_ELBOW class-attribute instance-attribute

LEFT_ELBOW = 'L_Elbow'

LEFT_WRIST class-attribute instance-attribute

LEFT_WRIST = 'L_Wrist'

RIGHT_SHOULDER class-attribute instance-attribute

RIGHT_SHOULDER = 'R_Shoulder'

RIGHT_ELBOW class-attribute instance-attribute

RIGHT_ELBOW = 'R_Elbow'

RIGHT_WRIST class-attribute instance-attribute

RIGHT_WRIST = 'R_Wrist'

SmplxMotionJoint

Bases: MotionJoint

Attributes:

Name	Type	Description
PELVIS
LEFT_HIP
RIGHT_HIP
SPINE1
LEFT_KNEE
RIGHT_KNEE
SPINE2
LEFT_ANKLE
RIGHT_ANKLE
SPINE3
LEFT_FOOT
RIGHT_FOOT
NECK
HEAD
LEFT_SHOULDER
RIGHT_SHOULDER
LEFT_ELBOW
RIGHT_ELBOW
LEFT_WRIST
RIGHT_WRIST

Attributes

PELVIS class-attribute instance-attribute

PELVIS = 'Pelvis'

LEFT_HIP class-attribute instance-attribute

LEFT_HIP = 'L_Hip'

RIGHT_HIP class-attribute instance-attribute

RIGHT_HIP = 'R_Hip'

SPINE1 class-attribute instance-attribute

SPINE1 = 'Spine1'

LEFT_KNEE class-attribute instance-attribute

LEFT_KNEE = 'L_Knee'

RIGHT_KNEE class-attribute instance-attribute

RIGHT_KNEE = 'R_Knee'

SPINE2 class-attribute instance-attribute

SPINE2 = 'Spine2'

LEFT_ANKLE class-attribute instance-attribute

LEFT_ANKLE = 'L_Ankle'

RIGHT_ANKLE class-attribute instance-attribute

RIGHT_ANKLE = 'R_Ankle'

SPINE3 class-attribute instance-attribute

SPINE3 = 'Spine3'

LEFT_FOOT class-attribute instance-attribute

LEFT_FOOT = 'L_Foot'

RIGHT_FOOT class-attribute instance-attribute

RIGHT_FOOT = 'R_Foot'

NECK class-attribute instance-attribute

NECK = 'Neck'

HEAD class-attribute instance-attribute

HEAD = 'Head'

LEFT_SHOULDER class-attribute instance-attribute

LEFT_SHOULDER = 'L_Shoulder'

RIGHT_SHOULDER class-attribute instance-attribute

RIGHT_SHOULDER = 'R_Shoulder'

LEFT_ELBOW class-attribute instance-attribute

LEFT_ELBOW = 'L_Elbow'

RIGHT_ELBOW class-attribute instance-attribute

RIGHT_ELBOW = 'R_Elbow'

LEFT_WRIST class-attribute instance-attribute

LEFT_WRIST = 'L_Wrist'

RIGHT_WRIST class-attribute instance-attribute

RIGHT_WRIST = 'R_Wrist'

SupportPlane

SupportPlane(normal: ArrayLike, origin: ArrayLike, up_axis: int = 2)

Planar support surface used by contact-aware terms.

Methods:

Name	Description
clearance	Signed clearance from the support plane.
height_at	Support height at the horizontal coordinates of points.
scaled	Return a copy with positional quantities scaled.
to_frame	Return this support plane represented in another frame convention.

Attributes:

Name	Type	Description
normal	FloatArray
origin	FloatArray
up_axis	int

Attributes

normal instance-attribute

normal: FloatArray = normal_array / norm

origin instance-attribute

origin: FloatArray = origin_array

up_axis instance-attribute

up_axis: int = int(up_axis)

Functions

clearance

clearance(points: ArrayLike) -> FloatArray

Signed clearance from the support plane.

height_at

height_at(points: ArrayLike) -> FloatArray

Support height at the horizontal coordinates of points.

scaled

scaled(factor: float) -> SupportPlane

Return a copy with positional quantities scaled.

to_frame

to_frame(source: FrameConvention, target: FrameConvention) -> SupportPlane

Return this support plane represented in another frame convention.

TargetFrame dataclass

TargetFrame(frame_idx: int, tracks: tuple[LinkTargetTrack[LinkT], ...])

Bases: Generic[LinkT]

Per-frame view of link targets.

Attributes:

Name	Type	Description
frame_idx	int
tracks	tuple[LinkTargetTrack[LinkT], ...]
samples	tuple[LinkTargetSample[LinkT], ...]	Active target samples at this frame.
links	tuple[LinkT, ...]	Active typed robot links.
positions	FloatArray	Active target positions.
weights	FloatArray	Active target weights.

Attributes

frame_idx instance-attribute

frame_idx: int

tracks instance-attribute

tracks: tuple[LinkTargetTrack[LinkT], ...]

samples property

samples: tuple[LinkTargetSample[LinkT], ...]

Active target samples at this frame.

links property

links: tuple[LinkT, ...]

Active typed robot links.

positions property

positions: FloatArray

Active target positions.

weights property

weights: FloatArray

Active target weights.

MotionFormatSpec

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

model_config class-attribute instance-attribute

model_config = ConfigDict(arbitrary_types_allowed=True)

name instance-attribute

name: str

joint_vocabulary instance-attribute

joint_vocabulary: type[JointT]

root_joint instance-attribute

root_joint: JointT

quaternion_order class-attribute instance-attribute

quaternion_order: QuaternionOrder = WXYZ

frame_convention class-attribute instance-attribute

frame_convention: FrameConvention = Z_UP_RIGHT_HANDED

default_fps class-attribute instance-attribute

default_fps: float = 30.0

default_height_m class-attribute instance-attribute

default_height_m: float | None = None

description class-attribute instance-attribute

description: str = ''

joints property

joints: tuple[JointT, ...]

Ordered joints declared by this format.

Functions

joint_index

joint_index(joint: JointT) -> int

Return the index of a typed joint.

MotionSequence

Bases: BaseModel, Generic[JointT]

Canonical shared-timeline actor motion with a concrete joint vocabulary.

Methods:

Name	Description
joint_index	Return the index of a typed joint.
joint	Return positions for one joint with shape (samples, 3).
with_positions	Return a copy with replacement joint positions.
scaled	Return a spatially scaled copy.
resampled	Return this motion sampled on a uniform timeline.
to_frame	Return this motion represented in another coordinate frame.
centered_on_root	Return a sequence translated so root_joint begins at the origin.
zeros	Create a zero-valued fixture motion.

Attributes:

Name	Type	Description
model_config
name	str
joint_vocabulary	type[JointT]
joints	tuple[JointT, ...]
root_joint	JointT
joint_positions	FloatArray
timeline	SampleTimeline
frame	FrameConvention
root_poses	PoseSequence | None
source_height_m	float | None
provenance	dict[str, Any]
frame_count	int	Number of samples.
joint_count	int	Number of joints.
fps	float	Nominal sampling rate.
duration_s	float	Duration between the first and last samples.

Attributes

model_config class-attribute instance-attribute

model_config = ConfigDict(arbitrary_types_allowed=True)

name instance-attribute

name: str

joint_vocabulary instance-attribute

joint_vocabulary: type[JointT]

joints instance-attribute

joints: tuple[JointT, ...]

root_joint instance-attribute

root_joint: JointT

joint_positions instance-attribute

joint_positions: FloatArray

timeline instance-attribute

timeline: SampleTimeline

frame class-attribute instance-attribute

frame: FrameConvention = Z_UP_RIGHT_HANDED

root_poses class-attribute instance-attribute

root_poses: PoseSequence | None = None

source_height_m class-attribute instance-attribute

source_height_m: float | None = None

provenance class-attribute instance-attribute

provenance: dict[str, Any] = Field(default_factory=dict)

frame_count property

frame_count: int

Number of samples.

joint_count property

joint_count: int

Number of joints.

fps property

fps: float

Nominal sampling rate.

duration_s property

duration_s: float

Duration between the first and last samples.

Functions

joint_index

joint_index(joint: JointT) -> int

Return the index of a typed joint.

joint

joint(joint: JointT) -> FloatArray

Return positions for one joint with shape (samples, 3).

with_positions

with_positions(
    positions: FloatArray | ArrayLike, *, name: str | None = None
) -> MotionSequence[JointT]

Return a copy with replacement joint positions.

scaled

scaled(factor: float, *, name: str | None = None) -> MotionSequence[JointT]

Return a spatially scaled copy.

resampled

resampled(fps: float, *, name: str | None = None) -> MotionSequence[JointT]

Return this motion sampled on a uniform timeline.

to_frame

to_frame(target: FrameConvention, *, name: str | None = None) -> MotionSequence[JointT]

Return this motion represented in another coordinate frame.

centered_on_root

centered_on_root(root_joint: JointT) -> MotionSequence[JointT]

Return a sequence translated so root_joint begins at the origin.

zeros classmethod

zeros(
    name: str,
    *,
    joint_vocabulary: type[JointT],
    joints: tuple[JointT, ...],
    root_joint: JointT,
    frame_count: int,
    fps: float = 30.0,
    frame: FrameConvention = Z_UP_RIGHT_HANDED,
) -> MotionSequence[JointT]

Create a zero-valued fixture motion.

FootSupportClassificationConfig dataclass

FootSupportClassificationConfig(
    ground_height_percentile: float = 8.0,
    ground_clearance_m: float = 0.035,
    ground_speed_mps: float = 0.18,
    object_horizontal_distance_m: float = 0.35,
    object_height_min_m: float = 0.0,
    object_height_max_m: float = 0.14,
    object_relative_speed_mps: float = 0.15,
)

Thresholds for ground and moving-object foot support.

Attributes:

Name	Type	Description
ground_height_percentile	float
ground_clearance_m	float
ground_speed_mps	float
object_horizontal_distance_m	float
object_height_min_m	float
object_height_max_m	float
object_relative_speed_mps	float

Attributes

ground_height_percentile class-attribute instance-attribute

ground_height_percentile: float = 8.0

ground_clearance_m class-attribute instance-attribute

ground_clearance_m: float = 0.035

ground_speed_mps class-attribute instance-attribute

ground_speed_mps: float = 0.18

object_horizontal_distance_m class-attribute instance-attribute

object_horizontal_distance_m: float = 0.35

object_height_min_m class-attribute instance-attribute

object_height_min_m: float = 0.0

object_height_max_m class-attribute instance-attribute

object_height_max_m: float = 0.14

object_relative_speed_mps class-attribute instance-attribute

object_relative_speed_mps: float = 0.15

FootSupportStates dataclass

FootSupportStates(
    air: ContactState, ground: ContactState, observed_object: ContactState
)

Typed categorical values emitted by support classification.

Attributes:

Name	Type	Description
air	ContactState
ground	ContactState
observed_object	ContactState

Attributes

air instance-attribute

air: ContactState

ground instance-attribute

ground: ContactState

observed_object instance-attribute

observed_object: ContactState

ObservedObject 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]

Attributes

role instance-attribute

role: ObservationRole

pose instance-attribute

pose: PoseTrack

geometry instance-attribute

geometry: ObjectSpec

provenance class-attribute instance-attribute

provenance: dict[str, object] = field(default_factory=dict)

SceneObservation 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

name instance-attribute

name: str

timeline instance-attribute

timeline: SampleTimeline

world_frame instance-attribute

world_frame: FrameConvention

actor instance-attribute

actor: MotionSequence[Any]

landmarks class-attribute instance-attribute

landmarks: tuple[PointTrack, ...] = ()

rigid_bodies class-attribute instance-attribute

rigid_bodies: tuple[PoseTrack, ...] = ()

objects class-attribute instance-attribute

objects: tuple[ObservedObject, ...] = ()

contacts class-attribute instance-attribute

contacts: SemanticContactSequence | None = None

terrain class-attribute instance-attribute

terrain: TerrainSpec | None = None

alignment_reports class-attribute instance-attribute

alignment_reports: tuple[AlignmentReport, ...] = ()

provenance class-attribute instance-attribute

provenance: dict[str, object] = field(default_factory=dict)

Functions

landmark

landmark(role: ObservationRole) -> PointTrack

Return a semantic landmark track.

observed_object

observed_object(role: ObservationRole) -> ObservedObject

Return an observed object.

save_npz

save_npz(path: str | Path) -> Path

Explicitly save this observation checkpoint without pickle.

load_npz classmethod

load_npz(path: str | Path) -> SceneObservation

Load an explicit observation checkpoint.

SemanticContactSequence 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

timeline instance-attribute

timeline: SampleTimeline

tracks instance-attribute

tracks: tuple[SemanticContactTrack, ...]

support class-attribute instance-attribute

support: SupportPlane | None = None

provenance class-attribute instance-attribute

provenance: dict[str, object] = field(default_factory=dict)

Functions

resolve

resolve(link_mapping: Mapping[ContactSubject, Sequence[RobotLink]]) -> ContactPlan

Resolve semantic subjects to concrete robot links.

SemanticContactTrack dataclass

SemanticContactTrack(
    subject: ContactSubject,
    states: tuple[ContactState, ...],
    patch: ContactPatch | None = None,
    active_states: tuple[ContactState, ...] = (),
    support_states: tuple[ContactState, ...] = (),
    validity: ndarray | None = None,
    provenance: dict[str, object] = dict(),
)

Categorical contact state for one observed subject and patch.

Attributes:

Name	Type	Description
subject	ContactSubject
states	tuple[ContactState, ...]
patch	ContactPatch | None
active_states	tuple[ContactState, ...]
support_states	tuple[ContactState, ...]
validity	ndarray | None
provenance	dict[str, object]
sample_count	int	Number of samples.

Attributes

subject instance-attribute

subject: ContactSubject

states instance-attribute

states: tuple[ContactState, ...]

patch class-attribute instance-attribute

patch: ContactPatch | None = None

active_states class-attribute instance-attribute

active_states: tuple[ContactState, ...] = ()

support_states class-attribute instance-attribute

support_states: tuple[ContactState, ...] = ()

validity class-attribute instance-attribute

validity: ndarray | None = None

provenance class-attribute instance-attribute

provenance: dict[str, object] = field(default_factory=dict)

sample_count property

sample_count: int

Number of samples.

ConstraintContribution dataclass

ConstraintContribution(
    lower: FloatArray | None = None,
    upper: FloatArray | None = None,
    trust_radius: float | None = None,
    linear_constraints: tuple[LinearConstraint, ...] = (),
)

Bounds and linear constraints from one constraint term.

Attributes:

Name	Type	Description
lower	FloatArray | None
upper	FloatArray | None
trust_radius	float | None
linear_constraints	tuple[LinearConstraint, ...]

Attributes

lower class-attribute instance-attribute

lower: FloatArray | None = None

upper class-attribute instance-attribute

upper: FloatArray | None = None

trust_radius class-attribute instance-attribute

trust_radius: float | None = None

linear_constraints class-attribute instance-attribute

linear_constraints: tuple[LinearConstraint, ...] = ()

ObjectiveContribution dataclass

ObjectiveContribution(matrix: FloatArray, target: FloatArray)

Least-squares contribution from one objective term.

The contribution is expressed as ||matrix @ dq - target||^2 where dq is the current subproblem's actuated-joint increment.

Attributes:

Name	Type	Description
matrix	FloatArray
target	FloatArray

Attributes

matrix instance-attribute

matrix: FloatArray

target instance-attribute

target: FloatArray

TermContext dataclass

TermContext(
    problem: AnyRetargetingProblem,
    compiled: CompiledRetargetingProblem,
    backend: KinematicsBackend,
    q_current: FloatArray,
    q_previous: FloatArray,
    frame_idx: int,
    contact_frame: CompiledContactFrame | None,
    target_frame: CompiledTargetFrame | None,
    robot_point_names: tuple[str, ...],
    robot_points: FloatArray,
    robot_jacobians: FloatArray,
    environment_points: FloatArray,
    adjacency: tuple[tuple[int, ...], ...],
    target_laplacian: FloatArray,
    laplacian_weighting: LaplacianWeighting,
    laplacian_epsilon: float,
    reference_pose: Pose | None,
    joint_lower: FloatArray,
    joint_upper: FloatArray,
    current_joints: FloatArray,
    variable_indices: NDArray[int64] | None = None,
    current_variables: FloatArray | None = None,
    variable_lower: FloatArray | None = None,
    variable_upper: FloatArray | None = None,
    nominal_qpos_frame: NominalQposFrame | None = None,
)

Per-frame data available to objective and constraint terms.

Terms operate on the actuated-joint increment for the current SQP subproblem. All point arrays and Jacobians are already represented in the local frame relevant to the current task, such as the object frame for dynamic object interaction.

Attributes:

Name	Type	Description
problem	RetargetingProblem	Parent run specification.
backend	KinematicsBackend	Kinematics provider for positions and Jacobians.
q_current	FloatArray	Full qpos vector for the frame being optimized.
q_previous	FloatArray	qpos from the prior frame (warm start for smoothness).
frame_idx	int	Zero-based index into the motion sequence.
contact_frame	ContactFrame | None	Typed contact view for the current frame, when configured.
target_frame	TargetFrame | None	Typed link-target view for the current frame, when configured.
robot_point_names	tuple[str, ...]	Link or joint names used for mesh matching.
robot_points	FloatArray	Robot match points in the task-local frame, shape (P, 3).
robot_jacobians	FloatArray	Position Jacobians w.r.t. active variables, shape (P, 3, dof).
environment_points	FloatArray	Scene or object sample points, shape (E, 3).
adjacency	tuple[tuple[int, ...], ...]	Mesh neighbor indices per vertex.
target_laplacian	FloatArray	Desired Laplacian coordinates for the interaction mesh.
laplacian_weighting	LaplacianWeighting	Neighbor weighting used by the current mesh builder.
laplacian_epsilon	float	Epsilon used by distance-weighted Laplacians.
reference_pose	Pose | None	Object pose for dynamic scenes; None in world frame.
joint_lower	FloatArray	Actuated joint lower limits for the current robot.
joint_upper	FloatArray	Actuated joint upper limits for the current robot.
current_joints	FloatArray	Actuated joint values extracted from q_current.
variable_indices	NDArray[int64] | None	Qpos indices for active optimization variables.
current_variables	FloatArray | None	Active qpos values extracted from q_current.
variable_lower	FloatArray | None	Absolute lower bounds for active qpos variables.
variable_upper	FloatArray | None	Absolute upper bounds for active qpos variables.
nominal_qpos_frame	NominalQposFrame | None	Optional nominal qpos target view.

Attributes

problem instance-attribute

problem: AnyRetargetingProblem

compiled instance-attribute

compiled: CompiledRetargetingProblem

backend instance-attribute

backend: KinematicsBackend

q_current instance-attribute

q_current: FloatArray

q_previous instance-attribute

q_previous: FloatArray

frame_idx instance-attribute

frame_idx: int

contact_frame instance-attribute

contact_frame: CompiledContactFrame | None

target_frame instance-attribute

target_frame: CompiledTargetFrame | None

robot_point_names instance-attribute

robot_point_names: tuple[str, ...]

robot_points instance-attribute

robot_points: FloatArray

robot_jacobians instance-attribute

robot_jacobians: FloatArray

environment_points instance-attribute

environment_points: FloatArray

adjacency instance-attribute

adjacency: tuple[tuple[int, ...], ...]

target_laplacian instance-attribute

target_laplacian: FloatArray

laplacian_weighting instance-attribute

laplacian_weighting: LaplacianWeighting

laplacian_epsilon instance-attribute

laplacian_epsilon: float

reference_pose instance-attribute

reference_pose: Pose | None

joint_lower instance-attribute

joint_lower: FloatArray

joint_upper instance-attribute

joint_upper: FloatArray

current_joints instance-attribute

current_joints: FloatArray

variable_indices class-attribute instance-attribute

variable_indices: NDArray[int64] | None = None

current_variables class-attribute instance-attribute

current_variables: FloatArray | None = None

variable_lower class-attribute instance-attribute

variable_lower: FloatArray | None = None

variable_upper class-attribute instance-attribute

variable_upper: FloatArray | None = None

nominal_qpos_frame class-attribute instance-attribute

nominal_qpos_frame: NominalQposFrame | None = None

dof property

dof: int

Number of coordinates in the subproblem variable.

active_qpos_indices property

active_qpos_indices: NDArray[int64]

Qpos indices represented by the current subproblem variable.

current_variable_values property

current_variable_values: FloatArray

Current values of active qpos variables.

variable_lower_bounds property

variable_lower_bounds: FloatArray

Absolute lower bounds for active qpos variables.

variable_upper_bounds property

variable_upper_bounds: FloatArray

Absolute upper bounds for active qpos variables.

ConstraintConfig

Bases: BaseModel

Base class for constraint configs keyed by an extensible enum member.

Methods:

Name	Description
with_enabled	Return a copy with a different enabled state.
disabled	Return a disabled copy.

Attributes:

Name	Type	Description
model_config
kind	ConstraintKind
enabled	bool

Attributes

model_config class-attribute instance-attribute

model_config = ConfigDict(extra='forbid', arbitrary_types_allowed=True)

kind class-attribute

kind: ConstraintKind

enabled class-attribute instance-attribute

enabled: bool = True

Functions

with_enabled

with_enabled(enabled: bool = True) -> Self

Return a copy with a different enabled state.

disabled

disabled() -> Self

Return a disabled copy.

DiagonalRegularizationObjectiveConfig

Bases: ObjectiveConfig

Penalize selected qpos variables toward zero with diagonal weights.

Attributes:

Name	Type	Description
kind
qpos_weights	tuple[float, ...]
variable_weights	tuple[float, ...]
qpos_weight_overrides	dict[int, float]

Attributes

kind class-attribute instance-attribute

kind = DIAGONAL_REGULARIZATION

qpos_weights class-attribute instance-attribute

qpos_weights: tuple[float, ...] = ()

variable_weights class-attribute instance-attribute

variable_weights: tuple[float, ...] = ()

qpos_weight_overrides class-attribute instance-attribute

qpos_weight_overrides: dict[int, float] = Field(default_factory=dict)

FootLockConstraintConfig

Bases: ConstraintConfig

Pin exact typed support links or subjects during configured windows.

Attributes:

Name	Type	Description
kind
windows	tuple[FootLockWindow, ...]
z_floor	float
tolerance	float

Attributes

kind class-attribute instance-attribute

kind = FOOT_LOCK

windows class-attribute instance-attribute

windows: tuple[FootLockWindow, ...] = ()

z_floor class-attribute instance-attribute

z_floor: float = 0.0

tolerance class-attribute instance-attribute

tolerance: float = 0.005

FootStickingConstraintConfig

Bases: ConstraintConfig

Constrain active support links near their previous tangent-plane position.

Attributes:

Name	Type	Description
kind
tolerance	float

Attributes

kind class-attribute instance-attribute

kind = FOOT_STICKING

tolerance class-attribute instance-attribute

tolerance: float = 0.001

JointLimitsConstraintConfig

Bases: ConstraintConfig

Box limits on actuated joints.

Attributes:

Name	Type	Description
kind

Attributes

kind class-attribute instance-attribute

kind = JOINT_LIMITS

LaplacianObjectiveConfig

Bases: ObjectiveConfig

Interaction-mesh Laplacian deformation objective.

Attributes:

Name	Type	Description
kind

Attributes

kind class-attribute instance-attribute

kind = LAPLACIAN

LinkTrackingObjectiveConfig

Bases: ObjectiveConfig

Track robot links to a typed target plan.

Attributes:

Name	Type	Description
kind
weight_scale	float

Attributes

kind class-attribute instance-attribute

kind = LINK_TRACKING

weight_scale class-attribute instance-attribute

weight_scale: float = 1.0

NominalTrackingObjectiveConfig

Bases: ObjectiveConfig

Track a nominal posture for typed robot joints or explicit qpos coordinates.

Attributes:

Name	Type	Description
kind
weight	float
joints	tuple[RobotJoint, ...]
qpos_indices	tuple[int, ...]
fallback	NominalFallback

Attributes

kind class-attribute instance-attribute

kind = NOMINAL_TRACKING

weight class-attribute instance-attribute

weight: float = 5.0

joints class-attribute instance-attribute

joints: tuple[RobotJoint, ...] = ()

qpos_indices class-attribute instance-attribute

qpos_indices: tuple[int, ...] = ()

fallback class-attribute instance-attribute

fallback: NominalFallback = ZERO

NonPenetrationConstraintConfig

Bases: ConstraintConfig

Separate selected typed robot links from support and explicit geometry.

Attributes:

Name	Type	Description
kind
links	tuple[RobotLink, ...]
subjects	tuple[ContactSubject, ...]
sources	tuple[NonPenetrationSource, ...]
geometry_pairs	tuple[GeometryPair, ...]
tolerance	float
floor_z	float
scene_clearance	float
activation_distance	float | None

Attributes

kind class-attribute instance-attribute

kind = NON_PENETRATION

links class-attribute instance-attribute

links: tuple[RobotLink, ...] = ()

subjects class-attribute instance-attribute

subjects: tuple[ContactSubject, ...] = ()

sources class-attribute instance-attribute

sources: tuple[NonPenetrationSource, ...] = (SUPPORT, SCENE_POINTS, GEOMETRY)

geometry_pairs class-attribute instance-attribute

geometry_pairs: tuple[GeometryPair, ...] = ()

tolerance class-attribute instance-attribute

tolerance: float = 0.001

floor_z class-attribute instance-attribute

floor_z: float = 0.0

scene_clearance class-attribute instance-attribute

scene_clearance: float = 0.02

activation_distance class-attribute instance-attribute

activation_distance: float | None = None

ObjectiveConfig

Bases: BaseModel

Base class for objective configs keyed by an extensible enum member.

Methods:

Name	Description
with_weight	Return a copy with a different objective weight.

Attributes:

Name	Type	Description
model_config
kind	ObjectiveKind
weight	float

Attributes

model_config class-attribute instance-attribute

model_config = ConfigDict(extra='forbid', arbitrary_types_allowed=True)

kind class-attribute

kind: ObjectiveKind

weight class-attribute instance-attribute

weight: float = 1.0

Functions

with_weight

with_weight(weight: float) -> Self

Return a copy with a different objective weight.

OptimizationProfile

Bases: BaseModel

Reusable typed objective/constraint composition.

Methods:

Name	Description
defaults	Return default robot-only optimization terms.
objective	Return the last objective matching kind.
constraint	Return the last constraint matching kind.
with_objective
without_objective
with_constraint
without_constraint
validate_registry_references

Attributes:

Name	Type	Description
model_config
name	str
objectives	tuple[ObjectiveConfig, ...]
constraints	tuple[ConstraintConfig, ...]
provenance	dict[str, object]
objective_kinds	tuple[ObjectiveKind, ...]	Objective kinds in profile order.
constraint_kinds	tuple[ConstraintKind, ...]	Constraint kinds in profile order.

Attributes

model_config class-attribute instance-attribute

model_config = ConfigDict(arbitrary_types_allowed=True)

name class-attribute instance-attribute

name: str = 'custom'

objectives class-attribute instance-attribute

objectives: tuple[ObjectiveConfig, ...] = ()

constraints class-attribute instance-attribute

constraints: tuple[ConstraintConfig, ...] = ()

provenance class-attribute instance-attribute

provenance: dict[str, object] = Field(default_factory=dict)

objective_kinds property

objective_kinds: tuple[ObjectiveKind, ...]

Objective kinds in profile order.

constraint_kinds property

constraint_kinds: tuple[ConstraintKind, ...]

Constraint kinds in profile order.

Functions

defaults classmethod

defaults(*, name: str = 'default') -> OptimizationProfile

Return default robot-only optimization terms.

objective

objective(kind: ObjectiveKind) -> ObjectiveConfig | None

Return the last objective matching kind.

constraint

constraint(kind: ConstraintKind) -> ConstraintConfig | None

Return the last constraint matching kind.

with_objective

with_objective(objective: ObjectiveConfig, *, replace: bool = True) -> Self

without_objective

without_objective(*kinds: ObjectiveKind) -> Self

with_constraint

with_constraint(constraint: ConstraintConfig, *, replace: bool = True) -> Self

without_constraint

without_constraint(*kinds: ConstraintKind) -> Self

validate_registry_references

validate_registry_references(solver: SolverSpec | None = None) -> None

SelfCollisionConstraintConfig

Bases: ConstraintConfig

Maintain minimum separation between explicit typed robot geometry pairs.

Attributes:

Name	Type	Description
kind
pairs	tuple[GeometryPair, ...]
minimum_distance	float
margin	float | None
windows	tuple[tuple[int, int], ...] | None

Attributes

kind class-attribute instance-attribute

kind = SELF_COLLISION

pairs class-attribute instance-attribute

pairs: tuple[GeometryPair, ...] = ()

minimum_distance class-attribute instance-attribute

minimum_distance: float = 0.02

margin class-attribute instance-attribute

margin: float | None = None

windows class-attribute instance-attribute

windows: tuple[tuple[int, int], ...] | None = None

SmoothnessObjectiveConfig

Bases: ObjectiveConfig

Penalize changes from the previous frame.

Attributes:

Name	Type	Description
kind

Attributes

kind class-attribute instance-attribute

kind = SMOOTHNESS

SolverSpec

Bases: BaseModel

Solver selection and common options.

Attributes:

Name	Type	Description
model_config
backend	SolverKind
max_iterations	int
first_frame_iterations	int | None
trust_radius	float
tolerance	float
convergence	ConvergenceMode
cost_atol	float
cost_rtol	float
verbose	bool

Attributes

model_config class-attribute instance-attribute

model_config = ConfigDict(extra='forbid', arbitrary_types_allowed=True)

backend class-attribute instance-attribute

backend: SolverKind = AUTO

max_iterations class-attribute instance-attribute

max_iterations: int = 10

first_frame_iterations class-attribute instance-attribute

first_frame_iterations: int | None = None

trust_radius class-attribute instance-attribute

trust_radius: float = 0.2

tolerance class-attribute instance-attribute

tolerance: float = 1e-06

convergence class-attribute instance-attribute

convergence: ConvergenceMode = STEP_NORM

cost_atol class-attribute instance-attribute

cost_atol: float = 1e-08

cost_rtol class-attribute instance-attribute

cost_rtol: float = 1e-05

verbose class-attribute instance-attribute

verbose: bool = False

TrustRegionConstraintConfig

Bases: ConstraintConfig

Cap the Euclidean norm of each SQP update.

Attributes:

Name	Type	Description
kind
radius	float | None

Attributes

kind class-attribute instance-attribute

kind = TRUST_REGION

radius class-attribute instance-attribute

radius: float | None = None

QposVariableSpec

Bases: BaseModel

Configuration describing which qpos coordinates the optimizer may change.

actuated preserves the package default: only robot joints are decision variables. qpos_slice and qpos_indices allow floating-base, Holosoma-style, or otherwise custom variable sets without changing terms.

Methods:

Name	Description
actuated	Return the default actuated-joint variable policy.
qpos_slice	Return a contiguous qpos variable policy.
qpos_indices	Return an explicit qpos-index variable policy.
from_actuated_start_offset	Return a slice starting relative to robot.qpos_layout.joint_start.
holosoma_q_a	Return the variable policy matching Holosoma's default q_a slice.
resolve	Resolve this policy against a robot and concrete qpos width.

Attributes:

Name	Type	Description
model_config
kind	QposVariableKind
start	int | None
stop	int | None
indices	tuple[int, ...]
actuated_start_offset	int | None
unbounded_limit	float
normalize_quaternion	bool

Attributes

model_config class-attribute instance-attribute

model_config = ConfigDict(extra='forbid')

kind class-attribute instance-attribute

kind: QposVariableKind = ACTUATED

start class-attribute instance-attribute

start: int | None = None

stop class-attribute instance-attribute

stop: int | None = None

indices class-attribute instance-attribute

indices: tuple[int, ...] = ()

actuated_start_offset class-attribute instance-attribute

actuated_start_offset: int | None = None

unbounded_limit class-attribute instance-attribute

unbounded_limit: float = 1000000.0

normalize_quaternion class-attribute instance-attribute

normalize_quaternion: bool = True

Functions

actuated classmethod

actuated() -> Self

Return the default actuated-joint variable policy.

qpos_slice classmethod

qpos_slice(
    *, start: int, stop: int | None = None, normalize_quaternion: bool = True
) -> Self

Return a contiguous qpos variable policy.

qpos_indices classmethod

qpos_indices(indices: tuple[int, ...], *, normalize_quaternion: bool = True) -> Self

Return an explicit qpos-index variable policy.

from_actuated_start_offset classmethod

from_actuated_start_offset(offset: int, *, stop: int | None = None) -> Self

Return a slice starting relative to robot.qpos_layout.joint_start.

Holosoma's q_a_init_idx=-7 is represented by from_actuated_start_offset(-7) for the default floating-base qpos layout, giving a variable slice from root position through actuated joints.

holosoma_q_a classmethod

holosoma_q_a(q_a_init_idx: int = -7) -> Self

Return the variable policy matching Holosoma's default q_a slice.

resolve

resolve(
    robot: RobotSpec[JointT, Any, Any, Any],
    *,
    qpos_size: int,
    joint_limits: Mapping[JointT, tuple[float, float]] | None = None,
) -> ResolvedQposVariables

Resolve this policy against a robot and concrete qpos width.

ResolvedQposVariables dataclass

ResolvedQposVariables(
    spec: QposVariableSpec,
    indices: NDArray[int64],
    lower: FloatArray,
    upper: FloatArray,
    quaternion_slice: tuple[int, int] | None = None,
)

Resolved qpos coordinates used as one SQP subproblem variable.

The solver still optimizes an increment vector, but the columns can now refer to any qpos coordinate, not only actuated joints. This is the abstraction needed for floating-base q_a style solves.

Methods:

Name	Description
values	Return this variable set's current qpos values.
apply_delta	Return a copy of qpos after applying one solver increment.

Attributes:

Name	Type	Description
spec	QposVariableSpec
indices	NDArray[int64]
lower	FloatArray
upper	FloatArray
quaternion_slice	tuple[int, int] | None
size	int	Number of optimization variables.

Attributes

spec instance-attribute

spec: QposVariableSpec

indices instance-attribute

indices: NDArray[int64]

lower instance-attribute

lower: FloatArray

upper instance-attribute

upper: FloatArray

quaternion_slice class-attribute instance-attribute

quaternion_slice: tuple[int, int] | None = None

size property

size: int

Number of optimization variables.

Functions

values

values(qpos: FloatArray) -> FloatArray

Return this variable set's current qpos values.

apply_delta

apply_delta(qpos: FloatArray, delta: FloatArray) -> FloatArray

Return a copy of qpos after applying one solver increment.

BatchJob

Bases: BaseModel

One retargeting job in a batch run.

Attributes:

Name	Type	Description
id	str	Stable job identifier used in manifests and resume logic.
motion	Path	Input motion artifact path for the worker.
output	Path	Expected output artifact path; existing files may be skipped.
name	str | None	Optional display name; defaults to id in callers.
motion_format	MotionFormatKind | None	Typed source motion format override.
robot	RobotKind | None	Typed robot registry override.
config_path	Path | None	Optional declarative experiment config.
provenance	dict[str, Any]	Origin and scheduling history for the job.

Attributes

model_config class-attribute instance-attribute

model_config = ConfigDict(arbitrary_types_allowed=True)

id instance-attribute

id: str

motion instance-attribute

motion: Path

output instance-attribute

output: Path

name class-attribute instance-attribute

name: str | None = None

motion_format class-attribute instance-attribute

motion_format: MotionFormatKind | None = None

robot class-attribute instance-attribute

robot: RobotKind | None = None

config_path class-attribute instance-attribute

config_path: Path | None = None

provenance class-attribute instance-attribute

provenance: dict[str, Any] = Field(default_factory=dict)

BatchManifest

Bases: BaseModel

Manifest written by resumable batch runs.

Attributes:

Name	Type	Description
schema_version	int	Manifest format version for forward compatibility.
created_at	datetime	UTC time when the batch run first started.
updated_at	datetime	UTC time of the most recent manifest write.
input_dir	Path | None	Root directory scanned for input motions, if known.
output_dir	Path | None	Root directory for written outputs, if known.
pattern	str	Glob or filter pattern used to build the job list.
total	int	Number of jobs in the batch definition.
success_count	int	Jobs that completed with :attr:~RunStatus.SUCCESS.
skipped_count	int	Jobs skipped because outputs already existed.
failed_count	int	Jobs that raised during execution.
records	tuple[BatchRunRecord, ...]	Per-job outcomes in submission order.

Methods:

Name	Description
from_records	Build a manifest and derive summary counts from records.
load	Load a manifest JSON file.
save_json	Save manifest JSON.
records_by_id	Return records keyed by job id.

Attributes

model_config class-attribute instance-attribute

model_config = ConfigDict(arbitrary_types_allowed=True)

schema_version class-attribute instance-attribute

schema_version: int = 1

created_at instance-attribute

created_at: datetime

updated_at instance-attribute

updated_at: datetime

input_dir class-attribute instance-attribute

input_dir: Path | None = None

output_dir class-attribute instance-attribute

output_dir: Path | None = None

pattern class-attribute instance-attribute

pattern: str = ''

total class-attribute instance-attribute

total: int = 0

success_count class-attribute instance-attribute

success_count: int = 0

skipped_count class-attribute instance-attribute

skipped_count: int = 0

failed_count class-attribute instance-attribute

failed_count: int = 0

records class-attribute instance-attribute

records: tuple[BatchRunRecord, ...] = ()

Functions

from_records classmethod

from_records(
    *,
    records: Iterable[BatchRunRecord],
    total: int,
    created_at: datetime,
    input_dir: Path | None = None,
    output_dir: Path | None = None,
    pattern: str = "",
) -> BatchManifest

Build a manifest and derive summary counts from records.

load classmethod

load(path: str | Path) -> BatchManifest

Load a manifest JSON file.

save_json

save_json(path: str | Path) -> Path

Save manifest JSON.

records_by_id

records_by_id() -> dict[str, BatchRunRecord]

Return records keyed by job id.

BatchRunner

Execute jobs with resume-aware manifest updates.

The worker must be pickleable when max_workers is greater than one.

Methods:

Name	Description
run	Run jobs, skip existing outputs, and update a manifest incrementally.

Functions

run

run(
    jobs: Iterable[BatchJob],
    worker: BatchWorker,
    *,
    manifest_path: str | Path,
    max_workers: int = 1,
    force: bool = False,
    input_dir: Path | None = None,
    output_dir: Path | None = None,
    pattern: str = "",
) -> BatchManifest

Run jobs, skip existing outputs, and update a manifest incrementally.

Loads an existing manifest at manifest_path when present so reruns can resume. Jobs whose output already exists are marked skipped unless force is true. After each completed (or skipped) job the manifest is rewritten so partial progress survives interruption.

Parameters:

Name	Type	Description	Default
jobs	Iterable[BatchJob]	Iterable of retargeting jobs to execute.	required
worker	BatchWorker	Pickleable callable invoked per pending job; must accept a :class:BatchJob and return optional provenance on success.	required
manifest_path	str | Path	JSON manifest path updated after each job finishes.	required
max_workers	int	Process pool size; 1 runs jobs sequentially in-process.	1
force	bool	When true, rerun jobs even if output already exists.	False
input_dir	Path | None	Optional batch input root stored on the manifest.	None
output_dir	Path | None	Optional batch output root stored on the manifest.	None
pattern	str	Optional glob or filter label stored on the manifest.	''

Returns:

Type	Description
BatchManifest	Final manifest aggregating all job records and summary counts.

Raises:

Type	Description
ValueError	If max_workers is less than 1.

BatchRunRecord

Bases: BaseModel

Recorded outcome for one batch job.

Attributes:

Name	Type	Description
job_id	str	Identifier matching :attr:BatchJob.id.
motion	Path	Input path from the job definition.
output	Path	Output path from the job definition.
status	RunStatus	Terminal status (success, skipped, or failed).
started_at	datetime	UTC timestamp when execution began.
finished_at	datetime	UTC timestamp when execution completed.
message	str	Human-readable summary or error text.
error_type	str | None	Exception class name when status is failed.
provenance	dict[str, Any]	Worker-returned processing history or resume information.

Attributes

model_config class-attribute instance-attribute

model_config = ConfigDict(arbitrary_types_allowed=True)

job_id instance-attribute

job_id: str

motion instance-attribute

motion: Path

output instance-attribute

output: Path

status instance-attribute

status: RunStatus

started_at instance-attribute

started_at: datetime

finished_at instance-attribute

finished_at: datetime

message class-attribute instance-attribute

message: str = ''

error_type class-attribute instance-attribute

error_type: str | None = None

provenance class-attribute instance-attribute

provenance: dict[str, Any] = Field(default_factory=dict)

duration_s property

duration_s: float

Wall-clock duration in seconds.

InteractionMeshRetargetingEngine

InteractionMeshRetargetingEngine(
    *,
    kinematics: KinematicsBackend | None = None,
    mesh_builder: InteractionMeshBuilder | None = None,
)

Backend-agnostic interaction-mesh SQP retargeter.

The engine builds one local quadratic problem per SQP iteration. Its decision variable is the actuated-joint increment for the current frame. Root and object poses are locked from the motion/scene specification.

Methods:

Name	Description
run	Run interaction-mesh retargeting for all frames.

Attributes:

Name	Type	Description
kinematics	KinematicsBackend | None
mesh_builder	InteractionMeshBuilder | None

Attributes

kinematics instance-attribute

kinematics: KinematicsBackend | None = kinematics

mesh_builder instance-attribute

mesh_builder: InteractionMeshBuilder | None = mesh_builder

Functions

run

run(problem: RetargetingProblem) -> EngineOutput

Run interaction-mesh retargeting for all frames.

RetargetingExperiment

RetargetingExperiment(
    *,
    observation: ObservationRecipe | SceneObservation,
    recipe: RetargetingRecipe,
    robot: RobotSpec,
    retargeter: Retargeter | None = None,
    retargeter_factory: Callable[[RetargetingProblem], Retargeter] | None = None,
)

Compose observation processing, robot adaptation, and optimization.

Methods:

Name	Description
observe	Process capture inputs once and retain the in-memory observation.
build_problem	Adapt the observation to the configured robot.
run	Run the complete in-memory experiment.

Attributes:

Name	Type	Description
recipe
robot
retargeter
retargeter_factory

Attributes

recipe instance-attribute

recipe = recipe

robot instance-attribute

robot = robot

retargeter instance-attribute

retargeter = retargeter or Retargeter()

retargeter_factory instance-attribute

retargeter_factory = retargeter_factory

Functions

observe

observe() -> SceneObservation

Process capture inputs once and retain the in-memory observation.

build_problem

build_problem() -> RetargetingProblem

Adapt the observation to the configured robot.

run

run() -> RetargetingResult

Run the complete in-memory experiment.

RetargetingProblem

Bases: BaseModel, Generic[MotionJointT, RobotJointT, RobotLinkT, RobotGeometryT, RobotRoleT]

Complete typed run specification before backend compilation.

Methods:

Name	Description
joint_mapping	Return the typed motion-joint to robot-joint mapping.
link_mapping	Return the typed motion-joint to robot-link mapping.
validate_registry_references	Validate registered optimization references used by this problem.
with_optimization_profile	Return a copy using one reusable optimization profile.
with_output_fps_applied	Return a problem whose dynamic data matches output_fps.

Attributes:

Name	Type	Description
model_config
name	str
task_kind	TaskKind
robot	RobotSpec[RobotJointT, RobotLinkT, RobotGeometryT, RobotRoleT]
motion	MotionSequence[MotionJointT]
scene	SceneSpec
contacts	ContactPlan[Any, Any, Any, RobotLinkT] | None
targets	LinkTargetPlan[RobotLinkT] | None
initial_qpos	InitialQposPlan | None
nominal_qpos	NominalQposPlan | None
joint_bindings	tuple[JointBinding[MotionJointT, RobotJointT], ...]
link_bindings	tuple[LinkBinding[MotionJointT, RobotLinkT], ...]
mesh	InteractionMeshSpec
solver	SolverSpec
variables	QposVariableSpec
objectives	tuple[ObjectiveConfig, ...]
constraints	tuple[ConstraintConfig, ...]
scale_to_robot	bool
output_fps	float | None
show_progress	bool
progress_description	str | None
provenance	dict[str, Any]
fps	float	Effective playback and result sampling rate.

Attributes

model_config class-attribute instance-attribute

model_config = ConfigDict(arbitrary_types_allowed=True)

name instance-attribute

name: str

task_kind instance-attribute

task_kind: TaskKind

robot instance-attribute

robot: RobotSpec[RobotJointT, RobotLinkT, RobotGeometryT, RobotRoleT]

motion instance-attribute

motion: MotionSequence[MotionJointT]

scene instance-attribute

scene: SceneSpec

contacts class-attribute instance-attribute

contacts: ContactPlan[Any, Any, Any, RobotLinkT] | None = None

targets class-attribute instance-attribute

targets: LinkTargetPlan[RobotLinkT] | None = None

initial_qpos class-attribute instance-attribute

initial_qpos: InitialQposPlan | None = None

nominal_qpos class-attribute instance-attribute

nominal_qpos: NominalQposPlan | None = None

joint_bindings class-attribute instance-attribute

joint_bindings: tuple[JointBinding[MotionJointT, RobotJointT], ...] = ()

link_bindings class-attribute instance-attribute

link_bindings: tuple[LinkBinding[MotionJointT, RobotLinkT], ...] = ()

mesh class-attribute instance-attribute

mesh: InteractionMeshSpec = Field(default_factory=InteractionMeshSpec)

solver class-attribute instance-attribute

solver: SolverSpec = Field(default_factory=SolverSpec)

variables class-attribute instance-attribute

variables: QposVariableSpec = Field(default_factory=actuated)

objectives class-attribute instance-attribute

objectives: tuple[ObjectiveConfig, ...] = objectives

constraints class-attribute instance-attribute

constraints: tuple[ConstraintConfig, ...] = constraints

scale_to_robot class-attribute instance-attribute

scale_to_robot: bool = True

output_fps class-attribute instance-attribute

output_fps: float | None = None

show_progress class-attribute instance-attribute

show_progress: bool = False

progress_description class-attribute instance-attribute

progress_description: str | None = None

provenance class-attribute instance-attribute

provenance: dict[str, Any] = Field(default_factory=dict)

fps property

fps: float

Effective playback and result sampling rate.

Functions

joint_mapping

joint_mapping() -> dict[MotionJointT, RobotJointT]

Return the typed motion-joint to robot-joint mapping.

link_mapping

link_mapping() -> dict[MotionJointT, RobotLinkT]

Return the typed motion-joint to robot-link mapping.

validate_registry_references

validate_registry_references() -> None

Validate registered optimization references used by this problem.

with_optimization_profile

with_optimization_profile(
    profile: OptimizationProfile,
) -> RetargetingProblem[
    MotionJointT, RobotJointT, RobotLinkT, RobotGeometryT, RobotRoleT
]

Return a copy using one reusable optimization profile.

with_output_fps_applied

with_output_fps_applied() -> RetargetingProblem[
    MotionJointT, RobotJointT, RobotLinkT, RobotGeometryT, RobotRoleT
]

Return a problem whose dynamic data matches output_fps.

ObservationRecipe

Bases: Protocol

Process native recordings into a target-independent observation.

Methods:

Name	Description
observe	Return a shared-timeline scene observation.

Functions

observe

observe() -> SceneObservation

Return a shared-timeline scene observation.

RetargetingRecipe

Bases: Protocol

Adapt a scene observation to one target robot.

Methods:

Name	Description
build_problem	Build a complete retargeting problem.

Functions

build_problem

build_problem(observation: SceneObservation, robot: RobotSpec) -> RetargetingProblem

Build a complete retargeting problem.

SceneRecipe

Bases: Protocol

Build target-independent runtime scene data from an observation.

Methods:

Name	Description
build_scene	Build a frame-aligned scene.

Functions

build_scene

build_scene(observation: SceneObservation) -> SceneSpec

Build a frame-aligned scene.

Retargeter

Retargeter(*, engine: InteractionMeshRetargetingEngine | None = None)

Run a RetargetingProblem and return a typed result.

Methods:

Name	Description
run	Retarget a motion sequence.

Attributes:

Name	Type	Description
engine	InteractionMeshRetargetingEngine

Attributes

engine instance-attribute

engine: InteractionMeshRetargetingEngine = engine or InteractionMeshRetargetingEngine()

Functions

run

run(problem: RetargetingProblem) -> RetargetingResult

Retarget a motion sequence.

MotionFileObservationRecipe dataclass

MotionFileObservationRecipe(
    path: Path,
    motion_format: MotionFormatSpec,
    name: str | None = None,
    max_frames: int | None = None,
    source_height_m: float | None = None,
)

Load a registered motion file into a typed scene observation.

Methods:

Name	Description
registered	Construct from a registered motion-format key.
observe	Load the file without creating an intermediate checkpoint.

Attributes:

Name	Type	Description
path	Path
motion_format	MotionFormatSpec
name	str | None
max_frames	int | None
source_height_m	float | None

Attributes

path instance-attribute

path: Path

motion_format instance-attribute

motion_format: MotionFormatSpec

name class-attribute instance-attribute

name: str | None = None

max_frames class-attribute instance-attribute

max_frames: int | None = None

source_height_m class-attribute instance-attribute

source_height_m: float | None = None

Functions

registered classmethod

registered(
    path: str | Path,
    format_kind: MotionFormatKind,
    *,
    name: str | None = None,
    max_frames: int | None = None,
    source_height_m: float | None = None,
) -> MotionFileObservationRecipe

Construct from a registered motion-format key.

observe

observe() -> SceneObservation

Load the file without creating an intermediate checkpoint.

RobotOnlySceneRecipe dataclass

RobotOnlySceneRecipe(
    terrain: TerrainSpec = TerrainSpec(),
    ground_range: tuple[float, float] = (-1.0, 1.0),
    ground_size: int = 15,
)

Build a flat-ground robot-only scene.

Methods:

Name	Description
build_scene	Build the scene independently of the target robot.

Attributes:

Name	Type	Description
terrain	TerrainSpec
ground_range	tuple[float, float]
ground_size	int

Attributes

terrain class-attribute instance-attribute

terrain: TerrainSpec = field(default_factory=TerrainSpec)

ground_range class-attribute instance-attribute

ground_range: tuple[float, float] = (-1.0, 1.0)

ground_size class-attribute instance-attribute

ground_size: int = 15

Functions

build_scene

build_scene(observation: SceneObservation) -> SceneSpec

Build the scene independently of the target robot.

RoleRetargetingRecipe dataclass

RoleRetargetingRecipe(
    task_kind: TaskKind,
    motion_format: MotionFormatSpec,
    scene: SceneRecipe,
    joint_roles: dict[MotionJoint, RobotRole] = dict(),
    link_roles: dict[MotionJoint, RobotRole] = dict(),
    mesh: InteractionMeshSpec = InteractionMeshSpec(),
    solver: SolverSpec = SolverSpec(),
    variables: QposVariableSpec = actuated(),
    objectives: tuple[ObjectiveConfig, ...] = objectives,
    constraints: tuple[ConstraintConfig, ...] = constraints,
    scale_to_robot: bool = True,
    output_fps: float | None = None,
    show_progress: bool = False,
    name: str | None = None,
    provenance: dict[str, object] = dict(),
)

Resolve typed motion joints through semantic robot roles.

Methods:

Name	Description
build_problem	Build the generic problem through explicit semantic role bindings.

Attributes:

Name	Type	Description
task_kind	TaskKind
motion_format	MotionFormatSpec
scene	SceneRecipe
joint_roles	dict[MotionJoint, RobotRole]
link_roles	dict[MotionJoint, RobotRole]
mesh	InteractionMeshSpec
solver	SolverSpec
variables	QposVariableSpec
objectives	tuple[ObjectiveConfig, ...]
constraints	tuple[ConstraintConfig, ...]
scale_to_robot	bool
output_fps	float | None
show_progress	bool
name	str | None
provenance	dict[str, object]

Attributes

task_kind instance-attribute

task_kind: TaskKind

motion_format instance-attribute

motion_format: MotionFormatSpec

scene instance-attribute

scene: SceneRecipe

joint_roles class-attribute instance-attribute

joint_roles: dict[MotionJoint, RobotRole] = field(default_factory=dict)

link_roles class-attribute instance-attribute

link_roles: dict[MotionJoint, RobotRole] = field(default_factory=dict)

mesh class-attribute instance-attribute

mesh: InteractionMeshSpec = field(default_factory=InteractionMeshSpec)

solver class-attribute instance-attribute

solver: SolverSpec = field(default_factory=SolverSpec)

variables class-attribute instance-attribute

variables: QposVariableSpec = field(default_factory=actuated)

objectives class-attribute instance-attribute

objectives: tuple[ObjectiveConfig, ...] = objectives

constraints class-attribute instance-attribute

constraints: tuple[ConstraintConfig, ...] = constraints

scale_to_robot class-attribute instance-attribute

scale_to_robot: bool = True

output_fps class-attribute instance-attribute

output_fps: float | None = None

show_progress class-attribute instance-attribute

show_progress: bool = False

name class-attribute instance-attribute

name: str | None = None

provenance class-attribute instance-attribute

provenance: dict[str, object] = field(default_factory=dict)

Functions

build_problem

build_problem(observation: SceneObservation, robot: RobotSpec) -> RetargetingProblem

Build the generic problem through explicit semantic role bindings.

StaticSceneRecipe dataclass

StaticSceneRecipe(scene: SceneSpec)

Return a predeclared target-independent scene specification.

Methods:

Name	Description
build_scene	Validate the scene timeline and return the configured scene.

Attributes:

Name	Type	Description
scene	SceneSpec

Attributes

scene instance-attribute

scene: SceneSpec

Functions

build_scene

build_scene(observation: SceneObservation) -> SceneSpec

Validate the scene timeline and return the configured scene.

EvaluationManifest

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 records.
success_count	int	Records with :attr:~retarget.core.enums.RunStatus.SUCCESS.
partial_count	int	Records with :attr:~retarget.core.enums.RunStatus.PARTIAL.
skipped_count	int	Records with :attr:~retarget.core.enums.RunStatus.SKIPPED.
failed_count	int	Records with :attr:~retarget.core.enums.RunStatus.FAILED.
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

model_config class-attribute instance-attribute

model_config = ConfigDict(arbitrary_types_allowed=True)

schema_version class-attribute instance-attribute

schema_version: int = 1

created_at instance-attribute

created_at: datetime

updated_at instance-attribute

updated_at: datetime

total class-attribute instance-attribute

total: int = 0

success_count class-attribute instance-attribute

success_count: int = 0

partial_count class-attribute instance-attribute

partial_count: int = 0

skipped_count class-attribute instance-attribute

skipped_count: int = 0

failed_count class-attribute instance-attribute

failed_count: int = 0

records class-attribute instance-attribute

records: tuple[EvaluationRecord, ...] = ()

Functions

from_records classmethod

from_records(records: Iterable[EvaluationRecord]) -> EvaluationManifest

Build a summary manifest from per-result records.

load classmethod

load(path: str | Path) -> EvaluationManifest

Load a batch evaluation manifest JSON file.

save_json

save_json(path: str | Path) -> Path

Save manifest JSON.

EvaluationRecord

Bases: BaseModel

Recorded outcome for evaluating one retargeting result.

Attributes:

Name	Type	Description
result_path	Path	Path to the evaluated .npz retargeting output.
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 status is not success.
metrics	dict[str, float]	Scalar metrics copied from the report.
warnings	tuple[str, ...]	Warnings surfaced during evaluation.

Attributes

model_config class-attribute instance-attribute

model_config = ConfigDict(arbitrary_types_allowed=True)

result_path instance-attribute

result_path: Path

status instance-attribute

status: RunStatus

report_path class-attribute instance-attribute

report_path: Path | None = None

job_id class-attribute instance-attribute

job_id: str | None = None

source_name class-attribute instance-attribute

source_name: str | None = None

frame_count class-attribute instance-attribute

frame_count: int | None = None

message class-attribute instance-attribute

message: str = ''

metrics class-attribute instance-attribute

metrics: dict[str, float] = Field(default_factory=dict)

warnings class-attribute instance-attribute

warnings: tuple[str, ...] = ()

EvaluationReport

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 qpos width.
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 metrics keys.
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.

Attributes

status class-attribute instance-attribute

status: RunStatus = SUCCESS

source_name class-attribute instance-attribute

source_name: str | None = None

frame_count class-attribute instance-attribute

frame_count: int | None = None

qpos_dimension class-attribute instance-attribute

qpos_dimension: int | None = None

fps class-attribute instance-attribute

fps: float | None = None

task_kind class-attribute instance-attribute

task_kind: str | None = None

robot_name class-attribute instance-attribute

robot_name: str | None = None

motion_name class-attribute instance-attribute

motion_name: str | None = None

metrics class-attribute instance-attribute

metrics: dict[str, float] = Field(default_factory=dict)

metric_units class-attribute instance-attribute

metric_units: dict[str, str] = Field(default_factory=dict)

details class-attribute instance-attribute

details: dict[str, Any] = Field(default_factory=dict)

warnings class-attribute instance-attribute

warnings: tuple[str, ...] = ()

Functions

save_json

save_json(path: str | Path) -> Path

Save report as JSON.

RetargetingResult

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 .npz.
load_npz	Load the current strict .npz checkpoint schema.

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

model_config class-attribute instance-attribute

model_config = ConfigDict(arbitrary_types_allowed=True)

schema_version class-attribute instance-attribute

schema_version: int = 2

name instance-attribute

name: str

status instance-attribute

status: RunStatus

qpos instance-attribute

qpos: FloatArray

fps class-attribute instance-attribute

fps: float = 30.0

cost class-attribute instance-attribute

cost: FloatArray | None = None

human_joints class-attribute instance-attribute

human_joints: FloatArray | None = None

human_vocabulary class-attribute instance-attribute

human_vocabulary: VocabularyManifest | None = None

robot_link_positions class-attribute instance-attribute

robot_link_positions: FloatArray | None = None

run class-attribute instance-attribute

run: RetargetingRunReport | None = None

playback class-attribute instance-attribute

playback: ResultPlaybackSpec | None = None

warnings class-attribute instance-attribute

warnings: tuple[str, ...] = ()

provenance class-attribute instance-attribute

provenance: dict[str, Any] = Field(default_factory=dict)

frame_count property

frame_count: int

Number of frames.

Functions

resampled

resampled(fps: float, *, name: str | None = None) -> RetargetingResult

Return this result sampled on a new FPS grid.

save_npz

save_npz(path: str | Path) -> Path

Save result to .npz.

load_npz classmethod

load_npz(path: str | Path) -> RetargetingResult

Load the current strict .npz checkpoint schema.

JointLimit

Bases: BaseModel, Generic[JointT]

Position bounds for one typed actuated joint.

Attributes:

Name	Type	Description
joint	JointT
lower	float
upper	float

Attributes

joint instance-attribute

joint: JointT

lower instance-attribute

lower: float

upper instance-attribute

upper: float

QposLayout

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

root_position class-attribute instance-attribute

root_position: tuple[int, int] = (0, 3)

root_quaternion class-attribute instance-attribute

root_quaternion: tuple[int, int] = (3, 7)

joint_start class-attribute instance-attribute

joint_start: int = 7

object_pose_size class-attribute instance-attribute

object_pose_size: int = 7

Functions

qpos_size

qpos_size(robot_dof: int, *, has_object: bool = False) -> int

Return qpos size for this layout.

joint_slice

joint_slice(robot_dof: int) -> slice

Return the slice containing actuated robot joints.

object_slice

object_slice(robot_dof: int) -> slice

Return the slice containing an appended object pose.

RobotSpec

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 base_dir.
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

model_config class-attribute instance-attribute

model_config = ConfigDict(arbitrary_types_allowed=True)

name instance-attribute

name: str

height_m instance-attribute

height_m: float

vocabulary instance-attribute

vocabulary: RobotVocabulary[JointT, LinkT, GeometryT, RoleT]

joints instance-attribute

joints: tuple[JointT, ...]

links instance-attribute

links: tuple[LinkT, ...]

contact_links class-attribute instance-attribute

contact_links: tuple[LinkT, ...] = ()

geometries class-attribute instance-attribute

geometries: tuple[GeometryT, ...] = ()

joint_limits class-attribute instance-attribute

joint_limits: dict[JointT, tuple[float, float]] = Field(default_factory=dict)

joint_roles class-attribute instance-attribute

joint_roles: dict[RoleT, JointT] = Field(default_factory=dict)

link_roles class-attribute instance-attribute

link_roles: dict[RoleT, LinkT] = Field(default_factory=dict)

link_groups class-attribute instance-attribute

link_groups: dict[RoleT, tuple[LinkT, ...]] = Field(default_factory=dict)

mujoco_body_aliases class-attribute instance-attribute

mujoco_body_aliases: dict[LinkT, str] = Field(default_factory=dict)

simple_kinematics class-attribute instance-attribute

simple_kinematics: dict[LinkT, SimpleKinematicPoint[JointT]] = Field(
    default_factory=dict
)

urdf_path class-attribute instance-attribute

urdf_path: Path | None = None

mujoco_xml_path class-attribute instance-attribute

mujoco_xml_path: Path | None = None

qpos_layout class-attribute instance-attribute

qpos_layout: QposLayout = Field(default_factory=QposLayout)

provenance class-attribute instance-attribute

provenance: dict[str, Any] = Field(default_factory=dict)

dof property

dof: int

Number of actuated joints.

Functions

joint_index

joint_index(joint: JointT) -> int

Return the actuated index for a typed joint.

joint_for_role

joint_for_role(role: RoleT) -> JointT

Resolve a semantic robot role to an actuated joint.

link_for_role

link_for_role(role: RoleT) -> LinkT

Resolve a semantic robot role to a link.

links_for_role

links_for_role(role: RoleT) -> tuple[LinkT, ...]

Resolve a semantic robot role to one or more links.

qpos_size

qpos_size(*, has_object: bool = False) -> int

Return qpos size for this robot and object setting.

load classmethod

load(path: str | Path) -> RobotSpec[Any, Any, Any, Any]

Load a robot spec whose config names concrete enum vocabulary classes.

resolve_paths

resolve_paths(base_dir: str | Path) -> RobotSpec[JointT, LinkT, GeometryT, RoleT]

Return a copy with relative asset paths resolved against base_dir.

save_json

save_json(path: str | Path) -> Path

Save a JSON representation with explicit vocabulary references.

limits_array

limits_array() -> tuple[list[float], list[float]]

Return joint limits in joint order.

RobotVocabulary

Bases: BaseModel, Generic[JointT, LinkT, GeometryT, RoleT]

Concrete enum classes used by one robot specification.

Attributes:

Name	Type	Description
model_config
joints	type[JointT]
links	type[LinkT]
geometries	type[GeometryT]
roles	type[RoleT]

Attributes

model_config class-attribute instance-attribute

model_config = ConfigDict(arbitrary_types_allowed=True, frozen=True)

joints instance-attribute

joints: type[JointT]

links instance-attribute

links: type[LinkT]

geometries instance-attribute

geometries: type[GeometryT]

roles instance-attribute

roles: type[RoleT]

SimpleKinematicPoint

Bases: BaseModel, Generic[JointT]

Explicit fixture kinematics for one robot link.

Attributes:

Name	Type	Description
model_config
joint	JointT
offset	tuple[float, float, float]
axis	tuple[float, float, float]
scale	float

Attributes

model_config class-attribute instance-attribute

model_config = ConfigDict(arbitrary_types_allowed=True, frozen=True)

joint instance-attribute

joint: JointT

offset instance-attribute

offset: tuple[float, float, float]

axis instance-attribute

axis: tuple[float, float, float]

scale class-attribute instance-attribute

scale: float = 1.0

ObjectSpec

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 (N, 3).
sample_space	ObjectSampleSpace	Coordinate space for sample_points.
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

model_config class-attribute instance-attribute

model_config = ConfigDict(arbitrary_types_allowed=True)

name instance-attribute

name: str

mesh_path class-attribute instance-attribute

mesh_path: Path | None = None

urdf_path class-attribute instance-attribute

urdf_path: Path | None = None

asset_scale class-attribute instance-attribute

asset_scale: tuple[float, float, float] = (1.0, 1.0, 1.0)

visual_parts class-attribute instance-attribute

visual_parts: tuple[ObjectVisualPart, ...] = ()

sample_points class-attribute instance-attribute

sample_points: FloatArray | None = None

sample_space class-attribute instance-attribute

sample_space: ObjectSampleSpace = OBJECT_LOCAL

trajectory class-attribute instance-attribute

trajectory: ObjectTrajectory | None = None

qpos_mode class-attribute instance-attribute

qpos_mode: ObjectQposMode = APPENDED

provenance class-attribute instance-attribute

provenance: dict[str, Any] = Field(default_factory=dict)

Functions

scaled_sample_points

scaled_sample_points(default: FloatArray | None = None) -> FloatArray | None

Return object sample points in the active object-local geometry frame.

ObjectTrajectory

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

poses instance-attribute

poses: PoseSequence

name class-attribute instance-attribute

name: str = 'object'

Functions

identity classmethod

identity(
    frame_count: int, *, fps: float = 30.0, name: str = "object"
) -> ObjectTrajectory

Return an identity object trajectory.

resampled

resampled(fps: float) -> ObjectTrajectory

Return this object trajectory sampled on a new FPS grid.

ObjectVisualPart

Bases: BaseModel

A renderable object mesh part with optional material styling.

Attributes:

Name	Type	Description
name	str	Stable part label used in scene paths.
mesh_path	Path	Mesh file for this visual part.
asset_scale	tuple[float, float, float] | None	Optional part-local scale; inherits the parent object scale when omitted by playback spec builders.
rgba	tuple[float, float, float, float] | None	Optional material color with alpha in [0, 1].

Attributes

model_config class-attribute instance-attribute

model_config = ConfigDict(arbitrary_types_allowed=True)

name instance-attribute

name: str

mesh_path instance-attribute

mesh_path: Path

asset_scale class-attribute instance-attribute

asset_scale: tuple[float, float, float] | None = None

rgba class-attribute instance-attribute

rgba: tuple[float, float, float, float] | None = None

SceneSpec

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:ground_points.
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

model_config class-attribute instance-attribute

model_config = ConfigDict(arbitrary_types_allowed=True)

task_kind instance-attribute

task_kind: TaskKind

object class-attribute instance-attribute

object: ObjectSpec | None = None

terrain class-attribute instance-attribute

terrain: TerrainSpec | None = None

ground_range class-attribute instance-attribute

ground_range: tuple[float, float] = (-1.0, 1.0)

ground_size class-attribute instance-attribute

ground_size: int = 15

provenance class-attribute instance-attribute

provenance: dict[str, Any] = Field(default_factory=dict)

Functions

robot_only classmethod

robot_only() -> SceneSpec

Create a robot-only ground scene.

Returns:

Name	Type	Description
SceneSpec	SceneSpec	ROBOT_ONLY task with default flat terrain.

object_interaction classmethod

object_interaction(object_spec: ObjectSpec) -> SceneSpec

Create an object interaction scene.

Parameters:

Name	Type	Description	Default
object_spec	ObjectSpec	Manipulated object definition.	required

Returns:

Name	Type	Description
SceneSpec	SceneSpec	OBJECT_INTERACTION task referencing object_spec.

climbing classmethod

climbing(
    terrain: TerrainSpec | None = None, object_spec: ObjectSpec | None = None
) -> SceneSpec

Create 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	CLIMBING task; inserts a default terrain spec when both arguments are omitted.

has_dynamic_object

has_dynamic_object() -> bool

Whether qpos should include appended object poses.

resampled

resampled(fps: float) -> SceneSpec

Return a scene with dynamic trajectories sampled on a new FPS grid.

ground_points

ground_points() -> FloatArray

Create an xy grid of ground points.

TerrainSpec

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 (N, 3).
provenance	dict[str, Any]	Origin and processing history for terrain.

Attributes

model_config class-attribute instance-attribute

model_config = ConfigDict(arbitrary_types_allowed=True)

name class-attribute instance-attribute

name: str = 'ground'

mesh_path class-attribute instance-attribute

mesh_path: Path | None = None

sample_points class-attribute instance-attribute

sample_points: FloatArray | None = None

provenance class-attribute instance-attribute

provenance: dict[str, Any] = Field(default_factory=dict)

Functions

estimate_clock_offset

estimate_clock_offset(
    reference_timeline: SampleTimeline,
    reference_signal: FloatArray,
    moving_timeline: SampleTimeline,
    moving_signal: FloatArray,
    config: TemporalRegistrationConfig,
    *,
    target_clock: str = "observation",
) -> AlignmentReport

Estimate an offset mapping moving_timeline into reference_timeline.

register_rigid_points

register_rigid_points(
    source: FloatArray, target: FloatArray, *, maximum_rms_error: float | None = None
) -> tuple[RigidTransform, AlignmentReport]

Estimate a Kabsch rigid transform from corresponding finite points.

convert_points_frame

convert_points_frame(
    points: Any, source: FrameConvention, target: FrameConvention
) -> FloatArray

Convert point coordinates between supported right-handed frame conventions.

Parameters:

Name	Type	Description	Default
points	Any	Array-like positions with trailing dimension 3.	required
source	FrameConvention	Convention of the input coordinates.	required
target	FrameConvention	Desired output convention.	required

Returns:

Name	Type	Description
FloatArray	FloatArray	Points re-expressed in target, preserving the input shape.

frame_transform_matrix

frame_transform_matrix(source: FrameConvention, target: FrameConvention) -> FloatArray

Return the rotation matrix that maps coordinates from source to target.

Parameters:

Name	Type	Description	Default
source	FrameConvention	Input coordinate convention.	required
target	FrameConvention	Output coordinate convention.	required

Returns:

Name	Type	Description
FloatArray	FloatArray	(3, 3) rotation matrix R with p_target = R @ p_source.

reorder_quaternion

reorder_quaternion(
    quaternion: ndarray, source: QuaternionOrder, target: QuaternionOrder
) -> ndarray

Convert quaternion storage order without changing the represented rotation.

Parameters:

Name	Type	Description	Default
quaternion	ndarray	Quaternion components in source layout.	required
source	QuaternionOrder	Storage order of quaternion.	required
target	QuaternionOrder	Desired storage order.	required

Returns:

Type	Description
ndarray	np.ndarray: Quaternion with the same rotation in target layout.

reorder_quaternions

reorder_quaternions(
    quaternions: Any,
    source: QuaternionOrder,
    target: QuaternionOrder,
    *,
    axis: int = -1,
) -> FloatArray

Convert quaternion storage order along one array axis.

Parameters:

Name	Type	Description	Default
quaternions	Any	Array-like quaternion components with length 4 along axis.	required
source	QuaternionOrder	Storage order of quaternions.	required
target	QuaternionOrder	Desired storage order.	required
axis	int	Axis containing quaternion components.	-1

Returns:

Name	Type	Description
FloatArray	FloatArray	Copy with the same rotations in target layout.

resample_linear

resample_linear(values: Any, source_fps: float, target_fps: float) -> FloatArray

Linearly resample an array whose first axis is time.

Parameters:

Name	Type	Description	Default
values	Any	Array-like data with time as axis 0.	required
source_fps	float	Source sampling rate in Hz.	required
target_fps	float	Target sampling rate in Hz.	required

Returns:

Name	Type	Description
FloatArray	FloatArray	Resampled array with the same trailing dimensions as values.

resampling_times

resampling_times(
    frame_count: int, source_fps: float, target_fps: float
) -> tuple[FloatArray, FloatArray]

Return source and target sample times for endpoint-preserving interpolation.

Parameters:

Name	Type	Description	Default
frame_count	int	Number of frames in the source sequence.	required
source_fps	float	Source sampling rate in Hz.	required
target_fps	float	Target sampling rate in Hz.	required

Returns:

Type	Description
tuple[FloatArray, FloatArray]	tuple[FloatArray, FloatArray]: (source_times, target_times) in seconds, with the final target time clamped to the source duration.

sample_mesh_points

sample_mesh_points(path: str | Path, *, count: int = 128) -> FloatArray

Return deterministic surface samples for a mesh file.

OBJ files are parsed without optional dependencies. Other mesh formats use trimesh when it is installed.

Parameters:

Name	Type	Description	Default
path	str | Path	Mesh file path (.obj or any format supported by trimesh).	required
count	int	Number of sample points to return.	128

Returns:

Name	Type	Description
FloatArray	FloatArray	Sampled points with shape (count, 3).

Raises:

Type	Description
ValueError	If count is not positive or the mesh geometry is invalid.
ImportError	If a non-OBJ format is requested without trimesh installed.

classify_foot_support

classify_foot_support(
    *,
    timeline: SampleTimeline,
    left_foot: PointTrack,
    right_foot: PointTrack,
    observed_object: PointTrack,
    left_subject: ContactSubject,
    right_subject: ContactSubject,
    left_patch: ContactPatch,
    right_patch: ContactPatch,
    states: FootSupportStates,
    config: FootSupportClassificationConfig | None = None,
) -> SemanticContactSequence

Classify feet as air, ground, or supported by an observed object.