Skip to main content

MNE Align

mne_align is the standalone coregistration helper that ships with mne-cpp v2.3.0. It walks an operator through a seven-step wizard that takes a subject's head BEM, the corresponding live or recorded digitisation, and produces a -trans.fif head→MRI transform suitable for downstream forward / inverse modelling.

The app is built on the same MultimodalScene foundation as mne_inspect, and integrates direct serial capture from a Polhemus FASTRAK digitiser via the shared UTILSLIB::PolhemusConnection driver. It also accepts a previously recorded digitisation FIFF file when no hardware is available.

mne_align overview

Launching​

out/Release/lib/mne_align

The window splits horizontally:

  • Left: the seven-step wizard (AlignWizard).
  • Right: the 3D scene (Align3DView) showing the BEM surface, captured points, and live tracker cursor.

The toolbar exposes Back / Next navigation, viewport count, camera preset, render shader, focus target, and the active Polhemus pen station id.

The 7-step wizard​

Step 1 — Setup​

Load the head BEM (.fif / .fif.gz) and pick the standard EEG cap (10-20, 10-10, 10-05). Select a fiducial button (NAS, LPA, RPA) and double-click on the BEM surface to place the corresponding twin fiducial in MRI space. These twin points define the target landmarks for the head→MRI fit.

Step 1 — Setup

Step 2 — Fiducials​

Capture the three cardinal points (NAS → LPA → RPA) from the subject. There are two paths:

  1. Live FASTRAK capture. Hold the stylus on the landmark and either press the pen button on the stylus or click Capture. The wizard advances to the next uncaptured fiducial automatically.
  2. Load from FIFF. Click Load FIFF… to import an existing digitisation (ISOTRAK) from a .fif file. Cardinal, EEG and HSP points are dispatched into the corresponding wizard buckets automatically.

Step 2 — Fiducials

Step 3 — EEG cap​

Walk the cap label by label. The wizard's electrode list highlights the next uncaptured site and the Capture button advances through the montage. Undo last reverts the most recent capture.

Step 3 — EEG cap

Step 4 — Head shape​

Sweep the stylus over the scalp and capture additional head-shape points (FIFF EXTRA). The capture count is shown live and the points appear immediately in the 3D scene.

Step 4 — Head shape

Step 5 — Verify​

Click Run ICP Fit to refine the fiducial-based coregistration via the mne_icp library. The page shows:

  • Source: description of the fit (ICP, N iterations max).
  • RMSE: overall mean residual in millimetres.
  • Per-point residuals: distance from each captured cardinal point to its MRI twin after applying the refined transform.

Re-running ICP after editing fiducials produces a new fit. Returning to an earlier step and re-capturing a landmark automatically invalidates the override so the next ICP run starts from a clean fiducial-only fit.

Step 5 — Verify

Step 6 — Save​

Two save actions are exposed:

  • Save -trans.fif… writes the head→MRI rigid transform as a FiffCoordTrans via FIFFLIB::FiffCoordTrans::write. The suggested filename derives from the BEM stem (e.g. subject01-trans.fif). The transform is what downstream tools (mne_forward_solution, mne_compute_mne, mne-python's read_trans) expect.
  • Save digitisation FIFF… writes the captured ISOTRAK point set (cardinal, EEG, HSP) via FIFFLIB::FiffDigPointSet::write — useful for archiving the raw capture independently of the transform.

Step 6 — Save

Step 7 — Done​

A summary lists the BEM, cap, captured counts, ICP source / RMSE, and the path of the most recently saved -trans.fif. Use the Back button to refine and re-save at any time without restarting the session.

Step 7 — Done

Hardware: Polhemus FASTRAK​

mne_align talks to the FASTRAK over a serial port via the shared UTILSLIB::PolhemusConnection driver (src/libraries/utils/polhemus/). Use Digitizer → Connect… to attach:

  • The wizard first scans known FASTRAK / FastSCAN USB vendor ids; if a device is detected its port name is pre-selected.
  • If auto-detection fails, a dialog lists every visible serial port plus a Mock backend option that emits scripted samples for offline testing.

The active pen station (1 – 4) is selected from the toolbar Pen: combo. Only samples from the active station are treated as captures — additional sensors (e.g. a reference attached to the subject's forehead) can stream concurrently without polluting the capture buffer.

On capture, the page reacts to either:

  • the physical pen button on the stylus (preferred — guarantees the point is taken at the exact instant the operator is steady on the landmark), or
  • the on-screen Capture button (fallback if the pen button is unavailable).

If no hardware is connected, the Mock backend still drives the wizard end-to-end with synthetic samples — useful for training and CI.

Output: -trans.fif​

The -trans.fif produced in Step 6 is a single FiffCoordTrans block tagged

  • from = FIFFV_COORD_HEAD (4)
  • to = FIFFV_COORD_MRI (5)

with the 4×4 rigid head→MRI matrix and its inverse populated via FiffCoordTrans::addInverse. The file is binary-compatible with both the MNE C reference toolkit and mne-python's mne.read_trans().

A typical downstream pipeline is:

# Forward solution against a previously prepared source space:
mne_forward_solution --meas raw.fif \
                     --src subject-oct-6-src.fif \
                     --bem subject-5120-bem-sol.fif \
                     --trans subject-trans.fif \
                     --fwd subject-fwd.fif

or, in Python:

import mne
trans = mne.read_trans("subject-trans.fif")
fwd   = mne.make_forward_solution(raw.info, trans=trans, src=src, bem=bem)

The digitisation .fif written in parallel can be merged back into a raw recording via mne_process_raw --dig or mne.io.read_raw_fif(..., preload=False).set_montage(...).

Files of interest​

  • src/applications/mne_align/mne_align.{h,cpp} — QMainWindow shell.
  • src/applications/mne_align/align_wizard.{h,cpp} — seven-step wizard.
  • src/applications/mne_align/align_3d_view.{h,cpp} — 3D scene + camera presets.
  • src/applications/mne_align/polhemus_connection.h — re-export of UTILSLIB::PolhemusConnection.
  • src/libraries/utils/polhemus/ — shared FASTRAK parser, connection driver, AcquiredPoints store.
  • src/libraries/mne/mne_icp.{h,cpp} — ICP refinement entry point (MNELIB::performIcp).
  • Co-Registration — equivalent coregistration plugin embedded in mne_analyze.
  • Inspect — the broader multimodal viewer mne_align is derived from.