NaturalPoint Tracking Toolkits (Point Cloud and Rigid Body) Users Manual   7. Using the Rigid Body API In order to use Rigid Body tracking in your own applications, you will need to implement support for it using the Rigid Body API. The Rigid Body API is written as a set of C/C++ function calls and a loadable DLL. The following section provides an overview of the system architecture as well as specific detail about the API calls. 7.1 Getting Started Only a small amount of code needs to be written in order to begin tracking rigid bodies. The following outlines the initialization procedure :   Make sure the cameras have been calibrated with the result saved to a file as described in Section 4.2 ("Camera Calibration tool").   Initialize the rigid body tracking using RB_InitializeRigidBody().   Load an existing calibration profile using RB_LoadProfile().   Load existing rigid body definitions using RB_LoadDefinition().   Start the cameras using RB_StartCameras(). At this point, the cameras should be initialized and collecting frame information. The main loop of the application should poll for frames using RB_GetNextFrame() or RB_GetLatestFrame().   When data processing is complete, call the RB_StopCameras() and then RB_ShutdownRigidBody. 7.2 Rigid Body API Calls 7.2.1 Rigid Body Startup and Shutdown 7.2.1.1 RB_InitializeRigidBody( ) The RB_InitializeRigidBody( ) function attempts to initialize the rigid body tracking API. It should be called before attempting to use other components of the API. It returns information about whether or not it succeeded. NPRESULT RB_InitializeRigidBody()   Parameters none   Parameters Value Meaning NPRESULT_SUCCESS Method succeeded   7.2.1.2 RB_ShutdownRigidBody( ) The RB_ShutdownRigidBody( ) function attempts to shutdown the rigid body tracking API. It should be called after RB_StopCameras() and before the application using the rigid body API closes. It returns information about whether or not it succeeded. NPRESULT RB_ShutdownRigidBody()   Parameters none   Parameters Value Meaning NPRESULT_SUCCESS Method succeeded   7.2.2 Rigid Body Interface 7.2.2.1 RB_LoadProfile() The RB_LoadProfile() function attempts to load a calibration profile stored in a file. It is passed the path to the profile and returns information about whether or not it succeeded. NPRESULT RB_LoadProfile(const char *filename)   Parameters filename [in] the path to the location of the calibration profile   Parameters Value Meaning NPRESULT_SUCCESS Method succeeded InvalidFile The file or path specified is not valid InvalidLicense A valid Rigid Body license was not found InvalidProfileCameraCount The specified profile does not match the current camera configuration   7.2.2.2 RB_StartCameras() The RB_StartCameras() function starts the cameras so that tracking will begin. This function should be called after RB_LoadProfile(). It returns information about whether or not it succeeded. NPRESULT RB_StartCameras()   Parameters none   Parameters Value Meaning NPRESULT_SUCCESS Method succeeded PointCloudNotInitialized The Point Cloud engine has not been properly initialized CamerasAlreadyStarted The cameras have already been started NoProfileLoaded A calibration profile for the cameras has not been loaded UnableToInitializeOptiTrackCameras A problem was encountered when initializing the cameras   7.2.2.3 RB_StopCameras() The RB_StopCameras() function stops the cameras so that tracking will cease. It returns information about whether or not it succeeded. NPRESULT RB_StopCameras()   Parameters none   Parameters Value Meaning NPRESULT_SUCCESS Method succeeded PointCloudNotInitialized The Point Cloud engine has not been properly initialized CamerasNotRunning The cameras are already stopped   7.2.2.4 RB_GetNextFrame() The RB_GetNextFrame() function loads the next available frame of tracking data. Information about the frame is accessed using the Rigid Body Control set of API calls. It returns information about whether or not it succeeded. NPRESULT RB_GetNextFrame()   Parameters none   Parameters Value Meaning NPRESULT_SUCCESS Method succeeded InvalidLicense A valid Rigid Body license was not found NoFrameAvailable No tracking data was found   7.2.2.5 RB_GetLatestFrame() The RB_GetLatestFrame() function loads the most recent frame of tracking data. Information about the frame is accessed using the Rigid Body Control set of API calls. It returns information about whether or not it succeeded. NPRESULT RB_GetLatestFrame()   Parameters none   Parameters Value Meaning NPRESULT_SUCCESS Method succeeded InvalidLicense A valid Rigid Body license was not found NoFrameAvailable No tracking data was found   7.2.2.6 RB_LoadDefinition() The RB_LoadDefinition() function loads a set of rigid body definitions from a file for tracking. It returns information about whether or not it succeeded. NPRESULT RB_LoadDefinition(const char *filename)   Parameters filename [in] the path to the location of the rigid body definition file   Parameters Value Meaning NPRESULT_SUCCESS Method succeeded Failed The definitions failed to load   7.2.2.7 RB_SaveDefinition() The RB_SaveDefinition() function saves the currently loaded rigid body definitions to a file for later use. It returns information about whether or not it succeeded. NPRESULT RB_SaveDefinition(const char *filename)   Parameters filename [in] the path to the location of the rigid body definition file   Parameters Value Meaning NPRESULT_SUCCESS Method succeeded Failed Saving the definitions failed   7.2.3 Rigid Body Streaming 7.2.3.1 RB_StreamTrackd() The RB_StreamTrackd() function starts and stops streaming tracking data over the Trackd interface. It returns information about whether or not it succeeded. NPRESULT RB_StreamTrackd(bool enabled)   Parameters enabled [in] starts and stops the streaming, true starts and false stops   Parameters Value Meaning NPRESULT_SUCCESS Method succeeded   7.2.3.2 RB_StreamVRPN() The RB_StreamVRPN() function starts and stops streaming tracking data over the VRPN interface. It returns information about whether or not it succeeded. NPRESULT RB_StreamVRPN(bool enabled, int port)   Parameters enabled [in] starts and stops the streaming, true starts and false stops port [in] selects the network port to broadcast over   Parameters Value Meaning NPRESULT_SUCCESS Method succeeded   7.2.3.3 RB_StreamNP() The RB_StreamNP() function starts and stops streaming tracking data over the NaturalPoint streaming interface. It returns information about whether or not it succeeded. NPRESULT RB_StreamNP(bool enabled)   Parameters enabled [in] starts and stops the streaming, true starts and false stops   Parameters Value Meaning NPRESULT_SUCCESS Method succeeded   7.2.4 Rigid Body Frame 7.2.4.1 RB_FrameMarkerCount() The RB_FrameMarkerCount() function returns the number of 3D point cloud markers found in the current frame. int RB_FrameMarkerCount()   Parameters (returns) [out] the number of 3D point cloud markers found in the current frame   7.2.4.2 RB_FrameMarkerX() The RB_FrameMarkerX() function returns the X axis position in meters of the selected 3D point cloud marker. float RB_FrameMarkerX(int index)   Parameters (returns) [out] the X position in meters of the selected 3D point cloud marker index [in] the index number of the desired marker. the index is zero based   Parameters Value Meaning 0 No frame data was found   7.2.4.3 RB_FrameMarkerY() The RB_FrameMarkerY() function returns the Y axis position in meters of the selected 3D point cloud marker. float RB_FrameMarkerY(int index)   Parameters (returns) [out] the Y position in meters of the selected 3D point cloud marker index [in] returns the index number of the desired marker. the index is zero based   Parameters Value Meaning 0 No frame data was found   7.2.4.4 RB_FrameMarkerZ() The RB_FrameMarkerZ() function returns the Z axis position in meters of the selected 3D point cloud marker. float RB_FrameMarkerZ(int index)   Parameters (returns) [out] the Z position in meters of the selected 3D point cloud marker index [in] returns the index number of the desired marker. the index is zero based   Parameters Value Meaning 0 No frame data was found   7.2.5 Rigid Body Control 7.2.5.1 RB_IsRigidBodyTracked() The RB_IsRigidBodyTracked() function returns information about whether the selected rigid body is found in the current frame. bool RB_IsRigidBodyTracked(int index)   Parameters (returns) [out] true if the selected rigid body is found in the current frame index [in] the index number of the desired rigid body. the index is zero based   7.2.5.2 RB_GetRigidBodyLocation() The RB_GetRigidBodyLocation() function returns the position and orientation of the selected rigid body. RB_IsRigidBodyTracked() should be checked first to determine whether the rigid body was tracked in the current frame, otherwise the data may be stale. void RB_GetRigidBodyLocation(int RigidIndex,           float *x, float *y, float *z,           float *qx, float *qy, float *qz, float *qw,           float *heading, float *attitude, float *bank)   Parameters RigidIndex [in] the index number of the desired rigid body. the index is zero based x [out] receives the X axis position in meters of the selected rigid body y [out] receives the Y axis position in meters of the selected rigid body z [out] receives the Z axis position in meters of the selected rigid body qx [out] receives the quaternion x value of the selected rigid body qy [out] receives the quaternion y value of the selected rigid body qz [out] receives the quaternion z value of the selected rigid body qw [out] receives the quaternion w value of the selected rigid body heading [out] receives the heading orientation value in degrees of the selected rigid body attitude [out] receives the attitude orientation value in degrees of the selected rigid body bank [out] receives the bank orientation value in degrees of the selected rigid body   7.2.5.3 RB_ClearRigidBodyList() The RB_ClearRigidBodyList() function removes all of the currently loaded rigid body definitions. void RB_ClearRigidBodyList()   Parameters none   7.2.5.4 RB_GetRigidBodyCount() The RB_GetRigidBodyCount() function returns the number of currently loaded rigid body definitions. int RB_GetRigidBodyCount()   Parameters (returns) [out] the number of currently loaded rigid body definitions.   7.2.5.5 RB_DeleteRigidBodyMarker() The RB_DeleteRigidBodyMarker() function deletes a marker from a rigid body definition. void RB_DeleteRigidBodyMarker(int RigidIndex, int MarkerIndex)   Parameters RigidIndex [in] the index of the desired rigid body to remove the marker from. the index is zero based MarkerIndex [in] the index of the desired marker to remove. the index is zero based   7.2.5.6 RB_AddRigidBodyMarker() The RB_AddRigidBodyMarker() function adds a marker to an existing rigid body definition. void RB_AddRigidBodyMarker(int RigidIndex, float x, float y, float z)   Parameters RigidIndex [in] the index of the desired rigid body. the index is zero based x [in] the X axis position of the marker in meters relative to the origin y [in] the Y axis position of the marker in meters relative to the origin z [in] the Z axis position of the marker in meters relative to the origin   7.2.5.7 RB_SetRigidBodyOrigin() The RB_SetRigidBodyOrigin() function changes the origin for an existing rigid body definition. void RB_SetRigidBodyOrigin(int RigidIndex, float x, float y, float z)   Parameters RigidIndex [in] the index of the desired rigid body. the index is zero based x [in] the new X axis position of the origin in meters y [in] the new Y axis position of the origin in meters z [in] the new Z axis position of the origin in meters   7.2.5.8 RB_GetRigidBodyID() The RB_GetRigidBodyID() function returns the ID for the selected rigid body. int RB_GetRigidBodyID(int index)   Parameters (returns) [out] the ID of the selected rigid body index [in] the index of the desired rigid body. the index is zero based   7.2.5.9 RB_SetRigidBodyID() The RB_SetRigidBodyID() function changes the ID for the selected rigid body. void RB_SetRigidBodyID(int index, int ID)   Parameters index [in] the index of the desired rigid body. the index is zero based ID [in] the new ID value for the selected rigid body   7.2.5.10 RB_CreateRigidBody() The RB_CreateRigidBody() function creates a new rigid body definition. void RB_CreateRigidBody(const char *name)   Parameters name [in] the name to be assigned to the newly created rigid body   7.2.5.11 RB_DeleteRigidBody() The RB_DeleteRigidBody() function deletes an existing rigid body definition. void RB_DeleteRigidBody(int index)   Parameters index [in] the index of the rigid body to be deleted. the index is zero based   7.2.5.12 RB_GetRigidBodyFlexibility() The RB_GetRigidBodyFlexibility() function returns the flexibility setting for the selected rigid body. float RB_GetRigidBodyFlexibility(int index)   Parameters (returns) [out] the flexibility setting for the selected rigid body index [in] the index of the desired rigid body. the index is zero based   7.2.5.13 RB_SetRigidBodyFlexibility() The RB_SetRigidBodyFlexibility() function changes the flexibility setting for the selected rigid body. void RB_SetRigidBodyFlexibility(int index, float value)   Parameters index [in] the index of the desired rigid body. the index is zero based value [in] the new flexibility setting for the selected rigid body. the input values range from 0 (least flexible) to 1.0 (most flexible)   7.2.5.14 RB_GetRigidBodyRotationConst() The RB_GetRigidBodyRotationConst() function returns the rotational constraint setting for the selected rigid body. float RB_GetRigidBodyRotationConst(int index)   Parameters (returns) [out] the rotational constraint setting for the selected rigid body index [in] the index of the desired rigid body. the index is zero based   7.2.5.15 RB_SetRigidBodyRotationConst() The RB_SetRigidBodyRotationConst() function changes the rotational constraint setting for the selected rigid body. void RB_SetRigidBodyRotationConst(int index, float value)   Parameters index [in] the index of the desired rigid body. the index is zero based value [in] the new rotational constraint setting for the selected rigid body. the value range is in degrees per frame and ranges from 0 to 180 degrees, a value of 0 disables the constraint   7.2.5.16 RB_GetRigidBodyTranslationConst() The RB_GetRigidBodyTranslationConst() function returns the translation constraint setting for the selected rigid body. float RB_GetRigidBodyTranslationConst(int index)   Parameters (returns) [out] the translation constraint setting for the selected rigid body. index [in] the index of the desired rigid body. the index is zero based   7.2.5.17 RB_SetRigidBodyTranslationConst() The RB_SetRigidBodyTranslationConst() function changes the translation constraint setting for the selected rigid body. void RB_SetRigidBodyTranslationConst(int index, float value)   Parameters index [in] the index of the desired rigid body. the index is zero based value [in] the new translation constraint setting for the selected rigid body. the values are in meters per frame, a value of 0 disables the constraint   7.2.5.18 RB_SetRigidBodyEnabled() The RB_SetRigidBodyEnabled() function controls whether the selected rigid body is enabled for tracking. void RB_SetRigidBodyEnabled(int index, bool enabled)   Parameters index [in] the index of the desired rigid body. the index is zero based enabled [in] a value of true enables the rigid body, a value of false disables it   7.2.5.19 RB_GetRigidBodyEnabled() The RB_GetRigidBodyEnabled() function returns information about whether the selected rigid body is enabled for tracking. bool RB_GetRigidBodyEnabled(int index)   Parameters (returns) [out] a value of true means the rigid body is enabled, a value of false means it is disabled index [in] the index of the desired rigid body. the index is zero based   7.2.5.20 RB_SetRigidBodyColor() The RB_SetRigidBodyColor() function changes the color used for displaying the selected rigid body in the 3D viewport. void RB_SetRigidBodyColor(int index, int r, int g, int b)   Parameters index [in] the index of the desired rigid body. the index is zero based r [in] value for the red color component. the range is from 0 to 255 g [in] value for the green color component. the range is from 0 to 255 b [in] value for the blue color component. the range is from 0 to 255   7.2.5.21 RB_GetRigidBodyColorR() The RB_GetRigidBodyColorR() function returns the red component of the color used for displaying the selected rigid body in the 3D viewport. int RB_GetRigidBodyColorR(int index)   Parameters (returns) [out] the red color component of the rigid body index [in] the index of the desired rigid body. the index is zero based   7.2.5.22 RB_GetRigidBodyColorG() The RB_GetRigidBodyColorG() function returns the green component of the color used for displaying the selected rigid body in the 3D viewport. int RB_GetRigidBodyColorG(int index)   Parameters (returns) [out] the green color component of the rigid body index [in] the index of the desired rigid body. the index is zero based   7.2.5.23 RB_GetRigidBodyColorB() The RB_GetRigidBodyColorB() function returns the blue component of the color used for displaying the selected rigid body in the 3D viewport. int RB_GetRigidBodyColorB(int index)   Parameters (returns) [out] the blue color component of the rigid body index [in] the index of the desired rigid body. the index is zero based   7.2.5.24 RB_GetRigidBodyMarkerCount() The RB_GetRigidBodyMarkerCount() function returns the number of markers used in the selected rigid body definition. int RB_GetRigidBodyMarkerCount(int index)   Parameters (returns) [out] the number of markers used in the selected rigid body index [in] the index of the desired rigid body. the index is zero based   7.2.5.25 RB_GetRigidBodyMarker() The RB_GetRigidBodyMarker() function returns the position of the selected marker in the selected rigid body definition. Marker positions are in meters and relative to the pivot point or center of mass of the rigid body. void RB_GetRigidBodyMarker(int RigidIndex, int MarkerIndex, float *x, float *y, float *z)   Parameters RigidIndex [in] the index of the desired rigid body. the index is zero based MarkerIndex [in] the index of the desired marker. the index is zero based x [out] the X axis position of the marker in meters y [out] the Y axis position of the marker in meters z [out] the Z axis position of the marker in meters   7.2.5.26 RB_GetSyncQuality() The RB_GetSyncQuality() function returns the current camera synchronization status. int RB_GetSyncQuality()   Parameters (returns) [out] the current camera synchronization status. 0=No Sync, 1=Hardware Sync, 2=Good Software Sync, 3=Poor Sync   7.2.6 Point Cloud Interface 7.2.6.1 RB_SetPointCloudTrackingParams() The RB_SetPointCloudTrackingParams() function changes the Point Cloud tracking settings. void RB_SetPointCloudTrackingParams(int iMinRays, float fMaxResidual, float fMinAngle, float fMinRayLength, float fMaxRayLength)   Parameters iMinRays [in] the minimum number of rays required to form a 3D point cloud marker fMaxResidual [in] rays from the camera to the marker must cross closer than this value (in meters) to form 3D points fMinAngle [in] rays from the camera to the marker must cross at an angle (in radians) larger than this to form 3D points fMinRayLength [in] rays from the camera to the marker must cross farther than this distance (in meters) from the camera to form 3D points fMaxRayLength [in] rays from the camera to the marker must cross closer than this distance (in meters) from the camera to form 3D points   7.2.6.2 RB_GetPointCloudTrackingParams() The RB_GetPointCloudTrackingParams() function returns the current Point Cloud tracking settings. void RB_GetPointCloudTrackingParams(int* iMinRays, float* fMaxResidual, float* fMinAngle, float* fMinRayLength, float* fMaxRayLength)   Parameters iMinRays [out] the minimum number of rays required to form a 3D point cloud marker fMaxResidual [out] rays from the camera to the marker must cross closer than this value (in meters) to form 3D points fMinAngle [out] rays from the camera to the marker must cross at an angle (in degrees) larger than this to form 3D points fMinRayLength [out] rays from the camera to the marker must cross farther than this distance (in meters) from the camera to form 3D points fMaxRayLength [out] rays from the camera to the marker must cross closer than this distance (in meters) from the camera to form 3D points   7.2.6.3 RB_CameraCount() The RB_CameraCount() function returns the number of connected cameras. int RB_CameraCount()   Parameters (returns) [out] the number of connected cameras   7.2.6.4 RB_CameraXLocation() The RB_CameraXLocation() function returns the X position of the selected camera in relation to the coordinate system origin. float RB_CameraXLocation(int index)   Parameters (returns) [out] the X position of the selected camera in meters index [in] the index of the desired camera. the index is zero based   7.2.6.5 RB_CameraYLocation() The RB_CameraYLocation() function returns the Y position of the selected camera in relation to the coordinate system origin. float RB_CameraYLocation(int index)   Parameters (returns) [out] the Y position of the selected camera in meters index [in] the index of the desired camera. the index is zero based   7.2.6.6 RB_CameraZLocation() The RB_CameraZLocation() function returns the Z position of the selected camera in relation to the coordinate system origin. float RB_CameraZLocation(int index)   Parameters (returns) [out] the Z position of the selected camera in meters index [in] the index of the desired camera. the index is zero based   7.2.6.7 RB_CameraOrientationMatrix() The RB_CameraOrientationMatrix() function returns the selected element of the orientation matrix of the selected camera. float RB_CameraOrientationMatrix(int camera, int index)   Parameters (returns) [out] the selected element of the orientation matrix camera [in] the index of the desired camera. the index is zero based index [in] index of the item in the array to retrieve. there are 9 elements in the array, valid inputs range from 0 to 8.   7.2.7 Return Code Processing 7.2.7.1 RB_GetResultString() The RB_GetResultString() function returns a plain text message for status codes returned from other functions in the Rigid Body API. const char *RB_GetResultString(NPRESULT result)   Parameters (returns) [out] the plain text message associated with the selected return code result [in] the status code returned from another function in the Rigid Body API