#### read vertexwise data to .val field, (also vectors) ####
-------------------------------------------
funct: "Read Valfile, Real Or Complex (left-click-R)"
  set val <infile>
  read_binary_values
  [tcl: read_real_or_complex_binary_values]
-------------------------------------------
funct: "Same As Above + Demean, VarNorm (mid-clk-R)"
  set val <infile>
  read_binary_values
  [tcl: read_real_or_complex_binary_values]
  demean_varnorm_val
-------------------------------------------
functs: "Read Valfile Real/Imag,Set Amp=1 (shift-mid-clk-R)"
  set val <infile>
  read_binary_values
  [tcl: read_real_or_complex_binary_values]
  meanamp2one_valval2
-------------------------------------------
funct: "Read 3-Frame *.mgh File as Vect (shift-right-clk-R)"
  set val <infile>   [must be 3-frame *.mgh]
  read_mgh_dipoles
-------------------------------------------


Detailed Description of Label "R" Button Actions

-------------------------------------------
funct: "Read Valfile, Real Or Complex (left-click-R)"
  set val <infile>
  read_binary_values
  [tcl: read_real_or_complex_binary_values]
-------------------------------------------

A default left-click the "R" button on the "val:"
entry line reads painted surface vertexwise data
from file whose name is current value of $val
(entry at left).  Re-read overwrites any data
currently in the vertex[i].val field.

The entire .val field is always zeroed before
reading, even with file formats containing vertex
subsets.

The read_binary_values function can auto-detect
and read the following formats, mostly using
magic numbers (first 3 bytes):

  *.w -- freesurfer wfile, usu. vertex subset
  *.w/*.curv -- new curv/area, req's data all vtxs
  *.mgh -- 1D float real data (req's *.mgh suff)
  *.vtk -- 1D ASCII real (req's *.vtk suff)
  *.vtk-like -- 1D ASCII beginning w/POINT_DATA
  *.gii -- single-frame vertex-data GIFTI file
  *_000.bfloat -- bfloat, req's data all vtxs

In order for *.w files to be loaded into the
dropdown, they should have the format:

  <stem>-?h.w

and similarly, for bfloat files:

  <stem>-?h_000.bfloat
  
See R-click help for val entry for details of
file formats.  The old curv format (truly
ancient) cannot be read by the "val:" field.

In the special case where:

  1) complexvalflag is set ("cpx" checked)
  2) the entry matches this pattern:  *_?-?h.w
  3) the infix is: _r or _i (or _x or _y)

such as:

  */image/pol1/pol1-vreg+orig_r-rh.w

the "R" button (tksurfer.tcl wrapper function:
read_real_or_complex_binary_values) will
auto-read complex valued data using these
commands:

  set infix $imag
  setfile val ${stem}${infix}-${hemi}.w
  read_binary_values
  push_val_val2
  set infix $real
  setfile val ${stem}${infix}-${hemi}.w
  read_binary_values

using $stem, $hemi, and $real and $imag infixes
extracted from the filename in the entry.  The
filename in the entry can contain either the real
(_r or _x) or imaginary (_i or _y) infix.

The same works for complex-valued bfloat file
pairs.

In cases where a *.mgh file contains more than
one frame, a pop-up allows a non-zero-index frame
to be chosen.

See read_mgh_dipoles below for how to read a
3-frame surface-vertex-list *.mgh file in order
to display it as surface ball-and-stick vectors.

Functions to Manipulate Read-In Data

Some of the tcl script functions that can copy or
move data out of the .val field, or manipulate it
in place include:

 swap_stat_val		swap stat/val (S/V)
 swap_val_val2		swap val/val2 (middle-S/V)
 swap_pval_val		swap pval/val (shift-left-S/V)
 swap_valval2_valbakval2bak
		swap 2 real or cplx (shift-middle-S/V)
 swap_curv_val
 swap_pval_val
 swap_val_val2		swap real/imag
 swap_val_valbak        
 copy_val_val2		copy val to val2 (script only)
 copy_val_dip <0=x,1=y,2=z>
 clear_values		both .val .val2
 scale_val <scalefact>
 subtr_valbak_from_val

The .val field is the 'top of the stack', usually
the first entry point for vertexwise data.  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, maybe modulates)
  vertex[i].pval		(invisible, maybe modulates)

  vertex[i].valbak		(invisible, maybe compute with)
  vertex[i].val2bak		(invisible, maybe compute with)

Conversions

The commandline program calcvert can covert
between a number of different formats.  For
example, the following converts an ASCII label
file to a wfile.  Note that the hemisphere
(lh,rh) must be placed first in a label filename,
but just before the *.w suffix in a wfile
filename:

  calcvert -convert -labelfilein -valfileout rh-MT.label MT-rh.w


-------------------------------------------
funct: "Same As Above + Demean, VarNorm (mid-clk-R)"
  set val <infile>
  read_binary_values
  [tcl: read_real_or_complex_binary_values]
  demean_varnorm_val
-------------------------------------------

Similar to read_binary_values above, but subtract
mean, divide by standard deviation after read.

N.B.: the de-mean and divide-by-standard
deviation operations are only computed using
currently visible/uncut vertices.


-------------------------------------------
functs: "Read Valfile Real/Imag,Set Amp=1 (shift-mid-clk-R)"
  set label <outfile>
  read_binary_values
  [tcl: read_real_or_complex_binary_values]
  meanamp2one_valval2
-------------------------------------------

Similar to above, but scale complex amplitude of
.val/.val2 to one, without changing phase.

N.B.: the average complex amplitude is only
computed across currently visible/uncut vertices.


-------------------------------------------
funct: "Read 3-Frame *.mgh File as Vect (shift-right-clk-R)"
  set val <infile>   [must be 3-frame *.mgh]
  read_mgh_dipoles
-------------------------------------------

[N.B.: this one doesn't touch .val field!]

Read a 3-frame vertexwise *.mgh file into the
.dip{x,y,z} fields and display it as a field of
magenta ball-and-stick vectors.

N.B.: any vectors pointing into the surface are
reversed (flipped outward).  A shift-right-click
on the unlabeld arrowscale tickbox (in the
middle-right "phc" box) toggles vector display.

