-------------------------------------------
entry variable: $val -- vtxlist file (real)
-------------------------------------------
default: */scandir1/scan1-$hemi.w

The "val:" entry shows the current vertex list
data file (usu. file with *.w suffix, orig
meaning 'weight'), which will be loaded if
tksurfer was started with data overlay.  To load
a different file, select one from the "val:"
dropdown and click "R" (auto-detects
complex-valued pairs).

The wfile (vertex list file, output of PAINT) is
read into the top of the stack (.val).  This is
also the stack position that can be written out
to a wfile (with "W").

Session directory can be abbreviated as an
asterisk (*).  Absolute name OK, too.  Relative
name appended to session.  The stack is normally
automatically loaded by standard scripts or by
using the complex-valued-data sensitive "R"
button.  The function push_val_val2 can be used
to copy the top of stack (.val) to (.val2) before
reading second data set into top.

Examples:

  pol1_r-rh.w   # real comp. Fourier stats
  pol1_i-rh.w   # imaginary comp. Fourier stats
  pol1_f-rh.mgh # real-valued stats file
  mp2rage_profiles.vtk  # surface + real-valued stats

Six different data formats can be read in here:

 (1) *.w -- wfile fmt (vtxnums plus float data, maybe subset)
 (2) *.w/.curv -- newcurv fmt (floatdata all vtxs, implicit num)
 (3) *.mgh -- pseudovol fmt (float data, all vtxs, implicit num)
 (4) *.vtk -- ASCII fmt (POINT_DATA) w/1+ columns per vtx
 (5) *.gii -- GIFTI overlay format (*.shape.gii, *.func.gii)
 (6) *_000.bfloat -- floatdata all vtxs, implicit num

Valfiles (wfile's) can contain data for a subset
of all vertices in the surface, while newcurv and
bfloat files contain data for all vertices
(ancient 'oldcurv' files *cannot* be read as a
valfile and will be recognized and rejected).
Finally, 1D pseudo-volume *.mgh files and ASCII
*.vtk files can be read.

-----------------------------------------------------
Binary valfile/wfile/*.w file format:
-----------------------------------------------------
  2-byte latency: 0 (was ms lat*10 for EEG/MEG)
  3-byte uint: num painted vertices (usu. subset)
  3-byte uint: painted vertex number
  4-byte float: data
  3-byte uint: painted vertex number
  4-byte float: data
   ...
  [vertices can be in any order]
  [unpainted *and* data=0 vertices not in file]

-----------------------------------------------------
Binary newcurv file format (=newarea):
-----------------------------------------------------
  3-byte magic number: 16777215
  4-byte int: vertex count
  4-byte int: face count
  4-byte int: values per vertex
  4-byte float: data [vtx0]
  4-byte float: data [vtx1]
  ...
  [implicit sequential vtx numbering req'd]
  [all vtxs req'd]

-----------------------------------------------------
Binary 1D .mgh format (now only accepts float)
-----------------------------------------------------
  4-byte int: version (1)
  4-byte int: width (usu. num vertices)
  4-byte int: height (usu. 1)
  4-byte int: depth (usu. 1)
  4-byte int: nframes (usu. 1)
  4-byte int: type (must be 3: 0=byte,1=int,3=float,4=short)
  [skip remaining hdr (bytes=0-283) to 1st img byte=284
  4-byte float: data [vtx0]
  4-byte float: data [vtx1]
  [begin first frame/brik]
  ...
  [maybe begin second frame/brik]
  ...
  [skip footer]
  [skip tags]

-----------------------------------------------------
ASCII 1D .vtk format (surface + overlay data)
-----------------------------------------------------
  ... [opt. surf spec -- see Help -> csurf]
----- anything above here ignored ----
  POINT_DATA <vertexcount>
  SCALARS EmbedVertex float <columncount>
  LOOKUP_TABLE default
  column1value column2value ... [columncount entries]
  column1value column2value ... [columncount entries]
  ... [implitictly num'd tuples to vertexcount]

-----------------------------------------------------
GIFTI 1D .gii format (overlay data)
-----------------------------------------------------
  <?xml version="1.0" encoding="UTF-8"?>
  <GIFTI ...
         NumberOfDataArrays="1">
  ...
    <DataArray Intent="NIFTI_INTENT_NORMAL"
               DataType="NIFTI_TYPE_FLOAT32"
               ArrayIndexingOrder="RowMajorOrder"
               Dimensionality="1"
               Dim0="32492"
               Encoding="GZipBase64Binary"
               Endian="LittleEndian"
               ExternalFileName=""
               ExternalFileOffset="0">
      ...
      <Data>
        [usu: base64 encoded gzipped binary data]
      </Data>
    </DataArray>
  </GIFTI>

For details, see: https://www.nitrc.org/projects/gifti/

-----------------------------------------------------
Binary/ASCII bfloat-plus-hdr file format:
-----------------------------------------------------
  <stem>_000.bfloat 
  <stem>_000.hdr
  <stem>_001.bfloat 
  <stem>_001.hdr
  . . .

The *.bfloat files are MSB floats with no header
and the *.hdr files are one-line ASCII files:

  <y> <x> <t> 0

where y=1, x=vertexcnt, and t=1.  The second
number must match the number of vertices in the
current surface.
-----------------------------------------------------

Multiple frames

If the .mgh file header says it contains more
than one frame, the "R" button will bring up a
popup to allow resetting the variable
$mghvalframe from its default (0=firstframe).

[TODO: implement above for multi-frame bfloat's]

One-frame files with height and/or depth not
equal to 1 (e.g., single-frame FSL .mgh output)
can be read if width*height*depth = numvertices
in current surface.

If the .vtk has a line as follows, whose 4th
argument is larger than 1:

  SCALARS EmbedVertex float 21

the "R" button will bring up a popup to allow
resetting the variable $vtkvalcolumn from its
default (0=firstcolumn).  A pseudo-vtk file that
begins with a POINT_DATA line will also be
accepted.

GIFTI files are expected to contain only one
frame.

Output format

Two flags, both currently unset (=0) by default,
modify format of an *output* val file:

  allverticesflag -> write full (3-byte style) wfile
     (vs. just non-zero vertices)

  val2newcurvflag -> write full newcurv wfile
     (ignores allverticesflag)

A middle-click on the "val:" label makes a popup
for interactively controlling these flags.

