###################################################################
LATEST EMAIL UPDATE: 30 Dec 2015
###################################################################

-----------------------------------------------
Keyword search in Help, all-help-in-one
-----------------------------------------------

A Cmd-f (linux: Alt-f) in any Help popup does a
search for a keyword in that panel (starts at top,
wraps).  Handy for longer panels.  Use "NEXT" or
<Return> or Cmd-g (linux: Alt-g) to find next
occurrence.

A middle-click on lower right "h" in csurf (or
Cmd-capital-H, linux: alt-capital-H) in the csurf
interface -- brings up all 24,000 lines of help
for csurf, tksurfer, tkmedit, and tkregister in a
single keyword-searchable panel.

-----------------------------------------------
Pop-up for live-record Tcl Commands
-----------------------------------------------

When "tcl:" is clicked in tksurfer or tkmedit in
order to record tcl commands for the purpose of
automating a series of interface actions, each
generated tcl command now appears in a pop-up
xterm (in addition to being written in a scripts
dir log file).

-----------------------------------------------
Single vertex removal/restore from labels
-----------------------------------------------

The edges of labels can be ragged after an AREA or
LINE cut.  The new PTS button (next to LINE)
allows quickly touching up the edges of a label by
removing or adding to each of the single vertices
in the currently selected list.

For example, to trim ragged edge of label:

  1) recut label with "C" on "label:" line
  2) select one or more edge vertices to trim
  3) left-click PTS

Or, to fill in gaps in the edge of a label:

  1) recut label with "C" on "label:" line
  2) select one or more edge vertices to extend
  3) middle-click PTS (like tkmedit edit-to-white)

-----------------------------------------------
Save/Restore Views
-----------------------------------------------

The new Views "Save" and "Goto" buttons (in the
TRANSLATE panel) allow quickly saving and
restoring an arbitrary surface view/pose
(rotations/translations/scale).  If another csurf
is started with the same subject, "Goto" can
be used to match the pose of the first.

-----------------------------------------------
Surface-based cluster exclusion on VTK files
-----------------------------------------------

The command line program, surfclust, does surface
based cluster-size-exclusion for correction for
multiple comparison (in csurf, usu. run by the
PAINT button at the single subject level, or
by the SAMP2SUBJ button at the cross-subject
level).  The surfclust command line usage
is appended below.

Surfclust, now accepts ASCII .vtk files directly
as input.  These must contain a surface followed
by 1 or more columns of stats per vertex (pick one
column to operate on with -vtxvalcol).  The output
is another ASCII .vtk file that contains the same
surface, and a single column of
surface-cluster-filtered stats.

When given an .mgh input file, surfclust now
writes an .mgh output file (was: only write
freesurfer *.w wfile output given .mgh input).

The program, randsurfclust, now also works with a
.vtk surface as input.  This program determines
minimum cluster exclusion size (for surfclust)
given hard stat thresh, desired corrected p-value,
and smoothing steps (using Monte Carlo sim).

The program, multiclust, now also accepts and
writes .vtk/.mgh files.  This program generates
non-overlapping, numbered clusters given a paired
list of ascending thresholds and cluster sizes.

See:
  Hagler, D.J. Jr., A.P. Saygin, M.I. Sereno (2006)
  Smoothing and cluster thresholding for cortical
  surface-based group analysis of fMRI data.
  Neuroimage 33:1093-1103:
  http://www.cogsci.ucsd.edu/~sereno/papers/SurfCluster06v.pdf

-----------------------------------------------
Write vtk surf/value/surf+value files from tksurfer
-----------------------------------------------

The "W" button on the "val:" line, which by default
writes a freesurfer wfile, can now also write *.mgh
or *.vtk value files from currently displayed vertexwise
data.  It can also write an all-in-one *.vtk file that
contains the current surface plus one column of
vertexwise values.  See the R-click help for the
"val:" line "W" button.

The new "VTK" button on the larger F3 panel can
write out a *.vtk version of the current surface.
Note that for now, this (and the all-in-one option
above) simply writes out the surface in freesurfer
native coordinates with no transformation, so the
surface may not display as a lateral view in a vtk
viewing program.

-----------------------------------------------
Bug fixes, small changes
-----------------------------------------------

Fixed recently-introduced bug that prevented
reading non-default parameters in movie tcl
scripts.

Tcl logging for pose changes and tkmedit GL window
clicks improved.

A Shift-down in another window when starting with
focus in the surface window no longer incorrectly
engages direct manipulate.

Can now select text from confirm popups (e.g.,
long file paths, measurements).

##########################################################################
### UPDATE: 30 Dec 2015
--multiclust.cpp: marty: allow .mgh/.vtk input/output (parallel to surfclust)
--multiclust.cpp: extern global recurscnt/maxusedrecurscnt (decl:surflib.h)
--multiclust.cpp: (from surfclust) incr stacksize deep recursive growCluster
--randsurfclust.cpp: allow vtk surf input
--randsurfclust.cpp: crashes w/recursive growCluster -> incr stacksize to max
--csurf: add View:Save/Goto and F3 VTK write surf to all-help
--tksurfer.tcl: .mgh/.vtk "val:" line "R" resets colscale real-valued if cmplx
--tksurfer.tcl: shift-ctrl-mid-clk val "W": write_vtk_surface_plus_values
--tksurfer.c: write_vtk_surface_plus_values, auto-append .vtk as previous
--tksurfer.c: write_vtk_surface, auto-append .vtk to outname if not there
--tksurfer.tcl: rm F3 FL (flatten) button til works again (makes space for PTS)
--tksurfer.tcl: F3 panel: W-ASCII=>ASC, VTK (write_vtk_surface), autoappend .vtk
--tksurfer.c: read_binary_values: accept *.vtk start w/header *or* POINT_DATA
--lib/help/tksurfer/{val,val_read,val_write}: updates, "W" overloads
--tksurfer.tcl: ctrl-middle-W: write vtk POINT_DATA valfile (force realonly)
--tksurfer.tcl: ctrl-left-W: write mgh valfile (force real-only)
--tksurfer.c: add write_vtk_values (begin POINT_DATA: allvertices,float,1frame)
--tksurfer.c: add write_mgh_values (allvertices,float,1frame)
--clustlib.cpp: warn half that (calcStats w/300K already over 15 min)
--clustlib.cpp: block >300K growCluster recursions (crashes above 750K)
--surfclust.c: extern global recurscnt/maxusedrecurscnt (declared: surflib.h)
--surflib.c: surflib.h: global recurscnt/MAXRECURSCNT to catch growCluster crash
--surfclust: still crashes w/recursive growCluster -> incr stacksize to max
--surflib.c: comment out redone MRIScomputeNormals,mrisComputeVertexDistances
--wrappers.tcl: new confirmalert $bgcol w/barely vis frame indicate selectable
--wrappers.tcl: okreplace indents filename
--tksurfer.tcl: GO (run tcl script) suppresses ret=0,1 in addition to ret=""
--surfclust.cpp: add help, examples, arg checking
--surfclust.cpp: .vtk: transcribe surf, append one col vals
--surfclust.cpp: .mgh: req .mgh input, writes only 1 frame regardless of inp
--surflib.c: MRISwriteVtkSurfaceAndValues: transcribe surf, append 1 col vals
--surflib.c: MRISwriteMghValues: one output frame regardless of input frames
--csurf: add View:Save/Goto to all-help
--lib/help/tksurfer/{save_pnt,goto_pnt,saveview}: document $subjtmpdir
--surflib.c: MRI_DIR -> CSURF_DIR
--surflib.c: regularize MRISreadValues{Mgh,Vtk}File to return ecode
--surflib.c: mv MRISreadValues{Mgh,Vtk}File from surflib.cpp to here
--surflib.c: add mrisReadVtkFile function
--surflib.c: add 2nd fork (mrisReadVtkFile) to MRISread/MRISreadOverAlloc
--surflib.h: add MATCH_{PREFIX,SUFFIX} macros, FIRST_IMG_BYTE, MAXVTKLINE
--surfclust.cpp: add -vtkvalcol, MRISreadValuesVtkFile
--tksurfer.c: make backup of surfer.mat before writing new, hardcoded->defines
--tksurfer.tcl: add Save/Goto View buttons inside TRANSLATE panel
--csurf: fixsurfaces trace for fsaverage: if inflated_avg there, use it
--csurf: previous forces error/explain on try to misconfig Funct or SphAvg Dir
--csurf: block/explain SURFACE/VOLUME-STATS if this notebook page not config'd
--nmovie.c: break to STOPPED if wastefully LOOPING w/1 image
--wrappers.tcl: confirmalert selectable textwidget ($usetext=0 to revert)
--lib/help/tksurfer/{save_pnt,goto_pnt}: improve orig coords explanations
--mk0{.csh}: include new helpfile
--lib/help/tksurfer/cutpts: new helpfile
--lib/help/tksurfer/{cutline,cutarea}: update to remove awk cut/uncut overloads
--tksurfer.tcl: mv awk LINE/AREA cut/restore points overloads to new PTS button
--tksurfer.c: Enter/LeaveNotify: ignore Shift down in otherwin w/start GL focus
--tksurfer.tcl: shift-mid-clk overload AREA/LINE w/cut_vertices (1+ marked)
--tksurfer.tcl: mid-clk overload AREA/LINE w/uncut_connected_vertices (1+ mark)
--tksurfer.c: new/export: uncut_connected_vertices (also export cut_vertex)
--tksurfer.c: cut_line: re-enable cut_vertex: open/closed line same (AREA/LINE)
--tkmedit.c: add/export left_click, use if tkmedit.log in do_one_glx_event
--tkmedit.tcl: log tkwin arrowkeys (arrow bindings)
--tkmedit.tcl: log GLwin arrowkeys (tcl changeslice call from do_one_glx_event)
--csurf: Re-Make Surf (hi-res): block use mri_fill
--tkmedit.tcl: fix log report for sag/hor trough, sag/hor-tal/native coords
--tkmedit.tcl: open xterm, run tail -f tkmedit.log in it upon record tclscript
--tksurfer.tcl: open xterm, run tail -f tksurfer.log in it on record tclscript
--wrappers.tcl: mk xcmd/cmdkey global here (rm in csurf/tk{surf,med,reg,strip})
--lib/help/tksurfer/cuts: mention auto-setup-output-names menu items
--csurf: mid-click on csurf "h" button brings up full help
--csurf: 3 selected text widget logs black on linux (-selectforeground black)
--wrappers.tcl: helpwin: selected text widget help black on linux
--csurf: viewonehelp: focus on helptext, position cursor beginning
--wrappers.tcl: helpwin: focus on helptext, position cursor beginning
--wrappers.tcl: helpwin: OK kills search panel like "x"
--wrappers.tcl: helpwin: fix alt-f,g to work on Linux
--csurf: viewonehelp: fix alt-f to work on Linux
--wrappers.tcl: helpwin: strip periods from helpfile name (b/c window path)
--wrappers.tcl: move replchar from csurf to here (now needed in helpwin)
--csurf: move replchar to wrappers.tcl (needed by helpwin there)
--lib/tcl/{flattenmovie,inflatemovie}.tcl: use parms (bug from changed controls)
--lib/tcl/{movie360,phasemovie,offsetmovie}.tcl:use parms (new ctrls),close@end
--csurf: check/block/warn "#" in recon-all pathname (subshell fails)
--csurf: file chooser height 400->500
--csurf: italicize (bold/unbold) main all help TOC headings
--csurf: rename ifont->ifontb, add ifont for allhelp
--wrappers.tcl: rename ifont->ifontb, add ifont
--csurf: add hemi,3dradios,surfradios,other3dvol to help TOC
--lib/help/csurf/csurf: help TOC, Cmd-f/NEXT,<Ret>,Cmd-g, search big help
--csurf: bind Alt/Cmd-H to all help in one window (CSURF_HELP.txt)
--csurf: finish R-click help (hemi, 3d radios, surf radios, other 3d vol)
--mk0{.csh}: add new helpfiles
--lib/help/csurf/{rc-hemi,rc-volradio,rc-vol,rc-surfradio}: new helpfiles
--csurf: use wrapper26nm.tcl onefindpanel for onehelp window in allhelp
--wrappers.tcl: add search to help panels (Cmd-f, NEXT==<Ret>==Cmd-g)
--lib/help/csurf/{csurf,rc-surface} mention make empty subject
--tksurfer.c: read_binary_values: VTK: check first line only, skip to POINT_DATA
--tksurfer.c: read_binary_surface: VTK: more feedback, more checking

### UPDATE: 21 Nov 2015
--lib/help/csurf/{csurf,rc-surfaces}: HOWTO make vtk surf appear in "surface:"
--csurf: surface combo includes $hemi.{orig,inflated}* at end, better sorting
--lib/help/tksurfer/val: doc new multi-column ASCII .vtk vertex data format
--lib/help/csurf/csurf: doc new ASCII .vtk surface format
--tksurfer.tcl: "val:" line "R" choose column num popup if .vtk filehdr ncols>1
--tksurfer.tcl: also load *.vtk files (sub+sess) to "val:" (ignore $hemi)
--tksurfer.c: read_binary_values: .vtk w/3lines: POINT_DATA,SCALARS,LOOKUP_TABLE
...

##########################################################################
# usage for surfclust program:
##########################################################################
sereno% surfclust

Usage: surfclust -instem instem -subj subjname [options]

  [zero clusters below requested size for cluster-size exclusion]

 Notes:

  .w/.mgh input => surf for area calc from SUBJECTS_DIR
  .vtk input => req's surf+vtxdata in 1 infile (smoothwm-like)
  .vtk input => -subj,-hemi,-surf ignored: infile has surf+data
  .mgh/.vtk output each require equivalent input
  .mgh/.vtk write 1frame/1col regardless of input frames/cols
  quit if >300K recursions during growCluster (fix: raise -thresh)

 Required:

  -instem <string>    wfile: omit hemi, extension: <instem>-rh.w
                         *or* full .mgh name: <lh.cope1.mgh>
                         *or* full .vtk name: <lh.surf+data.vtk>
  -subj <subjname>    subject name (can be ico, not-req'd/ignored if .vtk)

 Optional:

  -outstem <string>   wfile: omit hemi, extension: <outstem>-rh.w
                         *or* full .mgh name: <lh.cope1.mgh>
                         *or* full .vtk name: <lh.surf+data_filt.vtk>
  -indir <dir>        input dir (def . overidden by abs instem)
  -outdir <dir>       output dir (def . overidden by abs outstem)
  -mghvalframe <n>    .mgh infile frame (if omit, assumes 1st=0)
  -vtkvalcol <n>      .vtk infile col (if omit, assumes 1st=0)
  -hemi <rh,lh>       rh or lh (default=rh, ignored if .vtk)
  -thresh <F>         hard thresh before clustering (def=10^-10)
  -threshabs          use absolute val when thresholding (def=no)
  -minarea <mm^2>     minimum cluster size (def=1mm^2)
  -surf <surfext>     surf for area calc (def=smoothwm, ignored if .vtk)
  -summary            output detailed per-cluster stats (def=no)
  -talcoords          xform coords to talairach space (def=no)
  -nofixmni           no fix mnicoords: MattBrett's txfm (def=yes)
  -quiet              suppress messages

 Example (orig: read/write orig freesurfer valfile):

   cd <dir_containing_stat_valfile> \
   surfclust \
     -instem pol1-vreg+orig_f \
     -outstem pol1-vreg+orig_g \
     -hemi rh \
     -threshabs \
     -thresh 5.0 \
     -minarea 150 \
     -surf smoothwm

   infile:  ./pol1-vreg+orig_f-rh.w
   outfile: ./pol1-vreg+orig_g-rh.w

 Example (read/write 1D mghfile, outfile has 1 frame):

   surfclust \
     -instem /data/lh.cope1.mgh \
     -mghframe 0 \
     -outstem /data/lh.cope1-filtered.mgh \
     -hemi rh \
     -threshabs \
     -thresh 5.0 \
     -minarea 150 \
     -surf smoothwm

 Example (read/write surf+data ASCII vtkfile, outfile has 1 col):

   surfclust \
     -instem /data/lh.surf+data.vtk \
     -vtkvalcol 0 \
     -outstem /data/lh.surf+data_filtered.vtk \
     -threshabs \
     -thresh 5.0 \
     -minarea 150
                                               version: 01e





