Differences between revisions 23 and 24
Deletions are marked like this. Additions are marked like this.
Line 74: Line 74:
The programs ["mris_label2annot"] and ["mri_annotation2label"] are used to assembled and disassemble annotation files from/to label/CLUT files. The programs ["mris_label2annot"] and ["mri_annotation2label"] are used to assemble and disassemble annotation files from/to label/CLUT files.

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, 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 or 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 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:

  • lh.cortex.label
  • lh-avg_calcarine_sulcus.label.

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

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 assemble 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's label data consists of a single list including all vertices, with exactly 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 contents and format

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

Count

Group

Item

Type

Description

1

vtxct

int

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

vtxct

Vertex data

vno

int

Vertex number, 0..vtxct-1

Vertex data

label

int

Label value

1

acount

int

Count of something

acount

Not used

skip

int

Don't know

Not used

skip

int

Don't know

1

tag

int

Tag "TAG_OLD_COLORTABLE" indicating a color table comes next

1

ctabversion

int

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

1

maxstruc

int

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

1

len

int

Length of subsequent string

1

fname

string

File name

1

num_entries

int

Count of LUT entries

num_entries

LUT

Label

int

Label number (also called "structure" number)

LUT

len

int

Length of subsequent string

LUT

labelname

string

Name of label (= structure name)

LUT

red

int

Red value 0..255

LUT

green

int

Green value 0..255

LUT

blue

int

Blue value 0..255

LUT

transp

int

Transparency = 255-Alpha

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.

  • "Annotation index" and "structure number" are sometimes used to refer to label number.
  • "Parcellation" is the word usually used to refer to the labeling of the anatomical regions of cortical surface, whereas "segmentation" is usually used for the labelling of tissues, for example in an MRI volume. A surface parcellation (eg: aparc) is captured by attaching labels to vertices, and storing the result in either a set of label files, or more likely an annotation file. But an alternate approach taken by some programs is to capture the list of per-vertex labels in an array, and store that in a file whose format looks like FS's mgh MRI format. This is referred to as a "volume-encoded surface segmentation file". It's not volume data, and here the word "segmentation" is being used where the effect is elsewhere known as "parcellation".

Related pages

  • AnnotFiles : Some brief end-user notes on annotation files, plus MatLab and C developer notes.

  • ["mris_label2annot"] : Documentation for the command-line program that amalgamates label files (plus optional color lookup table file) into a single annotation file.
  • ["mri_annotation2label"] : Documentation for the command-line program that breaks an annotation file into individual label files
  • EditingLabels : Pointers to a couple of pages about labels

  • TkSurferGuide/TkSurferWorkingWithData/TkSurferLabel : Working with labels

Document Author/s

GrahamWideman

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