magsensor

Magnetometer array reader & dipole magnet localizer

Overview

magsensor is a demo codebase. It reads a 9-sensor magnetometer array via serial and localizes a dipole magnet in real time, with a live 3D visualization GUI.

Quick Start

Prerequisites: uv, and of course, a magnetometer array :)

Clone this repo and install dependencies:

git clone https://github.com/zixingjiang/magsensor
cd magsensor

# install with optional extras as needed
uv sync                      # core dependencies
uv sync --extra gui          # with GUI
uv sync --extra examples     # to run the example
uv sync --extra dev          # everything

Usage:

uv run magsensor --help      # show available commands; also works on subcommands (e.g. magsensor read --help)
uv run magsensor read        # read raw sensor data from the array
uv run magsensor calibrate   # calibrate sensor bias offsets
uv run magsensor localize    # localize a dipole magnet from current readings
uv run magsensor gui         # launch the all-in-one GUI

Dipole Magnet Localization

Localizing a dipole magnet from a magnetometer array is formulated as a nonlinear least-squares problem: find the 5-DoF magnet pose (position and heading) that minimizes the difference between the measured field and the analytical dipole model.

Dipole Field Model

The magnetic field at position $\mathbf{r}$ due to a dipole with moment $\mathbf{m} = m\hat{\mathbf{m}}$ is:

$$\mathbf{B}(\mathbf{r}, \mathbf{m}) = \frac{\mu_0}{4\pi} \frac{1}{|\mathbf{r}|^3} \left( 3\hat{\mathbf{r}}\hat{\mathbf{r}}^\top - \mathbf{I} \right) \mathbf{m}$$

where $\mu_0 = 4\pi \times 10^{-7}$ and $\hat{\mathbf{r}} = \mathbf{r} / |\mathbf{r}|$.

Problem Formulation

Let $\mathbf{p}$ be the magnet position, $\mathbf{t}_i$ the position of sensor $i$, and $\mathbf{r}_i = \mathbf{t}_i - \mathbf{p}$ the vector from the magnet to that sensor. Given a known moment magnitude $m$ and a unit heading $\hat{\mathbf{m}}$, the predicted field at sensor $i$ is:

$$\mathbf{B}_i^{\text{pred}}(\mathbf{p}, \hat{\mathbf{m}}) = \frac{\mu_0 m}{4\pi} \frac{1}{|\mathbf{t}_i - \mathbf{p}|^3} \left( 3\widehat{\mathbf{t}_i - \mathbf{p}} ; \widehat{\mathbf{t}_i - \mathbf{p}}^\top - \mathbf{I} \right) \hat{\mathbf{m}}$$

The localizer solves for $\mathbf{p}$ and $\hat{\mathbf{m}}$ by minimizing the residual across all 9 sensors:

$$\min_{\mathbf{p}, \hat{\mathbf{m}}} \sum_{i=1}^{9} | \mathbf{B}_i^{\text{meas}} - \mathbf{B}_i^{\text{pred}}(\mathbf{p}, \hat{\mathbf{m}}) |_2^2 \qquad \text{s.t. } |\hat{\mathbf{m}}| = 1$$

Solvers

This codebase provides two complementary solvers:

Solver	Description
SQP (Sequential Quadratic Programming)	Gradient-based optimizer using CasADi's sqpmethod. Default solver.
PIA (Particle Importance Analysis)	Random particle sampling followed by Gram-Schmidt Orthogonal Least Squares. Global search, less susceptible to local minima.

Note: This is an unofficial implementation of the PIA algorithm. See XuRuoyuRoy/Particle-Importance-Analysis for the official version.

Both solvers support solving with the moment magnitude $m$ as either a known constant or a free variable.

Magnetometer Array

The magnetometer array (a) contains 9 LIS3MDL sensors arranged in a $3\times3$ planar grid (credit: Yichong Sun). An STM32 Blue Pill MCU (b) queries these sensors via the I2C protocol and sends the data to the computer via USB. A flashable firmware is available here.

Needle Overlay Example

The codebase includes a toy demo showing how dipole‑magnet localization can support ultrasound‑guided needle insertion. By tracking a magnet mounted on the needle, its position relative to the ultrasound scan plane is estimated, enabling an overlay on the ultrasound image that helps keep the needle aligned with the scan plane.

To run the example:

uv run examples/needle_overlay/3dview.py      examples/needle_overlay/config.yaml   # 3D illustration
uv run examples/needle_overlay/overlay.py     examples/needle_overlay/config.yaml   # ultrasound image overlay
uv run examples/needle_overlay/simulation.py  examples/needle_overlay/config.yaml   # simulation without ultrasound

License

MIT © Zixing Jiang