IKSolver Class Reference

#include <iksolver.h>

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.

Inheritance diagram for IKSolver:

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
Public Member Functions inherited from BaseInterfaceServer
virtual UtilExport BaseInterface *	GetInterface (Interface_ID id)
virtual UtilExport int	NumInterfaces () const
virtual UtilExport BaseInterface *	GetInterfaceAt (int i) const
virtual UtilExport	~BaseInterfaceServer ()
Public Member Functions inherited from InterfaceServer
virtual UtilExport	~InterfaceServer ()
	Destructor. More...

Additional Inherited Members
Static Public Member Functions inherited from MaxHeapOperators
static UtilExport void *	operator new (size_t size)
	Standard new operator used to allocate objects If there is insufficient memory, an exception will be thrown. More...
static UtilExport void *	operator new (size_t size, const std::nothrow_t &e)
	Standard new operator used to allocate objects if there is insufficient memory, NULL will be returned. More...
static UtilExport void *	operator new (size_t size, const char *filename, int line)
	New operator used to allocate objects that takes the filename and line number where the new was called If there is insufficient memory, an exception will be thrown. More...
static UtilExport void *	operator new (size_t size, int block_type, const char *filename, int line)
	New operator used to allocate objects that takes the type of memory, filename and line number where the new was called If there is insufficient memory, an exception will be thrown. More...
static UtilExport void *	operator new (size_t size, const std::nothrow_t &e, const char *filename, int line)
	New operator used to allocate objects that takes the filename and line number where the new was called If there is insufficient memory, NULL will be returned. More...
static UtilExport void *	operator new (size_t size, unsigned long flags)
	New operator used to allocate objects that takes extra flags to specify special operations If there is insufficient memory, an exception will be thrown. More...
static UtilExport void *	operator new (size_t size, const std::nothrow_t &e, unsigned long flags)
	New operator used to allocate objects that takes extra flags to specify special operations If there is insufficient memory, NULL will be returned. More...
static UtilExport void *	operator new[] (size_t size)
	New operator used to allocate arrays of objects If there is insufficient memory, an exception will be thrown. More...
static UtilExport void *	operator new[] (size_t size, const std::nothrow_t &e)
	New operator used to allocate arrays of objects If there is insufficient memory, NULL will be returned. More...
static UtilExport void *	operator new[] (size_t size, const char *filename, int line)
	New operator used to allocate arrays of objects If there is insufficient memory, an exception will be thrown. More...
static UtilExport void *	operator new[] (size_t size, int block_type, const char *filename, int line)
	New operator used to allocate arrays of objects. More...
static UtilExport void *	operator new[] (size_t size, const std::nothrow_t &e, const char *filename, int line)
	New operator used to allocate arrays of objects If there is insufficient memory, NULL will be returned. More...
static UtilExport void *	operator new[] (size_t size, unsigned long flags)
	New operator used to allocate arrays of objects If there is insufficient memory, an exception will be thrown. More...
static UtilExport void *	operator new[] (size_t size, const std::nothrow_t &e, unsigned long flags)
	New operator used to allocate arrays of objects If there is insufficient memory, NULL will be returned. More...
static UtilExport void	operator delete (void *ptr)
	Standard delete operator used to deallocate an object If the pointer is invalid, an exception will be thrown. More...
static UtilExport void	operator delete (void *ptr, const std::nothrow_t &e)
	Standard delete operator used to deallocate an object If the pointer is invalid, nothing will happen. More...
static UtilExport void	operator delete (void *ptr, const char *filename, int line)
	Delete operator used to deallocate an object that takes the filename and line number where the delete was called If the pointer is invalid, an exception will be thrown. More...
static UtilExport void	operator delete (void *ptr, int block_type, const char *filename, int line)
	Delete operator used to deallocate an object that takes the type of memory, filename and line number where the delete was called If the pointer is invalid, an exception will be thrown. More...
static UtilExport void	operator delete (void *ptr, const std::nothrow_t &e, const char *filename, int line)
	Delete operator used to deallocate an object that takes the filename and line number where the delete was called If the pointer is invalid, nothing will happen. More...
static UtilExport void	operator delete (void *ptr, unsigned long flags)
	Delete operator used to deallocate an object that takes extra flags to specify special operations If the pointer is invalid, an exception will be thrown. More...
static UtilExport void	operator delete (void *ptr, const std::nothrow_t &e, unsigned long flags)
	Delete operator used to deallocate an object that takes extra flags to specify special operations If the pointer is invalid, nothing will happen. More...
static UtilExport void	operator delete[] (void *ptr)
	Standard delete operator used to deallocate an array of objects If the pointer is invalid, an exception will be thrown. More...
static UtilExport void	operator delete[] (void *ptr, const std::nothrow_t &e)
	Standard delete operator used to deallocate an array of objects If the pointer is invalid, nothing will happen. More...
static UtilExport void	operator delete[] (void *ptr, const char *filename, int line)
	Delete operator used to deallocate an array of objects that takes the filename and line number where the delete was called If the pointer is invalid, an exception will be thrown. More...
static UtilExport void	operator delete[] (void *ptr, int block_type, const char *filename, int line)
	Delete operator used to deallocate an array of objects that takes the type of memory, filename and line number where the delete was called If the pointer is invalid, an exception will be thrown. More...
static UtilExport void	operator delete[] (void *ptr, const std::nothrow_t &e, const char *filename, int line)
	Delete operator used to deallocate an array of objects that takes the filename and line number where the delete was called If the pointer is invalid, nothing will happen. More...
static UtilExport void	operator delete[] (void *ptr, unsigned long flags)
	Delete operator used to deallocate an array of objects that takes extra flags to specify special operations If the pointer is invalid, an exception will be thrown. More...
static UtilExport void	operator delete[] (void *ptr, const std::nothrow_t &e, unsigned long flags)
	Delete operator used to deallocate an array of objects that takes extra flags to specify special operations If the pointer is invalid, an exception will be thrown. More...
static UtilExport void *	operator new (size_t size, void *placement_ptr)
	Placement new operator. More...
static UtilExport void	operator delete (void *ptr, void *placement_ptr)
	Placement delete operator. More...
static UtilExport void *	aligned_malloc (size_t size, size_t alignment)
	Allocates memory on a specified alignment boundary. More...
static UtilExport void *	aligned_realloc (void *ptr, size_t size, size_t alignment)
	Reallocates memory on a specified alignment boundary. More...
static UtilExport void	aligned_free (void *ptr)
	Frees a block of memory that was allocated with aligned_malloc/aligned_realloc. More...
Protected Attributes inherited from BaseInterfaceServer
Tab< BaseInterface * >	interfaces

Member Typedef Documentation

typedef unsigned ReturnCondition

Member Enumeration Documentation

enum ConditionBit

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 ( )

inlinevirtual

Remarks

Destructor.

{}

Member Function Documentation

virtual SClass_ID SuperClassID ( )

inlinevirtual

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 )

inlinevirtual

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

inlinevirtual

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

inlinevirtual

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

inlinevirtual

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

inlinevirtual

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.