Pipeline

High-level API for defining and running retargeting jobs.

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.

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.

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.

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.

EngineOutput dataclass

EngineOutput(
    qpos: FloatArray,
    costs: FloatArray,
    iterations: tuple[int, ...],
    solver_backend: SolverKind,
    solver_statuses: tuple[str, ...],
    mesh_spec: InteractionMeshSpec,
    mesh_source: str,
    robot_link_names: tuple[str, ...] = (),
    robot_link_positions: FloatArray | None = None,
    warnings: tuple[str, ...] = (),
)

Raw output from the interaction-mesh engine.

Attributes:

Name	Type	Description
qpos	FloatArray	Retargeted generalized coordinates, shape (frames, nq).
costs	FloatArray	Per-frame subproblem cost after the last inner iteration.
iterations	tuple[int, ...]	Inner solver iterations used per frame.
solver_backend	SolverKind	Resolved typed registry key for the subproblem solver.
solver_statuses	tuple[str, ...]	Backend status string per frame.
mesh_spec	InteractionMeshSpec	Mesh topology used when building interaction graphs.
mesh_source	str	"engine" when a custom builder was injected; otherwise "problem".
robot_link_names	tuple[str, ...]	Link names for optional playback positions.
robot_link_positions	FloatArray | None	World positions (frames, links, 3) when computed.
warnings	tuple[str, ...]	Non-fatal issues encountered during the run.

Attributes

qpos instance-attribute

qpos: FloatArray

costs instance-attribute

costs: FloatArray

iterations instance-attribute

iterations: tuple[int, ...]

solver_backend instance-attribute

solver_backend: SolverKind

solver_statuses instance-attribute

solver_statuses: tuple[str, ...]

mesh_spec instance-attribute

mesh_spec: InteractionMeshSpec

mesh_source instance-attribute

mesh_source: str

robot_link_names class-attribute instance-attribute

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

robot_link_positions class-attribute instance-attribute

robot_link_positions: FloatArray | None = None

warnings class-attribute instance-attribute

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