#### swap values on the vertexwise data stack ####
-------------------------------------------
funct: "Swap Stat/Val (left-click-S/V)"
  swap_stat_val
-------------------------------------------
funct: "Swap Val/Val2 (mid-click-S/V)"
  swap_val_val2
-------------------------------------------
funct: "Swap Two Complex (shift-mid-clk-S/V)"
  swap_valval2_valbakval2bak
-------------------------------------------
funct: "Swap Pval/Val (shift-left-click-S/V)"
  swap_pval_val
-------------------------------------------
funct: "Swap Curv/Curvbak (shift-right-click-S/V)"
  swap_curv_curvbak
-------------------------------------------
funct: "Swap Curv/Val (ctrl-right-click-S/V)"
  swap_curv_val
-------------------------------------------
funct: "Swap OrigArea/Val (ctrl-mid-click-S/V)"
  swap_origarea_val
-------------------------------------------
funct: "Copy IDnum to Val (ctrl-left-click-S/V)"
  copy_idnum_val
-------------------------------------------


The "S/V" button on the "val:" entry line
manipulates the position of vertexwise data in
the stack of 6 values at each vertex using 4
different functions (an additional 3 functions
manipulate curvature and annotation idnums -- see
below).

Note that only the top one (or top pair) is
visible on the displayed surface (the
vertex[i].val field for real-valued data if
complexvalflag is 0, or the vertex[i].val and
vertex[i].val2 fields for complex-valued data if
complexvalflag is 1).

The stack at each numbered vertex[i] looks like
this:

  vertex[i].val		(always visible)
  vertex[i].val2		(visible if complexvalflag is 1)

  vertex[i].stat		(invisible)
  vertex[i].pval		(invisible)

  vertex[i].valbak		(invisible)
  vertex[i].val2bak		(invisible)


Data is typically only read into or written from
the top of the stack.  Even though the .stat
field is not directly visible, if "mask" is
clicked, it will be used to mask the visible part
of the stack.

The following current color scale settings are
swapped along with the data:

  colscale
  fthresh
  sfthresh
  fmid
  sfmid
  fslope
  sfslope
  angle_cycles
  angle_offset
  revphaseflag
  ipsiyellowfact

-------------------------------------------
funct: "Swap Stat/Val (left-click-S/V)"
  swap_stat_val
-------------------------------------------

Swap the stat and val data fields at each vertex
(vertex[i].stat and vertex[i].val).  A typical
usage is:

  "R" statfile
  left-click "S/V"
  "R" valfile

or equivalently:

  "R" valfile
  left-click "S/V"
  "R" statfile
  "S/V"

Here are tcl script commands to do the same thing:

  setfile val */scan1/statfile.w
  [or: set val /some/statfile.w]
  read_binary_values
  swap_stat_val
  setfile val */scan1/valfile.w
  [or: set val /some/valfile.w]
  set colscale <num-that-uses-stat-and-val>
  redraw

See also:

  push_val_val2               copy val to val2
  swap_val_val2               swap val and val2
  swap_valval2_valbakval2bak  swap 2 complex nums

Finally, it is also possible to read a stat file
directly into the stat field without using swap
function:

  setfile stat */scan1/statfile.w
  read_binary_stats

This function can also be used to directly view
the stat field on the surface (use a real-valued
color scale like "BR").

-------------------------------------------
funct: "Swap Val/Val2 (mid-click-S/V)"
  swap_val_val2
-------------------------------------------

If the "S/V" button is middle-clicked (instead of
default left-clicked), an alternate swap function
is called:

  swap_val_val2

Swap the .val and the .val2 data fields at each
vertex (vertex[i].val and vertex[i].val2).  A
typical usage is:

  "R" imaginary valfile
  middle-click "S/V" (swap_val_val2)
  "R" real valfile

-------------------------------------------
funct: "Swap Two Complex (shift-mid-clk-S/V)"
  swap_valval2_valbakval2bak
-------------------------------------------

If the "S/V" button is shift-middle-clicked
(instead of default left-clicked), another
alternate swap function is called:

  swap_valval2_valbakval2bak

This function swaps the position of a pair of
complex-valued data sets, A and B, on the
vertex-wise data stack.  If the starting
condition is as follows:

 vertex[i].val		-> real-A
 vertex[i].val2		-> imaginary-A

 vertex[i].stat		(not touched)
 vertex[i].pval		(not touched)

 vertex[i].valbak		-> real-B
 vertex[i].val2bak		-> imaginary-B

after executing the function, the ending
condition is:

 vertex[i].val		-> real-B
 vertex[i].val2		-> imaginary-B

 vertex[i].stat		(not touched)
 vertex[i].pval		(not touched)

 vertex[i].valbak		-> real-A
 vertex[i].val2bak		-> imaginary-A

This function is used to load a pair of
complex-valued data sets prior to calculating
visual field sign, finding retinotopic areas by
region growing, or performing correlations as
follows:

  ### read eccen imaginary, push
  setfile val */$eccendir/${eccenstem}_i-$hemi.w
  read_binary_values
  smooth_val $smoothsteps
  push_val_val2
  ### read ecc real
  setfile val */$eccendir/${eccenstem}_r-$hemi.w
  read_binary_values
  smooth_val $smoothsteps
  ### swap complex
  swap_valval2_valbakval2bak

  ### read polar imaginary, push
  setfile val */$polardir/${polarstem}_i-$hemi.w
  read_binary_values
  smooth_val $smoothsteps
  push_val_val2
  ### read polar real
  setfile val */$polardir/${polarstem}_r-$hemi.w
  read_binary_values
  smooth_val $smoothsteps
  ### swap complex (ecc on top)
  swap_valval2_valbakval2bak

-------------------------------------------
funct: "Swap Pval/Val (shift-left-click-S/V)"
  swap_pval_val
-------------------------------------------

Swap the pval and val data fields at each vertex
(vertex[i].pval and vertex[i].val).  This
function makes the pval visible and saveable.

Currently, the .pval field is only loaded when
corr_over_label is run ("X" button on "label:"
line).  In that case, the pval is saved as the
positive power of ten; for example, p<0.01 is
saved as 2.0

-------------------------------------------
funct: "Swap Curv/Curvbak (shift-right-click-S/V)"
  swap_curv_curvbak
-------------------------------------------

Swap the curv and curvbak data fields at each
vertex (vertex[i].curv and vertex[i].curvbak).

In addition to the overlay stack described above,
there also two curvatures at each vertex:

  vertex[i].curv	(visible [unless surfcolor=0])
  vertex[i].curvbak	(always invisible)

This can be used to toggle between two curvatures
(e.g., native curvature and target template
curvature):

  set template /Applications/freesurfer/average/..buckner40..
  set templateframe 6
  read_tif_template
  swap_curv_curvbak
  read_binary_curv
  ### compare
  swap_curv_curvbak
  swap_curv_curvbak
  swap_curv_curvbak
  ...

-------------------------------------------
funct: "Swap Curv/Val (ctrl-right-click-S/V)"
  swap_curv_val
-------------------------------------------

Swap the curv and val data fields at each vertex
(vertex[i].curv and vertex[i].val).

N.B.: if .val is part of a complex number
(val,val2), this can make the overlay colors
nonsensical (undo by re-apply).

This can be used to import a template variable
into the data overlay stack:

  set template /my/template/file
  set templateframe 3
  read_tif_template
  swap_curv_val

To import a complex-valued data overlay from two
frames of template data, do something like:

  set template /my/template/file
  set templateframe 6  ;# imaginary
  read_tif_template
  swap_curv_val
  swap_val_val2
  set templateframe 3  ;# real
  read_tif_template

-------------------------------------------
funct: "Swap OrigArea/Val (ctrl-mid-click-S/V)"
  swap_origarea_val
-------------------------------------------

Swap the origarea and val data fields at each
vertex (vertex[i].origarea and vertex[i].val).

N.B.: if .val is part of a complex number
(val,val2), this can make the overlay colors
nonsensical (undo by re-apply).

This can be used to import a valfile (e.g., an
*.mgh file) into the 'original area' field
(.origarea), which is typically loaded at startup
with the $hemi.area file.

-------------------------------------------
funct: "Copy IDnum to Val (ctrl-left-click-S/V)"
  copy_idnum_val
-------------------------------------------

Copy the integer idnum into the val data field at
each vertex (copy brainregion[i].idnum to
vertex[i].val).  An annotation must first be
loaded.

This is useful for writing out quick-and-dirty
annotation-like files in labelfile or valfile
format (using "W" on the "label:" line, or "W" on
the "val:" line).

The x,y,z coordinates written to the label file
will respect any currently set normal search
parameters (left-click "label:" to get popup to
adjust).  The will also respect the settings of
the upper left "|ta|cu|" select buttons (origsurf
vs. currsurf vs. MNI 305 Talairach vs. MNI 152
Talairach coordinates).

To display/verify the integer values, you can
make a random color lookup table with the
supplied $CSURF_DIR/bin/noarch program,
mkrandlut:

  mkrandlut <minval> <maxval> <step> [rseed]

For example, to make a random color LUT for the
CsurfMaps1 annotation file (117 regions) for
fsaverage, do the following in bash/tcsh to write
a val2rgb.lut file to the cwd:

  cd $SUBJECTS_DIR/fsaverage/script
  $CSURF_DIR/bin/noarch/mkrandlut 0 117 1

Then click "Col:" to get colscale popup, select
color scale 12 ("lt"), and read the val2rgb.lut
file with "R" on the "lut:" line.
