[Neuroimaging] NiBabel - Streamlines API - TRK header extension

Thu May 26 15:31:36 EDT 2016

Hi Marc-Alex,

+1 for option 1. I think it is a useful addition and it will not be
disruptive for the developers or users who use the trk format. However, we
should move beyond the Trackvis format as soon as possible. There are many
limitations on the format that make it especially time consuming for
loading and saving large datasets. And the datasets continue grow day by
day.

So, I suggest to move ahead with option 1 and merge the PR asap. After that
let's go back to the previous discussion of what should be the correct
format for modern tractograms and not spend more time on filling up
different corner cases of the Trackvis format.

Thanks!

Cheers,
Eleftherios

On Thu, May 26, 2016 at 11:16 AM Marc-Alexandre Côté <marc.cote.19 at gmail.com>
wrote:

> On 16-05-26 09:56 AM, Jean-Christophe Houde wrote:
>
> Hi Marc-Alex,
>
> a few small things:
>
> - you say you can save 20 property tags and 20  scalar tags. However, in
> the trk format description you linked, it seems to say only 10 for each.
>
> You are right, it is 10 for each not 20.
>
>
> - For your example file, I guess that means you'd be saving using the hack
> so you know that the first 3 properties written for a track are the RGB
> components, and the follwoing 2 are the mean curvature and mean torsion.
> Just to make sure I understand, that means that you would set n_properties
> to 5, to reflect the total number?
>
> Yes, the n_properties would be set to the total number of values
> associated to properties, in this case 5.
>
>
> If you can share your example file, I'd like to load it in our soft to
> check the compatibility (pretty sure we would be willing to support that).
>
> The file I used is the following:
>
> https://github.com/MarcCote/nibabel/blob/streamlines_api/nibabel/streamlines/tests/data/complex.trk
> Note that this file contains 3 streamlines composed of 1, 2 and 3 random
> points respectively, so they might not be displayable.
>
> Also, regarding your software, can you check that
>
> https://github.com/MarcCote/nibabel/blob/streamlines_api/nibabel/streamlines/tests/data/standard.trk
> is displayed correctly on top of
>
> https://github.com/MarcCote/nibabel/blob/streamlines_api/nibabel/streamlines/tests/data/standard.nii.gz
> as expected (I tested it with TrackVis and dipy.viz and both are
> displaying it correctly).
>
>
> --
> JC
>
> 2016-05-26 8:07 GMT-04:00 Marc <marc.cote.19 at gmail.com>:
>
>> 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
>>
>>
>> _______________________________________________
>> Neuroimaging mailing list
>> Neuroimaging at python.org
>> https://mail.python.org/mailman/listinfo/neuroimaging
>>
>>
>
>
> _______________________________________________
> Neuroimaging mailing listNeuroimaging at python.orghttps://mail.python.org/mailman/listinfo/neuroimaging
>
>
> _______________________________________________
> Neuroimaging mailing list
> Neuroimaging at python.org
> https://mail.python.org/mailman/listinfo/neuroimaging
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/neuroimaging/attachments/20160526/6a8b95b9/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/6a8b95b9/attachment.png>
-------------- 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/6a8b95b9/attachment-0001.png>