[Brains-users] New b2 commands::FreeFurfer labels on GTSurfaces

[Greg Harris]

This announcement documents a (relatively) new ability in brains2
to work with FreeSurfer-generated parcellation labels.

'b2 filter-list GTSurface' now exhibits a 'FreeSurfer' filter
for use by 'b2 load GTSurface'.

You can load a FreeSurfer parcellation file this way:
b2 load GTSurface 
/raid1/structural/MR/8823080/0177395/10_ACPC/FreeSurfer_Subjects/Parcellate_0177395/surf/lh.orig

Although the FreeSurfer GTS filter has also picked up the labels info 
from the sister file
.../10_ACPC/FreeSurfer_Subjects/Parcellate_0177395/label/lh.aparc.annot
the parcellation will not be visible until you do 'b2 color GTSurface 
labels gts1  0'
(the '0' is the label family, which is always 0, so far), and then 
select the gts1
object's display properties User Color button.

The new command 'b2 convert GTSurface-set to code-image' is designed
to take a left and right hemisphere GTSurface, an enclosing brain mask
and a label family (which is always 0, so far), and produce a labeled 3D 
image
that classifies space within the mask as to what is the label of the closest
point on any of the surfaces.

For example,
b2 load Mask /raid1/structural/MR/8823080/0177395/10_ACPC/cran_mask.segment
b2 convert GTSurface-set to code-image m1 0 {gts1 gts2}
generates an image you can then convert to masks with
'b2 convert code-image to mask-set'.

= = = APPENDIX = = =
Usage   b2 color GTSurface labels [GTSurface_index] [labelFamilyNumber] 
{{red green blue alpha}, ...}

Description     Color code regions of the surface by decoding one
             of the surface's label families. Any udefined regions
             remain the original gold color.

[surfaceID]     An identifier for a surface

[labelFamilyNumber]     Usually 0 since there is only one label family 
possible

[color-list]    An optional of colors for coding the surface.
             The list is of the form {{red green blue alpha}, ...}
             When omitted the colors are copied from a standard
             table supplied with FreeSurfer.
Return          Upon successful completion, 0 is returned,
                otherwise an error status of -1 is returned

= = = APPENDIX = = =
Usage   b2 convert GTSurface-set to code-image  [maskID] 
[labelFamilyNumber] [GTSurface-list]

Description     This is one of the ways to find a cortical
             ribbon-of-interest, in this case based on a set of
             GTSurfaces, a selection mask, AND most importantly,
             a parcellation label family to define the set of regions.
             See Also: 'b2 convert code-image to mask-set'.

[maskID]        An identifier for a mask

[labelFamilyNumber]     Usually 0 since there is only one label family 
possible

[GTSurface-list]        A set of GTSurfaces.  Voxel labeling will be
             based on the FreeSurfer-generated vertex labeling.

Return          Upon successful completion a newly created
                object identifier is returned,  otherwise
                an error status of -1 is returned.

= = = APPENDIX = = =
Usage   b2 convert code-image to mask-set [image]  [mask-name-list]

Description     (for cortical parcellation v. II)
             Decodes a (warped,  nearest-neighbor-resampled) atlas
             mask partition image.
             See Also: 'b2 convert mask-set to code-image'.

[imageID]       An identifier for an image

[mask-name-list]        Tcl list of names to give the code-image regions.
             If you give 'standard', you get the FreeSurfer Simple
             atlas names.  The list's elements indexed 0 through N-1
             are assigned to image codes 1 through N, respectively.

Return  Returns a list of disjoint masks in sublist pairs beginning with
             the name in question.  If the method 'fails', an error
             status of -1 is returned.