#### sample 3D data to surface ####
-------------------------------------------
funct (left-click): paint
  paint_surface <fstatflag=0,1>
-------------------------------------------
funct (middle-click): also smooth
  paint_surface <fstatflag=0,1>
  smooth_{val,val_sparse} <steps>
-------------------------------------------


Detailed Description of "PAINT" Button Actions

-------------------------------------------
funct (left-click):
  paint_surface <fstatflag=0,1>
-------------------------------------------

A default left-click on the "PAINT" button on the
"val3d:" entry line samples the 3D volume stat
files previously read into internal buffers onto
the surface using the same code as paint.c (which
is what is called by the PAINT buttons in csurf
panels).  No effect if 3D buffers unloaded.

Sampling surface

PAINT always reloads the current "original"
surface (e.g., "white" or "orig" extension)
before sampling the 3D data.  The sample surface
can be changed on the "NormSamp (PAINT)" pop-up
(see below).  The current surface (e.g., inflated
or a flat patch) is reloaded after sampling.

The parameters that control the sampling
operation are set by tksurfer options:

  -wmgmext <orig,white>			surf to use for sampling
  -normdfracflag <0,1>			0=mm,1=frac along norm
  -normdsampsearchflag <0,1>			samp between limits
  -normdsampuniqvoxflag <0,1>		samp uniqvox
  -normdsampallflag <0,1>			samp every normddstep
  -normdfracsamp <float>			samp pnt or min frac wht->pial
  -normdfracmax <float>			max frac wht->pial
  -normdsamp <float>			samp pnt (or min) mm over wht
  -normdmax <float>			max mm above wht
  -normddstep <float>			searchstep mm/frac
  -normdop <0=max,1=avg,2=min>
  -samevtxthickflag <0,1>			dist to samenum vtx as "thick"

The initial values are loaded from current
settings in csurf for the current scandir.  The
PAINT button blocks some inconsistent settings
(e.g., norm search with non-zero range, min
larger than max).

These parameters can be modified directly from
tksurfer using a pop-up that is accessed by
left-clicking the bold "label:" (these are the
same parameters used for sampling raw timecourses
and stats using a label).

Finally, these parameters can also be controlled
as tcl variables in scripts like this:

  set normdfracmax 0.8
  [set others]
  paint_surface 0

The paint_surface argument, fstatflag, controls
whether the amplitude of a complex-valued stat is
squared and placed in the .stat field to use as a
statistical mask (shortcut to load vertexwise
.stat field when reading complex-valued data that
has amplitude replaced by sqrt(F)).  This is
automatically set to 1 w/complex data.

This can be passed through a cluster exclusion
filter (see help for the "CS" button on normal
surface-based "val:" line).

The paint_surface function forcibly zeros range
by setting max to min if norm search if off.

The "PAINT" button automatically tries to paint
the partner of a file if it has a complex-valued
infix:

  _r,_i		complex-valued significance files
  _x,_y		complex-valued raw Fourier amplitude

The wrapper tcl function for "PAINT" button is:

  paint_real_or_complex

-------------------------------------------
Alt funct (middle-click): also smooth
  paint_surface <fstatflag=0,1>
  smooth_{val,val_sparse} <steps>
-------------------------------------------

Like a default left click, except that the data
is surface-smoothed before redraw, using current
interface settings of smoothtype (e.g., val or
sparse) and steps (e.g., 10 -> ~3mm FWHM).

The wrapper tcl function accepts an option flag
to also smooth:

  paint_real_or_complex 1
