Index

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, namely labels, so-called color lookup tables, and annotations.

In each case, the concept is discussed first, followed by a description of the file that is used to capture data for each kind of concept, and the detailed format of that file. The detailed file description is useful in clarifying exactly what each concept refers to, and how one might expect to interact with it within tksurfer or tkmedit.

Label

A label is an integer value, or a name (depending on context) which can be associated with a vertex of a surface mesh, or with a voxel of an MRI volume, to indicate that it belongs to some region of interest. Vertices marked with the same label value are said to "belong to the same label". This could mark the vertices/voxels as part of an anatomical region, or as part of a region-of-interest for analysis.

"Saving a label" refers to saving into a file the list of vertices marked by a single particular label value.

Associating label values with vertices enables manipulating sets of vertices. In order to distinctly display these sets in tksurfer (or labeled locations in tkmedit), a color lookup table, translating label to color, is also required -- described below.

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 contents and 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:

Although called a "color lookup", in many usages it is the cross-reference to caption, or simply the list of captions, which a program uses.

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 contents and 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

At a broad-brush level, an annotation file amalgamates information from one or more label files, usually along with a color (and label-caption) 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 assemble and disassemble annotation files from/to label/CLUT files.

It may be worth noting that a label file explicitly lists each vertex belonging to a single set, which may be a few vertices, 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's vertex data consists of a single list including all vertices, with exactly one entry for each vertex. (The annotation file format doesn't guarantee this, but it is implemented this way in MRISwriteAnnotation(). More on this below.)

So, for example, when converting label files into an annotation file, 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 contents and format

The annotation file is a binary file with the following format. (Verified by virtue of my writing code to extract the LUT information --GW)

Count

Group

Item

Type

Description

1

vtxct

int4

Vertex count. This should be the complete count of vertices for the surface to which the labels were associated

vtxct

Vertex data

vno

int4

Vertex number, (0..vtxct-1)

Vertex data

label

int4

Annotation value (see note below)

1

tag

int4

Tag "TAG_OLD_COLORTABLE" indicating a color table comes next

1

ctabversion

int4

>0 means "old format", <0 means "new format" (new shown below)

1

maxstruc

int4

Max structure index (could be more than actual entries, since some may be omitted)

1

len

int4

Length of subsequent string

1

fname

string

File name

1

num_entries

int4

Count of LUT entries

num_entries

LUT

Label

int4

Label number (also called "structure" number)

LUT

len

int4

Length of subsequent string

LUT

labelname

string

Name of label (= structure name)

LUT

red

int4

Red value 0..255

LUT

green

int4

Green value 0..255

LUT

blue

int4

Blue value 0..255

LUT

transp

int4

Transparency = 255-Alpha

Notes:

Annotation file design surprise

As noted above, an annotation file seems like an amalgam of multiple label files plus a label-code/color/label-caption table ("ColorLUT"). One might therefore expect a couple of things about the per-vertex data:

However, the design of this file format undermines both of those expectations.

Code that loads an annotation file (eg: labl_import_annotation in tksurfer) has to compare annotation values to the color values in the ColorLUT part of the annotation file to discover what parcellation label code (ie: structure code) corresponds.

The fact that the "ColorLUT" is called a "Color Lookup Table" in the first place asserts the idea that the label code is used to look up the color. With the annotation file, the reverse is needed: the color has to be used to look up the label code.

This has several awkward consequences:

Additionally, this confusion between the annotation of a vertex versus the label of a vertex extends to tksurfer. There, it is possible to recolor a region's vertices to match the vertices of another region. At that point, though the colors match, the vertices in the two regions retain their different labels. However, if this state of annotation is saved to a file, the per-vertex data saves the annotation values (ie: colors) only , and thus no longer distinguishes the two regions, which can be seen when the annotation file is reloaded into tksurfer.

Related terminology issues

The vocabulary in this area of FreeSurfer has not been tightly controlled, leading to confusion as to what different words actually refer to the same things, and instances where the same word refers to different things.

Related pages

Outstanding Issues

Not currently fully understood by me (GW, 2008-01-19) is the treatment of multiple labels-per-vertex in tksurfer. Under certain conditions, vertices can acquire multiple label values (as judged by the control panel display of labels attached to vertex at cursor). However, I haven't got to the bottom of how to work with these (save, load, display, edit).

Document Author(s)

Graham Wideman (GrahamWideman)

LabelsClutsAnnotationFiles (last edited 2018-09-28 13:42:03 by 66)