###################################################################
LATEST EMAIL UPDATE: 10 Apr 2015
###################################################################

The new things are, find geodesic paths, display
gradients of various kinds, and bugfixes.  Full details
in UPDATES.txt.

Geodesic Paths/Labels

A new button ("Dijk" just to the right of "DIST" in the
TRANSLATE panel) calculates an approximate geodesic path
between the last two clicked points and displays it on the
current surface (folded, inflated, flat).  It does this by
tracing geodesics on smoothwm (not the current surface).
The path is found using a Dijkstra algorithm by the MGH
freesurfer binary, mris_pmake, by Rudolph Pienaar (this
requires you have installed FreeSurfer 5.3 and have defined
the FSURF_DIR environment variable).

The path follows the edges of triangular faces and is
therefore very slightly longer than a geodesic path.  When
finished (about 5 sec for any length path), the path is
displayed in yellow, using the label generated by
mris_pmake.

The path can be used to make quantitative linear
measurements on cortical areas.  The displayed path/label
can be used to define the edge of another label since FILL
and ROI respect displayed labels.  The label can also be
used to extract a straight line of data.

Per-vertex Calculation/Display of Gradients in Curv/Val/Phase

Gradient arrow fields can now be calculated and displayed
for several kinds of data.  There is a new "GR" button at
the end of the fieldsign ("fs:") line.  After loading a flat
patch, a default left click on "GR" calculates and displays
the gradient of curv (or sulc).  You will have to zoom in to
make out the per-vertex arrows.

The gradient vectors can be normalized with the new
unlabeled tick at the bottom of the phasecontour box (just
to the left of "fmid:").  The length of the vectors
(normalized or unnormalized) can be adjusted with the
unlabeled entry immediately to the right of that tick box.

A middle-click on the "GR" button instead calculates the
gradient of the current data (real) in the .val field.

Finally, a shift-middle-click calculates the gradient of the
complex phase (in this case, finite differences are
calculated with circular subtraction).

In general, the gradients are calculated and stored in the
bottom of the complex stack in valbak/val2bak, and
$gradvecbakflag is autoset to display them.

Displaying your own gradient/arrow/2d-directional data

 1) put x,y vectors into complex label (6 entries per line)
 2) read with "R" on "label:" line (goes to va/val2 fields)
 3) shift-middle-click "S/V" => swap to complex stack bottom
 4) load surface data over which arrows will be displayed
 5) shift-middle-click this checkbox to show arrows

Note that the arrows will rotate with the patch.
With patch rotation set to 0.0 in (Preferences -> Expert
Preferences -> Views), the positive x direction
will be *down* and the positive x direction will
be *left*.

Displaying Two Phase Gradients Simultaneously

The two gradients used to calculate visual (or
other) fieldsign can be displayed interactively
along with fieldsign using the "F" button.  The
procedure for visual fieldsign is:

 1) load/smooth 1st (e.g., polar) data set
 2) shift-middle-click "S/V" => swap it to stack bottom
 3) load/smooth 2nd (e.g., eccen) data set
 4) click "F" button
 
See the right click help for the "F" button for
details.

Displaying Phase as Vector Relative to Window Frame

To directly visualize the polar angle normally
only represented by color, a vector can be draw at
each vertex *relative to the display window* to
indicate the local polar angle.

Unlike the gradient vectors, these vectors are not
'stuck' to the flat surface and *don't* rotate (at
a particular vertex) when the surface is rotated.
They *do* rotate when revphaseflag or angle_offset
are adjusted.

To try out this experimental display, load a polar
angle data set from the right hemisphere and do a
shift-middle-click on the unmarked tick box just
to the left of "fs:" (see R-click help for the
tick box for details).

Small updates

New tcl function, print_selected_list, dumps the
current list of selected vertices to an ASCII file.

The area ratio button ("D" button on the "area:" line) now
by default shows *log* area ratio.

The automatic startup of TextEdit on Mac for editing tcl
scripts (incl. file doesn't exist yet) or NOTES files is
fixed on 10.9 and 10.10.  On Mac, TextEdit will be used as
an editor (best when X11 is not in fullscreen) as opposed to
Paleolithic xedit.

The read_fieldsign function can now autodetect and read
fieldsign and fieldsign mask in the form standard curvature
format files.

### 10 Apr 2015 (geodesics, gradients)
 1) calculate geodesic path on surface, show as label
 2) calculate/display gradients of curvature, val, or phase
 3) display two gradients (fieldsign calculation)


###################################################################

To install the new csurf:

cd <dir-where-csurf-currently-installed>
  mv csurf csurf-YYMMDD
  tar xvfz csurf0.8-{mac,linux}-YYMMDD.tgz

cheers,
marty


#########################################
Latest addition to $CSURF_DIR/UPDATES.txt
#########################################

---------------- 10Apr2015 FreeSurfer0.8/csurf0.8 tarballs -------------------
--tksurfer.tcl: overload unlab'd arrownormflag check w/toggle angoffrevarrflag
--tksurfer.tcl: editfile: 'open -e', touch to mk new file, OK on OSX 10.10
--tksurfer.tcl: toggle arrownormflag resets arrowscale (ON=>0.5mm, OFF=>5)
--tksurfer.c: fix compute_gradient on phase (save gradients til loop done)
--tksurfer.c: correctly track compute_angles r,i=>th,r thru swaps,push,readnew
--lib/help/tksurfer/comp_fs: document confusing polar angle grad directions
--tksurfer.c: read_{fieldsign,fsmask} now autodetects, correctly reads curvfmt
--mk0{.csh}: new helpfiles: arrownorm,arrowscale
--lib/help/tksurfer/{arrownorm,arrowscale}: new helpfiles
--tksurfer.tcl: arrownormflag/arrowscale unlabeled chk/entry under phasecont
--tksurfer.c: adjust grad vec colors if fieldsign so both visible over it
--tksurfer.tcl: "F" button to run fieldsign, optionally display 2 gradients
--tksurfer.c: filter/zero gradient outliers to zero -> dark red arrowheads
--tksurfer.c: finally made *seriously confusing* angoffrevarrflag hack work!
--tksurfer.c: angoffrevarrflag: angle_offset/revphaseflag ctrl win-rel arrows
--tksurfer.tcl: tick gradvec{bak}flag only resets parms if other not ON
--tksurfer.c: arrownormflag: ignore amplitude, arrowscale sets length in mm
--tksurfer.tcl: overload nonbinaryfs tick w/toggle gradvecflag,gradvecbakflag
--tksurfer.tcl: "GR" button to run compute_gradient
--tksurfer.tcl: squish entry, "sl:" to nothing, to mk space for "F"/"GR" butts
--tksurfer.tcl: squish "sl:" to nothing to make space for "F" and "GR" buttons
--mk0{.csh}: new helpfiles: comp_fs,comp_grad
--lib/help/tksurfer/nonbinaryfs: update for toggle gradvec{bak}flags overload
--lib/help/tksurfer/{comp_fs,comp_grad}: new helpfiles
--tksurfer.c: fsdata2gradsflag: compute_fieldsign converts data to gradients
--tksurfer.c: compute_gradient: arg=2=phase (circsubtract) -> valbak,val2bak
--tksurfer.c: draw_cursor norm/big: don't draw select edges to ripped vertices
--tksurfer.c: add adjustable gradient arrowheads, add/export arrowscale
--tksurfer.c: block compute_{fieldsign,gradient} on non-flat surface
--tksurfer.c: add/export compute_gradient(0=curv,1=val) -> valbak,val2bak
--mk0{.csh}: add new helpfile: djik
--lib/help/tksurfer/dijk: new helpfile
--tksurfer.tcl: Dijk: warn/use $hemi.curv if $hemi.smoothwm.H.curv not found
--tksurfer.tcl: "Dijk" butt measure/disp ~geodesic path between last 2 selected
--tksurfer.c: add/export print_selected_list(): scripts/CurrVtxList.txt else log
--tksurfer.tcl: select_curv rec $hemi.area.logarat, fix R/G colscale resets
--bin/noarch/mri2mpgs: fix AFNI bg, recursive subdirs problem
--lib/help/csurf/tksurfer: doc "area:" line "D" button, "label:" line "X" butt
--lib/help/tksurfer/area_disp: explain new function and revised "D" bindings
--tksurfer.tcl: rebind area "D": left=>logarat,mid=>arat,shift-mid=>pial/white
--tksurfer.tcl: calcdisp_curr2orig_logarat: use compute_logarea
--tksurfer.c: add/export compute_logarea()
--lib/help/tksurfer/label_corr: clarifications
---------------- 22Mar2015 FreeSurfer0.8/csurf0.8 tarballs -------------------
--tksurfer.tcl: rm corr parms from label popup, add setup prepopup to "X" butt
--tksurfer.tcl: confirm 3 kinds of swap with a diagram of stack
--tksurfer.tcl: swap/show corr, reset col when done w/corr_over_label/annotcol
--tksurfer.c: do GLX window events during corr_over_label, find_retin_borders
--tksurfer.tcl: overload "X" button: middle-click does corr_over_annotcol
--tksurfer.c: corr_over_annotcol (wrapper, like annotcol stats/timecourses)
--csurf: Preferences -> Bigger Logs: 18 lines each vs. 7 lines each
...