Skip to main content

FiffCoordTrans

Namespace: FIFFLIB  ·  Library: FIFF Library

Python equivalent

mne.transforms.Transform in MNE-Python.

#include <fiff/fiff_coord_trans.h>

class FIFFLIB::FiffCoordTrans

Labelled 4x4 FIFF affine: source frame, destination frame, rotation, translation and cached inverse.

Each transform carries its source (from) and destination (to) FIFFV_COORD_* frame identifiers so the inverse and any chained composition can be type-checked at runtime. The inverse is stored alongside the forward transform because both directions are routinely needed (device→head for head-position tracking, head→MRI for source space registration, etc.).

src/examples/ex_fiff_api/main.cpp
const FiffCoordTrans headToMri = FiffCoordTrans::readTransform(dir + "/all-trans.fif", FIFFV_COORD_HEAD, FIFFV_COORD_MRI);
const FiffCoordTrans devHead = info.dev_head_t; // device -> head, from the measurement info
FiffCoordTrans back = devHead.inverted();
float r[3] = {0.0f, 0.0f, 0.0f};
FiffCoordTrans::apply_trans(r, devHead, true); // the device origin in head coordinates

Public Methods​

FiffCoordTrans()​

Constructs the coordinate transformation descriptor.

FiffCoordTrans(p_IODevice)​

Constructs a coordinate transformation, by reading from a IO device.

Parameters:

  • p_IODevice : QIODevice & IO device to read from the coordinate transform.

FiffCoordTrans(p_FiffCoordTrans)​

Copy constructor.

Parameters:

  • p_FiffCoordTrans : const FiffCoordTrans & Coordinate transformation description which should be copied.

operator=(p_FiffCoordTrans)​

Copy assignment.

All members are values, so the compiler-generated member-wise assignment is correct. It has to be declared explicitly because declaring the copy constructor and destructor above deprecates the implicit one.

Parameters:

  • p_FiffCoordTrans : const FiffCoordTrans & Coordinate transformation description which should be assigned.

Returns:

FiffCoordTrans(from, to, rot, move)​

Constructs a coordinate transformation from a rotation matrix and translation vector.

Parameters:

  • from : int Source coordinate system.

  • to : int Destination coordinate system.

  • rot : const Eigen::Matrix3f & The forward transform (3×3 rotation matrix).

  • move : const Eigen::Vector3f & The forward transform (3×1 translation vector).

FiffCoordTrans(from, to, matTrans, bStandard)​

Constructs a coordinate transformation from a 4×4 homogeneous matrix.

Parameters:

  • from : int Source coordinate system.

  • to : int Destination coordinate system.

  • matTrans : const Eigen::Matrix4f & The 4×4 forward transform.

  • bStandard : bool When true, enforce standard transform (last row = [0,0,0,1]). Defaults to false.

~FiffCoordTrans()​

Destroys the coordinate transformation descriptor.

clear()​

Initializes the coordinate transformation descriptor.

invert_transform()​

Invert a coordinate transformation (actual obsolete - cause trans and inverse are both stored).

Returns:

  • bool — true if succeeded, false otherwise.

isEmpty()​

Returns true if coordinate transform contains no data.

Returns:

  • bool — true if coordinate transform is empty.

apply_trans(rr, do_move)​

Applies the coordinate transform to given coordinates and returns the transformed coordinates.

Parameters:

  • rr : const Eigen::MatrixX3f & The coordinates.

  • do_move : bool Perform translation next to rotation yes/no.

Returns:

  • Eigen::MatrixX3f — Transformed coordinates.

apply_inverse_trans(rr, do_move)​

Applies the inverse coordinate transform to given coordinates and returns the transformed coordinates.

Parameters:

  • rr : const Eigen::MatrixX3f & The coordinates.

  • do_move : bool Perform translation next to rotation yes/no.

Returns:

  • Eigen::MatrixX3f — Transformed coordinates.

inverted()​

Returns a new inverted copy of this transformation (swaps from/to and trans/invtrans).

Returns:

print()​

Prints the coordinate transform.

write(p_IODevice)​

Writes the transformation to file.

Parameters:

  • p_IODevice : QIODevice & IO device to write the transformation to.

Returns:

  • bool — false if the device cannot be opened for writing.

writeToStream(p_pStream)​

Writes the transformation to a FIFF stream.

Parameters:

  • p_pStream : *FiffStream ** Pointer to the FIFF stream to write to.

angleTo(mTransDest)​

Calculate rotation as angle between two rotation matrices.

Parameters:

  • mTransDest : Eigen::MatrixX4f The destination transformation matrix.

Returns:

  • float — The angle of rotation between two rotation matrices in degrees.

translationTo(mTransDest)​

Calculate translation between two rotation matrices in meter.

Parameters:

  • mTransDest : Eigen::MatrixX4f The destination transformation matrix.

Returns:

  • float — The translation between two rotation matrices in m.

Static Methods​

read(p_IODevice, p_Trans)​

Reads the first coordinate transform from a fif file (as mne.read_trans).

Use readTransform() to select a transform by its coordinate frames.

Parameters:

  • p_IODevice : QIODevice & A fiff IO device like a fiff QFile or QTCPSocket.

  • p_Trans : FiffCoordTrans & A coordinate transform from a fif file.

Returns:

  • bool — true if succeeded, false otherwise.

readTransform(name, from, to)​

Reads a specified coordinate transform from a FIFF file.

Parameters:

  • name : const QString & FIFF file path.

  • from : int Expected source coordinate system.

  • to : int Expected destination coordinate system.

Returns:

  • FiffCoordTrans — The coordinate transform, or an empty transform if not found.

readMriTransform(name)​

Reads the MRI → head coordinate transform from a FIFF file.

Parameters:

  • name : const QString & FIFF file path.

Returns:

  • FiffCoordTrans — The MRI→head transform, or an empty transform if not found.

readMeasTransform(name)​

Reads the MEG device → head coordinate transform from a FIFF file.

Parameters:

  • name : const QString & FIFF file path.

Returns:

  • FiffCoordTrans — The device→head transform, or an empty transform if not found.

readTransformAscii(name, from, to)​

Reads a coordinate transform from an ASCII 4×3 matrix file (mm-to-m conversion applied).

Parameters:

  • name : const QString & ASCII file path.

  • from : int Source coordinate system.

  • to : int Destination coordinate system.

Returns:

  • FiffCoordTrans — The coordinate transform, or an empty transform on failure.

readFShead2mriTransform(name)​

Reads the FreeSurfer head → MRI transform from an ASCII file.

Parameters:

  • name : const QString & ASCII file path.

Returns:

  • FiffCoordTrans — The head→MRI transform, or an empty transform on failure.

apply_trans(r, t, do_move)​

Applies the coordinate transform to a single 3D point in place.

Parameters:

  • r : float 3-element float array to transform in place.

  • t : const FiffCoordTrans & The coordinate transformation to apply.

  • do_move : bool If true, apply translation; if false, rotation only.

apply_inverse_trans(r, t, do_move)​

Applies the inverse coordinate transform to a single 3D point in place.

Parameters:

  • r : float 3-element float array to transform in place.

  • t : const FiffCoordTrans & The coordinate transformation whose inverse to apply.

  • do_move : bool If true, apply translation; if false, rotation only.

frame_name(frame)​

Map coordinate frame integers to human-readable names.

Parameters:

  • frame : int The coordinate frame integer.

Returns:

  • QString — Human readable form of the coordinate frame.

identity(from, to)​

Creates an identity transformation between two coordinate systems.

Parameters:

  • from : int Source coordinate system.

  • to : int Destination coordinate system.

Returns:

combine(from, to, t1, t2)​

Combines two coordinate transformations to yield a transform from from to to.

Automatically handles inversion and ordering of the input transforms.

Parameters:

  • from : int Desired source coordinate system.

  • to : int Desired destination coordinate system.

  • t1 : const FiffCoordTrans & First transformation.

  • t2 : const FiffCoordTrans & Second transformation.

Returns:

  • FiffCoordTrans — The combined transformation, or an empty transform on failure.

fromCardinalPoints(from, to, rL, rN, rR)​

Constructs a coordinate transformation from cardinal points (LPA, Nasion, RPA).

Parameters:

  • from : int Source coordinate system.

  • to : int Destination coordinate system (in which the points are expressed).

  • rL : *const float ** Left auricular point (3 floats).

  • rN : *const float ** Nasion point (3 floats).

  • rR : *const float ** Right auricular point (3 floats).

Returns:

addInverse(t)​

Parameters:

Returns:

  • bool — True when successful.

storageSize()​

Size of the old struct (fiffCoordTransRec) 26int = 264 = 104.

Returns:

  • qint32 — the size of the old struct fiffCoordTransRec.

readFromTag(tag)​

Reads a coordinate transform from a FIFF tag.

Parameters:

  • tag : const std::unique_ptr< FiffTag > & The FIFF tag to read from.

Returns:

  • FiffCoordTrans — The coordinate transform, or an empty transform if the tag is invalid.

readTransformFromNode(stream, node, from, to)​

Reads a coordinate transform from a FIFF stream node.

Parameters:

  • stream : FiffStream::SPtr & The FIFF stream.

  • node : const FiffDirNode::SPtr & The directory node to search.

  • from : int Expected source coordinate system.

  • to : int Expected destination coordinate system.

Returns:

  • FiffCoordTrans — The coordinate transform, or an empty transform if not found.

procrustesAlign(from_frame, to_frame, fromp, top, w, max_diff)​

Performs a Procrustes alignment between two sets of corresponding 3D points.

Parameters:

  • from_frame : int Source coordinate frame ID.

  • to_frame : int Destination coordinate frame ID.

  • fromp : const Eigen::MatrixXf & Point locations in the source frame (np×3 matrix).

  • top : const Eigen::MatrixXf & Point locations in the destination frame (np×3 matrix).

  • w : const Eigen::VectorXf & Weights (np elements), or empty vector for equal weight.

  • max_diff : float Maximum allowed difference between transformed and target.

Returns:

  • FiffCoordTrans — The alignment transform, or an empty transform on failure.

Example​

Used in examples​

ex_fiff_api​

FIFF library: measurement info, channels, digitizer, transforms, projectors, covariance, events,.

src/examples/ex_fiff_api/main.cpp, line 131
const FiffCoordTrans headToMri = FiffCoordTrans::readTransform(dir + "/all-trans.fif", FIFFV_COORD_HEAD, FIFFV_COORD_MRI);
const FiffCoordTrans devHead = info.dev_head_t; // device -> head, from the measurement info
FiffCoordTrans back = devHead.inverted();
float r[3] = {0.0f, 0.0f, 0.0f};
FiffCoordTrans::apply_trans(r, devHead, true); // the device origin in head coordinates
// mne.read_trans: 1 -> 4 ... ; info["dev_head_t"] translation (-0.006129, 0.000064, 0.064742) m
ok &= expect(devHead.from == FIFFV_COORD_DEVICE && devHead.to == FIFFV_COORD_HEAD && (Vector3f(r[0], r[1], r[2]) - Vector3f(-0.006129f, 0.000064f, 0.064742f)).norm() < 1e-6f && (back.trans * devHead.trans).isIdentity(1e-5f) && headToMri.from == FIFFV_COORD_HEAD && headToMri.to == FIFFV_COORD_MRI,
             "FiffCoordTrans: device origin maps to (-6.13, 0.06, 64.74) mm in head coordinates");

ex_read_evoked​

Example for read an evoked from fiff file.

src/examples/ex_read_evoked/main.cpp, line 79
//Select the head coordinate system
bool use_ctf_head = parser.isSet(useCTFCompOption);
FiffCoordTrans meg_trans;

ex_mne_api​

MNE library: BEM surfaces, surface projection, ICP, source spaces and epochs.

src/examples/ex_mne_api/main.cpp, line 181
MatrixXf mriPoints(3, 3);
mriPoints << innerSkull.rr.row(0), innerSkull.rr.row(20), innerSkull.rr.row(40);
fitMatchedPoints(headShape.topRows(3), mriPoints, start);
FiffCoordTrans headToMri(FIFFV_COORD_HEAD, FIFFV_COORD_MRI, start);
// 2. Drop head shape points further than 10 mm from the surface, then refine with ICP
auto surface = QSharedPointer<MNEProjectToSurface>::create(innerSkull);
VectorXi take;
MatrixXf kept;
discard3DPointOutliers(surface, headShape, headToMri, take, kept, 0.01f);
float rmse = 0.0f;
performIcp(surface, kept, headToMri, rmse, false, 50, 1e-6f);
ok &= expect(take.size() == headShape.rows() && (headToMri.rot() - trueRot).norm() < 1e-3f && (headToMri.move() - trueMove).norm() < 1e-4f && rmse < 1e-4f,
             "fitMatchedPoints/discard3DPointOutliers/performIcp recover the known head-to-MRI transform");

Also used in ex_compute_forward, ex_fwd_api, ex_hpiFit, ex_mri.

Authors of this file​