-------------------------------------------
tcl/C functions:
  compute_angles
  compute_fieldsign
tcl/C variables:
  $fsdata2gradsflag
  $gradvecflag
  $gradvecbakflag
  $arrownormflag
  $arrowscale
  $angoffrevarrflag
-------------------------------------------

The "F" button on the "fs:" entry line computes
the visual fieldsign and the fieldsign mask.  The
tksurfer.tcl function used to run compute_angles
and compute_fieldsign is: comp_fs

Visual fieldsign data sets are normally generated
using the SessionTools -> Calc Visual Field Sign
panel.

To interactively generate fieldsign data set with
an overlay of the gradient vectors used to
calculate fieldsign using the "F" button, first
do the following:

 (1) load a flat patch (for fieldsign computation)
 (2) load polar angle data ("R" on "val:" line)
 (3) smooth with SMOOTH (e.g., 30 steps)
 (4) Shift-Middle-S/V (swap_valval2_valbakval2bak)
 (5) load eccentricity data ("R" on "val:" line)
 (6) smooth with SMOOTH (e.g., 30 steps)

To access files in another scandir, manually type
the scandir name into the "val:" entry after "*/"
(star-slash), the abbreviation for the session
"image" directory).

Clicking "F" first does:

   compute_angles

to convert complex data in the two pairs of
fields, val/val2, and valbak/val2bak, from real
and imaginary to phase and amplitude (the phase
will end up in the first member of each pair, val
and valbak).

Then, fieldsign is computed with:

  compute_fieldsign

which calculates gradients in the phase of
eccentricity and polar angle and takes the sign
of their cross product.

This fieldsign result is written to $hemi.fs
(amplitude and sign of the cross product between
polar angle and eccen gradients), and $hemi.fm
(geometric mean of amplitude of polar and
eccentricity data) into the current scan
directory (the polar and eccen data may have been
read out of other scandirs):

  setfile fs */$scandir/$hemi.fs
  write_fieldsign
  setfile fm */$scandir/$hemi.fm
  write_fsmask

or, to follow the naming convention for wfiles,
and write files with the same format as curv:

  setfile fs */$scandir/fs-$hemi.w
  write_fieldsign_curvfmt
  setfile fm */$scandir/fm-$hemi.w
  write_fsmask_curvfmt

Finally, the results are auto-loaded as an
underlay (functions below will autodetect and
read either kind of output above):

  read_fieldsign
  read_fsmask
  set colscale 9

On running "F", a popup will ask to to show
gradients, which will set $fsdata2gradsflag to 1
before running compute_fieldsign.  This has the
effect of saving the gradients into the val/va2
and valbak/val2bak fields so they can be
displayed as arrows (replacing the phase and
amplitude information compute_angles put
there, by replacing the original real and
imaginary data).

The following flags are automatically set to
control the display of the gradient arrows:

 set gradvecflag 1       ;# show eccen gradient vector
 set gradvecbakflag 1  ;# show polar gradient vector
 set arrownormflag 1    ;# ignore gradient amplitude
 set arrowscale 0.5      ;# mm length of arrows
 set angoffrevarrflag 0  ;# don't do win-relative polar angle

The settings of $arrownormflag and $arrowscale
can be adjusted using the unlabeled tick box
(arrownormflag) and the unlabeld entry
(arrowscale) at the bottom of the phasecontour
box ("phc").

Arrow colors

The eccentricity gradient (last loaded) arrows
will be red-orange, while the polar angle
gradient (first loaded) arrows will be cyan (the
colors were chosen to be visible over both yellow
mirror image fieldsign and blue non-mirror image
fieldsign).  They can be toggled on and off with
shift-middle-clicking or middle-clicking the
unmarked checkbutton to the left of "fs:".

Gradient directions for default eccen/polar stims

The default eccentricity stimulus moves from
center to periphery.  This means that the
periphery will have later (=larger) phases, and
that the gradient of eccentricity phase will
point toward the periphery.  The eccentriticity
color scale is typically arranged to have the
center of gaze red, intermediate eccentricities
blue, and the periphery green,

The default polar angle stimulus starts at the
horizontal meridian of the right hemifield and
rotates in a counter-clockwise direction.  This
means that the stimulus sweeps lower-to-upper in
the right hemifield (left hemisphere) but sweeps
upper-to-lower in the left hemifield (right
hemisphere).

Thus, in the left hemisphere, the upper field
will have later (=larger) phases, and the
gradient of polar angle will point toward the
upper field.  By contrast, in the right
hemisphere, the *lower* field with have later
(=larger) phases, and the gradient of polar angle
there will point toward the *lower* field.

For the opposite stimuli (contracting
eccentricity stimulus or clockwise polar angle
stimulus) simply reverse everything in the
previous 3 paragraphs :-}
