Motive API: Function Reference

A guide to the functions available in the Motive API.

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.

Important Note:

Some functions are not yet included in the documentation. Please refer to the Motive API header file (MotiveAPI.h) for information on any functions that are not documented here.


Startup / Shutdown

In this section:

Initialize | Shutdown | BuildNumber


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 | SaveProfile


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 | UpdateSingleFrame | FlushCameraQueues


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.

Update vs. UpdateSingleFrame:

In general, the Update() function is sufficient to capture frames lost when a client application stalls momentarily. This function disregards accumulated frames and serves only the most recent frame data, which means the client application will miss the previous frames.

For situations where it is critical to ensure every frame is captured and the Update() cannot be called in a timely fashion, use theUpdateSingleFrame()function ensures that the next consecutive frame is updated each time the function is called.

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

Update vs. UpdateSingleFrame:

In general, the Update() function is sufficient to capture frames lost when a client application stalls momentarily. This function disregards accumulated frames and serves only the most recent frame data, which means the client application will miss the previous frames.

For situations where it is critical to ensure every frame is captured and the Update() cannot be called in a timely fashion, use theUpdateSingleFrame()function ensures that the next consecutive frame is updated each time the function is called.

  • 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 | LoadCalibrationFromMemory | CameraExtrinsicsCalibrationFromMemory | StartCalibrationWanding | CalibrationState | CalibrationCamerasLackingSamples | CameraCalibrationSamples | CancelCalibration | StartCalibrationCalculation |CurrentCalibrationQuality | ApplyCalibrationCalculation | SetGroundPlane | TranslateGroundPlane


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 | StreamVRPN


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

Enables or disables data stream into VRPN.

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


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 | MarkerID | MarkerResidual | MarkerCameraCentroid


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 | CreateRigidBody | SetRigidBodyProperty | ClearRigidBodies | LoadRigidBodies | AddRigidBodies | SaveRigidBodies | RigidBodyID | RigidBodyName | IsRigidBodyTracked | RemoveRigidBody | SetRigidBodyEnabled | RigidBodyEnabled | RigidBodyTranslatePivot | RigidBodyResetOrientation | RigidBodyMarkerCount | RigidBodyMarker | RigidBodyUpdateMarker | RigidBodyReconstructedMarker | RigidBodyMeanError |


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 | RigidBodyRefineSample | RigidBodyRefineState | RigidBodyRefineProgress | RigidBodyRefineInitialError | RigidBodyRefineResultError | RigidBodyRefineApplyResult | RigidBodyRefineReset |


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 | CameraGroupCount | CameraGroup | CameraSerial | CameraObjectCount | CameraObject | CameraObjectPredistorted | SetCameraProperty


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