Index TableOfContents

Labels, Color Lookup Tables and Annotation Files

This page discusses the basic concepts of FreeSurfer files that relate to identifying regions-of-interest for surfaces and volumes.

Label

A label is an integer value which can be associated with a surface mesh vertex, or with a voxel, to indicate that it belongs to some region of interest. This could mark the vertex or voxel as part of an anatomical region, or it could mark the vertex/voxel as part of a region for analysis.

Sometimes when speaking or writing loosely, the word "label" is used as shorthand for "the set of vertices marked with a particular label". Sometimes vertices are said to "belong to a label", meaning that these vertices belong to the set marked by that label. "Saving a label" refers to saving into a file the list of vertices marked by a particular label value.

Label file

A label file is a text file capturing a list of vertices belonging to a region, including their spatial positions(using R,A,S coordinates). A label file corresponds only to a single label, thus contains only a single list of vertices.

Because both vertex number and corresponding position are listed, a label file can be used by either tksurfer or tkmedit to identify surface or volume locations belonging to the region.

It should be noted that a label file's vertex numbers will apply to several surfaces of a subject: for example the white surface, the pial surface, the inflated surface and so on. However the R,A,S positions are those of a particular one of these surfaces, according to selections in effect when the label file was saved by tksurfer.

Perhaps surprisingly, a label file contains neither the label code nor label name that it pertains to. Instead it is conventional to name the label file in a manner that indicates the label intended, though this naming convention has varied over the years. Examples:

Label file format

1806
7  -22.796  -66.405  -29.582 0.000000
89  -22.273  -43.118  -24.069 0.000000
138  -14.142  -81.495  -30.903 0.000000
[...]

Row

Col1

Col2

Col3

Col4

Col5

1

Comment

2

Count of subsequent rows

3..end

Vertex num

R coord

A coord

S coord

Don't know

Color Lookup Table

In FreeSurfer a "color lookup table" is a table cross-referencing the integer label code to a name, and to a color (Red, Green, Blue and Opacity values). Although called a "color lookup", in many usages it is the cross-reference to name, or simply the list of names, which is important.

Color Lookup Table file

FreeSurfer is supplied with a standard color lookup table in the file FreeSurferColorLUT.txt, which needs to be loaded into tksurfer or tkmedit for some display situations, for example in order to color regions when showing labels.

FreeSurferColorLUT.txt can be edited (probably not recommended), or other similar files can be prepared for purposes such as customizing the colors or working with additional regions.

Color Lookup Table file format

#$Id: FreeSurferColorLUT.txt,v 1.38.2.1 2007/08/20 01:52:07 nicks Exp $
#No. Label Name:                            R   G   B   A
0   Unknown                                 0   0   0   0
1   Left-Cerebral-Exterior                  205 62  78  0
2   Left-Cerebral-White-Matter              245 245 245 0
3   Left-Cerebral-Cortex                    205 62  78  0

Row

Col1

Col2

Col3

Col4

Col5

Col5

1

Comment (version info)

2

Comment (col headings)

3..

Label code

Label name

Red

Green

Blue

Opacity

Annotation

In FreeSurfer jargon, "annotation" refers to a collection of labels (ie: sets of vertices marked by label values) and often an associated color table (recalling that a color table importantly includes cross-reference from label code to label name).

Annotation file

An annotation file amalgamates information from one or more label files, usually along with a color (and label-name) lookup table. It thus represents a more-complete packaging of information that one would want to keep together when marking up regions on a surface (or in a volume).

The programs ["mris_label2annot"] and ["mri_annotation2label"] are used to assembled and disassemble annotation files from/to label/CLUT files.

It may be worth noting that label files explicitly list each vertex belonging to a set, which may be a few, or many. Taken together, two or more label files could mention a particular vertex once, or never, or two or more times.

By contrast, an annotation file contains a single list including all vertices, with only a slot for one label value for each vertex. If ["mris_label2annot"] encounters two or more label values for a vertex, only the last-encountered one is retained. (mris_label2annot does include a diagnostic option to help find multiply labeled vertices).

Annotation file format

(Note: From source code, but not actually confirmed independently by my own code --GW) The annotation file is a binary file with approximately the following format.

Count

Group

Item

Type

Description

1

vtxct

int

Vertex count

vtxct

Vertex data

vno

int

Vertex number, counting from zero

label

int

Label value

1

ctabct

int

Color table row count

ctabct

Color table row

skip

int

Don't know

skip

int

Don't know

Related pages

Document Author/s

GrahamWideman