Skip to main content

PathIKOptions Struct

Options passed to the Path Inverse Kinematics solver. More...

Declaration​

struct path_ik::PathIKOptions { ... }

Included Headers​

#include <path_ik.hpp>

Public Member Functions Index​

PathIKOptions &setBlendingRadius (double blending_radius)
PathIKOptions &setTipConstraint (TipConstraint tip_constraint)
PathIKOptions &setTipOffset (const Eigen::Isometry3d &tip_offset)
PathIKOptions &setJointLimitAvoidanceParameters (double activation_fraction, double gain)
PathIKOptions &setMaxOptimizerIterations (int max_iterations)
PathIKOptions &setTrackPathOrientationNullspaceTask (double gain)
PathIKOptions &setMaxAllowedPathDeviation (double translation, double rotation)

Sets the maximum allowed path deviation tolerances in Cartesian space for the primary task (constraint). More...

PathIKOptions &setGoalTolerance (double translation, double rotation)

Sets the tolerances that the final path waypoint (the goal) must satisfy. More...

PathIKOptions &setNullspaceOverrideFunction (const NullspaceOverrideFunction &function)

Set a nullspace override function. More...

PathIKOptions &setJacobianInverseDamping (double damping)

Set the Jacobian inverse damping factor used for solving the path inverse kinematics. More...

Public Member Attributes Index​

doubleblending_radius = kDefaultBlendingRadius
TipConstrainttip_constraint = TipConstraint::kPositionOnly
Eigen::Isometry3dtip_offset = Eigen::Isometry3d::Identity()
doublejoint_limit_cost_activation_fraction = kDefaultJointLimitCostActivationFraction
doublejoint_limit_cost_gain = kDefaultJointLimitCostGain
intmax_optimizer_iterations = kDefaultMaxOptimizerIterations
doubletrack_path_orientation_gain = 0.0
doublemax_allowed_path_deviation_translation = kDefaultMaxAllowedPathDeviationTranslation
doublemax_allowed_path_deviation_rotation = kDefaultMaxAllowedPathDeviationRotation
NullspaceOverrideFunctioncustom_nullspace_task
doublejacobian_inverse_damping = kDefaultJacobianInverseDamping
std::optional< GoalTolerance >goal_tolerance

Public Static Attributes Index​

static constexpr doublekDefaultBlendingRadius = 0.001
static constexpr TipConstraintkDefaultTipConstraint = TipConstraint::kPositionOnly
static constexpr doublekDefaultJointLimitCostActivationFraction = 0.05
static constexpr doublekDefaultJointLimitCostGain = 0.4
static constexpr intkDefaultMaxOptimizerIterations = 1
static constexpr doublekDefaultMaxAllowedPathDeviationTranslation = 0.001
static constexpr doublekDefaultMaxAllowedPathDeviationRotation = 0.001
static constexpr doublekDefaultJacobianInverseDamping = 0.001

Description​

Options passed to the Path Inverse Kinematics solver.

Use method chaining for in-line construction and modification, e.g: pathIK(..., PathIKOptions().setBlendingRadius(0.1), ...);

Definition at line 71 of file path_ik.hpp.

Public Member Functions​

setBlendingRadius()​

PathIKOptions & path_ik::PathIKOptions::setBlendingRadius (double blending_radius)
 inline

Definition at line 98 of file path_ik.hpp.

setGoalTolerance()​

PathIKOptions & path_ik::PathIKOptions::setGoalTolerance (double translation, double rotation)
 inline

Sets the tolerances that the final path waypoint (the goal) must satisfy.

The maximum allowed path deviation applies to every point on the dense path, so loosening it (e.g. to allow deviating near a singularity) also loosens the accuracy guarantee at the goal. Setting a goal tolerance restores that guarantee: after solving the final waypoint, the solver runs extra refinement iterations until the tip error at the goal is within the given tolerances, and fails (returning the partial path) if they cannot be met. The refinement iteration budget is bounded; raising max_optimizer_iterations above the built-in floor extends it, which is the recourse for slowly converging (e.g. heavily damped) solves that run out of budget. Raising it also raises the per-waypoint iteration cap for the whole path, which is expensive on long paths. Refinement updates the final joint-space waypoint in place, preserving a one-to-one correspondence between the dense Cartesian path and the returned joint-space path. The goal is each tip's reference pose at the final path waypoint: when the reference path does not start at the tip, that is the final path pose composed with the tip's initial offset from the path start (see pathIK()), not the raw final path pose.

The goal tolerance is enforced in addition to the maximum allowed path deviation, which still applies at every point, including the goal and during the refinement iterations. A goal tolerance larger than the maximum allowed path deviation therefore has no effect.

Nullspace tasks keep acting during the refinement iterations and can hold the tip error at an equilibrium above a tight tolerance, especially with high Jacobian damping.

Goal tolerance enforcement is disabled by default. A tolerance of infinity leaves that component unconstrained.

If tip_constraint is kPositionAndOrientation, both translation and rotation tolerances are enforced. If tip_constraint is kPositionOnly, only the translation tolerance is enforced: set the rotation tolerance to infinity. In that mode, an orientation tracking task (setTrackPathOrientationNullspaceTask) keeps adjusting the tip orientation during the refinement iterations, unbounded by either the goal tolerance or the path deviation check.

The tolerance bounds the planned path only: the accuracy of the executed motion additionally depends on how well the controller tracks the trajectory.

Parameters
translation

Maximum allowed translation error at the goal, in meters. Must be greater than zero; infinity leaves translation unconstrained.

rotation

Maximum allowed rotation error at the goal, in radians. Must be greater than zero; infinity leaves rotation unconstrained.

Definition at line 201 of file path_ik.hpp.

setJacobianInverseDamping()​

PathIKOptions & path_ik::PathIKOptions::setJacobianInverseDamping (double damping)
 inline

Set the Jacobian inverse damping factor used for solving the path inverse kinematics.

A higher damping factor will make the solver more robust to singularities, but may result in slower convergence. A lower damping factor will make the solver converge faster, but may cause it to fail to find a solution near singularities. The default value is 0.001, which should be a good balance for most cases.

Definition at line 238 of file path_ik.hpp.

setJointLimitAvoidanceParameters()​

PathIKOptions & path_ik::PathIKOptions::setJointLimitAvoidanceParameters (double activation_fraction, double gain)
 inline

Definition at line 116 of file path_ik.hpp.

setMaxAllowedPathDeviation()​

PathIKOptions & path_ik::PathIKOptions::setMaxAllowedPathDeviation (double translation, double rotation)
 inline

Sets the maximum allowed path deviation tolerances in Cartesian space for the primary task (constraint).

These tolerances are checked at every point along the dense interpolated path, including the destination. After each IK iteration at each waypoint, the solver computes the Cartesian error between the solved tip pose and the desired reference pose. If either component exceeds its tolerance, the solver immediately fails and returns the partial path solved so far.

The solver does NOT automatically relax tolerances. It is fail-fast: it either meets the tolerance at every point or returns an error. To allow more deviation, increase these values explicitly.

If tip_constraint is kPositionAndOrientation, both translation and rotation tolerances are enforced. If tip_constraint is kPositionOnly, only the translation tolerance is enforced (rotation is unconstrained, and can be potentially controlled by a nullspace task, see setTrackPathOrientationNullspaceTask).

To keep a tighter error bound at the final waypoint when these tolerances are loosened, see setGoalTolerance().

Parameters
translation

Maximum allowed translation deviation in meters. Default: 0.001 m (1 mm).

rotation

Maximum allowed rotation deviation in radians. Default: 0.001 rad (~0.057 degrees).

Definition at line 156 of file path_ik.hpp.

setMaxOptimizerIterations()​

PathIKOptions & path_ik::PathIKOptions::setMaxOptimizerIterations (int max_iterations)
 inline

Definition at line 123 of file path_ik.hpp.

setNullspaceOverrideFunction()​

PathIKOptions & path_ik::PathIKOptions::setNullspaceOverrideFunction (const NullspaceOverrideFunction & function)
 inline

Set a nullspace override function.

This allows users to inject custom nullspace costs into the path IK solver. The function is called after the built-in nullspace tasks (joint limit avoidance, orientation tracking) have been computed, and can modify or replace the nullspace component. It takes the current nullspace component and the current joint values as input, and should return the modified nullspace component.

Example usage:

 options.setNullspaceOverrideFunction(
  [](const Eigen::VectorXd& nullspace, const Eigen::VectorXd& joints) {
  // Add a custom cost to keep joint 3 near zero.
  Eigen::VectorXd modified = nullspace;
  modified[3] += -0.01 * joints[3];
  return modified;
  });

Definition at line 226 of file path_ik.hpp.

setTipConstraint()​

PathIKOptions & path_ik::PathIKOptions::setTipConstraint (TipConstraint tip_constraint)
 inline

Definition at line 104 of file path_ik.hpp.

setTipOffset()​

PathIKOptions & path_ik::PathIKOptions::setTipOffset (const Eigen::Isometry3d & tip_offset)
 inline

Definition at line 110 of file path_ik.hpp.

setTrackPathOrientationNullspaceTask()​

PathIKOptions & path_ik::PathIKOptions::setTrackPathOrientationNullspaceTask (double gain)
 inline

Definition at line 131 of file path_ik.hpp.

Public Member Attributes​

blending_radius​

double path_ik::PathIKOptions::blending_radius = kDefaultBlendingRadius

Definition at line 245 of file path_ik.hpp.

custom_nullspace_task​

NullspaceOverrideFunction path_ik::PathIKOptions::custom_nullspace_task

Definition at line 276 of file path_ik.hpp.

goal_tolerance​

std::optional<GoalTolerance> path_ik::PathIKOptions::goal_tolerance

Definition at line 283 of file path_ik.hpp.

jacobian_inverse_damping​

double path_ik::PathIKOptions::jacobian_inverse_damping = kDefaultJacobianInverseDamping

Definition at line 279 of file path_ik.hpp.

joint_limit_cost_activation_fraction​

double path_ik::PathIKOptions::joint_limit_cost_activation_fraction = kDefaultJointLimitCostActivationFraction

Definition at line 254 of file path_ik.hpp.

joint_limit_cost_gain​

double path_ik::PathIKOptions::joint_limit_cost_gain = kDefaultJointLimitCostGain

Definition at line 255 of file path_ik.hpp.

max_allowed_path_deviation_rotation​

double path_ik::PathIKOptions::max_allowed_path_deviation_rotation = kDefaultMaxAllowedPathDeviationRotation

Definition at line 272 of file path_ik.hpp.

max_allowed_path_deviation_translation​

double path_ik::PathIKOptions::max_allowed_path_deviation_translation = kDefaultMaxAllowedPathDeviationTranslation

Definition at line 271 of file path_ik.hpp.

max_optimizer_iterations​

int path_ik::PathIKOptions::max_optimizer_iterations = kDefaultMaxOptimizerIterations

Definition at line 262 of file path_ik.hpp.

tip_constraint​

TipConstraint path_ik::PathIKOptions::tip_constraint = TipConstraint::kPositionOnly

Definition at line 248 of file path_ik.hpp.

tip_offset​

Eigen::Isometry3d path_ik::PathIKOptions::tip_offset = Eigen::Isometry3d::Identity()

Definition at line 251 of file path_ik.hpp.

track_path_orientation_gain​

double path_ik::PathIKOptions::track_path_orientation_gain = 0.0

Definition at line 267 of file path_ik.hpp.

Public Static Attributes​

kDefaultBlendingRadius​

constexpr double path_ik::PathIKOptions::kDefaultBlendingRadius = 0.001
 constexpr static

Definition at line 75 of file path_ik.hpp.

kDefaultJacobianInverseDamping​

constexpr double path_ik::PathIKOptions::kDefaultJacobianInverseDamping = 0.001
 constexpr static

Definition at line 96 of file path_ik.hpp.

kDefaultJointLimitCostActivationFraction​

constexpr double path_ik::PathIKOptions::kDefaultJointLimitCostActivationFraction = 0.05
 constexpr static

Definition at line 82 of file path_ik.hpp.

kDefaultJointLimitCostGain​

constexpr double path_ik::PathIKOptions::kDefaultJointLimitCostGain = 0.4
 constexpr static

Definition at line 83 of file path_ik.hpp.

kDefaultMaxAllowedPathDeviationRotation​

constexpr double path_ik::PathIKOptions::kDefaultMaxAllowedPathDeviationRotation = 0.001
 constexpr static

Definition at line 91 of file path_ik.hpp.

kDefaultMaxAllowedPathDeviationTranslation​

constexpr double path_ik::PathIKOptions::kDefaultMaxAllowedPathDeviationTranslation = 0.001
 constexpr static

Definition at line 90 of file path_ik.hpp.

kDefaultMaxOptimizerIterations​

constexpr int path_ik::PathIKOptions::kDefaultMaxOptimizerIterations = 1
 constexpr static

Definition at line 86 of file path_ik.hpp.

kDefaultTipConstraint​

constexpr TipConstraint path_ik::PathIKOptions::kDefaultTipConstraint = TipConstraint::kPositionOnly
 constexpr static

Definition at line 78 of file path_ik.hpp.

The documentation for this struct was generated from the following file:

Generated via doxygen2docusaurus 2.2.2 by Doxygen 1.9.8.