fiff: port the MNE-C head -> MNI -> Talairach transform chain

FiffCoordTransSet holds MNE-C's coordTransSet chain and gains
readMniTransform (talairach.xfm), addTalairach (plus M. Brett's two
MNI -> Talairach matrices), read/write, headToMni (= mne.head_to_mni)
and mniToTalairach.

MriMghIO tagged the talairach.xfm transform MRI -> MRI_DISPLAY and never
emitted surface RAS -> RAS; it now returns surface RAS -> RAS and the
RAS -> MNI -> Talairach chain with MNE-C's frames.
mne_collect_transforms gains --mgh and collects the whole chain like
MNE-C instead of only device->head and MRI->head.

Author: chdinh

doc/api_registry.json

@@ -8121,7 +8121,14 @@
       "mne_python": null,
       "sklearn": null,
       "test": null,
-      "example": null,
+      "example": "ex_fiff_api",
+      "example_snippet": [
+        "ex_fiff_api/main.cpp#fiff_coord_trans_set_usage"
+      ],
+      "example_mode": "run",
+      "required_data": [
+        "mne-cpp-test-data"
+      ],
       "status": "documented",
       "skigen_candidate": false,
       "documented": true,

doc/release/v2.4.0/api-evidence-baseline.json

@@ -12,16 +12,16 @@
     "registered_stale": 0,
     "registered_with_test": 101,
     "registered_test_unresolved": 0,
-    "registered_with_example": 267,
+    "registered_with_example": 268,
     "registered_example_not_built": 0,
     "registered_with_python_equiv": 88,
     "registered_without_api_page": 0,
-    "with_snippet": 328,
+    "with_snippet": 329,
     "public_api_units": 478,
     "example_eligible": 383,
     "example_exempt": 95,
-    "eligible_backed_by_registry_example": 267,
-    "eligible_used_by_some_example": 327,
+    "eligible_backed_by_registry_example": 268,
+    "eligible_used_by_some_example": 328,
     "examples_on_disk": 68,
     "examples_built": 68
   },
@@ -94,9 +94,9 @@
       "registered": 32,
       "with_test": 10,
       "eligible": 37,
-      "eligible_with_registry_example": 31,
-      "eligible_used_by_example": 34,
-      "with_snippet": 36
+      "eligible_with_registry_example": 32,
+      "eligible_used_by_example": 35,
+      "with_snippet": 37
     },
     "fs": {
       "public": 8,
@@ -6142,10 +6142,14 @@
       "registry_status": "documented",
       "test": null,
       "test_resolves": false,
-      "example": null,
-      "example_state": "none",
-      "including_examples": [],
-      "snippets": [],
+      "example": "ex_fiff_api",
+      "example_state": "built",
+      "including_examples": [
+        "ex_fiff_api"
+      ],
+      "snippets": [
+        "ex_fiff_api/main.cpp#fiff_coord_trans_set_usage"
+      ],
       "api_page": "doc/website/docs/api/fiff/fiff-coord-trans-set.mdx",
       "python_equiv": null,
       "example_eligible": true,

doc/release/v2.4.0/api-evidence-baseline.md

@@ -15,16 +15,16 @@ Generated by `tools/quality/audit_api_evidence.py`. Do not edit by hand.
 ## Evidence
 
 - Registry test reference: 101 / 354 (28.5%) (0 unresolved)
-- Registry example reference: 267 / 354 (75.4%) (0 missing or not built)
+- Registry example reference: 268 / 354 (75.7%) (0 missing or not built)
 - Python equivalent recorded: 88 / 354 (24.9%)
-- Doxygen `@snippet` references: 328
+- Doxygen `@snippet` references: 329
 
 ## G3 example metric
 
 Public API units (exported classes, registered function namespaces and header-only types): 478. Example-eligible: **383** (95 exempt under the proposed policy).
 
-- Eligible with a built registry example: 267 / 383 (69.7%)
-- Eligible whose header is included by any example: 327 / 383 (85.4%)
+- Eligible with a built registry example: 268 / 383 (70.0%)
+- Eligible whose header is included by any example: 328 / 383 (85.6%)
 - Examples on disk / built: 68 / 68
 
 ## By library
@@ -38,7 +38,7 @@ Public API units (exported classes, registered function namespaces and header-on
 | `disp` | 66 | 66 | 0 | 8 | 8 | 8 | 8 |
 | `disp3D` | 46 | 10 | 0 | 22 | 6 | 11 | 9 |
 | `dsp` | 80 | 51 | 28 | 80 | 51 | 80 | 80 |
-| `fiff` | 37 | 32 | 10 | 37 | 31 | 34 | 36 |
+| `fiff` | 37 | 32 | 10 | 37 | 32 | 35 | 37 |
 | `fs` | 8 | 8 | 4 | 8 | 8 | 8 | 8 |
 | `fwd` | 13 | 13 | 3 | 12 | 10 | 8 | 10 |
 | `inv` | 43 | 35 | 19 | 41 | 33 | 39 | 39 |

doc/release/v2.4.0/maintainability-baseline.json

@@ -3,7 +3,7 @@
   "generated_by": "tools/quality/audit_maintainability.py",
   "policy": "tools/quality/maintainability_policy.json",
   "scanned_files": 1508,
-  "scanned_lines": 394648,
+  "scanned_lines": 394768,
   "oversized_threshold": 2000,
   "metrics": {
     "null_macro": {
@@ -406,12 +406,12 @@
       }
     },
     "console_io": {
-      "total": 370,
-      "files": 54,
+      "total": 358,
+      "files": 53,
       "by_scope": {
         "applications": 7,
         "libraries": 59,
-        "tools": 304
+        "tools": 292
       },
       "suppressed": [],
       "top": {
@@ -420,7 +420,6 @@
         "src/tools/inverse/mne_compute_raw_inverse/main.cpp": 19,
         "src/libraries/utils/layoutmaker.cpp": 16,
         "src/tools/info/mne_show_fiff/mne_show_fiff_settings.cpp": 16,
-        "src/tools/info/mne_collect_transforms/main.cpp": 12,
         "src/tools/inverse/mne_map_data/main.cpp": 11,
         "src/tools/preprocessing/mne_rename_channels/main.cpp": 10,
         "src/tools/visualization/mne_screenshot_regression/main.cpp": 10,
@@ -429,7 +428,8 @@
         "src/tools/conversion/mne_convert_surface/main.cpp": 8,
         "src/tools/conversion/mne_epochs2mat/main.cpp": 8,
         "src/tools/conversion/mne_eximia2fiff/main.cpp": 8,
-        "src/tools/forward/mne_surf2bem/surfacechecks.cpp": 8
+        "src/tools/forward/mne_surf2bem/surfacechecks.cpp": 8,
+        "src/tools/info/mne_check_eeg_locations/main.cpp": 8
       },
       "all_files": {
         "src/applications/mne_analyze/plugins/view3d/view3d.cpp": 1,
@@ -465,7 +465,6 @@
         "src/tools/forward/mne_surf2bem/surfacechecks.cpp": 8,
         "src/tools/forward/mne_transform_points/main.cpp": 5,
         "src/tools/info/mne_check_eeg_locations/main.cpp": 8,
-        "src/tools/info/mne_collect_transforms/main.cpp": 12,
         "src/tools/info/mne_list_bem/main.cpp": 8,
         "src/tools/info/mne_list_coil_def/main.cpp": 5,
         "src/tools/info/mne_list_proj/main.cpp": 6,

doc/release/v2.4.0/maintainability-baseline.md

@@ -3,7 +3,7 @@
 Generated by `tools/quality/audit_maintainability.py`. Do not edit by hand.
 Counts are lexical candidates with comments and string literals removed; they rank work, they do not prove defects.
 
-Scanned 1,508 files / 394,648 lines in `src/libraries`, `src/applications`, `src/tools`. Compiler warnings: 0 (the build is `-Werror`, T6.1).
+Scanned 1,508 files / 394,768 lines in `src/libraries`, `src/applications`, `src/tools`. Compiler warnings: 0 (the build is `-Werror`, T6.1).
 
 | Metric | Total | Files | libraries | applications | tools |
 |---|---:|---:|---:|---:|---:|
@@ -12,7 +12,7 @@ Scanned 1,508 files / 394,648 lines in `src/libraries`, `src/applications`, `src
 | `c_style_cast` | 429 | 73 | 275 | 61 | 93 |
 | `raw_new` | 169 | 90 | 63 | 100 | 6 |
 | `raw_delete` | 275 | 101 | 98 | 155 | 22 |
-| `console_io` | 370 | 54 | 59 | 7 | 304 |
+| `console_io` | 358 | 53 | 59 | 7 | 292 |
 | `numeric_define` | 834 | 31 | 730 | 69 | 35 |
 | `qt_new_unparented` | 825 | 83 | 108 | 715 | 2 |
 | `oversized_unit` | 8 | 8 | 5 | 3 | 0 |
@@ -107,7 +107,6 @@ Scanned 1,508 files / 394,648 lines in `src/libraries`, `src/applications`, `src
 | 19 | `src/tools/inverse/mne_compute_raw_inverse/main.cpp` |
 | 16 | `src/libraries/utils/layoutmaker.cpp` |
 | 16 | `src/tools/info/mne_show_fiff/mne_show_fiff_settings.cpp` |
-| 12 | `src/tools/info/mne_collect_transforms/main.cpp` |
 | 11 | `src/tools/inverse/mne_map_data/main.cpp` |
 | 10 | `src/tools/preprocessing/mne_rename_channels/main.cpp` |
 | 10 | `src/tools/visualization/mne_screenshot_regression/main.cpp` |
@@ -117,6 +116,7 @@ Scanned 1,508 files / 394,648 lines in `src/libraries`, `src/applications`, `src
 | 8 | `src/tools/conversion/mne_epochs2mat/main.cpp` |
 | 8 | `src/tools/conversion/mne_eximia2fiff/main.cpp` |
 | 8 | `src/tools/forward/mne_surf2bem/surfacechecks.cpp` |
+| 8 | `src/tools/info/mne_check_eeg_locations/main.cpp` |
 
 ## `numeric_define` — top files
 

doc/release/v2.4.0/quality-baseline.json

@@ -50,8 +50,8 @@
       "public_api_units": 478,
       "exported_not_registered": 124,
       "example_eligible": 383,
-      "eligible_backed_percent": 69.71,
-      "snippets": 328,
+      "eligible_backed_percent": 69.97,
+      "snippets": 329,
       "registered_test_percent": 28.53
     },
     "G4_screenshots": {
@@ -68,7 +68,7 @@
       "c_style_cast": 429,
       "raw_new": 169,
       "raw_delete": 275,
-      "console_io": 370,
+      "console_io": 358,
       "numeric_define": 834,
       "qt_new_unparented": 825,
       "oversized_unit": 8

doc/release/v2.4.0/quality-baseline.md

@@ -13,12 +13,12 @@ Coverage from `5053fe099` (https://github.com/mne-tools/mne-cpp/actions/runs/362
 | G2 | Applications >= 50.0% line | 24.9% | **open** |
 | G2 | Tools >= 50.0% line | 61.68% | met |
 | G2 | Libraries >= 65.0% branch | 42.9% | **open** |
-| G3 | Eligible APIs have an executable example | 69.71% of 383; 328 snippets | **open** |
+| G3 | Eligible APIs have an executable example | 69.97% of 383; 329 snippets | **open** |
 | G3 | Exported API is registered | 124 exported classes unregistered | **open** |
 | G4 | Documentation images generated in CI | 19 referenced, 0 without producer, placeholders in 0 workflows | met |
 | G4 | Visual regression compares to goldens | 0 golden comparisons | **open** |
 | G5 | Zero compiler warnings | enforced by -Werror on every matrix entry | met |
-| G5 | Debt metrics ratcheted | null_macro 43, typedef_struct 12, c_style_cast 429, raw_new 169, raw_delete 275, console_io 370, numeric_define 834, qt_new_unparented 825, oversized_unit 8 | baseline recorded |
+| G5 | Debt metrics ratcheted | null_macro 43, typedef_struct 12, c_style_cast 429, raw_new 169, raw_delete 275, console_io 358, numeric_define 834, qt_new_unparented 825, oversized_unit 8 | baseline recorded |
 | G6 | Pinned reference environment | MNE-Python 1.11.0; unpinned in CI: none | met |
 | G6 | Parity claims cross-validated | cross-validated-static 3, cross-validated-live 1, tested 84, unverified 270 | **open** |
 

doc/website/docs/api/class-members.mdx

@@ -7,7 +7,7 @@ sidebar_position: 5
 
 # Class Members
 
-Index of 6270 public class members (functions, variables, typedefs, enums) across all documented classes.
+Index of 6275 public class members (functions, variables, typedefs, enums) across all documented classes.
 
 **Jump to:** [A](#a) · [B](#b) · [C](#c) · [D](#d) · [E](#e) · [F](#f) · [G](#g) · [H](#h) · [I](#i) · [J](#j) · [K](#k) · [L](#l) · [M](#m) · [N](#n) · [O](#o) · [P](#p) · [Q](#q) · [R](#r) · [S](#s) · [T](#t) · [U](#u) · [V](#v) · [W](#w) · [X](#x) · [Y](#y) · [Z](#z)
 
@@ -98,6 +98,7 @@ Index of 6270 public class members (functions, variables, typedefs, enums) acros
 - **addSubject** `[slot]` in [BidsViewModel](/docs/api/disp/bids-view-model) — Adds subject with given input name.
 - **addSurface** `[fn]` in `BrainTreeModel`
 - **addTable** `[fn]` in [Report](/docs/api/utils/report) — Add a table section.
+- **addTalairach** `[fn]` in [FiffCoordTransSet](/docs/api/fiff/fiff-coord-trans-set) — Sets the RAS -> MNI transform from a ``.xfm file and the two MNI -> FreeSurfer Talairach transforms (MNE-C mne_mri_add_talairach_transforms).
 - **addText** `[fn]` in [Report](/docs/api/utils/report) — Add a text section.
 - **addToData** `[slot]` in [BidsViewModel](/docs/api/disp/bids-view-model) — Adds a sub-item to a data item (ex.
 - **addTriangleData** `[fn]` in [MNEBemSurface](/docs/api/mne/mne-bem-surface) — Definition of the mne_add_triangle_data function in mne_add_geometry_info.c.
@@ -1624,7 +1625,6 @@ Index of 6270 public class members (functions, variables, typedefs, enums) acros
 - **FiffCoordTrans** `[fn]` in [FiffCoordTrans](/docs/api/fiff/fiff-coord-trans) — Copy constructor.
 - **FiffCoordTrans** `[fn]` in [FiffCoordTrans](/docs/api/fiff/fiff-coord-trans) — Constructs a coordinate transformation from a rotation matrix and translation vector.
 - **FiffCoordTrans** `[fn]` in [FiffCoordTrans](/docs/api/fiff/fiff-coord-trans) — Constructs a coordinate transformation from a 4×4 homogeneous matrix.
-- **FiffCoordTransSet** `[fn]` in [FiffCoordTransSet](/docs/api/fiff/fiff-coord-trans-set) — Constructs the [`FiffCoordTransSet`](/docs/api/fiff/fiff-coord-trans-set).
 - **FiffCov** `[fn]` in [FiffCov](/docs/api/fiff/fiff-cov) — Constructs the covariance data matrix.
 - **FiffCov** `[fn]` in [FiffCov](/docs/api/fiff/fiff-cov) — Constructs a covariance data matrix, by reading from a IO device.
 - **FiffCov** `[fn]` in [FiffCov](/docs/api/fiff/fiff-cov) — Copy constructor.
@@ -2406,6 +2406,7 @@ Index of 6270 public class members (functions, variables, typedefs, enums) acros
 - **headerData** `[fn]` in [FrequencySpectrumModel](/docs/api/disp/frequency-spectrum-model) — Returns the data for the given role and section in the header with the specified orientation.
 - **headerData** `[fn]` in [RtFiffRawViewModel](/docs/api/disp/rt-fiff-raw-view-model) — Returns the data for the given role and section in the header with the specified orientation.
 - **headToDevice** `[fn]` in [PolhemusCoregistration](/docs/api/utils/polhemus-coregistration)
+- **headToMni** `[fn]` in [FiffCoordTransSet](/docs/api/fiff/fiff-coord-trans-set) — Maps MEG head coordinates to MNI Talairach coordinates, as `mne.head_to_mni` does.
 - **headToWorld** `[fn]` in [PolhemusCoregistration](/docs/api/utils/polhemus-coregistration)
 - **height** `[var]` in [MNEVolGeom](/docs/api/mne/mne-vol-geom)
 - **height** `[var]` in `MriSlice` — Height of the image in pixels.
@@ -3316,6 +3317,7 @@ Index of 6270 public class members (functions, variables, typedefs, enums) acros
 - **MNEVolGeom** `[fn]` in [MNEVolGeom](/docs/api/mne/mne-vol-geom) — Constructs the [`MNE`](/docs/api/mne/mne-class) Volume Geometry.
 - **MNI_tal_tal_gtz_t** `[var]` in [FiffCoordTransSet](/docs/api/fiff/fiff-coord-trans-set) — Transform MNI Talairach to FreeSurfer Talairach coordinates (z > 0).
 - **MNI_tal_tal_ltz_t** `[var]` in [FiffCoordTransSet](/docs/api/fiff/fiff-coord-trans-set) — Transform MNI Talairach to FreeSurfer Talairach coordinates (z < 0).
+- **mniToTalairach** `[fn]` in [FiffCoordTransSet](/docs/api/fiff/fiff-coord-trans-set) — Maps MNI Talairach coordinates to FreeSurfer Talairach coordinates, using the transform for points above or below the AC-PC plane (MNI z > 0 or not).
 - **modalitiesChanged** `[signal]` in [ModalitySelectionView](/docs/api/disp/modality-selection-view) — Emit this signal whenever the user changed the modality.
 - **modality** `[fn]` in `RtSensorStreamManager`
 - **modalityChanged** `[signal]` in [DipoleFitView](/docs/api/disp/dipole-fit-view) — Send new modality selection.
@@ -4133,6 +4135,7 @@ Index of 6270 public class members (functions, variables, typedefs, enums) acros
 - **read** `[fn]` in [BidsRawData](/docs/api/bids/bids-raw-data) — Read a BIDS dataset from disk.
 - **read** `[fn]` in [FiffAnnotations](/docs/api/fiff/fiff-annotations) — Auto-detects format and reads annotations.
 - **read** `[fn]` in [FiffCoordTrans](/docs/api/fiff/fiff-coord-trans) — Reads a coordinate transform from a fif file.
+- **read** `[fn]` in [FiffCoordTransSet](/docs/api/fiff/fiff-coord-trans-set) — Takes every transform of the chain stored in a FIFF file, such as a `-trans.fif` file or a `COR.fif` MRI set (MNE-C mne_collect_transforms).
 - **read** `[fn]` in [FiffEvents](/docs/api/fiff/fiff-events) — Read events from a FIFF or ASCII event file.
 - **read** `[fn]` in [FiffEvoked](/docs/api/fiff/fiff-evoked) — fiff_read_evoked
 - **read** `[fn]` in [FiffEvokedSet](/docs/api/fiff/fiff-evoked-set) — fiff_read_evoked
@@ -4246,6 +4249,7 @@ Index of 6270 public class members (functions, variables, typedefs, enums) acros
 - **readMetadata** `[fn]` in `RtDataClient` — Reads fiff metaata class from data connection.
 - **readMNESelFile** `[fn]` in [SelectionIO](/docs/api/utils/selection-io) — Reads the specified MNE sel file.
 - **readMNESelFile** `[fn]` in [SelectionIO](/docs/api/utils/selection-io) — Reads the specified MNE sel file.
+- **readMniTransform** `[fn]` in [FiffCoordTransSet](/docs/api/fiff/fiff-coord-trans-set) — Reads the scanner RAS -> MNI Talairach transform of a FreeSurfer/MNI ``.xfm file (MNE-C read_mni_coord_transform_file).
 - **readMriTransform** `[fn]` in [FiffCoordTrans](/docs/api/fiff/fiff-coord-trans) — Reads the MRI → head coordinate transform from a FIFF file.
 - **readRawBuffer** `[fn]` in `RtDataClient` — Reads fiff measurement information of a data the connection.
 - **readRawSegment** `[fn]` in [AbstractFormatReader](/docs/api/bids/abstract-format-reader) — Read a segment of raw data.
@@ -6202,6 +6206,7 @@ Index of 6270 public class members (functions, variables, typedefs, enums) acros
 - **write** `[fn]` in [BidsRawData](/docs/api/bids/bids-raw-data) — Convenience overload — write with default options.
 - **write** `[fn]` in [FiffAnnotations](/docs/api/fiff/fiff-annotations) — Auto-detects format and writes annotations.
 - **write** `[fn]` in [FiffCoordTrans](/docs/api/fiff/fiff-coord-trans) — Writes the transformation to file.
+- **write** `[fn]` in [FiffCoordTransSet](/docs/api/fiff/fiff-coord-trans-set) — Writes every non-empty transform, head -> MRI first.
 - **write** `[fn]` in [FiffDigPointSet](/docs/api/fiff/fiff-dig-point-set) — Writes the [`FiffDigPointSet`](/docs/api/fiff/fiff-dig-point-set) to a FIFF file.
 - **write** `[fn]` in [FiffDigPointSet](/docs/api/fiff/fiff-dig-point-set) — Convenience overload: write the digitizer point set to a path on disk.
 - **write** `[fn]` in [FiffIO](/docs/api/fiff/fiff-io) — Write data to a single pIODevice.