Class FrameToFrameJacobianGenerator

Class FrameToFrameJacobianGenerator#

Inheritance Relationships#

Base Type#

Class Documentation#

class FrameToFrameJacobianGenerator : public Karana::Core::LockingBase#

Class for computing relative Jacobians and pose gradients for a frame pair defined by a Karana::Frame::FrameToFrame.

The source and target frames for the Jacobian are the oframe/pframe Karana::Frame::Frame pair for the Karana::Frame::FrameToFrame provided to the constructor. See the

Jacobians section for more discussion on Jacobians.

CAUTION: When using the “analytical” computation approach (recommended), an important assumption is that the f2f path contains only regular edges, i.e. one whose transform values that depend on coordinate values do so via regular subhinges and body coordinates, and not in come non-standard way (e.g., subtree CM frames, ephemeris frames). Since this Jacobian generator will not know about these non-standard dependencies, it will not be able to take them into account when computing the Jacobians, so use the “numerical” approach for these situations.

Public Functions

FrameToFrameJacobianGenerator(std::string_view name, kc::ks_ptr<kf::FrameToFrame> f2f, kc::ks_ptr<CoordData> coord_data)#

Constructor.

Constructor for the FrameToFrameJacobianGenerator. Once created, this object can be used repeatedly to compute the configuration dependent Jacobian and pose gradient matrices for different poses. The returned matrices are for the f2f’s pframe with respect to its oframe. While the common use case is with the source frame being the inertial frame, this object supports the more general case where the source frame may be attached to another moving body in the system.

The computed jacobian matrices do not include columns for the frozen coords in the CoordData. An alternative option would be to set the columns to zero values, but this is non-optimal since the column values would need to be computed (only to be discarded), and the returned matrix would be larger.

Parameters:
inline virtual std::string_view typeString() const noexcept override#

Returns the type string of Base.

Returns:

The type string.

km::Mat jacobian(bool analytical = true)#

Method to compute the Jacobian matrix.

Return the overall assembled 6xnU Jacobian to the target frame spatial velocity (represented in the target frame) with respect to the path map’s source frame from the U generalized velocities of all the component coordinate providers. Use the component analytical Jacobians if analytical is true, or the numerical differencing approach otherwise. If not provided, the source frame is assumed to be the newtonian frame. This Jacobian is such that the following will be true:

f2f.relSpVel() == f2f.relTransform().getUnitQuaternion() (jac * getU())

The input polarity map must be compatible with the same source/target frame values used when calling this method. It will be created if it is not provided. Coordinate providers not in the polarity map are assumed to not have an effect on the target frame, and zero sub-matrix entries are assigned for them.

For normal inverse kinematics (e.g., with respect to inertial frame), we normally exclude coordinate providers that are outboard of (or on a separate branch from) the target frame of interest.

Otherwise, the polarity map value for each coordinate provider is used to negate the sub-matrix entries for the ones with opposed polarity. We include such opposed polarity coordinate provider elements for cases where the source frame is not the inertial frame, and the coordinate provider is on the path from the source to the target frame, but may be on a different branch and o the path from the source frame to the common ancestor frame. In this case, the coordinate provider’s effect is the negative of the normal effect on the target frame.

Parameters:

analytical – If true, use the analytical process, else numerical differencing

Returns:

the Jacobian matrix

km::Mat jacobianDot()#

Method to compute the time derivative of the Jacobian matrix.

Returns:

the time derivative of the Jacobian matrix

km::Mat poseGradient(bool analytical = true)#

Method to compute the pose gradient matrix.

Return the overall assembled 6xnU gradient for the target frame pose with respect to the Q generalized coordinates of all the component coordinate providers. Use the component analytical gradient contributions if analytical is true, or the numerical differencing approach otherwise.

The input polarity map must be compatible with the same source/target frame values used when calling this method. It will be created if it is not provided. Coordinate providers not in the polarity map are assumed to not have an effect on the target frame, and zero sub-matrix entries are assigned for them. For normal inverse kinematics (e.g., with respect to inertial frame), we exclude coordinate providers that are outboard of (or on a separate branch from) the target frame of interest.

Otherwise, the polarity map value for each coordinate provider is used to negate the sub-matrix entries for the ones with opposed polarity. We include such opposed polarity coordinate provider elements for cases where the source frame is not the inertial frame, and the coordinate provider is on the path from the source to the target frame, but may be on a different branch and o the path from the source frame to the common ancestor frame. In this case, the coordinate provider’s effect is the negative of the normal effect on the target frame.

We can choose to eliminate some columns from the computed matrix by specifying the corresponding coordinate providers in the skip_coords list. An alternative option is to set the columns to zero values, but this is non-optimal since the column values would need to be computed (only to be discarded), and the returned matrix would be larger.

Parameters:

analytical – If true, use the analytical process, else numerical differencing

Returns:

the pose gradient matrix

Public Static Functions

static kc::ks_ptr<FrameToFrameJacobianGenerator> create(std::string_view name, kc::ks_ptr<kf::FrameToFrame> f_to_f, kc::ks_ptr<CoordData> coord_data)#

Factory method for creating a FrameToFrameJacobianGenerator.

Parameters:

  • name – name for the new object

  • f_to_f – the Karana::Frame::FrameToFrame instance to compute the relative Jacobian for

  • coord_data – the list of CoordData with the coordinates

Returns:

the new FrameToFrameJacobianGenerator instance

Protected Functions

inline const std::unordered_map<kc::id_t, bool> &_getPolarityMap() const#

Compute the polarities for all the coordinates.

Returns:

the polarity map

void _setupPolarityMap()#

For the subhinges in this CoordData, a polarity map with bool entries for the component subhinges. Set the entry to true if the subhinge’s edge direction is aligned with the f2f path. Add a false entry if include_opposed is true. Skip adding an entry for the subhinge if the subhinge edge does not lie in the path. The polarity map is used to limit the subhinge entries of interest to just those on the f2f path when assembling the Jacobian for the target frame (see the jacobian method).

This polarity map is used for assembling the Jacobian matrix for the f2f path. A true entry for a subhinge means that subhinge’s Jacobian to the target should be used as is since the pframe is outboard of the coord. When the target frame is not outboard, i.e. we have opposite polarity and the negative of the contributing subhinge Jacobian matrix should be used.

virtual void _makeCurrent() override#

Derived classes override this to define how to make themselves current.

void _discard(kc::ks_ptr<Base> &base) override#

Discard the provided FrameToFrameJacobianGenerator.

Parameters:

base – - Base pointer to the FrameToFrameJacobianGenerator to discard.

Protected Attributes

kc::ks_ptr<kf::FrameToFrame> _f2f = nullptr#
std::unordered_map<kc::id_t, bool> _polarity_map#
kc::ks_ptr<CoordData> _coord_data#
Contents