#### find/write uniq sample vertices ####
-------------------------------------------
functs (left-click): find/show uniq vertices
  find_uniqsamp_vertices
  select_uniqsamp_vertices
-------------------------------------------
functs (middle-click): also write scandir label
  find_uniqsamp_vertices
  select_uniqsamp_vertices
  write_uniqsamp_vertices
-------------------------------------------


Detailed Description of "UQ" Button Actions

-------------------------------------------
functs (left-click):
  find_uniqsamp_vertices
  select_uniqsamp_vertices
-------------------------------------------

A default left-click on the "UQ" button on the
"val3d:" entry line marks 3D-voxel-unique
'representative' vertices.  To do this:

 0) [click "val:" to toggle to "val3d:"]
 1) select 3D stat BRIK from "val3d:" dropdown
 2) read 3D data with "val3d:" "R" button
 3) sample 3D data to surface with "PA" (paint) button
 4) click UQ

Note that this must be a directory with 3D data
and a register.dat in it (see below for
surface-averaged data).

Since 3D functional data usually has larger
voxels than the 1x1x1 (or better) structural
scans used to reconstruct the cortical surface,
each functional voxel will typically be
nearest-neighbor sampled to more than one 2D
surface vertex.

For each set of vertices that has sampled the
same 3D functional voxel (as determined when
paint_surface uniquely numbers the 3D voxels it
is sampling), the "UQ" button does the following:

 1) get avg 3D location of vertices in unique voxel set
 2) find vertex in set whose location is closest to avg
 3) vertex[win].uniqvoxcnt 'winner' set to num vtxs
 4) vertex[lose].uniqvoxcnt 'losers' all set to 0
 5) uniq vertices marked (can be saved, see below)

N.B.: this doesn't work if the normal search
operation ($normdop) is set to 1 (average), since
more than one voxel is sampled in that case.

The resulting set of vertices can be saved in a
label by typing a suitable label name (e.g.,
lh-UniqSampVtxs.label) and ctrl-left-clicking "D"
on the "label:" line, which calls the function,
write_val_selected_list_to_label.

The tcl/C functions used to perform the full
sequence of actions listed at the top (read 3D
data, paint and find unique vox sets, find
representative vertices, display representative
vertices) are:

  read_native_stat <0=real,1=imag>
  paint_surface <fstatflag=0,1>
  find_uniqsamp_vertices
  select_uniqsamp_vertices      ;# display

Sampling surface

The "UQ" button by default temporarily reloads
the coordinates of the current "original" surface
(e.g. "white") before finding uniq vertices for
each sampled voxel (like PA [=paint] does).  To
instead use the current surface for the uniq'ing
operation, tick "c2lab" (this sets
($usecurrcoordsflag to 1).

The difference is subtle.  When the function
find_uniqsamp_vertices is run on an inflated
surface, the nearest-to-average vertex will be in
the middle of the almost flat patch of vertices
labeled by the data from one 3D voxel.

When run on a folded surface, nearest-to-average
vertex is not guaranteed to lie in the middle of
the one-voxel patch AFTER the surface has been
inflated.

The sample surface can be changed on the
"NormSamp (paint/label) and ClusterFilter
Controls" pop-up accessed by clicking the bold
"label:" label (parameter: wmgmext).  The current
surface is reloaded when the operation finishes.

Command line operation (cmdline program: paint)

The program, paint, will directly generate the
uniq sample vertex label if the following
option is appended to its command line:

  -uniqsampvtxs

The result is written to a label in the same
scandir as the other paint output files.

  ?h-UniqSampVtxs.label

Surface-Averaged Data

In the case of data generated by cross-subject
spherical averaging, there will usually be no 3D
datasets or register.dat in the cross-session
average scandir.

One way to generate 'representative' vertices at
a given voxel resolution for surface-averaged
data is to manually register 3D data from one of
the single subjects to target fsaverage, using a
3D timeseries, to generate a register.dat file.
Then read in a 3D stats file from the same
scandir.  To do this:

 1) File -> New Functional
 2) choose fsaverage as the matching subject
 3) SessionTools -> Setup Align/Funct Scans
 4) READ HEADER, use tkregister to align to fsaverage 3D
 5) copy 3D statBRIK and register.dat to average scandir
 6) follow instructions 1-4 at top

How to copy single subj scandir files to surfavg
scandir for step 5 (csh commandline example):

 set onesubj $FUNCTIONALS_DIR/150801/image/pol
 set surfavg $FUNCTIONALS_DIR/150901polavg/image/avg
 cd $surfavg
 cp $onesubj/register.dat .
 cp $onesubj/pol-vreg+orig.HEAD .
 cp $onesubj/pol-vreg+orig.BRIK .

The registration only has to be good enough to
make sure that the fsaverage surface will sample
voxels everywhere as opposed to space outside of
the functional data block (voxel contents are
ignored when calculating 'representative'
vertices).

There will be a harmless "stale vertex list"
error on starting tksurfer with SURFACE-STATS if
you are using a local surface average (not
fsaverage), which should be ignored.

-------------------------------------------
Alt functs (middle-click): also write label
  find_uniqsamp_vertices
  select_uniqsamp_vertices
  write_uniqsamp_vertices
-------------------------------------------

Like a default left click, except that the
selected vertices are also written to a .label
file in the current scandir.  The name of the
label file is first reset to:

  ?h-UniqSampVtxs.label

The function, write_uniqsamp_vertices, always
reloads the orig/sample surface coordinates, even
if "c2lab" ($usecurrcoordsflag) has been ticked
(which WILL STILL affect the operation of
find_uniqsamp_vertices).  Asks overwrite.
