IK plugin API reference

API functions for creating kinematics tasks. All units, unless otherwise indicated, are specified in meters and radians.

simIK.addElement
simIK.addElementFromScene
simIK.computeGroupJacobian
simIK.computeJacobian
simIK.createDebugOverlay
simIK.createDummy
simIK.createEnvironment
simIK.createGroup
simIK.createJoint
simIK.doesGroupExist
simIK.doesObjectExist
simIK.duplicateEnvironment
simIK.eraseDebugOverlay
simIK.eraseEnvironment
simIK.eraseObject
simIK.generatePath
simIK.findConfigs
simIK.getAlternateConfigs
simIK.getElementBase
simIK.getElementConstraints
simIK.getElementFlags
simIK.getElementPrecision
simIK.getElementWeights
simIK.getGroupCalculation
simIK.getGroupFlags
simIK.getGroupHandle
simIK.getGroupJointLimitHits
simIK.getGroupJoints
simIK.getJointDependency
simIK.getJointInterval
simIK.getJointLimitMargin
simIK.getJointMatrix
simIK.getJointMaxStepSize
simIK.getJointMode
simIK.getJointPosition
simIK.getJointScrewLead
simIK.getJointTransformation
simIK.getJointType
simIK.getJointWeight
simIK.getObjectHandle
simIK.getObjectMatrix
simIK.getObjectParent
simIK.getObjectPose
simIK.getObjects
simIK.getObjectTransformation
simIK.getObjectType
simIK.getTargetDummy
simIK.handleGroup
simIK.handleGroups
simIK.load
simIK.save
simIK.setElementBase
simIK.setElementConstraints
simIK.setElementFlags
simIK.setElementPrecision
simIK.setElementWeights
simIK.setGroupCalculation
simIK.setGroupFlags
simIK.setJointDependency
simIK.setJointInterval
simIK.setJointLimitMargin
simIK.setJointMaxStepSize
simIK.setJointMode
simIK.setJointPosition
simIK.setJointScrewLead
simIK.setJointWeight
simIK.setObjectMatrix
simIK.setObjectParent
simIK.setObjectPose
simIK.setObjectTransformation
simIK.setSphericalJointMatrix
simIK.setSphericalJointRotation
simIK.setTargetDummy
simIK.syncToSim
simIK.syncFromSim

Environment functions and helpers

simIK.createEnvironment
simIK.eraseEnvironment
simIK.duplicateEnvironment
simIK.createDebugOverlay
simIK.eraseDebugOverlay
simIK.save
simIK.load
simIK.addElementFromScene
simIK.syncToSim
simIK.syncFromSim

Objects

simIK.getObjects
simIK.getObjectHandle
simIK.doesObjectExist
simIK.eraseObject
simIK.getObjectParent
simIK.setObjectParent
simIK.getObjectPose
simIK.setObjectPose
simIK.getObjectTransformation
simIK.setObjectTransformation
simIK.getObjectType
simIK.getObjectMatrix
simIK.setObjectMatrix

Dummies

simIK.createDummy
simIK.eraseObject
simIK.getTargetDummy
simIK.setTargetDummy

Joints

simIK.createJoint
simIK.eraseObject
simIK.getJointPosition
simIK.setJointPosition
simIK.getJointMode
simIK.setJointMode
simIK.getJointInterval
simIK.setJointInterval
simIK.getJointDependency
simIK.setJointDependency
simIK.getJointWeight
simIK.setJointWeight
simIK.getJointLimitMargin
simIK.setJointLimitMargin
simIK.getJointMaxStepSize
simIK.setJointMaxStepSize
simIK.getJointScrewLead
simIK.setJointScrewLead
simIK.getJointTransformation
simIK.setSphericalJointRotation
simIK.getJointType
simIK.getJointMatrix
simIK.setSphericalJointMatrix
simIK.getGroupJoints

IK groups

simIK.createGroup
simIK.getGroupHandle
simIK.doesGroupExist
simIK.getGroupFlags
simIK.setGroupFlags
simIK.getGroupJointLimitHits
simIK.getGroupJoints
simIK.getGroupCalculation
simIK.setGroupCalculation

IK elements

simIK.addElement
simIK.addElementFromScene
simIK.getElementFlags
simIK.setElementFlags
simIK.getElementConstraints
simIK.setElementConstraints
simIK.getElementBase
simIK.setElementBase
simIK.getElementPrecision
simIK.setElementPrecision
simIK.getElementWeights
simIK.setElementWeights

IK calculation

simIK.handleGroup
simIK.handleGroups
simIK.findConfigs
simIK.getAlternateConfigs
simIK.computeGroupJacobian
simIK.computeJacobian
simIK.generatePath
simIK.syncToSim
simIK.syncFromSim

simIK.addElement

Description Adds a new IK element to an IK group.
Lua synopsis int elementHandle=simIK.addElement(int environmentHandle,int ikGroupHandle,int tipDummyHandle)
Lua arguments
environmentHandle: the handle of the environment.
ikGroupHandle: the handle of the IK group.
tipDummyHandle: the handle of the dummy object that should act as the tip in the IK element.
Lua return values
elementHandle: the IK element handle in the IK group
Python synopsis int elementHandle=simIK.addElement(int environmentHandle,int ikGroupHandle,int tipDummyHandle)
See also simIK.createEnvironment, simIK.getGroupHandle, simIK.getObjectHandle, simIK.addElementFromScene

simIK.addElementFromScene

Description Convenience function to quickly generate an IK element from a kinematic chain in the scene
Lua synopsis int ikElement,map simToIkObjectMap,map ikToSimObjectMap=simIK.addElementFromScene(int environmentHandle,int ikGroup,int baseHandle,int tipHandle,int targetHandle,int constraints)
Lua arguments
environmentHandle: the handle of the IK environment.
ikGroup: the handle of the IK group, where the IK element should be added.
baseHandle: the handle of the base object in the scene. Can be -1 if the base of the kinematic chain is not moving nor changing orientation.
tipHandle: the handle of the tip object in the scene.
targetHandle: the handle of the target object in the scene.
constraints: the constraints for the IK element that should be created. Bit-combine following: simIK.constraint_x, simIK.constraint_y, simIK.constraint_z, simIK.constraint_alpha_beta, simIK.constraint_gamma (simIK.constraint_gamma should only be set if simIK.constraint_alpha_beta is also set). For convenience we also have simIK.constraint_position=simIK.constraint_x|simIK.constraint_y|simIK.constraint_z, simIK.constraint_orientation=simIK.constraint_alpha_beta|simIK.constraint_gamma, and simIK.constraint_pose=simIK.constraint_position|simIK.constraint_orientation.
Lua return values
ikElement: the handle of the created IK element
simToIkObjectMap: the mapping of scene objects to IK environment objects
ikToSimObjectMap: the mapping of IK environment objects to scene objects
Python synopsis int ikElement,list simToIkObjectMap,list ikToSimObjectMap=simIK.addElementFromScene(int environmentHandle,int ikGroup,int baseHandle,int tipHandle,int targetHandle,int constraints)
See also simIK.addElement

simIK.applyIkEnvironmentToScene

Description Deprecated. Use simIK.syncToSim.
Lua synopsis int result,int reason=simIK.applyIkEnvironmentToScene(int environmentHandle,int ikGroup,bool applyOnlyWhenSuccessful=false)
Lua arguments
environmentHandle: the handle of the IK environment.
ikGroup: the handle of the IK group.
applyOnlyWhenSuccessful: whether computed values should only be applied if computation result is simIK.result_success.
Lua return values
result: simIK.result_success if successfull
Python synopsis int result=simIK.applyIkEnvironmentToScene(int environmentHandle,int ikGroup,bool applyOnlyWhenSuccessful=False)
See also

simIK.applySceneToIkEnvironment

Description Deprecated. Use simIK.syncFromSim instead
Lua synopsis simIK.applySceneToIkEnvironment(int environmentHandle,int ikGroup)
Lua arguments
environmentHandle: the handle of the IK environment.
ikGroup: the handle of the IK group.
Lua return values
Python synopsis simIK.applySceneToIkEnvironment(int environmentHandle,int ikGroup)
See also

simIK.computeGroupJacobian

Description Computes the Jacobian and error vector for an IK group
Lua synopsis float[] jacobian,float[] errorVector=simIK.computeGroupJacobian(int environmentHandle,int ikGroupHandle)
Lua arguments
environmentHandle: the handle of the environment
ikGroupHandle: the handle of an IK group
Lua return values
jacobian: the jacobian (row major order). Each row corresponds to one constraint in following order: x, y, z, alpha, beta, gamma. Each column corresponds to one joint, from base to tip
errorVector: the error vector between the target and the tip
Python synopsis list jacobian,list errorVector=simIK.computeGroupJacobian(int environmentHandle,int ikGroupHandle)
See also simIK.createEnvironment, simIK.handleGroup, simIK.computeJacobian

simIK.computeJacobian

Description Computes the Jacobian and error vector for a kinematic chain
Lua synopsis float[] jacobian,float[] errorVector=simIK.computeJacobian(int environmentHandle,int baseObject,int lastJoint,int constraints,float[7..12] tipMatrix,float[7..12] targetMatrix=nil,float[7..12] constrBaseMatrix=nil)
Lua arguments
environmentHandle: the handle of the environment.
baseObject: the handle of the base of the kinematic chain, or -1 for the world
lastJoint: the handle of the last joint in the kinematic chain, when going from base to tip
constraints: a combination of following is possible: simIK.constraint_x, simIK.constraint_y, simIK.constraint_z, simIK.constraint_alpha_beta, simIK.constraint_gamma. For convenience we also have simIK.constraint_position=simIK.constraint_x|simIK.constraint_y|simIK.constraint_z, simIK.constraint_orientation=simIK.constraint_alpha_beta|simIK.constraint_gamma, and simIK.constraint_pose=simIK.constraint_position|simIK.constraint_orientation
tipMatrix: the transformation matrix or pose of the tip object, relative to the world
targetMatrix: the transformation matrix or pose of the target object, relative to the world. Can be nil, in which case the targetPose is the same as the tipPose
constrMaseMatrix: the transformation matrix or pose that should serve as the reference frame for positional constraints, or nil to use baseHandle as reference frame
Lua return values
jacobian: the jacobian (row major order). Each row corresponds to one constraint in following order: x, y, z, alpha, beta, gamma. Each column corresponds to one joint, from base to tip
errorVector: the error vector between the target and the tip
Python synopsis list jacobian,list errorVector=simIK.computeJacobian(int environmentHandle,int baseObject,int lastJoint,int constraints,list tipMatrix,list targetMatrix=None,list constrBaseMatrix=None)
See also simIK.createEnvironment, simIK.handleGroup, simIK.computeGroupJacobian

simIK.createDebugOverlay

Description Creates a visual representation of an IK chain.
Lua synopsis int objectHandle=simIK.createDebugOverlay(int environmentHandle,int tipHandle,int baseHandle=-1)
Lua arguments
environmentHandle: the handle of the environment.
tipHandle: the handle of the tip dummy.
baseHandle: the handle of the base object.
Lua return values
objectHandle: the handle of the visual overlay object.
Python synopsis int objectHandle=simIK.createDebugOverlay(int environmentHandle,int tipHandle,int baseHandle=-1)
See also simIK.eraseDebugOverlay

simIK.createDummy

Description Creates a dummy object.
Lua synopsis int dummyHandle=simIK.createDummy(int environmentHandle,string dummyName='')
Lua arguments
environmentHandle: the handle of the environment.
dummyName: the name of the dummy.
Lua return values
dummyHandle: the handle of the dummy.
Python synopsis int dummyHandle=simIK.createDummy(int environmentHandle,string dummyName='')
See also simIK.createEnvironment, simIK.doesObjectExist, simIK.createJoint, simIK.eraseObject

simIK.createEnvironment

Description Creates an new IK environment.
Lua synopsis int environmentHandle=simIK.createEnvironment(int flags=0)
Lua arguments
flags: reserved, keep at 0.
Lua return values
environmentHandle: the handle of the newly created environment.
Python synopsis int environmentHandle=simIK.createEnvironment()
See also simIK.eraseEnvironment, simIK.load

simIK.createGroup

Description Creates an IK group.
Lua synopsis int ikGroupHandle=simIK.createGroup(int environmentHandle,string ikGroupName='')
Lua arguments
environmentHandle: the handle of the environment.
ikGroupName: the name of the IK group.
Lua return values
ikGroupHandle: the handle of the IK group.
Python synopsis int ikGroupHandle=simIK.createGroup(int environmentHandle,string ikGroupName='')
See also simIK.createEnvironment, simIK.doesGroupExist

simIK.createJoint

Description Creates a joint object.
Lua synopsis int jointHandle=simIK.createJoint(int environmentHandle,string jointName='')
Lua arguments
environmentHandle: the handle of the environment.
jointName: the name of the joint.
jointType: the type of the joint. Supported types are simIK.jointtype_revolute, simIK.jointtype_prismatic and simIK.jointtype_spherical.
Lua return values
jointHandle: the handle of the joint.
Python synopsis int jointHandle=simIK.createJoint(int environmentHandle,string jointName='')
See also simIK.createEnvironment, simIK.doesObjectExist, simIK.createDummy, simIK.eraseObject

simIK.doesObjectExist

Description Checks whether an object exists, based on its name.
Lua synopsis bool result=simIK.doesObjectExist(int environmentHandle,string objectName)
Lua arguments
environmentHandle: the handle of the environment.
objectName: the name of the object.
Lua return values
result: true if the object exists.
Python synopsis bool result=simIK.doesObjectExist(int environmentHandle,string objectName)
See also simIK.createEnvironment, simIK.getObjectHandle

simIK.doesGroupExist

Description Checks whether an IK group exists, based on its name.
Lua synopsis bool result=simIK.doesGroupExist(int environmentHandle,string ikGroupName)
Lua arguments
environmentHandle: the handle of the environment.
ikGroupName: the name of the IK group.
Lua return values
result: true if the IK group exists.
Python synopsis bool result=simIK.doesGroupExist(int environmentHandle,string ikGroupName)
See also simIK.createEnvironment, simIK.getGroupHandle

simIK.duplicateEnvironment

Description Duplicates an IK environment. Useful when operating on an environment while leaving the original environment unchanged.
Lua synopsis int newEnvironmentHandle=simIK.duplicateEnvironment(int environmentHandle)
Lua arguments
environmentHandle: the handle of the environment.
Lua return values
newEnvironmentHandle: the handle of the duplicated environment.
Python synopsis int newEnvironmentHandle=simIK.duplicateEnvironment(int environmentHandle)
See also simIK.eraseEnvironment, simIK.createEnvironment

simIK.eraseDebugOverlay

Description Removes the visual representation of an IK chain.
Lua synopsis simIK.eraseDebugOverlay(int objectHandle)
Lua arguments
objectHandle: the handle of the visual overlay object.
Lua return values
Python synopsis simIK.eraseDebugOverlay(int objectHandle)
See also simIK.createDebugOverlay

simIK.eraseEnvironment

Description Erases an IK environment.
Lua synopsis simIK.eraseEnvironment(int environmentHandle)
Lua arguments
environmentHandle: the handle of the environment.
Lua return values
Python synopsis simIK.eraseEnvironment(int environmentHandle)
See also simIK.createEnvironment

simIK.eraseObject

Description Erases an object.
Lua synopsis simIK.eraseObject(int environmentHandle,int objectHandle)
Lua arguments
environmentHandle: the handle of the environment.
objectHandle: handle of the object.
Lua return values
Python synopsis simIK.eraseObject(int environmentHandle,int objectHandle)
See also simIK.createEnvironment, simIK.getObjectHandle, simIK.createDummy, simIK.createJoint

simIK.findConfigs

Description Searches for one or several manipulator configurations that match the target dummy/dummies position/orientation in space. Search is randomized. The IK environment remains unchanged.
Lua synopsis float[][] configs=simIK.findConfigs(int environmentHandle,int ikGroupHandle,int[] jointHandles,map params={}, float[][] configs={})
Lua arguments
environmentHandle: the handle of the environment.
ikGroupHandle: the handle of the IK group.
jointHandles: a table that specifies the joint handles for the joints we wish to retrieve the values calculated by the IK.
params: optional parameters:
    maxDist: an optional distance indicating when IK should be computed in order to try to bring the tip onto the target: since the search algorithm proceeds by generating random configurations, many of them produce a tip pose that might be too far from the target pose to run IK successfully. Choosing a large value will result in slow calculations, choosing a small value might produce a smaller subset of solutions. Distance between two poses is calculated using the metric pMetric
    maxTime: an optional upper time limit, in seconds, after which the function returns
    pMetric: an optional table to 4 values indicating a metric used to compute pose-pose distances: distance=sqrt((dx*metric[1])^2+(dy*metric[2])^2+(dz*metric[3])^2+(angle*metric[4])^2)
    cMetric: an optional table to n values indicating a metric used to compute config-config distances
    findAlt: an optional boolean indicating if alternate configurations are returned too. If a manipulator has one or more revolute joints that have a limited range of more than 360 degrees, then there are alternate configurations
    findMultiple: an optional boolean indicating if additional configurations should be searched, until maxTime has elapsed
    cb: an optional callback function expressed as a function or a string. The callback function takes as input arguments the proposed joint values (i.e. a configuration) and auxData, and as return value whether the configuration is valid (e.g. is not colliding).
    auxData: optional auxiliary data handed to the validation callback function
configs: configurations previously calculated, that should be added to the newly calculated configurations, as return value
Lua return values
configs: an array of configurations, sorted from closest to farthest from the current configuration (using the metric cMetric)
Python synopsis list[] configs=simIK.findConfigs(int environmentHandle,int ikGroupHandle,list jointHandles,dict params={}, list[] configs=[])
See also simIK.createEnvironment, simIK.duplicateEnvironment, simIK.computeJacobian

simIK.findConfig

Description Deprecated. See simIK.findConfigs instead.
Lua synopsis float[] jointPositions=simIK.findConfig(int environmentHandle,int ikGroupHandle,int[] jointHandles,float thresholdDist=0.1,float maxTime=0.5,float[4] metric={1,1,1,0.1},func/string validationCallback=nil,auxData=nil)
Lua arguments
environmentHandle: the handle of the environment.
ikGroupHandle: the handle of the IK group.
jointHandles: a table that specifies the joint handles for the joints we wish to retrieve the values calculated by the IK.
thresholdDist: a distance indicating when IK should be computed in order to try to bring the tip onto the target: since the search algorithm proceeds by generating random configurations, many of them produce a tip pose that is too far from the target pose to run IK successfully. Choosing a large value will result in slow calculations, choosing a small value might produce a smaller subset of solutions. Distance between two poses is calculated using a metric (see metric argument below).
maxTime: the upper time limit, in seconds, after which the function returns.
metric: a table to 4 values indicating a metric used to compute pose-pose distances: distance=sqrt((dx*metric[1])^2+(dy*metric[2])^2+(dz*metric[3])^2+(angle*metric[4])^2).
validationCallback: an optional callback function expressed as a function or a string. The callback function takes as input arguments the proposed joint values (i.e. a configuration) and auxData, and as return value whether the configuration is valid (e.g. is not colliding).
auxData: auxiliary data that will be handed to the validation callback.
Lua return values
jointPositions: a table that contains the IK calculated joint values, as specified by the jointHandles table, if a valid configuration was found.
Python synopsis list jointPositions=simIK.findConfig(int environmentHandle,int ikGroupHandle,list jointHandles,float thresholdDist=0.1,float maxTime=0.5,list metric=[1,1,1,0.1],function/string validationCallback=None,auxData=None)
See also simIK.findConfigs

simIK.generatePath

Description Generates a path that drives the IK tip onto its IK target, in a straight line (i.e. shortest path in Cartesian space). The function returns a path in the configuration space if the operation was successful. A reason for a non-successful operation can be: there are some forbidden poses/configurations on the way, or some of the configuration points cannot be reached (e.g. out of reach, or due to joint limits). The IK environment remains unchanged.
Lua synopsis float[] configurationList=simIK.generatePath(int environmentHandle,int ikGroupHandle,int[] jointHandles,int tipHandle,int pathPointCount,function/string validationCallback=nil,auxData=nil
Lua arguments
environmentHandle: the handle of the environment.
ikGroupHandle: the IK group handle.
jointHandles: a table that specifies the joint handles for the joints we wish to retrieve the values calculated by the IK.
tipHandle: the handle of the tip object.
pathPointCount: the desired number of path points. Each path point contains a joint configuration. A minimum of two path points is required.
validationCallback: an optional callback function, expressed as a function or string. The callback function takes as input arguments proposed joint values (i.e. a configuration) and auxData, and as return value whether the configuration is valid (e.g. is not colliding).
auxData: auxiliary data that will be handed to the validation callback.
Lua return values
configurationList: a table that contains configurations (in row-major order) that will bring the IK tip onto its IK target.
Python synopsis list configurationList=simIK.generatePath(int environmentHandle,int ikGroupHandle,list jointHandles,int tipHandle,int pathPointCount,function/string validationCallback=None,auxData=None
See also simIK.duplicateEnvironment

simIK.getAlternateConfigs

Description Generates alternative manipulator configurations, for a same end-effector pose, for a manipulator that has revolute joints with a range larger than 360 degrees. The original submitted configuration will be part of the returned configurations. The IK environment remains unchanged.
Lua synopsis float[] configurations=simIK.getAlternateConfigs(int environmentHandle,int[] jointHandles,float[] lowLimits=nil,float[] ranges=nil)
Lua arguments
environmentHandle: the handle of the environment.
jointHandles: a table with the handles of the manipulator joints.
lowLimits: a table with joint low limit values for each specified joint. This can be useful when you wish to explore a sub-set of the joint's intervals.
ranges: a table with joint range values for each specified joint. This can be useful when you wish to explore a sub-set of the joint's intervals. If the range value is 0, then the lowLimit and range values are taken from the joint's properties. If the range value is negative, then the search interval will be centered around the current linear/angular joint position, with an extent of (-range).
Lua return values
configurations: a table containing configurations (in row-major order) that are equivalent to the specified inputConfig, in terms of end-effector pose.
Python synopsis list configurations=simIK.getAlternateConfigs(int environmentHandle,list jointHandles,list lowLimits=None,list ranges=None)
See also simIK.createEnvironment

simIK.getConfigForTipPose

Description Deprecated. See simIK.findConfigs instead.
Lua synopsis float[] jointPositions=simIK.getConfigForTipPose(int environmentHandle,int ikGroupHandle,int[] jointHandles,float thresholdDist=0.1,float maxTime=0.5,float[4] metric={1,1,1,0.1},function validationCallback=nil,auxData=nil,int[] jointOptions={},float[] lowLimits={},float[] ranges={})
Lua arguments
environmentHandle: the handle of the environment.
ikGroupHandle: the handle of the IK group.
jointHandles: a table that specifies the joint handles for the joints we wish to retrieve the values calculated by the IK.
thresholdDist: a distance indicating when IK should be computed in order to try to bring the tip onto the target: since the search algorithm proceeds by generating random configurations, many of them produce a tip pose that is too far from the target pose to run IK successfully. Choosing a large value will result in slow calculations, choosing a small value might produce a smaller subset of solutions. Distance between two poses is calculated using a metric (see metric argument below).
maxTime: the upper time limit, in seconds, after which the function returns.
metric: a table to 4 values indicating a metric used to compute pose-pose distances: distance=sqrt((dx*metric[1])^2+(dy*metric[2])^2+(dz*metric[3])^2+(angle*metric[4])^2).
validationCallback: an optional callback function. The callback function takes as input arguments the proposed joint values (i.e. a configuration) and auxData, and as return value whether the configuration is valid (e.g. is not colliding).
auxData: auxiliary data that will be handed to the validation callback.
jointOptions: a table with bit-coded values corresponding to each specified joint handle. Bit 0 (i.e. 1) indicates the corresponding joint is dependent of another joint.
lowLimits: a table with joint low limit values for each specified joint. This can be useful when you wish to explore a sub-set of the joint's intervals.
ranges: a table with joint range values for each specified joint. This can be useful when you wish to explore a sub-set of the joint's intervals. If the range value is 0, then the lowLimit and range values are taken from the joint's properties. If the range value is negative, then the search interval will be centered around the current linear/angular joint position, with an extent of (-range).
Lua return values
jointPositions: a table that contains the IK calculated joint values, as specified by the jointHandles table, if a valid configuration was found.
Python synopsis list jointPositions=simIK.getConfigForTipPose(int environmentHandle,int ikGroupHandle,list jointHandles,float thresholdDist=0.1,float maxTime=0.5,list metric=[1,1,1,0.1],function validationCallback=None,auxData=None,list jointOptions=[],list lowLimits=[],list ranges=[])
See also simIK.createEnvironment, simIK.duplicateEnvironment, simIK.getAlternateConfigs, simIK.computeJacobian

simIK.getElementBase

Description Retrieves the base object of an IK element.
Lua synopsis int baseHandle,int constraintsBaseHandle=simIK.getElementBase(int environmentHandle,int ikGroupHandle,int elementHandle)
Lua arguments
environmentHandle: the handle of the environment.
ikGroupHandle: the handle of the IK group.
elementHandle: the IK element handle, or X, where X=handleOfTipDummy+simIK.handleflag_tipdummy (if several IK elements with the same tip dummy exist, then the first encountered will be selected).
Lua return values
baseHandle: the handle of the base object, or -1 if the world is the base.
constraintsBaseHandle: the handle of the constraints base object, relative to which the constraints are specified. Returns -1 if the constraints are relative to the base object.
Python synopsis int baseHandle,int constraintsBaseHandle=simIK.getElementBase(int environmentHandle,int ikGroupHandle,int elementHandle)
See also simIK.createEnvironment, simIK.setElementBase, simIK.getGroupHandle, simIK.getObjectHandle

simIK.getElementConstraints

Description Retrieves the constraints of an IK element.
Lua synopsis int constraints=simIK.getElementConstraints(int environmentHandle,int ikGroupHandle,int elementHandle)
Lua arguments
environmentHandle: the handle of the environment.
ikGroupHandle: the handle of the IK group.
elementHandle: the IK element handle, or X, where X=handleOfTipDummy+simIK.handleflag_tipdummy (if several IK elements with the same tip dummy exist, then the first encountered will be selected).
Lua return values
constraints: the constraints. A bit-combination of following is possible: simIK.constraint_x, simIK.constraint_y, simIK.constraint_z, simIK.constraint_alpha_beta, simIK.constraint_gamma.
Python synopsis int constraints=simIK.getElementConstraints(int environmentHandle,int ikGroupHandle,int elementHandle)
See also simIK.createEnvironment, simIK.setElementConstraints, simIK.getGroupHandle, simIK.getObjectHandle

simIK.getElementFlags

Description Retrieves various flags of an IK element.
Lua synopsis int flags=simIK.getElementFlags(int environmentHandle,int ikGroupHandle,int elementHandle)
Lua arguments
environmentHandle: the handle of the environment.
ikGroupHandle: the handle of the IK group.
elementHandle: the IK element handle, or X, where X=handleOfTipDummy+simIK.handleflag_tipdummy (if several IK elements with the same tip dummy exist, then the first encountered will be selected).
Lua return values
flags: bit-coded flags: bit0 set(1)=the enabled state of the ik element.
Python synopsis int flags=simIK.getElementFlags(int environmentHandle,int ikGroupHandle,int elementHandle)
See also simIK.createEnvironment, simIK.setElementFlags, simIK.getGroupHandle, simIK.getObjectHandle

simIK.getElementPrecision

Description Retrieves the precision settings of an IK element.
Lua synopsis float[2] precision=simIK.getElementPrecision(int environmentHandle,int ikGroupHandle,int elementHandle)
Lua arguments
environmentHandle: the handle of the environment.
ikGroupHandle: the handle of the IK group.
elementHandle: the IK element handle, or X, where X=handleOfTipDummy+simIK.handleflag_tipdummy (if several IK elements with the same tip dummy exist, then the first encountered will be selected).
Lua return values
precision: a table with the linear and angular precision.
Python synopsis list precision=simIK.getElementPrecision(int environmentHandle,int ikGroupHandle,int elementHandle)
See also simIK.createEnvironment, simIK.setElementPrecision, simIK.getGroupHandle, simIK.getObjectHandle

simIK.getElementWeights

Description Retrieves the desired linear and angular resolution weights of an IK element.
Lua synopsis float[3] weights=simIK.getElementWeights(int environmentHandle,int ikGroupHandle,int elementHandle)
Lua arguments
environmentHandle: the handle of the environment.
ikGroupHandle: the handle of the IK group.
elementHandle: the IK element handle, or X, where X=handleOfTipDummy+simIK.handleflag_tipdummy (if several IK elements with the same tip dummy exist, then the first encountered will be selected).
Lua return values
weights: a table with the linear, angular and overall resolution weights.
Python synopsis list weights=simIK.getElementWeights(int environmentHandle,int ikGroupHandle,int elementHandle)
See also simIK.createEnvironment, simIK.setElementWeights, simIK.getGroupHandle, simIK.getObjectHandle

simIK.getGroupCalculation

Description Retrieves calculation properties for an IK group.
Lua synopsis int method,float damping,int maxIterations=simIK.getGroupCalculation(int environmentHandle,int ikGroupHandle)
Lua arguments
environmentHandle: the handle of the environment.
ikGroupHandle: the handle of the IK group.
Lua return values
method: the resolution method. Possible values are simIK.method_pseudo_inverse (features a tiny bit of hard-coded damping), simIK.method_undamped_pseudo_inverse, simIK.method_damped_least_squares and simIK.method_jacobian_transpose.
damping: the damping, in case the resolution method is simIK.method_damped_least_squares.
maxIterations: the maximum number of iterations.
Python synopsis int method,float damping,int maxIterations=simIK.getGroupCalculation(int environmentHandle,int ikGroupHandle)
See also simIK.createEnvironment, simIK.setGroupCalculation, simIK.getGroupHandle

simIK.getGroupFlags

Description Retrieves flags of an IK group.
Lua synopsis int flags=simIK.getGroupFlags(int environmentHandle,int ikGroupHandle))
Lua arguments
environmentHandle: the handle of the environment.
ikGroupHandle: the handle of the IK group.
Lua return values
flags: the flags of the IK group, bit-coded:
simIK.group_enabled: the group's enabled state
simIK.group_ignoremaxsteps: the joints' max step sizes are ignored. Otherwise, when detected, an interpolation factor (originally at 1.0) is successively divided by 2.0 until the max. step sizes are respected
simIK.group_restoreonbadlintol: the IK world state is left untouched if the linear precision is not reached
simIK.group_restoreonbadangtol: the IK world state is left untouched if the angular precision is not reached
simIK.group_avoidlimits: joint limits are actively avoided
simIK.group_stoponlimithit: calculation ends when a joint limit is hit
Python synopsis int flags=simIK.getGroupFlags(int environmentHandle,int ikGroupHandle))
See also simIK.createEnvironment, simIK.setGroupFlags, simIK.getGroupHandle

simIK.getGroupHandle

Description Retrieves the handle of an IK group based on its name.
Lua synopsis int ikGroupHandle=simIK.getGroupHandle(int environmentHandle,string ikGroupName)
Lua arguments
environmentHandle: the handle of the environment.
ikGroupName: the name of the IK group.
Lua return values
ikGroupHandle: the handle of the IK group.
Python synopsis int ikGroupHandle=simIK.getGroupHandle(int environmentHandle,string ikGroupName)
See also simIK.createEnvironment, simIK.doesGroupExist, simIK.createGroup

simIK.getGroupJointLimitHits

Description Checks which joints of an IK group hit a limit last time that IK group was handled
Lua synopsis int[] jointHandles,float[] underOrOvershots=simIK.getGroupJointLimitHits(int environmentHandle,int ikGroupHandle)
Lua arguments
environmentHandle: the handle of the environment.
ikGroupHandle: the handle of the IK group.
Lua return values
jointHandles: the joint handles that that had joint limits under- or overshot
underOrOvershots: the corresponding under- or overshots, for each of the jointHandles
Python synopsis list jointHandles,list underOrOvershots=simIK.getGroupJointLimitHits(int environmentHandle,int ikGroupHandle)
See also simIK.setGroupFlags

simIK.getGroupJoints

Description Returns the joint handles involved in the IK group calculation, i.e. one handle per Jacobian column (except with revolute joints that have 3 corresponding Jacobian columns)
Lua synopsis int[] jointHandles=simIK.getGroupJoints(int environmentHandle,int ikGroupHandle)
Lua arguments
environmentHandle: the handle of the environment
ikGroupHandle: the handle of the IK group
Lua return values
jointHandles: the joint handles
Python synopsis list jointHandles=simIK.getGroupJoints(int environmentHandle,int ikGroupHandle)
See also

simIK.getJointDependency

Description Retrieves information about a possible joint dependency.
Lua synopsis int depJointHandle,float offset,float mult=simIK.getJointDependency(int environmentHandle,int jointHandle)
Lua arguments
environmentHandle: the handle of the environment.
jointHandle: the handle of the joint.
Lua return values
depJointHandle: the handle of the dependency joint.
offset: the offset. We have linear/angular joint position = dependency linear/angular joint position * mult + offset.
mult: the multiplication factor. We have linear/angular joint position = dependency linear/angular joint position * mult + offset.
Python synopsis int depJointHandle,float offset,float mult=simIK.getJointDependency(int environmentHandle,int jointHandle)
See also simIK.createEnvironment, simIK.setJointDependency, simIK.getObjectHandle

simIK.getJointWeight

Description Retrieves the IK weight of a joint, i.e. the weight it has during IK resolution.
Lua synopsis float weight=simIK.getJointWeight(int environmentHandle,int jointHandle)
Lua arguments
environmentHandle: the handle of the environment.
jointHandle: the handle of the joint.
Lua return values
weight: the IK weight.
Python synopsis float weight=simIK.getJointWeight(int environmentHandle,int jointHandle)
See also simIK.createEnvironment, simIK.setJointWeight, simIK.getObjectHandle

simIK.getJointInterval

Description Retrieves the joint limits.
Lua synopsis bool cyclic,float[2] interval=simIK.getJointInterval(int environmentHandle,int jointHandle)
Lua arguments
environmentHandle: the handle of the environment.
jointHandle: the handle of the joint.
Lua return values
cyclic: whether the joint is cyclic (has no limits).
interval: a table with two values: the joint lower limit, and the joint range (i.e. joint upper limit = joint lower limit + joint range)
Python synopsis bool cyclic,list interval=simIK.getJointInterval(int environmentHandle,int jointHandle)
See also simIK.createEnvironment, simIK.setJointInterval, simIK.getObjectHandle

simIK.getJointLimitMargin

Description Retrieves the limit margin of a joint, i.e. the threshold that will be used to counteract on joint limit violation during IK resolution, if the appropriate IK group flag was set
Lua synopsis float margin=simIK.getJointLimitMargin(int environmentHandle,int jointHandle)
Lua arguments
environmentHandle: the handle of the environment.
jointHandle: the handle of the joint.
Lua return values
margin: the margin
Python synopsis float margin=simIK.getJointLimitMargin(int environmentHandle,int jointHandle)
See also simIK.createEnvironment, simIK.setJointLimitMargin, simIK.getGroupFlags

simIK.getJointMatrix

Description Retrieves the intrinsic transformation matrix of a joint.
Lua synopsis float[12] matrix=simIK.getJointMatrix(int environmentHandle,int jointHandle)
Lua arguments
environmentHandle: the handle of the environment.
jointHandle: the handle of the joint.
Lua return values
matrix: a table of 12 numbers representing the transformation matrix (the last row of the 4x4 matrix (0,0,0,1) is not returned).
Python synopsis list matrix=simIK.getJointMatrix(int environmentHandle,int jointHandle)
See also simIK.createEnvironment, simIK.setSphericalJointMatrix, simIK.getJointPosition, simIK.getJointTransformation, simIK.getObjectHandle

simIK.getJointMaxStepSize

Description Retrieves the maximum step size of a joint.
Lua synopsis float stepSize=simIK.getJointMaxStepSize(int environmentHandle,int jointHandle)
Lua arguments
environmentHandle: the handle of the environment.
jointHandle: the handle of the joint.
Lua return values
stepSize: the maximum step size.
Python synopsis float stepSize=simIK.getJointMaxStepSize(int environmentHandle,int jointHandle)
See also simIK.createEnvironment, simIK.setJointMaxStepSize, simIK.getObjectHandle

simIK.getJointMode

Description Retrieves the joint mode.
Lua synopsis int jointMode=simIK.getJointMode(int environmentHandle,int jointHandle)
Lua arguments
environmentHandle: the handle of the environment.
jointHandle: the handle of the joint.
Lua return values
jointMode: the joint mode. Possible values are: simIK.jointmode_passive, simIK.jointmode_ik
Python synopsis int jointMode=simIK.getJointMode(int environmentHandle,int jointHandle)
See also simIK.createEnvironment, simIK.setJointMode, simIK.getObjectHandle

simIK.getJointPosition

Description Retrieves the position (linear or angular) of a joint.
Lua synopsis float position=simIK.getJointPosition(int environmentHandle,int jointHandle)
Lua arguments
environmentHandle: the handle of the environment.
jointHandle: the handle of the joint.
Lua return values
position: the position.
Python synopsis float position=simIK.getJointPosition(int environmentHandle,int jointHandle)
See also simIK.createEnvironment, simIK.setJointPosition, simIK.getJointMatrix, simIK.getJointTransformation, simIK.getObjectHandle

simIK.getJointScrewLead

Description Retrieves the screw lead of a revolute joint.
Lua synopsis float lead=simIK.getJointScrewLead(int environmentHandle,int jointHandle)
Lua arguments
environmentHandle: the handle of the environment.
jointHandle: the handle of the joint.
Lua return values
lead: the screw lead of the joint. A lead value of zero represents a revolute joint, a value different from zero represents a screw.
Python synopsis float lead=simIK.getJointScrewLead(int environmentHandle,int jointHandle)
See also simIK.createEnvironment, simIK.setJointScrewLead, simIK.getObjectHandle

simIK.getJointTransformation

Description Retrieves the intrinsic transformation of a joint.
Lua synopsis float[3] position,float[4] quaternion,float[3] euler=simIK.getJointTransformation(int environmentHandle,int jointHandle)
Lua arguments
environmentHandle: the handle of the environment.
jointHandle: the handle of the joint.
Lua return values
position: the translation of the joint.
quaternion: the rotation of the joint, expressed as quaternion (x,y,z,w).
euler: the rotation of the joint, expressed as Euler angles (alpha,beta,gamma).
Python synopsis list position,list quaternion,list euler=simIK.getJointTransformation(int environmentHandle,int jointHandle)
See also simIK.createEnvironment, simIK.setSphericalJointRotation, simIK.getJointPosition, simIK.getJointMatrix, simIK.getObjectHandle

simIK.getJointType

Description Retrieves the joint type.
Lua synopsis int jointType=simIK.getJointType(int environmentHandle,int jointHandle)
Lua arguments
environmentHandle: the handle of the environment.
jointHandle: the handle of the joint.
Lua return values
jointType: the joint type. Possible values are: simIK.jointtype_revolute, simIK.jointtype_prismatic and simIK.jointtype_spherical
Python synopsis int jointType=simIK.getJointType(int environmentHandle,int jointHandle)
See also simIK.createJoint

simIK.getLinkedDummy

Description Deprecated. Use simIK.getTargetDummy instead
Lua synopsis int linkedDummyHandle=simIK.getLinkedDummy(int environmentHandle,int dummyHandle)
Lua arguments
environmentHandle: the handle of the environment.
dummyHandle: the handle of the dummy object.
Lua return values
linkedDummyHandle: the handle of the linked dummy object. Is -1 if no dummy object is linked to this one.
Python synopsis int linkedDummyHandle=simIK.getLinkedDummy(int environmentHandle,int dummyHandle)
See also simIK.createEnvironment, simIK.setLinkedDummy, simIK.getObjectHandle

simIK.getObjectHandle

Description Retrieves the handle of an object based on its name.
Lua synopsis int objectHandle=simIK.getObjectHandle(int environmentHandle,string objectName)
Lua arguments
environmentHandle: the handle of the environment.
objectName: the name of the object.
Lua return values
objectHandle: the object handle.
Python synopsis int objectHandle=simIK.getObjectHandle(int environmentHandle,string objectName)
See also simIK.createEnvironment, simIK.doesObjectExist, simIK.createDummy, simIK.createJoint

simIK.getObjectMatrix

Description Retrieves the transformation matrix of an object. If the object is a joint object, the matrix does not include the joint's intrinsic transformation.
Lua synopsis float[12] matrix=simIK.getObjectMatrix(int environmentHandle,int objectHandle,int relativeToObjectHandle=simIK.handle_world)
Lua arguments
environmentHandle: the handle of the environment.
objectHandle: the handle of the object.
relativeToObjectHandle: the handle of an object relative to which we want the matrix expressed. Otherwise, specify simIK.handle_world if you want the absolute matrix, or simIK.handle_parent if you want the matrix relative to the parent object.
Lua return values
matrix: a table of 12 numbers representing the transformation matrix (the last row of the 4x4 matrix (0,0,0,1) is not returned)
Python synopsis list matrix=simIK.getObjectMatrix(int environmentHandle,int objectHandle,int relativeToObjectHandle=simIK.handle_world)
See also simIK.createEnvironment, simIK.setObjectMatrix, simIK.getObjectPose,simIK.getObjectTransformation, simIK.getJointTransformation, simIK.getObjectHandle

simIK.getObjectParent

Description Retrieves an object's parent handle.
Lua synopsis int parentObjectHandle=simIK.getObjectParent(int environmentHandle,int objectHandle)
Lua arguments
environmentHandle: the handle of the environment.
objectHandle: the handle of the object.
Lua return values
parentObjectHandle: the returned handle of the parent, or -1 if the object has no parent.
Python synopsis int parentObjectHandle=simIK.getObjectParent(int environmentHandle,int objectHandle)
See also simIK.createEnvironment, simIK.setObjectParent, simIK.getObjectHandle

simIK.getObjectPose

Description Retrieves the pose (position and quaternion) of an object. If the object is a joint object, the pose does not include the joint's intrinsic transformation.
Lua synopsis float[7] pose=simIK.getObjectPose(int environmentHandle,int objectHandle,int relativeToObjectHandle=simIK.handle_world)
Lua arguments
environmentHandle: the handle of the environment.
objectHandle: the handle of the object.
relativeToObjectHandle: the handle of an object relative to which we want the pose expressed. Otherwise, specify simIK.handle_world if you want the absolute pose, or simIK.handle_parent if you want the pose relative to the parent object.
Lua return values
pose: the position and quaternion of the object (x,y,z,qx,qy,qz,qw).
Python synopsis list pose=simIK.getObjectPose(int environmentHandle,int objectHandle,int relativeToObjectHandle=simIK.handle_world)
See also simIK.createEnvironment, simIK.setObjectPose, simIK.getObjectTransformation, simIK.getObjectMatrix, simIK.getJointTransformation, simIK.getObjectHandle

simIK.getObjects

Description Allows to loop through all objects in the environment.
Lua synopsis int objectHandle,string objectName,bool isJoint,int jointType=simIK.getObjects(int environmentHandle,int index)
Lua arguments
environmentHandle: the handle of the environment.
index: the zero-based index. Start at 0, and increment until there is no return values anymore, in order to loop through all objects in the environment.
Lua return values
objectHandle: the handle of the object, or nil if there is no object at the specified index.
objectName: the name of the object.
isJoint: whether the object is a joint.
jointType: the type of joint, if the object at the specified index is a joint. Possible values are simIK.jointtype_revolute, simIK.jointtype_prismatic or simIK.jointtype_spherical.
Python synopsis int objectHandle,string objectName,bool isJoint,int jointType=simIK.getObjects(int environmentHandle,int index)
See also simIK.getObjectHandle, simIK.doesObjectExist

simIK.getObjectTransformation

Description Retrieves the transformation (position and quaternion/euler angles) of an object. If the object is a joint object, the transformation does not include the joint's intrinsic transformation.
Lua synopsis float[3] position,float[4] quaternion,float[3] euler=simIK.getObjectTransformation(int environmentHandle,int objectHandle,int relativeToObjectHandle=simIK.handle_world)
Lua arguments
environmentHandle: the handle of the environment.
objectHandle: the handle of the object.
relativeToObjectHandle: the handle of an object relative to which we want the transformation expressed. Otherwise, specify simIK.handle_world if you want the absolute transformation, or simIK.handle_parent if you want the transformation relative to the parent object.
Lua return values
position: the position of the object.
quaternion: the orientation of the object, expressed as quaternion (x,y,z,w).
euler: the orientation of the object, expressed as Euler angles (alpha,beta,gamma).
Python synopsis list position,list quaternion,list euler=simIK.getObjectTransformation(int environmentHandle,int objectHandle,int relativeToObjectHandle=simIK.handle_world)
See also simIK.createEnvironment, simIK.setObjectTransformation, simIK.getObjectPose, simIK.getObjectMatrix, simIK.getJointTransformation, simIK.getObjectHandle

simIK.getObjectType

Description Retrieves the type of an object.
Lua synopsis int objectType=simIK.getObjectType(int environmentHandle,int objectHandle)
Lua arguments
environmentHandle: the handle of the environment.
objectHandle: the handle of the object.
Lua return values
objectType: the returned type of the object.
Python synopsis int objectType=simIK.getObjectType(int environmentHandle,int objectHandle)
See also

simIK.getTargetDummy

Description Retrieves the handle of the target dummy associated with a tip dummy
Lua synopsis int targetDummyHandle=simIK.getTargetDummy(int environmentHandle,int tipDummyHandle)
Lua arguments
environmentHandle: the handle of the environment
tipDummyHandle: the handle of the tip dummy
Lua return values
targetDummyHandle: the handle of the target dummy. Is -1 if no target dummy is associated with the tip dummy
Python synopsis int targetDummyHandle=simIK.getTargetDummy(int environmentHandle,int tipDummyHandle)
See also simIK.createEnvironment, simIK.setTargetDummy, simIK.getObjectHandle

simIK.handleGroup

Description Handles (i.e. computes/resolves) an IK group. Convenience function for simIK.handleIkGroups(ikEnv,{ikGroupHandle},..)
Lua synopsis int result,int flags,float[2] precision=simIK.handleGroup(int environmentHandle,int ikGroupHandle,map options={})
Lua arguments
environmentHandle: the handle of the environment
ikGroupHandle: the handle of the IK group
options: options:
options.syncWorlds: if true, then calculation will be preceeded by simIK.syncFromSim and followed by simIK.syncToSim
options.allowError: if true, and options.syncWorlds is true too, then calculation result will be applied to the scene, even if tip/target pairs are not within tolerance
options.debug: bit0 is set, then a visual representation of the IK group will be made
options.callback: a callback function that allows to inspect and manipulate the Jacobian. It also allows to directly perform joint valiation calculations while skipping internal computations:
outData=callbackFunction(inData)
inData.jacobian: a Matrix object representing the Jacobian
inData.e: a Vector object representing the error vector
inData.rows: a table describing the jacobian rows
inData.cols: a table describing the jacobian cols
outData.jacobian: an optional Matrix object representing the Jacobian to use in subsequent calculations. If not provided, then the original inData.jacobian is used
outData.e: an optional Vector object representing the error vector to use in subsequent calculations. If not provided, then the original inData.e is used
outData.dq: an optional Vector object representing the joint variation to apply. If provided, then internal Jacobian calculations (i.e. Jacobian pseudo-inverse) will be skipped)
outData.jacobianPinv: an optional Matrix object representing the jacobian pseudo-inverse. If provided (and dq is not provided), then internal Jacobian calculations will be skipped and following executed instead: dq=outData.jacobianPinv*e)
Lua return values
result: simIK.result_success, if successful
reason: bit-coded flags: simIK.calc_notperformed, simIK.calc_cannotinvert, simIK.calc_notwithintolerance, simIK.calc_stepstoobig, simIK.calc_limithit
precision: 2 values indicating the largest linear and angular distance between all tip-target pairs
Python synopsis int result,int flags,list precision=simIK.handleGroup(int environmentHandle,int ikGroupHandle,map options=None)
See also simIK.handleGroups,simIK.createEnvironment, simIK.computeJacobian, simIK.findConfigs

simIK.handleGroups

Description Handles (i.e. computes/resolves) one or several IK groups
Lua synopsis int result,int flags,float[2] precision=simIK.handleGroups(int environmentHandle,int[] ikGroupHandles,map options={})
Lua arguments
environmentHandle: the handle of the environment
ikGroupHandles: the handles of the IK groups. If one handle is specified, then a simple IK calculation is performed. If more than one handle is specified, then a projected IK computation is performed, where each group calculation result is projected into the previous group's null space, i.e. dq=dq0+NP0*(dq1+NP1*(dq2+NP2*(...))), where dqi is the result of i-th task's IK (i.e. typically J#*e), and NPi is the i-th task's I-J#*J
options: options:
options.syncWorlds: if true, then calculation will be preceeded by simIK.syncFromSim and followed by simIK.syncToSim
options.allowError: if true, and options.syncWorlds is true too, then calculation result will be applied to the scene, even if tip/target pairs are not within tolerance
options.debug: if bit0 is set, then a visual representation of the IK groups will be made
options.callback: a callback function that allows to inspect and manipulate the Jacobian. It also allows to directly perform joint valiation calculations while skipping internal computations:
outData=callbackFunction(inData)
inData.jacobian: a Matrix object representing the Jacobian
inData.e: a Vector object representing the error vector
inData.rows: a table describing the jacobian rows
inData.cols: a table describing the jacobian cols
outData.jacobian: an optional Matrix object representing the Jacobian to use in subsequent calculations. If not provided, then the original inData.jacobian is used
outData.e: an optional Vector object representing the error vector to use in subsequent calculations. If not provided, then the original inData.e is used
outData.dq: an optional Vector object representing the joint variation to apply. If provided, then internal Jacobian calculations (i.e. Jacobian pseudo-inverse) will be skipped)
outData.jacobianPinv: an optional Matrix object representing the jacobian pseudo-inverse. If provided (and dq is not provided), then internal Jacobian calculations will be skipped and following executed instead: dq=outData.jacobianPinv*e)
Lua return values
result: simIK.result_success, if successful
reason: bit-coded flags: simIK.calc_notperformed, simIK.calc_cannotinvert, simIK.calc_notwithintolerance, simIK.calc_stepstoobig, simIK.calc_limithit
precision: 2 values indicating the largest linear and angular distance between all tip-target pairs
Python synopsis int result,int flags,list precision=simIK.handleGroups(int environmentHandle,int[] ikGroupHandles,map options=None)
See also simIK.handleGroup,simIK.createEnvironment, simIK.computeJacobian, simIK.findConfigs

simIK.load

Description Loads kinematic content previously exported in the CoppeliaSim application. Make sure that the environment is empty before calling this function.
Lua synopsis simIK.load(int environmentHandle,buffer data)
Lua arguments
environmentHandle: the handle of the environment.
data: a buffer with the kinematic content.
Lua return values
Python synopsis simIK.load(int environmentHandle,bytes data)
See also simIK.save, simIK.createEnvironment, simIK.eraseEnvironment

simIK.save

Description Saves the kinematic content of an IK environment.
Lua synopsis buffer data=simIK.save(int environmentHandle)
Lua arguments
environmentHandle: the handle of the environment.
Lua return values
data: the exported data.
Python synopsis bytes data=simIK.save(int environmentHandle)
See also simIK.load

simIK.setElementBase

Description Sets the base object of an IK element.
Lua synopsis simIK.setElementBase(int environmentHandle,int ikGroupHandle,int elementHandle,int baseHandle,int constraintsBaseHandle=-1)
Lua arguments
environmentHandle: the handle of the environment.
ikGroupHandle: the handle of the IK group.
elementHandle: the IK element handle, or X, where X=handleOfTipDummy+simIK.handleflag_tipdummy (if several IK elements with the same tip dummy exist, then the first encountered will be selected).
baseHandle: the handle of the base object, or -1 if the world is the base.
constraintsBaseHandle: the handle of the constraints base object, relative to which the constraints are specified. Set to -1 to have the constraints relative to the base object.
Lua return values
Python synopsis simIK.setElementBase(int environmentHandle,int ikGroupHandle,int elementHandle,int baseHandle,int constraintsBaseHandle=-1)
See also simIK.createEnvironment, simIK.getElementBase, simIK.getGroupHandle, simIK.getObjectHandle

simIK.setElementConstraints

Description Sets the constraints of an IK element.
Lua synopsis simIK.setElementConstraints(int environmentHandle,int ikGroupHandle,int elementHandle,int constraints)
Lua arguments
environmentHandle: the handle of the environment.
ikGroupHandle: the handle of the IK group.
elementHandle: the IK element handle, or X, where X=handleOfTipDummy+simIK.handleflag_tipdummy (if several IK elements with the same tip dummy exist, then the first encountered will be selected).
constraints: the constraints. Bit-combine following: simIK.constraint_x, simIK.constraint_y, simIK.constraint_z, simIK.constraint_alpha_beta, simIK.constraint_gamma (simIK.constraint_gamma should only be set if simIK.constraint_alpha_beta is also set). For convenience we also have simIK.constraint_position=simIK.constraint_x|simIK.constraint_y|simIK.constraint_z, simIK.constraint_orientation=simIK.constraint_alpha_beta|simIK.constraint_gamma, and simIK.constraint_pose=simIK.constraint_position|simIK.constraint_orientation.
Lua return values
Python synopsis simIK.setElementConstraints(int environmentHandle,int ikGroupHandle,int elementHandle,int constraints)
See also simIK.createEnvironment, simIK.getElementConstraints, simIK.getGroupHandle, simIK.getObjectHandle

simIK.setElementFlags

Description Sets various flags of an IK element.
Lua synopsis simIK.setElementFlags(int environmentHandle,int ikGroupHandle,int elementHandle,int flags)
Lua arguments
environmentHandle: the handle of the environment.
ikGroupHandle: the handle of the IK group.
elementHandle: the IK element handle, or X, where X=handleOfTipDummy+simIK.handleflag_tipdummy (if several IK elements with the same tip dummy exist, then the first encountered will be selected).
flags: bit-coded flags: bit0 set (1)=the enabled state of the IK element.
Lua return values
Python synopsis simIK.setElementFlags(int environmentHandle,int ikGroupHandle,int elementHandle,int flags)
See also simIK.createEnvironment, simIK.getElementFlags, simIK.getGroupHandle, simIK.getObjectHandle

simIK.setElementPrecision

Description Sets the desired precision of an IK element.
Lua synopsis simIK.setElementPrecision(int environmentHandle,int ikGroupHandle,int elementHandle,float[2] precision)
Lua arguments
environmentHandle: the handle of the environment.
ikGroupHandle: the handle of the IK group.
elementHandle: the IK element handle, or X, where X=handleOfTipDummy+simIK.handleflag_tipdummy (if several IK elements with the same tip dummy exist, then the first encountered will be selected).
precision: a table with two values for the linear and angular precision.
Lua return values
Python synopsis simIK.setElementPrecision(int environmentHandle,int ikGroupHandle,int elementHandle,list precision)
See also simIK.createEnvironment, simIK.getElementPrecision, simIK.getGroupHandle, simIK.getObjectHandle

simIK.setElementWeights

Description Sets the desired linear and angular resolution weights of an IK element.
Lua synopsis simIK.setElementWeights(int environmentHandle,int ikGroupHandle,int elementHandle,float[3] weights)
Lua arguments
environmentHandle: the handle of the environment.
ikGroupHandle: the handle of the IK group.
elementHandle: the IK element handle, or X, where X=handleOfTipDummy+simIK.handleflag_tipdummy (if several IK elements with the same tip dummy exist, then the first encountered will be selected).
weights: a table with three values for the linear, angular and overall resolution weight.
Lua return values
Python synopsis simIK.setElementWeights(int environmentHandle,int ikGroupHandle,int elementHandle,list weights)
See also simIK.createEnvironment, simIK.getElementWeights, simIK.getGroupHandle, simIK.getObjectHandle

simIK.setGroupCalculation

Description Sets calculation properties for an IK group.
Lua synopsis simIK.setGroupCalculation(int environmentHandle,int ikGroupHandle,int method,float damping,float maxIterations)
Lua arguments
environmentHandle: the handle of the environment.
ikGroupHandle: the handle of the IK group.
method: the resolution method. Possible values are simIK.method_pseudo_inverse (features a tiny bit of hard-coded damping), simIK.method_undamped_pseudo_inverse, simIK.method_damped_least_squares and simIK.method_jacobian_transpose.
damping: the damping, in case the resolution method is simIK.method_damped_least_squares.
maxIterations: the maximum number of iterations.
Lua return values
Python synopsis simIK.setGroupCalculation(int environmentHandle,int ikGroupHandle,int method,float damping,float maxIterations)
See also simIK.createEnvironment, simIK.getGroupCalculation, simIK.getGroupHandle

simIK.setGroupFlags

Description Sets flags of an IK group.
Lua synopsis simIK.setGroupFlags(int environmentHandle,int ikGroupHandle,int flags)
Lua arguments
environmentHandle: the handle of the environment.
ikGroupHandle: the handle of the IK group.
flags: the flags of the IK group, bit-coded:
simIK.group_enabled: the group's enabled state
simIK.group_ignoremaxsteps: the joints' max step sizes are ignored. Otherwise, when detected, an interpolation factor (originally at 1.0) is successively divided by 2.0 until the max. step sizes are respected
simIK.group_restoreonbadlintol: the IK world state is left untouched if the linear precision is not reached
simIK.group_restoreonbadangtol: the IK world state is left untouched if the angular precision is not reached
simIK.group_avoidlimits: joint limits are actively avoided
simIK.group_stoponlimithit: calculation ends when a joint limit is hit
Lua return values
Python synopsis simIK.setGroupFlags(int environmentHandle,int ikGroupHandle,int flags)
See also simIK.createEnvironment, simIK.getGroupFlags, simIK.getGroupHandle

simIK.setJointDependency

Description Sets information about a possible dependent joint.
Lua synopsis simIK.setJointDependency(int environmentHandle,int jointHandle,int depJointHandle,float offset=0,float mult=1,func callback=nil)
Lua arguments
environmentHandle: the handle of the environment.
jointHandle: the handle of the joint.
depJointHandle: the handle of the joint, this joint is dependent of. -1 to disable.
offset: the offset. We have linear/angular joint position = dependency linear/angular joint position * mult + offset
mult: the multiplication factor. We have linear/angular joint position = dependency linear/angular joint position * mult + offset
callback: an optional callback that allows to provide a custom dependency function:
float result=callbackFunction(int ikEnv,int slaveJointHandle,float masterJointPosition)
Lua return values
Python synopsis simIK.setJointDependency(int environmentHandle,int jointHandle,int depJointHandle,float offset=0,float mult=1,string callback=None)
See also simIK.createEnvironment, simIK.getJointDependency, simIK.getObjectHandle

simIK.setJointWeight

Description Sets the IK weight of a joint, i.e. the weight it has during IK resolution.
Lua synopsis simIK.setJointWeight(int environmentHandle,int jointHandle,float weight)
Lua arguments
environmentHandle: the handle of the environment.
jointHandle: the handle of the joint.
weight: the IK weight.
Lua return values
Python synopsis simIK.setJointWeight(int environmentHandle,int jointHandle,float weight)
See also simIK.createEnvironment, simIK.getJointWeight, simIK.getObjectHandle

simIK.setJointLimitMargin

Description Sets the limit margin of a joint, i.e. the threshold that will be used to counteract on joint limit violation during IK resolution, if the appropriate IK group flag was set
Lua synopsis simIK.setJointLimitMargin(int environmentHandle,int jointHandle,float margin)
Lua arguments
environmentHandle: the handle of the environment.
jointHandle: the handle of the joint.
margin: the margin
Lua return values
Python synopsis simIK.setJointLimitMargin(int environmentHandle,int jointHandle,float margin)
See also simIK.createEnvironment, simIK.getJointLimitMargin, simIK.getGroupFlags

simIK.setJointInterval

Description Sets the joint limits.
Lua synopsis simIK.setJointInterval(int environmentHandle,int jointHandle,bool cyclic,float[2] interval={})
Lua arguments
environmentHandle: the handle of the environment.
jointHandle: the handle of the joint.
cyclic: whether the joint is cyclic (has no limits). Only revolute joints can be cyclic.
interval: a table with two values: the joint lower limit, and the joint range (i.e. joint upper limit = joint lower limit + joint range)
Lua return values
Python synopsis simIK.setJointInterval(int environmentHandle,int jointHandle,bool cyclic,list interval=[])
See also simIK.createEnvironment, simIK.getJointInterval, simIK.getObjectHandle

simIK.setJointMaxStepSize

Description Sets the maximum step size of a joint.
Lua synopsis simIK.setJointMaxStepSize(int environmentHandle,int jointHandle,float stepSize)
Lua arguments
environmentHandle: the handle of the environment.
jointHandle: the handle of the joint.
stepSize: the maximum step size.
Lua return values
Python synopsis simIK.setJointMaxStepSize(int environmentHandle,int jointHandle,float stepSize)
See also simIK.createEnvironment, simIK.getJointMaxStepSize, simIK.getObjectHandle

simIK.setJointMode

Description Sets the joint mode.
Lua synopsis simIK.setJointMode(int environmentHandle,int jointHandle,int jointMode)
Lua arguments
environmentHandle: the handle of the environment.
jointHandle: the handle of the joint.
jointMode: the joint mode. Allowed values are: simIK.jointmode_passive, simIK.jointmode_ik
Lua return values
Python synopsis simIK.setJointMode(int environmentHandle,int jointHandle,int jointMode)
See also simIK.createEnvironment, simIK.getJointMode, simIK.getObjectHandle

simIK.setJointPosition

Description Sets the position (linear or angular) of a joint.
Lua synopsis simIK.setJointPosition(int environmentHandle,int jointHandle,float position)
Lua arguments
environmentHandle: the handle of the environment.
jointHandle: the handle of the joint.
position: the position.
Lua return values
Python synopsis simIK.setJointPosition(int environmentHandle,int jointHandle,float position)
See also simIK.createEnvironment, simIK.getJointPosition, simIK.setSphericalJointMatrix, simIK.setSphericalJointRotation, simIK.getObjectHandle

simIK.setJointScrewLead

Description Sets the screw lead, in case of a revolute joint.
Lua synopsis simIK.setJointScrewLead(int environmentHandle,int jointHandle,float lead)
Lua arguments
environmentHandle: the handle of the environment.
jointHandle: the handle of the joint.
lead: the screw lead of the joint. A lead value of zero represents a revolute joint, a value different from zero represents a screw.
Lua return values
Python synopsis simIK.setJointScrewLead(int environmentHandle,int jointHandle,float lead)
See also simIK.createEnvironment, simIK.getJointScrewLead, simIK.getObjectHandle

simIK.setLinkedDummy

Description Deprecated. Use simIK.setTargetDummy instead
Lua synopsis simIK.setLinkedDummy(int environmentHandle,int dummyHandle,int linkedDummyHandle)
Lua arguments
environmentHandle: the handle of the environment.
dummyHandle: the handle of the dummy object.
linkedDummyHandle: the handle of the dummy object to be linked, or -1 to detach this dummy object from a linked dummy object.
Lua return values
Python synopsis simIK.setLinkedDummy(int environmentHandle,int dummyHandle,int linkedDummyHandle)
See also simIK.createEnvironment, simIK.getLinkedDummy, simIK.getObjectHandle

simIK.setObjectMatrix

Description Sets the transformation matrix of an object. If the object is a joint object, the matrix does not include the joint's intrinsic transformation.
Lua synopsis simIK.setObjectMatrix(int environmentHandle,int objectHandle,float[12] matrix,int relativeToObjectHandle=simIK.handle_world)
Lua arguments
environmentHandle: the handle of the environment.
objectHandle: the handle of the object.
matrix: a table of 12 values representing the transformation matrix (the last row of the 4x4 matrix (0,0,0,1) is omitted)
relativeToObjectHandle: the handle of an object relative to which the matrix is expressed. Otherwise, specify simIK.handle_world if you specify the absolute matrix, or simIK.handle_parent if you specify the matrix relative to the parent object.
Lua return values
Python synopsis simIK.setObjectMatrix(int environmentHandle,int objectHandle,list matrix,int relativeToObjectHandle=simIK.handle_world)
See also simIK.createEnvironment, simIK.getObjectMatrix, simIK.setObjectPose, simIK.setObjectTransformation, simIK.setJointPosition, simIK.getObjectHandle

simIK.setObjectParent

Description Sets the parent of an object.
Lua synopsis simIK.setObjectParent(int environmentHandle,int objectHandle,int parentObjectHandle, bool keepInPlace=true)
Lua arguments
environmentHandle: the handle of the environment.
objectHandle: the handle of the object.
parentObjectHandle: the desired parent object, set -1 for no parent.
keepInPlace: if true, the object will stay in place, otherwise, it will keep its local transformation.
Lua return values
Python synopsis simIK.setObjectParent(int environmentHandle,int objectHandle,int parentObjectHandle, bool keepInPlace=True)
See also simIK.createEnvironment, simIK.getObjectParent, simIK.getObjectHandle

simIK.setObjectPose

Description Sets the pose (position and quaternion) of an object. If the object is a joint object, the pose does not include the joint's intrinsic transformation.
Lua synopsis simIK.setObjectPose(int environmentHandle,int objectHandle,float[7] pose,int relativeToObjectHandle=simIK.handle_world)
Lua arguments
environmentHandle: the handle of the environment.
objectHandle: the handle of the object.
pose: the position and quaternion (x,y,z,qx,qy,qz,qw).
relativeToObjectHandle: the handle of an object relative to which the pose is expressed. Otherwise, specify simIK.handle_world if you specify the absolute pose, or simIK.handle_parent if you specify the pose relative to the parent object.
Lua return values
Python synopsis simIK.setObjectPose(int environmentHandle,int objectHandle,list pose,int relativeToObjectHandle=simIK.handle_world)
See also simIK.createEnvironment, simIK.getObjectPose, simIK.setObjectTransformation, simIK.setObjectMatrix, simIK.setJointPosition, simIK.getObjectHandle

simIK.setObjectTransformation

Description Sets the transformation (position and quaternion/Euler angles) of an object. If the object is a joint object, the transformation does not include the joint's intrinsic transformation.
Lua synopsis simIK.setObjectTransformation(int environmentHandle,int objectHandle,float[3] position,float[] eulerOrQuaternion,int relativeToObjectHandle=simIK.handle_world)
Lua arguments
environmentHandle: the handle of the environment.
objectHandle: the handle of the object.
position: the position component of the transformation.
eulerOrQuaternion: the orientation component of the transformation. If 3 values are specified, then they will be interpreted as Euler angles (alpha,beta,gamma). If 4 values are specified, they will be interpreted as quaternion values (x,y,z,w).
relativeToObjectHandle: the handle of an object relative to which the transformation is expressed. Otherwise, specify simIK.handle_world if you specify the absolute transformation, or simIK.handle_parent if you specify the transformation relative to the parent object.
Lua return values
Python synopsis simIK.setObjectTransformation(int environmentHandle,int objectHandle,list position,list eulerOrQuaternion,int relativeToObjectHandle=simIK.handle_world)
See also simIK.createEnvironment, simIK.getObjectTransformation, simIK.setObjectPose, simIK.setObjectMatrix, simIK.setJointPosition, simIK.getObjectHandle

simIK.setSphericalJointMatrix

Description Sets the rotation transformation matrix of a spherical joint.
Lua synopsis simIK.setSphericalJointMatrix(int environmentHandle,int jointHandle,float[12] matrix)
Lua arguments
environmentHandle: the handle of the environment.
jointHandle: the handle of the joint.
matrix: a table of 12 values representing the transformation matrix (the last row of the 4x4 matrix (0,0,0,1) is omitted). The translation part in the matrix will be ignored.
Lua return values
Python synopsis simIK.setSphericalJointMatrix(int environmentHandle,int jointHandle,list matrix)
See also simIK.createEnvironment, simIK.getJointMatrix, simIK.setJointPosition, simIK.setSphericalJointRotation, simIK.getObjectHandle

simIK.setSphericalJointRotation

Description Sets the rotation transformation of a spherical joint.
Lua synopsis simIK.setSphericalJointRotation(int environmentHandle,int jointHandle,float[] eulerOrQuaternion)
Lua arguments
environmentHandle: the handle of the environment.
jointHandle: the handle of the joint.
eulerOrQuaternion: the rotation transformation to apply. If 3 values are specified, they will be interpreted as Euler angles (alpha,beta,gamma). If 4 values are specified, they will be interpreted as quaternion values (x,y,z,w).
Lua return values
Python synopsis simIK.setSphericalJointRotation(int environmentHandle,int jointHandle,list eulerOrQuaternion)
See also simIK.createEnvironment, simIK.getJointTransformation, simIK.setSphericalJointMatrix, simIK.setJointPosition, simIK.getObjectHandle

simIK.setTargetDummy

Description Associates a tip dummy with a target dummy, or removes that association. If the tip dummy is already associated with another target dummy, then first remove that association before setting another one
Lua synopsis simIK.setTargetDummy(int environmentHandle,int tipDummyHandle,int targetDummyHandle)
Lua arguments
environmentHandle: the handle of the environment
tipDummyHandle: the handle of the tip dummy
targetdDummyHandle: the handle of the new target dummy, or -1 to remove a previous target dummy association from the tip dummy
Lua return values
Python synopsis simIK.setTargetDummy(int environmentHandle,int tipDummyHandle,int targetDummyHandle)
See also simIK.createEnvironment, simIK.getTargetDummy, simIK.getObjectHandle

simIK.syncToSim

Description Convenience function to apply inverse kinematic values computed in the IK world, to the scene. Use together with simIK.addElementFromScene.
Lua synopsis simIK.syncToSim(int environmentHandle,int[] ikGroups)
Lua arguments
environmentHandle: the handle of the IK environment
ikGroups: the handles of one or several IK groups
Lua return values
Python synopsis simIK.syncToSim(int environmentHandle,int[] ikGroups)
See also simIK.addElementFromScene,simIK.syncFromSim

simIK.syncFromSim

Description Convenience function to apply the scene state to its ik environment counterpart. Use together with simIK.addElementFromScene.
Lua synopsis simIK.syncFromSim(int environmentHandle,int[] ikGroups)
Lua arguments
environmentHandle: the handle of the IK environment
ikGroups: the handle of one or several IK groups
Lua return values
Python synopsis simIK.syncFromSim(int environmentHandle,int[] ikGroups)
See also simIK.addElementFromScene,simIK.syncToSim