-------------------------------------------
vars,functs (left-click): for assemble labels into annotation
  set lulabel <SomeColorLUT.txt> 
  set anlabel <$hemi-MY_ANNOT.annot>
  write_mgh_annot
-------------------------------------------

This assembles multiple labels into a single MGH
annotation file using the region names (i.e.,
labelfile prefixes) and matching colors from an
MGH FreeSurfer LUT file.

(1) MGH FreeSurfer Color Lookup Table (LUT)
  [default name:]
  $CSURF_DIR/lib/lut/CsurfColorLUT.txt

(2) output .annot file
  [default name:]
  $SUBJECTS_DIR/$subject/label/$hemi-MY_ANNOT.annot

The dropdowns are loaded with all *.txt and
*.annot files in the default directories.

Change the "MY_ANNOT" infix to something more
useful (this is the default to avoid accidental
overwrites).  Here is an example of the format of
an MGH FreeSurfer LUT file (empty lines or lines
starting with '#' are ignored).

#!ascii , CsurfColorLUT.txt (in $CSURF_DIR/lib/lut)
#------------------------------------------
#id	region(=labelinfix)		R      G      B      A
#------------------------------------------
 0	Unknown		0      0       0       0
 1	V1_lower		150   0      100    0
 2	V1_upper		150   0      120    0
14	V3_lower		0      50     200    0
15	VP_upper		0      50     220    0

N.B.: Though csurf tksurfer will accept and
display a FreeSurfer Color LUT containing
non-zero values for column A (alpha,
transparency), MGH tksurfer/freeview requires
that the color LUT value of alpha always be 0
(100% transparent, AKA invisible).  Therefore,
for compatibility, always use 0 as the last entry
in each FreeSurfer Color LUT line.  The
transparency of all labels can be adjusted
afterward with set_annot_alpha.

Each region or structure name (except "Unknown")
must have a corresponding csurf dash-style label
file in the current subject's label directory.
Using the example above for the right hemisphere
of the subject, fsaverage, the following label
files must exist:

  $SUBJECTS_DIR/fsaverage/label/rh-V1_lower.label
  $SUBJECTS_DIR/fsaverage/label/rh-V1_upper.label
  $SUBJECTS_DIR/fsaverage/label/rh-V3_lower.label
  $SUBJECTS_DIR/fsaverage/label/rh-VP_upper.label

If any are missing, they will be omitted from the
final combined annotation file.

Finally, click READY to assemble an MGH
annotation file containing these labels in these
colors.  The new assembled annotation file will
be displayed, followed by the number of hits per
vertex (this will be 2 on borders).  To
re-display the assembled annotation at another
time, select it, and use "D" on the "label:"
line.

The process will fail if there are any duplicate
region id numbers *or* duplicate colors in the
color LUT file (duplicates reported in popup).

The number of hits per vertex (e.g., if labels
overlap) is saved into the .stat field and
swapped to the surface at the end to make it
visible.  To save it, select a new wfile name
(e.g., <annotname>_nhits-$hemi.w) and use "W" on
the "val:" line.  The last label file that
contains a vertex sets the structure name and
color for that vertex in the annotation file.

Vertices on the surface not included in any label
will be given structure name "Unknown" and will
always be displayed as completely transparent
(alpha=0).  The transparency of all other
structures is controlled by the "tran" entry at
the upper right.

How to do this procedure with a tcl script:

  ### set infile (default, but any source OK)
  set lulabel $CSURF_DIR/lib/lut/CsurfColorLUT.txt
  ### set outfile (setfile is csurf-specific glob)
  setfile anlabel ~/label/$hemi-MY_ANNOT.annot
  write_mgh_annot
