> For the complete documentation index, see [llms.txt](https://docs.optitrack.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.optitrack.com/motive/calibration/.mcal-xml-calibration-files.md).

# .mcal XML Calibration Files

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

{% hint style="info" %}
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.
{% endhint %}

## Camera Serial

```xml
<Camera Serial="M21614">
```

The serial number of the camera. In Motive, this information is located in the [Camera Details](/motive-ui-panes/properties-pane/properties-pane-camera.md#camera-details) section of the [Camera Properties](/motive-ui-panes/properties-pane/properties-pane-camera.md).&#x20;

## Camera Properties

{% code overflow="wrap" %}

```xml
<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"/>
```

{% endcode %}

Properties related to the specified camera, as defined in the [Camera Properties](/motive-ui-panes/properties-pane/properties-pane-camera.md) pane in Motive.&#x20;

<details>

<summary>Camera ID</summary>

The camera number assigned by Motive. In the Properties pane, this is shown in the [Number field](/motive-ui-panes/properties-pane/properties-pane-camera.md#number).

</details>

<details>

<summary>ImagerIndex</summary>

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

<table><thead><tr><th>Camera Type</th><th width="134">Prefix</th><th width="100">Value</th></tr></thead><tbody><tr><td>Prime Cameras</td><td>M</td><td>00</td></tr><tr><td>USB Cameras</td><td>None</td><td>00</td></tr><tr><td>Tracking Bar Cameras Primary</td><td>None</td><td>01</td></tr><tr><td>Tracking Bar Cameras Secondary</td><td>None</td><td>02</td></tr><tr><td>Tracking Bar Cameras Tertiary</td><td>None</td><td>03</td></tr><tr><td>OptiTrack IO X Duo &#x26; Trio Device Break-out Connectors</td><td>None</td><td>0F</td></tr><tr><td>eSync Devices</td><td>ES</td><td>10</td></tr><tr><td>Golftec Cameras</td><td>GT</td><td>20</td></tr><tr><td>Color Cameras</td><td>C</td><td>30</td></tr><tr><td>Active Devices</td><td>A</td><td>40</td></tr><tr><td>Leyard Cameras</td><td>L</td><td>50</td></tr></tbody></table>

</details>

<details>

<summary>Exposure</summary>

The amount of time, in microseconds, that the camera exposes per frame.&#x20;

</details>

<details>

<summary>Threshold</summary>

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

</details>

<details>

<summary>Intensity</summary>

This is a legacy setting related to LED power.&#x20;

</details>

<details>

<summary>ContinuousIR</summary>

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

</details>

<details>

<summary>VideoType</summary>

Indicates the video mode of the camera.&#x20;

| Value | Video Mode |
| ----- | ---------- |
| 2     | Object     |
| 4     | Precision  |
| 1     | Grayscale  |
| 6     | MJPEG      |

</details>

<details>

<summary>FrameRate</summary>

The camera system frame rate.&#x20;

</details>

<details>

<summary>FrameDecimation</summary>

Indicates the ratio of frames displayed per total frames captured.&#x20;

Frame Decimation is not supported in all devices.&#x20;

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

</details>

<details>

<summary>GrayscaleDecimation</summary>

Indicates the ratio of frames displayed per total frames captured when in Grayscale mode.&#x20;

Grayscale decimation is not supported in all devices.&#x20;

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

</details>

<details>

<summary>JPEGQua</summary>

For cameras in MJPEG mode, this value indicates the quality of the video recording.&#x20;

| Value | Quality Level |
| ----- | ------------- |
| 25    | Minimum       |
| 50    | Low           |
| 75    | Medium        |
| 100   | High          |

</details>

<details>

<summary>IRFilter</summary>

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

</details>

<details>

<summary>AutoGainControl</summary>

This is a legacy property that no longer affects the system calibration. &#x20;

</details>

<details>

<summary>AutoExposureControl</summary>

This is a legacy property that no longer affects the system calibration. &#x20;

</details>

<details>

<summary>HighPower</summary>

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

{% hint style="info" %}
High power mode is only available on Flex 3 and Slim3u USB cameras when used with an OptiHub2.
{% endhint %}

</details>

<details>

<summary>Orientation</summary>

Indicates the angle of the camera's view. This property can be adjusted in Motive from the [Camera Settings](/motive-ui-panes/viewport.md#camera-settings) menu in the [Cameras View of the Viewport](/motive-ui-panes/viewport.md#cameras-view). &#x20;

</details>

<details>

<summary>ImagerGain</summary>

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

{% hint style="info" %}
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.
{% endhint %}

</details>

<details>

<summary>Enabled</summary>

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

</details>

<details>

<summary>EnabledForRecording</summary>

Indicates whether the [Reconstruction ](/motive-ui-panes/properties-pane/properties-pane-camera.md#reconstruction)setting is enabled (1) or not (0).&#x20;

</details>

## Attributes

{% code overflow="wrap" %}

```xml
<Attributes DeviceName="Prime 13 #21614" Revision="31" Model="0" Group="0" ImagerPixelWidth="1280" ImagerPixelHeight="1024" RinglightType="2" RinglightWavelength="-1" FilterSwitchType="1"/>
```

{% endcode %}

These values are found in the [Details section](/motive-ui-panes/properties-pane/properties-pane-camera.md#camera-details) of the Camera Properties in Motive.

<details>

<summary>DeviceName</summary>

The camera model and numeric portion of the serial number.&#x20;

</details>

<details>

<summary>Revision</summary>

Internal reference information for the camera.&#x20;

</details>

<details>

<summary>Model</summary>

The internal camera model number.&#x20;

</details>

<details>

<summary>Group</summary>

The camera group number that the selected camera is in.

</details>

<details>

<summary>ImagerPixelWidth</summary>

Defines the center point of the imager on the x-axis.&#x20;

</details>

<details>

<summary>ImagerPixelHeight</summary>

Defines the center point of the imager on the y-axis.&#x20;

</details>

## Intrinsic Values

{% code overflow="wrap" %}

```xml
<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"/>
```

{% endcode %}

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

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.&#x20;
* **Standard Camera Model.** Standardized values that provide accurate results when exported to the OpenCV model.&#x20;

<details>

<summary>LensCenterX</summary>

The location of the lens center on the imager, on the X axis.&#x20;

</details>

<details>

<summary>LensCenterY</summary>

The location of the lens center on the imager, on the Y axis.&#x20;

</details>

<details>

<summary>HorizontalFocalLength</summary>

The Focal Length of the imager along the Y axis, in pixels.&#x20;

</details>

<details>

<summary>VerticalFocalLength</summary>

The Focal Length of the imager along the X axis, in pixels.&#x20;

</details>

<details>

<summary>Distortion: K1 / K2 / K3 Values</summary>

K values control the amount of radial distortion applied to the image.&#x20;

</details>

<details>

<summary>Tangential X / Y</summary>

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.&#x20;

</details>

#### 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.&#x20;

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

{% code overflow="wrap" %}

```python
# 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)
```

{% endcode %}

## Extrinsic Values

{% code overflow="wrap" %}

```xml
<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"/>
```

{% endcode %}

Extrinsic values define the physical location of the camera. In Motive, the position values are shown in the Details section of [Camera Properties](/motive-ui-panes/properties-pane/properties-pane-camera.md).

<details>

<summary>Position: X / Y / Z</summary>

The camera's location in X/Y/Z coordinates.&#x20;

</details>

<details>

<summary>Rotation: OrientMatrix 0 - 8</summary>

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

</details>

## Camera Software Filters

{% code overflow="wrap" %}

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

{% endcode %}

Camera Software filter properties are found on the [Settings Panel > Live Pipeline > Camera tab](/motive-ui-panes/settings/settings-live-pipeline.md#camera-advanced-settings). Some are advanced settings.&#x20;

<details>

<summary>FilterLevel</summary>

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).&#x20;

</details>

<details>

<summary>MarkerMinSize</summary>

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

</details>

<details>

<summary>MarkerMaxSize</summary>

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

</details>

<details>

<summary>MarkerMinRoundness</summary>

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

</details>

## Camera Hardware Filters

{% code overflow="wrap" %}

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

{% endcode %}

Camera Hardware filter properties are found on the [Settings Panel > Live Pipeline > Camera tab](/motive-ui-panes/settings/settings-live-pipeline.md#camera-advanced-settings). All are advanced settings.&#x20;

<details>

<summary>GrayscaleFloor</summary>

The pixel intensity of the grayscale floor.&#x20;

</details>

<details>

<summary>ObjectMargin</summary>

The minimum number of pixels required between objects before they begin to overlap.&#x20;

</details>

<details>

<summary>ObjectSkew</summary>

The number of pixels a 2D object is allowed to lean.&#x20;

</details>

<details>

<summary>AspectTolerance</summary>

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

</details>

<details>

<summary>AspectBase</summary>

The allowable aspect tolerance for very small objects.

</details>

<details>

<summary>Aspect Step</summary>

The rate at which the aspect tolerance relaxes as object size increase.&#x20;

</details>

<details>

<summary>RIOIntrusion</summary>

Indicates whether the intrusion band setting is on (1) or off (0).&#x20;

</details>

<details>

<summary>RIOGuardBand</summary>

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

</details>

## Continuous Calibration

{% code overflow="wrap" %}

```xml
<Calibration PartitionID="1"/>
```

{% endcode %}

Camera properties relevant to continuous calibration are found in the [Camera Properties](/motive-ui-panes/properties-pane/properties-pane-camera.md) pane.&#x20;

<details>

<summary>PartitionID</summary>

The partition group assigned to the camera for continuous calibration.&#x20;

</details>

## Color Camera Properties

{% code overflow="wrap" %}

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

{% endcode %}

Additional properties specific to Color Cameras are located in the [Camera Properties](/motive-ui-panes/properties-pane/properties-pane-camera.md) pane. These properties are not included in the .mcal file if there are no color cameras present.

<details>

<summary>CameraResolution</summary>

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

| Value | Resolution |
| ----- | ---------- |
| 0     | 1080       |
| 1     | 720        |
| 2     | 540        |
| 3     | 272        |

</details>

<details>

<summary>ColorCompressionMode</summary>

The type of compression that will be applied to the captured images.&#x20;

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

</details>

<details>

<summary>ColorCompression</summary>

&#x20;The percentage of the maximum data transmission speed to allocate for the camera.&#x20;

</details>

<details>

<summary>ColorBitRate</summary>

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](#colorcompressionmode) is set to 1 (Constant Bit-Rate).

</details>

<details>

<summary>ColorGamma</summary>

The amount of [gamma ](/motive-ui-panes/properties-pane/properties-pane-camera.md#gamma)correction applied to the selected camera's output image.

</details>

<details>

<summary>SubModel</summary>

The camera sub-model, as shown in the Camera details.&#x20;

</details>

## Export for OpenCV Use

The .mcal XML file can be exported for use with the OpenCV platform.&#x20;

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

<figure><img src="/files/W4JO3GFJESQqwN3graH4" alt=""><figcaption><p>The Motive File menu.</p></figcaption></figure>

* Browse to the directory where you would like the file exported to.&#x20;
* The default file name includes the timestamp of the export, not the calibration itself.&#x20;

<figure><img src="/files/NAKr2c6Ui0LUVyoaOm0F" alt="" width="563"><figcaption></figcaption></figure>

{% hint style="info" %}
For instructions on importing the .mcal file into your OpenCV project, please consult the documentation for the applicable platform.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.optitrack.com/motive/calibration/.mcal-xml-calibration-files.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.