Protocols

Extension points implemented by backends, terms, loaders, and exporters.

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.

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.

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.

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.

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.

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.

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.

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

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.

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