-------------------------------------------
funct (left-click): nearest-neighbor-FILL region
  floodfill_marked_patch <0,1,2,3,4,5>
-------------------------------------------

The "FILL" button (lower right) performs a
region-growing operation on the surface starting
from any current marked seed(s).

"FILL" is used to select a connected subset(s) of
vertices to be written out as a patch or a label.
After this operation finished, any unselected
vertices are made invisible (after the report of
the filled area in sq mm).  Undo this with "UNDO"
or use "INIT" to restore initial read-in state of
surface.

Start by clearing all previously marked vertices
with a right-click in the surface display window.

Then specify one or more closed regions using
open- or closed-line cuts:

  closed line:
    left click sequence
    AREA (tcl/C function: cut_line 1)

  open line:
    left click sequence
    LINE (tcl/C function: cut_line 0)

Then specify seed(s) for fill(s) with one (or
more) left-clicks in region(s) to save (N.B.:
left-clicking two disconnected regions will fill
them both, which you may want to do).

Finally, click FILL.  This flood fills the marked
region(s).  The progress of the flood fill is
shown by white coloring.  When done, the white
coloring is removed and only the filled region(s)
are visible.

For surfaces with a very large number of vertices
(e.g., cerebellum), an ongoing FILL operation can
be killed with cmd-F (i.e., cmd-shift-f)

FILL and ROI will not fill any region containing
a displayed ("D") label or annotation.  Clear
labels or annotations first ("label:" line CLR)
to remove this contraint.  On the other hand,
leaving labels displayed is a way to generate
adjoining labels.

At this point, the result can be saved as a patch
(e.g., for flattening) or as a label (or both).
The patch is a binary file that will contain the
current surface vertex x,y,z positions but no
data.  The label is an ASCII file that will
contain the vertex numbers, any data that was on
the surface at write time, and typically the
vertex x,y,z positions in the original folded
surface (N.B.: not the current surface).

The tcl wrapper function for the FILL button,
which runs floodfill_marked_patch and generates
the sum filled area popup, is:

  fillbutton

The meaning of the number arguments to the
underlying function, floodfill_marked_patch, are:

  floodfill_marked_patch <0-5>:

    0: fill to cuts and labels
    1: fill to stat=sfthresh (and cuts/labels)
    2: fill to val=fthresh (and cuts/labels)
    3: fill to complexamp=fthresh (and cuts/labels)
    4: fill to truncphase limits (and cuts/labels)
    5: fill to stat=sfthresh and complexamp=fthresh

A vertex can be marked from a script using:

  click_vertex <xpix> <ypix>

Find out x and y from "pix=<x>,<y>" in the log
after an interactive click.  The argument units
are window pixels.  For the standard 600x600
window the upper left corner is 0 0 and the lower
right is 599 599, so the near the center of the
default 600x600 window is: click_vertex 300 300.

Label Boundaries

The first time a patch is FILL'd, its outer
boundary vertices will be set to 'border'.  Doing
a second FILL operation on this already-FILL'd
patch will thus remove one layer of vertices.

Therefore, by default, FILL pads the set of
filled vertices with all the vertices of visible
faces on the edge of the label.  This prevents
that layer of 'border' vertices from being
stripped when FILL is repeated on the same patch
(no effect of this padding the first time filling
a cut region since the cut vertices are already
hidden).

Since a non-eroding fill pads vertices from
currently visible faces on the label boundary,
this means that FILL'ing up to a displayed label,
will generate adjoining labels that share the
vertices at their boundary (sometimes desired).

To create completely non-overlapping adjoining
labels, click "er" (for "eroding", next to FILL)
before clicking FILL, which restores the original
eroding behavior of FILL (sets $erodingfillflag
to 1).  Since a layer of vertices is lost, draw
cuts taking this into consideration.

Touch up a cut label (or a cut region before a
FILL) with the PTS button: left-click PTS after
selecting a series of vertices to remove them,
middle-click PTS to add nearest neighbors to a
series of selected vertices.  Use MESH to show
dangling edges.  R-click unlabeled tixbox at
bottom of left "phc" panel to get popup to turn
on $pointsflag to see stray solitary vertices.

An alternate use of an eroding fill is to shrink
a label: with "er" ticked, a second click and
FILL of an already filled region will erode one
layer of vertices.

The ROI button *always* does an eroding fill so
that only vertices above the number in "fthresh:"
will be included in the label.

See help for ROI for exact details on how flood
filling is implemented.

Surface Area Measurments/Report

The "area" of each vertex is the sum of 1/3 of
the area of each of the triangles surrounding
that vertex.

When the FILL, ROI, or N/A/R buttons are clicked,
a popup reports the summed vertexwise area of the
result.  Two sums are reported.  The first, the
"curr surf" area, comes from measuring area on
the currently displayed surface (the .area
field).  The second, the "orig surf" area, comes
from summing areas for the same vertices from the
areafile.  The areafile ($hemi.area) is read into
the .origarea field at startup (it can be updated
interactively by clicking "R" on the "area:"
line).

The two summed area numbers from the most recent
FILL, ROI, or N/A/R operation are saved as in the
tcl variables:

  $filled_origarea
  $filled_currarea

These can be retrieved any time before the next
FILL, ROI. or N/A/R operation by clicking FILL
with no vertex selected.

MGH freesurfer currently uses $hemi.white to
write the original areafiles.  This file can be
interactively overwritten (after a warning) with
current surface areas by clicking "W" on the
"area:" line.

The "curr surf" area of the vertices on the
boundaries of a flat patch would be reduced
relative to patch-internal vertices, since
contributions from the cut-away faces that used
to adjoin those border vertices won't be defined
after flattening and can't be included (this only
applies to flattened, not to inflated surfaces).
Therefore, the "curr surf" area of patch-edge
vertices are estimated by replacing them with the
values in the areafile.  (not required for "orig
surf" patch areas, which use the areafile for all
vertices).
