# Multi-Device Calibration Specification

`MultiDeviceCalibration` estimates where your OAK devices are and which way they face relative to one another. This page covers
device placement, test methodology and measured accuracy. For node configuration, code examples and result checks, see the
[MultiDeviceCalibration node
guide](https://docs.luxonis.com/software-v3/depthai/depthai-components/host_nodes/multi_device_calibration.md).

The tested setups cover two ways to arrange your devices:

### Outside-in

Place devices around a shared area and point them inward. Use this setup to view a work cell from several sides, cover a room from
its corners, or capture an object in 3D.

### Inside-out

Place devices on one mount and point them in different directions, with overlapping views between neighbors. Use this setup for a
360° view from a robot, pole or ceiling mount.

## Setup requirements

The accuracy figures below apply when each pair of devices you calibrate meets these conditions. An optical axis is the direction
a camera points; the angle below measures how differently the two cameras are aimed.

Shared view (overlap) is the part of each image that is also visible in the other camera, excluding areas hidden behind objects.
Use the smaller of the two percentages. For example, if 40 % of camera A's image is visible in B, but only 25 % of B's image is
visible in A, the overlap is 25 %.

| Condition | Outside-in | Inside-out |
| --- | --- | --- |
| Difference in camera pointing directions | < 45° | < 45° |
| Shared view (overlap) | ≥ 30 % | ≥ 30 % |
| Distance between devices | 0.25–4.5 m (tested) | 0.08–1 m (tested) |
| Mounting | Secure mounts; devices stay still during capture | Secure mounts; devices stay still during capture |

### Place devices where they can see useful detail

#### Outside-in

Aim the devices at a shared area containing furniture, objects or equipment. An empty floor or blank wall offers few details to
match between images.

Calibration can still succeed below 30 % overlap or above 45° when both views contain enough shared detail, but the stated
accuracy figures apply only within the setup limits.

#### Inside-out

 * Tilt the mount so each view contains furniture, objects or a floor with visible detail.
 * For cameras that see about 75° across horizontally, about 40° or less between neighboring pointing directions is a useful
   starting point. Check that the actual shared view meets the table's requirement.
 * Calibrate each neighboring pair separately, then combine the relationships into one calibration. See [Calibrating more than two
   devices](#Calibrating%20more%20than%20two%20devices) for the comparison with calibrating all devices together.

For either setup, if you fall outside the table's limits, see [Results beyond the tested setup
limits](#Results%20beyond%20the%20tested%20setup%20limits) before relying on the accuracy figures.

## Test methodology

### Test configuration

The tests use two devices, each with a stereo camera pair, within the setup limits above. Each run uses 10 synchronized image
groups: one image from every registered camera in each group. The tests assume exact factory calibration within each device;
errors in that calibration can affect your results.

The figures describe calibration between devices, rather than the accuracy of depth measurements from an individual camera.
Results are reported for each device pair, rather than the combined error across a larger mount.

### What the errors measure

The errors compare the estimated relationship between devices with the reference relationship used in the tests:

 * Rotation error is the difference between the estimated and reference device orientations, in degrees. Orientation includes
   which way a device faces and how it is tilted.
 * Translation error is how far the estimated position is from the reference, in centimeters.
 * Translation error as a percentage divides that position error by the distance between devices. For example, a 1 cm error
   between devices 1 m apart is 1 %.

An entry such as "< 0.17° for 90 % of cases" means nine out of ten test cases had a smaller rotation error. It is not a maximum
error for every run.

## Results

### Accuracy within the setup limits

A result meets the accuracy target when its rotation error is at most 1° and its translation error is at most 5 % of the distance
between devices. Both conditions must hold. For devices 1 m apart, the position limit is 5 cm. This target labels the test results
using the reference relationship; the [result
checks](https://docs.luxonis.com/software-v3/depthai/depthai-components/host_nodes/multi_device_calibration.md) help select
results when that reference is unavailable.

#### Before score checks

Start with every test case, including attempts where calibration did not complete. The percentages below are measured against all
test cases.

| Outcome before score checks | Outside-in | Inside-out |
| --- | --- | --- |
| Calibration completed | 98.2 % | 98.1 % |
| Met the accuracy target | 95.5 % | 88.1 % |

#### After score checks

Keep a result only if calibration completed, `sampsonError ≤ 5e-4` and `dataConfidence ≥ 0.85`. These are the accepted results;
the remaining test cases are rejected.

The first row shows how many test cases were kept. The second shows how often those kept results met the accuracy target.

| Outcome after score checks | Outside-in | Inside-out |
| --- | --- | --- |
| Test cases kept, as a share of all tests | 86 % | 80 % |
| Kept results that met the accuracy target | 99.8 % | 92.6 % |

The error tables below use the same two stages: before score checks and after score checks. Each percentage applies independently
to the named error measure.

#### Rotation error

| Cases below this error | Outside-in | Inside-out |
| --- | --- | --- |
| 50 % before score checks | < 0.03° | < 0.04° |
| 90 % before score checks | < 0.17° | < 0.17° |
| 95 % before score checks | < 0.29° | < 0.26° |
| 90 % after score checks | < 0.11° | < 0.15° |

#### Position error

| Cases below this error | Outside-in | Inside-out |
| --- | --- | --- |
| 50 % before score checks | < 0.2 cm | < 0.3 cm |
| 90 % before score checks | < 1.2 cm | < 1.2 cm |
| 90 % after score checks | < 0.9 cm | < 1.1 cm |

#### Position error relative to device spacing

| Cases below this error | Outside-in | Inside-out |
| --- | --- | --- |
| 50 % before score checks | < 0.2 % | < 1.3 % |
| 90 % before score checks | < 1.0 % | < 5.1 % |

> **Why relative position errors differ**
> Inside-out devices are often only 15–30 cm apart. A 1 cm position error is 5 % at 20 cm spacing, but only 1 % at 1 m spacing. Similar errors in centimeters can therefore mean different percentage errors.

### Results beyond the tested setup limits

These charts show how often two stereo devices met the same accuracy target as the pointing angle and shared view changed. Each
cell is the percentage of results meeting both the rotation and position limits at that combination of angle and overlap. Gray
cells mean no test samples were available, rather than a 0 % success rate.

Outlined cells meet the setup limits. The 20–40 % overlap row includes values both below and above the 30 % minimum, so it is not
outlined. Results beyond these limits vary with the scene and are not guaranteed.

### Calibrating more than two devices

These two-device results do not establish accuracy for a larger group of devices. A separate comparison of pair-by-pair
calibration with calibrating all devices together found that:

 * Calibrating all devices together recovered 36 % of pairs that had failed when calibrated separately.
 * Of the pairs that met the accuracy target when calibrated separately, 22 % missed it when all devices were calibrated together.

For an inside-out setup, calibrate neighboring pairs separately and combine their relationships. Check the combined result in your
application as well.

## When to recalibrate

Keep the devices fixed relative to one another after calibration. Recalibrate if a device moves on its mount, is re-mounted or
receives a knock that could change its position.

Periodically re-run calibration and compare the estimated position and orientation of each device with the saved values. Use the
same reference device and camera origins for both results. Orientation describes which way a device faces; position describes
where it sits relative to the reference device.

Repeated runs in the tests differed by about 0.02° in orientation and 0.1–0.6 % of the distance between devices in position. For
devices 1 m apart, that position difference is about 1–6 mm. These figures describe how much repeated estimates vary, rather than
their error against the true positions. A larger change is a reason to check the mounts, scene and calibration quality; it does
not by itself prove that a device moved.

### Need assistance?

Head over to [Discussion Forum](https://discuss.luxonis.com/) for technical support or any other questions you might have.