-------------------------------------------
function: floodfill_marked_patch <0,1,2,3,4,5>
-------------------------------------------
keyboard equivalent: none

The "ROI" button floodfills a connected surface
region starting from one or more seed vertices
that has stat, complex phase, complex amplitude,
or val above a requested threshold value.  If
multiple starting vertices are selected, this
may result in disconnected patches.

The precendence of operations is:

 (a) if statANDhypot: STAT>$sfthresh && CPLXAMP>$fthresh
 (a) if statANDreal:    STAT>$sfthresh && REALAMP>$fthresh
 (b) if mask on, use:          STAT > $sfthresh 
 (c) if truncphase, use:      COMPLEX PHASE within limits 
 (d) if complex data, use:   COMPLEX AMP > $fthresh 
 (e) if real data, use:         REAL AMP > $fthresh 

Which operation is done thus depends on the state
of the following tickboxes:

  mid-click "mask" -> toggles $statANDhypotflag
  ctrl-mid-click "mask" -> toggles $statANDrealflag
  left-click "mask" -> toggles $maskflag
  left-click "truncph" -> toggle $truncphaseflag
  left-click "cpx" -> toggle $complexvalflag

N.B.: the first matching conditions win and the
other criteria are ignored.  For example, to fill
a region in an overlay containing real data, the
"mask", "truncphase", and "cpx" ticks must all be
unticked.  The operations in more detail are:

N.B.: statANDhypotflag and statANDrealflag are
incompatible (autofixed based on state of
complexvalflag).

Here again are the ROI fill criteria in order of
precedence (first wins):

 (a) compare hypot(.val,.val2) to $fthresh
         AND compare .stat to $sfthresh
 (b) compare .val to $fthresh AND .stat to $sfthresh
 (c) compare .stat to $sfthresh
 (d) compare atan2(.val2,.val)/2Pi to $truncphasemin,max
 (e) compare hypot(.val,.val2) to $fthresh
 (f) compare .val to $fthresh

The "AND" in the first two cases means, only show
areas with .stat over $sfthresh AND real or
complex amplitude over $fthresh.  If "mask" is
ticked with real or complex data, popups will
force explicit choice between: use stat AND
real/hypot thresholds vs. just use stat
threshold.

In truncphase case, the phase angle is modifed by
$revphaseflag, $invphaseflag, and $angle_offset
before truncation is applied (like "truncphase").

In all cases, this fill procedure also respects
(doesn't go past) cuts, as well as any currently
displayed labels ("label:" ine CLR them if
desired).

Disconnected regions can be filled by marking
vertices by left-clicking them in more than one
region before clicking ROI.

For scripts, the function arguments to
floodfill_marked_patch are (N.B.: arg numbers
have different order than precedence above,
sorry):

 0 - fill visible, connected (this is FILL button)
 1 - compare .stat to $sfthresh
 2 - compare .val to $fthresh
 3 - compare complexamp to $fthresh: hypot(val,val2)
 4 - compare complexpha to $truncphasemin,$truncphasemax
 5 - compare .stat to $sfthresh AND complexamp to $fthresh
 6 - compare .stat to $sfthresh AND real to $fthresh

In contrast to the FILL button, the ROI button
forces an eroding fill (regardless of the setting
of "erode").  This is so that the initially
selected patch will only contain vertices equal
or above "fthresh" (or sfthresh, or within
complex-valued criteria, or stat AND complexamp).

Note that this means that re-doing ROI on an
already-cut-out ROI to the same "fthresh" will
successively erode it (because boundary [=cut]
vertices will be treated the same as vertices
below "fthresh").

See below for the gory details of why this is
this way.

=============================================
Arcane details of flood filling
=============================================

The surface specification consists of a list of
vertices who know their neighbors, and a list of
faces who know their vertices.  During flood
filling, all vertices are first "ripped" (made
invisible), then starting from the seed(s)
vertices, *neighboring vertices* are added to the
growing patch if (as described above):

 (1) not already added
 (2) not set to "border"
 (3) not currently displaying any label
 (3a) .stat>sfthresh AND cplxamp(val,val2)>fthresh (optional)
 (3b) .stat>sfthresh AND val>fthresh (optional)
 (3c) .stat field equal/above sfthresh (optional)
 (3d) cplxphase (val,val2) in trunphase limits (optional)
 (3e) cplxamp (val,val2) eq/above fthresh (optional)
 (3f) .val field equal/above fthresh (optional)

Two things are done when adding the vertex to the
patch:

 (1) vertex is unripped (made visible)
 (2) vertex is labeled "marked" (white)

When done (no more nearest-neighbor filling
possible after up and down passes of the vertex
list), the non-filled *faces* (as opposed to
vertices) are 'ripped' (made invisible).  This is
done by:

 (1) removing faces with 1+ non-filled vertices
 (2) setting vertices of all ripped faces to 'border'

Thus, invisible vertices are 'ripped' plus
'border', border vertices are 'not ripped' plus
'border', and internal vertices are 'not ripped'
plus 'not border'.

The last step also results in a filled vertex on
the border being not being filled the next time
around because it has now become a border.

To prevent this erosion (e.g., during repeated
FILL's up to a cut), the edge is padded by:

  if any vertex of a face is "marked",
  unrip (make visible) all of its vertices

Then, when faces are ripped, the edge won't be
eroded (if even one vertex of a face is filled,
the face gets drawn).

However, for a floodfill of *vertices* above a
thresh, we typically *don't* want to do this,
since this would add another layer of vertices
that were just below the threshold.  So, the ROI
button always forces an eroding fill.
