
This collection of functions allows to perform the same kinematic calculations as you are able to do from within V-REP. Exception to this is the obstacle avoidance functionality which is only supported from within V-REP.
The idea is to normally build your kinematic tasks inside V-REP, then to export the kinematic content of a scene, which can then directly be used with the embeddable functions below. The required source code, in scrambled form, is located in the programming/externalIk folder. Make sure to include all files into your project, and include extIk.h in the files where you need access to the functions. Make also sure you know how to use the kinematics functionality from within V-REP first!! If you have access to the regular API, then you won't need this auxiliary API, since all following functions have their regular API equivalent.
The scrambled source code located in the programming/externalIk folder, meant for evaluation purpose, is fully functional, however with the following restriction: only about the first 40000 explicit calls to simEmbHandleIkGroup will have an effect. If you call the function in a non-explicit way (i.e. simEmbHandleIkGroup(sim_handle_all)), then each ik group will represent a distinct call. The scrambled source code without this restriction requires a separate licensing, please contact us for details.
Follow the method below to perform kinematic calculations from within your own external application:
Build your kinematic tasks within V-REP. Test them.
Export the kinematic content of the scene with [Menu bar --> File --> Export IK content...]
Include the external kinematics code in your own application (the code is located in the programming/externalIk folder)
Call simEmbLaunch at application start-up, and simEmbShutDown at application end.
Call simEmbStart to import the previously exported file. simEmbStart may be called as often as desired to reset the kinematic scene. A kinematic scene is similar to a scene in V-REP, except that it is stripped of everything non-kinematic.
Call various functions to shift / rotate the target dummies (e.g. with simEmbSetObjectTransformation), or to move non-active joints, i.e. joints that are not in IK mode (e.g. with simEmbSetJointPosition).
Call simEmbHandleIkGroup to perform one calculation pass (i.e. effectively bringing dummy tips onto their targets).
Repeat above last 2 steps as often as required. Make sure to check for return values to detect errors.
Refer also to the example application programming/externalIkDemo. That demo application uses the external kinematics routines described here, combined with the remote API functionality to control the IRB 360 "delta" robot in inverse kinematics mode. The demo scene "externalIkDemo.ttt" launches the externalIkDemo automatically.
simEmbEulerAnglesToQuaternion
simEmbGetIkGroupHandle
simEmbGetJointPosition
simEmbGetJointTransformation
simEmbGetObjectHandle
simEmbGetObjectParent
simEmbGetObjectTransformation
simEmbGetRotationAxis
simEmbHandleIkGroup
simEmbInterpolateTransformations
simEmbInvertTransformation
simEmbLaunch
simEmbMultiplyTransformations
simEmbMultTransformationWithVector
simEmbQuaternionToEulerAngles
simEmbRotateAroundAxis
simEmbSetIkElementProperties
simEmbSetIkGroupExplicitHandling
simEmbSetIkGroupProperties
simEmbSetJointMode
simEmbSetJointPosition
simEmbSetObjectParent
simEmbSetObjectTransformation
simEmbSetSphericalJointQuaternion
simEmbShutDown
simEmbStart
simEmbEulerAnglesToQuaternion (regular API equivalent: simGetEulerAnglesFromMatrix)
Description
|
Retrieves a quaternion based on Euler angles. See also simEmbQuaternionToEulerAngles |
C++ synopsis
|
int simEmbEulerAnglesToQuaternion(const float* euler,float* quaternion) |
parameters |
euler (input): the 3 Euler angles (alpha, beta, gamma)
quaternion (output): the 4 values of a quaternion (x, y, z, w)
|
return value
|
-1 if operation failed
|
simEmbGetIkGroupHandle (regular API equivalent: simGetIkGroupHandle)
Description
|
Retrieves the handle of an IK group based on its name. Specify the full IK group name, including suffixes. |
C++ synopsis
|
int simEmbGetIkGroupHandle(const char* ikGroupName) |
parameters |
ikGroupName (input): the name of the IK group
|
return value
|
-1 if operation failed, otherwise the handle of the IK group.
|
simEmbGetJointPosition (regular API equivalent: simGetJointPosition)
Description
|
Retrieves the intrinsic position of a joint. This function cannot be used with spherical joints (use simEmbGetJointTransformation instead). See also simEmbSetJointPosition |
C++ synopsis
|
int simEmbGetJointPosition(int jointHandle,float* position) |
parameters |
jointHandle (input): handle of the joint
position (output): intrinsic position of the joint. This is a one-dimensional value: if the joint is revolute, the rotation angle is returned, if the joint is prismatic, the translation amount is returned, etc.
|
return value
|
-1 if operation failed
|
simEmbGetJointTransformation (regular API equivalent: simGetJointMatrix)
Description
|
Retrieves the intrinsic transformation of a joint (the transformation caused by the joint movement). See also simEmbSetSphericalJointQuaternion. |
C++ synopsis
|
int simEmbGetJointTransformation(int jointHandle,float* position,float* quaternion) |
parameters |
jointHandle (input): handle of the joint
position (output): the position component of the transformation (x, y, z)
quaternion (output): the orientation component of the transformation (x, y, z, w)
|
return value
|
-1 if operation failed
|
simEmbGetObjectHandle (regular API equivalent: simGetObjectHandle)
Description
|
Retrieves an object handle based on its name. Specify the full object name, including suffixes. |
C++ synopsis
|
int simEmbGetObjectHandle(const char* objectName) |
parameters |
objectName (input): name of the object
|
return value
|
-1 if operation failed, otherwise the handle of the object
|
simEmbGetObjectParent (regular API equivalent: simGetObjectParent)
Description
|
Retrieves the handle of an object's parent object. See also simEmbSetObjectParent. |
C++ synopsis
|
int simEmbGetObjectParent(int objectHandle) |
parameters |
objectHandle (input): handle of the object
|
return value
|
-1 if operation failed, otherwise the handle of the parent object
|
simEmbGetObjectTransformation (regular API equivalent: simGetObjectMatrix)
Description
|
Retrieves the transformation (position / orientation) of an object. See also simEmbSetObjectTransformation. |
C++ synopsis
|
int simEmbGetObjectTransformation(int objectHandle,int relativeToObjectHandle,float* position,float* quaternion) |
parameters |
objectHandle (input): handle of the object
relativeToObjectHandle (input): indicates relative to which reference frame we want the transformation. Specify -1 to retrieve the absolute transformation, sim_handle_parent to retrieve the transformation relative to the object's parent, or an object handle relative to whose reference frame we want the transformation.
position (output): the position component of the transformation (x, y, z)
quaternion (output): the orientation component of the transformation (x, y, z, w)
|
return value
|
-1 if operation failed
|
simEmbGetRotationAxis (regular API equivalent: simGetRotationAxis)
Description
|
Retrieves an axis and rotation angle that brings one transformation onto another one. The translation part of the transformations is ignored. This function, when used in combination with simEmbRotateAroundAxis, can be used to build interpolations between transformations. |
C++ synopsis
|
int simEmbGetRotationAxis(const float* positionStart,const float* quaternionStart,const float* positionGoal,const float* quaternionGoal,float* axis,float* angle) |
parameters |
positionStart (input): the position component of the first transformation (x, y, z)
quaternionStart (input): the orientation component of the first transformation (x, y, z, w)
positionGoal (input): the position component of the second transformation (x, y, z)
quaternionGoal (input): the orientation component of the second transformation (x, y, z, w)
axis (output): the rotation axis (x, y, z vector)
angle (output): the rotation angle
|
return value
|
-1 if operation failed
|
simEmbHandleIkGroup (regular API equivalent: simHandleIkGroup)
Description
|
Handles (i.e. solves) an IK group (i.e. by trying to respect the given constraints). |
C++ synopsis
|
int simEmbHandleIkGroup(int ikGroupHandle) |
parameters |
ikGroupHandle (input): handle of the IK group or sim_handle_all or sim_handle_all_except_explicit. (sim_handle_all will handle all IK groups, while sim_handle_all_except_explicit will only handle those that are not marked as "explicit handling")
|
return value
|
number of performed calculations (i.e. when IK group calculation results are different from sim_ikresult_not_performed) if no specific IK group was specified, or a value of type IK result if a specific IK group was specified, -1 in case of an error (a failed IK group calculation is not considered as an error)
|
simEmbInterpolateTransformations (regular API equivalent: simInterpolateMatrices)
Description
|
Computes the interpolated transformation between 2 transformations. |
C++ synopsis
|
int simEmbInterpolateTransformations(const float* position1,const float* quaternion1,const float* position2,const float* quaternion2,float interpolFactor,float* positionOut,float* quaternionOut) |
parameters |
position1 (input): the position component of the first transformation (x, y, z)
quaternion1 (input): the orientation component of the first transformation (x, y, z, w)
position2 (input): the position component of the second transformation (x, y, z)
quaternion2 (input): the orientation component of the second transformation (x, y, z, w)
interpolFactor (input): the interpolation factor, a value between 0.0 and 1.0 (0.0--> transformationOut=transformationIn1, 1.0--> transformationOut=transformationIn2)
positionOut (output): the position component of the interpolated transformation (x, y, z)
quaternionOut (output): the orientation component of the interpolated transformation (x, y, z, w)
|
return value
|
-1 if operation failed
|
simEmbInvertTransformation (regular API equivalent: simInvertMatrix)
Description
|
Inverts a transformation matrix |
C++ synopsis
|
int simEmbInvertTransformation(float* position,float* quaternion); |
parameters |
position (input/output): the position component of the transformation (x, y, z)
quaternion (input/output): the orientation component of the transformation (x, y, z, w)
|
return value
|
-1 if operation failed
|
simEmbLaunch
Description
|
Initializes the external kinematics routines. Should be the very first function called. See also simEmbShutDown. |
C++ synopsis
|
bool simEmbLaunch() |
parameters |
none
|
return value
|
false if operation failed.
|
simEmbMultiplyTransformations (regular API equivalent: simMultiplyMatrices)
Description
|
Multiplies two transformation |
C++ synopsis
|
int simEmbMultiplyTransformations(const float* position1,const float* quaternion1,const float* position2,const float* quaternion2,float* positionOut,float* quaternionOut); |
parameters |
position1 (input): the position component of the first transformation (x, y, z)
quaternion1 (input): the orientation component of the first transformation (x, y, z, w)
position2 (input): the position component of the second transformation (x, y, z)
quaternion2 (input): the orientation component of the second transformation (x, y, z, w)
positionOut (output): the position component of the multiplication (x, y, z)
quaternionOut (output): the orientation component of the multiplication (x, y, z, w)
|
return value
|
-1 if operation failed
|
simEmbMultTransformationWithVector (regular API equivalent: simTransformVector)
Description
|
Multiplies a vector with a transformation (v=tr*v) |
C++ synopsis
|
int simEmbMultTransformationWithVector(const float* position,const float* quaternion,float* vect); |
parameters |
position (input): the position component of the transformation (x, y, z)
quaternion (input): the orientation component of the transformation (x, y, z, w)
vect (input/output): the vector to transform (x, y, z)
|
return value
|
-1 if operation failed
|
simEmbQuaternionToEulerAngles (regular API equivalent: simGetQuaternionFromMatrix)
Description
|
Retrieves Euler angles based on a quaternion. See also simEmbEulerAnglesToQuaternion |
C++ synopsis
|
int simEmbQuaternionToEulerAngles(const float* quaternion,float* euler) |
parameters |
quaternion (input): the 4 values of a quaternion (x, y, z, w)
euler (output): the 3 Euler angles (alpha, beta, gamma)
|
return value
|
-1 if operation failed
|
simEmbRotateAroundAxis (regular API equivalent: simRotateAroundAxis)
Description
|
Rotates a transformation around a specific axis in space. This function, when used in combination with simEmbGetRotationAxis, can be used to build interpolations between transformations. |
C++ synopsis
|
int simEmbRotateAroundAxis(const float* positionIn,const float* quaternionIn,const float* axisVector,const float* axisPosition,float angle,float* positionOut,float* quaternionOut) |
parameters |
positionIn (input): the position component of a transformation (x, y, z)
quaternionIn (input): the orientation component of a transformation (x, y, z, w)
axisVector (input): the axis vector (x, y, z)
axisPosition (input): the axis position (x, y, z)
angle (input): the desired rotation angle
positionOut (output): the position component of the rotated transformation (x, y, z)
quaternionOut (output): the orientation component of the rotated transformation (x, y, z, w)
|
return value
|
-1 if operation failed
|
simEmbSetIkElementProperties (regular API equivalent: simSetIkElementProperties)
Description
|
Sets properties of a specific IK element. See also simEmbSetIkGroupProperties and simEmbGetIkGroupHandle. |
C++ synopsis
|
int simEmbSetIkElementProperties(int ikGroupHandle,int tipDummyHandle,int constraints,const float* precision,const float* weight) |
parameters |
ikGroupHandle (input): handle of the IK group
tipDummyHandle (input): handle of the tip dummy object of the IK element
constraints (input): the constraints of the ik element. sim_ik_avoidance_constraint is not allowed
precision (input): an array of two values where the first represents the linear precision, and the second the angular precision. Can be NULL to keep current settings.
weight (input): an array of two values that represent the linear and angular resolution weights. Can be NULL to keep current settings
|
return value
|
-1 if operation failed
|
simEmbSetIkGroupExplicitHandling (regular API equivalent: simSetExplicitHandling)
Description
|
Sets the explicit handling flags for an IK group. An IK group flagged as "explicit handling" will only be handled or solved when called explicitely with simEmbHandleIkGroup(ikGroupHandle) or simEmbHandleIkGroup(sim_handle_all). |
C++ synopsis
|
int simEmbSetIkGroupExplicitHandling(int ikGroupHandle,bool explicitHandling) |
parameters |
ikGroupHandle (input): handle of the IK group
explicitHandling (input): the desired explicit handling state
|
return value
|
-1 if operation failed
|
simEmbSetIkGroupProperties (regular API equivalent: simSetIkGroupProperties)
Description
|
Sets properties of an IK group. See also simEmbSetIkElementProperties |
C++ synopsis
|
int simEmbSetIkGroupProperties(int ikGroupHandle,int resolutionMethod,int maxIterations,float damping) |
parameters |
ikGroupHandle (input): handle of the IK group
maxIterations (input): the maximum number of iterations for the calculations
damping (input): the DLS damping factor
|
return value
|
-1 if operation failed
|
simEmbSetJointMode (regular API equivalent: simSetJointMode)
Description
|
Sets the operation mode of a joint. Might have as side-effect the change of additional properties of the joint. |
C++ synopsis
|
int simEmbSetJointMode(int jointHandle,int jointMode) |
parameters |
jointHandle (input): handle of the joint
|
return value
|
-1 if operation failed
|
simEmbSetJointPosition (regular API equivalent: simSetJointPosition)
Description
|
Sets the intrinsic position of a joint. This function cannot be used with spherical joints (use simEmbSetSphericalJointQuaternion instead). See also simEmbGetJointPosition |
C++ synopsis
|
int simEmbSetJointPosition(int jointHandle,float position) |
parameters |
jointHandle (input): handle of the joint
position (input): position of the joint (angular or linear value depending on the joint type)
|
return value
|
-1 if operation failed
|
simEmbSetObjectParent (regular API equivalent: simSetObjectParent)
Description
|
Sets an object's parent object. See also simEmbGetObjectParent. |
C++ synopsis
|
int simEmbSetObjectParent(int objectHandle,int parentObjectHandle,bool keepInPlace) |
parameters |
objectHandle (input): handle of the object that will become child of the parent object
parentObjectHandle (input): handle of the object that will become parent, or -1 if the object should become parentless
keepInPlace (input): indicates whether the object's absolute position and orientation should stay same
|
return value
|
-1 if operation failed
|
simEmbSetObjectTransformation (regular API equivalent: simSetObjectMatrix)
Description
|
Sets the transformation (position / orientation) of an object. See also simEmbGetObjectTransformation. |
C++ synopsis
|
int simEmbSetObjectTransformation(int objectHandle,int relativeToObjectHandle,const float* position,const float* quaternion) |
parameters |
objectHandle (input): handle of the object
relativeToObjectHandle (input): indicates relative to which reference frame the transformation is specified. Specify -1 to set the absolute transformation, sim_handle_parent to set the transformation relative to the object's parent, or an object handle relative to whose reference frame the transformation is specified.
position (input): the position component of the transformation (x, y, z)
quaternion (input): the orientation component of the transformation (x, y, z, w)
|
return value
|
-1 if operation failed
|
simEmbSetSphericalJointQuaternion (regular API equivalent: simSetSphericalJointMatrix )
Description
|
Sets the intrinsic quaternion of a spherical joint object. This function cannot be used with non-spherical joints (use simEmbSetJointPosition instead). See also simEmbGetJointTransformation. |
C++ synopsis
|
int simEmbSetSphericalJointQuaternion(int jointHandle,const float* quaternion) |
parameters |
jointHandle (input): handle of the joint
quaternion (input): the quaternion (x, y, z, w)
|
return value
|
-1 if operation failed
|
simEmbShutDown
Description
|
Deinitializes the external kinematics routines. Should be the very last function called. See also simEmbLaunch. |
C++ synopsis
|
bool simEmbShutDown() |
parameters |
none
|
return value
|
false if operation failed.
|
simEmbStart
Description
|
Imports a previously exported kinematic scene content. Can be called at any time to reset the object/joint configurations. |
C++ synopsis
|
int simEmbStart(unsigned char* data,int dataLength) |
parameters |
data (input): pointer to the data to import
dataLength (input): the size of the data to import
|
return value
|
-1 if operation failed, otherwise the number of imported objects
|
|