Regular API function

simGetIkGroupMatrix

Description
Retrieves various information from an IK group, such as the Jacobian. For the result to be valid, the Jacobian must previously have been computed via the simComputeJacobian, simHandleIkGroup or simCheckIkGroup functions. Following situations have to be differentiated:
a) If you call simComputeJacobian just before calling simGetIkGroupMatrix, then the returned Jacobian will be the one at the current state/configuration of the mechanism. This is the recommended way to retrieve the Jacobian.
b) If you call simHandleIkGroup or simCheckIkGroup just before calling simGetIkGroupMatrix, then the returned Jacobian will be the one computed last, while trying to reach the target (since it usually takes at least 2-3 iterations to reach a target because of the linearization), which is not the current state/configuration of the mechanism, unless the target overlaps the tip.
C synopsis simFloat* simGetIkGroupMatrix(simInt ikGroupHandle,simInt options,simInt* matrixSize)
C parameters
ikGroupHandle: handle of an IK group
options: a value indicating what kind of information to retrieve:
0: to retrieve the last calculated Jacobian. matrixSize[0] is the number of rows (the number of DoFs), matrixSize[1] is the number of columns. See further down how to extract the Jacobian.
1: to retrieve the manipulability value, i.e. sqrt(det(J*JT)), where J is the Jacobian, and JT the Jacobian transpose. The returned pointer points onto a single value.
matrixSize: the dimensions of the returned matrix (x=rows, y=columns)

USAGE EXAMPLE (to correctly interpret the Jacobian):
float jacobianSize[2];
float* jacobian=simGetIkGroupMatrix(ikGroupHandle,0,jacobianSize);

// jacobianSize[0] represents the row count of the Jacobian 
// (i.e. the number of equations or the number of joints involved
// in the IK resolution of the given kinematic chain)
// Joints appear from tip to base.

// jacobianSize[1] represents the column count of the Jacobian 
// (i.e. the number of constraints, e.g. x,y,z,alpha,beta,gamma,jointDependency)

// The Jacobian data is ordered row-wise, i.e.:
// [row0,col0],[row1,col0],..,[rowN,col0],[row0,col1],[row1,col1],etc.

for (int i=0;i<jacobianSize[0];i++)
{
    std::string str;
    for (int j=0;j<jacobianSize[1];j++)
    {
        if (str.size()==0)
            str+=", ";
        str+=boost::str(boost::format("%.1e") % jacobian[j*jacobianSize[0]+i]);
    }
    printf(str.c_str());
}
C return value
A pointer to x*y float values. The values should be copied since the pointer might not remain valid.
Lua synopsis table matrix,table_2 matrixSize=simGetIkGroupMatrix(number ikGroupHandle,number options)
Lua parameters
Same as C-function

USAGE EXAMPLE (to correctly interpret the Jacobian):
jacobian,jacobianSize=simGetIkGroupMatrix(ikGroupHandle,0)

-- jacobianSize[1] represents the row count of the Jacobian 
-- (i.e. the number of equations or the number of joints involved
-- in the IK resolution of the given kinematic chain)
-- Joints appear from tip to base.

-- jacobianSize[2] represents the column count of the Jacobian 
-- (i.e. the number of constraints, e.g. x,y,z,alpha,beta,gamma,jointDependency,etc.)

-- The Jacobian data is ordered row-wise, i.e.:
-- [row1,col1],[row2,col1],..,[rowN,col1],[row1,col2],[row2,col2],etc.

for i=1,jacobianSize[1],1 do
    str=''
    for j=1,jacobianSize[2],1 do
        if #str~=0 then
            str=str..', '
        end
        str=str..string.format("%.1e",jacobian[(j-1)*jacobianSize[1]+i])
    end
    print(str)
end
Lua return values
Same as C-function

All regular API functions on one page