Back to the main page.

Bug 993 - the different coordinate systems should be better documented in headcoordinates.m and the documentation to ft_volumerealign should be improved

Reported 2011-09-28 12:30:00 +0200
Modified 2011-10-05 15:08:24 +0200
Product: FieldTrip
Component: documentation
Version: unspecified
Hardware: PC
Operating System: Mac OS
Importance: P1 normal
Assigned to: Jan-Mathijs Schoffelen
Depends on:
See also:

Jan-Mathijs Schoffelen - 2011-09-28 12:30:14 +0200

I am going to do this. @ Elli: could you check whether the changes in the documentation (help ft_volumerealign and help private/headcoordinates) make thins a bit less confusing?

Jan-Mathijs Schoffelen - 2011-09-28 13:29:05 +0200

Hi Elli and Beth, I updated some code and documentation in ft_volumerealign and some documentation in private/headcoordinates. Could you check whether it makes sense to you guys? Beth, for this you probably need to have look at the code in our google code repository (, or check out a fresh version of fieldtrip which will become available next night (CET). Thanks.

Eliezer Kanal - 2011-09-28 18:42:22 +0200

The code for the source reconstruction is pretty complicated, so I'm having a hard time reviewing it, but it looks like there's still a problem (code from Rev 4311): ... 446 if basedonfid 447 % the fiducial locations are now specified in voxels, convert them to head 448 % coordinates according to the existing transform matrix 449 nas_head = warp_apply(mri.transform, cfg.fiducial.nas); 450 lpa_head = warp_apply(mri.transform, cfg.fiducial.lpa); 451 rpa_head = warp_apply(mri.transform, cfg.fiducial.rpa); 452 453 % compute the homogenous transformation matrix describing the new coordinate system 454 [realign, coordsys] = headcoordinates(nas_head, lpa_head, rpa_head, cfg.coordsys); 455 456 elseif basedonmrk 457 % the fiducial locations are now specified in voxels, convert them to head 458 % coordinates according to the existing transform matrix 459 ac = warp_apply(mri.transform,; 460 pc = warp_apply(mri.transform, cfg.landmark.pc); 461 xzpoint= warp_apply(mri.transform, cfg.landmark.xzpoint); 462 463 % compute the homogenous transformation matrix describing the new coordinate system 464 [realign, coordsys] = headcoordinates(ac, pc, xzpoint, 'spm'); ## PROBLEM HERE? 465 466 else ... If I understand this correctly, if markers are being used, then the realignment is hardcoded to be relative to the 'spm' system (line 464). That should probably be `cfg.coordsys` like the fiducial case. I imagine that may be why it was ignoring my specified cfg.coordsys.

Eliezer Kanal - 2011-09-28 18:44:53 +0200

(different point, different comment) Regarding the documentation, I like the update. The only improvement I can suggest is to specifically mention that the cfg.coordsys refers to the MEG coordinate system (since the output structure of ft_read_mri also has it's own coordsys... maybe I'm an idiot, but I found the cfg.coordsys one confusing).

Beth Belluscio - 2011-09-29 20:30:12 +0200

Hi Jan-Mathijs, I'm sorry, I could not find the ft_volumerealign code in the google repository. At the moment at the NIH we are not allowed to do our own updates, so I need to wait on someone else to upload the newest version. I have asked for permission to do this myself, but it hasn't happened yet. I will look at it as soon as I can. Sorry for the delay! Beth.

Jan-Mathijs Schoffelen - 2011-09-29 21:08:24 +0200

@ Beth: no problem @ Elli: yes, good point about the hard coded 'spm'. As a matter of fact, once the coordinate system should be based on the landmarks, i.e. ant.comm etc. the only system I can come up with is the spm/tal coordinate system. So as such there's no need to replace it by cfg.coordsys, because that's imposed earlier in the code. Yet, for readability I may change it. BW, JM

Beth Belluscio - 2011-09-29 21:46:15 +0200

JM- I looked at the implementation of the current version (20110928) of ft_volumerealign. I did not look at the code, but I think what I found confusing when I first used it was the instructions that are printed as part of its implementation. This does not look different to me and perhaps you did not intend to change this. However, if you are interested, here is a suggestion for what is printed when the function is called: 1. To change the slice viewed in one plane, either a. click (left mouse) in the image on a different plane. Eg, to view a more superior slice in the horizontal plane, click on a superior position in the coronal plane, or b. use the arrow keys to increase or decrease the slice number by one 2. To mark an anatomical position, do BOTH a. select the position by clicking on it in any slice with the right mouse button b. identify it by pressing either n/l/r for fiducials, or a/p/z for anatomical landmark 3. To unmark or remark a location a. click with the middle mouse button to unmark last position b. select new position with right mouse button and identify it using the keyboard 4. To change the display a. press c or C on keyboard to show/hide crosshair b. press m or M on keyboard to show/hide marked positions 5. To finalize markers and quit interactive mode, press q on keyboard 6. Close figure This may be too much, or may assume less intelligence than the average user, but it would have helped me. I didn't quite understand that I needed to both mark the position with the crosshair AND indicate the identity with the keyboard. Beth.

Jan-Mathijs Schoffelen - 2011-10-03 14:54:28 +0200

Hi Beth, I indeed did not consider changing the output text to the screen. But I like your suggestion! I modified it a bit and built it into the function. Thanks for the suggestions.

Beth Belluscio - 2011-10-03 15:02:32 +0200

OK, thanks. I'm probably most helpful at this stage with regard to how a naive user reads the tutorials and other documentation. Hopefully as time goes on I'll be able to give input on code, but I'm not there yet! Beth.

Jan-Mathijs Schoffelen - 2011-10-03 15:08:08 +0200

Hi Beth, Thanks, no problem. I also updated the text which appears on the screen when typing 'help ft_volumerealign'. I was hinting at this text to see whether it makes sense.

Beth Belluscio - 2011-10-03 16:30:19 +0200

JM- The help screen does make sense. You might want to consider, though, moving the instructions for specifying the position of the fiducials (cfg.fiducial.nas etc) in the same section as the description of the 'fiducial' method. Likewise for the 'landmark' method. Then, in the section for 'interactive' you may want to expand slightly to describe that this method allows one to click on the image of the brain to identify either fiducials or anatomical landmarks without having to know their coordinates. I think this arrangement would make it most clear that these are 3 different approaches, with different input requirements. This point is obvious if you are following a tutorial that instructs you to use the interactive mode, but may not be obvious to someone who encounters the volumerealign function for the first time through the help menu. Beth.