Skip to content

Neuronavigation read-in

Extracting neuronavigation coordinates for post-hoc ultrasound simulations is critical to verify and predict the focus of the realized stimulation sites during neuromodulation experiments. Neuronavigation systems provide spatial tracking of the ultrasound transducer position relative to the individual subject’s anatomy in real-time.

PRESTUS provides functions that aim to facilitate the read-in and preprocessing of positions recorded with the Localite system. To get started, see an example demo (without provided data) in /examples/demo_localite.m.

Three Localite XML file types are supported. All are parsed via the same pipeline (neuronav_compute_series_statistics), which handles single markers, repeated trigger trains, and multi-position recordings uniformly.

Localite XML file formats — TriggerMarkers, GUMMarkers, InstrumentMarker

TriggerMarkers

Multiple triggers can be sent during stimulation to acquire updates to the transducer location over time. Files are named TMSTrigger/TriggerMarkers_Coil0_<timestamp>. Recorded locations are averaged within each position series (identified by time-gap segmentation). Multiple positions per recording session are supported.

GUMMarkers

These files contain one or more static marker positions. Each Element in the file is expected to be of type EntryTargetPair (with a Target/Marker/ColVec3D position and a Rotation/RotationReference/ColVec3D beam direction), from which a synthetic 4×4 matrix is constructed.

Mixed-type GUMMarkers files. Some Localite versions write a GUMMarkerList file that contains a mix of EntryTargetPair and InstrumentMarker elements (the latter identified by type="InstrumentMarker" on the Element tag). neuronav_compute_series_statistics will fail on the InstrumentMarker elements when called with markertype='GUMMarkers'. Inspect the file first and, if an InstrumentMarker element with set=true is present, extract its Matrix4D directly and pass it to localite_matrix_to_positions. See code/debug_localite_inputs.m for an example.

InstrumentMarker

Static instrument positions stored as full 4×4 matrices in an InstrumentMarkerList file. Each InstrumentMarker entry contains a Marker/Matrix4D block with the same data{row}{col} field layout as TriggerMarkers. Set placement.localite.markertype = 'InstrumentMarker' to use this format.

Unsupported: EntryTarget

Some Localite versions export an EntryTargetList XML containing flat Target/Marker/ColVec3D and Rotation/RotationReference/ColVec3D entries at the top level (not wrapped in GUMMarkerList/Element). This format is not currently handled by neuronav_compute_series_statistics. To use it, manually read the target position and rotation reference vector, construct a synthetic 4×4 matrix (as in the GUMMarkers branch of neuronav_compute_series_statistics), and pass it to localite_matrix_to_positions.

Pipeline entry point

Set parameters.placement.localite.enabled = 1 to use Localite positioning in the PRESTUS pipeline (prestus_pipeline → preproc_head). Two modes are supported:

Simple mode — single XML file

Set placement.localite.file to the path of a specific Localite XML file. The file is parsed directly via position_transducer_localite.

placement:
  localite:
    enabled: 1
    file: '/path/to/GUMMarkers_sub-001.xml'

Full neuronav mode — automatic file selection

Leave placement.localite.file empty and set path.localite to the Localite data folder. The pipeline automatically selects the most recent valid file for the subject and session using neuronav_select_localite, averages markers across triggers using neuronav_compute_series_statistics, and resolves positions via localite_matrix_to_positions.

path:
  localite: '/path/to/localite/data/'

placement:
  localite:
    enabled: 1
    session: 1              # Session number or 'ses-01'
    markertype: 'TriggerMarkers'  # or 'GUMMarkers' or 'InstrumentMarker'
    position: 1             # Series index when multiple positions are recorded

This mode is appropriate when TriggerMarkers files contain repeated acquisitions per position that need to be averaged, or when automatic session-based file deduplication is required.

Standalone / batch use

For multi-position or multi-session workflows outside the pipeline, use neuronav_select_localite → neuronav_compute_series_statistics → neuronav_convert_trigger_to_voxels directly (see examples/demo_localite.m).

All paths share the same XML parser and position math (localite_matrix_to_positions). The reference distance from the IR tracker attachment point to the transducer exit plane is derived automatically from transducer geometry (curv_radius_mm − dist_geom_ep_mm) when defined, with fallback to parameters.placement.localite.reference_distance_mm.

Average transducer and target locations can be provided in multiple coordinate spaces (native image space being the most relevant for PRESTUS). The functions also facilitate standard-space definitions (experimental), e.g., to plot average transducer positions in standard space.

Neuronavigation Coordinate Transforms

See the coordinate system documentation.

Recorded Localite coordinates are relative to a neuronavigation planning image (e.g., T1_forneuronav) that was loaded in the neuronavigation software. Neuronavigation software writes this planning image with a zero-origin, diagonal affine (world = voxel × voxel_size_mm) rather than a scanner-isocenter world-space affine. Localite trigger matrices are therefore in planning-image space, not scanner world-space RAS.

The InstrumentMarker XML written by neuronav_ingest_markers preserves these coordinates as-is and labels the coordinate space "RAS" — meaning the axes are RAS-oriented, but the origin remains at the image corner (zero-origin). To convert to voxels, use ras_to_grid() with the planning T1 header, not the SimNIBS m2m T1 header. The m2m T1 has a full world-space affine; applying its inverse to planning-image coordinates displaces positions by tens of millimetres.

When SimNIBS is run on the planning T1, the resulting m2m_{sub}/T1.nii.gz shares the same voxel grid (SimNIBS preserves voxel dimensions and layout, updating only the affine). Voxel indices computed via ras_to_grid(localite_mm, planning_t1_header) are therefore directly valid for PRESTUS simulations that load the m2m T1 — no reprojection is needed. See Coordinate Reference Systems.

SimNIBS' nonlinear transform matrices to MNI are relative to the final_tissues.nii.gz segmentation image, so PRESTUS applies a transform from the planning to the segmentation image before porting coordinates to MNI space.

  1. Trigger to Voxel (neuronav_convert_trigger_to_voxels): → subject voxel indices
  2. Voxel → mm (neuronav_grid_to_mm_batch): → subject mm
  3. Native mm → MNI mm (neuronav_apply_deformation): → MNI mm

[Optional]: Interpolate average positions across subjects

  1. Aggregate means in MNI mm across subjects (neuronav_get_group_mean_mni)
  2. Group mean MNI mm → subject mm (neuronav_apply_inverse_deformation)
  3. Subject mm → subject voxel (neuronav_mm_to_voxel)

Coordinate Spaces in neuronav functions

  • neuronav_convert_trigger_to_voxels
    • Localite/trigger data (planning-image space mm, zero-origin RAS) → subject (native) voxel space via planning T1 header
  • neuronav_grid_to_mm_batch
    • Input: Subject voxel indices (i,j,k)
    • Operation: Uses subject’s T1 NIfTI affine transform
    • Output: Subject native mm coordinates (in scanner/world space)
  • neuronav_apply_deformation (forward warp)
    • Input: Native mm locations
    • Operation: Queries subject’s Conform2MNI_nonl.nii.gz (subject-native → MNI (mm))
    • Output: MNI mm coordinates (for reporting/plotting/averaging)
  • neuronav_get_group_mean_mni
    • Input: CSVs containing columns like Mtrans_pos_MNI_x/y/z (all from previous function outputs)
    • Operation: Aggregates these MNI mm locations across subjects/sessions, computes mean (in mm)
    • Output: MNI mm group-mean locations (still in millimeters, not voxels)
  • neuronav_apply_inverse_deformation (inverse warp)
    • Input: MNI mm group-mean locations (x, y, z in mm)
    • Operation: Uses subject’s MNI2Conform_nonl.nii.gz nonlinear field to map standard points back into that subject’s native space.
    • Output: Native mm location (in subject’s world/scanner space, for that subject)
  • neuronav_mm_to_voxel (helper)
    • Input: Native mm (x, y, z) location
    • Operation: Uses subject T1 affine to map mm → voxel (i, j, k)
    • Output: Subject voxel indices for subsequent image work or storage
  • neuronav_export_session_csv
    • Columns include:
    • Native (subject) voxel indices for target/transducer: (i, j, k from subject’s grid)
    • Native mm coordinates (if desired): (x, y, z in subject’s scanner space)
    • MNI mm coordinates for each (from deformation step): (x, y, z in standard space)
    • MNI voxel indices (may be inaccurate with limited FOVs)
Localite matrix origin: physical interpretation and calibration

Background

The Localite 4×4 transformation matrix encodes the pose of an IR-tracked instrument. Column 4 (the translation vector) gives the 3D position in RAS mm; column 1 (the first axis) gives the beam direction (from the coil/transducer face toward the target). These are the only two columns used by PRESTUS.

What PRESTUS models as the transducer position is the bowl rear centre — the geometric axis point at the back of the bowl housing. This is bowl_pos in k-Wave's makeBowl, from which the acoustic focus is offset by focal_distance_bowl along the beam direction. The acoustic focus position is therefore self-consistent with this convention.

The physical meaning of the Localite matrix origin (column 4) is not fixed — it depends on how the instrument was registered in the Localite instrument definition at the time of recording. Possible interpretations and their implications:

Possible matrix origin Value of tracker_to_bowl_mm
Exit plane centre -(curv_radius_mm − dist_geom_ep_mm) (negative; bowl rear is behind exit plane)
Bowl rear centre 0
IR tracker cluster centroid Measured distance from cluster to bowl rear centre (likely negative)
Housing reference point Measured distance from reference to bowl rear centre

The default geometry-derived formula (-(curv_radius_mm − dist_geom_ep_mm)) assumes the matrix origin is at the exit plane, placing the bowl rear centre behind it by the bowl depth. This assumption holds only if the Localite instrument was registered with the exit plane as the origin — which is a common convention, but is not guaranteed.

An incorrect assumption introduces a systematic spatial error along the beam axis equal to the difference between the assumed and actual origin.

How to determine the correct offset

Option 1 — Localite instrument definition file (recommended)

The Localite instrument definition is an XML file typically stored in the Localite software installation under Instruments/ or provided by the instrument manufacturer. Open it and locate the <ReferencePoint> or <Origin> tag. This describes what physical point the matrix origin corresponds to and its distance from key transducer landmarks in mm.

Option 2 — Empirical measurement (ruler / phantom)

  1. Place the transducer on a flat phantom surface and record a Localite position.
  2. Measure the distance from the phantom surface (= exit plane) to the IR tracker attachment on the housing.
  3. The bowl rear centre is approximately curv_radius_mm − dist_geom_ep_mm mm behind the exit plane.
  4. Set tracker_to_bowl_mm = (bowl rear centre position) − (matrix origin position), in mm along the beam axis.

Alternatively, acquire an MR image of a gel phantom with the transducer in place and compare the PRESTUS-predicted bowl voxel position against the visible gel/transducer interface.

Option 3 — Contact Localite support

The instrument registration specification can be confirmed by Localite (https://www.localite.de). Provide the instrument type and firmware version used during the recording.

Setting the calibrated offset in PRESTUS

Once the offset is known, set it explicitly in your config:

placement:
  localite:
    tracker_to_bowl_mm: -15   # mm from the Localite matrix origin to the bowl rear centre
                              # negative = bowl rear is on the housing side (away from head)

tracker_to_bowl_mm takes priority over the geometry-derived distance and over reference_distance_mm. The geometry-derived fallback (-(curv_radius_mm − dist_geom_ep_mm)) remains available when transducer geometry is fully specified and the matrix origin is known to be at the exit plane.