#### FIELDSIGN, GRADIENT ARROWS CONTROLS ####
-------------------------------------------
toggle variable (left-click tickbox):
  $nonbinaryfsflag -- toggle fs approx=0 valley
-------------------------------------------
toggle variable (shift-middle-click tickbox):
  $gradvecflag -- toggle val/val2 arrows
-------------------------------------------
toggle variable (middle-click tickbox):
  $gradvecbakflag -- toggle valbak/val2bak arrs
-------------------------------------------
toggle variable (ctrl-middle-click tickbox):
  $gradvecbak3dflag -- toggle valbak/val2bak 3D arrows
-------------------------------------------
toggle variable (popup):
  $reggradvecbakflag -- per-region valbak/val2bak arrows
-------------------------------------------
toggle variable (popup):
  $reggradvecbak3dflag -- per-region val/val2bak 3D arrows
-------------------------------------------
toggle variable (popup):
  $arrownormflag -- toggle gradient arrow norm
-------------------------------------------
toggle variable (popup):
  $filledarrowsflag -- toggle filled vs. line arrows
-------------------------------------------
toggle variable (popup):
  $centerarrowsflag -- toggle cent on vertex vs. from vtx
-------------------------------------------
toggle variable (popup):
  $angoffrevarrflag -- toggle disp pol/ecc as screen-rel arr
-------------------------------------------
toggle variable (popup):
  $flipRHpolararrowsflag -- flip RH arrows to match colscale
-------------------------------------------
variable: $arrowscale (popup) -- arrow length
-------------------------------------------
variable: $arrowline (popup) -- arrow stem thickness
-------------------------------------------
variable: $arrowheadfracauto (popup) -- head frac stem len
-------------------------------------------
variable: $arrowheadmin (popup) -- minimum head length
-------------------------------------------
variable: $line_arrowbarbangle (popup) -- angle barbs/stem
-------------------------------------------
variable: $filled_arrowtipangle (popup) -- ang tip-edge/stem
-------------------------------------------
variable: $filled_arrowbarbangle (popup) -- ang barbs/stem
-------------------------------------------
variable: $gridsize (popup) -- requested downsamp interval
-------------------------------------------
variable: $sdoutlierfact (popup) -- crop lg arr g.t. this * stdev
-------------------------------------------
variable: $areaoutliermin (popup) -- min vtx area to disp arr
-------------------------------------------
toggle variable (popup):
  $rmgradoutliersflag -- toggle rm grad arrows outliers
-------------------------------------------
toggle variable (popup):
  $prunearrowsflag -- toggle arrow downsampling
-------------------------------------------
button: PRUNE ARROWS (popup button)
  function: prune_arrows <gridsize>
-------------------------------------------
button: DENSE ARROWS DEFAULTS (popup button)
  function: [reset multiple panel variables]
-------------------------------------------
button: SPARSE ARROWS DEFAULTS (popup button)
  function: [reset multiple panel variables]
-------------------------------------------

This unlabeled tickbox to left of fieldsign file
entry ("fs:") toggles a fieldsign display setting
(how to color ambiguous fieldsign) and has many
additional flags for controlling display of
gradient arrows and per-vertex vectors.

The best way to access these (and more above)
parameters is by a right-click on that tickbox to
pop up a control panel (along with this help
panel; also auto-pops up when R-clicking the
gradient button, GR).

A number of these parameters are duplicated on
the ARROWS/NORMALS/POINTS popup available from a
R-click on the unlabeled tickbox at the bottom of
the "phc" (phasecontours) panel at the middle
left of the tksurfer panel.

-------------------------------------------
Left-click tickbox (toggle $nonbinaryfsflag)
-------------------------------------------

The default left-click toggles $nonbinaryfsflag.
When it is set to 1 (ticked) near-zero fieldsign
values fade from yellow/blue coloring to gray.
This is in addition to main modulation by fsmask.
The width of the near zero valley is controlled
by $fsslope which is the unlabeled energy just to
the right of the tick.  No effect on oldstyle
$hemi.fs files, which were clamped to -1,0,1.

-------------------------------------------
Shift-Middle-click tickbox (toggle $gradvecflag)
-------------------------------------------

A non-default shift-middle-click on this tick box
toggles $gradvecflag, which controls whether the
val/val2 fields should be shown as overlay
arrows.

This can also be used to toggle visibility of one
of two gradients when fieldsign has been computed
with $fsdata2gradsflag set to 1, which causes the
data loaded into both val/val2 and valbak/valbak2
to be replaced with gradients.

-------------------------------------------
Middle-click tickbox (toggle $gradvecbakflag)
-------------------------------------------

A second non-default middle-click on this tick
box toggles $gradvecbakflag, which controls
whether or not gradients loaded into the
valbak/val2bak fields should be shown as overlay
arrows.

This sets arrowscale to 5.0 and unsets
$arrownormflag and $angoffrevarrflag (if
$gradvecflag is not set).

-------------------------------------------
Control-Middle-click tickbox (toggle $gradvecbak3dflag)
-------------------------------------------

A third non-default control-middle-click on this
tick box toggles $gradvecbak3dflag, which
controls whether the valbak/val2bak/val3bak
fields should be shown as 3D overlay arrows or
not.

In contrast to the previous two cases (2d arrows)
the 3d arrows follow the folded surface.


R-click Popup: tickboxes, entry variables, buttons

-------------------------------------------
tick: $reggradvecbakflag (popup) -- per-region valbak/val2bak arrows
-------------------------------------------

This flag, $reggradvecbakflag, toggles visibility
of per-region average gradient arrows on 2D/flat
surfaces.  No effect unless MGH annotation has
been read on top of real or complex-valued data,
and a gradient (curv, val, angle-of-complex) has
been calculated using the "GR" button on the
"fs:" line (R-click on "GR" to get 12-button
popup, use bottom buttons 7-9).

N.B.: this overrides $gradvecbakflag, so it must
be unticked to reveal full field of dense (or
dense-pruned) per-vertex gradient arrows.

-------------------------------------------
tick: $reggradvecbak3dflag (popup) -- per-region val/val2bak 3D arrows
-------------------------------------------

This flag, $reggradvecbak3dflag, toggles
visibility of per-region average gradient arrows
on 3D surfaces.  No effect unless MGH annotation
has been read on top of real or complex-valued
data, and a gradient (curv, val,
angle-of-complex) has been calculated using the
"GR" button on the "fs:" line (R-click on "GR" to
get 12-button popup, use bottom buttons 10-12).

N.B.: this overrides $gradvecbak3flag, so it must
be unticked to reveal full field of dense (or
dense-pruned) per-vertex gradient arrows.

-------------------------------------------
tick: $arrownormflag (popup) -- toggle gradient arrow norm
-------------------------------------------

This unlabeled tick at the bottom of the
phasecontour box ("phc") (or $arrownormflag on 
the popup) toggles whether gradient vector
lengths are normalized to the same length or are
proportional.  Gradient vectors are calculated
and displayed when the "F" (fieldsign) or "GR"
(calculate gradients) buttons on the "fs:" line
are used.  See the R-click help for "F" and "GR"
for details. 

If the gradients were calculated on phase-encoded
data (i.e., on the phase angles), they will be
appoximately perpendicular to the iso-phase
contours (hence placement of these controls
here).

The unmarked entry immediately to the right of
the tickbox scales the gradient vectors (whether
normalized or not).  When $arrownormflag
(constant length gradient arrows) is enabled,
that field will be autoset to a sane value of 0.5
mm (which can be adjusted afterward).

-------------------------------------------
tick: $filledarrowsflag (popup) -- toggle filled vs. line arrows
-------------------------------------------

This toggles between line arrows and filled
arrowheads.  The filled arrowheads are made of
four adjustable triangles: two for the arrow
barbs, and two forming a diamond for the point.

Depending on the data gradients, other arrow
parameters may need adjusting when this is
toggled.  There is a DEFAULT LINE/FILL ARROWS
button to set defaults for each type.

Currently filled arrows only working for 2D/flat
gradient arrows (no effect of ticking this on 3D
surface arrows).

-------------------------------------------
tick: $centerarrowsflag (popup) -- toggle center arrow on vertex
-------------------------------------------

The default state (ON) centers the stem of the
arrow on the vertex to which it belongs (else,
the arrow stem starts from the vertex).

The only time this is forced off is when two
arrows are drawn at each vertex to illustrate the
polar and and eccentricity gradients at the same
time.

-------------------------------------------
tick: $angoffrevarrflag (popup) -- toggle display polar arrows
-------------------------------------------

Toggles the value of $angoffrevarrflag, which
causes polar angle data in the val/val2 fields to
be displayed as arrows.  For more details see the
end of this R-click help.

-------------------------------------------
tick: $flipRHpolararrowsflag -- flip RH arrows to match colscale
-------------------------------------------

Because standard rotating wedge polar angle
mapping stimuli result in phases with opposite
signs in left and right hemispheres, by default,
$flipRHpolararrowsflag is ON, which causes a 180
deg flip of RH gradient arrows (to match the flip
in the standard polar angle color scales).
Gradient arrows are only flipped if:

  (1) complexvalflag is ON
  (2) hemi is "rh"
  (3) angle_cycles is *not* an integer (1.0, 2.0, ...)

Turning OFF $flipRHpolararrowsflag stops all
arrow flipping.

-------------------------------------------
variable: $arrowscale (popup) -- arrow length
-------------------------------------------

The displayed length of gradient arrows can be
globally adjusted with the entry variable,
$arrowscale (default=2.0), which is a fraction
applied to all arrows.  Alternatively, if arrow
length has been normalized (made all the same)
with $arrownormflag, $arrowscale will then be in
units of mm.

-------------------------------------------
variable: $arrowline (popup) -- arrow stem thickness
-------------------------------------------

The thickness of the line used to draw line
arrows (stem and arrowhead are lines) is
controlled with the entry variable, $arrowline.
When $filledarrowsflag is ticked, this entry
controls the thickness of the arrow stem.

-------------------------------------------
variable: $arrowheadfracauto (popup) -- head frac stem len
-------------------------------------------

This variable specifies the size of the arrowhead 
as a fraction of the arrow stem length; as the
arrow length declines, the arrow barbs do too 
(with a minimum cutoff, see next variable).  To
turn off this scaling, in order to get constant
size arrowheads, set this to 0.0.

-------------------------------------------
variable: $arrowheadmin (popup) -- minimum head length
-------------------------------------------

When $arrowheadfracauto (above) is non-zero, this
variable, $arrowheadmin, sets the minimum size of
the arrowhead (as a fraction of the arrow stem
length).  When arrow-length normalization is 
turned off by settings $arrowheadfracauto to
zero, this variable will set the fixed size for
all arrowheads.

-------------------------------------------
variable: $line_arrowbarbangle (popup) -- ang barbs/stem
-------------------------------------------

For line arrows, this variable sets the angle of
the arrow barbs relative to the arrow stem
(default 22.5 deg).  No effect on filled arrows.

-------------------------------------------
variable: $filled_arrowtipangle (popup) -- ang tip-edge/stem
-------------------------------------------

For filled arrows, this variable sets the angle
of the tip of the arrow relative to the arrow
stem (default 15 deg).  If this angle is small
(like the default), the sides of the arrow barbs
will be concave.  Increasing it will make sides
of the arrow barbs flat, and then eventually
convex.  Set to taste.  No effect on line arrows.

-------------------------------------------
variable: $filled_arrowbarbangle (popup) -- ang barbs/stem
-------------------------------------------

For filled arrows, this variable sets the angle
of the arrow barbs relative to the arrow stem
(default 60 deg).  Increasing it makes a fatter
arrowhead.  No effect on filled arrows.

-------------------------------------------
variable: $gridsize (popup) -- requested downsamp interval
-------------------------------------------

Sets the gridsize (in mm) for pruning arrows.
Only the single arrow closest to each grid cell
will be shown when $prunearrowsflag is on.

-------------------------------------------
variable: $sdoutlierfact (popup) -- crop lg arr if g.t. this x stdev
-------------------------------------------

This crops extra-large arrows if the arrow
amplitude is greater than this factor
($sdoutlierfact) times the standard deviation of
all the arrows amplitude (default: 2x stddev).

-------------------------------------------
variable: $areaoutliermin (popup) -- min vtx area to disp arr
-------------------------------------------

This crops extra tiny arrows if the vertex area
(vertex[i].area) is below this ($areaoutliermin)
(default: 0.02).

-------------------------------------------
toggle: $rmgradoutliersflag (popup) -- toggle rm grad outliers
-------------------------------------------

This toggles whether to remove of overly large
gradient arrow outliers (based on the standard
deviation of the other arrow amplitudes), as well
as overly tiny arrows (based on tiny vertex
area).

N.B.: since this flag is only consulted during
gradient calculation, re-calculate gradient to
see the effect of changing it.

-------------------------------------------
toggle: $prunearrowsflag (popup) -- toggle arrow downsampling
-------------------------------------------

This flag toggles arrow pruning.  The removed
arrows are still there, just hidden when
$prunearrowsflag is on.

-------------------------------------------
button: PRUNE ARROWS (popup)
  function: prune_arrows <gridsize>
-------------------------------------------

Gradient calculations result in a very large
number of gradient arrows (one per vertex), which
will look cluttered (unless the surface is
strongly zoomed).  A R-click on the unlabeled
tickbox to the left of "fs:" (middle left),
brings up a popup for controlling gradient (and
fieldsign) arrows.

There is a PRUNE ARROWS button at the bottom of
the popup.  The density of arrows is set by the
$gridsize parameter (in mm) on the popup.  The
"prunearrowsflag" toggles between pruning and no
pruning.  N.B.: click PRUNE ARROWS again to see
the effect of adjusting $gridsize.

The pruning works by only showing one arrow for
each specified-size grid cell.  Since the actual
vertex location of the winning arrow is used, the
grid will be slightly irregular. Try slight (+/-
0.1) adjustments for fine-tuning.

Also remember that *.val (or *.stat) thresholds
can be used to prune 'noise' arrows by setting
$fthresh (or $sfthresh if "mask" is ticked), and
then recalculating the gradient arrows.

-------------------------------------------
button: DENSE ARROWS DEFAULTS (popup button)
  function: [reset multiple panel variables]
-------------------------------------------

The line arrows and filled arrows need subtly
different settings to look good on the same data.
Also, different gradient data requires different
settings.

The DENSE ARROWS DEFAULTS button sets sane
defaults, depending on whether $filledarrowsflag
is on or off, for gradient of retinotopic mapping
phase data.

-------------------------------------------
button: SPARSE ARROWS DEFAULTS (popup button)
  function: [reset multiple panel variables]
-------------------------------------------

The SPARSE ARROWS DEFAULTS button has a similar
function to the above button, but for arrows that
have been pruned to a (default) 3 mm grid, so the
arrows are bigger and thicker.

-------------------------------------------
HOWTO load your own vertex-wise vector field
-------------------------------------------

To load a vector field overlay of your own making
(over any data set) on a flat patch:

 1) put x,y vectors into complex label (6 entries per line)
 2) read with "R" on "label:" line (goes to va/val2 fields)
 3) shift-middle-click "S/V" => swap to cmplx stack bottom
 4) load surface data over which arrows will be displayed
 5) tick popup gradvecflag (or shift-mid-clk mainpanel tick)

Note that arrows will rotate with the pose of the
flat patch (i.e., the arrows will be stuck to the
surface).  The z-rotation of the flat patch is
typically saved in Preferences -> Expert
Preferences -> Views.

Because of the way patches are flattened, if the
rotation of the patch view has been set to zero,
unfortunately the positive y direction is *down*
and the positive x direction is *left*.  Thus,
the vector (1,1) will point down and to the lower
left in the window (both reversed from normal
expectations).

-------------------------------------------
HOWTO View polar angle arrows (hack)
-------------------------------------------

If $gradvecbakflag is *not* set (i.e., you are
*not* displaying two sets of gradients), this
action also does an additional thing:

  set arrowscale 0.5       ;# mm
  set arrownormflag 1     ;# unit length vectors
  set angoffrevarrflag 1   ;# use angle_offset/revphaseflag

in order to view raw polar angle phase data as a
field of arrows relative to screen.

Note that in contrast to the display of gradient
arrows, the arrows here are drawn *relative to
the window frame* -- that is, upward arrows
indicate upper field polar angle data and left
arrows indicate left hemifield.  Unlike the
gradient arrows, rotating the flat patch will
have no effect on the orientation of these
arrows, and the settings of $angle_offset and
$revphaseflag will affect the arrows.

The $angoffrevarrflag can be directly toggled
with a middle-click on the unlabeled tick box at
the bottom of the phasecontours box to the left
of "fmid:" (a regular left-click here toggles
$arrownormflag).

Interface uglies

The overloaded "fs:" line tick box mark only
reflects the state of $nonbinarfsflag even tho
the other flags are being toggled.  Same for the
(unlabeled) $arrownorm/$angoffrevarrflag.

It is much easier to use the popup from R-click
help on the "fs:" line tickbox (same popup from a
R-click on the "GR" button), which explicitly shows
all the parameters.  A R-click on the unlabeled
tickbox at the bottom of the mid right "phc" panel
makes another popup with most of these parameters
(as well as paramters for controlling the display
of normals, edges, points, and the cursor).

Since the 'direct display' of phase data responds
to angle_offset and revphaseflag as well as
hemisphere (so arrows point into the correct
hemifield), the *raw phase* can only be displayed
in the right hemisphere with angle_offset = 0 and
revphaseflag off.

