Overview

The Motive API allows access to and control of the backend software platform for Motive via a C/C++ interface, performing Motive functions without the graphical user interface on top. With the API, users can employ several features of Motive in custom applications, such as accessing 2D camera images, marker centroid data, unlabeled 3D points, labeled markers, and Rigid Body tracking data.

All of the required components for utilizing the API are included in the Motive install directory when the application is installed. The key files for using the Motive API are listed in the below section.

What it offers:

• Camera control

• Frame control

• Point Cloud reconstruction engine control

• Ability to obtain and use reconstructed 3D Marker data

• Rigid body tracking

• Query results

• Ability to stream results over the network

What it doesn't offer

• In-depth hardware control (e.g. hardware sync customization). Use the Camera SDK for this.

• Direct support for data recording and playback.

• Control over peripheral devices (Force plates and NI-DAQ).

• Functionality for Skeleton assets.

Requirements

• The Motive API is supported in Windows only

• Must have a valid Motive license and a corresponding Hardware key.

Files List

When Motive is installed, all of the required components of the Motive API are placed in folders within the installation directory. By default, this directory is C:\Program Files\OptiTrack\Motive.

The following section describes the key files of the API and where each is located.

MotiveAPI.h

[Motive Install Directory]\inc\MotiveAPI.h

The header file MotiveAPI.h contains declarations for functions and classes of the API. Necessary functions and classes are thoroughly commented within this file. This header file must be included in the source code for utilizing the Motive API functions.

lib folder

[Motive Install Directory]\lib

This folder includes C++ 64-bit library files (.lib and .dll) for employing the Motive API.

Samples project

[Motive Install Directory]\Samples\MotiveAPI\

Samples in a Visual Studio project (samples.sln) for accessing Motive functionality such as cameras, markers, and Rigid Body tracking information. Refer to this folder to find out how the API can be used.

Platforms folder

[Motive Install Directory]\plugins

The platforms folder contains qwindows.dll, which is required for running applications using the Motive API. Copy and paste this folder into the EXE directory.

Third-party libraries

[Motive Install Directory]

Third-party DLL libraries are required for all applications built against the API. Please see Motive API: Quick Start Guide for more information.

API Guide / Function Reference

Quick Start Guide: Motive API

This guide introduces some of the commonly used functions of the Motive API.

Motive API Function Reference

A reference guide for Motive API functions, including code samples.

eResult & Video Types

Many of the Motive API functions return their results as integer values defined as an eResult. This value expresses the outcome of the result. eResult values indicate if the function operated successfully, and if not, they provide detailed information on the type of error that occurred.

When you get the eResult output from a function, you can use the MapToResultString function to get the plain text result that corresponds to the error message.

MOTIVE_API const std::wstring MapToResultString( eResult result ); // Returns text of detail information on the result.

Camera video types, or image processing modes, are expressed as integer values as well. These values are listed below and are also commented within the header file.

eResult Values

enum eResult
{
    kApiResult_Success = 0,
    kApiResult_Failed,
    kApiResult_FileNotFound,
    kApiResult_LoadFailed,
    kApiResult_SaveFailed,
    kApiResult_InvalidFile,
    kApiResult_InvalidLicense,
    kApiResult_NoFrameAvailable,
    kApiResult_TooFewMarkers,
    kApiResult_ToManyMarkers,
    kApiResult_UnableToFindGroundPlane,
    kApiResult_UnableGetGroundPlane,
    kApiResult_RemoveCalibrationSquare
};

Camera Video Type Definitions

enum eVideoType
{
    kVideoType_Segment = 0,
    kVideoType_Grayscale = 1,
    kVideoType_Object = 2,
    kVideoType_Precision = 4,
    kVideoType_MJPEG = 6,
    kVideoType_ColorH264 = 9
};

Calibration Functions

The following functions are used to complete the calibration process using the Motive API, and are presented in the order in which they would be performed. For details on specific functions, please refer to the page.

Masking

Auto-Masking

Auto-Masking is done directly using the function. When this function is called, Motive will sample for a short amount of time and apply a mask to the camera imagers where light was detected.

Camera Mask

The function returns the memory block of the mask, with one bit per each pixel of the mask. Masking pixels are rasterized from left to right and from top to bottom of the camera's view.

Clear Masks

The function is used to clear existing masks from the 2D camera view. It returns true when it successfully removes pixel masks.

Set Camera Mask

The function is used to replace the existing camera mask for any camera. A mask is an array of bytes, one byte per mask pixel block. Returns true when masks are applied.

Calibration State

The function is used to report the current state and is typically tracked throughout the calibration process. In addition to providing status information to the operator, the Calibration state is used to determine if and when other calibration functions should be run.

Wanding

Set Calibration Wand

OptiTrack Calibration Wands are configured with preset distances between the markers to ensure precision when calculating the position of the marker in the 3D space. For this reason, it's critical to use the SetCalibrationWand function to establish the correct wand type prior to collecting samples.

The Wand Type is identified as follows:

Start Wanding

Start Calculation

Calibration State

• Initialized: the calibration process has started.

• Wanding: the system is collecting samples.

• PreparingSolver: the system is setting up the environment for the solver.

• EstimatingFocals: the system is estimating the camera focal lengths.

• CalculatingInitial: the system is setting up the environment to calculate the calibration.

• Phase1 - 3: the system is calculating the calibration.

• Phase4: the calibration calculation is finished and ready for the user to either apply or cancel.

• Complete: the calibration has been applied to the cameras and the process is finished.

• CalibrationError: this state occurs either when the calibration has not been started (or reset) or when an error occurs during the calibration process.

Apply Calibration

Cancel Calibration

Evaluate Calibration

Ground Plane

This guide provides detailed instructions on commonly used functions of the Motive API for developing custom applications. For a full list of the functions, refer to the Motive API: Function Reference page. Also, for a sample use case of the API functions, please check out the provided marker project. In this guide, the following topics will be covered:

• Library files and header files

• Initialization and shutdown

• Capture setup (Calibration)

• Configuring camera settings

• Updating captured frames

• 3D marker tracking

• Rigid body tracking

• Data streaming

Environment Setup

Library Files

When developing a Motive API project, make sure its linker knows where to find the required library files. This can be done either by specifying its location within the project or by copying these files onto the project folder.

MotiveAPI.h

Motive API libraries (.lib and .dll) are located in the lib folder within the Motive install directory; which is located at C:\Program Files\OptiTrack\Motive\lib by default. In this folder, library files for both 64-bit (MotiveAPI.dll and MotiveAPI.lib) platforms can be found. When using the API library, all of the required DLL files must be located in the executable directory. Copy and paste the MotiveAPI.dll file onto the folder alongside the executable file.

Third-party Libraries

• Additional third-party libraries are required for Motive API, and most of the DLL files for these libraries can be found in the Motive install directory C:\Program Files\OptiTrack\Motive\. You can simply copy and paste all of the DLL files from the Motive installation directory into the directory of the Motive API project to use them. Highlighted items in the below image are the required DLL files.

• Lastly, copy the C:\Program Files\OptiTrack\Motive\plugins\platforms folder and its contents into the EXE as well since the libraries contained in this folder will also be used.

Header Files

For function declarations, there are two required header files: MotiveAPI.h and RigidBodySettings.h, and these files are located in the C:\Program Files\OptiTrack\Motive\inc\ folder. Always include the directive syntax for adding the MotiveAPI.h header file for all programs that are developed against the Motive API. The syntax for including RigidBodySetting.h file is already included in the MotiveAPI.h file, so there is no need to include this separately.

#include    "MotiveAPI.h"

• The MotiveAPI.h file contains the declaration for most of the functions and classes in the API.

• The RigidBodySettings.h file contains declaration for the cRigidBodySettings class, which is used for configuring Rigid Body asset properties.

Note: You could define these directories by using the MOTIVEAPI_INC, MOTIVEAPI_LIB environment variables. Check the project properties (Visual Studio) of the provided marker project for a sample project configuration.

Motive Files

Motive API, by default, loads the default calibration (CAL) and Application profile (MOTIVE) files from the program data directory unless separately specified. These are the files that Motive also loads at the application startup, and they are located in the following folder:

• Default System Calibration: C:\ProgramData\OptiTrack\Motive\System Calibration.cal

• Default Application Profile: C:\ProgramData\OptiTrack\MotiveProfile.motive

If there are specific files that need to be loaded into the project, you can export and import two files from Motive: motive application profile (MOTIVE) and camera calibration (CAL). The application profile is imported in order to obtain software settings and trackable asset definitions. Only after the camera calibration is imported, reliable 3D tracking data can be obtained. Application profiles can be loaded using the TT_LoadProfile function, and the calibration files can be loaded using the TT_LoadCalibration function.

Initialization and Shutdown

When using the API, connected devices and the Motive API library need to be properly initialized at the beginning of a program and closed down at the end. The following section covers Motive API functions for initializing and closing down devices.

Initialization

To initialize all of the connected cameras, call the TT_Initialize function. This function initializes the API library and gets the cameras ready for capturing data, so always call this function at the beginning of a program. If you attempt to use the API functions without the initialization, you will get an error.

// Initializing all connected cameras
TT_Initialize();

Update

The TT_Update function is primarily used for updating captured frames, which will be covered later, but there is another use. The TT_Update can also be called to update a list of connected devices, and you can call this function after the initialization to make sure all of the newly connected devices are properly initialized in the beginning.

// Initializing all connected cameras
TT_Initialize();

//Update for newly arrive cameras
TT_Update();

Shutdown

When exiting out of a program, make sure to call the TT_Shutdown function to completely release and close down all of the connected devices. Cameras may fail to shut down completely when this function is not called.

// Closing down all of the connected cameras
TT_Shutdown();
return 0;

Setup the Project

Motive Application Profile

The Motive application profile (MOTIVE) stores all the trackable assets involved in a capture and software configurations including application settings and data streaming settings. When using the API, it is strongly recommended to first configure all of the settings and define trackable assets in Motive, export a profile MOTIVE file, and then load the file by calling the TT_LoadProfile function. This way, you can adjust the settings for your need in advance and apply them to your program without worrying about configuring individual settings.

TT_LoadProfile("UserProfile.motive"); 	// Loading application profile, UserProfile.motive

Camera Calibration

Cameras must be calibrated in order to track in 3D space. However, since camera calibration is a complex process, and because of this, it's easier to have the camera system calibrated from Motive, export the camera calibration file (CAL), and the exported file can be loaded into custom applications that are developed against the API. Once the calibration data is loaded, the 3D tracking functions can be used. For detailed instructions on camera calibration in Motive, please read through the Calibration page.

TT_LoadCalibration("CameraCal.cal"); 	// Loading CAL file

Loading Calibration

1. Open Motive.

2. [Motive] Calibrate: Calibrate camera system using the Calibration panel. Read through the Calibration page for details.

3. [Motive] Export: After the system has been calibrated, export the calibration file (CAL) from Motive.

4. Close out of Motive.

5. [API] Load: Import calibration onto your custom application by calling the TT_LoadCalibration function to import CAL files.

6. When successfully loaded, you will be able to obtain 3D tracking data using the API functions.

Camera Settings

Connected cameras are accessible by index numbers. The camera indexes are assigned in the order the cameras are initialized. Most of the API functions for controlling cameras require an index value. When processing all of the cameras, use the TT_CameraCount function to obtain the total camera count and process each camera within a loop. For pointing to a specific camera, you can use the TT_CameraID or TT_CameraName functions to check and use the camera with given its index value. This section covers Motive API functions for checking and configuring camera frame rate, camera video type, camera exposure, pixel brightness threshold, and IR illumination intensity.

Fetching Camera Settings

The following functions return integer values for the configured settings of a camera specified by its index number. Camera video type is returned as an integer value that represents a image processing mode, as listed in the NPVIDEOTYPE.

These camera settings are equivalent to the settings that are listed in the Devices pane of Motive. For more information on each of the camera settings, refer to the Devices pane page.

TT_CameraVideoType(int cameraIndex)      // Returns Video Type
TT_CameraExposure (int cameraIndex)      // Returns Camera Exposure
TT_CameraThreshold(int cameraIndex)      // Returns Pixel Threshold
TT_CameraIntensity(int cameraIndex)      // Returns IR Illumination Intensity
TT_CameraFrameRate(int cameraIndex)      // Returns Camera Frame Rate

Configuring Settings

Now that we have covered functions for obtaining configured settings, now let's modify some of them. There are two main functions for adjusting the camera settings: TT_SetCameraSettings and TT_SetCameraFramerate. The TT_SetCameraSettings function configures video type, exposure, threshold, and intensity settings of a camera which is specified by its index number. The TT_SetCameraFrameRate is used for configuring frame rate of a camera. Supported frame rate range may vary for different camera models. Check the device specifications and apply the frame rates only within the supported range.

TT_SetCameraSettings(int cameraIndex, int videoType, int exposure, int threshold, int intensity);

TT_SetCameraFrameRate(int cameraIndex, int framerate);

If you wish to keep part of the current camera settings, you can use the above functions to obtain the configured settings (e.g. TT_CameraVideoType, TT_CameraFrameRate, TT_CameraExposure, etc.) and use them as input arguments for the TT_SetCameraSettings function. The following example demonstrates modifying frame rate and IR illumination intensity for all of the cameras, while keeping the other settings constant.

//== Changing exposure and threshold settings for all of the cameras ==//
int cameraCount = TT_CameraCount();
int intensity = 10;
int framerate = 100;

for (int i = 0; i < cameraCount; i++)
{
	TT_SetCameraSettings(i, TT_CameraVideoType(i), TT_CameraExposure(i),
					TT_CameraThreshold(i), intensity);

	TT_SetCameraFrameRate(i, framerate);

	//== Outputting the Settings ==//
	printf("Camera #%d:\n", i);
	printf("\tFPS: %d\n\tIntensity: %d\n\tExposure: %d\n\tIntensity: %d\n\tVideo Type:%d\n", 
			TT_CameraFrameRate(i), TT_CameraIntensity(i), TT_CameraExposure(i), 
			TT_CameraIntensity(i),TT_CameraVideoType(i));
}

Camera Setting Ranges

Camera Settings

• Valid frame rate values: Varies depending on camera models, refer to the respective hardware specifications.

• Valid exposure values: Depends on camera model and frame rate settings.

• Valid threshold values: 0 - 255

• Valid intensity values: 0 - 15

Video Types

• Video Type: see the Data Recording page for more information on image processing modes.

• Segment Mode: 0

• Grayscale Mode: 1

• Object Mode: 2

• Precision Mode: 4

• MJPEG Mode: 6

Other Settings

There are other camera settings, such as imager gain, that can be configured using the Motive API. Please refer to the Motive API: Function Reference page for descriptions on other functions.

Updating the frames

In order to process multiple consecutive frames, you must update the camera frames using the following API functions: TT_Update or TT_UpdateSingleFrame. Call one of the two functions repeatedly within a loop to process all of the incoming frames. In the 'marker sample', TT_Update function is called within a while loop as the frameCounter variable is incremented, as shown in the example below.

// marker.cpp sample project

int main()
{
        TT_Initialize();
	int frameCounter = 0; // Frame counter variable
 	while (!_kbhit())
	{
		if(TT_Update() == NPRESULT_SUCCESS)
		{
			// Each time the TT_Update function successfully updates the frame,
			// the frame counter is incremented, and the new frame is processed.
			frameCounter++;

			////// PROCESS NEW FRAME //////
		}
	}
}

TT_Update() vs. TT_UpdateSingleFrame()

There are two functions for updating the camera frames: TT_Update and TT_UpdateSingleFrame. At the most fundamental level, these two functions both update the incoming camera frames. However, they may act differently in certain situations. When a client application stalls momentarily, it could get behind on updating the frames and the unprocessed frames may be accumulated. In this situation, each of these two functions will behave differently.

• The TT_Update() function will disregard accumulated frames and service only the most recent frame data, but it also means that the client application will not be processing the previously missed frames.

• The TT_UpdateSingleFrame() function ensures that only one frame is processed each time the function is called. However, when there are significant stalls in the program, using this function may result in accumulated processing latency.

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.

TT_Update() 		// Process all outstanding frames of data.

TT_UpdateSingleFrame() // Process one outstanding frame of data.

3D Marker Tracking

After loading valid camera calibration, you can use the API functions to track retroreflective markers and get their 3D coordinates. The following section demonstrates using the API functions for obtaining the 3D coordinates. Since marker data is obtained for each frame, always call the TT_Update, or the TT_UpdateSingleFrame, function each time newly captured frames are received.

Marker Index

In a given frame, each reconstructed marker is assigned a marker index number. These marker indexes are used for pointing to a particular reconstruction within a frame. You can also use the TT_FrameMarkerCount function to obtain the total marker count and use this value within a loop to process all of the reconstructed markers. Marker index values may vary between different frames, but unique identifiers will always remain the same. Use the TT_FrameMarkerLabel function to obtain the individual marker labels if you wish to access same reconstructions for multiple frames.

int totalMarker = TT_FrameMarkerCount();
printf("Frame #%d: (Markers: %d)\n", framecounter, totalMarker);

//== Use a loop to access every marker in the frame ==//
for (int i = 0 ; i < totalMarker; i++) {
        printf("\tMarker #%d:\t(%.2f,\t%.2f,\t%.2f)\n\n", 
		i, TT_FrameMarkerX(i), TT_FrameMarkerY(i), TT_FrameMarkerZ(i));
}

Marker Position

For obtaining 3D position of a reconstructed marker, you can use TT_FrameMarkerX, TT_FrameMarkerY, and TT_FrameMarkerZ functions. These functions return 3D coordinates (X/Y/Z) of a marker in respect to the global coordinate system, which was defined during the calibration process. You can further analyze 3D movements directly from the reconstructed 3D marker positions, or you can create a Rigid Body asset from a set of tracked reconstructions for 6 Degrees of Freedom tracking data. Rigid body tracking via the API will be explained in the later section.

int totalMarker = TT_FrameMarkerCount();
printf("Frame #%d: (Markers: %d)\n", framecounter, totalMarker);

//== Use a loop to access every marker in the frame ==//
for (int i = 0 ; i < totalMarker; i++) {
        printf("\tMarker #%d:\t(%.2f,\t%.2f,\t%.2f)\n\n", 
		i, TT_FrameMarkerX(i), TT_FrameMarkerY(i), TT_FrameMarkerZ(i));
}

Rigid Body Tracking

For tracking 6 degrees of freedom (DoF) movement of a Rigid Body, a corresponding Rigid Body (RB) asset must be defined. A RB asset is created from a set of reflective markers attached to a rigid object which is assumed to be undeformable. There are two main approaches for obtaining RB assets when using Motive API; you can either import existing Rigid Body data or you can define new Rigid Bodies using the TT_CreateRigidBody function. Once RB assets are defined in the project, Rigid Body tracking functions can be used to obtain the 6 DoF tracking data. This section covers sample instructions for tracking Rigid Bodies using the Motive API.

Importing Rigid Body Assets

Let's go through importing RB assets into a client application using the API. In Motive, Rigid Body assets can be created from three or more reconstructed markers, and all of the created assets can be exported out into either application profile (MOTIVE) or a Motive Rigid Body file (TRA). Each Rigid Body asset saves marker arrangements when it was first created. As long as the marker locations remain the same, you can use saved asset definitions for tracking respective objects.

Exporting all RB assets from Motive:

• Exporting application profile: File → Save Profile

• Exporting Rigid Body file (TRA): File → Export Rigid Bodies (TRA)

Exporting individual RB asset:

• Exporting Rigid Body file (TRA): Under the Assets pane, right-click on a RB asset and click Export Rigid Body

When using the API, you can load exported assets by calling the TT_LoadProfile function for application profiles and the TT_LoadRigidBodies or TT_AddRigidBodes function for TRA files. When importing TRA files, the TT_LoadRigidBodies function will entirely replace the existing Rigid Bodies with the list of assets from the loaded TRA file. On the other hand, TT_AddRigidBodes will add the loaded assets onto the existing list while keeping the existing assets. Once Rigid Body assets are imported into the application, the API functions can be used to configure and access the Rigid Body assets.

TT_LoadProfile("UserProfile.motive"); 	// Loading application profile

TT_LoadRigidBodies("rbfile.tra"); 	// Loading TRA file
TT_AddRigidBodies("rbfile.tra"); 

Creating New Rigid Body Assets

Rigid body assets can also be defined directly using the API. The TT_CreateRigidBody function defines a new Rigid Body from given 3D coordinates. This function takes in an array float values which represent x/y/z coordinates or multiple markers in respect to Rigid Body pivot point. The float array for multiple markers should be listed as following: {x1, y1, z1, x2, y2, z2, …, xN, yN, zN}. You can manually enter the coordinate values or use the TT_FrameMarkerX, TT_FrameMarkerY, and TT_FrameMarkerZ functions to input 3D coordinates of tracked markers.

When using the TT_FrameMarkerX/Y/Z functions, you need to keep in mind that these locations are taken in respect to the RB pivot point. To set the pivot point at the center of created Rigid Body, you will need to first compute pivot point location, and subtract its coordinates from the 3D coordinates of the markers obtained by the TT_FrameMarkerX/Y/Z functions. This process is shown in the following example.

NPRESULT		TT_CreateRigidBody(const char* name, int userDataID, int markerCount, float *markerList);

Example: Creating RB Assets

int markerCount = TT_FrameMarkerCount;
vector<float> markerListRelativeToGlobal(3*markerCount);

// add markers to markerListRelativeToGlobal using TT_FrameMarkerX, etc
for (int i = 0; i < markerCount; ++i)
{
    	markerListRelativeToGlobal.push_back(TT_FrameMarkerX(i));
    	markerListRelativeToGlobal.push_back(TT_FrameMarkerY(i));
	markerListRelativeToGlobal.push_back(TT_FrameMarkerZ(i));
}

// then average the locations in x, y and z
for (int i = 0; i < markerCount; ++i)
{
    	float sx += markerListRelativeToGlobal[3*i];
    	float sy += markerListRelativeToGlobal[3*i + 1];
    	float sz += markerListRelativeToGlobal[3*i + 2];
}


float ax = sx/markerCount;
float ay = sy/markerCount;
float az = sz/markerCount;
vector<float> pivotPoint = {ax, ay, az};
vector<float> markerListRelativeToPivotPoint(3*markerCount);

// subtract the pivot point location from the marker location
for (int i = 0; i < markerCount; ++i)
{
    markerListRelativeToPivotPoint.push_back(markerListRelativeToGlobal[3*i] - ax);
    markerListRelativeToPivotPoint.push_back(markerListRelativeToGlobal[3*i + 1] - ay);
    markerListRelativeToPivotPoint.push_back(markerListRelativeToGlobal[3*i + 2] - az);
}

TT_CreateRigidBody("Rigid Body New", 1, markerCount, markerListRelativeToPivotPoint);

Rigid Body 6 DoF Tracking Data

6 DoF Rigid Body tracking data can be obtained using the TT_RigidBodyLocation function. Using this function, you can save 3D position and orientation of a Rigid Body into declared variables. The saved position values indicate location of the Rigid Body pivot point, and they are represented in respect to the global coordinate axis. The Orientation is saved in both Euler and Quaternion orientation representations.

void	TT_RigidBodyLocation(int rbIndex, 				//== RigidBody Index
			float *x, float *y, float *z, 			//== Position
			float *qx, float *qy, float *qz, float *qw, 	//== Quaternion
			float *yaw, float *pitch, float *roll);   	//== Euler

Example: RB Tracking Data

//== Declared variables ==//
float	x, y, z;
float 	qx, qy, qz, qw;
float	yaw, pitch, roll;
int rbcount = TT_RigidBodyCount();

for(int i = 0; i < rbcount; i++)
{
	//== Obtaining/Saving the Rigid Body position and orientation ==//
	TT_RigidBodyLocation( i, &x, &y, &z, &qx, & qy, &qz, &qw, &yaw, &pitch, &roll );
	
	if( TT_IsRigidBodyTracked( i ) )
	{
		printf( "%s: Pos (%.3f, %.3f, %.3f) Orient (%.1f, %.1f, %.1f)\n", 
					TT_RigidBodyName( i ), x, y, z, yaw, pitch, roll );
	}
}

Rigid Body Properties

In Motive, Rigid Body assets have Rigid Body properties assigned to each of them. Depending on how these properties are configured, display and tracking behavior of corresponding Rigid Bodies may vary. When using the API, Rigid Body properties are configured and applied using the cRigidBodySettings class which is declared within the RigidBodySetting.h header file.

Within your program, create an instance of cRigidBodySettings class and call the API functions to obtain and adjust Rigid Body properties. Once desired changes are made, use the TT_SetRigidBodySettings function to assign the properties back onto a Rigid Body asset.

For detailed information on individual Rigid Body settings, read through the Properties: Rigid Body page.

NPRESULT	TT_RigidBodySettings(int rbIndex, RigidBodySolver::cRigidBodySettings &settings);

NPRESULT	TT_SetRigidBodySettings(int rbIndex, RigidBodySolver::cRigidBodySettings &settings);

Data Streaming

Once the API has been successfully initialized, data streaming can be enabled, or disabled, by calling either the TT_StreamNP, TT_StreamTrackd, or TT_StreamVRPN function. The TT_StreamNP function enables/disables data streaming via the NatNet. The NatNet SDK is a client/server networking SDK designed for sending and receiving NaturalPoint data across networks, and tracking data from the API can be streamed to client applications from various platforms via the NatNet protocol. Once the data streaming is enabled, connect the NatNet client application to the server IP address to start receiving the data.

TT_StreamNP(true);	//Enabling NatNet Streaming.

The TT_StreamNP function is equivalent to Broadcast Frame Data from the Data Streaming pane in Motive.

Data Streaming Settings

The Motive API does not currently support configuring data streaming settings directly from the API. To configure the streaming server IP address and the data streaming settings, you will need to use Motive and save an application profile MOTIVE file that contains the desired configuration. Then, the exported profile can be loaded when using the API. Through this way, you will be able to set the interface IP address and decide which data to be streamed over the network.

For more information on data streaming settings, read through the Data Streaming page.

Please use the table of contents to the right to navigate to categories of functions. Links to the specific functions in each category are contained in the section header.

Alternately, use Ctrl + F to search the page contents.

Startup / Shutdown

In this section:

| |

Initialize

Initializes the API and prepares all connected devices for capturing. Initialize also loads the default profile C:\ProgramData\OptiTrack\MotiveProfile.motive. When there is a need to load the profile from a separate directory, use the LoadProfile function.

eRESULT		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

• eRESULT

C++ Example

// Initializing all connected cameras
Initialize();

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 kApiResult_Success).

• When calling this function, the currently configured camera calibration will be saved under the default System Calibration.cal file.

Function Input

• None

Function Output

• eRESULT

C++ Example

// Close down all of the connected cameras
Shutdown();
return 0;

BuildNumber

Retrieves the specific build number of the API. This is correlated with the software /// release version, but the software release version is not encoded in this value.

Description

• This function returns the corresponding Motive build number.

Function Input

• None

Function Output

• Build number (int)

C++ Example

//== Printing Motive Build Number ==//

printf("Motive Build: %d\n", BuildNumber());

User Profile Interface

In this section:

LoadProfile

Loads a Motive User Profile (.MOTIVE).

eRESULT		LoadProfile(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 file stores software configurations as well as other application-wide settings.

• Returns an eRESULT integer value. If the project file was successfully loaded, it returns 0 (kApiResult_Success).

Function Input

Filename (const wchar_t)

Function Output

eRESULT

SaveProfile

Saves the current application settings into a Profile XML file.

eRESULT		SaveProfile(const wchar_t* filename);

Description

• This function saves the current configuration into an application Profile XML file.

• Attaches the *.xml extension at the end of the filename.

• Returns an eRESULT integer value. If the profile XML file was saved successfully, it returns 0 (kApiResult_Success).

Function Input

Filename (const wchar_t)

Function Output

eRESULT

Frame Processing

In this section:

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.

• Returns an eRESULT integer value, depending on whether the operation was successful or not. Returns kApiResult_Successwhen it successfully updates the frame data.

Function Input

• None

Function Output

• eRESULT

C++ Example

//== Update to pick up recently-arrived cameras ==/
Update();

//== Frame Processing: Polling the frame data ==//
while( programRunning ){
	if( Update() == kApiResult_Success){
		frameNumber++;
		//== Process Frame Data ==//
	}
} 

UpdateSingleFrame

Updates a single frame of camera data.

eRESULT		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.

• Returns an eRESULT value. When the function successfully updates the data, it returns 0 (or kApiResult_Success).

Function Input

• None

Function Output

• eRESULT

C++ Example

//== Update to pick up recently-arrived cameras ==/
Update();

//== Frame Processing: Polling the frame data ==//
while( programRunning ){
	if( UpdateSingleFrame() == kApiResult_Success){
		frameNumber++;
		//== Process Frame Data ==//
	}
}

FlushCameraQueues

Flushes out the camera queues.

void		FlushCameraQueues();

Description

• This function flushes all queued camera frames.

• 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 FlushCameraQueues() to refresh the camera queue before calling Update() for processing the frame. After calling this function, avoid calling it again until the Update() function is called and kApiResult_Success is returned.

Function Input

• None

Function Output

• Void

C++ Example

//== Flush Camera Queues to remove accumulated latency. ==//
FlushCameraQueues();

//== Update the incoming camera data after. ==//
Update();

Camera Calibration Interface

In this section:

LoadCalibration

Loads a Motive camera calibration file.

eRESULT		LoadCalibration(const wchar_t* filename, int* cameraCount = nullptr);

Description

• Loads a camera calibration file (CAL).

• Camera calibration files need to be exported from Motive.

• Returns an eRESULT integer value. If the file was successfully loaded, it returns kApiResult_Success.

Function Input

• Filename (const wchar_t)

Function Output

• eRESULT

C++ Example

const wchar_t* calibrationFile = L"C:\\ProgramData\\OptiTrack\\Motive\\System Calibration.mcal";
int calibrationCameraCount = 0; 

eRESULT fileload = LoadCalibration( calibrationFile, &calibrationCameraCount );
if (fileload == kApiResult_Success)
{
	printf("%ls successfully loaded.\n", calFileName);
}
else
{
	printf("Error: %ls\n", MapToResultString(fileload));
}

LoadCalibrationFromMemory

Loads a calibration file that was previously loaded into a memory block.

eRESULT		LoadCalibrationFromMemory(unsigned char* buffer, int bufferSize, int* cameraCount = nullptr);

Description

• This function loads a camera calibration from memory. In order to do this, the program must have a saved calibration in 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

• eRESULT

• The number of cameras read from the calibration file (int)

C++ Example

// get a pointer to the calibration block in memory
int bufferSize;
 
// get the size of the buffer
eRESULT result = LoadCalibrationFromMemory(unsigned char* buffer, int bufferSize, int* cameraCount = nullptr );

CameraExtrinsicsCalibrationFromMemory

Gets camera extrinsics from a calibration file in memory.

std::vector<sCameraInfo> CameraExtrinsicsCalibrationFromMemory( unsigned char* buffer, int bufferSize,
        eResult& result );

Description

• This allows for acquiring camera extrinsics for cameras not connected to system.

• It 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

• eRESULT

StartCalibrationWanding

Start a new calibration wanding for all cameras.

void		StartCalibrationWanding();

Description

• This will cancel any existing calibration process.

Function Input

• None

Function Output

CalibrationState

Returns the current calibration state.

eCalibrationState		CalibrationState();

Description

• Returns the current calibration state.

Function Input

• None

Function Output

• eCalibrationState

C++ Example

// If calibrating, print out some state information.
eCalibrationState state = CalibrationState();
if( state == eCalibrationState::Wanding )
{
	std::vector<int> neededCameras( CalibrationCamerasLackingSamples() );
	if( !neededCameras.empty() )
	{
		printf( "\nNeed more samples for %d cameras:", (int) neededCameras.size() );
		for( int cameraIndex:neededCameras )
		{
			int cameraSamples = CameraCalibrationSamples( cameraIndex );
			printf( "\n%d (%d)", CameraID( cameraIndex ), cameraSamples );
		}
		printf( "\n" );
	}
}
// If completed calibration wanding, print the quality
else if( state >= eCalibrationState::PreparingSolver && state <= eCalibrationState::Complete )
{
	PrintCalibrationQuality();
}

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>		CalibrationCamerasLackingSamples();

Description

• When the returned vector for this method goes to zero, call StartCalibrationCalculation() to begin calibration calculations.

• Wanding samples will be collected until StartCalibrationCalculation() is called.

Function Input

• None

Function Output

• Vector (int)

C++ Example

// If calibrating, print out some state information.
eCalibrationState state = CalibrationState();
if( state == eCalibrationState::Wanding )
{
	std::vector<int> neededCameras( CalibrationCamerasLackingSamples() );
	if( !neededCameras.empty() )
	{
		printf( "\nNeed more samples for %d cameras:", (int) neededCameras.size() );
		for( int cameraIndex:neededCameras )
		{
			int cameraSamples = CameraCalibrationSamples( cameraIndex );
			printf( "\n%d (%d)", CameraID( cameraIndex ), cameraSamples );
		}
		printf( "\n" );
	}
}
// If completed calibration wanding, print the quality
else if( state >= eCalibrationState::PreparingSolver && state <= eCalibrationState::Complete )
{
	PrintCalibrationQuality();
}

CameraCalibrationSamples

Returns the number of wand samples collected for the given camera during calibration wanding.

int		CameraCalibrationSamples(int cameraIndex);

Description

• This will return the number of wand samples collected for the given camera.

• Returns 0 otherwise.

Function Input

• Camera index (int)

Function Output

• Number of samples (int)

C++ Example

// If calibrating, print out some state information.
eCalibrationState state = CalibrationState();
if( state == eCalibrationState::Wanding )
{
	std::vector<int> neededCameras( CalibrationCamerasLackingSamples() );
	if( !neededCameras.empty() )
	{
		printf( "\nNeed more samples for %d cameras:", (int) neededCameras.size() );
		for( int cameraIndex:neededCameras )
		{
			int cameraSamples = CameraCalibrationSamples( cameraIndex );
			printf( "\n%d (%d)", CameraID( cameraIndex ), cameraSamples );
		}
		printf( "\n" );
	}
}
// If completed calibration wanding, print the quality
else if( state >= eCalibrationState::PreparingSolver && state <= eCalibrationState::Complete )
{
	PrintCalibrationQuality();
}

CancelCalibration

Cancels wanding or calculation and resets the calibration engine.

void		CancelCalibration();

Description

• Cancels wanding or calculation

• Resets calibration engine

Function Input

• none

Function Output

• Exits either StartCalibrationWanding() or StartCalibrationCalculation()

StartCalibrationCalculation

Once wanding is complete, call this function to begin the calibration calculations.

bool		StartCalibrationCalculation();

Description

• Starts calibration calculations after wanding.

Function Input

• Boolean value

Function Output

• Starts calculation

C++ Example

// Start calculation and it will return false if it fails (likely due to not wanding first)
if( !StartCalibrationCalculation() )
{
	printf( "ERROR - Please wand the volume first by calling StartCalibrationWanding()\n" );
}

CurrentCalibrationQuality

Retrieves the current calibration quality.

int		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

int quality = CurrentCalibrationQuality();

printf( "Current calibration quality: " );
switch( quality )
{
case 0:
	printf( "Fair\n" );
	break;
case 1:
	printf( "Good\n" );
	break;
case 2:
	printf( "Great\n" );
	break;
case 3:
	printf( "Excellent\n" );
	break;
case 4:
	printf( "Exceptional\n" );
	break;
}

ApplyCalibrationCalculation

Call this function once CalibrationState() returns "Complete" to apply the calibration results to all cameras.

bool		ApplyCalibrationCalculation();

Description

• Call this method to apply the calibration results to all cameras.

Function Input

• none

Function Output

• Apply calibration results

C++ Example

// Apply calibration to all cameras and if it fails, it will return false (likely due to not wanding)
if( !ApplyCalibrationCalculation() )
{
	printf( "ERROR - Please wand the volume first by calling StartCalibrationWanding()\n" );
}

SetGroundPlane

Set the ground plane using a standard or custom ground plane template.

eRESULT		SetGroundPlane(bool useCustomGroundPlane);

Description

• Applies a standard or custom ground plane to the calibration.

Function Input

• Boolean value of useCustomGroundPlane

Function Output

• Either applies custom or preset ground plane to calibration.

TranslateGroundPlane

Translate the existing ground plane (in mm).

void		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.

Data Streaming

In this section:

StreamNP

Enables or disables the NatNet streaming of the OptiTrack data.

eRESULT		StreamNP(bool enable);

Description

• This function enables/disables the OptiTrack data stream.

• This is equivalent to the Broadcast Frame Data in the Data Streaming panel in Motive.

• If the operation was successful, it returns 0 (kApiResult_Success), or an error code otherwise.

Function Input

• Boolean argument enabled (true) / disabled (false)

Function Output

• eRESULT

C++ Example

//== Enable NP Streaming ==/
StreamNP(true);

StreamVRPN

eRESULT		StreamVRPN(bool enable, int port);

Description

• This function enables or disables data streaming into VRPN.

• To stream onto VRPN, the port address must be specified. VRPN server applications run through 3883 port, which is the default port for the VRPN streaming.

• Returns an eRESULT integer value. If streaming was successfully enabled, or disabled, it returns 0 (kApiResult_Success).

Function Input

• True to enable and false to disable (bool)

• Streaming port address (int)

Function Output

• eRESULT

C++ Example

//== Enable Streaming into VRPN ==/
StreamVRPN(true);

Frame Info

In this section:

FrameTimeStamp

Returns a timestamp value for the current frame.

double		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( !Update() ){
		frameNumber++;	// increment frame number each time a frame is processed.

		printf("Frame #%d: (Timestamp: %f)\n", frameNumber, FrameTimeStamp());
	}
}

Marker Interface

In this section:

MarkerCount

Retrieves the total number of reconstructed markers in the current frame.

int		MarkerCount();

Description

• This function returns a total number of reconstructed 3D markers detected in the 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 = MarkerCount();
printf("Total number of markers: %d", totalMarker);

MarkerID

Returns the unique identifier of a specific marker in the current frame.

Core::cUID		MarkerID(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 = MarkerID();
vector<Core::cUID> unique_Marker_ID(totalMarkers);

for (int i = 0; i < totalMarkers; ++i)
{
    unique_Marker_ID[i] = MarkerID(int markerIndex); 
}

MarkerResidual

Returns the residual value of a specific marker in the current frame.

float		MarkerResidual(int markerIndex);

Description

• This function returns the residual value for a given marker indicated by the marker index.

• 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)

MarkerCameraCentroid

Checks whether a camera is contributing to reconstruction of a 3D marker, and saves the corresponding 2D location as detected in the camera's view.

bool		MarkerCameraCentroid(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 = MarkerCount();

for (int i = 0; i < frameMarkercount; i++) // For each detected markers
{
	bool result = MarkerCameraCentroid(i, targetcam, x, y)

	if (result)
	{
		printf("Marker %d location in camera #%d: %f, %f\n", i, targetcam, x, y);
	}
}

Rigid Body Interface

In this section:

RigidBodyCount

Returns a total number of Rigid Bodies.

int		RigidBodyCount();

Description

• This function returns a total count of Rigid Bodies defined in the project, including all tracked and untracked assets.

• This function can be used within a loop to set required number iterations and access each of the Rigid Bodies.

Function Input

• None

Function Output

• Total Rigid Body count (int)

C++ Example

//== Getting names of all Rigid Bodies ==//
int rigidBodyCount = RigidBodyCount();

for( int i = 0; i < rigidBodyCount; i++ )
{
	wchar_t name[ 256 ];
	RigidBodyName( i, name, 256 );
	printf( L"\t%ls\n", name );
}

CreateRigidBody

Creates a Rigid Body asset from a set of reconstructed 3D markers.

eRESULT		CreateRigidBody(const wchar_t* name, int id, int markerCount, float* markerList);

Description

• This functions creates a Rigid Body from the marker list and marker count provided in its argument.

• The marker list is expected to contain a list of marker coordinates in the following order: (x1, y1, z1, x2, y2, z2, …, xN, yN, zN). The x/y/z coordinates must be in respect to the Rigid Body pivot point, in meters.

• Inputted 3D locations are taken as Rigid Body marker positions about the Rigid Body pivot point. If you are using MarkerX/Y/Z functions to obtain the marker coordinates, you will need to subtract the pivot point location from the global marker locations when creating a Rigid Body. This is shown in the below example. If this is not done, the created Rigid Body will have its pivot point at the global origin.

• Returns an eRESULT integer value. If the Rigid Body was successfully created, it returns 0 or kApiResult_Success.

Function Input

• Rigid body name (wchar_t)

• User Data ID (int)

• Marker Count (int)

• Marker list (float list)

Function Output

• eRESULT

SetRigidBodyProperty

Changes property settings of a Rigid Body.

bool		SetRigidBodyProperty(int rbIndex, const std::wstring& propertyName, const sPropertyValue& value);

Description

• This function sets the value of a rigidbody property.

• True if the property was found and the value was set

Function Input

• Rigid body index (int)

• Name of the property to set (std::wstring)

• Value to set the property to (sPropertyValue)

Function Output

• bool

ClearRigidBodies

Clears and removes all Rigid Body assets.

void		ClearRigidBodies();

Description

• This function clears all of existing Rigid Body assets in the project.

Function Input

• None

Function Output

• Void

C++ Example

//== Clear all Rigid Bodies ==//
ClearRigidBodies();

LoadRigidBodies

Imports .motive files and loads Rigid Body assets from it.

eRESULT		LoadRigidBodies(const wchar_t* filename);

Description

• This function imports and loads Rigid Body assets from a saved .motive file.

• .motive file contain exported Rigid Body asset definitions from Motive.

• All existing assets in the project will be replaced with the Rigid Body assets from the .motive file when this function is called. If you want to keep existing assets and only wish to add new Rigid Bodies, use the AddRigidBodies function.

• Returns an eRESULT integer value. It returns kApiResult_Success when the file is successfully loaded.

Function Input

Filename (const wchat_t)

Function Output

eRESULT

AddRigidBodies

Loads a .motive file and adds its Rigid Body assets onto the project.

eRESULT		AddRigidBodies(const wchar_t* filename);

Description

• This function adds Rigid Body assets from the imported .motive file to the asset list of the current project. Existing assets are not deleted.

• Returns an eRESULT integer value. If the Rigid Bodies have been added successfully, it returns 0 or kApiResult_Success.

Function Input

Filename (const wchar_t)

Function Output

eRESULT

SaveRigidBodies

Saves all of the Rigid Body asset definitions into a .motive file.

eRESULT		SaveRigidBodies(const wchar_t* filename);

Description

• This function saves all of the Rigid Body assets from the project into a .motive file.

• Returns an eRESULT integer value. It returns 0 or kApiResult_Success when successfully saving the file.

Function Input

Filename (const wchar_t)

Function Output

eRESULT

RigidBodyID

Returns the unique ID of a Rigid Body at the given index.

Core::cUID		RigidBodyID(int rbIndex);

Description

• This function returns the unique ID number of a Rigid Body.

• This is different from User ID, which is a user definable ID for the Rigid Body. When working with capture data in external pipelines, this value can be used to address specific Rigid Bodies in the scene.

Function Input

• Rigid body index (int)

Function Output

• Unique ID number for Rigid Body

C++ Example

//== unique ID for all Rigid Bodies ==//
for ( int i = 0 ; i < RigidBodyCount(); i++ )
{
	Core::cUID rbID = RigidBodyID();
	std::wstring ID = 
		std::to_wstring(rbID.HighBits()) + L", " +
		std::to_wstring(rbID.LowBits());
 	printf("ID for RigidBody %d : %ls", i, ID);
}

RigidBodyName

Returns the name for the Rigid Body at the given index.

const wchar_t*		RigidBodyName(int rbIndex, wchar_t* buffer, int bufferSize);

Description

• These functions are used to obtain the name of a Rigid Body.

• Returns the assigned name of the Rigid Body.

Function Input

• Rigid body index (int)

Function Output

• Rigid body name (wconst char_t*)

C++ Example

int totalRB = RigidBodyCount();

//== Printing Rigid Body Names ==//
for( int i = 0; i < totalRB; i++ )
{
	printf("Rigid Body: %ls", RigidBodyName(i)); 
}

IsRigidBodyTracked

Checks whether Rigid Body is tracked or not.

bool		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 = RigidBodyCount();

//== Checking if the Rigid Body is tracked or not ==//
for(int i = 0; i < totalRB)
{
	If(IsRigidBodyTracked(i))
	{
		// Process Rigid Body
	}
}

RemoveRigidBody

Removes a Rigid Body at the given index.

eRESULT		RemoveRigidBody(int rbIndex);

Description

• This function removes a single Rigid Body from a project.

• Returns an eRESULT integer value. If the operation was successful, it returns 0 (kApiResult_Success).

Function Input

• Rigid body index (int)

Function Output

• eRESULT

C++ Example

//== Removing Rigid Bodies that are not tracked in the scene ==//
int totalRB = RigidBodyCount();

for (int i = 0; i < totalRB; i++)
{
	if(!IsRigidBodyTracked(i))
	{
 		RemoveRigidBody(i);
	}
}

SetRigidBodyEnabled

Enables or disables tracking of a Rigid Body.

void		SetRigidBodyEnabled(int rbIndex, bool enabled);

Description

• This function enables or disables tracking of the selected Rigid Body.

• All Rigid Bodies are enabled by default. Disabled Rigid Bodies will not be tracked, and no data will be received from it.

Function Input

• Rigid body index (int)

• Tracking status (bool)

Function Output

• Void

C++ Example

int totalRB = RigidBodyCount();

//== Disabling all Rigid Bodies ==//
for(int i = 0; i < totalRB; i++)
{
	SetRigidBodyEnabled(i, FALSE);
} 

RigidBodyEnabled

Checks whether a Rigid Body is enabled.

bool		RigidBodyEnabled(int rbIndex);

Description

• This function checks whether tracking of the Rigid Body is enabled or not.

• The function returns true is the tracking is enabled.

Function Input

• Rigid body index (int)

Function Output

• True / False (bool)

C++ Example

int totalRB = RigidBodyCount();

for (int i = 0; i < totalRB; i++)
{
	if (RigidBodyEnabled(i))
	{
 		//== Disabling all enabled Rigid Bodies ==//
		SetRigidBodyEnabled(i, FALSE);
	}
}

RigidBodyTranslatePivot

Translates the pivot point of a Rigid Body.

eRESULT		RigidBodyTranslatePivot(int rbIndex, float x, float y, float z);

Description

• This function translates a Rigid Body.

• 3D position of a Rigid Body will be displaced in x/y/z directions by inputted amount (meters).

• Translation is applied in respect to the local Rigid Body coordinate axis, not the global axis.

• Returns an eRESULT integer value. If the operation is successful, returns 0 (kApiResult_Success).

Function Input

• Rigid body index (int)

• Translation along x-axis, in meters. (float)

• Translation along y-axis, in meters. (float)

• Translation along z-axis, in meters. (float)

Function Output

• eRESULT

C++ Example

int rbIndex = 1;

//== Translating a Rigid Body 2 cm in positive x-direction ==//
RigidBodyTranslatePivot(rbIndex, 0.02, 0, 0);

RigidBodyResetOrientation

Resets the orientation of a Rigid Body.

bool		RigidBodyResetOrientation(int rbIndex);

Description

• This function resets the orientation of the Rigid Body and re-aligns its orientation axis with the global coordinate system.

• Note: When creating a Rigid Body, its zero orientation is set by aligning its axis with the global axis at the moment of creation. Calling this function essentially does the same thing on an existing Rigid Body asset.

• Returns true if the Rigid Body orientation was reset.

Function Input

• Rigid body index (int)

Function Input

• True / False (bool)

C++ Example

int rbcount = RigidBodyCount();

//== Resetting orientation of each Rigid Body. ==//
for( int i = 0; i < rbcount i++ )
{
	if(RigidBodyResetOrientation(i))
	{
		printf("Rigid body (%ls) orientation reset", RigidBodyName(i));
	}
}

RigidBodyMarkerCount

Gets total number of markers in a Rigid Body.

int		RigidBodyMarkerCount(int rbIndex);

Description

• This function returns the total number of markers involved in a Rigid Body.

Function Input

• Rigid body index (int)

Function Output

• Total number of marker in the Rigid Body (int)

C++ Example

int rbcount = RigidBodyCount();

//== Listing out all of the Rigid Body markers ==// 
for(int i = 0; i < rbcount; i++)
{
	printf("Rigid Body:%ls\t Marker Count: %d", RigidBodyName(i), RigidBodyMarkerCount(i));
}

RigidBodyMarker

Retrieves the positional offset of a marker constraint from a defined rigid body.

bool		RigidBodyMarker(int rbIndex, int markerIndex, float* x, float* y, float* z);

Description

• This function gets the 3D position of a solved Rigid Body marker and saves them in designated addresses. Rigid body marker positions from this function represents solved (or expected) location of the Rigid Body markers.

• Note that the 3D coordinates obtained by this function are represented in respect to Rigid Body's local coordinate axis.

Function Input

• Rigid body index (int)

• Marker index (int)

• Three declared variable addresses for saving the x, y, z coordinates of the marker (float)

Function Output

• True / False (bool)

C++ Example

//== Listing out all of the Rigid Body markers and its respective position. ==//
int rbcount = RigidBodyCount();

for(int i = 0; i < rbcount; i++)
{
	float	x,y,z;

	for(int j = 0; j < RigidBodyMarkerCount(i); j++)
	{
		wchar_t name[ 256 ];
		RigidBodyName( i, name, 256 );
		printf("Rigid Body:%ls\t Marker #%d\n", RigidBodyName(i), j);
		
		//== Marker Locations ==//
		RigidBodyMarker(i, j, &x, &y, &z);
		printf("Local: (%f, %f, %f)\n", x, y, z);
	}
}

RigidBodyUpdateMarker

Changes and updates the Rigid Body marker constraint positions.

bool     RigidBodyUpdateMarker( int rbIndex, int markerIndex, float x, float y, float z );

Description

• This function is used to change the expected positions of a single Rigid Body marker.

• Rigid body markers are expected marker positions. Read about marker types in Motive.

Function Input

• Rigid body index (int)

• Marker index (int)

• New x-position of the Rigid Body marker in relation to the local coordinate system.

• New y-position of the Rigid Body marker in relation to the local coordinate system.

• New z-position of the Rigid Body marker in relation to the local coordinate system.

Function Output

• Returns true if marker locations have been successfully updated.

RigidBodyReconstructedMarker

Retrieves the reconstructed marker location for a marker constraint on a defined rigid body in the current frame.

bool	RigidBodyReconstructedMarker( int rbIndex, int markerIndex, bool& tracked,       float& x, float& y, float& z );

Description

• This function retrieves 3D coordinates of each expected Rigid Body marker positions in designated variable addresses.

• 3D coordinates are saved in respect to global coordinate system.

Function Input

• Rigid body index (int)

• Marker index (int)

• Tracked status, True or False (bool)

• Three declared variable addresses for saving x, y, z coordinates of the marker (float).

Function Output

• Returns true if marker locations were found and successfully returned.

C++ Example

//== Listing out all of the Rigid Body markers and its respective position. ==//
int rbcount = RigidBodyCount();

for(int i = 0; i < rbcount; i++)
{
	float	gx, gy, gz;
	bool	tracked;

	for(int j = 0; j < RigidBodyMarkerCount(i); j++)
	{
		printf("Rigid Body:%ls\t Marker #%d\n", RigidBodyName(i), j);
		 
		//== Expected Rigid Body marker positions. ==//
		RigidBodyReconstructedMarker(i, j, tracked, gx, gy, gz);
		printf("Global: (%f, %f, %f)\n", x, y, z);
	}
}

RigidBodyMeanError

Returns a mean error of the Rigid Body tracking data.

float		RigidBodyMeanError(int rbIndex);

Description

• Returns the average distance between the constraint location and the corresponding reconstructed marker, for all constraints.

Function Input

• Rigid body index (int)

Function Output

• Mean error (meters)

Rigid Body Refinement

In this section:

RigidBodyRefineStart

Initiates the Rigid Body refinement process. Input the number of samples and the ID of the Rigid Body you wish to refine. After starting the process, RigidBodyRefineSample must be called on every frame to collect samples.

bool     RigidBodyRefineStart( Core::cUID rigidBodyID, int sampleCount );

Description

• This function is used to start Rigid Body refinement.

Function Input

• Target Rigid Body ID

• Sample count (int)

Function Output

• Returns true if the refinement process has successfully initiated.

RigidBodyRefineSample

This function collects samples for Rigid Body refinement after calling the RigidBodyRefineStart function. Call this function for every frame within the update loop. You can check the progress of calibration by calling the RigidBodyRefineProgress function.

bool     RigidBodyRefineSample();

Description

• This function collects Rigid Body tracking data for refining the definition of the corresponding Rigid Body.

Function Input

• None. Samples frames for the initialized refine progress.

Function Output

• Returns true if the refinement process has successfully collected a sample. This function does not collect samples if the Rigid Body is not tracked on the frame.

RigidBodyRefineState

This function inquiries the state of the refinement process. It returns eRigidBodyRefineState enum as a result.

eRigidBodyRefineState     RigidBodyRefineState();

Description

• This function queries the state of the Rigid Body refinement process. It returns an enum value for indicating whether the process is initialized, sampling, solving, complete, or uninitialized.

   <source> enum eRigidBodyRefineState {
   RigidBodyRefine_Initialized = 0,
   RigidBodyRefine_Sampling,
   RigidBodyRefine_Solving,
   RigidBodyRefine_Complete,
   RigidBodyRefine_Uninitialized
   };
   </source>

Function Input

• None. Checks the state on the ongoing refinement process.

Function Output

• Returns eRigidBodyRefineState enum value.

RigidBodyRefineProgress

This function retrieves the overall sampling progress of the rigid body refinement solver.

float     RigidBodyRefineProgress();

Description

• When the refinement process is under the sampling state, calling this function returns the sampling progress. It will return a percentage value representing the sampling progress with respect to the total number of samples given in the RigidBodyRefineStart parameter.

Function Input

• None. Checks the progress on the ongoing refinement process.

Function Output

• Returns percentage completeness of the sampling process (float).

RigidBodyRefineInitialError

This function returns the error value of the Rigid Body definition before the refinement and is typically called in conjunction with RigidBodyRefineResultError.

float     RigidBodyRefineInitialError();

Description

• Once the refinement process has reached complete stage, this function can be called along with RigidBodyRefineResultError to compare the error values from the corresponding Rigid Body definition before and after the refinement.

Function Input

• None.

Function Output

• Average error value of the target Rigid Body definition prior (RigidBodyRefineInitialError) and after (RigidBodyRefineResultError) the refinement.

RigidBodyRefineResultError

This function returns the error value of the Rigid Body definition after the refinement.

float     RigidBodyRefineResultError();

Description

• Once the refinement process has reached complete stage, this function can be called along with RigidBodyRefineInitialError to compare the error values from the corresponding Rigid Body definition before and after the refinement.

Function Input

• None.

Function Output

• Average error value of the target Rigid Body definition prior (RigidBodyRefineInitialError) and after (RigidBodyRefineResultError) the refinement.

RigidBodyRefineApplyResult

This function applies the refined result to the corresponding Rigid Body definition.

bool     RigidBodyRefineApplyResult();

Description

• This function applies the refinement to the Rigid Body definition. Call this function after comparing the error values before and after the refinement using the RigidBodyRefineInitialError and RigidBodyRefineResultError functions.

Function Input

• None.

Function Output

• Returns true if the refined results have been successfully applied.

RigidBodyRefineReset

This function discards the final refinement result and resets the refinement process.

bool     RigidBodyRefineReset();

Description

• If the final refinement result from the RigidBodyRefineResultError call is not satisfying, you can call this function to discard the result and start over from the sampling process again.

Function Input

• None.

Function Output

• Returns true if the refined results have been successfully reset.

Camera Interface

In this section:

CameraCount

Returns the total number of cameras connected to the system.

int		CameraCount();

Description

• This function returns a total camera count.

Function Input

• None

Function Output

• Total number of cameras (int)

C++ Example

//== Printing Frame rate of the cameras ==//
int totalCamera = CameraCount();
for( int i = 0; i < totalCamera; i++)
{
 	printf("%d frame rate: %d\n", CameraSerial(i), CameraFrameRate(i));
}

CameraGroupCount

Returns the camera group count.

int		CameraGroupCount();

Description

• This function returns the total count of camera groups that are involved in the project.

• This will generally return a value of two: one for the tracking cameras and one for reference cameras.

Function Input

• None

Function Output

• Camera group count (int)

C++ Example

int groupcount = CameraGroupCount();

//== Processing Camera Groups ==//
for(int i = 0; i < groupcount; i++)
{
	//== Process each camera group ==//
}

CameraGroup

Returns an index value of a camera group that a camera is in.

int		CameraGroup(int cameraIndex);

Description

• This function takes an index value of a camera and returns the corresponding camera group index that the camera is in.

Function Input

• Camera index (int)

Function Output

• Camera group index (int)

C++ Example

//== Listing out all of the cameras and their associate group index ==//
int cameracount = CameraCount();

for(int i = 0; i < cameracount; i ++)
{
	printf("Camera: %d\t CameraGroup: #%d", CameraSerial(i), CameraGroup(i));
}

CameraSerial

Returns the corresponding camera's serial number as an integer.

int		CameraSerial(int cameraIndex);

Description

• This function returns the corresponding camera's serial number.

Function Input

• Camera index (int)

Function Output

• Camera serial number (int)

C++ Example

//== Displaying all connected cameras ==//
int totalCamera = CameraCount();

printf("Detected Cameras Serial Numbers:\n"); 
for (int i = 0; i < totalCamera; i++)
{
	printf("\t%d\n", CameraSerial(i));
}

CameraObjectCount

Returns a total number of objects detected by a camera in the current frame.

int		CameraObjectCount( int cameraIndex );

Description

• This function returns a total number of centroids detected by a camera.

• A centroid is defined for every group of contiguous pixels that forms a shape that encloses the thresholded pixels.

• The size and roundness filter (cCameraGroupFilterSettings) is not applied in this data.

Function Input

• Camera index (int)

Function Output

• Number of centroids (int)

C++ Example

for (int i = 0; i < CameraCount(); i++)
{
	int centroidcount = CameraObjectCount(i);
	printf("Camera #%d detected centroids: %d\n", i, centroidcount);
}

CameraObject

Returns 2D location of the centroid as seen by a camera.

bool     CameraObject( int cameraIndex, int objectIndex, float& x, float& y );

Description

• This function saves 2D location of the centroid as detected by a camera's imager.

• Returns true if the function successfully saves the x and y locations.

Function Input

• Camera index (int)

• Object index (int)

• Declared variables for saving x and y (float)

Function Output

• True/False (bool)

C++ Example

int cameracount = CameraCount();

for (int i = 0; i < cameracount; i++)
{
	float x, y;
	int centroidcount = CameraObjectCount(i);
	printf("Camera #%d detected centroids: %d\n", i, centroidcount);

	for (int j = 0; j < centroidcount; j++)
	{
		if ( CameraObject(i, j, x, y) )
		{
			printf("\t#%d\t(%.2f, %.2f)\n", j, x, y);
		}
	}
}

CameraObjectPredistorted

Retrieve the pre-distorted object location in the view of the camera.

bool	CameraObjectPredistorted( int cameraIndex, int objectIndex, float& x, float& y );

Description

• This function saves the predistorted 2D location of a centroid.

• This data indicates where the camera would see a marker if there were no effects from lens distortions. For most of our cameras/lenses, this location is only a few pixels different from the distorted position obtained by the CameraObject function.

• Returns true when the values are successfully saved.

Function Input

• Camera index (int)

• Object (centroid) index (int)

• Declared variable for saving x location (float)

• Declared variable for saving y location (float)

Function Output

• True/False (bool)

C++ Example

for (int i = 0; i < CameraCount(); i++)
{
	float x, y, pdx, pdy;

	int centroidcount = CameraObjectCount(i);
	printf("Camera #%d detected centroids: %d\n", i, centroidcount);

	for (int j = 0; j < centroidcount; j++)
	{
		CameraObject(i, j, x, y);
		CameraObjectPredistorted(i, j, pdx, pdy);
		printf("\t#%d\t(%.2f, %.2f)\tPredistorted:\t(%.2f, %.2f)\n", j, x, y, pdx, pdy);
	}
}

SetCameraProperty

Configures the value of a camera property.

bool		SetCameraProperty( int cameraIndex, const std::wstring& propertyName, const sPropertyValue& value );

Description

• This function sets camera properties for a camera device specified by its index number.

• A false return value indicates the function did not complete the task.

• Each of the video types is indicated with the following integers. Supported video types may vary for different camera models. Please check the Data Recording page for more information on which image processing modes are available in different models.

• Segment Mode: 0

• Raw Grayscale Mode: 1

• Object Mode: 2

• Precision Mode: 4

• MJPEG Mode: 6

• Valid exposure ranges depend on the framerate settings:

• Prime series and Flex 13: 1 ~ maximum time gap between the frames, which is approximately (1 / framerate) - 200 microseconds with about 200 microseconds gap for protection.

• Valid threshold ranges: 0 - 255

Function Input

• Camera index (int)

• Name of the propety to set (const std::wstring&)

• For more information on the camera settings, refer to the Devices pane page.

Function Output

• True/False (bool)

Full Frame Grayscale Decimation

In this section:

SetCameraGrayscaleDecimation

Sets frame rate decimation ratio for processing grayscale images.

bool		SetCameraGrayscaleDecimation(int cameraIndex, int value);

Description

• This feature is available only in Flex 3 and Trio/Duo tracking bars, and has been deprecated for other camera models.

• This functions sets the frame decimation ratio for processing grayscale images in a camera.

• Depending on the decimation ratio, a fewer number of grayscale frames will be captured. This can be beneficial when looking to reduce the processing loads.

• Supported decimation ratios: 0, 2, 4, 6, 8. When the decimation setting is set to 4, for example, a camera will capture one grayscale frame for 4 frames of the tracking data.

• Returns true when it successfully sets the decimation value.

Function Input

• Camera index (int)

• Decimation value (int)

Function Output

• True/False (bool)

C++ Example

//== Introducing frame decimation to reference cameras ==//
for (int i = 0; i < CameraCount(); i++)
{
	if (CameraVideoType(i) == 1 ||CameraVideoType(i) == 6)
	{
		SetCameraGrayscaleDecimation(i, 2);
		printf("Camera #%d grayscale video frame decimation: %d\n",
					i, CameraGrayscaleDecimation(i));
	}
}

CameraGrayscaleDecimation

Retrieves the configured grayscale image frame rate decimation ratio of a camera.

int		CameraGrayscaleDecimation(int cameraIndex);

Description

• This feature is available only in Flex 3 and Trio/Duo tracking bars, and it has been deprecated for other camera models.

• This function returns grayscale frame rate decimation ratio of a camera.

• Valid decimation ratios are 0, 2, 4, 8. When the decimation setting is set to 4, for example, a camera will capture one grayscale frame for 4 frames of the tracking data.

• Grayscale images require more load on data processing. Decimate the grayscale frame images and capture the frames at a lower frame rate to reduce the volume of data.

Function Input

• Camera index (int)

Function Output

• Decimation ratio (int)

C++ Example

//== Checking grayscale decimation ==//
for (int i = 0; i < CameraCount(); i++)
{
	if (CameraVideoType(i) == 1 ||CameraVideoType(i) == 6)
	{
		printf("Camera #%d grayscale video frame decimation: %d\n",
					i, CameraGrayscaleDecimation(i));
	}
}

CameraIsContinuousIRAvailable

Checks if the continuous IR mode is supported.

bool		CameraIsContinuousIRAvailalbe(int cameraIndex);

Description

• This function checks whether the continuous IR illumination mode is available in the camera model.

• In the continuous IR mode, the IR LEDs will not strobe but will illuminate continuously instead.

• Continuous IR modes are available only in the Flex 3 camera model and the Duo/Trio tracking bars.

• Returns true if continuous IR mode is available.

Function Input

• Camera index (int)

Function Output

• True / False (bool)

C++ Example

//== Configuring Continuous IR ==//
int totalCamera = CameraCount();

for (int i = 0; i < totalCamera; i++)
{
	//== Checking if the mode is available ==//
	if (CameraIsContinuousIRAvailable(i))
	{
		if (CameraContinuousIR(i))
		{
			printf("Continuous IR enabled already\n");
		}
		else
		{
			printf("Enabling continuous IR\n");
			CameraSetContinuousIR(i, true);
		}
	}
	else
	{
		printf("Continuous IR is not available\n");
	}
}

CameraSetContinuousIR

Enables or disables continuous IR, if the camera supports it.

bool		CameraSetContinuousIR(int cameraIndex, bool enable);

Description

• This function enables, or disables, continuous IR illumination in a camera.

• Continuous IR mode outputs less light when compared to Strobed (non-continuous) illumination, but this mode could be beneficial in situations where there are extraneous IR reflections in the volume.

• Use the CameraIsContinuousIRAvailable function to check if the camera supports this mode.

Function Input

• Camera index (int)

• A Boolean argument for enabling (true) or disabling (false)

Function Output

• True / False (bool)

C++ Example

int totalCamera = CameraCount();

//== Configuring Continuous IR ==// 
for (int i = 0; i < totalCamera; i++)
{
	if (CameraIsContinuousIRAvailable(i))
	{
		//== Checking if already enabled ==//
		if (CameraContinuousIR(i))
		{
			printf("Coninuous IR enabled already\n");
		}
		else
		{
			printf("Enabling continuous IR\n");
			CameraSetContinuousIR(i, true);
		}
	}
	else
	{
		printf("Continuous IR is not available\n");
	}
}

CameraContinuousIR

Checks if the continuous IR mode is enabled.

bool		CameraContinuousIR(int cameraIndex);

Description

• This function checks if the continuous IR mode is enabled or disabled in a camera.

• Returns true if the continuous IR mode is already enabled.

Function Input

• Camera index (int)

Function Output

• True / False (bool)

C++ Example

int totalCamera = CameraCount();

//== Configuring Continuous IR ==// 
for (int i = 0; i < totalCamera; i++)
{
	if (CameraIsContinuousIRAvailable(i))
	{
		//== Checking if already enabled ==//
		if (CameraContinuousIR(i))
		{
			printf("Continuous IR enabled already\n");
		}
		else
		{
			printf("Enabling continuous IR\n");
			CameraSetContinuousIR(i, true);
		}
	}
	else
	{
		printf("Continuous IR is not available\n");
	}
}

SetCameraSystemFrameRate

Sets the camera frame rate.

bool		SetCameraSystemFrameRate(int framerate);

Description

• This function sets the master frame rate for the camera system.

• Returns true if it successfully adjusts the settings.

• Note that this function may assign a frame rate setting that is out of the supported range. Check to make sure the desired frame rates are supported.

Function Input

• Frame rate (frames/sec)

Function Output

• True/False (bool).

C++ Example

//== Changing frame rate of all cameras ==//
int framerate = 120;

for (int i = 0; i < CameraCount(); i++)
{
	SetCameraSystemFrameRate(i, framerate);
	printf("\t%d\tFrame Rate: %d", CameraSerial(i), CameraSystemFrameRate(i));
}

CameraSystemFrameRate

Retrieves the the current master system frame rate.

int		CameraSystemFrameRate();

Description

• This function returns the master frame rate of a camera system.

Function Input

• none

Function Output

• Camera frame rate (int)

C++ Example

//== Checking camera settings ==//
int totalCamera = CameraCount();

for (int i = 0; i < totalCamera; i++)
{
	printf("Camera #%d:\tFPS: %d\n",
		i, CameraSystemFrameRate(i) );
}

Measured Camera System Frame Rate

In this section:

CameraTemperature

Measures the image board temperature of a camera.

float		CameraTemperature(int cameraIndex);

Description

• This function returns the temperature (in Celsius) of a camera's image board.

• Temperature sensors are featured only in Prime series camera models.

Function Input

• Camera index (int)

Function Output

• Image board temperature (float)

C++ Example

//== Temperature settings ==//
for (int i = 0; i < CameraCount(); i++)
{
	printf("Camera #%d:\n",i);
	printf("\tImage Board Temperature: %.2f\n", CameraTemperature(i));
	printf("\tIR Board Temperature: %.2f\n", CameraRinglightTemperature(i));
	printf("\n");
}

CameraRinglightTemperature

Measures the IR LED board temperature of a camera.

float		CameraRinglightTemperature(int cameraIndex);

Description

• This function returns temperature (in celsius) of a camera's IR LED board.

• Temperature sensors are featured only in Prime series camera models.

Function Input

• Camera index (int)

Function Output

• IR LED board temperature (float)

C++ Example

//== Temperature settings ==//
for (int i = 0; i < CameraCount(); i++)
{
	printf("Camera #%d:\n",i);
	printf("\tImage Board Temperature: %.2f\n", CameraTemperature(i));
	printf("\tIR Board Temperature: %.2f\n", CameraRinglightTemperature(i));
	printf("\n");
}

SetCameraAGC

Enables or disables automatic gain control.

bool		SetCameraAGC(int cameraIndex, bool enable);

Description

• This function enables or disables automatic gain control (AGC).

• Automatic Gain Control feature adjusts the camera gain level automatically for best tracking.

• AGC is only available in Flex 3 cameras and Duo/Trio tracking bars.

• Returns true when the operation completed successfully.

Function Input

• Camera index (int)

• Enabled (true) / disabled (false) status (bool)

Function Output

• True/False (bool)

C++ Example

//== Setting the Automatic Exposure Control ==//
int totalCamera = CameraCount();

for(int i = 0; i < totalCamera; i++)
{
	if(SetCameraAGC(i, true))
	{
		printf("Camera #%d AGC enabled");
	}
	else
	{
		printf("AGC not set properly. Check if this is supported.");
	}
}

SetCameraAEC

Enables or disables automatic exposure control.

bool		SetCameraAEC(int cameraIndex, bool enable);

Description

• This function enables or disables Automatic Exposure Control (AEC) for featured camera models.

• This feature is only available in Flex 3 cameras and Duo/Trio tracking bars.

• AEC allows a camera to automatically adjust its exposure setting by looking at the properties of the incoming frames.

• Returns true if the operation was successful.

Function Input

• Camera index (int)

• A Boolean argument for enabling (true) or disabling (false) the filter.

Function Output

• True/false (bool)

C++ Example

//== Setting the Automatic Exposure Control ==//
int totalCamera = CameraCount();

for(int i = 0; i < totalCamera; i++)
{
	if(SetCameraAEC(i, true))
	{
		printf("Camera #%d AEC enabled");
	}
	else
	{
		printf("AEC not set properly. Check if this is supported.");
	}
}

CameraImagerGainLevels

Retrieves the total number of gain levels available in a camera.

int		CameraImagerGainLevels(int cameraIndex);

Description

• This function returns a total number of available gain levels in a camera.

• Different camera models may have different gain level settings. This function can be used to check the number of available gain levels.

Function Input

• Camera index (int)

Function Output

• Number of gain levels available (int)

C++ Example

//== Checking number of gain levels ==//
for (int i = 0; i < CameraCount(); i++)
{
	printf("%ls camera has %d gain levels\n", CameraSerial(i),CameraImagerGainLevels(i));
}

Camera Masking

In this section:

ClearCameraMask

Clears masking from camera's 2D view.

bool		ClearCameraMask(int cameraIndex);

Description

• This function clears existing masks from the 2D camera view.

• Returns true when it successfully removes pixel masks.

Function Input

• Camera index (int)

Function Output

• True / False (bool)

C++ Example

//== Clearing existing masks for all cameras ==//
int totalCamera = CameraCount();

for (int i = 0; i < totalCamera; i++)
{
    ClearCameraMask(i);
}

SetCameraMask

bool	SetCameraMask( int cameraIndex, unsigned char* buffer, int bufferSize );

Description

• This function allows a user-defined image mask to be applied to a camera.

• A mask is an array of bytes, one byte per mask pixel block.

• Returns true when masks are applied.

Function Input

• Camera index (int)

• Buffer

• BufferSize

Function Output

• True / False (bool)

C++ Example

unsigned char* maskBuffer = nullptr;
int bufferSize = 0;
int cameraCount = CameraCount();

// Retrieve the mask for each camera, perform a simple edit on it, then set it.
for( int i = 0; i < cameraCount; ++i )
{
   int maskWidth;
   int maskHeight;
   int maskGrid;

   // Mask dimensions for the camera.
   CameraMaskInfo( i, maskWidth, maskHeight, maskGrid );

   int newBufferSize = maskWidth * maskHeight;
   if( bufferSize < newBufferSize )
   {
       delete[] maskBuffer;
       maskBuffer = new unsigned char[newBufferSize];
       bufferSize = newBufferSize;
   }

   // Retrieve the mask now that the receiving buffer is correctly sized.
   CameraMask( i, maskBuffer, bufferSize );

   // Add a mask 'pixel' in the approximate center of the image.
   // Each pixel is actually a grid of maskGrid size.
   int pixelIndex = ( maskHeight / 2 ) * maskWidth + ( maskWidth / 2 );
   maskBuffer[pixelIndex] = 1; // Any non-zero value for the byte will do.

   // Set the mask image on the camera.
   SetCameraMask( i, maskBuffer, bufferSize );
}

CameraMask

bool		CameraMask(int cameraIndex, unsigned char* buffer, int bufferSize);

Description

• This function returns the memory block of the mask.

• One bit per a pixel of the mask.

• Masking pixels are rasterized from left to right and from top to bottom of the camera's view.

Function Input

• Camera index (int)

• Buffer

• Buffer size

Function Output

• True / False (bool)

C++ Example

unsigned char* maskBuffer = nullptr;
int bufferSize = 0;
int cameraCount = CameraCount();

// Retrieve the mask for each camera, perform a simple edit on it, then set it.
for( int i = 0; i < cameraCount; ++i )
{
   int maskWidth;
   int maskHeight;
   int maskGrid;

   // Mask dimensions for the camera.
   CameraMaskInfo( i, maskWidth, maskHeight, maskGrid );

   int newBufferSize = maskWidth * maskHeight;
   if( bufferSize < newBufferSize )
   {
       delete[] maskBuffer;
       maskBuffer = new unsigned char[newBufferSize];
       bufferSize = newBufferSize;
   }

   // Retrieve the mask now that the receiving buffer is correctly sized.
   CameraMask( i, maskBuffer, bufferSize );

   // Add a mask 'pixel' in the approximate center of the image.
   // Each pixel is actually a grid of maskGrid size.
   int pixelIndex = ( maskHeight / 2 ) * maskWidth + ( maskWidth / 2 );
   maskBuffer[pixelIndex] = 1; // Any non-zero value for the byte will do.

   // Set the mask image on the camera.
   SetCameraMask( i, maskBuffer, bufferSize );
}

CameraMaskInfo

bool		CameraMaskInfo(int cameraIndex, int& blockingMaskWidth, int& blockingMaskHeight, int& blockingMaskGrid);

Description

• This function retrieves the width, height, and grid size of the mask for the camera at the given index.

• One byte per pixel of the mask. Masking width * masking height gives the required size of the buffer.

• Returns true when the information is successfully obtained and saved.

Function Input

• Camera index (int)

• Declared variables:

  • Masking width (int)

  • Masking height (int)

  • Masking grid (int)

Function Output

• True / False (bool)

C++ Example

unsigned char* maskBuffer = nullptr;
int bufferSize = 0;
int cameraCount = CameraCount();

// Retrieve the mask for each camera, perform a simple edit on it, then set it.
for( int i = 0; i < cameraCount; ++i )
{
   int maskWidth;
   int maskHeight;
   int maskGrid;

   // Mask dimensions for the camera.
   CameraMaskInfo( i, maskWidth, maskHeight, maskGrid );

   int newBufferSize = maskWidth * maskHeight;
   if( bufferSize < newBufferSize )
   {
       delete[] maskBuffer;
       maskBuffer = new unsigned char[newBufferSize];
       bufferSize = newBufferSize;
   }

   // Retrieve the mask now that the receiving buffer is correctly sized.
   CameraMask( i, maskBuffer, bufferSize );

   // Add a mask 'pixel' in the approximate center of the image.
   // Each pixel is actually a grid of maskGrid size.
   int pixelIndex = ( maskHeight / 2 ) * maskWidth + ( maskWidth / 2 );
   maskBuffer[pixelIndex] = 1; // Any non-zero value for the byte will do.

   // Set the mask image on the camera.
   SetCameraMask( i, maskBuffer, bufferSize );
}

AutoMaskAllCameras

Auto-mask all cameras with additional masking data.

void		AutoMaskAllCameras();

Description

• Auto-mask all cameras.

• This is additive to any existing masking.

• To clear masks on a camera, call ClearCameraMask prior to auto-masking.

Function Input

• none

Function Output

• Auto masks all cameras

SetCameraState

Sets the state for a camera.

bool		SetCameraState(int cameraIndex, eCameraState state);

Description

• This function configures the camera state of a camera. Different camera states are defined in the eCameraState enumeration.

• Returns true when it successfully sets the camera state.

enum eCameraState
{
    Camera_Enabled = 0,
    Camera_Disabled_For_Reconstruction = 1,
    Camera_Disabled = 2,
   };

Function Input

• Camera index (int)

• Camera state (eCameraState)

Function Output

• True / False (bool)

C++ Example

int totalCamera = CameraCount();

//== Disabling all of the cameras from contributing to reconstruction ==//
for (int i = 0; i < totalCamera; i++)
{
	SetCameraState(i, Camera_Enabled);
}

CameraState

Retrieves the current participation state of a camera.

bool		CameraState(int cameraIndex, eCameraState& currentState);

Description

• This function obtains and saves the camera state of a camera onto the declared variables.

• Returns true if it successfully saves configured state.

Function Input

• Camera index (int)

• Declared variable for camera state (eCameraState)

Function Output

• True / False (bool)

C++ Example

//== Checking Camera Status ==//
int totalCamera = CameraCount();
eCameraStates cameraState;

for (int i = 0; i < totalCamera; i++)
{
	//== Checking the Camera Status ==//
	CameraState(i, cameraState);

	if (cameraState == 0) {
		printf("Camera #%d State: Camera_Enabled\n", i);
	}
	else if (cameraState == 1)
	{
		printf("Camera #%d State: Camera_Disabled_For_Reconstruction\n",i );
	}
	else if (cameraState == 2)
	{
		printf("Camera #%d State: Camera_Disabled\n", i);
	}	
}

CameraID

Returns the Camera ID.

int		CameraID(int cameraIndex);

Description

• This function takes in a camera index number and returns the camera ID number.

• Camera ID numbers are the numbers that are displayed on the devices.

• The Camera ID number is different from the camera index number.

  • On Prime camera systems, Camera IDs are assigned depending on where the cameras are positioned within the calibrated volume.

  • On Flex camera systems, Camera IDs are assigned according to the order in which devices connected to the OptiHub(s).

Function Input

• Camera index (int)

Function Output

• Camera ID (int)

C++ Example

int totalCamera = CameraCount();

for(int i = 0; i < totalCamera; i++){
	// Listing Camera Serial, index, and ID
	printf("Camera %d:\tIndex:%d\tID:%d\n", CameraSerial(i), i, CameraID(i)); 
}

CameraFrameBuffer

Fills a buffer with images from camera's view.

bool	CameraFrameBuffer(int cameraIndex, int bufferPixelWidth, int bufferPixelHeight, int bufferByteSpan, int bufferPixelBitDepth, unsigned char* buffer);

Description

• This function fetches raw pixels from a single frame of a camera and fills the provided memory block with the frame buffer.

• The resulting image depends on which video mode the camera is in. For example, if the camera is in grayscale mode, a grayscale image will be saved from this function call.

• For obtaining buffer pixel width and height, you can use the CameraNodeImagerPixelSize property to obtain respective camera resolution.

• Byte span: Byte span is the number of bytes for each row of the frame. In a case of 8-bit pixel images (one byte per pixel), the number of pixels in the frame width will equal to the byte size of the span.

• Buffer pixel bit depth: Pixel bit size for the image buffer that will be stored in the memory. If the imagers on the OptiTrack cameras capture 8-bit grayscale pixels, you will need to input 8 for this input.

• Buffer: make sure enough memory is allocated for the frame buffer. A frame buffer will require memory of at least (Byte span * pixel height * Bytes per pixel) bytes. For example, on a 640 x 480 image with 8-bit black and white pixels, you will need (640 * 480 * 1) bytes allocated for the frame buffer.

• Returns true if it successfully saves the image in the buffer.

Function Input

• Camera index (int)

• Buffer pixel width (int)

• Buffer pixel height (int)

• Buffer byte span (int)

• Buffer pixel bit depth (int)

• Buffer address (unsigned char*)

Function Output

• True / False (bool)

C++ Example

// Sample code for saving frame buffer from a camera (index 0)
int cameraIndex = 0;
int reswidth;
int resheight;
int bytespan;

// Obtaining pixel resolution
CameraPixelResolution(cameraIndex, reswidth, resheight);
printf("Camera #%d:\tWidth:%d\tHeight:%d\n", i, reswidth, resheight);

// Defining span size of the buffer
bytespan = reswidth;

// Allocating memory block for the buffer
unsigned char* frameBuffer = (unsigned char*)std::malloc(bytespan*resheight*1);

bool result = CameraFrameBuffer(cameraIndex, reswidth, resheight, bytespan, 8, frameBuffer);

if (result == true)
{
	printf("Frame Buffer Saved.");
}

CameraFrameBufferSaveAsBMP

Saves image buffer of a camera into a BMP file.

bool		CameraFrameBufferSaveAsBMP(int cameraIndex, const wchar_t* filename);

Description

• This function saves image frame buffer of a camera into a BMP file.

• Video type of the saved image depends on configured camera settings

• Attaches *.bmp at the end of the filename.

• Returns true if it successfully saves the file.

Function Input

• Camera index (int)

• Filename (const wchar_t*)

Function Output

• True / False (bool)

C++ Example

int cameraCount = CameraCount();
std::vector<std::string> filenames(cameraCount);

for (int i = 0; i < cameraCount; ++i)
{
	filenames[i] = "camera" + std::to_string(i) + ".bmp";
	CameraFrameBufferSaveAsBMP(i, filenames[i].c_str());
}

CameraBackproject

Obtains the 2D position of a 3D marker as seen by one of the cameras.

void		CameraBackproject(int cameraIndex, float x, float y, float z, float& cameraX, float& cameraY);

Description

• This function reverts 3D data into 2D data. If you input a 3D location (in meters) and a camera, it will return where the point would be seen from the 2D view of the camera (in pixels) using the calibration information. In other words, it locates where in the camera's FOV a point would be located.

• If a 3D marker is reconstructed outside of the camera's FOV, saved 2D location may be beyond the camera resolution range.

• Respective 2D location is saved in the declared X-Y address, in pixels.

Function Input

• Camera index (int)

• 3D x-position (float)

• 3D y-position (float)

• 3D z-position (float)

• Declared variable for x and y location from camera's 2D view (float)

Function Output

• Void

CameraUndistort2DPoint

Removes lens distortion.

void		CameraUndistort2DPoint(int cameraIndex, float& x, float& y);

Description

• This function removes the effect of the lens distortion filter and obtains undistorted raw x and y coordinates (as seen by the camera) and saves the data in the declared variables.

• Lens distortion is measured during the camera calibration process.

• If you want to re-apply the lens distortion filter, use the CameraDistort2DPoint function.

Function Input

• Camera index (int)

• Declared variables for x and y position in respect to camera's view (float)

Function Output

• Void

C++ Example

// Reflection detected at (125, 213) from 2D view of a camera 1.
int x = 125;
int y = 213;
int cameraIndex = 1;

// Saving raw, undistorted, coordinates as seen by the imager
CameraUndistort2DPoint(cameraIndex, x, y);

CameraDistort2DPoint

Reapplies the lens distortion model.

void		CameraDistort2DPoint(int cameraIndex, float& x, float& y);

Description

• This function restores the default model for accommodating effects of the camera lens.

• Note all reported 2D coordinates are already distorted to accommodate for effects of the camera lens. Use the CameraUndistort2DPoint function when working with coordinates that are undistorted .

• This can be used to obtain raw data for 2D points that have been undistorted using the CameraUndistort2DPoint function.

Function Input

• Camera index (int)

• Declared variables for x and y position in respect to camera's view (float)

Function Input

• Void

C++ Example

// Reflection detected at (125, 213) from 2D view of a camera 1.
int x = 125;
int y = 213;
int cameraIndex = 1;

// Saving raw, undistorted, coordinates as seen by the imager.
CameraUndistort2DPoint(cameraIndex, x, y);

// Process undistorted x y coordinates..

// Apply the distortion back again
CameraDistort2DPoint(cameraIndex, x, y);

CameraRay

Obtains 3D vector from a camera to a 3D point.

bool		CameraRay(int cameraIndex, float x, float y, 
				float& rayStartX, float& rayStartY, float& rayStartZ, 
				float& rayEndX, float& rayEndY, float& rayEndZ);

Description

• This function takes in an undistorted 2D centroid location seen by a camera's imager and creates a 3D vector ray connecting the point and the camera.

• Use CameraUndistort2DPoint to undistort the 2D location before obtaining the 3D vector.

• XYZ locations of both the start point and end point are saved into the referenced variables.

• Returns true when it successfully saves the ray vector components.

Function Input

• Camera index (int)

• x location, in pixels, of a centroid (float)

• y location, in pixels, of a centroid (float)

• Three reference variables for X/Y/Z location, in meters, of the start point (float)

• Three reference variables for X/Y/Z location, in meters, of the end point (float)

Function Output

• True / False (bool)

C++ Example

//== Obtaining a 3D vector for centroid detected at (100, 300) on a camera's 2D imager ==//
int targetcam = 0;
float  rayStartX, rayStartY, rayStartZ; //meters
float  rayEndX, rayEndY, rayEndZ; //meters
float x = 100; //pixels
float y = 300; //pixels
CameraUndistort2DPoint(targetcam, x, y);

CameraRay(targetcam, x, y, rayStartX, rayStartY, rayStartZ, rayEndX, rayEndY, rayEndZ);