MicroStrain MagCal

Suite of library and tools for magnetometer calibration.

Usage

See the following usage guides:

• Application
• Library

Fit Functions

The core functionality of this suite revolves around fitting calibration coefficients. The currently supported fit functions are:

Function	Correction	Coefficients calibrated
Spherical fit	$\mathbf{m}_\text{corr} = s \cdot (\mathbf{m}_\text{raw} - \mathbf{b})$	- Hard-iron offset - Uniform scale factor
Ellipsoidal fit	$\mathbf{m}_\text{corr} = \mathbf{A}(\mathbf{m}_\text{raw} - \mathbf{b})$	- Hard-iron offset - Non-uniform scale factor - Symmetric (non-uniform) cross-axis coupling

where,

$$ \begin{aligned} \mathbf{m}_\text{corr} &= \text{Corrected measurement (vector)} \\ \mathbf{m}_\text{raw} &= \text{Raw measurement (vector)} \\ \mathbf{b} &= \text{Hard-iron offset (vector)} \\ s &= \text{Uniform scale factor (scalar)} \\ \mathbf{A} &= \text{Soft-iron (matrix)} \end{aligned} $$

Calibration Coefficients

The following coefficients are used to provide corrections to the device:

Hard-Iron Offset

$$ \mathbf{b} = \begin{bmatrix} b_x \\ b_y \\ b_z \end{bmatrix} $$

where,

$$ \begin{aligned} b_i = \text{Hard-iron bias for axis } i \text{ (Gauss)} \end{aligned} $$

Soft-Iron Matrix

$$ \mathbf{A} = \begin{bmatrix} a_{xx} & a_{xy} & a_{xz} \\ a_{yx} & a_{yy} & a_{yz} \\ a_{zx} & a_{zy} & a_{zz} \end{bmatrix} $$

where,

$$ \begin{aligned} a_{ii} &= \text{Scale factor for axis } i \\ a_{ij} &= \text{Cross-axis coupling where axis } j \text{ affects axis } i, \text{ } i \neq j \end{aligned} $$

When To Use Each Fit Function

In general, Spherical Fit is more reliable but less accurate. Ellipsoidal Fit is much more accurate, but requires high spatial coverage (> 60%).

A good rule of thumb is to start with Spherical Fit for a baseline. Then, an Ellipsoidal Fit can be run to see if it improves calibration over the baseline.

Install

See the Releases page for downloads.

Pre-built

Releases are currently distributed as a compressed folder containing the pre-built binaries.

Each component is distributed separately. Download the folder for the desired component and version and unzip it.

Building manually

This project uses CMake. To configure it, first create a build directory in the project root:

mkdir <build-dir>

Then, run the configure command:

cmake -S . -B <build-dir>

Once the project has been configured, build it:

cmake --build <build-dir> --parallel

After building, run this if you would like to create a distributable package as well:

cmake --build <build_dir> --target package_microstrain_mag_cal

The package will be in <build-dir>.

Development

The library and application are developed together under the same project. They should be treated as one during development.

Running tests

Unit tests should be run after every code change to catch errors early:

ctest --test-dir <build-dir> -L unit --output-on-failure --parallel