-------------------------------------------
variable: $smoothsteps -- surface-smooth steps
-------------------------------------------
default: 5

The entry immediately right of the "SMOOTH"
button specified smooth steps.  It also accepts
the following 7 words (see below):

  "annotholes" (or "labelholes")
  "valholes" (or "valueholes")
  "annotholes-neigh" (or "labelholes-niegh")
  "annoterode"

An empirically derived correspondence between the
number of smoothing steps with the standard
nearest-neighbor functions (smooth_curv,
smooth_val, smooth_stat) and the average
full-width-at-half-max filter result starting
with a single non-zero vertex on a standard
resolution surface is:

  steps   FWHM (mm)
 --------------------
    5      2.22
   10      3.20
   20      4.49
   30      5.36
   50      6.99
   70      8.31
  100     10.15
  230     ~1.5 cm
  400     ~2 cm
  900     ~3 cm
 --------------------

A power function fit to this empirical map
(r^2 = 0.9987) is:

  fwhm = 0.9921 * steps^0.5018

Three alternate smoothing functions behave
differently:

  smooth_val_sparse <steps>
  smooth_val_weighted <steps>
  smooth_complexang_realamp <steps>

Sparse smoothing only interpolates non defined
vertices at the 'speed of light' (one additional
ring of vertices for each step).  Gaussian
weighted smoothing is still a nearest neighbor
operation, but has adjustable strength.
Smoothing using complex angle and real amplitude
smooths less than standard smoothing because
phase angle differences are ignored for the
purposes of determining amplitude.

Alternate hole-filling and eroding operations

If "annotholes"/"labelholes" or
"annotholes-neigh"/"labelholes-neigh" or
"valholes"/valueholes" or "annoterode" is entered
as the 'number' of smoothing steps (no quotes),
the SMOOTH button will instead run the following
tcl/C functions:

  1) annotholes -> fill_annot_holes
     [or labelholes -> synonym for above]

  2) valholes -> fill_val_holes
     [or valueholes -> synonym for above]

  3) annotholes-neigh -> fill_annot_holes_neigh
     [or labelholes-neigh -> syn for above]

  4) annoterode -> annot_erode

This R-click help also brings up a buttonbar to
conveniently access all of these options.

(1) smooth steps = "annotholes"

The first option calls the C/tcl function
fill_annot_holes, which fills holes in a label
previously read in as a binary annotation or a
single label using the "D" button (label vs.
non-labeled).  The annotation/color used to fill
is the annotation of the last non-zero neighbor.

(2) smooth steps = "valholes"

The second option calls the C/tcl function
fill_val_holes, fills in holes in label values
read into the .val field with the "R" button
(floating point values).  Filled values are the
average of non-zero neighbor val's.

In both cases a fill-able hole is defined as a
vertex in which all but 2 of its neighbors are
annotated (annotholes/labelholes) or non-zero
(valholes/valueholes).

This conservative definition of a hole will only
fill an outright single-vertex hole, or the end
of a linear defect.  Therefore, it may have to be
run several times to reach asymptote.  It will
not expand the convex edges of a label (like
SMOOTH with "sp" -> sparse will), but it will
fill in one-vertex-thick cracks in otherwise
linear edges.

(3) smooth steps = "annotholes-neigh"

The third option calls a more general and
controllable annotation/label C/tcl hole-filler
function, fill_annot_holes_neigh, which has an
adjustable neighborhood ($neighord: 1-5 rings of
nearest neighbors), and an adjustable criterion
($annotfrac: fill if some % of total neighbors
filled).  This is run and controlled from a popup
brought up when "annotholes-neigh" is entered for
'smooth steps' followed by a <Ret> or clicking
"SMOOTH".

Larger neighborhoods (3-5) are successively
slower with a large surface (e.g., 5M vertex
cerebellum), but can be sped up by cutting away
irrelevant parts of the surface, for example, by
using the "PLANE" button.

A final touch-up method to remove pesky remaining
holes is to FILL the region around the label,
save that everything-but-label as a new label,
then read it in to the full surface and FILL up
to the everything-but-label label.

(4) smooth steps = "annoterode"

Finally, the fourth/last option calls the C/tcl
function, erode_annot, which erodes a single
layer of vertices from each color in an
annotation (e.g., the HCP parcellation displayed
with "D") by setting the annotation of a vertex
to zero if any of its neighbors have a different
annotation value.  This will also work on a
single "D"-displayed label.  Note that this does
not do a FILL, so repeated applications of
annot_erode may result in disconnected patches
for a single color (probably what you want - see
next).

One use for eroded regions is to generate a label
that selects vertices that are more likely to
actually be in the region (away from the
boundaries with other regions).

Save a hole-filled annotation (when .val's don't matter)

Sometime, you just want to patch holes in a label
without concern for values - for example, to use
the label to make a multi-area annotation, or to
clean up holes in a 'foreign' label that was read
in from a previous surface edit using
read_label_to_nearest_annot_using_col.

In this case, to save the patched label:

 (1) re-cut label (ctrl-L-clk "C" on "label:" line)
 (2) maybe change "label:" entry (to avoid overwrite!)
 (3) save label with "W" on "label:" line"

Saving hole-filled values in a label

Once a read-in label has had its value holes
filled (or has been eroded), there are several
ways to save the new label.  Note that the "W"
button on the "label:" line (default left-click:
function: write_val_visible_vertices) saves all
visible vertices (and their currently displayed
values).  You probably don't want the entire
brain, so first re-cut the label by selecting a
vertex inside it and using the ROI button with
fthresh set to a value below any in the displayed
label's values (e.g., 0.001).  Also, type in a
new name on the "label:" line entry unless you
want to overwrite the original label.

For example, to patch value holes in a
single-subject MGH BA label (values are
probabiities):

 (1) set colscale to "BR" (real values)
 (2) read BA label (probabilities) to surf with "R"
 (3) enter "valholes" in smoothsteps entry
 (4) click SMOOTH several times until holes filled
 (5) click vertex inside label, click ROI to re-cut
 (6) type new filename for label
 (7) left-click "W"

Save data under label(s) in one step

It is possible to save the vertices and values of
a displayed label (transparent display from using
the "D" button; N.B.: the values being saved may
not be visible if "overlay" is unclicked),
without re-cutting the label by using an
alternate shift-middle-click "W" (function:
write_val_annoted_vertices <r> <g> <b>).

If a multi-area annotation is loaded, the
currently displayed value data for each
annotation region can be saved out as a separate
label file all at once with an alternate
shift-ctrl-left-click "W" (function:
write_val_annotedcols_vertices).

See the help for the "label:" "W" button for more
details.
