Character Setup

Character Setup

Module description

This section describes the functions used to set up an HIKCharacter.

Modules

 Character Properties
 This section describes the functions provided for setting and retrieving the modes and values of character properties within .
 
 Limits (Degrees of Freedom)
 This section describes the functions used to set up limits (Degrees of Freedom) for a character.
 
 Quadrupeds
 This section describes utility functions for use with quadruped characters.
 
 Floor Contact
 This section describes the functions used to set up floor contact for your characters.
 

Enumerations

enum  HIKMiddleJoint {
  HIKLeftKnee = 0, HIKRightKnee, HIKLeftElbow, HIKRightElbow,
  HIKLeftKnee = 0, HIKRightKnee, HIKLeftElbow, HIKRightElbow
}
 Lists the joints that can be inverted using the HIKInverseJoint() function. More...
 
enum  HIKMiddleJoint {
  HIKLeftKnee = 0, HIKRightKnee, HIKLeftElbow, HIKRightElbow,
  HIKLeftKnee = 0, HIKRightKnee, HIKLeftElbow, HIKRightElbow
}
 Lists the joints that can be inverted using the HIKInverseJoint() function. More...
 

Functions

void HIKSetCharacterizeNodeStatefv (HIKCharacter *pCharacter, int pNodeId, const float pXForm[16])
 Set the transform matrix for the Node pNodeId when the character is standing in the default T-stance. More...
 
void HIKSetCharacterizeNodeStatedv (HIKCharacter *pCharacter, int pNodeId, const double pXForm[16])
 Set the transform matrix for the Node pNodeId when the character is standing in the default T-stance. More...
 
void HIKSetCharacterizeNodeStateTQSfv (HIKCharacter *pCharacter, int pNodeId, const float pT[4], const float pQ[4], const float pS[4])
 Set the translation, orientation and scaling for the Node pNodeId when the character is standing in the default T-stance. More...
 
void HIKSetCharacterizeNodeStateTQSdv (HIKCharacter *pCharacter, int pNodeId, const double pT[4], const double pQ[4], const double pS[4])
 Set the translation, orientation and scaling for the Node pNodeId when the character is standing in the default T-stance. More...
 
void HIKGetCharacterizeNodeStateTQSfv (const HIKCharacter *pCharacter, int pNodeId, float pT[4], float pQ[4], float pS[4])
 Retrieve the translation, orientation and scaling for the Node pNodeId when the character is standing in the default T-stance. More...
 
void HIKGetCharacterizeNodeStateTQSdv (const HIKCharacter *pCharacter, int pNodeId, double pT[4], double pQ[4], double pS[4])
 Retrieve the translation, orientation and scaling for the Node pNodeId when the character is standing in the default T-stance. More...
 
void HIKGetCharacterizeNodeStatefv (const HIKCharacter *pCharacter, int pNodeId, float pXForm[16])
 Retrieve the transform matrix for the Node pNodeId when the character is standing in the default T-stance. More...
 
bool HIKCharacterizeGeometry (HIKCharacter *pCharacter)
 Set up and initialize character pCharacter for solving. More...
 
void HIKGetDefaultState (const HIKCharacter *pCharacter, HIKCharacterState *pCharacterState)
 Retrieve the default T-stance for character pCharacter, storing it in HIKCharacterState pCharacterState. More...
 
void HIKGetRelaxPose (const HIKCharacter *pCharacter, HIKCharacterState *pCharacterState)
 Calculate a basic seated pose for character pCharacter, storing it in HIKCharacterState pCharacterState. More...
 
int HIKGetNodeUse (const HIKCharacter *pCharacter, int pNodeId)
 Retrieve the characterization flag set for Node pNodeId in HIKCharacter pCharacter. More...
 
void HIKSetParentOffsetfv (HIKCharacter *pCharacter, int pNodeId, const float pParentTOffset[4], const float pParentQOffset[4], const float pParentSOffset[4])
 Set the parent offset for Node pNodeId. More...
 
void HIKSetParentOffsetdv (HIKCharacter *pCharacter, int pNodeId, const double pParentTOffset[4], const double pParentQOffset[4], const double pParentSOffset[4])
 Set the parent offset for Node pNodeId. More...
 
void HIKGetParentOffsetfv (const HIKCharacter *pCharacter, int pNodeId, float pParentTOffset[4], float pParentQOffset[4], float pParentSOffset[4])
 Retrieve the parent offset set for Node pNodeId. More...
 
void HIKGetParentOffsetdv (const HIKCharacter *pCharacter, int pNodeId, double pParentTOffset[4], double pParentQOffset[4], double pParentSOffset[4])
 Retrieve the parent offset set for Node pNodeId. More...
 
void HIKInverseJoint (HIKCharacter *pCharacter, eHIKMiddleJoint pJoint, int pInverse)
 Reverses the direction in which a middle joint bends, such as a knee or elbow. More...
 
int HIKIsJointInverted (const HIKCharacter *pCharacter, eHIKMiddleJoint pJoint)
 Indicates whether or not a middle joint is inverted. More...
 

Enumeration Type Documentation

Lists the joints that can be inverted using the HIKInverseJoint() function.

Enumerator
HIKLeftKnee 

Represents the left knee (HIKNodeId::LeftKneeNodeId).

HIKRightKnee 

Represents the right knee (HIKNodeId::RightKneeNodeId).

HIKLeftElbow 

Represents the left elbow (HIKNodeId::LeftElbowNodeId).

HIKRightElbow 

Represents the right elbow (HIKNodeId::RightElbowNodeId).

HIKLeftKnee 

Represents the left knee (HIKNodeId::LeftKneeNodeId).

HIKRightKnee 

Represents the right knee (HIKNodeId::RightKneeNodeId).

HIKLeftElbow 

Represents the left elbow (HIKNodeId::LeftElbowNodeId).

HIKRightElbow 

Represents the right elbow (HIKNodeId::RightElbowNodeId).

Definition at line 813 of file humanik.h.

814 {
815  HIKLeftKnee = 0,
816  HIKRightKnee,
817  HIKLeftElbow,
819 };
Represents the right elbow (HIKNodeId::RightElbowNodeId).
Definition: humanik.h:818
Represents the left elbow (HIKNodeId::LeftElbowNodeId).
Definition: humanik.h:817
Represents the right knee (HIKNodeId::RightKneeNodeId).
Definition: humanik.h:816
Represents the left knee (HIKNodeId::LeftKneeNodeId).
Definition: humanik.h:815

Lists the joints that can be inverted using the HIKInverseJoint() function.

Enumerator
HIKLeftKnee 

Represents the left knee (HIKNodeId::LeftKneeNodeId).

HIKRightKnee 

Represents the right knee (HIKNodeId::RightKneeNodeId).

HIKLeftElbow 

Represents the left elbow (HIKNodeId::LeftElbowNodeId).

HIKRightElbow 

Represents the right elbow (HIKNodeId::RightElbowNodeId).

HIKLeftKnee 

Represents the left knee (HIKNodeId::LeftKneeNodeId).

HIKRightKnee 

Represents the right knee (HIKNodeId::RightKneeNodeId).

HIKLeftElbow 

Represents the left elbow (HIKNodeId::LeftElbowNodeId).

HIKRightElbow 

Represents the right elbow (HIKNodeId::RightElbowNodeId).

Definition at line 853 of file humanik.h.

854 {
855  HIKLeftKnee = 0,
856  HIKRightKnee,
857  HIKLeftElbow,
859 };
Represents the right elbow (HIKNodeId::RightElbowNodeId).
Definition: humanik.h:818
Represents the left elbow (HIKNodeId::LeftElbowNodeId).
Definition: humanik.h:817
Represents the right knee (HIKNodeId::RightKneeNodeId).
Definition: humanik.h:816
Represents the left knee (HIKNodeId::LeftKneeNodeId).
Definition: humanik.h:815

Function Documentation

bool HIKCharacterizeGeometry ( HIKCharacter pCharacter)

Set up and initialize character pCharacter for solving.

Call this function after you have called HIKSetCharacterizeNodeStatefv() for all your character's Nodes. This function finalizes the default stance and calibrates the engine.

Parameters
pCharacterCharacter to set up and initialize.
Remarks
The character must be standing in a T-stance, facing the positive direction of the Z axis, with the left hand pointing along the positive direction of the X axis and the right hand pointing along the negative direction of the X axis. See ~{ Overview }~ for an image. Your character MUST be characterized in this pose in order for the HumanIK solvers to be able to control your character.
Returns
false if there is an error in the provided T-stance.
+ Examples:
void HIKGetCharacterizeNodeStatefv ( const HIKCharacter pCharacter,
int  pNodeId,
float  pXForm[16] 
)

Retrieve the transform matrix for the Node pNodeId when the character is standing in the default T-stance.

Parameters
pCharacterThe character you want to query.
pNodeIdThe Node that you want to query. See the HIKNodeId enumeration for possible values.
pXFormThe transform matrix of this joint in the default T-stance, in global space.
+ Examples:
void HIKGetCharacterizeNodeStateTQSdv ( const HIKCharacter pCharacter,
int  pNodeId,
double  pT[4],
double  pQ[4],
double  pS[4] 
)

Retrieve the translation, orientation and scaling for the Node pNodeId when the character is standing in the default T-stance.

Parameters
pCharacterThe character you want to query.
pNodeIdThe Node that you want to query. See the HIKNodeId enumeration for possible values.
pTDefault stance translation for this joint in global space.
pQDefault stance orientation for this joint in global space, expressed as a quaternion.
pSDefault stance scale for this joint in global space.
+ Examples:
void HIKGetCharacterizeNodeStateTQSfv ( const HIKCharacter pCharacter,
int  pNodeId,
float  pT[4],
float  pQ[4],
float  pS[4] 
)

Retrieve the translation, orientation and scaling for the Node pNodeId when the character is standing in the default T-stance.

Parameters
pCharacterThe character you want to query.
pNodeIdThe Node that you want to query. See the HIKNodeId enumeration for possible values.
pTDefault stance translation for this joint in global space.
pQDefault stance orientation for this joint in global space, expressed as a quaternion.
pSDefault stance scale for this joint in global space.
void HIKGetDefaultState ( const HIKCharacter pCharacter,
HIKCharacterState pCharacterState 
)

Retrieve the default T-stance for character pCharacter, storing it in HIKCharacterState pCharacterState.

This function always returns the same stance for the given character. The default stance does not differ before and after you perform a solve.

Parameters
pCharacterCharacter whose default stance is to be retrieved.
[out]pCharacterStateHIKCharacterState to contain the default stance.
+ Examples:
int HIKGetNodeUse ( const HIKCharacter pCharacter,
int  pNodeId 
)

Retrieve the characterization flag set for Node pNodeId in HIKCharacter pCharacter.

Parameters
pCharacterCharacter.
pNodeIdNode ID whose flag is to be retrieved. See the HIKNodeId enumeration for possible values.
Returns
A bit mask that indicates the status of Node pNodeId within HIKCharacter pCharacter. This bit mask is composed of the flags in the HIKNodeFlags enumeration.
  • If the Node is used by the character, the HIKNodeUsed flag will be true.
  • If the Node supports the use of a parent offset, the HIKNodeParentOffset flag will also be true
  • If the Node supports the use of limits (Degrees of Freedom), the HIKNodeLimits flag will also be true
  • If the Node is not used, all flags will be false.
+ Examples:
void HIKGetParentOffsetdv ( const HIKCharacter pCharacter,
int  pNodeId,
double  pParentTOffset[4],
double  pParentQOffset[4],
double  pParentSOffset[4] 
)

Retrieve the parent offset set for Node pNodeId.

This function is needed only if the parent joint is unknown to HumanIK, and if you are using either local space transforms or limits (DoF).

Parameters
pCharacterThe character you want to get.
pNodeIdThe Node whose parent offset you want to retrieve. See the HIKNodeId enumeration for possible values.
pParentTOffsetThe parent node translation offset.
pParentQOffsetThe parent node rotation offset, expressed as a quaternion.
pParentSOffsetThe parent node scaling offset.
void HIKGetParentOffsetfv ( const HIKCharacter pCharacter,
int  pNodeId,
float  pParentTOffset[4],
float  pParentQOffset[4],
float  pParentSOffset[4] 
)

Retrieve the parent offset set for Node pNodeId.

This function is needed only if the parent joint is unknown to HumanIK, and if you are using either local space transforms or limits (DoF).

Parameters
pCharacterThe character you want to get.
pNodeIdThe Node whose parent offset you want to retrieve. See the HIKNodeId enumeration for possible values.
pParentTOffsetThe parent node translation offset.
pParentQOffsetThe parent node rotation offset, expressed as a quaternion.
pParentSOffsetThe parent node scaling offset.
void HIKGetRelaxPose ( const HIKCharacter pCharacter,
HIKCharacterState pCharacterState 
)

Calculate a basic seated pose for character pCharacter, storing it in HIKCharacterState pCharacterState.

Parameters
pCharacterCharacter whose seated pose is to be retrieved.
[out]pCharacterStateHIKCharacterState to contain the default stance.
+ Examples:
void HIKInverseJoint ( HIKCharacter pCharacter,
eHIKMiddleJoint  pJoint,
int  pInverse 
)

Reverses the direction in which a middle joint bends, such as a knee or elbow.

If you characterize your character programmatically, this function can only be called after the character's geometry has been finalized by the call to HIKCharacterizeGeometry().

Parameters
pCharacterThe character you want to set up.
pJointThe joint to be inverted. See the HIKMiddleJoint enumeration for possible values.
pInverseSpecifies the direction of rotation for the joint. 0 = normal rotation, any other value = inverse rotation.
+ Examples:
int HIKIsJointInverted ( const HIKCharacter pCharacter,
eHIKMiddleJoint  pJoint 
)

Indicates whether or not a middle joint is inverted.

If you characterize your character programmatically, this function can only be called after the character's geometry has been finalized by the call to HIKCharacterizeGeometry().

Parameters
pCharacterThe character whose joint inversion you want to query.
pJointThe joint to be queried for its inversion state. See the HIKMiddleJoint enumeration for possible values.
Returns
0 = normal rotation, any other value = inverse rotation.
void HIKSetCharacterizeNodeStatedv ( HIKCharacter pCharacter,
int  pNodeId,
const double  pXForm[16] 
)

Set the transform matrix for the Node pNodeId when the character is standing in the default T-stance.

Parameters
pCharacterThe character you want to set up.
pNodeIdThe unique ID of the Node that you want to set up. See the HIKNodeId enumeration for possible values.
pXFormDefault stance matrix for this Node in global space (4x4 column major matrix).
+ Examples:
void HIKSetCharacterizeNodeStatefv ( HIKCharacter pCharacter,
int  pNodeId,
const float  pXForm[16] 
)

Set the transform matrix for the Node pNodeId when the character is standing in the default T-stance.

Parameters
pCharacterThe character you want to set up.
pNodeIdThe unique ID of the Node that you want to set up. See the HIKNodeId enumeration for possible values.
pXFormDefault stance matrix for this Node in global space (4x4 column major matrix).
+ Examples:
void HIKSetCharacterizeNodeStateTQSdv ( HIKCharacter pCharacter,
int  pNodeId,
const double  pT[4],
const double  pQ[4],
const double  pS[4] 
)

Set the translation, orientation and scaling for the Node pNodeId when the character is standing in the default T-stance.

Parameters
pCharacterThe character you want to set up.
pNodeIdThe unique ID of the Node that you want to set up. See the HIKNodeId enumeration for possible values.
pTDefault stance translation for this joint in global space.
pQDefault stance orientation for this joint in global space, expressed as a quaternion.
pSDefault stance scale for this joint in global space.
+ Examples:
void HIKSetCharacterizeNodeStateTQSfv ( HIKCharacter pCharacter,
int  pNodeId,
const float  pT[4],
const float  pQ[4],
const float  pS[4] 
)

Set the translation, orientation and scaling for the Node pNodeId when the character is standing in the default T-stance.

Parameters
pCharacterThe character you want to set up.
pNodeIdThe unique ID of the Node that you want to set up. See the HIKNodeId enumeration for possible values.
pTDefault stance translation for this joint in global space.
pQDefault stance orientation for this joint in global space, expressed as a quaternion.
pSDefault stance scale for this joint in global space.
void HIKSetParentOffsetdv ( HIKCharacter pCharacter,
int  pNodeId,
const double  pParentTOffset[4],
const double  pParentQOffset[4],
const double  pParentSOffset[4] 
)

Set the parent offset for Node pNodeId.

This function is needed only if the parent joint is unknown to HumanIK, and if you are using either local space transforms or limits (DoF).

Parameters
pCharacterThe character you want to set up.
pNodeIdThe Node whose parent offset you want to set up. See the HIKNodeId enumeration for possible values.
pParentTOffsetThe parent node translation offset, relative to the next HumanIK Node above the parent in the joint chain.
pParentQOffsetThe parent node rotation offset, expressed as a quaternion., relative to the next HumanIK Node above the parent in the joint chain. This value must be normalized. You can calculate this offset as follows:
pParentQOffset = inverse(HIKParentGQ) * RealParentGQ
where:
  • HIKParentGQ is a quaternion containing the rotation of the next HumanIK joint above the unknown parent joint in the skeletal hierarchy, expressed in global space
  • RealParentGQ is a quaternion containing the rotation of the unknown parent joint, expressed in global space.
pParentSOffsetThe parent node scaling offset, relative to the next HumanIK Node above the parent in the joint chain.
+ Examples:
void HIKSetParentOffsetfv ( HIKCharacter pCharacter,
int  pNodeId,
const float  pParentTOffset[4],
const float  pParentQOffset[4],
const float  pParentSOffset[4] 
)

Set the parent offset for Node pNodeId.

This function is needed only if the parent joint is unknown to HumanIK, and if you are using either local space transforms or limits (DoF).

Parameters
pCharacterThe character you want to set up.
pNodeIdThe Node whose parent offset you want to set up. See the HIKNodeId enumeration for possible values.
pParentTOffsetThe parent node translation offset, relative to the next HumanIK Node above the parent in the joint chain.
pParentQOffsetThe parent node rotation offset, expressed as a quaternion., relative to the next HumanIK Node above the parent in the joint chain. This value must be normalized. You can calculate this offset as follows:
pParentQOffset = inverse(HIKParentGQ) * RealParentGQ
where:
  • HIKParentGQ is a quaternion containing the rotation of the next HumanIK joint above the unknown parent joint in the skeletal hierarchy, expressed in global space
  • RealParentGQ is a quaternion containing the rotation of the unknown parent joint, expressed in global space.
pParentSOffsetThe parent node scaling offset, relative to the next HumanIK Node above the parent in the joint chain.