IK plugin API reference

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

simIK.addIkElement
simIK.addIkElementFromScene
simIK.applyIkEnvironmentToScene
simIK.applySceneToIkEnvironment
simIK.computeJacobian
simIK.createEnvironment
simIK.createDummy
simIK.createIkGroup
simIK.createJoint
simIK.doesObjectExist
simIK.doesIkGroupExist
simIK.duplicateEnvironment
simIK.eraseEnvironment
simIK.eraseObject
simIK.generatePath
simIK.getAlternateConfigs
simIK.getConfigForTipPose
simIK.getIkElementBase
simIK.getIkElementConstraints
simIK.getIkElementFlags
simIK.getIkElementPrecision
simIK.getIkElementWeights
simIK.getIkGroupCalculation
simIK.getIkGroupFlags
simIK.getIkGroupHandle
simIK.getJacobian
simIK.getJointDependency
simIK.getJointIkWeight
simIK.getJointInterval
simIK.getJointMatrix
simIK.getJointMaxStepSize
simIK.getJointMode
simIK.getJointPosition
simIK.getJointScrewPitch
simIK.getJointTransformation
simIK.getJointType
simIK.getLinkedDummy
simIK.getManipulability
simIK.getObjectHandle
simIK.getObjectMatrix
simIK.getObjectParent
simIK.getObjects
simIK.getObjectTransformation
simIK.handleIkGroup
simIK.load
simIK.save
simIK.setIkElementBase
simIK.setIkElementConstraints
simIK.setIkElementFlags
simIK.setIkElementPrecision
simIK.setIkElementWeights
simIK.setIkGroupCalculation
simIK.setIkGroupFlags
simIK.setJointDependency
simIK.setJointIkWeight
simIK.setJointInterval
simIK.setJointMaxStepSize
simIK.setJointMode
simIK.setJointPosition
simIK.setJointScrewPitch
simIK.setLinkedDummy
simIK.setObjectMatrix
simIK.setObjectParent
simIK.setObjectTransformation
simIK.setSphericalJointMatrix
simIK.setSphericalJointRotation

Environment functions and helpers

simIK.createEnvironment
simIK.eraseEnvironment
simIK.duplicateEnvironment
simIK.save
simIK.load
simIK.addIkElementFromScene
simIK.applyIkEnvironmentToScene
simIK.applySceneToIkEnvironment

Objects

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

Dummies

simIK.createDummy
simIK.eraseObject
simIK.getLinkedDummy
simIK.setLinkedDummy

Joints

simIK.createJoint
simIK.eraseObject
simIK.getJointPosition
simIK.setJointPosition
simIK.getJointMode
simIK.setJointMode
simIK.getJointInterval
simIK.setJointInterval
simIK.getJointDependency
simIK.setJointDependency
simIK.getJointIkWeight
simIK.setJointIkWeight
simIK.getJointMaxStepSize
simIK.setJointMaxStepSize
simIK.getJointScrewPitch
simIK.setJointScrewPitch
simIK.getJointTransformation
simIK.setSphericalJointRotation
simIK.getJointType
simIK.getJointMatrix
simIK.setSphericalJointMatrix

IK groups

simIK.createIkGroup
simIK.getIkGroupHandle
simIK.doesIkGroupExist
simIK.getIkGroupFlags
simIK.setIkGroupFlags
simIK.getIkGroupCalculation
simIK.setIkGroupCalculation

IK elements

simIK.addIkElement
simIK.addIkElementFromScene
simIK.getIkElementFlags
simIK.setIkElementFlags
simIK.getIkElementConstraints
simIK.setIkElementConstraints
simIK.getIkElementBase
simIK.setIkElementBase
simIK.getIkElementPrecision
simIK.setIkElementPrecision
simIK.getIkElementWeights
simIK.setIkElementWeights

IK calculation

simIK.handleIkGroup
simIK.applyIkEnvironmentToScene
simIK.getConfigForTipPose
simIK.getAlternateConfigs
simIK.computeJacobian
simIK.getJacobian
simIK.getManipulability
simIK.generatePath

simIK.addIkElement

Description Adds a new IK element to an IK group.
Synopsis number elementHandle=simIK.addIkElement(number environmentHandle,number ikGroupHandle,number tipDummyHandle)
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.
Return values
elementHandle: the IK element handle in the IK group
See also simIK.createEnvironment, simIK.getIkGroupHandle, simIK.getObjectHandle, simIK.addIkElementFromScene

simIK.addIkElementFromScene

Description Convenience function to quickly generate an IK element from a kinematic chain in the scene. Use together with simIK.applyIkEnvironmentToScene.
Synopsis number ikElement,table simToIkObjectMap=simIK.addIkElementFromScene(number environmentHandle,number ikGroup,number baseHandle,number tipHandle,number targetHandle,number constraints)
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.
Return values
ikElement: the handle of the created IK element.
simToIkObjectMap: the mapping of scene object to IK environment objects.
See also simIK.applyIkEnvironmentToScene, simIK.addIkElement

simIK.applyIkEnvironmentToScene

Description Convenience function to compute and apply inverse kinematic values to the scene. Use together with simIK.addIkElementFromScene.
Synopsis number result=simIK.applyIkEnvironmentToScene(number environmentHandle,number ikGroup,bool applyOnlyWhenSuccessful=false)
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.ikresult_success.
Return values
result: the resolution result, in return. Possible values are simIK.ikresult_not_performed, simIK.ikresult_success, or simIK.ikresult_fail
See also simIK.addIkElementFromScene,simIK.applySceneToIkEnvironment

simIK.applySceneToIkEnvironment

Description Convenience function to apply the scene state to its ik environment counterpart. Use together with simIK.addIkElementFromScene.
Synopsis simIK.applySceneToIkEnvironment(number environmentHandle,number ikGroup)
Arguments
environmentHandle: the handle of the IK environment.
ikGroup: the handle of the IK group.
Return values
See also simIK.addIkElementFromScene,simIK.applyIkEnvironmentToScene

simIK.computeJacobian

Description Computes the Jacobian for an IK group.
Synopsis bool success=simIK.computeJacobian(number environmentHandle,number ikGroupHandle,number options)
Arguments
environmentHandle: the handle of the environment.
ikGroupHandle: the handle of the IK group.
options: options flag, bit-coded. bit0 set (i.e. 1): takes joint weights into account.
Return values
success: whether the Jacobian could successfully be computed.
See also simIK.createEnvironment, simIK.getJacobian, simIK.getManipulability

simIK.createDummy

Description Creates a dummy object.
Synopsis number dummyHandle=simIK.createDummy(number environmentHandle,string dummyName='')
Arguments
environmentHandle: the handle of the environment.
dummyName: the name of the dummy.
Return values
dummyHandle: the handle of the dummy.
See also simIK.createEnvironment, simIK.doesObjectExist, simIK.createJoint, simIK.eraseObject

simIK.createEnvironment

Description Creates an new IK environment.
Synopsis number environmentHandle=simIK.createEnvironment()
Arguments
Return values
environmentHandle: the handle of the newly created environment.
See also simIK.eraseEnvironment, simIK.load

simIK.createIkGroup

Description Creates an IK group.
Synopsis number ikGroupHandle=simIK.createIkGroup(number environmentHandle,string ikGroupName='')
Arguments
environmentHandle: the handle of the environment.
ikGroupName: the name of the IK group.
Return values
ikGroupHandle: the handle of the IK group.
See also simIK.createEnvironment, simIK.doesIkGroupExist

simIK.createJoint

Description Creates a joint object.
Synopsis number jointHandle=simIK.createJoint(number environmentHandle,string jointName='')
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.
Return values
jointHandle: the handle of the joint.
See also simIK.createEnvironment, simIK.doesObjectExist, simIK.createDummy, simIK.eraseObject

simIK.doesObjectExist

Description Checks whether an object exists, based on its name.
Synopsis bool result=simIK.doesObjectExist(number environmentHandle,string objectName)
Arguments
environmentHandle: the handle of the environment.
objectName: the name of the object.
Return values
result: true if the object exists.
See also simIK.createEnvironment, simIK.getObjectHandle

simIK.doesIkGroupExist

Description Checks whether an IK group exists, based on its name.
Synopsis bool result=simIK.doesIkGroupExist(number environmentHandle,string ikGroupName)
Arguments
environmentHandle: the handle of the environment.
ikGroupName: the name of the IK group.
Return values
result: true if the IK group exists.
See also simIK.createEnvironment, simIK.getIkGroupHandle

simIK.duplicateEnvironment

Description Duplicates an IK environment. Useful when operating on an environment while leaving the original environment unchanged.
Synopsis number newEnvironmentHandle=simIK.duplicateEnvironment(number environmentHandle)
Arguments
environmentHandle: the handle of the environment.
Return values
newEnvironmentHandle: the handle of the duplicated environment.
See also simIK.eraseEnvironment, simIK.createEnvironment

simIK.eraseEnvironment

Description Erases an IK environment.
Synopsis simIK.eraseEnvironment(number environmentHandle)
Arguments
environmentHandle: the handle of the environment.
Return values
See also simIK.createEnvironment

simIK.eraseObject

Description Erases an object.
Synopsis simIK.eraseObject(number environmentHandle,number objectHandle)
Arguments
environmentHandle: the handle of the environment.
objectHandle: handle of the object.
Return values
See also simIK.createEnvironment, simIK.getObjectHandle, simIK.createDummy, simIK.createJoint

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.
Synopsis table configurationList=simIK.generatePath(number environmentHandle,table ikGroupHandle,table jointHandles,number tipHandle,number pathPointCount,function validationCallback=nil,auxData=nil
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. 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.
Return values
configurationList: a table that contains configurations (in row-major order) that will bring the IK tip onto its IK target.
See also simIK.duplicateEnvironment

simIK.getAlternateConfigs

Description Useful when called after simIK.getConfigForTipPose: 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.
Synopsis table configurations=simIK.getAlternateConfigs(number environmentHandle,table jointHandles,table lowLimits=nil,table ranges=nil)
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 joint position, with an extent of (-range).
Return values
configurations: a table containing configurations (in row-major order) that are equivalent to the specified inputConfig, in terms of end-effector pose.
See also simIK.createEnvironment, simIK.getConfigForTipPose

simIK.getConfigForTipPose

Description Searches for a manipulator configuration that matches the target dummy position/orientation in space. Search is randomized. One should call simIK.getAlternateConfigs for each returned configuration, if some revolute joints of the manipulator have a range of more than 360 degrees, in order to generate some equivalent poses but alternate configurations. The IK environment remains unchanged.
Synopsis table jointPositions=simIK.getConfigForTipPose(number environmentHandle,number ikGroupHandle,table jointHandles,number thresholdDist=0.1,number maxTime=0.5,table_4 metric={1,1,1,0.1},function validationCallback=nil,auxData=nil,table jointOptions={},table lowLimits={},table ranges={})
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 joint position, with an extent of (-range).
Return values
jointPositions: a table that contains the IK calculated joint values, as specified by the jointHandles table, if a valid configuration was found.
See also simIK.createEnvironment, simIK.duplicateEnvironment, simIK.getAlternateConfigs, simIK.computeJacobian, simIK.getJacobian

simIK.getIkElementBase

Description Retrieves the base object of an IK element.
Synopsis number baseHandle,number constraintsBaseHandle=simIK.getIkElementBase(number environmentHandle,number ikGroupHandle,number elementHandle)
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).
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.
See also simIK.createEnvironment, simIK.setIkElementBase, simIK.getIkGroupHandle, simIK.getObjectHandle

simIK.getIkElementConstraints

Description Retrieves the constraints of an IK element.
Synopsis number constraints=simIK.getIkElementConstraints(number environmentHandle,number ikGroupHandle,number elementHandle)
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).
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.
See also simIK.createEnvironment, simIK.setIkElementConstraints, simIK.getIkGroupHandle, simIK.getObjectHandle

simIK.getIkElementFlags

Description Retrieves various flags of an IK element.
Synopsis number flags=simIK.getIkElementFlags(number environmentHandle,number ikGroupHandle,number elementHandle)
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).
Return values
flags: bit-coded flags: bit0 set(1)=the enabled state of the ik element.
See also simIK.createEnvironment, simIK.setIkElementFlags, simIK.getIkGroupHandle, simIK.getObjectHandle

simIK.getIkElementPrecision

Description Retrieves the precision settings of an IK element.
Synopsis table_2 precision=simIK.getIkElementPrecision(number environmentHandle,number ikGroupHandle,number elementHandle)
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).
Return values
precision: a table with the linear and angular precision.
See also simIK.createEnvironment, simIK.setIkElementPrecision, simIK.getIkGroupHandle, simIK.getObjectHandle

simIK.getIkElementWeights

Description Retrieves the desired linear and angular resolution weights of an IK element.
Synopsis table_2 weights=simIK.getIkElementWeights(number environmentHandle,number ikGroupHandle,number elementHandle)
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).
Return values
weights: a table with the linear and angular resolution weights.
See also simIK.createEnvironment, simIK.setIkElementWeights, simIK.getIkGroupHandle, simIK.getObjectHandle

simIK.getIkGroupCalculation

Description Retrieves calculation properties for an IK group.
Synopsis number method,number damping,number maxIterations=simIK.getIkGroupCalculation(number environmentHandle,number ikGroupHandle)
Arguments
environmentHandle: the handle of the environment.
ikGroupHandle: the handle of the IK group.
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.
See also simIK.createEnvironment, simIK.setIkGroupCalculation, simIK.getIkGroupHandle

simIK.getIkGroupFlags

Description Retrieves flags of an IK group.
Synopsis number flags=simIK.getIkGroupFlags(number environmentHandle,number ikGroupHandle))
Arguments
environmentHandle: the handle of the environment.
ikGroupHandle: the handle of the IK group.
Return values
flags: the flags of the IK group. bit0 set (i.e. 1)=group is enabled, bit1 set (i.e. 2)=max. step sizes are ignored, bit2 set (i.e. 4)=restore joints if target position not reached, bit3 set (i.e. 8)=restore joints if target orientation not reached.
See also simIK.createEnvironment, simIK.setIkGroupFlags, simIK.getIkGroupHandle

simIK.getIkGroupHandle

Description Retrieves the handle of an IK group based on its name.
Synopsis number ikGroupHandle=simIK.getIkGroupHandle(number environmentHandle,string ikGroupName)
Arguments
environmentHandle: the handle of the environment.
ikGroupName: the name of the IK group.
Return values
ikGroupHandle: the handle of the IK group.
See also simIK.createEnvironment, simIK.doesIkGroupExist, simIK.createIkGroup

simIK.getJacobian

Description Retrieves the Jacobian previously computed via simIK.computeJacobian.
Synopsis table jacobian,table_2 matrixSize=simIK.getJacobian(number environmentHandle,number ikGroupHandle)
Arguments
environmentHandle: the handle of the environment.
ikGroupHandle: the handle of the IK group.
Return values
jacobian: a table with the jacobian values.
matrixSize: a table containing the sizes (row count (i.e. number of DoFs) and column count) of the Jacobian matrix.
See also simIK.createEnvironment, simIK.computeJacobian, simIK.getManipulability

simIK.getJointDependency

Description Retrieves information about a possible joint dependency.
Synopsis number depJointHandle,number offset,number mult=simIK.getJointDependency(number environmentHandle,number jointHandle)
Arguments
environmentHandle: the handle of the environment.
jointHandle: the handle of the joint.
Return values
depJointHandle: the handle of the dependency joint.
offset: the offset. We have joint position = dependency joint position * mult + offset.
mult: the multiplication factor. We have joint position = dependency joint position * mult + offset.
See also simIK.createEnvironment, simIK.setJointDependency, simIK.getObjectHandle

simIK.getJointIkWeight

Description Retrieves the IK weight of a joint, i.e. the weight it has during IK resolution.
Synopsis number weight=simIK.getJointIkWeight(number environmentHandle,number jointHandle)
Arguments
environmentHandle: the handle of the environment.
jointHandle: the handle of the joint.
Return values
weight: the IK weight.
See also simIK.createEnvironment, simIK.setJointIkWeight, simIK.getObjectHandle

simIK.getJointInterval

Description Retrieves the joint limits.
Synopsis bool cyclic,table_2 interval=simIK.getJointInterval(number environmentHandle,number jointHandle)
Arguments
environmentHandle: the handle of the environment.
jointHandle: the handle of the joint.
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)
See also simIK.createEnvironment, simIK.setJointInterval, simIK.getObjectHandle

simIK.getJointMatrix

Description Retrieves the intrinsic transformation matrix of a joint.
Synopsis table_12 matrix=simIK.getJointMatrix(number environmentHandle,number jointHandle)
Arguments
environmentHandle: the handle of the environment.
jointHandle: the handle of the joint.
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).
See also simIK.createEnvironment, simIK.setSphericalJointMatrix, simIK.getJointPosition, simIK.getJointTransformation, simIK.getObjectHandle

simIK.getJointMaxStepSize

Description Retrieves the maximum step size of a joint.
Synopsis number stepSize=simIK.getJointMaxStepSize(number environmentHandle,number jointHandle)
Arguments
environmentHandle: the handle of the environment.
jointHandle: the handle of the joint.
Return values
stepSize: the maximum step size.
See also simIK.createEnvironment, simIK.setJointMaxStepSize, simIK.getObjectHandle

simIK.getJointMode

Description Retrieves the joint mode.
Synopsis number jointMode=simIK.getJointMode(number environmentHandle,number jointHandle)
Arguments
environmentHandle: the handle of the environment.
jointHandle: the handle of the joint.
Return values
jointMode: the joint mode. Possible values are: simIK.jointmode_passive, simIK.jointmode_ik, simIK.jointmode_dependent, simIK.jointmode_force
See also simIK.createEnvironment, simIK.setJointMode, simIK.getObjectHandle

simIK.getJointPosition

Description Retrieves the position (linear or angular) of a joint.
Synopsis number position=simIK.getJointPosition(number environmentHandle,number jointHandle)
Arguments
environmentHandle: the handle of the environment.
jointHandle: the handle of the joint.
Return values
position: the position.
See also simIK.createEnvironment, simIK.setJointPosition, simIK.getJointMatrix, simIK.getJointTransformation, simIK.getObjectHandle

simIK.getJointScrewPitch

Description Retrieves the screw pitch of a revolute joint.
Synopsis number pitch=simIK.getJointScrewPitch(number environmentHandle,number jointHandle)
Arguments
environmentHandle: the handle of the environment.
jointHandle: the handle of the joint.
Return values
pitch: the screw pitch of the joint. A pitch value of zero represents a revolute joint, a value different from zero represents a screw.
See also simIK.createEnvironment, simIK.setJointScrewPitch, simIK.getObjectHandle

simIK.getJointTransformation

Description Retrieves the intrinsic transformation of a joint.
Synopsis table_3 position,table_4 quaternion,table_3 euler=simIK.getJointTransformation(number environmentHandle,number jointHandle)
Arguments
environmentHandle: the handle of the environment.
jointHandle: the handle of the joint.
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).
See also simIK.createEnvironment, simIK.setSphericalJointRotation, simIK.getJointPosition, simIK.getJointMatrix, simIK.getObjectHandle

simIK.getJointType

Description Retrieves the joint type.
Synopsis number jointType=simIK.getJointType(number environmentHandle,number jointHandle)
Arguments
environmentHandle: the handle of the environment.
jointHandle: the handle of the joint.
Return values
jointType: the joint type. Possible values are: simIK.jointtype_revolute, simIK.jointtype_prismatic and simIK.jointtype_spherical
See also simIK.createJoint

simIK.getLinkedDummy

Description Retrieves the handle of a dummy linked to this one.
Synopsis number linkedDummyHandle=simIK.getLinkedDummy(number environmentHandle,number dummyHandle)
Arguments
environmentHandle: the handle of the environment.
dummyHandle: the handle of the dummy object.
Return values
linkedDummyHandle: the handle of the linked dummy object. Is -1 if no dummy object is linked to this one.
See also simIK.createEnvironment, simIK.setLinkedDummy, simIK.getObjectHandle

simIK.getManipulability

Description Retrieves the manipulability value ( sqrt(det(J*JT)) ) of the Jacobian previously computed via simIK.computeJacobian.
Synopsis number manipulability=simIK.getManipulability(number environmentHandle,number ikGroupHandle)
Arguments
environmentHandle: the handle of the environment.
ikGroupHandle: the handle of the IK group.
Return values
manipulability: the manipulability value.
See also simIK.createEnvironment, simIK.computeJacobian, simIK.getJacobian

simIK.getObjectHandle

Description Retrieves the handle of an object based on its name.
Synopsis number objectHandle=simIK.getObjectHandle(number environmentHandle,string objectName)
Arguments
environmentHandle: the handle of the environment.
objectName: the name of the object.
Return values
objectHandle: the object handle.
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.
Synopsis table_12 matrix=simIK.getObjectMatrix(number environmentHandle,number objectHandle,number relativeToObjectHandle)
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 -1 if you want the absolute matrix, or simIK.handle_parent if you want the matrix relative to the parent object.
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)
See also simIK.createEnvironment, simIK.setObjectMatrix, simIK.getObjectTransformation, simIK.getJointTransformation, simIK.getObjectHandle

simIK.getObjectParent

Description Retrieves an object's parent handle.
Synopsis number parentObjectHandle=simIK.getObjectParent(number environmentHandle,number objectHandle)
Arguments
environmentHandle: the handle of the environment.
objectHandle: the handle of the object.
Return values
parentObjectHandle: the returned handle of the parent, or -1 if the object has no parent.
See also simIK.createEnvironment, simIK.setObjectParent, simIK.getObjectHandle

simIK.getObjects

Description Allows to loop through all objects in the environment.
Synopsis number objectHandle,string objectName,bool isJoint,number jointType=simIK.getObjects(number environmentHandle,number index)
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.
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.
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.
Synopsis table_3 position,table_4 quaternion,table_3 euler=simIK.getObjectTransformation(number environmentHandle,number objectHandle,number relativeToObjectHandle)
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 -1 if you want the absolute transformation, or simIK.handle_parent if you want the transformation relative to the parent object.
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).
See also simIK.createEnvironment, simIK.setObjectTransformation, simIK.getObjectMatrix, simIK.getJointTransformation, simIK.getObjectHandle

simIK.handleIkGroup

Description Handles (i.e. computes/resolves) an IK group.
Synopsis number result=simIK.handleIkGroup(number environmentHandle,number ikGroupHandle)
Arguments
environmentHandle: the handle of the environment.
ikGroupHandle: the handle of the IK group, or simIK.handle_all to handle all IK groups.
Return values
result: the resolution result, in return. Possible values are simIK.ikresult_not_performed, simIK.ikresult_success, or simIK.ikresult_fail
See also simIK.createEnvironment, simIK.computeJacobian, simIK.getConfigForTipPose

simIK.load

Description Loads kinematic content previously exported in the CoppeliaSim application. Make sure that the environment is empty before calling this function.
Synopsis simIK.load(number environmentHandle,string data)
Arguments
environmentHandle: the handle of the environment.
data: a buffer with the kinematic content.
Return values
See also simIK.save, simIK.createEnvironment, simIK.eraseEnvironment

simIK.save

Description Saves the kinematic content of an IK environment.
Synopsis string data=simIK.save(number environmentHandle)
Arguments
environmentHandle: the handle of the environment.
Return values
data: the exported data.
See also simIK.load

simIK.setIkElementBase

Description Sets the base object of an IK element.
Synopsis simIK.setIkElementBase(number environmentHandle,number ikGroupHandle,number elementHandle,number baseHandle,number constraintsBaseHandle=-1)
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.
Return values
See also simIK.createEnvironment, simIK.getIkElementBase, simIK.getIkGroupHandle, simIK.getObjectHandle

simIK.setIkElementConstraints

Description Sets the constraints of an IK element.
Synopsis simIK.setIkElementConstraints(number environmentHandle,number ikGroupHandle,number elementHandle,number constraints)
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.
Return values
See also simIK.createEnvironment, simIK.getIkElementConstraints, simIK.getIkGroupHandle, simIK.getObjectHandle

simIK.setIkElementFlags

Description Sets various flags of an IK element.
Synopsis simIK.setIkElementFlags(number environmentHandle,number ikGroupHandle,number elementHandle,number flags)
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.
Return values
See also simIK.createEnvironment, simIK.getIkElementFlags, simIK.getIkGroupHandle, simIK.getObjectHandle

simIK.setIkElementPrecision

Description Sets the desired precision of an IK element.
Synopsis simIK.setIkElementPrecision(number environmentHandle,number ikGroupHandle,number elementHandle,table_2 precision)
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.
Return values
See also simIK.createEnvironment, simIK.getIkElementPrecision, simIK.getIkGroupHandle, simIK.getObjectHandle

simIK.setIkElementWeights

Description Sets the desired linear and angular resolution weights of an IK element.
Synopsis simIK.setIkElementWeights(number environmentHandle,number ikGroupHandle,number elementHandle,table_2 weights)
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 two values for the linear and angular resolution weight.
Return values
See also simIK.createEnvironment, simIK.getIkElementWeights, simIK.getIkGroupHandle, simIK.getObjectHandle

simIK.setIkGroupCalculation

Description Sets calculation properties for an IK group.
Synopsis simIK.setIkGroupCalculation(number environmentHandle,number ikGroupHandle,number method,number damping,number maxIterations)
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.
Return values
See also simIK.createEnvironment, simIK.getIkGroupCalculation, simIK.getIkGroupHandle

simIK.setIkGroupFlags

Description Sets flags of an IK group.
Synopsis simIK.setIkGroupFlags(number environmentHandle,number ikGroupHandle,number flags)
Arguments
environmentHandle: the handle of the environment.
ikGroupHandle: the handle of the IK group.
flags: the flags of the IK group. bit0 set (i.e. 1)=group is enabled, bit1 set (i.e. 2)=max. step sizes are ignored, bit2 set (i.e. 4)=restore joints if target position not reached, bit3 set (i.e. 8)=restore joints if target orientation not reached.
Return values
See also simIK.createEnvironment, simIK.getIkGroupFlags, simIK.getIkGroupHandle

simIK.setJointDependency

Description Sets information about a possible dependent joint.
Synopsis simIK.setJointDependency(number environmentHandle,number jointHandle,number depJointHandle,number offset=0,number mult=1)
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 joint position = dependency joint position * mult + offset
mult: the multiplication factor. We have joint position = dependency joint position * mult + offset
Return values
See also simIK.createEnvironment, simIK.getJointDependency, simIK.getObjectHandle

simIK.setJointIkWeight

Description Sets the IK weight of a joint, i.e. the weight it has during IK resolution.
Synopsis simIK.setJointIkWeight(number environmentHandle,number jointHandle,number weight)
Arguments
environmentHandle: the handle of the environment.
jointHandle: the handle of the joint.
weight: the IK weight.
Return values
See also simIK.createEnvironment, simIK.getJointIkWeight, simIK.getObjectHandle

simIK.setJointInterval

Description Sets the joint limits.
Synopsis simIK.setJointInterval(number environmentHandle,number jointHandle,bool cyclic,table_2 interval={})
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)
Return values
See also simIK.createEnvironment, simIK.getJointInterval, simIK.getObjectHandle

simIK.setJointMaxStepSize

Description Sets the maximum step size of a joint.
Synopsis simIK.setJointMaxStepSize(number environmentHandle,number jointHandle,number stepSize)
Arguments
environmentHandle: the handle of the environment.
jointHandle: the handle of the joint.
stepSize: the maximum step size.
Return values
See also simIK.createEnvironment, simIK.getJointMaxStepSize, simIK.getObjectHandle

simIK.setJointMode

Description Sets the joint mode.
Synopsis simIK.setJointMode(number environmentHandle,number jointHandle,number jointMode)
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, simIK.jointmode_dependent
Return values
See also simIK.createEnvironment, simIK.getJointMode, simIK.getObjectHandle

simIK.setJointPosition

Description Sets the position (linear or angular) of a joint.
Synopsis simIK.setJointPosition(number environmentHandle,number jointHandle,number position)
Arguments
environmentHandle: the handle of the environment.
jointHandle: the handle of the joint.
position: the position.
Return values
See also simIK.createEnvironment, simIK.getJointPosition, simIK.setSphericalJointMatrix, simIK.setSphericalJointRotation, simIK.getObjectHandle

simIK.setJointScrewPitch

Description Sets the screw pitch, in case of a revolute joint.
Synopsis simIK.setJointScrewPitch(number environmentHandle,number jointHandle,number pitch)
Arguments
environmentHandle: the handle of the environment.
jointHandle: the handle of the joint.
pitch: the screw pitch of the joint. A pitch value of zero represents a revolute joint, a value different from zero represents a screw.
Return values
See also simIK.createEnvironment, simIK.getJointScrewPitch, simIK.getObjectHandle

simIK.setLinkedDummy

Description Links this dummy object to another dummy object, or detaches it from another dummy object.
Synopsis simIK.setLinkedDummy(number environmentHandle,number dummyHandle,number linkedDummyHandle)
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.
Return values
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.
Synopsis simIK.setObjectMatrix(number environmentHandle,number objectHandle,number relativeToObjectHandle,table_12 matrix)
Arguments
environmentHandle: the handle of the environment.
objectHandle: the handle of the object.
relativeToObjectHandle: the handle of an object relative to which the matrix is expressed. Otherwise, specify -1 if you specify the absolute matrix, or simIK.handle_parent if you specify the matrix relative to the parent object.
matrix: a table of 12 values representing the transformation matrix (the last row of the 4x4 matrix (0,0,0,1) is omitted)
Return values
See also simIK.createEnvironment, simIK.getObjectMatrix, simIK.setObjectTransformation, simIK.setJointPosition, simIK.getObjectHandle

simIK.setObjectParent

Description Sets the parent of an object.
Synopsis simIK.setObjectParent(number environmentHandle,number objectHandle,number parentObjectHandle, bool keepInPlace=true)
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.
Return values
See also simIK.createEnvironment, simIK.getObjectParent, 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.
Synopsis simIK.setObjectTransformation(number environmentHandle,number objectHandle,number relativeToObjectHandle,table_3 position,table eulerOrQuaternion)
Arguments
environmentHandle: the handle of the environment.
objectHandle: the handle of the object.
relativeToObjectHandle: the handle of an object relative to which the transformation is expressed. Otherwise, specify -1 if you specify the absolute transformation, or simIK.handle_parent if you specify the transformation relative to the parent 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).
Return values
See also simIK.createEnvironment, simIK.getObjectTransformation, simIK.setObjectMatrix, simIK.setJointPosition, simIK.getObjectHandle

simIK.setSphericalJointMatrix

Description Sets the rotation transformation matrix of a spherical joint.
Synopsis simIK.setSphericalJointMatrix(number environmentHandle,number jointHandle,table_12 matrix)
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.
Return values
See also simIK.createEnvironment, simIK.getJointMatrix, simIK.setJointPosition, simIK.setSphericalJointRotation, simIK.getObjectHandle

simIK.setSphericalJointRotation

Description Sets the rotation transformation of a spherical joint.
Synopsis simIK.setSphericalJointRotation(number environmentHandle,number jointHandle,table eulerOrQuaternion)
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).
Return values
See also simIK.createEnvironment, simIK.getJointTransformation, simIK.setSphericalJointMatrix, simIK.setJointPosition, simIK.getObjectHandle