[Neuroimaging] NiBabel - Streamlines API - TRK header extension

[Marc]

Hi everyone,

I'm currently working on an API for streamlines in NiBabel and I would 
like the feedback of the Nipy community about an unofficial extension 
for the TRK header.

Right now, the TrackVis's file format for streamlines supports 
conserving additional information for each point and/or streamline. The 
format refers to that additional information as "scalars" and 
"properties" respectively (ref: 
http://www.trackvis.org/docs/?subsect=fileformat). There is a field in 
the header to keep a tag name for the first 20 scalars and the first 20 
properties even though the format supports having up to 2^16 scalars and 
2^16 properties.

First, 20 is not a lot when you think of all the metrics one could want 
to keep (e.g. color, FA, curvature, torsion, MD, cluster ID, etc.) in 
its tractogram file. On top of that, some of these metrics consist of 
more than one value, for instance the color is in fact composed of three 
values (i.e. RGB). I find it a bit wasteful to use up multiple tag names 
only because it is composed of multiple values.

What I proposed is to encode that number of values in the tag name at 
save time and take that encoded number into account when loading a TRK 
file. I have two ways in mind and I would like your opinion.

*1st approach*
A tag name can only have 20 characters/bytes. I would use the last two 
bytes to encode the number of values associated to a given tag name. The 
first byte would always be \x00 (EOL) so that TrackVis doesn't try to 
interpret the last byte which will be set to the number of values (since 
it is a uint8 the range is [0, 255]). The upside of this approach is 
that TrackVis is not aware (read doesn't crash) thanks to the \x00 
"hack". The downside is that a TrackVis's user will be less aware of 
what's going on behind the scene but a NiBabel's user won't see a 
difference since we revert the process when loading the TRK file.

*2nd approach
*This consists of simply adding the number of values in plain ascii text 
as follows: "property_name-n=3" (or a better naming convention if you 
have one). The upside is the TrackVis's user will see how many values a 
given scalar/property is composed of. The downside is it will use up 
more valuable characters as the number of values gets bigger.

That said, no matter the approach, there is another small downside. 
Coming back to the color example, TrackVis will associate the tag name 
only for the first value (R) and the remaining two values (GB) will have 
an empty tag name. The following picture shows a TRK file, written using 
the first approach, that has been loaded in TrackVis. The properties 
(values per streamline) saved are a color (RGB), the mean curvature and 
the mean torsion of a streamline.




For more information see the following PR: 
https://github.com/nipy/nibabel/pull/391/

Thanks for your feedback.

-- 
Marc

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/neuroimaging/attachments/20160526/40c76ca5/attachment.html>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: image/png
Size: 24501 bytes
Desc: not available
URL: <http://mail.python.org/pipermail/neuroimaging/attachments/20160526/40c76ca5/attachment.png>