#### display, uncut, conv=>3D a label/annot ####
-------------------------------------------
funct: "Display Label or Annot (left-click-D)"
  set label <infile>
  read_label_to_annot_using_col $r $g $b
  ------- or --------
  set anlabel <infile>
  read_mgh_annot
  read_poi_annot
  read_obj_to_annot
  read_gifti_to_annot
-------------------------------------------
funct: "Undo Cut with Label (mid-click-D)"
  set label <infile>
  read_label_to_undo_cut
-------------------------------------------
funct: "Convert Label to 3D ROI (shift-mid-click-D)"
  set label <outfile>
  write_label_timecourses_stats 3
-------------------------------------------
funct: "Convert One Annot ID to 3D ROI (shift-left-click-D)"
  [3D-ROI outfile is auto-named]
  write_annotcol_timecourses_stats $r $g $b 3
-------------------------------------------
funct: "Pick Annot Idnums to View/Mask (shift-right-click-D)"
  set_idnums_visibility <0,1>
  set_idnum_visibility <idnum> <0,1>
  set_idnum_visibility <idnum> <0,1>
    [etc for all visible]
  set annotmaskflag 1
  redraw
  [write_val_unmasked_vertices]
-------------------------------------------
funct: "All Annots to 3D ROIs (ctrl-shift-left-click-D)"
  [3D-ROI outfiles are auto-named]
  write_annotcols_timecourses_stats 3
-------------------------------------------
funct: "Count/Print annot neighbors (ctrl-mid-click-D)"
  areaneigh2stat
-------------------------------------------
funct: "Read Label to Select (ctrl-left-click-D)"
  set label <infile>
  read_label_to_select
-------------------------------------------
funct: "Calc Overlap Annots w/Non-0 (ctrl-shift-right-clk-D)"
  calc_annots_nzval_overlap
-------------------------------------------
funct: "Copy Current Cols to Vtxcols (ctrl-right-clk-D)"
  currcol_to_vtxcol
-------------------------------------------
funct:"Copy Curr Lab/Annot to Vtxcols (ctrl-shift-mid-clk-D)"
  labelcol_to_vtxcol
-------------------------------------------
funct: "Display Label on Nearest Vertices (no hotkey)"
  read_label_to_nearest_annot_using_col
-------------------------------------------


Display Layering

There are 5 layers in the cortical surface
display separated by increments of 0.02 mm along
the vertex normal.

  [most superficial]
  --------------------
  cyan cursor (0.10 mm up)
  vertex points (0.08 mm up)
  face edge mesh (0.06 mm up
  labels/annot (0.04 mm up)
  data/curv,vtxcols (0.00 mm up)
  --------------------
  [deepest]

For data in the same layer, later reads occlude
earlier reads (except vertex colors, which are
always drawn after data/curv colors).

Detailed Description of Label "D" Button Actions

-------------------------------------------
funct: "Display Label or Annot (left-click-D)"
  set label <infile>
  read_label_to_annot_using_col $r $g $b
  -------------------
  set anlabel <infile>
  read_mgh_annot
  read_poi_annot
  read_obj_to_annot
  read_gifti_to_annot
-------------------------------------------

A default left-click on the "D" button
auto-detects (by suffix) and reads five different
kind of files available in the "label:" dropdown
into the annotation color field (.annot) of each
vertex -- (1) standard ASCII single-label files
(*.label), (2) binary MGH annotation files
(*.annot), (3) ASCII BV 'patches of interest"
(*.poi) files, (4) Wavefront ASCII surface+colors
files, and (5) GIFTI annotation files.

(1) ASCII Label file (.label suffix)

Left-clicking "D" reads the current file in the
label entry (tcl var: $label) and displays the
label as a colored overlay (N.B.: this ignores
both val's and coord's in the label file).

The area of the label is reported on the popup
after reading.  The "curr area" is the label area
calculated using the current surface.  The "orig
area" is the label area calculated using the
lh/rh.area file, which is generated during
initial surface reconstruction using the
lh/rh.white surface.

If you have used the fsaverage update script,
$CSURF_DIR/bin/noarch/update-fsaverage (highly
recommended!), then (just) for the average
subject, fsaverage, the "orig area" will be
calculated using the inflated_avg surface, which
is much less shrunken than the smoothwm/white
surfaces.  This is because surface-averaging
coordinates of folded surfaces smooths
idiosyncratic 'crinkles', selectively reducing
sulcal area in the average; surface-averaging
coordinates of individually inflated surfaces
avoids this distortion).

The default is to only show the boundary of the
label (so it doesn't occlude activations).  To
fill in the label, R-click the tickbox to the
left of "label:" and untick "annotbordflag".

The r,g,b values that the "D" button passes to
this function are taken from the current values
of the r,g,b entries to the right of the MESH
button (default 120,120,255=blue/purple).  To
change the label color, reset those values and
re-left-click "D".

The opacity of all labels is controlled by the
far upper left "tran" entry ($labelalpha).  The
default is 128 for partially transparent (0 is
invisible and 255 is opaque).

To use the label to extract surface vertex data
in the .val(.val2) fields, see "W" button R-click
help.  For example, shift-middle-clk-W writes out
a new label containing currently displayed
.val(.val2) data just from labeled vertices
(uses tcl funct: write_val_annoted_vertices).

Use the "label:" line "CLR" button to clear any
displayed labels (or annotations).  This does not
affect data in the .val(.val2) fields.

For the ASCII format of freesurfer *.label files,
see the R-click help for the "label:" line entry,
(also describes special case of SamSrf toolbox
labels saved in non-standard "prf" subdir of
subject).

To make labels consisting of a line of single
vertices more visible, set r/g/b (to right of
MESH) to 255/255/255, tick "padlabelvtxsflag" (on
R-click label tickbox popup), set "tran"
(transparency) to 255.  This also labels
neighbors of each vertex in label.

(2) MGH Annotation file (.annot suffix)

The "D" button can also read a binary MGH
annotation file, which typically contains a set
of differently colored labels, as a transparent
overlay.  In this case the "D" button also reads
the color LUT embedded in the annotation file,
which maps unique colors to brain region names
and numbers.  This uses the C/tcl function,
read_mgh_annot.

This also pops up a window with the the full
color table listing all label regions with the
following format:

#from: /usr0/subjects/fsaverage/label/rh-CsurfMaps1.annot
#---------------------------------------------------------
#id  name                              r   g   b    a
#---------------------------------------------------------
  0  Unknown                           0   0   0    0
  1  V1_lower                        100   0 190    0
  2  V1_upper                        100   0 200    0
  3  V2_lower                         60  20 240    0
    [etc]
#---------------------------------------------------------

This table is generated when an annotation is
read, and is saved as an ASCII file with the same
prefix as the annotation file, either here if
you started tksurfer with the SURFACE button:

  $SUBJECTS_DIR/$subject/scripts/<prefix>.ctab

or here (if the annotation is loaded after
starting tksurfer from a functional session using
the SURFACE-STATS button):

  $FUNCTIONALS_DIR/$session/image/scripts/<prefix>.ctab

In addition, another file is saved in the same place
identical to the freesurfer *.ctab file, but with
the area (mm^2) of each region appended as a 7th
column:

  $SUBJECTS_DIR/$subject/scripts/<prefix>.ctab.area
  $FUNCTIONALS_DIR/$session/image/scripts/<prefix>.ctab.area

Double-middle-click a region on the brain surface
to get a temporary pop-up with this information,
for example:

  MT_lower

    idnum:  21
    rgb:  35  175  175
    neighcnt:  4
    vertexcnt:  232
    origarea:  135.0 mm^2

To avoid clogging up the display, this popup
automatically closes itself in 3.5 sec.

Alternatively, to display the names of *all* of
the annotation regions, tick "areanamesflag"
(default=OFF) on the LABEL CONTROLS popup. The
label names are centered on the vertex in each
annotation region that is closest to the 3D
average of the vertices in each region.  This 3D
average is calculated by read_mgh_annot on
whatever surface (folded, inflated, flattened)
that the annotation has been read onto (if
surface interactively changed, re-read annotation
to re-calc).  See R-click help for the "W" button
on the "label:" line to write out the center
vertex for each region.  Use tksurfer command
line option -fontfile <somefont.ttf> to use a
different font than the included luxisb.ttf (put
the alt .ttf file into $CSURF_DIR/lib/fonts).

Left-clicking (or double-middle-clicking) a
region also loads the annotation color of that
region into the r,g,b field to the right of the
MESH button.

To use the MGH annotation to extract surface
vertex data in the .val(.val2) fields under one
of the colored labels, see "W" button R-click
help (tcl funct: write_val_annotedcol_vertices).

To count the number of neighbors of each
annotation region, save the counts in stat, and
print each area's neighbors to the scripts dir
(file: AnnotRegionsNeighborCounts.txt), use
ctrl-mid-click-D (tcl function: areaneigh2stat,
see below).

To calculate vertex-wise percent overlap between
each region in the currently loaded MGH
annotation file and any vertices containing
non-zero .val data, use calc_annots_nzval_overlap
(see below).

The "label:" line "CLR" button clears all
displayed labels, and also, the embedded MGH
color LUT.

To resample an fsaverage annotation to current
single subject, use the standard tcl script:

  annot2roi.tcl

from "tcl:" dropdown (described in R-click help
for the "tcl:" entry).

For the binary format of the MGH annotation
files, see the R-click help for the "label:" line
entry.

(3) Brain Voyager POI Annotation file (.poi suffix)

The "D" button can also read an Brain Voyager
"Patches of Interest" (*.poi) annotation file
(ASCII, vers=2).  Any *.poi file in the current
subject's label directory will be loaded into the
"label:" line dropdown.  This uses the C/tcl
function, read_poi_annot.

The result of reading a *.poi file is the same as
the result of reading an MGH annotation file, and
the displayed labels/patches can be used in the
same way.

For the ASCII format of BV patches-of-interest
files, see the R-click help for the "label:" line
entry.

(4) Wavefront ASCII file w/vertexwise colors (.obj suffix)

The "D" button can also read an ASCII Wavefront
surface file containing vertexwise colors as if
it was an annotation (a set of patches of
interest).  That is, the vertices in each unique
color are assigned to different brain regions (up
to 5000 unique colors/regions allowed, before
bailing).  This uses the C/tcl function,
read_obj_to_annot.  Again see R-click help for
the "label:" entry for expected file format.

In this case, the vertex x,y,z coordinates and
faces geometry (and texture if there) is ignored.

(5) GIFTI xml annotation file (.gii suffix)

The "D" button can also read a GIFTI xml
annotation file (e.g., as generated by
mris_convert).  This contains a color lookup
table that maps region names and region id number
to floating point (0.0 to 1.0) r,g,b colors,
followed by a list of region id numbers for every
surface vertex.  This uses the C/tcl function,
read_gifti_to_annot.

-------------------------------------------
funct: "Undo Cut with Label (mid-click-D)"
  set label <infile>
  read_label_to_undo_cut
-------------------------------------------

If the "D" button is middle-clicked (instead of
default left-clicked), vertices in label are read
and used to uncut the surface (if cut).  If
vertex not cut, no effect.

To repair unintended surface cuts on a patch,
first make a label that covers the parts of the
cut(s) you want to undo.

There are two critical points:

(1) the cut-fixing label has to be *made* on an
  *uncut* surface (e.g., inflated).  This is so
  that the missing vertices can be labeled.  To
  transfer the location from the cut surface to
  the uncut surface, FILL an AREA cut around the
  unintended cut as a marker label, display that
  on the uncut surface, then make a new AREA cut.

(2) the cut-fixing label can only be *applied*
  to an already-cut but *still 3D* surface (e.g.,
  full.patch.3d).  This is because the missing
  (invisible) vertices on an already-flattened
  patch will no longer be located inside the cut
  (they will still be back in their original 3D
  locations!).

Re-read the cut surface, select the label on
the "label:" entry, and middle click the "D"
button to repair the cut.

Before applying, you can display the cut-fixing
label with a left click on the "D" button.

-------------------------------------------
funct: "Convert Label to 3D ROI (shift-mid-click-D)"
  set label <outfile>
  write_label_timecourses_stats 3
-------------------------------------------

If the "D" button is shift-middle-clicked
(instead of default left-clicked), the currently
selected label is converted to a 3D ROI mask
(0,1) AFNI BRIK at the resolution and orientation
of the raw data set (the rawdata set must be
present in the scandir for this to work).

The name of the function is a little confusing.
The "3" option changes its behavior from
extracting timecourses to dumping an ROI, but
using the exact same normal search code used
during time course extraction.

The sampling of the 3D data set is done according
to the current sample settings (right-click the
"label:" label for a popup), and uses the name of
the label as a BRIK prefix.  For example, a label
named:

  rh-MY_AREA.label

will be converted to an ROI BRIK named:

  rh-MY_AREA+orig.BRIK

-------------------------------------------
funct: "Convert One Annot ID to 3D ROI (shift-left-click-D)"
  [3D-ROI outfile is auto-named]
  write_annotcol_timecourses_stats $r $g $b 3
-------------------------------------------

A shift-left-click on the "D" button (instead of
default left-clicked), can be used to extract a
3D ROI mask AFNI BRIK for one of the brain
regions in a loaded MGH annotation file.

The name of the function is a little confusing.
The "3" option changes its behavior from
extracting timecourses to dumping an ROI, but
using the exact same normal search code used
during time course extraction.

As above, the ROI will be at the resolution and
orientation of the raw data set (so the rawdata
set must be present in the scandir for this to
work).  The steps are:

 (1) select MGH annotation from label dropdown
 (2) load it with left-click "D"
 (3) click one of the brain regions to load r,g,b color
 (4) shift-left-click "D" to extract 3D ROI

The sampling of the 3D data set is done according
to the current sample settings (right-click the
"label:" label for a popup).

The name of the ROI BRIK will be taken from the
MGH annotation file name for the current r,g,b
color.

For example, for annotation file:

  rh.aparc.a2009s.annot

clicking on the STS will set r,g,b (just to right
of MESH) to 223,220,60, which corresponds to
structure "S_temporal_sup" and the output mask
BRIK will be named:

  rh-region_S_temporal_sup+orig.BRIK

The selected voxels in the output mask BRIK
(datatype=short) will contain the IDnum for this
region ("S_temporal_sup" IDnum=74), else zero.

See also standard tcl script, annot2roi.tcl,
available from the "tcl:" dropdown, which dumps
out each of the annotations in an MGH annotation
file into individual volumes, and also into a
single, composite volume (with voxel value equal
to annotID).

-------------------------------------------
funct: "Pick Annot Idnums to View/Mask (shift-right-click-D)"
  set_idnums_visibility <0,1>
  set_idnum_visibility <idnum> <0,1>
  set_idnum_visibility <idnum> <0,1>
    [etc for all visible]
  set annotmaskflag 1
  redraw
  [write_val_unmasked_vertices]
-------------------------------------------

After an MGH surface annotation file has been
read with "D" on the "label:" line, you can use
this function either to:

  (1) display a subset of the annotation labels

or, if a vtxcol label (fixed "paint") has been
loaded:

  (2) display a subset of the vtxcol "paint"

or, if surface data overlay has been loaded (at
least the .val field):

  (3) mask real/complex data by annotation idnum's

A shift-right-click on the "D" button brings up
two popups.  The tcl function to do this is:

  annotmaskctrls

The first popup lists the idnum's and names of
all the annotation regions for reference.  In the
second popup (3 similar versions depending on
state), you enter a space-separated list of
idnum's to show (all not listed are masked).  To
quickly find a label, just enter one label number
and <Return>.

In case (1), the subset of annotation regions is
displayed over a grayed curvature (transparency
controlled by the upper right "tran" entry
($labelapha).

In case (2), the subset of vtxcol regions is
displayed over the curvature (no effect of
transparency).

In case (3), overlay data in the .val(.val2)
fields is only shown for selected annotation
regions.  This is useful, for example, to see
phase encoded data from annotation regions
(easier than with colored annotation borders).

Here is an example tcl script to reload a mask
containing somatomotor areas (3b, 4, etc) from
the HCP parcellation (assuming you have loaded
that annotation):

# tksurfer tcl script (N.B.: idnums vs. idnum)
set annotmaskflag 1
set labelflag 0
set_idnums_visibility 0    ;# mask all: idnums vs. idnum
set_idnum_visibility  8 1  ;# area 4
set_idnum_visibility  9 1  ;# area 3b
set_idnum_visibility 36 1  ;# area 5m
set_idnum_visibility 39 1  ;# area 5L
set_idnum_visibility 40 1  ;# area 24dd
set_idnum_visibility 41 1  ;# area 24dv
set_idnum_visibility 51 1  ;# area 1
set_idnum_visibility 52 1  ;# area 2
set_idnum_visibility 53 1  ;# area 3a
set_idnum_visibility 54 1  ;# area 6d
set_idnum_visibility 55 1  ;# area 6mp
set_idnum_visibility 56 1  ;# area 6v
redraw 

Once an annotation has been set up to mask data
(second case), the masked subset of data can be
optionally written out in two different forms.

To get a single label containing all currently
displayed (unmasked) data (uses C/tcl funct,
write_val_unmasked_vertices):

  tick "unmasked_to_label_flag"
  enter output file in "labelabbrev"
     [format: ~/label/$hemi-<infix>.label]
  READY

To instead write out currently visible data to
per-area label files (uses C/tcl funct,
write_val_idnum_vertices):

  tick "unmasked_to_labels_flag"
  enter output files *stem* in "labelabbrev"
     [format: ~/label/$hemi-<infix>]
  READY

This writes a label for each displayed region
into the subject's label directory with the name
formatted as follows:

  rh-<infix>_<areaname>.label

These operations are slightly out-of-place for
the label "D" button (display) as opposed to
being to being attached to the label "W" button
(write), but more convenient here grouped with
their display-only equivalents..

-------------------------------------------
funct: "All Annots to 3D ROIs (ctrl-shift-left-click-D)"
  [3D-ROI outfiles are auto-named]
  write_annotcols_timecourses_stats 3
-------------------------------------------

Same as previous, but automatically dumps *all*
of the brain regions in an MGH annotation files
to seperate AFNI ROI mask BRIK's.

This runs faster if the sampling surface (usu.
"orig") is first loaded.

This also constructs a single, all-ROIs-in-one
BRIK named:

  $hemi-ALL_ANNOT_ROIs-<sampledepth>+orig.BRIK

Each annotation region is added to the all-in-one
ROI BRIK sequentially, so if a voxel is claimed
by more than one region, the last one 'wins'.

Overlap between ROIs can be reduced by first
eroding the surface annotation regions by
entering "annoterode" for smoothing steps and
clicking the SMOOTH button.  Each click erodes
another single layer of vertices from each
annotation region.

-------------------------------------------
funct: "Count/Print annot neighbors (ctrl-mid-click-D)"
  areaneigh2stat
-------------------------------------------

Count the number of other areas bordering each
area in an annotation (first, have to load an MGH
annotation file -- see HOWTO above).  The integer
sum is stored (vertexwise) in the .stat field
(overwrite warning), and then the counts and all
the neighbors of each annotation area are written
to an ASCII table in the current subject's
scripts dir (no overwrite warning):

  AnnotRegionsNeighborCounts.txt

Here is what a portion of that output file looks
like for rh.HCP-MMP1.annot:

#IDnum  Neighs  Structure			NeighIDnums
#-------------------------------------------
...
21      5       R_LO2_ROI			20 22 156 6 138
22      5       R_PIT_ROI			21 6 7 18 138
23      4       R_MT_ROI			156 159 2 141
24      3       R_A1_ROI			173 104 174
25      6       R_PSL_ROI			28 149 105 175 148 104
...

The neighbors are indicated by area ID numbers.

-------------------------------------------
funct: "Read Label to Select (ctrl-left-click-D)"
  set label <infile>
  read_label_to_select
-------------------------------------------

Read label and select each vertex in it
(as if each vertex left-clicked).

The inverse is write_val_selected_list_to_label
(ctrl-left-click "W" on "label:" line).

-------------------------------------------
funct: "Calc Overlap Annots w/Non-0 (ctrl-shift-right-clk-D)"
  calc_annots_nzval_overlap
-------------------------------------------

Calculate vertex-wise percent overlap between
each region in the currently loaded MGH
annotation file and any vertices containing
non-zero .val data.  Annotation regions
overlapping only zero .val's are not reported.

To use this, if necessary, first clear any
existing .annot or .val data from the surface
using:

  "CLR" on the "label:" line
  "CLR" on the "val:" line

Then load the .val field, using either:

  select valfile (*.w or *.mgh) file "val:" dropdown
  click "R" (=read) on the "val:" line
     *or*
  select data-containing label from "label:" dropdown
  click "R" (=read) on the "label:" line

Also, load an MGH annotation using:

  select .annot file from "label:" dropdown
  click "D" (=display) on the "val:" line

Finally, ctrl-shift-right-click the "D" button on
the "val:" line.

The result is written to a pop-up, to the csurf
log, and to a text file ($hemi.overlap.txt) in
the subject's "scripts" directory with the
following format:

#calc_annots_nzval_overlap (non-zero .val's)
#annot=/usr0/subjects/fsaverage/label/lh.HCP-MMP1.annot
#val=/tmp/191101BC-ICA_mgh/ICA20_medial_sensorimotor_rh.mgh
#IDnum	Percent	(Overlap/Vtxs)		Structure
#-----------------------------------------------------------
8	27.7%	(1111/4015)        	L_4_ROI
9	29.9%	(852/2845)          	L_3b_ROI
10	5.2%	(43/832)              	L_FEF_ROI
11	6.1%	(23/375)              	L_PEF_ROI
12	39.8%	(261/656)		L_55b_ROI
...

The $hemi.overlap.txt file is overwritten each
time cal_annots_nzval_overlap is re-run, so first
copy the previous output aside if you want to
save it.

-------------------------------------------
funct:"Copy Current Cols to Vtxcols (ctrl-right-clk-D)"
  currcol_to_vtxcol
-------------------------------------------

Copy the current data-derived color at each
visible vertex (as controlled by current settings
of colscale, etc) to the fixed vertex color
"paint" fields (.vr/.vg/.vb).  This can be used
to assemble illustrations containing data that
uses different color scales.

N.B.: ignores labels/annotations!  Use
currlabel_to_vtxcol below to copy labels
instead.

N.B.: this is color before the lighting
calculations have been applied!

N.B.: does NOT turn on $vtxcolflag (view
vtxcol's).

To save the vertex colors as a file, use
ctrl-R-click W on the "label:" line (tcl/C
function: write_vtxcol_label).

Be sure to start with a clean vtxcol slate by
middle-click-CLR on the "label:" line, else any
previously copied vtxcols will be included in
final .cols file.

Also, if you want to assemble multiple vtxcol's,
be sure a label has been re-cut so the whole
surface won't be saved to the vtxcol file, which
would otherwise occlude other vtxcol labels if
loaded after them.

If you already have a data-containing label, this
can all be done in one step by converting a
standard label directly to a vertex color label
using middle-click W on "label:" line (tcl/C
function: label_to_vtxcol_label).

-------------------------------------------
funct: "Copy Curr Lab/Annot to Vtxcols (ctrl-shift-mid-clk-D)"
  labelcol_to_vtxcol
-------------------------------------------

Copy the currently displayed label/annotation
color at each visible vertex to the fixed vertex
color "paint" fields (.vr/.vg/.vb).

This can be used to save a snapshot of a label or
annotation, e.g., for blink comparison with
another annotation by ticking and unticking
"labelflag" (tickbox to left of "label:"), since
vtxcols are below labels/annotations.

N.B.: ignores any currently displayed data! (use
currcol_to_vtxcol above to copy labels instead)

N.B.: this is color before the lighting
calculations have been applied!

N.B.: does NOT turn on $vtxcolflag (view
vtxcol's).

To save the vertex colors as a file, use
ctrl-R-click W on the "label:" line (tcl/C
function: write_vtxcol_label).

Be sure to start with a clean vtxcol slate by
middle-click-CLR on the "label:" line, else any
previously copied vtxcols will be included in
final .cols file.

Also, if you want to assemble multiple vtxcol's,
be sure a label has been re-cut so the whole
surface won't be saved to the vtxcol file, which
would otherwise occlude other vtxcol labels if
loaded after them.

-------------------------------------------
funct: "Display Label on Nearest Vertices (no hotkey)"
  read_label_to_nearest_annot_using_col
-------------------------------------------

Import a label file (for the same subject), but
which has a different vertex numbering scheme
(e.g., a surface made from a previous edit).

This works like read_label_to_annot_using_col in
that the requested color is defined in the r,g,b
fields to the right of "MESH"),

However, instead of reading the label file vertex
indices (first entry on each label line) to
determine which surface vertices to color, each
label file line will be used to color the current
surface vertex that has its .orig x,y,z
coordinates closest to the x,y,z coordinates in
that label file line.  N.B.: the label file
coordinates are are assumed to be from the .orig
surface, which is the default for label-writing
(i.e., not from the new Talairach coordinate
option above, for from inflated surface
coordinates, etc).

This makes it possible to display a label file
written out from an earlier version of a surface,
which will have a different vertex numbering
scheme, and which would otherwise be incompatible
with the newer surface.

N.B.: this will give non-sensical results if the
label file comes from a different subject or if
the label file contains x.y,z vertex coordinates
that are not from the .orig surface.

N.B.: to save new label:

  (1) re-cut current labeled (ctrl-L-clk "C" on "label:" line
         or tcl funct:  labeled_cut_clearvals 0)
  (2) change name in "label:" line entry to avoid overwrite!
  (3) save label with \"W\" on \"label:\" line"

This works well when edits are localized and no
global refinements have been applied (e.g.,
slightly different target target image value
criterion).  If not, there will be aliasing
between the older label x,y,z vertex positions
and the newer surface x,y,z vertex positions,
resulting in many small linear-shaped holes in
the transferred label where a new surface vertex
just missed being assigned an annotation from a
label vertex.

To fix this, use the C/tcl function
fill_annot_holes_neigh, which can be accessed by
typing "fillannot-neigh" into the unlabeled
"steps" entry immediately to the right of the
"SMOOTH" button.  A <Ret> or clicking SMOOTH
brings up a popup to control the size of the
smoothing neighborhood, "neighord" (1-5, where 1
means just consider nearest vertex neighbors),
and "annotedfrac" (% of surrounding vertices
required to cause an annotation/label hole to be
filled with the surrounding color).  For more
details, see R-click help for the smooth steps
entry immediately right of the "SMOOTH" button.

However, even without hole-filling, the converted
label can be used as a template to re-cut a new
native surface label.

This function is quick on a standard sized
freesurfer brain (130K vertices), but it will be 
slow with a very large surface (e.g., over 30 min
for a 5M vertex cerebellum).  In that case, it 
can be sped up by cutting away irrelevant parts
of the surface (if these are known), for example,
using the "PLANE" button.

