-------------------------------------------
entry variable: $label -- absolute name labelfile
def: $SUBJECTS_DIR/$name/label/$hemi-MY_AREA.label
-------------------------------------------
entry variable: $anlabel -- abs name annotation file
def: $SUBJECTS_DIR/$name/label/$hemi.aparc.annot
[dropdown also loads: *.poi, *.obj]
-------------------------------------------

The "label:" entry shows the current label file,
which could be any one the the following:

  single-area freesurfer label   (*.label, ASCII)
  multi-label MGH annotation  (*.annot, MSB binary)
  multi-label GIFTI annotation  (*.gii, ASCII)
  BV patches-of-interest file    (*.poi, ASCII)
  Wavefront surf+col as annot (*.obj, ASCII)
  vertex color file                   (*.cols, ASCII)

No file is loaded at startup.  The dropdown will
contain files in the "label" subdirectory ending
in any of those suffixes.

Two pairs of useful annotation files for the RH
and LH fsaverage surfaces are included in this
distribution:

 {rh,lh}-CsurfMaps1.annot
 {rh,lh}.HCP-MMP1.annot

They are found here:

 $CSURF_DIR/subjects/fsaverage-ADDITIONS

and can be copied into the label subdirectory of
FreeSurfer subject, fsaverage.  Run the
annot2roi.tcl script to sample them to an
individual subject.

To load a label or MGH annotation (or other
format annotation: GIFTI *.gii, or BV *.poi, or
Wavefront *.obj), select one from the "label:"
dropdown.  To display the location of the label
or MGH annotation as a transparent overlay, use
"D".  Many other actions using a label or an
annotation file are possible.

The R-click help for each "label:" line button
make a second left popup containing verbosely
labeled buttons for all the alternate clicks on
each main button (an immediate <Return> will
close the help panel).

See also *shift*-R-click help for this entry for
a summary of actions using an MGH annotation
(the current file is plain R-click help :-} ).

Relative label name assumes same dir as above.
Home dir of subject can be abbreviated as tilde
(~) and session dir (usu. includes "image") as an
asterisk (*).  Absolute name OK, too.  When
making labels files, replace <id> with an
informative infix.  To distinguish csurf label
files from MGH label files (interchangeable
except that MGH label files cannot contain
complex values), a dash is used after $hemi
instead of a period.

The "label:" dropdown is loaded with any file
ending in *.label, *.annot, *.poi (or *.obj).

Label files (and multi-label annotation files)
can be used/read in (at least) 7 distinct ways:

(1) To color (mark) surface vertices of labeled
    region w/single transparent color.  Use "D"
    (display) button, or from script, use tcl
    function, read_label_to_annot_using_col $r $g
    $b.  Ignores vertex data in label.  The "D"
    button can also be used to display MGH
    annotation files (double-mid-click to pop up
    annot region name/color after display).

(2) To recut a label, a hole, or add to a cut
    label (clearing the .val(.val2) field(s)).
    Use "C" (cut) button, or from a script with
    function, read_label_cut_clearvals <0,1,2>

(3) To read the *data* in the label file into the
    .val(.val2) field(s).  Done with "R" button,
    or from script with function, read_label_to_val.
    If all vertices need to be cleared first, use
    CLR button on "val:" line, else any existing
    .val(.val2)'s will remain.  Not clearing can
    be useful for masking operations or assembling
    activations.

(4) To write the data from the .val(.val2)
    field(s) from a selected portion of the
    surface into a file ("W" button).

(5) To constrain the range of another operation
    such as sampling 3D data or timecourses using
    the label, constraining a searchlight or
    retinotopic border run (done with "T", "S",
    "X" buttons), or providing a border for
    a FILL or ROI operation

(6) To convert a label, annotation region, or all
    or annotations to a 3D AFNI ROI(s) (also "D"
    button)

(7) To assemble a group of labels, together
    with a FreeSurfer LUT file, into an MGH
    annotation file (also the "W" button)


FreeSurfer ASCII label file (*.label)

A standard single-label ASCII file can contain
any valid vertex number, but is typically made by
flood-filling a connected patch created using
AREA (closed contour cut) or ROI (fill to
threshold).  With more than one seed
(left-click), AREA and ROI will combine
disconnected patches into one label.

The label file is an ASCII file with the
following format:

  The first line is a comment, typically:
  #!ascii , from subject <somebody>

  The second line contains a single number, which
  is the number of labeled vertices in the file.

  The third and following lines will each have 5
  or 6 numbers: the vertex number, the x,y,z
  coordinates of the vertex (from the $origcoords
  surface, typically $hemi.orig), the value of
  vertex[i].val, and optionally vertex[i].val2,
  if the complex-valued data has being displayed.
  The data field(s) will be 0.0 if a label is
  written when no overlay data has been loaded.

  -------------------------------------------
  Fragment of a real-valued label file:
  -------------------------------------------
  #!ascii , from subject martys09
  317
  26595 42.500 -61.500 -11.500 0.254000
  27575 44.500 -60.500 -9.500 -0.456067
  27599 44.500 -60.500 -10.500 0.948998
  27600 43.500 -60.500 -10.500 1.239467
  27614 45.500 -60.500 -11.500 -1.392878
  27615 44.500 -60.500 -11.500 0.000000
  ... [311 more lines]
  -------------------------------------------

To assign an RGB color to the labeled vertices
(first usage (1) above -- ignores data in file),
set the values of the r,g,b fields to the right
of the MESH button before reading the label file.
The color setting only affects the rendered color
of a subsequently read label file.


SamSrf (pRF) data labels

Labels written by the SamSrf toolbox for pRF
mapping that is available at:

  http://figshare.com/articles/
    SamSrf_toolbox_for_pRF_mapping/1344765

are typically saved in a "prf" subdir of a
subject.  They have the same ASCII format as the
real-valued *.label files above.  These are
loaded as a group at the bottom of the "label:"
dropdown.  These have an underscore (e.g., 'rh_')
after the hemisphere (instead of a 'rh.' for an
MGH label, and a 'rh-' for a csurf label).  If
the label is part of a complex-valued pair such
as:

 ~/prf/rh_pRF_sf_pol_r.label
 ~/prf/rh_pRF_sf_pol_i.label
           or
 ~/prf/lh_pRF_sf_ecc_r.label
 ~/prf/lh_pRF_sf_ecc_i.label

reading the data from either one of these files
using "R" will automatically load the other file
from the complex-valued pair, and then auto-reset
the color scale setting appropriately as follows:

SamSrf (both ecc and pol):
  set complexvalflag 1
  set colscale 0
  set fthresh 0.0
  set fmid 0.025
  set fslope 100.0

SamSrf (ecc only):
  set angle_cycles 1.0
  set angle_offset 0.0

SamSrf (pol only):
  set angle_cycles 2.001
  set angle_offset 0.5   ;# N.B.: both hemi's same
  set revphaseflag 1

Note that csurf labels ('rh-' prefix), by
contrast, typically store real and imaginary
values in a single label file (6 entries per line
instead of 5).


MGH annotation file (*.annot, vtx cols + LUT)

Binary (MSB first) MGH .annot files contain a
color for every vertex followed by a look up
table that maps cortical area names to unique
colors.  The definition of the "new format"
annotation file follows:

  ------------ header 1 ---------------------
   4-byte int: surface vertex count
  ------------ vtx cols ---------------------
   4-byte int: vtxnum
   4-byte int: packed color (ABGR)
   ... [pairs for every surface vertex]
  ------------ header 2 ---------------------
   4-byte int: tag (=1)
   4-byte int: version (-2 = vers2)
   4-byte int: largest ID number of any area
   4-byte int: length of LUT filename
   [length] bytes ending with \0: orig LUT filename
   4-byte int: color LUT entries
  ------------ LUT entries ------------------
   4-byte int: area ID number
   4-byte int: length of region name
   [length] bytes ending with \0: region name
   4-byte int: red
   4-byte int: green
   4-byte int: blue
   4-byte int: transparency
   ... [7-tuples for every cortical area]
  -------------------------------------------

The slightly different "old format" is also
readable/auto-detected.

N.B.: mris_convert and freeview crash/can't read
annotation files containing:

  (1) 'holes' in the list of region ID numbers
  (2) actual largest ID number (must be +1)

so tksurfer write_mgh_annot re-numbers the output
and increments the max ID num field.

The MGH annot files can be displayed with the "D"
button (auto selects function read_mgh_annot if
input file suffix is .annot).  They can also be
used to extract current surface data as follows:

  1) load vertex data of interest to .val(.val2)
  2) load MGH annot with left-click "D"
  3) click one colored label to use (loads color)
  4) set name in "label:" entry for output file
  5) Shift-middle-click-"W" (see below)

When an MGH annot file is displayed, clicking a
vertex reports the current annotation color in
the r,g,b entries to the right of the MESH
button, and the corresponding brain structure
found in the embedded color LUT in the csurf log
(double-middle-click vertex to get a pop-up).

The data for every region in an MGH annot file
can be dumped to separate label files with a
shift-left-click on the "W" button.

A selected subset of annotation region labels can
be (1) displayed or, (2) used to mask overlay
data, using a shift-right-click on the "D"
button, which makes popups to pick a subset of
annotation regions by idnum (all other regions
(1) or overlay data (2) are masked).  In case
(2), the data can be dumped to individual label
files.

An MGH annot file can be constructed from a
FreeSurfer LUT file and a series of individual
labels with ctrl-middle-click on the "W" button.

An MGH .annot file from fsaverage can be
resampled to an individual subject to make a
subject-specific .annot file, and optionally
converted to 3D AFNI BRIK ROIs by using the
standard tcl script, annot2roi.tcl, which is
available from the "tcl:" dropdown.

The vertex-wise percent overlap between currently
loaded vertex values (.val) that are non-zero and
each region in an MGH .annot file can be
calculated (ctrl-shift-right-click on the "D"
button).

Finally, an MGH .annot file can be viewed as a
colored cortical ribbon on a 2D slice in tkmedit
bu using the SURFPAINT panel in the F4 interface
of tkmedit.


GIFTI annotation file (*.gii)

A GIFTI xml annotation file (as generated from an
MGH annotation file by FreeSurfer) contain a
FreeSurfer color table that maps region names
(and sequential, zero-based region id numbers) to
unique r,g,b colors, followed by a list of region
id numbers for each vertex.

The color table contains floating point r,g,b
colors in the range 0-1 (N.B.: can result in
overlapping unsigned char [0-255] colors if not
converted from them).

The subsequent list of region id numbers must
match the total number of vertices in the
surface.

The expected format looks like this:

  -------------------------------------------
  <?xml version="1.0" encoding="UTF-8"?>
  <!DOCTYPE GIFTI SYSTEM "http://gifti.projects.nitrc.org/gifti.dtd">
  <GIFTI Version="1.0"  NumberOfDataArrays="1">
     <MetaData>
       ...
     </MetaData>
     <LabelTable>
        <Label Key="0" Red="0" Green="0" Blue="0" Alpha="0"><![CDATA[Unknown]]></Label>
        <Label Key="1" Red="0.392157" Green="0" Blue="0.745098" Alpha="1"><![CDATA[V1_lower]]></Label>
        <Label Key="2" Red="0.392157" Green="0" Blue="0.784314" Alpha="1"><![CDATA[V1_upper]]></Label>
        ...
        <Label Key="102" Red="0.294118" Green="0.666667" Blue="0.27451" Alpha="1"><![CDATA[SMA2]]></Label>
     </LabelTable>
     <DataArray Intent="NIFTI_INTENT_LABEL"
                DataType="NIFTI_TYPE_INT32"
                ArrayIndexingOrder="RowMajorOrder"
                Dimensionality="1"
                Dim0="163842"
                Encoding="GZipBase64Binary"
                Endian="LittleEndian"
                ExternalFileName=""
                ExternalFileOffset="">
        <MetaData>
           <MD>
              <Name><![CDATA[Name]]></Name>
              <Value><![CDATA[node label]]></Value>
           </MD>
        </MetaData>
        <Data>eJztnXm3FEXy93N ... </Data>
     </DataArray>
  </GIFTI>
  -------------------------------------------


BV patches-of-interest (*.poi) file (label group + LUT)

These Brain Voyager files are functionally
similar to MGH annotation files (label group +
LUT) and should be able to be used in similar
ways.  The expected file format looks like this:

  -------------------------------------------
   FileVersion:      2
   FromMeshFile:     "<none>"
   NrOfMeshVertices: 163842
   NrOfPOIs:         8

   NameOfPOI:        "Te10"
   InfoTextFile:     "<none>"
   ColorOfPOI:       227 26 28
   LabelVertex:      0
   NrOfVertices:     468
   52656
   52657
   ... [vtxnums for every vtx in this patch]

   NameOfPOI:        "Te11"
   InfoTextFile:     "<none>"
   ColorOfPOI:       253 191 111
   LabelVertex:      0
   NrOfVertices:     855
   43
   166
   ... [vtxnums for every vtx in this patch]

   ... [additional patches]
  -------------------------------------------


Wavefront ASCII OBJ surface+colors file

A Wavefront surface file containing vertexwise
colors can be read as if it was an annotation (a
set of patches-of-interest) by considering
vertices in each unique color to be a different
brain region (up to 5000 unique colors/regions
allowed, before bailing).  The expected format
looks like this (only reads r,g,b - surface
gemoetry ignored):

  -------------- header ---------------------
   # comment line (no req'd header)
   [vertex triples implicitly numbered]
   "v"  x  y  z  r  g  b
   "v"  x  y  z  r  g  b
   ... [x,y,z triples or sextuples up to vertex count]

   [normal triples implicitly num'd, norm maybe!=1]
   [N.B.: currently ignored here and recalc'd as usual]
   "vn"  x  y  z
   "vn"  x  y  z
   ... [x,y,z triples up to vertex count]

   [face triples implicitly num'd]
   [entries: vtx, vtx/tex, vtx//norm, vtx/tex/norm]
   [N.B.: vtx/tex/norm nums are 1-based!]
   [N.B.: ignores tex/norm nums]
   "f" vtx1 vtx2 vtx3
            *or*
   "f" vtx1/tex1 vtx2/tex2 vtx3/tex3
            *or*
   "f" vtx1//norm1 vtx2//norm2 vtx3//norm3
            *or*
   "f" vtx1/tex1/norm1 vtx2/tex2/norm2 vtx3/tex3/norm3
   ... [triples up to face count]
  -------------------------------------------


Vertex color file (*.cols)

A vertex color file contains RGB colors for some
or all vertices (before modifications of vertex
color by lighting calculations).

This is fixed "paint" which ignores all color
scale settings for data.  It also occludes any
currently displayed data.

This allows combining data that has been rendered
with *different* color scales on the *same*
surface (e.g., visual and auditory data).  The
expected format is:

  #!ascii
  <vertices-in-file>
  <vtx> <r:0-1> <g:0-1> <b:0-1> 
  ...

Here is a fragment of such a file:

  -------------------------------------------
  #!ascii , from subject fsaverage
  10287
  509     0.000   0.522   0.960
  510     0.072   0.000   1.000
  519     0.868   0.019   0.576
  520     0.996   0.001   0.504
  ...
  -------------------------------------------

Use the "label:" line "R" button (middle-click-R)
to read such a file and the "CLR" button
(middle-click-CLR) to clear all such colors.  Use
the "D" button (ctrl-right-click-D) to copy the
current vertex colors (data as rendered by color
scale settings) to vertex colors.  Use the "W"
button (ctrl-righl-click-W) to write them out to
a *.cols file (all visible vertex, so cut first
to get smaller patch).


Label Buttons (D, C, CLR, R, W, T, S, X)

A large number of different operations (now
almost 50) can be done with a label (or an MGH
annotation) using the buttons on the "label:"
line.  Here are the default (left-click)
functions of each of the buttons.

Each button has individual right-click help.
They can all be scripted (see tcl functs, or
click upper left "tcl:" to see tcl functs echoed
as they are executed).

 D -- display transparent label or MGH annotation
  (tclfunct: read_label_to_annot_using_col <r> <g> <b>)
  (tclfunct: read_mgh_annot => all regions MGH .annot file)
  (tclfunct: read_poi_annot => all regions BV .poi file)

 C -- recut label without restoring prev cuts
    (tcl funct: read_label_cut_clearvals 0)

 CLR -- clear all displayed labels (and MGH annot LUT)
    (tcl funct: clear_annot)

 R -- read vtx data in label onto surface (maybe recut)
    (tcl funct: read_label_to_val 0,1)

 W -- write current surface val data to label file
    (tcl funct: write_val_visible_vertices)

 T -- use label to sample rawdata 3D timecourses to file
    (tcl funct: write_label_timecourses_stats <0=rawtime>)

 S -- like T but also get 3D stats
  (tcl funct: write_label_timecourses_stats <2=stat+rawtime)

 X -- run surface-based searchlight cross-corr over label
    (tcl funct: corr_over_label <neitype> <crit> <cmptype>)

Middle-clicks and left and middle clicks with
shift and/or control keys access alternate
conceptually related functions for each of these
buttons (also documented at top of R-click help
for each button):

-------------------------------------------
 left-D -- [def: display label or annotation]

 middle-D -- use label to undo cut
    (tcl funct: read_label_to_undo_cut)

 shift-left-D -- convert one MGH annot region to 3D-ROI
    (tcl funct: write_annotcol_timecourses_stats

 shift-middle-D -- convert label to 3D ROI
    (tcl funct: write_label_timecourses_stats <3=ROI>)

 shift-right-D -- pick annot idnums to view/mask
    (tcl funct: set_idnums_visiblity <0,1>)
    (tcl funct: set_idnum_visiblity <idnum< <0,1>)

 ctrl-shift-left-D -- convert all MGH annots to 3D ROIs
    (tcl funct: write_annotcols_timecourses_stats <3=ROI>)

 ctrl-middle-D -- count neighbor annot areas -> stat, print
    (tcl funct: areaneigh2stat)

 ctrl-left-click-D: select vertices in label (as if clicked)
    (tcl funct: read_label_to_select)

 ctrl-right-click-D: annots overlap w/non-0 .val
    (tcl funct: calc_annots_nzval_overlap)

 ctrl-right-click-D: copy curr col to vtxcol
    (tcl funct: currcol_to_vtxcol)

-------------------------------------------
 left-C -- [def: re-cut label]

 middle-C -- cut a hole using label
    (tcl funct: read_label_cut_clearvals <1=hole>)

 shift-middle-C -- add label to existing cut label
    (tcl funct: read_label_cut_clearvals <2=add>)

 ctrl-left-C -- re-cut existing displayed labels
    (tcl functs: labeled_cut_clearvals <0=label>)

 ctrl-middle-C -- cut hole using existing labels
    (tcl functs: labeled_cut_clearvals <1=hole>)

 ctrl-shift-left-C -- re-cut w/uniq vtx's
    (tcl funct: read_uniqsamp_vertices)
    (tcl funct: read_label_cut_clearvals 0)

-------------------------------------------
 left-CLR -- [def: clear labels/annots]

 middle-CLR -- clear vertex col label "paint"
    (tcl funct: clear_vtxcol_labels)

 ctrl-left-CLR -- use label to clear labels/annot
    (tcl funct: read_label_to_clear_annot)

 ctrl-middle-CLR -- clear one color of annot
    (tcl funct: clear_annot_with_col <r> <g> <b>)

-------------------------------------------
 left-R -- [def: read vals in label to .val]

 middle-R -- read vertex col label onto surface
    (tcl funct: read_vtxcol_label)

 shift-middle-R -- real val and recut label
    (tcl funct: read_label_to_val <1=cutlabelflag>)

 ctrl-left-R -- read uniq samp vertices label
    (tcl funct: read_uniqsamp_vertices)

-------------------------------------------
 left-W -- [def: write vals at currently visible vtxs]

 middle-W -- conv label to vertex color label
    (tcl funct: label_to_vtxcol_label)

 shift-middle-W -- write val data from annotated vtxs
    (tcl funct: write_val_annoted_vertices)
      => use label to get current val data

 shift-left-W -- write val data from 1 MGH annot area
    (tcl funct: write_val_annotedcol_vertices <r> <g> <b>)
      => first click an annot area to load color
      => gets current val data for one MGH annot label

 shift-ctrl-left-W -- write val data from all MGH annots
    (tcl funct: write_val_annotedcols_vertices)

 ctrl-left-W -- write curr set clicked vtxs to label
    (tcl funct: write_val_selected_list_to_label)

 ctrl-middle-W -- assemble MGH annot using MGH LUT file
    (tcl funct: write_mgh_annot)

 shift-ctrl-middle-W -- write concat searchlights to ASCII
    (tcl funct: write_searchlights <fillneartype> <criterion>)

 shift-ctrl-right-W -- extract label from annotation (autoname)
    (tcl funct:  write_val_annotedcol_autoname <r> <g> <b>

 ctrl-right-click-W: curr vtxcols to vtxcol label 
    (tcl funct: write_vtxcol_label)

 shift-right-click-W: write adjusted phase
    (tcl funct: write_adjphase_vertices)

-------------------------------------------
 left-T -- [def: write rawdata at label]

 shift-left-T -- rawdata at label + percent (Fourier) resp
    (tcl funct: write_label_timecourses_stats <4=time+percnt>)

 middle-T -- rawdata from one MGH annotation region
    (tcl funct: write_annotcol_timecourses_stats
                               <r> <g> <b> <0=rawtime>)

 shift-middle-T -- rawdata from every MGH annot region
    (tclfunc: write_annotcols_timecourses_stats <0=rawtime>)

-------------------------------------------
 left-S -- [def: write 3D write stat+raw at label]

 middle-S -- write 3D stats+raw for MGH annot region
    (tcl funct: write_annotcol_timecourses_stats
                                <r> <g> <b> <2=stat+rawtime>)

 shift-middle-S -- get stats+rawdata all MGH annot regions
    (tcl funct:  write_annotcols_timecourses_stats
                            <2=stat+rawtime>

 ctrl-left-S -- get just stats for label
    (tcl funct: write_label_timecourses_stats <1=st>

 ctrl-middle-S -- get stats for MGH annot region
    (tcl funct: write_annotcol_timecourses_stats
                                   <r> <g> <b> <1=statonly>)

 shift-ctrl-middle-S -- get stats for all MGH annot regions
    (tcl funct: write_annotcols_timecourses_stats <1=statonly>)

-------------------------------------------
 left-X -- [def: searchlight cross-corr over label]

 middle-X -- searchlight cross-corr on 1 MGH annot region
    (tcl funct: corr_over_annotcol 
                       <neitype> <crit> <cmptype> <r> <g> <b>)

-------------------------------------------

Convert data label to vertex-color label

The rendered color of a the vertex data of a
label (as controlled by any color scale, any
panel settings) can be converted to a
vertex-color label (suffix: *.cols).  This kind
of label contains vertex colors rather than data,
but can be read onto a surface already displaying
other data.  Note that it ignores color scale
settings.

This allows combining data that has been rendered
with *different* color scales on the *same*
surface.  With ordinary *data* labels, if two
more more are read onto a surface, they all have
to use the same color scale (mapping between data
values and colors).

Here is a recipe for doing this:

  (1) define a label using cuts and/or ROIs
  (2) write label using "label:" "W"
        (default left-click)
  (3) adj color scale settings to desired
  (4) convert current rendering of label data
        to vertex-color label (auto output name)
        (middle-click on "label:" "W")
  (5) display or read data label for underlay
  (6) read vertex color label onto surface
        (middle-click on "label:" "R")
        (auto input name from data label name)

Fill Holes in Label or Label Data

The SMOOTH button can run two different
hole-filling functions if the following text is
typed into the entry (instead of a number):

   labelholes -> fill holes in D'd label
   valholes   -> fill holes in R'd label *data*

These hole filling operations only affect
unlabeled vertices.  Any vertex with data is
considered fixed.

Make a single-vertex-wide line label (traverse an area)

  (1) turn on MESH
  (2) zoom until individual vertices visible
  (3) right-click to clear all prev selections
  (4) left-click a line of vertices
  (5) ctrl-left-click "W" (write selected list to label)

Note that when single-vertex 'line labels' (or
line labels generated by geodesic traverses using
the "Dijk" button) are re-displayed, they will
appear to be 3 vertices thick even though they
are actually 1 vertex thick.  This is because a
label is displayed by coloring *faces*, and any
face that has a vertex in the label will be
colored.  Faces on the boundary of the label will
have one or two vertices assigned background gray
color (darker of two grays = concave), so these
faces will merge into dark gray.  For more
details, see R-click help for ROI button.

Tips for label editing

The label drawing facilities are powerful but not
extremely user friendly.  Here are some tips on
how to refine a label after an initial attempt:

  Erode (rm rim of single vertices):
    click in label
    left-click "er", FILL

  Dilate (add rim of single vertices):
    click in label
    middle-click "er", FILL

  Touch up edges:
    select points -> trim: left-click-PTS
    select points -> add: middle-click-PTS

  Trim label using another label
    load target label
    select trim label
    middle-click "C" (cut away)

  Eliminate dangling edges (see with MESH)
    FILL or left-click + PTS

  Eliminate stray single vtxs (see w/mid-clk MESH)
    FILL or left-click + PTS

  Make label adjoining another label:
    "D" first label
    cut line new label start/end in displayed
    FILL (respects displayed labels)

  Add chunk to a label:
    display orig label
    cut line around chunk to add
    FILL (just the chunk)
    select original label again from dropdown
    shift-middle-click "C" to add it back to chunk

  Dilate label to meet existing label(s)
    display labels you want to respect
    re-cut the label you want to grow (only it visible)
    middle-click "er" (=dilate)
    repeat FILL (grows to invis. prev disp'd labels

  Quick re-view of a current set of labels:
    make tcl script in scriptsdir starting with:
      set labelflag 1
      set labelalpha 255
      clear_annot
    followed by pairs of lines like:
      ...
      ...
      setfile label ~/label/$hemi-MT.label
      read_label_to_annot_using_col 250 0 0
      ...
      ...
    INIT (show everything)
    run script with GO on "tcl:" line

  Hint: it is very easy to accidentally
    type something like "rh-V2_upper.label" on
    saving a finely crafted label that is on the
    *superior* occipital pole that is actually
    *lower* field V2 :-}

  For adjoining labels, sketch before cutting!
    click along intended bounadaries
    save selected as tmp label (ctrl-L-clk "W" labelline)
    display tmp label with label line "D" to guide cut
    cut/CLR/FILL first label, save, INIT, load
    redisplay tmp label sketch
    cut/CLR/FILL second label up to first, save, INIT, load
    ... (CLR so FILL doesn't avoid tmp label)

  Adjust border between two completely surrounded labels
    clear to-be-shrunken label (ctrl-left-CLR)
    cut line across cleared label
    FILL up to the other label
    ADD (shift-middle-C) other label to filled

  Make colored border line around a set of areas
    make labels for set of areas
    make color LUT for those areas
    assemble annotation (write_mgh_annot), load it
    turn on eroding fill
    FILL up to areas to make surface mask w/holes
    FILL mask 3x to enlarge holes
    mid-clk-C cut hole in orig mask w/3x erode (largest-hole)
    save border label
    tcl cmd: read_label_to_setvalval2 <real=2.0> <imag=0.0>
    make val2rgblut: 2.0 <r> <g> <b>
    R label to display val, mid-clk "W" to conv to vtxcol label

