v3.0
WebsiteSupportDownloadsForums
Search
⌃K
Links

Motive API: Function Reference

Please use the table of contents to the right to navigate to specific functions or specific group of functions.
Important Note:
Some of the functions may be missing in the documentation. Please refer to the NPTrackingTools header file for any information that are not documented here.

Project Management

TT_Initialize

Initializes the API and prepares all connected devices for capturing. Please note that TT_Initialize also loads the default profile from the ProgramData directory: C:\ProgramData\OptiTrack\MotiveProfile.motive. When there is a need to load the profile from a separate directory, use TT_LoadProfile function.
NPRESULT TT_Initialize();
Description
  • This function initializes the API library and prepares all connected devices for capturing.
  • When using the API, this function needs to be called at the beginning of a program before using the cameras.
  • Returns an NPRESULT value. When the function successfully updates the data, it returns 0 (or NPRESULT_SUCCESS).
Function Input
  • None
Function Output
  • NPRESULT
C++ Example
// Initializing all connected cameras
TT_Initialize();

TT_Shutdown

Shuts down all of the connected devices.
Description
  • This function closes down all connected devices and the camera library. To ensure that all devices properly shutdown, call this function before terminating an application.
  • When the function successfully closes down the devices, it returns 0 (or NPRESULT_SUCCESS).
  • When calling this function, currently configured camera calibration will be saved under the default System Calibration.cal file.
Function Input
  • None
Function Output
  • NPRESULT
C++ Example
// Close down all of the connected cameras
TT_Shutdown();
return 0;

TT_Update

Processes incoming frame data from the cameras.
Description
  • This function updates frame information with the most recent data from the cameras and 3D processing engines.
  • Another use of this function is to pick up newly connected cameras. Call this function at the beginning of a program in order to make sure that all of the new cameras are properly recognized.
  • TT_Update vs. TT_UpdateSingleFrame: In the case when a client application stalls momentarily, the program may get behind on updating the frames. In this situation, the TT_Update() function will disregard accumulated frames and service only the most recent frame data, but this also means that the client application will be missing the previous frames. On the other hand, the TT_UpdateSingleFrame function ensures that always a consecutive frame is updated each time the function is called. In general, a user should always use TT_Update(). Only in the case where a user wants to ensure their client application has access to every frame of tracking data and they are having problems calling TT_Update() in a timely fashion, should they consider using TT_UpdateSingleFrame(). If it is important for your program to obtain and process every single frame, use the TT_UpdateSingleFrame() function for updating the data.
  • Returns an NPRESULT integer value, depending on whether the operation was successful or not. Returns NPRESULT_SUCCESS when it successfully updates the frame data.
Function Input
  • None
Function Output
  • NPRESULT
C++ Example
//== Update to pick up recently-arrived cameras ==/
TT_Update();
​
//== Frame Processing: Polling the frame data ==//
while( programRunning ){
if( TT_Update() == NPRESULT_SUCCESS ){
frameNumber++;
//== Process Frame Data ==//
}
}

TT_UpdateSingleFrame

Updates a single frame of camera data.
NPRESULT TT_UpdateSingleFrame();
Description
  • Every time this function is called, it updates frame information with the next frame of camera data.
  • Using this function ensures that every frame of data is processed.
  • TT_Update() vs. TT_UpdateSingleFrame(): In the case when a client application stalls momentarily, the program may get behind on updating the frames. In this situation, the TT_Update() function will disregard accumulated frames and service only the most recent frame data, but this also means that the client application will be missing the previous frames. On the other hand, the TT_UpdateSingleFrame function ensures that always a consecutive frame is updated each time the function is called. In general, a user should always use TT_Update(). Only in the case where a user wants to ensure their client application has access to every frame of tracking data and they are having problems calling TT_Update() in a timely fashion, should they consider using TT_UpdateSingleFrame(). If it is important for your program to obtain and process every single frame, use the TT_UpdateSingleFrame() function for updating the data.
  • Returns an NPRESULT value. When the function successfully updates the data, it returns 0 (or NPRESULT_SUCCESS).
Function Input
  • None
Function Output
  • NPRESULT
C++ Example
//== Update to pick up recently-arrived cameras ==/
TT_Update();
​
//== Frame Processing: Polling the frame data ==//
while( programRunning ){
if( TT_UpdateSingleFrame() == NPRESULT_SUCCESS ){
frameNumber++;
//== Process Frame Data ==//
}
}

TT_LoadCalibration, TT_LoadCalibrationW

Loads a Motive camera calibration file.
NPRESULT TT_LoadCalibration(const char *filename);
NPRESULT TT_LoadCalibrationW(const wchar_t *filename);
Description
  • These functions load a camera calibration file (CAL).
  • Camera calibration files need to be exported from Motive.
  • Returns a NPRESULT integer value. If the file was successfully loaded, it returns NPRESULT_SUCCESS.
Function Input
  • Filename (const char, const wchar_t)
Function Output
  • NPRESULT
C++ Example
const char *calFileName= "project.ttp";
NPRESULT fileload = TT_LoadCalibration(calFileName);
​
if (fileload == NPRESULT_SUCCESS)
{
printf("%s successfully loaded.\n", calFileName);
}
else
{
printf("Error: %s\n", TT_GetResultString(fileload));
}

TT_LoadRigidBodies, TT_LoadRigidBodiesW

Imports TRA files and loads Rigid Body assets from it.
NPRESULT TT_LoadRigidBodies(const char *filename);
NPRESULT TT_LoadRigidBodiesW(const wchar_t *filename);
Description
  • This function imports and loads Rigid Body assets from a saved TRA file.
  • TRA files contain exported Rigid Body asset definitions from Motive.
  • All existing assets in the project will be replaced with the Rigid Body assets from the TRA file when this function is called. If you want to keep existing assets and only wish to add new Rigid Bodies, use TT_AddRigidBodies function.
  • Returns an NPRESULT integer value. It returns NPRESULT_SUCCESS when the file is successfully loaded.
Function Input
Filename (const char, const wchat_t)
Function Output
NPRESULT
C++ Example
//Loading Rigid Body Assets from a TRA file.
const char *traFile = "rigidbody.tra";
TT_LoadRigidBodies(traFile);

TT_SaveRigidBodies, TT_SaveRigidBodiesW

Saves all of the Rigid Body asset definitions into a TRA file.
NPRESULT TT_SaveRigidBodies(const char *filename);
NPRESULT TT_SaveRigidBodiesW(const wchar_t *filename);
Description
  • This function saves all of the Rigid Body assets from the project into a TRA file.
  • Attach *.tra extension at the end of the filename.
  • Returns an NPRESULT integer value. It returns 0 or NPRESULT_SUCCESS when successfully saving the file.
Function Input
Filename (const char, const wchar_t)
Function Output
NPRESULT
C++ Example
//== Save Rigid Bodies ==/
TT_SaveRigidBodies("traFileName.tra");

TT_AddRigidBodies, TT_AddRigidBodiesW

Loads a TRA file and adds its Rigid Body assets onto the project.
NPRESULT TT_AddRigidBodies(const char *filename);
NPRESULT TT_AddRigidBodiesW(const wchar_t *filename);
Description
  • This function adds Rigid Body assets from the imported TRA file onto the existing list.
  • Adds Rigid Bodies from imported TRA files onto the asset list of the current project.
  • Returns an NPRESULT integer value. If the Rigid Bodies have been added successfully, it returns 0 or NPRESULT_SUCCESS.
Function Input
Filename (const char, const wchat_t)
Function Output
NPRESULT
C++ Example
/== Adding Rigid Bodies ==/
TT_AddRigidBodies("rigidbody.tra");

TT_LoadProfile, TT_LoadProfileW

Loads a Motive User Profile (.MOTIVE).
NPRESULT TT_LoadProfile(const char *filename);
NPRESULT TT_LoadProfileW(const wchar_t *filename);
Description
  • Loads the default application profile file (MOTIVE), which is located in the ProgramData directory: C:\ProgramData\OptiTrack\MotiveProfile.motive
  • The MOTIVE files store software configurations as well as other software-wide settings.
  • Profile files also loads trackable asset definitions. Once the application profile containing trackable assets is imported, there is no need to import TRA and SKL files separately.
  • Returns an NPRESULT integer value. If the project file was successfully loaded, it returns 0 (NPRESULT_SUCCESS).
Function Input
Filename (const char, const wchar_t)
Function Output
NPRESULT
C++ Example
//== Loading application profile XML file ==/
const char *filename= "UserProfile.ttp";
NPRESULT profileLoad = TT_LoadProfile(filename);
​
if (profileLoad == NPRESULT_SUCCESS)
{
printf("%s successfully loaded.\n", filename);
}
else
{
printf("Error: %s\n", TT_GetResultString(profileLoad));
}

TT_LoadProject, TT_LoadProjectW

Loads a Motive TTP project file.
NPRESULT TT_LoadProject(const char *filename);
NPRESULT TT_LoadProjectW(const wchar_t *filename);
Description
  • Loads a Motive TTP project file. TTP project file loads and saves both camera calibration and Rigid Body assets, so when using TTP files, there is no need to import or export CAL or TRA files separately.
  • Loading a project file will import all of the required information for tracking. These include camera calibration and Rigid Body assets that are associated with a Motive project.
  • Returns an NPRESULT integer value. If the project file was successfully loaded, it returns 0 (NPRESULT_SUCCESS).
Function Input
Filename (const char, const wchar_t)
Function Output
NPRESULT
C++ Example
//== Loading TTP project file ==/
const char *filename= "project.ttp";
NPRESULT ttpload = TT_LoadProject(filename);
​
if (ttpload == NPRESULT_SUCCESS)
{
printf("%s successfully loaded.\n", filename);
}
else
{
printf("Error: %s\n", TT_GetResultString(ttpload));
}

TT_SaveProfile, TT_SaveProfileW

Saves current application setting into a Profile XML file.
NPRESULT TT_SaveProfile(const char *filename);
NPRESULT TT_SaveProfileW(const wchar_t *filename);
Description
  • This function saves the current configuration into an application Profile XML file.
  • Attach *.xml extension at the end of the filename.
  • Returns an NPRESULT integer value. If the profile XML file was saved successfully, it returns 0 (NPRESULT_SUCCESS).
Function Input
Filename (const char, const wchar_t)
Function Output
NPRESULT
C++ Example
//== Saving the TTP project ==/
const char *projectname = "project.ttp";
NPRESULT result = TT_SaveProfile(projectname);
​
if ( result == NPRESULT_SUCCESS ){
printf("Profile XML file saved.");
}
else {
printf("Error: %s", TT_GetResultString(result));
}

TT_SaveProject, TT_SaveProjectW

TT_LoadCalibrationFromMemory

Loads calibration from memory.
NPRESULT TT_LoadCalibrationFromMemory(unsigned char* buffer, int bufferSize);
Description
  • This function loads camera calibration from memory. In order to do this, the program must have saved calibration memory.
  • It assumes the pointer argument (unsigned char*) points to a memory block where calibration data is already stored. The address and size of the calibration buffer must be determined by the developer using the API.
Function Input
  • Buffer (unsigned char*)
  • Size of the buffer (int)
Function Output
  • NPRESULT
C++ Example
// get a pointer to the calibration block in memory
int bufferSize;
// get the size of the buffer
NPRESULT result = TT_LoadCalibrationFromMemory(buffer, bufferSize);

TT_CameraExtrinsicsCalibrationFromMemory

Gets camera extrinsics from a calibration file in memory.
NPRESULT TT_CameraExtrinsicsCalibrationFromMemory(unsigned char* buffer, int bufferSize, eMotiveAPIResult& result);
Description
  • This allows for acquiring camera extrinsics for cameras not connected to system.
  • It simply returns the list of details for all cameras contained in the calibration file.
Function Input
  • Buffer (unsigned char*)
  • Size of the buffer (int)
  • Result
Function Output
  • NPRESULT
C++ Example
// get a pointer to the calibration block in memory
int bufferSize;
​
// get the size of the buffer
NPRESULT result = TT_CameraExtrinsicsCalibrationFromMemory(unsigned char* buffer, int bufferSize, eMotiveAPIResult& result);

Calibration

TT_StartCalibrationWanding

Start a new calibration wanding for all cameras.
void TT_StartCalibrationWanding();
Description
  • This will cancel any existing calibration process.
Function Input
  • None
Function Output
C++ Example

TT_CalibrationState

Returns the current calibration state.
NPRESULT TT_CalibrationState();
Description
  • Returns the current calibration state.
Function Input
  • None
Function Output
  • NPRESULT
C++ Example

TT_CalibrationCamerasLackingSamples

During calibration wanding, this will return a vector of camera indices that are lacking the minimum number of calibration samples to begin calculation.
std::vector<int> TT_CalibrationCamerasLackingSamples();
Description
  • When the returned vector for this method goes to zero size, you can call TT_StartCalibrationCalculation() to begin calibration calculations.
  • Wanding samples will continue to be collected until TT_StartCalibrationCalculation() is called.
Function Input
  • None
Function Output
  • Vector (int)
C++ Example

TT_CameraCalibrationSamples

During calibration wanding.
int TT_CameraCalibrationSamples(int cameraIndex);
Description
  • This will return the number of wand samples collected for the given camera.
  • Return 0 otherwise.
Function Input
  • Camera index (int)
Function Output
  • Number of samples (int)
C++ Example

TT_CancelCalibration

Cancels wanding or calculation and resets calibration engine.
void TT_CancelCalibration();
Description
  • Cancels wanding or calculation
  • Resets calibration engine
Function Input
  • none
Function Output
  • Exits either TT_StartCalibrationWanding() or TT_StartCalibratoinCalculation()
C++ Example

TT_StartCalibrationCalculation

Once wanding is complete, call this to begin the calibration calculations.
bool TT_StartCalibrationCalculation();
Description
  • Starts calibration calculations after wanding.
Function Input
  • Boolean value
Function Output
  • Starts calculation
C++ Example

TT_CurrentCalibrationQuality

During calibration calculation.
int TT_CurrentCalibrationQuality();
Description
  • This method will return the current calibration quality in the range [0-5], with 5 being best.
  • Returns zero otherwise
Function Input
  • none
Function Output
  • Quality on scale of 0-5 (int)
C++ Example

TT_ApplyCalibrationCalculation

Run once TT_CalibrationState() returns "Complete".
bool TT_ApplyCalibrationCalculation();
Description
  • Call this method to apply the calibration results to all cameras.
Function Input
  • none
Function Output
  • Apply calibration results
C++ Example

TT_SetGroundPlane

Set the ground plane using a standard or custom ground plane template.
bool TT_SetGroundPlane(bool useCustomGroundPlane);
Description
  • If true then this function will use a custom ground plane.
Function Input
  • Boolean value of useCustomGroundPlane
Function Output
  • Either applies custom or preset ground plane to calibration.
C++ Example

TT_TranslateGroundPlane

Translate the existing ground plane (in mm).
void TT_TranslateGroundPlane(float x, float y, float z);
Description
  • Takes float variables to alter existing ground plane.
Function Input
  • X, Y, and Z values (float)
Function Output
  • Applies new values to existing ground plane.
C++ Example

Data Streaming

TT_StreamNP

Enables/disables the NatNet streaming of the Natrual Point tracking data.
NPRESULT TT_StreamNP(bool enabled);
Description
  • This function enables/disables NaturalPoint data stream.
  • This is equivalent to the Broadcase Frame Data in the Data Streaming panel in Motive.
  • Returns a NPRESULT integer value. If the operation was successful, it returns 0 (NPRESULT_SUCCESS).
Function Input
  • Boolean argument enabled (true) / disabled (false)
Function Output
  • NPRESULT
C++ Example
//== Enable NP Streaming ==/
TT_StreamNP(true);

TT_StreamTrackd

Enables/disables streaming frame data into trackd.
NPRESULT TT_StreamTrackd(bool enabled);
Description
  • This function enables/disables streaming data into trackd.
  • Returns a NPRESULT integer value. If the operation was successful, it returns 0 (NPRESULT_SUCCESS).
Function Input
  • True for enabling and false for disabling (bool)
Function Output
  • NPRESULT
C++ Example
//== Enable NP Streaming ==/
TT_StreamTrackd(true);

TT_StreamVRPN

Enables/disables data stream into VRPN.
NPRESULT TT_StreamVRPN(bool enabled, int port);
Description
  • This function enables/disables data streaming into VRPN.
  • To stream onto VRPN, the port address must be specified. VRPN server applications run through 3883 port, which is default port for the VRPN streaming.
  • Returns an NPRESULT integer value. If streaming was successfully enabled, or disabled, it returns 0 (NPRESULT_SUCCESS).
Function Input
  • True for enabling and false for disabling (bool)
  • Streaming port address (int)
Function Output
  • NPRESULT
C++ Example
//== Enable Streaming into VRPN ==/
TT_StreamVRPN(true);

3D Frame Data

TT_FrameMarkerCount

Gets total number of reconstruected markers in a frame.
int TT_FrameMarkerCount();
Description
  • This function returns a total number of reconstructed 3D markers detected in current capture frame.
  • Use this function to count a total number of markers, access every markers, and obtain the marker index values.
Function Input
  • None
Function Output
  • Total number of reconstructed markers in the frame (int)
C++ Example
//Obtaining total marker count
int totalMarker = TT_FrameMarkerCount();
printf("Total number of markers: %d", totalMarker);
​
for (int i = 0 ; i < totalMarker; i++) {
//== Use a loop to access every marker in the frame ==//
printf("Marker %d (X/Y/Z): (%f, %f, %f)\n", i,
TT_FrameMarkerX(i), TT_FrameMarkerY(i), TT_FrameMarkerZ(i));
}

TT_FrameMarkerX

Returns x-position of a reconstructed marker.
float TT_FrameMarkerX(int markerIndex);
Description
  • This function returns X coordinate of a reconstructed 3D marker in respect to the global coordinate system, in meters.
  • It requires a marker index value.
Function Input
  • Marker index (int)
Function Output
  • X-position of the 3D marker (float)
C++ Example
int totalMarker = TT_FrameMarkerCount();
printf("Total number of markers: %d", totalMarker);
​
//== Outputting marker positions ==//
for (int i = 0 ; i < totalMarker; i++) {
//== Use a loop to access every marker in the frame ==//
printf("Marker %d (X/Y/Z): (%f, %f, %f)", i,
TT_FrameMarkerX(i), TT_FrameMarkerY(i), TT_FrameMarkerZ(i));
}

TT_FrameMarkerY

Returns y-position of a reconstructed marker.
float TT_FrameMarkerY(int markerIndex);
Description
  • This function returns Y coordinate of a reconstructed 3D marker in respect to the global coordinate system, in meters.
  • It requires a marker index value.
Function Input
  • Marker index (int)
Function Output
  • Y-position of the 3D marker (float)
C++ Example
int totalMarker = TT_FrameMarkerCount();
printf("Total number of markers: %d", totalMarker);
​
//== Outputting marker positions ==//
for (int i = 0 ; i < totalMarker; i++) {
//== Use a loop to access every marker in the frame ==//
printf("Marker %d (X/Y/Z): (%f, %f, %f)", i,
TT_FrameMarkerX(i), TT_FrameMarkerY(i), TT_FrameMarkerZ(i));
}

TT_FrameMarkerZ

Returns z-position of a reconstructed marker.
float TT_FrameMarkerZ(int markerIndex);
Description
  • This function returns Z coordinate of a reconstructed 3D marker in respect to the global coordinate system, in meters.
  • It requires a marker index value.
Function Input
  • Marker index (int)
Function Output
  • Z-position of the 3D marker (float)
C++ Example
int totalMarker = TT_FrameMarkerCount();
printf("Total number of markers: %d", totalMarker);
​
//== Outputting marker positions ==//
for (int i = 0 ; i < totalMarker; i++) {
//== Use a loop to access every marker in the frame ==//
printf("Marker %d (X/Y/Z): (%f, %f, %f)", i,
TT_FrameMarkerX(i), TT_FrameMarkerY(i), TT_FrameMarkerZ(i));
}

TT_FrameMarkerResidual

Returns residual value of a marker.
float TT_FrameMarkerResidual(int markerIndex);
Description
  • This function returns a residual value for a given marker indicated by the marker index.
  • Unit of the returned value is in millimeters.
  • The marker index value may change between frames, but the unique identifier will always remain the same.
Function Input
  • Marker index (int)
Function Output
  • Residual value (float)

TT_FrameMarkerLabel

Returns a unique identifier of a marker.
Core::cUID TT_FrameMarkerLabel(int markerIndex);
Description
  • This function returns a unique identifier (cUID) for a given marker.
  • Markers have an index from 0 to [totalMarkers -1] for a given frame. In order to access unique identifier of any marker, it's index must be inputted.
  • The marker index value may change between frames, but the unique identifier will always remain the same.
Function Input
  • Marker index (int)
Function Output
  • Marker label (cUID)
C++ Example
int totalMarkers = TT_FrameMarkerCount();
vector<Core::cUID> unique_Marker_ID(totalMarkers);
​
for (int i = 0; i < totalMarkers; ++i)
{
unique_Marker_ID[i] = TT_FrameMarkerLabel(int markerIndex);
}

TT_FrameTimeStamp

Returns a timestamp value for the current frame.
double TT_FrameTimeStamp();
Description
  • This function returns a timestamp value of the current frame.
Function Input
  • None
Function Output
  • Frame timestamp (double)
C++ Example
int frameNumber = 0;
​
//== Display Frame number and Time stamp ==//
while( !_kbhit() )
{
if( !TT_Update() ){
frameNumber++; // increment frame number each time a frame is processed.
​
printf("Frame #%d: (Timestamp: %f)\n", frameNumber, TT_FrameTimeStamp());
}
}

TT_FrameCameraCentroid

Checks whether a camera is contributing to reconstruction of a 3D marker, and saves corresponding 2D location as detected in the camera's view.
bool TT_FrameCameraCentroid(int markerIndex, int cameraIndex, float &x, float &y);
Description
  • This function evaluates whether the specified camera (cameraIndex) is contributing to point cloud reconstruction of a 3D point (markerIndex).
  • It returns true if the camera is contributing to the marker.
  • After confirming that the camera contributes to the reconstruction, this function will save the 2D location of the corresponding marker centroid in respect to the camera's view.
  • The 2D location is saved in the declared variable.
Function Input
  • 3D reconstructed marker index (int)
  • Camera index (int)
  • Reference variables for saving x and y (floats).
Function Output
  • True / False (bool)
C++ Example
//== Getting 2D location of marker centroids from a camera.==//
float x, y;
int targetcam = 1;
int frameMarkercount = TT_FrameMarkerCount();
​
for (int i = 0; i < frameMarkercount; i++) // For each detected markers
{
bool result = TT_FrameCameraCentroid(i, targetcam, x, y)
​
if (result)
{
printf("Marker %d location in camera #%d: %f, %f\n", i, targetcam, x, y);
}
}

TT_FlushCameraQueues

Flushes out the camera queues.
void TT_FlushCameraQueues();
Description
  • This function flushes camera queues.
  • In an event when you are tracking a very high number (hundreds) of markers and the application has accumulated data processing latency, you can call TT_FlushCameraQueues() to refresh the camera queue before calling TT_Update() for processing the frame. After calling this function, avoid calling it again until the TT_Update() function is called and NPRESULT_SUCCESS is returned.
Function Input
  • None
Function Output
  • Void
C++ Example
//== Flush Camera Queues to remove accumulated latency. ==//
TT_FlushCameraQueues();
​
//== Update the incoming camera data after. ==//
TT_Update();

Rigid Bodies

TT_IsRigidBodyTracked

Checks whether Rigid Body is tracked or not.
bool TT_IsRigidBodyTracked(int rbIndex);
Description
  • Checks whether the Rigid Body is being tracked in the current frame.
  • Returns true if the Rigid Body is tracked.
Function Input
  • Rigid body index (int)
Function Output
  • True / False (bool)
C++ Example
int totalRB = TT_RigidBodyCount();
​
//== Checking if the Rigid Body is tracked or not ==//
for(int i = 0; i < totalRB)
{
If(TT_IsRigidBodyTracked(i))
{