Reference/API

Inverse Kinematics

class[source]
robokit.helpers.ik.IKSolver(
config: IKSolverConfig,
robot: Robot,
target_links: Union[str, int, Sequence[Union[str, int]]],
device: Optional[wp_device_type] = None,
scene: Optional[WarpScene] = None
)

IK solver accepting one target link or a sequence, using names or indices.

Parameters
configIKSolverConfigrequired
robotRobotrequired
target_linksUnion[str, int, Sequence[Union[str, int]]]required
deviceOptional[wp_device_type]= None
sceneOptional[WarpScene]= None
Members
attribute[source]
IKSolver.robot: Robot
attribute[source]
IKSolver.target_link_indices: List[int]
property[source]
IKSolver.num_targets: int
property[source]
IKSolver.num_solutions: int

Number of solutions returned per target instance.

method[source]
IKSolver.set_weight(
name: str,
value: Union[float, Sequence[float]]
)

Update a term's weight in-place: scalar for uniform, per-link sequence for terms on the target links.

Parameters
namestrrequired
valueUnion[float, Sequence[float]]required
method[source]
IKSolver.set_active_joint_mask(
joint_mask: Sequence[float]
)

Set which actuated joints are active (1.0) or locked (0.0).

Parameters
joint_maskSequence[float]required
method[source]
IKSolver.set_active_base_mask(
base_mask: Sequence[float]
)

Set active (1.0)/locked (0.0) base DOFs [x,y,z,roll,pitch,yaw]; needs enable_T_world_base=True.

Parameters
base_maskSequence[float]required
method[source]
IKSolver.warmup(
batch_size: int
)

Eagerly build the multi-candidate solver for a given batch size.

Parameters
batch_sizeintrequired
method[source]
IKSolver.solve(
T_world_target: wp.array,
prev_state: Optional[RobotState] = None,
init_state: Optional[RobotState] = None,
rest_state: Optional[RobotState] = None,
out_state: Optional[RobotState] = None,
init_sample_range: Optional[float] = None,
base_init_sample_range: Optional[Sequence[float]] = None,
scene_indices: Optional[wp.array] = None
) -> RobotState

Solve IK and return instance-major final-stage solutions shaped (batch * num_solutions, dofs); solver.rank_final=True sorts them best first within each instance.

Parameters
T_world_targetwp.arrayrequired
prev_stateOptional[RobotState]= None
init_stateOptional[RobotState]= None
rest_stateOptional[RobotState]= None
out_stateOptional[RobotState]= None
init_sample_rangeOptional[float]= None
base_init_sample_rangeOptional[Sequence[float]]= None
scene_indicesOptional[wp.array]= None
Returns
RobotState
method[source]
IKSolver.solve_torch(
T_world_target: torch.Tensor,
prev_state: Optional[RobotState] = None,
init_q: Optional[torch.Tensor] = None,
init_T_world_base: Optional[torch.Tensor] = None,
rest_q: Optional[torch.Tensor] = None,
rest_T_world_base: Optional[torch.Tensor] = None,
init_sample_range: Optional[float] = None,
base_init_sample_range: Optional[Sequence[float]] = None
) -> IKResultTorch
Parameters
T_world_targettorch.Tensorrequired
prev_stateOptional[RobotState]= None
init_qOptional[torch.Tensor]= None
init_T_world_baseOptional[torch.Tensor]= None
rest_qOptional[torch.Tensor]= None
rest_T_world_baseOptional[torch.Tensor]= None
init_sample_rangeOptional[float]= None
base_init_sample_rangeOptional[Sequence[float]]= None
Returns
IKResultTorch
method[source]
IKSolver.solve_numpy(
T_world_target: np.ndarray,
prev_state: Optional[RobotState] = None,
init_state: Optional[RobotState] = None,
rest_state: Optional[RobotState] = None,
out_state: Optional[RobotState] = None,
init_sample_range: Optional[float] = None,
base_init_sample_range: Optional[Sequence[float]] = None
) -> RobotState
Parameters
T_world_targetnp.ndarrayrequired
prev_stateOptional[RobotState]= None
init_stateOptional[RobotState]= None
rest_stateOptional[RobotState]= None
out_stateOptional[RobotState]= None
init_sample_rangeOptional[float]= None
base_init_sample_rangeOptional[Sequence[float]]= None
Returns
RobotState
method[source]
IKSolver.compute_costs(
state: RobotState,
T_world_target: wp.array,
prev_state: Optional[RobotState] = None,
scene_indices: Optional[wp.array] = None
) -> Dict[str, wp.array]
Parameters
stateRobotStaterequired
T_world_targetwp.arrayrequired
prev_stateOptional[RobotState]= None
scene_indicesOptional[wp.array]= None
Returns
Dict[str, wp.array]
method[source]
IKSolver.compute_metrics(
state: RobotState,
T_world_target: wp.array,
position_threshold_m: float = 0.005,
orientation_threshold_rad: float = 0.05,
out: Optional[IKMetrics] = None
) -> IKMetrics

Task-space accuracy of state against T_world_target, independent of term weights.

Parameters
stateRobotStaterequired

Robot state to score; any solver's output works, not just this one's.

T_world_targetwp.arrayrequired

[batch, num_targets] wp_vec7 targets on this solver's device.

position_threshold_mfloat= 0.005

Success threshold on translation error.

orientation_threshold_radfloat= 0.05

Success threshold on rotation error.

outOptional[IKMetrics]= None

Buffers to write in place, from an earlier call; allocated when omitted.

Returns
IKMetrics

Errors per target and per-batch success.

method[source]
IKSolver.compute_metrics_numpy(
state: RobotState,
T_world_target: np.ndarray,
position_threshold_m: float = 0.005,
orientation_threshold_rad: float = 0.05
) -> IKMetrics

compute_metrics for numpy targets shaped (7,), (batch, 7) or (batch, num_targets, 7).

Parameters
stateRobotStaterequired

Robot state to score; any solver's output works, not just this one's.

T_world_targetnp.ndarrayrequired

Targets as [x, y, z, q_w, q_x, q_y, q_z].

position_threshold_mfloat= 0.005

Success threshold on translation error.

orientation_threshold_radfloat= 0.05

Success threshold on rotation error.

Returns
IKMetrics

Errors per target and per-batch success, as numpy arrays.

class[source]
robokit.helpers.ik.IKSolverConfig(
terms: List[ResidualTask] = list(),
score_terms: List[ResidualTask] = list(),
solver: PopulationSolverConfig = _default_ik_solver_config(),
sampler: RobertsSamplerConfig = (lambda: RobertsSamplerConfig(keep_first=True))(),
base_init_sample_range: Tuple[float, float, float] = (0.1, 0.1, 0.0),
enable_T_world_base: bool = False,
base_active_mask: Sequence[float] = (1.0, 1.0, 1.0, 1.0, 1.0, 1.0)
)

Robot-free IK configuration; build it with IKSolver(config, robot, target_links).

Parameters
termsList[ResidualTask]= list()
score_termsList[ResidualTask]= list()
solverPopulationSolverConfig= _default_ik_solver_config()
samplerRobertsSamplerConfig= (lambda: RobertsSamplerConfig(keep_first=True))()
base_init_sample_rangeTuple[float, float, float]= (0.1, 0.1, 0.0)
enable_T_world_basebool= False
base_active_maskSequence[float]= (1.0, 1.0, 1.0, 1.0, 1.0, 1.0)
Members
attribute[source]
IKSolverConfig.terms: List[ResidualTask] = field(default_factory=list)

Optimization task templates; IKContext lists their inputs.

attribute[source]
IKSolverConfig.score_terms: List[ResidualTask] = field(default_factory=list)

Task templates that rank candidates at each select without changing optimization; empty ranks by cost.

attribute[source]
IKSolverConfig.solver: PopulationSolverConfig = field(default_factory=_default_ik_solver_config)

Candidate schedule and LM settings; the last segment's width is the solutions returned per target.

attribute[source]
IKSolverConfig.sampler: RobertsSamplerConfig = field(default_factory=lambda: RobertsSamplerConfig(keep_first=True))

Joint noise of the initial candidates; scale is a fraction of each joint's range around init_state.

attribute[source]
IKSolverConfig.base_init_sample_range: Tuple[float, float, float] = (0.1, 0.1, 0.0)

Per-axis base translation noise (m) around init_state, for a floating base.

attribute[source]
IKSolverConfig.enable_T_world_base: bool = False

Optimize the six floating-base DOFs along with the joints.

attribute[source]
IKSolverConfig.base_active_mask: Sequence[float] = (1.0, 1.0, 1.0, 1.0, 1.0, 1.0)

Active (1.0) or locked (0.0) base DOFs [x, y, z, roll, pitch, yaw]; locking needs enable_T_world_base.

method[source]
IKSolverConfig.add(
term: ResidualTask,
name: Optional[str] = None
) -> IKSolverConfig
Parameters
termResidualTaskrequired
nameOptional[str]= None
Returns
IKSolverConfig
method[source]
IKSolverConfig.add_score(
term: ResidualTask,
name: Optional[str] = None
) -> IKSolverConfig
Parameters
termResidualTaskrequired
nameOptional[str]= None
Returns
IKSolverConfig
method[source]
IKSolverConfig.task(
name: str
) -> ResidualTask

Return the term added under name, so a caller can complete a preset stub.

Parameters
namestrrequired
Returns
ResidualTask
class[source]
robokit.helpers.ik.IKResultTorch
Bases: NamedTuple
Members
attribute[source]
IKResultTorch.q: torch.Tensor
attribute[source]
IKResultTorch.T_world_base: Optional[torch.Tensor] = None