Computes pose inverse kinematics for the given group and set of targets.
This implements a Jacobian-based Newton-Raphson IK solver. The random sequence used internally is deterministic: given the same inputs, the solver will always find the same solution.
Groups may contain mimic joints. The solver searches over the group's active joints only — seed and solution are laid out as RobotState::setJointGroupActivePositions() expects — and mimic joints follow their driving joint, both in the forward kinematics and in the Jacobian, so the returned solution places the tips correctly when the mimic joints are applied. Limitations: a mimic joint's own position limits are not enforced, only its driving joint's (a multiplier other than +/-1 or a non-zero offset can put the mimic joint outside its URDF range), and non-empty params.joint_costs are still rejected on groups with mimic joints.
- Parameters
-
| robot_state | A robot state, used to compute FK. It will be updated to the solution, if a solution is found, or arbitrarily if not. |
| group | The joint model group to compute IK for. |
| targets | The target poses to compute IK for. |
| seed | A joint configuration to be used as a first seed, before starting taking random configurations. |
| timeout | Search timeout in seconds. |
| validation_fn | Applied to a candidate solution; returning false discards it and the search resumes. It is only ever invoked with a configuration that has already converged on targets, so a candidate it refuses is one that reached them and was rejected. Callers can rely on that to tell a target that was unreachable from one that was reachable and unacceptable — a distinction the returned error message does not carry. It follows that an unreachable target never invokes it at all. |
| params | Other IK parameters like tolerance, etc. params.joint_costs optionally holds one cost multiplier per active joint of group, in JointModelGroup::getActiveJointModelNames() order. A joint's cost scales how expensive it is to move away from seed, so raising it biases the solver toward solutions that move that joint less. Every entry must be finite and at least 1.0, the unbiased baseline; an empty list means "no bias", and kMaxJointCost is the accepted maximum — see that constant for why. Prefer the smallest cost that produces the bias you want. Costs only take effect when params.solve_mode is optimize_distance — see the error note below. |
- Returns
- a joint-space solution that brings
tip_link to root_pose_tip, or an error message if the preconditions are not met. Supplying non-empty params.joint_costs with params.solve_mode == "first_found" is an error rather than a no-op: that mode returns the first valid solution without ranking candidates, so the costs would otherwise be silently discarded. For the same reason, non-empty costs combined with a params.optimization_distance_gain that is not finite and strictly positive are also an error: zero flattens every candidate's cost, and a negative gain reverses the bias. That gain remains valid at zero when no costs are supplied, which is what the parameter's own validation allows.
1.9.8