Note: There are a bunch of problems with this page. I've made some notes, but the result is not very satisfactory. -- GW

An annotation file contains labels of a surface, for example the sulci and gyri labels of a cortical surface. (... but only indirectly, as it actually records annotation values aka colors, NOT region labels. Labels can be derived from the colors given the ColorLut that's usually included. --GW) It is usally found in the subject_identifier/label/ folder. There is a separate annotation for left and right hemisphere, e.g. ?h.aparc.annot

This page tells you how to display an annotation on tksurfer, read an annotation file into matlab or freesurfer.

(Readers stumbling across this page might also like LabelsClutsAnnotationFiles --GW)

Overlay Annotation on Surface in Tksurfer

(... here "Overlay" just means "Show". In tksurfer, "overlay" is something else. --GW)

(1) Start tksurfer as usual: e.g. tksurfer subject lh inflated

(2) Click on pull down menu: File -> Select Label -> Import Annotation

(3) Browse and find the annotation file (they are usually found in the label folder)

(4) Select and click ok. This will show the labels on the brain. (Not exactly. It shows annotation colors on the surface, and these often correspond to labels. --GW)

(5) To change view, click on pull-down menu: view->label style->outline.

Faster way

(1) ctrl-right click on "Show Labels" Button

(2) Browse and find the annotation file (they are usually found in the label folder)

(3) Select and click ok. This will show the labels on the brain.

(4) To change view, click on "Draw Outlined Labels" button

Reading Into Matlab

[v, L, ct] = read_annotation(annotation_filename);

Suppose N is the number of vertices. Then,

(1) v = N x 1 vector, v(i) = i-1 (you can usually ignore v)

(2) L = N x 1 vector, L(i) = label of ith vertex of mesh

(Not label, but rather annotation value. It looks to me like read_annotation reads in the array of annotation values, and does not translate those values to label numbers. --GW)

(3) ct = colortable structure

What is a colortable (matlab version, see freesurfer version below)

The colortable matches the label number (aka structure number -- GW) with the structure name. It also gives color to each label/structure for visualization in tksurfer. In matlab, the colortable structure can be dissected as follows.

(1) ct.numEntries = # structures that are specified (scalar)

(2) ct.orig_tab = location (filepath -- GW) of original colortable (string). It's mainly for book-keeping

(3) ct.struct_names = list of structure names (cell). The number of strings should be equal to the number of entries. For example, ct.struct_names{1} could be 'central sulcus'

(4) ct.table = ct.numEntries x 5 matrix. Row i describes the color and label of the ith structure. ct.table(1,j) specifies the red color value of structure j (0 to 255). ct.table(2,j) specifies the green color value of structure j (0 to 255). ct.table(3, j) specifies the blue color value of structure j (0 to 255). ct.table(4,j) is all zeros (and is currently not used for anything). Finally ct.table(5,j) = ct.table(1,j) + ct.table(2,j)*2⁸ + ct.table(3,j)*2¹⁶ + 0*2²⁴ = label given to structure j.

Therefore if vertex i is labeled structure j. Then L(i) = ct.table(5, j). (The i's and j's here are confused -- GW).

Reading Annotation Files into Freesurfer

(1) #include "mrisurf.h"

(2) use function: int MRISreadAnnotation (MRI_SURFACE *mris, char *sname).

(3) Returns NO_ERROR if successful.

(4) *mris is the freesurfer surface structure

(5) sname is the filename of the annotation file. sname can be the full path or just the filename. If it's not a full path, then function will use the directory where the surface mris was read from.

(6) (For each vertex...) The read annotation (value) is stored in the field mris->vertices[vertex number].annotation (look at mrisurf.h for more details). Note that mris->vertices[vertex number].annotation takes on values defined by the colortable. (Only sort of. First vtx->annotation gets the annotation value from the file, with no intervention of data from the colortable. It is indeed likely that annotation values may be found in the color part of the color table, but not necessarily so.--GW).

This is explained in the previous section on "What is a colortable".

(7) If a colortable exists in the annotation file (which in general it should), then the colortable is stored in mris->ct. Note that the colortable in freesurfer is structured differently from that in matlab, but they basically contain the same information. See below:

Colortable (Freesurfer version)

The colortable matches the label with the structure name. It also gives color to each structure type for visualization in tksurfer.

mris->ct is the pointer to the colortable struct that freesurfer uses. It's different from the matlab version of colortable. The structure can be found in colortab.h, but it can be summarized as follows:

(1) mris->ct->nentries = # entries in colortable (i.e. the number of structures defined by colortable)

(2) mris->ct->CTE[entry number] = pointer to a colortable entry (CTE).

(3) mris->ct->CTE[n]->name = structure name of the nth structure in the colortable

(4) mris->ct->CTE[n]->ri = red color [0-255] of the nth structure, BR mris->ct->CTE[n]->gi = green color [0-255] of the nth structure, BR mris->ct->CTE[n]->bi = blue color [0-255] of the nth structure, BR mris->ct->CTE[n]->ai = 0 (and this number is currently not used for anything).

(5) mris->ct->CTE[n]->rf, mris->ct->CTE[n]->gf, mris->ct->CTE[n]->bf, mris->ct->CTE[n]->af are the corresponding values but from 0 to 1.

Document Author(s)

Not known