IKSolver Class Reference
 
 
 
IKSolver Class Reference

This reference page is linked to from the following overview topics: Plug-in Base Classes, Inverse Kinematics, IK Solvers, IIKChainControl.


#include <iksolver.h>

Inheritance diagram for IKSolver:
BaseInterfaceServer InterfaceServer MaxHeapOperators

Class Description

See also:
Class BaseInterfaceServer, Class ZeroPlaneMap, Class LinkChain, Inverse Kinematics

Description:
This class represents the base class that IK Solver plugins should derive from.

The IK solver is a pure mathematical function and does not hold state, but instead just solves a given, self-contained, mathematical problem, e.g. the plugin solver does not have influence on when IK is invoked and what an IK problem is (what is the goal and what are the joints, etc.), but contributes to IK by providing an answer on how to solve. Structurally, it is independent of the SDK and, hence, can be built independently, except for some theoretically independent math library. See the Inverse Kinematics section for more detailed information.

Public Types

enum   ConditionBit {
  bLimitReached = 0x00000001, bLimitClamped = 0x00000002, bMaxIterationReached = 0x00000004, bGoalTooCloseToEE = 0x00000100,
  bInvalidArgument = 0x00000200, bInvalidInitialValue = 0x00000400
}
typedef unsigned  ReturnCondition

Public Member Functions

virtual SClass_ID  SuperClassID ()
virtual Class_ID  ClassID ()=0
virtual void  GetClassName (MSTR &s)
virtual  ~IKSolver ()
virtual bool  IsHistoryDependent () const =0
virtual bool  DoesOneChainOnly () const =0
virtual bool  IsInteractive () const =0
virtual bool  UseSlidingJoint () const =0
virtual bool  UseSwivelAngle () const =0
virtual bool  IsAnalytic () const
virtual bool  DoesRootJointLimits () const
virtual bool  DoesJointLimitsButRoot () const
virtual Interface_ID  ExpectGoal () const =0
virtual bool  SolveEERotation () const =0
virtual const IKSys::ZeroPlaneMap GetZeroPlaneMap (const Point3 &a0, const Point3 &n0) const
virtual float  GetPosThreshold () const =0
virtual float  GetRotThreshold () const =0
virtual unsigned  GetMaxIteration () const =0
virtual void  SetPosThreshold (float)=0
virtual void  SetRotThreshold (float)=0
virtual void  SetMaxIteration (unsigned)=0
virtual ReturnCondition  Solve (IKSys::LinkChain &)=0

Member Typedef Documentation


Member Enumeration Documentation

Enumerator:
bLimitReached 
bLimitClamped 
bMaxIterationReached 
bGoalTooCloseToEE 
bInvalidArgument 
bInvalidInitialValue 
                          {
                bLimitReached =                 0x00000001,
                bLimitClamped =                 0x00000002,
                bMaxIterationReached =  0x00000004,
                // The first eight bits are reserved for mild condition.
                // They are still considered successful.
                bGoalTooCloseToEE =             0x00000100,
                bInvalidArgument =              0x00000200,
                bInvalidInitialValue =  0x00000400
        };

Constructor & Destructor Documentation

virtual ~IKSolver ( ) [inline, virtual]
Remarks:
Destructor.
{}

Member Function Documentation

virtual SClass_ID SuperClassID ( ) [inline, virtual]
Remarks:
Plugins derived from this class are supposed to have IK_SOLVER_CLASS_IDas their super class ID. This method should not be overridden.
Default Implementation:
{ return IK_SOLVER_CLASS_ID; }
{return IK_SOLVER_CLASS_ID;}
virtual Class_ID ClassID ( ) [pure virtual]
Remarks:
Returns the class ID of the IK Solver plugin.
virtual void GetClassName ( MSTR s ) [inline, virtual]
Remarks:
This method returns the class name of the IK Solver plugin. This name will appear in the solver list from which users can pick or assign IK chains.
Parameters:
MSTR& s

The class name string.
Default Implementation:
{ s = MSTR(_M("IKSolver")); }
{ s= MSTR(_M("IKSolver")); }  
virtual bool IsHistoryDependent ( ) const [pure virtual]
Remarks:
At a specific point in time, the history dependent solver will reach solutions not only based the state of the goal at the time, but also its previous states (i.e. history dependent). On the contrary, the history independent solver does its job based on the state of the goal just at the time. The procedural implication is that, when the goal is changed at time t, the IK system would have to invalidate joints at time t for the history independent solver, and at all times that are greater or equal to t for the history dependent solver. In R4, only history dependent solvers are used by the IK system.
Returns:
TRUE if the IK Solver is history dependent, otherwise FALSE.
virtual bool DoesOneChainOnly ( ) const [pure virtual]
Remarks:
When two IK chains overlap, i.e., there is a joint belonging to both IK chains, some solvers are able to negotiate between the possibly contending goals and some are not. This method indicates if the IK Solver does a single chain only. For those IK Solvers that can only solve one chain at a time, the IK system will pass to the solvers one chain at a time in a definitive order. In R4, only solvers that "do one chain only" are used.
Returns:
TRUE if the IK Solver does only one chain, otherwise FALSE.
virtual bool IsInteractive ( ) const [pure virtual]
Remarks:
This method indicates whether the IK Solver is a controller or an interactive manipulation tool. In the former, the relationship between the goal and the joints are permanent: joints are completely controlled by the goal. In the latter, the relationship is transient, existing only during interactive manipulation. In the end, IK solutions are registered at each joint, mostly likely as key-frames, and it no longer matters how joints have got their joint angles. Only non-interactive, or controller, IK solvers are supported in R4. Note that Interactive solvers do not need an initial pose, instead it needs a current pose.
Returns:
TRUE if the IK Solver is an interactive tool, otherwise FALSE.
virtual bool UseSlidingJoint ( ) const [pure virtual]
Remarks:
This method indicates whether the IK Solver intends to use the sliding joint (translational degrees of freedom) of the IK chain.
Returns:
TRUE if the sliding joint of the IK chain is used, otherwise FALSE.
virtual bool UseSwivelAngle ( ) const [pure virtual]
Remarks:
This method indicates whether the IK Solver intends to use the swivel angle parameter of the IK chain.
Returns:
TRUE if the swivel angle of the IK chain is used, otherwise FALSE.
virtual bool IsAnalytic ( ) const [inline, virtual]
Remarks:
This method determines whether the IK Solver is analytic or needs to go through iterations. Solutions of an analytic IK Solver are not dependent on position and rotation thresholds or a maximum number of iterations.
Returns:
TRUE if the IK Solver is analytic, otherwise FALSE.
Default Implementation:
{ return false; }
{ return false; }
virtual bool DoesRootJointLimits ( ) const [inline, virtual]
Remarks:
This method determines whether the IK Solver handles root joint limits. If the IK Solver does not do joint limits, the result will be simply clamped into joint limits by the IK system.
Returns:
TRUE if the IK Solver does root joint limits, otherwise FALSE.
Default Implementation:
{ return false;}
{ return false;}
virtual bool DoesJointLimitsButRoot ( ) const [inline, virtual]
Remarks:
This method determines whether the IK Solver handles joint limits. If the IK Solver does not do joint limits, the result will be simply clamped into joint limits by the IK system.
Returns:
TRUE if the IK Solver does joint limits, otherwise FALSE.
Default Implementation:
{ return false;}
{ return false;}
virtual Interface_ID ExpectGoal ( ) const [pure virtual]
virtual bool SolveEERotation ( ) const [pure virtual]
Remarks:
This method determines whether the rotational part of the goal node will be used.
Returns:
TRUE if the rotational part of the goal node will be used, otherwise FALSE to indicate that only the position of the goal node is taken as the IK goal while the rotation threshold will be irrelevant.
virtual const IKSys::ZeroPlaneMap* GetZeroPlaneMap ( const Point3 a0,
const Point3 n0 
) const [inline, virtual]
Remarks:
IK Solvers may have their own Zero Plane Map. If so, they must override this method. The IK system will need it to perform IK snapping, which is setting the swivel angle based on the current pose so that the pose is consistent with the swivel angle. A Zero-Plane map can depend on the initial pose, which is when the joint angles take into account the respective preferred angles. In this method, a0 is to be substituted for by the end effector axis, which is a unit vector, and n0 by the solver plane normal, also a unit vector, when the chain is at the initial pose. The IK system will call this function using IIKChainControl::InitEEAxis() and IIKChainControl::InitPlane() for the two arguments.
Parameters:
const Point3& a0

The end effector axis unit vector.

const Point3& n0

The solver plane normal.
Returns:
A pointer to the ZeroPlaneMap.
Default Implementation:
{ return NULL; }
{ return NULL; }
virtual float GetPosThreshold ( ) const [pure virtual]
Remarks:
This method allows you to retrieve the position threshold.
virtual float GetRotThreshold ( ) const [pure virtual]
Remarks:
This method allows you to retrieve the rotation threshold.
virtual unsigned GetMaxIteration ( ) const [pure virtual]
Remarks:
This method allows you to retrieve the maximum number of iterations.
virtual void SetPosThreshold ( float  ) [pure virtual]
Remarks:
This method allows you to set the position threshold.
Parameters:
float

The position threshold value.
virtual void SetRotThreshold ( float  ) [pure virtual]
Remarks:
This method allows you to set the rotation threshold.
Parameters:
float

The rotation threshold value.
virtual void SetMaxIteration ( unsigned  ) [pure virtual]
Remarks:
This method allows you to set the maximum number of iterations.
Parameters:
unsigned

The maximum number of iterations.
virtual ReturnCondition Solve ( IKSys::LinkChain ) [pure virtual]
Remarks:
This is the method that the IK system will call when it's the time to update the joints according to the IK goal and other parameters. The derived class should override this method if DoesOneChainOnly() returns TRUE and HistoryDependent() returns FALSE. Note that the solver is not designed to be invoked recursively. The recursion logic existing among the IK chains is taken care of by the 3ds Max IK (sub-)System. The data structure passed to the Solver is transient and thus will be discarded once the solution is copied back to the joints. If the return condition indicates failure, (i.e. > 0xff) the result will not be copied back to the joint nodes in the 3ds Max scene database.
Parameters:
IKSys::LinkChain&

A reference to the Link Chain.
Returns:
The ReturnCondition bit-set with one or more of the following flags;

bLimitReached

The limit is reached.

bLimitClamped

The limit is clamped.

bMaxIterationReached

The maximum number of iterations is reached.

bGoalTooCloseToEE

The goal is too close to the end effector.

bInvalidArgument

An invalid argument is passed.

bInvalidInitialValue

An invalid initial value is passed.