Motive API Camera Calibration
Sample code with instructions on using Motive API functions to calibrate a camera system.
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 Motive API: Function Reference page.
Masking
Auto-Masking
Auto-Masking is done directly using the AutoMaskAllCameras 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 CameraMask 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 ClearCameraMask function is used to clear existing masks from the 2D camera view. It returns true when it successfully removes pixel masks.
Masking is always additive through the API unless preceded by the ClearCameraMask command.
Set Camera Mask
The SetCameraMask 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 CalibrationState 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:
WandLarge
CW-500 (500mm)
WandStandard
Legacy (400mm)
WandSmall
CW-250 (250mm)
WandCustom
Custom Wand
WandMicron
Micron Series
Start Wanding
The StartCalibrationWanding function begins the calibration wanding process, collecting samples until the StartCalibrationCalculation function is called.
The CalibrationCamerasLackingSamples function shows which cameras need more samples to obtain the best calibration. When this function returns an empty vector, then there are sufficient samples to begin calculating the calibration.
Start Calculation
The StartCalibrationCalculation function ends the wanding phase and begins calculating the calibration from the samples collected.
Calibration State
Use the CalibrationState function to monitor progress through the following states:
Initialized: the calibration process has started.
Wanding: the system is collecting samples.
WandingComplete: the system has finished collecting samples. This state is set automatically when the StartCalibrationCalculation function is called.
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
Once the Calibration State is "Phase4," use the ApplyCalibrationCalculation function to apply the newly calculated calibration to the cameras.
Cancel Calibration
The CancelCalibration function stops the calibration process. Use this when a calibration error occurs or any other time you wish to stop the calibrating.
Evaluate Calibration
Use the CurrentCalibrationQuality function to score the calibration quality on a scale from 0-5, with 5 being the highest quality.
Ground Plane
Set the ground plane by calling the SetGroundPlane function. When called, the camera system will search for 3-markers that resemble a calibration square. Once found, the system will use the inputted vertical offset value to configure the ground plane.
Last updated