.mcal XML Calibration Files

An overview of the data available in the .mcal calibration file.

Overview

Beginning with Motive 3.2, calibration data is stored in an XML file with the file extension .mcal. XML is a human-readable format that can be imported for use in end-user applications.

This page defines the properties in the .mcal file that could be used in third-party applications.

Properties in the calibration file that are not relevant for use outside of Motive are listed and noted as such. These properties may be used by OptiTrack Support for troubleshooting.

Camera Serial

<Camera Serial="M21614">

The serial number of the camera. In Motive, this information is located in the Camera Details section of the Camera Properties.

Camera Properties

<Properties CameraID="1" ImagerIndex="00" Exposure="250" Threshold="200" Intensity="15" ContinuousIR="0" VideoType="2" FrameRate="120" FrameDecimation="0" GrayscaleDecimation="0" JPEGQua="25" IRFilter="1" AutoGainControl="0" AutoExposureControl="0" HighPower="0" Orientation="0.000000000000000" ImagerGain="0" Enabled="1" EnabledForRecording="1"/>

Properties related to the specified camera, as defined in the Camera Properties pane in Motive.

Camera ID

The camera number assigned by Motive. In the Properties pane, this is shown in the Number field.

ImagerIndex

This value corresponds to the letter prefix in the device serial number, when present. Pre-set values are used for USB-connected devices.

Camera Type	Prefix	Value
Prime Cameras	M	00
USB Cameras	None	00
Tracking Bar Cameras Primary	None	01
Tracking Bar Cameras Secondary	None	02
Tracking Bar Cameras Tertiary	None	03
OptiTrack IO X Duo & Trio Device Break-out Connectors	None	0F
eSync Devices	ES	10
Golftec Cameras	GT	20
Color Cameras	C	30
Active Devices	A	40
Leyard Cameras	L	50

Exposure

The amount of time, in microseconds, that the camera exposes per frame.

Threshold

The minimum brightness required for a camera to detect a pixel. All pixels below the stated threshold will be ignored.

Intensity

This is a legacy setting related to LED power.

ContinuousIR

Indicates whether the camera's infrared lights are set to strobe (0) or to remain on continuously (1).

VideoType

Indicates the video mode of the camera.

Value	Video Mode
2	Object
4	Precision
1	Grayscale
6	MJPEG

FrameRate

The camera system frame rate.

FrameDecimation

Indicates the ratio of frames displayed per total frames captured.

Frame Decimation is not supported in all devices.

FrameDecimation Value	Frames displayed : Frames Captured
0	1:1
3	1:4
7	1:8
15	1:16

GrayscaleDecimation

Indicates the ratio of frames displayed per total frames captured when in Grayscale mode.

Grayscale decimation is not supported in all devices.

GrayscaleDecimation Value	Frames displayed : Frames Captured
0	1:1
2	1:4
4	1:16

JPEGQua

For cameras in MJPEG mode, this value indicates the quality of the video recording.

Value	Quality Level
25	Minimum
50	Low
75	Medium
100	High

IRFilter

Indicates whether the camera is set to view infrared spectrum (0) or visible (1) light.

AutoGainControl

This is a legacy property that no longer affects the system calibration.

AutoExposureControl

This is a legacy property that no longer affects the system calibration.

HighPower

Indicates if high power mode is on (1) or off (0) for applicable cameras.

High power mode is only available on Flex 3 and Slim3u USB cameras when used with an OptiHub2.

Orientation

Indicates the angle of the camera's view. This property can be adjusted in Motive from the Camera Settings menu in the Cameras View of the Viewport.

ImagerGain

Indicates the imager gain level for the selected camera. Gain settings can be adjusted to amplify or diminish the brightness of the image.

The valid range for gain values in the calibration file is 0 - 7. In the Motive user interface, gain values are increased by 1 for a more user-friendly experience. Thus, a gain of 3 in the .mcal file will show as a gain of 4 in Motive.

Enabled

Indicates whether the camera is enabled (1) or disabled (0) from contributing to the reconstruction of 3D data, when recording in object mode.

EnabledForRecording

Indicates whether the Reconstruction setting is enabled (1) or not (0).

Attributes

<Attributes Revision="31" Model="0" Group="0" ImagerPixelWidth="1280" ImagerPixelHeight="1024"/>

These values are found in the Details section of the Camera Properties in Motive.

Revision

Internal reference information for the camera.

Model

The internal camera model number.

Group

The camera group number that the selected camera is in.

ImagerPixelWidth

Defines the center point of the imager on the x-axis.

ImagerPixelHeight

Defines the center point of the imager on the y-axis.

Intrinsic Values

<IntrinsicStandardCameraModel LensCenterX="637.832275390625000" LensCenterY="510.441009521484375" HorizontalFocalLength="1201.796875000000000" VerticalFocalLength="1203.632812500000000" k1="0.107947303735803" k2="-0.099437290976564" k3="-0.000059653579376" TangentialX="-0.0008229074672L75" TangentialY="0.000262822252969"/>

Intrinsic values are fixed characteristics of the lens and are used to adjust for lens distortion. These values are not displayed in Motive.

The calibration file contains two types of intrinsic values:

• OptiTrack Internal Model. Values optimized for Motive's internal calibration calculation. This model is not applicable for use in other contexts.

• Standard Camera Model. Standardized values that provide accurate results when exported to the OpenCV model.

LensCenterX

The location of the lens center on the imager, on the X axis.

LensCenterY

The location of the lens center on the imager, on the Y axis.

HorizontalFocalLength

The Focal Length of the imager along the Y axis, in pixels.

VerticalFocalLength

The Focal Length of the imager along the X axis, in pixels.

Distortion: K1 / K2 / K3 Values

K values control the amount of radial distortion applied to the image.

Tangential X / Y

Tangential values account for the distortion that occurs when the imager and the lens are not aligned in parallel. TangentialX is the amount of tilt off the X axis, while TangentialY is the amount of tilt off the Y axis.

How to Use Intrinsics Parameters

Our camera parameters model the inverse of the lens distortion, so they can be used to go from points in the distorted images to points in the undistorted image. The sample code, below, demonstrates how.

To go from rays to points in the distorted image, find an approximated inverse to this function.

# The following function shows how to go from points in a distorted image to
# points in an undistorted image.
#
# If you want to go from rays to points in the distorted image, you need to
# create an approximate inverse to this function.

def undistort_point(point, intrinsics):
    # Convert a point in the distorted image to a point in the undistorted image
    u, v = point
    fx, fy, cx, cy, k1, k2, tx, ty, k3 = intrinsics

    # (u, v) is a point in the distorted image

    x = (u - cx) / fx
    y = (v - cy) / fy

    r2 = x*x + y*y
    r4 = r2*r2
    r6 = r2*r4

    k_rad = (1.0 + k1*r2 + k2*r4 + k3*r6)

    xp = x*k_rad + 2*tx*x*y + ty*(r2 + x*x)
    yp = y*k_rad + 2*ty*x*y + tx*(r2 + y*y)

    u_out = fx * xp + cx
    v_out = fy * yp + cy

    # (u_out, v_out) is the corresponding point in the undistorted image
    return (u_out, v_out)

Extrinsic Values

<Extrinsic X="1.221071839332581" Y="1.693764686584473" Z="-0.834836781024933" OrientMatrix0="-0.684483869006766" OrientMatrix1="-0.344133882888445" OrientMatrix2="0.642692542136324" OrientMatrix3="0.188509695729104" OrientMatrix4="0.768044864618728" OrientMatrix5="0.612022205927955" OrientMatrix6="-0.704234284656498" OrientMatrix7="0.540073102997105" OrientMatrix8="-0.460841746951629"/>

Extrinsic values define the physical location of the camera. In Motive, the position values are shown in the Details section of Camera Properties.

Position: X / Y / Z

The camera's location in X/Y/Z coordinates.

Rotation: OrientMatrix 0 - 8

Values that comprise the rotation matrix where the camera's rotation values are stored. Motive uses Row Major rotation matrices.

Camera Software Filters

<CameraSoftwareFilters FilterLevel="2" MarkerMinSize="4" MarkerMaxSize="3000" MarkerMinRoundness="0.600000023841858"/>

Camera Software filter properties are found on the Settings Panel > Live Pipeline > Camera tab. Some are advanced settings.

FilterLevel

Indicates the Filter Type to apply to a 2D object for it to be included in the Point Cloud reconstruction. Possible choices are Size & Roundness (2). or None (0).

MarkerMinSize

The minimum pixel size for a 2D object to be included in the Point Cloud reconstruction.

MarkerMaxSize

The maximum pixel size for a 2D object to be included in the Point Cloud reconstruction.

MarkerMinRoundness

The minimum circularity threshold a 2D object must meet to be included in the Point Cloud reconstruction.

Camera Hardware Filters

<CameraHardwareFilters GrayscaleFloor="48" ObjectMargin="2" ObjectSkew="64" AspectTolerance="64" AspectBase="1" AspectStep="1" ROIIntrusion="1" ROIGuardBand="0.500000000000000"/>

Camera Hardware filter properties are found on the Settings Panel > Live Pipeline > Camera tab. All are advanced settings.

GrayscaleFloor

The pixel intensity of the grayscale floor.

ObjectMargin

The minimum number of pixels required between objects before they begin to overlap.

ObjectSkew

The number of pixels a 2D object is allowed to lean.

AspectTolerance

The maximum allowable aspect tolerance to process a 2D object (width:height).

AspectBase

The allowable aspect tolerance for very small objects.

Aspect Step

The rate at which the aspect tolerance relaxes as object size increase.

RIOIntrusion

Indicates whether the intrusion band setting is on (1) or off (0).

RIOGuardBand

The size of the guard region beyond the object margin for neighbor detection. Corresponds to the Intrusion Band property.

Continuous Calibration

<Calibration PartitionID="1"/>

Camera properties relevant to continuous calibration are found in the Camera Properties pane.

PartitionID

The partition group assigned to the camera for continuous calibration.

Color Camera Properties

<ColorCamera CameraResolution="3" ColorCompressionMode="1" ColorCompression="0.200000002980232" ColorBitRate="0.300000011920929" ColorGamma="0.560000002384186" SubModel="0"/>

Additional properties specific to Color Cameras are located in the Camera Properties pane. These properties are not included in the .mcal file if there are no color cameras present.

CameraResolution

This property sets the resolution of the images captured by the selected camera.

Value	Resolution
0	1080
1	720
2	540
3	272

ColorCompressionMode

The type of compression that will be applied to the captured images.

Value	Compression Mode
1	Constant Bit-Rate
0	Variable Bit-Rate

ColorCompression

The percentage of the maximum data transmission speed to allocate for the camera.

ColorBitRate

The selected color camera's output transmission rate, as a fraction of the maximum (100 MB/s).

This value is applicable only when the ColorCompressionMode is set to 1 (Constant Bit-Rate).

ColorGamma

The amount of gamma correction applied to the selected camera's output image.

SubModel

The camera sub-model, as shown in the Camera details.

Export for OpenCV Use

The .mcal XML file can be exported for use with the OpenCV platform.

• From the File menu, select Export Calibration...

The Motive File menu.

• Browse to the directory where you would like the file exported to.

• The default file name includes the timestamp of the export, not for the calibration itself.

For instructions on importing the .mcal file into your OpenCV project, please consult the documentation for the applicable platform.