Main Page Modules Namespace List Class Hierarchy Alphabetical List Compound List File List Namespace Members Compound Members File Members Related Pages

OSCAR::KinematicsHandler Class Reference
[InverseKinematics]

KinematicsHandler describes an abstract class for computing the forward and inverse kinematics of serial robot arms. This class also checks for position limits. User should derive a specific class from this or use the GeneralKinematicsHandler class that is derived from KinematicsHandler. This class and dervied classes implement functionality that computes the forward and inverse position solution. It also checks joint travel limits and singularities. Objects of this class will always maintain a valid joint state and the corresponding cartesian state. Inputs that violate position limits or lead to singularities will not lead to an erroneous state of the system. More...

#include <KinematicsHandler.h>

Inheritance diagram for OSCAR::KinematicsHandler:

[legend]List of all members.


Public Methods
	KinematicsHandler (const OSCAR::DHData &dhData, const OSCAR::Vector &offset, const OSCAR::Limits &limits, OSCAR::OSCARError &err=DUMMY_ERROR(OSCAR::noError))
virtual	~KinematicsHandler ()
virtual bool	Initialize (const OSCAR::JointVector &initialJoints, OSCAR::AngleUnits angle=OSCAR::Radians)
virtual void	SetPartCoordinates (const OSCAR::Xform &partCoordinates)
virtual const OSCAR::Xform &	GetPartCoordinates () const
virtual void	SetCartesianCoordinates (CartesianCoordinateMode cartesianControlMode)
virtual CartesianCoordinateMode	GetCartesianCoordinates () const
virtual bool	GetJointState (OSCAR::JointVector &currentJointPosition, OSCAR::AngleUnits angle=OSCAR::Radians)
virtual bool	GetCartesianState (OSCAR::Xform &currentCartesianCoordinates)
virtual bool	GetCartesianState (OSCAR::HandPose &currentHand, OSCAR::AngleUnits angle=OSCAR::Radians)
virtual bool	UpdateJointState (const OSCAR::Xform &targetHand)=0
virtual bool	UpdateJointState (const OSCAR::HandPose &targetHand, OSCAR::AngleUnits angle=OSCAR::Radians)=0
virtual bool	UpdateHandState (const OSCAR::JointVector &targetJoints, OSCAR::AngleUnits angle=OSCAR::Radians)=0
bool	IsLimitCheckingEnabled () const
void	EnableLimitChecking (bool enable)
const std::vector< bool > &	GetLimitViolationDetails (OSCAR::String &description) const
unsigned int	GetDOF () const
virtual bool	SetTool (const OSCAR::Xform &_toolPose)
virtual bool	SetBase (const OSCAR::Xform &_basePose)
virtual OSCAR::Xform	GetTool () const
virtual OSCAR::Xform	GetBase () const
virtual bool	ComputeFK (const JointVector &inputJointPosition, Xform &handPosition, OSCAR::AngleUnits=Radians)=0
virtual bool	ComputeFK (const JointVector &inputJointPosition, HandPose &handPosition, OSCAR::AngleUnits=Radians)=0
virtual bool	ComputeIK (const HandPose &inputHandPosition, JointVector &jointPosition, OSCAR::AngleUnits=Radians, bool Interpolate=false)=0
virtual bool	ComputeIK (const Xform &inputHandPosition, JointVector &jointPosition, OSCAR::AngleUnits=Radians, bool Interpolate=false)=0
Protected Methods
bool	makeOffsetAdjustment (OSCAR::Vector &jointPos, bool toDHReference=true)
bool	checkJointPositionLimits (const OSCAR::JointVector &jointValues)
bool	convertJointUnits (OSCAR::Vector &jointValues, bool toRadians=true) const
	KinematicsHandler (const KinematicsHandler &)
Protected Attributes
bool	limitCheck
unsigned int	DOF
CartesianCoordinateMode	cartesianCoordinateMode
OSCAR::DHData	dhData
OSCAR::JointVector *	currentPosition
OSCAR::JointVector *	previousPosition
OSCAR::Vector *	offset
OSCAR::Xform	currentHand
OSCAR::Xform	previousHand
OSCAR::Xform	toolPose
OSCAR::Xform	basePose
OSCAR::Xform	partPose
OSCAR::Limits *	positionLimits
std::vector< bool >	limitStatus
OSCAR::String	limitViolationDescription

Detailed Description

Author:: Chetan Kapoor

Constructor & Destructor Documentation

OSCAR::KinematicsHandler::KinematicsHandler ( const OSCAR::DHData & dhData,

const OSCAR::Vector & offset,

const OSCAR::Limits & limits,

OSCAR::OSCARError & err = DUMMY_ERROR(OSCAR::noError)

)

Constructor. TODO: Limits are expressed in Degrees while everything else defaults to Radians. This is the constructor for an object of type KinematicsHandler. This is an abstract class and cannot be instantiated.

Parameters:

dhData A DHData object that defines the DH parameters for the robot. The units of angles in the DHData should be Degrees. The robot DOF is determined from dhData.

offset A vector whose size should match the DOF defined in the dhData parameter. The values of offset should define the offset between the zero position of the robot as defined by the DH parameters and as represented by the physical robot zero position. Offset should be defined in Degrees for all joints that are revolute. If the DH paramater defined 0 position is the same as the real robot zero position, then all offsets will be zero.

limits A Limits object that defines the position travel limits of the robot arm. The size of the limits object should be the same as the DOF defined in the dhData parameter. The limits should also be expressed in the robot coordinates instead of the DH parameter coordinates. For all revolute joints, the limits should be expressed in Degrees.

err An OSCARError object that on return will hold the value of any errors that were generated during the constructor call. If err is not equal to 'noError' you can call GetError() to get the details of the error code.

Exceptions:

argumentSizeIncorrect argumentSizeIncorrect. This error is generated when the size of the input parameter offset and limits does not match the DOF defined by the dhData parameter.

virtual OSCAR::KinematicsHandler::~KinematicsHandler ( ) [virtual]

OSCAR::KinematicsHandler::KinematicsHandler ( const KinematicsHandler & ) [protected]

Member Function Documentation

bool OSCAR::KinematicsHandler::checkJointPositionLimits ( const OSCAR::JointVector & jointValues ) [protected]

virtual bool OSCAR::KinematicsHandler::ComputeFK ( const JointVector & inputJointPosition,

HandPose & handPosition,

OSCAR::AngleUnits = Radians

) [pure virtual]

Computes the forward position solution without altering the joint state or the cartesian state of the robot.

Parameters:

inputJointPosition A JointVector of size DOF for which the corresponding carteisan position is computed. This parameter is bound checked only in Debug mode (#define _DEBUG). The units of revolute joint positions should be specified in the angle parameter.

handPosition A HandPose that holds the computed hand position. Bt default, the orientation is computed in radians. The angle parameter can be used to specify the units in which the orientation should be computed.

angle Specifies whether the inputJointPosition is in Degrees or Radians. It also specifies the units in which the orientation of component of handPosition is computed. Default is Radians.

Returns:
true if no error. false if error.

Implemented in OSCAR::GeneralKinematicsHandler.

virtual bool OSCAR::KinematicsHandler::ComputeFK ( const JointVector & inputJointPosition,

Xform & handPosition,

OSCAR::AngleUnits = Radians

) [pure virtual]

Computes the forward position solution without altering the joint state or the cartesian state of the robot.

Parameters:

inputJointPosition A JointVector of size DOF for which the corresponding carteisan position is computed. This parameter is bound checked only in Debug mode (#define _DEBUG). The units of revolute joint positions should be specified in the angle parameter.

handPosition An Xform holding the computed hand position.

angle Specifies whether the inputJointPosition is in Degrees or Radians. Default is Radians.

Returns:
true if no error. false if error.

Implemented in OSCAR::GeneralKinematicsHandler.

virtual bool OSCAR::KinematicsHandler::ComputeIK ( const Xform & inputHandPosition,

JointVector & jointPosition,

OSCAR::AngleUnits = Radians,

bool Interpolate = false

) [pure virtual]

Computes the inverse position solution without altering the joint state or the cartesian state of the robot.

Parameters:

inputHandPosition A HandPose for which the corresponding joint position is computed. The units in which the orientation is expressedshould be specified in the angle parameter.

jointPosition A JointVector of size DOF that holds the computed joint position. Bt default, the joint position of the revolute joints is computed in radians. The angle parameter can be used to specify the units in which the revolute joint positions should be computed. This parameter is bound checked only in Debug mode (#define _DEBUG).

angle Specifies whether the inputHandPosition orientation is in Degrees or Radians. It also specifies the units in which the revolute joint positions of are computed. Default is Radians.

interpolate Use this parameter to specify whether the IK should iterate and jog towards the inputHandPosition (from the current Hand state). This is useful if the inverse algorithm is iterative. It will not be relevant for closed form inverses. Default is false, i.e., do not interpolate.

Returns:
true if no error. false if error.

Implemented in OSCAR::GeneralKinematicsHandler, and OSCAR::RedundantKinematicsHandler.

virtual bool OSCAR::KinematicsHandler::ComputeIK ( const HandPose & inputHandPosition,

JointVector & jointPosition,

OSCAR::AngleUnits = Radians,

bool Interpolate = false

) [pure virtual]

Computes the inverse position solution without altering the joint state or the cartesian state of the robot.

Parameters:

inputHandPosition A HandPose for which the corresponding joint position is computed. The units in which the orientation is expressedshould be specified in the angle parameter.

jointPosition A JointVector of size DOF that holds the computed joint position. Bt default, the joint position of the revolute joints is computed in radians. The angle parameter can be used to specify the units in which the revolute joint positions should be computed. This parameter is bound checked only in Debug mode (#define _DEBUG).

angle Specifies whether the inputHandPosition orientation is in Degrees or Radians. It also specifies the units in which the revolute joint positions of are computed. Default is Radians.

interpolate Use this parameter to specify whether the IK should iterate and jog towards the inputHandPosition (from the current Hand state). This is useful if the inverse algorithm is iterative. It will not be relevant for closed form inverses. Default is false, i.e., do not interpolate.

Returns:
true if no error. false if error.

Implemented in OSCAR::GeneralKinematicsHandler, and OSCAR::RedundantKinematicsHandler.

bool OSCAR::KinematicsHandler::convertJointUnits ( OSCAR::Vector & jointValues,

bool toRadians = true

) const [protected]

void OSCAR::KinematicsHandler::EnableLimitChecking ( bool enable ) [inline]

virtual OSCAR::Xform OSCAR::KinematicsHandler::GetBase ( ) const [inline, virtual]

virtual CartesianCoordinateMode OSCAR::KinematicsHandler::GetCartesianCoordinates ( ) const [virtual]

Get the current coordinate frame for cartesian positions. Specifies whether the cartesian position is currently computed (or input) in World, Tool or Part coordinates.

virtual bool OSCAR::KinematicsHandler::GetCartesianState ( OSCAR::HandPose & currentHand,

OSCAR::AngleUnits angle = OSCAR::Radians

) [virtual]

Get the current cartesian state of the robot.

Parameters:

currentHand A HandPose with orientation expressed as FixedXYZ that holds the current cartesian position of the robot. This cartesian position will be in either World, Tool, or Part coordinates, as specified by the SetCartesianCoordinates(..) method.

angle Specifies whether the return value is in Degrees or Radians. Based on this, the orientation component of the return value is converted.

Returns:
true if no error. false if error.

virtual bool OSCAR::KinematicsHandler::GetCartesianState ( OSCAR::Xform & currentCartesianCoordinates ) [virtual]

Get the current cartesian state of the robot.

Parameters:

currentCartesianCoordinates An Xform that on return will hold the current cartesian position of the robot. This cartesian position will be in either World, Tool, or Part coordinates, as specified by the SetCartesianCoordinates(..) method.

Returns:
A true if no error. false if error.

unsigned int OSCAR::KinematicsHandler::GetDOF ( void ) const [inline]

Get the degrees of freedom (DOF) associated with the object.

Returns:
unsigned int specifying the DOF of the robot. This information is derived from the DHData parameter passed during construction.

virtual bool OSCAR::KinematicsHandler::GetJointState ( OSCAR::JointVector & currentJointPosition,

OSCAR::AngleUnits angle = OSCAR::Radians

) [virtual]

Get the current joint position of the robot.
currentJointPosition A JointVector of size DOF that on return holds the current joint position of the robot in robot coordinates. This is a valid joint position that has been checked for position limit violations.
Parameters:

angle Specifies whether the return value is in Degrees or Radians.

Returns:
true if no error. 0 if an error.

const std::vector<bool>& OSCAR::KinematicsHandler::GetLimitViolationDetails ( OSCAR::String & description ) const [inline]

virtual const OSCAR::Xform& OSCAR::KinematicsHandler::GetPartCoordinates ( ) const [virtual]

Queries the part coordinates.

Returns:
An Xform that defines the position and orientation of the workpiece in the robot base frame. By default, the robot base frame is at the first (zeroth) DH frame. However, the robot base frame can be set to any location by using the SetBase method.

virtual OSCAR::Xform OSCAR::KinematicsHandler::GetTool ( ) const [inline, virtual]

virtual bool OSCAR::KinematicsHandler::Initialize ( const OSCAR::JointVector & initialJoints,

OSCAR::AngleUnits angle = OSCAR::Radians

) [virtual]

Sets the initial state of the object. This method should be called prior to any other calls. Use this methoid to initialize the object with the initial position of the robot. The current hand position and current joint position of the robot is accordingly updated.

Parameters:

initialJoints A JointVector object of size DOF that specifies the starting position of the robot. The revolute joints can be expressed in Degrees or Radians. The size of the initialJoints is bound checked only in debug mode (#define _DEBUG). In release mode, program will fail.

angle Specifies the units used to express the position of revolute joints in the initialJoints parameter.

Exceptions:

argumentSizeIncorrect argumentSizeIncorrect. This error is generated when the size of the input parameter initialJoints does not match the DOF defined by the dhData parameter. This error is only generated in _DEBUG mode.

Reimplemented in OSCAR::GeneralKinematicsHandler.

bool OSCAR::KinematicsHandler::IsLimitCheckingEnabled ( ) const [inline]

bool OSCAR::KinematicsHandler::makeOffsetAdjustment ( OSCAR::Vector & jointPos,

bool toDHReference = true

) [protected]

virtual bool OSCAR::KinematicsHandler::SetBase ( const OSCAR::Xform & _basePose ) [inline, virtual]

Reimplemented in OSCAR::GeneralKinematicsHandler.

virtual void OSCAR::KinematicsHandler::SetCartesianCoordinates ( CartesianCoordinateMode cartesianControlMode ) [virtual]

Set the coordinate frame in which cartesian positions are specified.

Parameters:

cartesianControlMode Specifies whether the cartesian position is computed (or input) in World, Tool or Part coordinates.

virtual void OSCAR::KinematicsHandler::SetPartCoordinates ( const OSCAR::Xform & partCoordinates ) [virtual]

Defines the position and orientation of the part as expressed in the base frame of the robot.

Parameters:

partCoordinates An Xform that defines the position and orientation of the workpiece in the robot base frame. By default, the robot base frame is at the first (zeroth) DH frame. However, the robot base frame can be set to any location by using the SetBase method.

virtual bool OSCAR::KinematicsHandler::SetTool ( const OSCAR::Xform & _toolPose ) [inline, virtual]

Reimplemented in OSCAR::GeneralKinematicsHandler.

virtual bool OSCAR::KinematicsHandler::UpdateHandState ( const OSCAR::JointVector & targetJoints,

OSCAR::AngleUnits angle = OSCAR::Radians

) [pure virtual]

child classes should implement this.
Basically, perform FK. Implementation should check for limits if limitCheck is set to true
Implemented in OSCAR::GeneralKinematicsHandler.

virtual bool OSCAR::KinematicsHandler::UpdateJointState ( const OSCAR::HandPose & targetHand,

OSCAR::AngleUnits angle = OSCAR::Radians

) [pure virtual]

child classes should implement this.
Basically, perform FK. Implementation should check for limits if limitCheck is set to true
Implemented in OSCAR::GeneralKinematicsHandler, and OSCAR::RedundantKinematicsHandler.

virtual bool OSCAR::KinematicsHandler::UpdateJointState ( const OSCAR::Xform & targetHand ) [pure virtual]

child classes should implement this.
Basically, perform IK. Implementation should check for limits if limitCheck is set to true
Implemented in OSCAR::GeneralKinematicsHandler, and OSCAR::RedundantKinematicsHandler.