#### read 3D volume vecs for surface display ####
-------------------------------------------
funct,var (left-click): read 3Dvecs, sample to surf
  read_vecs2surf 9 5
  set dipolesflag 1
-------------------------------------------

A default left-click on the "V" button on the
"val3d:" entry line makes a popup to control
sampling vectors from a volume data for display
on a surface.

This requires first having read a rawdata
float-valued BRIK volume containing at least 3
volumes representing the x,y,z coordinates of the
vector and optionally a 4th volume for a scale
factor at each voxel.  It also requires having
read a corresponding register.dat.

The BRIK may contain more than 4 volumes (can
choose subbrik for x vector and scale factor).

To do those two, first use the "RD" button on the
"val3d:" line.

An example input volume set is output of 3dDWItoDT:
-------------------------------------------
### Calculate diffusion tensor from HARDI dataset (AFNI)
### BRIK: req's 1 init b0, strip extra b0's w/selector
### gradvec.1D line: Gxi, Gyi, Gzi => N.B.: omit *all* b0's
3dDWItoDT -automask -eigs gradvecs.1D \
  'scan02+orig[0..16,18..33,35..50,52..67]'
### outbrik (def=DT+orig, 0-base sel, 6-19 like 3dDTeig 0-13):
#  0-5 -> tensor
#  6-8 -> lambda_1,lambda_2,lambda_3,
#  9-11 -> eigvec_1[1-3]
#  12-14 -> eigvec_2[1-3]
#  15-17 -> eigvec_3[1-3]
#  18 -> FA
#  19 -> MD
-------------------------------------------

Enter the desired AFNI subbrik number for the
x-component of the vector (xvect_subbrik) and the
optional length scale volume (scale_subbrik).
These indices are zero-based (i.e., the first
BRIK in bucket is 0).

Next set the sampling surface and the cortical
depth of the sample.  The default is to sample at
the position of each surface vertex.  To sample
above (or below) that point along the local
surface normal, tick $normdsampsearchflag.  Pick
the units for the sampling distance (mm if
$normdfracflag unticked, or fraction of cortical
thickness if $normdfracflag ticked).  Finally,
set the sampling point (if mm, use $normdsamp_pnt
if fraction of local cortical thickness, use
$normdfracsamp_pnt).

The volume data for each x,y,z coodinate of the
vector set is processed as follows:

 (1) read coord into float volume buffer
 (2) sample to surf (.val) using curr register.dat
       and current vertex normal sampling policy
 (3) copy result into corresponding .dip{x,y,z} field
 (4) optional scale by 4th vol data set (e.g., eigenvalue)
 (5) display vectors as magenta ball-and-sticks

Here is how to perform all the subactions done by
the C/tcl function read_vecs2surf, assuming we
sample the diffusion vector volume at a point
halfway between the gray/white and pial surfaces:

if {$rawdataloaded && $registerdatloaded} {
  ### rawdata -> vector (dipole) display
  set xvectbrik 9
  set scalebrik 5
  set normdsampsearchflag 1
  set normdfracflag 1
  set normdfracsamp 0.5
  set normdfracmax 0.5
  swap_val_valbak    ;# save curr overlay
  for {set i 0} {$i < 3} {incr i} {
    rawdatasubbrik_to_paintable [expr $xvectbrik + $i]
    paint_surface 0
    push_val_dip $i   ;# 0=dipx,1=dipy,2=dipz
  }
  set dipolesloaded 1
  calc_dipavglen      ;# saved in $dipavglen
  ### optional scale by 4th volume data set
  if {$scalebrik >= 0} {
    rawdatasubbrik_to_paintable $scalebrik
    paint_surface 0
    swap_stat_val
    scale_dipxyz_by_stat
  }
  rotate_dti
  swap_val_valbak  ;# restore curr ovelay
  set dipolesflag 1
  redrawbutton
}

This is exactly equivalent to calling the
combined function directly:

if {$rawdataloaded && $registerdatloaded} {
  ### rawdata -> vector (dipole) display
  set xvectbrik 9
  set scalebrik 5
  set normdsampsearchflag 1
  set normdfracflag 1
  set normdfracsamp 0.5
  set normdfracmax 0.5
  read_vecs2surf $xvectbrik $scalebrik  ;# all-in-one
  set dipolesflag 1
  redrawbutton
}

