MRG Freesurfer coordinate frame tutorial

[larsoner]

The idea is to help people gain fluency with the Freesurfer coordinate frame (since we use it extensively), as well as some stuff about relationships between MRI voxels and affines/MRI coordinate frame. It's not done but at least gets some content out there.

Also makes much nicer some of our info repr stuff (dig, chs entries) by ensuring that on read the constants become "named constants", so that instead of seeing this on master:

>>> import mne
>>> from pprint import pprint
>>> info = mne.io.read_info(mne.datasets.sample.data_path() + '/MEG/sample/sample_audvis_raw.fif')
>>> pprint(info['chs'][0])
{'cal': 3.1600000394149674e-09,
 'ch_name': 'MEG 0113',
 'coil_type': 3012,
 'coord_frame': 1 (FIFFV_COORD_DEVICE),
 'kind': 1,
 'loc': array([-0.1066    ,  0.0464    , -0.0604    , -0.0127    ,  0.0057    ,
       -0.99990302, -0.186801  , -0.98240298, -0.0033    , -0.98232698,
        0.18674099,  0.013541  ]),
 'logno': 113,
 'range': 0.00030517578125,
 'scanno': 1,
 'unit': 201,
 'unit_mul': 0}

You get:

>>> pprint(info['chs'][0])
{'cal': 3.1600000394149674e-09,
 'ch_name': 'MEG 0113',
 'coil_type': 3012 (FIFFV_COIL_VV_PLANAR_T1),
 'coord_frame': 1 (FIFFV_COORD_DEVICE),
 'kind': 1 (FIFFV_MEG_CH),
 'loc': array([-0.1066    ,  0.0464    , -0.0604    , -0.0127    ,  0.0057    ,
       -0.99990302, -0.186801  , -0.98240298, -0.0033    , -0.98232698,
        0.18674099,  0.013541  ]),
 'logno': 113,
 'range': 0.00030517578125,
 'scanno': 1,
 'unit': 201 (FIFF_UNIT_T_M),
 'unit_mul': 0 (FIFF_UNITM_NONE)}

Todo:

• Better explanation of Freesurfer surface RAS (how it's defined)
• Surfaces (read in, show, units)
• Surface alignment (fsave, fsave sph, sample sph, sample)
• Surface decimation (show sphere, etc.)
• Link to forward tutorial or something that talks about vertex removal, probably a .. warn to take care of DOC: morph generated from src does not work because fwd exlcude some vertices #7007 (modify the morph tutorials and errors also?)
• Source space entries (use_tris, etc.)

[larsoner]

So far:

https://19221-1301584-gh.circle-artifacts.com/0/dev/auto_tutorials/source-modeling/plot_freesurfer_coordinate_frames.html

[codecov]

Codecov Report

Merging #7578 into master will decrease coverage by 0.00%.
The diff coverage is 100.00%.

@@            Coverage Diff             @@
##           master    #7578      +/-   ##
==========================================
- Coverage   90.13%   90.13%   -0.01%     
==========================================
  Files         452      452              
  Lines       82876    82973      +97     
  Branches    13101    13121      +20     
==========================================
+ Hits        74697    74784      +87     
- Misses       5350     5356       +6     
- Partials     2829     2833       +4     

[drammock]

@larsoner I've pushed an expansion of the freesurfer tutorial, mostly just adding prose to the explanations without changing the code very substantively. I feel like it ends kind of abruptly, not sure if there's a good way of summarizing / wrapping up / adding some "see also" text?

[larsoner]

I updated the top comment with other stuff I plan to add, WDYT?

[drammock]

TODO list seems reasonable. I added one item: explanation of how "freesurfer surface RAS" is defined. So far we only say "it's different from nibabel's RAS, and the transform from voxels is called..." without ever saying how it's different. I tried reading the Freesurfer PPT slides that allegedly explain it, but if the answer is in there I was not smart/patient enough to extract it.

[larsoner]

Yes, that has been my experience as well :)

I'll have to read and/or talk more to figure that out, but I agree it's worth doing...

[larsoner]

@wmvanvliet @hoechenberger I think I addressed your comments with the latest commit. (Had to force push to deal with a rebase problem)

[hoechenberger]

Built documentation: https://21054-1301584-gh.circle-artifacts.com/0/dev/auto_tutorials/source-modeling/plot_freesurfer_coordinate_frames.html#sphx-glr-auto-tutorials-source-modeling-plot-freesurfer-coordinate-frames-py

[hoechenberger]

Awesome work, @larsoner! No change requests from my side :)

[susamerz]

I like the hands on, step by step approach of the rest of the tutorial, but the following sentence had my (slightly sleep deprived) brain run out of processing capacity, even though I know the underlying theory:

" These data are voxel intensity values (unsigned integers in the range 0-255). A value data[i, j, k] at a given index triplet (i, j, k) is located at real-world (x, y, z) positions (in RAS orientation) in the scanner’s native coordinate frame (defined during acquisition) by the image’s affine transformation"

Trying to parse this I get:
These data are voxel intensity values (unsigned integers in the range 0-255). A value data[i, j, k] at a given index triplet (i, j, k) is located at real-world (x, y, z) positions (in RAS orientation).
The x y and z positions are in the scanners coordinate frame, which is defined during acquisition.
The relationship between the [i,j,k] index and the x, y, z coordinates is saved (or written?) in the images affine transformation.

Is this interpretation the intended one? If yes, feel free to use that wording, if no, please clarify :)

[wmvanvliet]

I agree with @susamerz's comment. Otherwise, I'm very happy with this, great work @larsoner!

[larsoner]

Okay addressed comments hopefully, @susamerz can you look again at the description of the affine?

I also added the rest of the missing content. @wmvanvliet @hoechenberger want to take another look to see if the new sections make sense to you?

https://21085-1301584-gh.circle-artifacts.com/0/dev/auto_tutorials/source-modeling/plot_background_freesurfer_mne.html

@GuillaumeFavelier can you look at the 3D plotting bits and advise how to avoid using a private function? Maybe we need to expose how to get a renderer? Also take a look at the changes I needed to make to the renderer code in general, it was necessary to:

1. get things to plot the same in mayavi and PyVista
2. allow wireframe rendering (needed for this tutorial)

Once the 3D plotting issues are taken care of this will be ready for review/merge.

[drammock]

some suggestions for clarity/flow

[hoechenberger]

Awesome!

[wmvanvliet]

cool!