###################################################################
UPDATE:  @@ Apr 2026
###################################################################

-------------------------------------------------------------------
Summary:
  (1) find gradient reversals (curv, real-valued, phase)
  (2) howto export annot region IDs to label/wfile (copy_idnum_val)
-------------------------------------------------------------------


-------------------------------------------
(1) find gradient reversals (curv, real-valued, phase data)
-------------------------------------------

There is a new 13th "Find Gradient Reversals"
button on the R-click popup for the tksurfer "GR"
(gradient) button.  It runs the C/tcl function,
find_gradient_reversals.  This requires that a
gradient (of .curv, real-valued data in .val, or
complex-valued phase data from .val and .val2) has
first been calculated and displayed using one of
the first 12 buttons on the "GR" right-click
popup.

For each vertex, the absolute angular difference
(lesser of CW and CCW angles) between the gradient
vector at the vertex and the gradient vectors at
each neighboring vertex are measured.  For each
angular difference that exceeds $mindiffphase, the
.pval field for that vertex is incremented by 1/n,
where n is the number of neighbors.  The
permissive default value of $mindiffphase is 0.1
(36deg) (0.5=180deg), which can be increased to
reduce noise in the reversal detection.

The calculated vertexwise .pval's are saved as a
wfile in the current scandir (or in the subject's
scripts dir for curv gradient reversals) as:

  gradrevprob_k-$hemi.w

The gradient reversals can be displayed in
two ways.  By default, $pvalborddotflag is ON
(ticked), which displays reversal vertices as cyan
dots (color adjustable in the the popup), with a
.pval threshold controlled by $dthresh (default
0.3).  Turn this up to reduce the number of dots
displayed (i.e., require a higher pval).

If $pvalborddotflag is unticked, there will be a
popup offering to swap .pval into the .val field
and display it using colscale 11 (BRy).


-------------------------------------------
(2) copy_idnum_val: export annot region IDs to label/wfile
-------------------------------------------

A new C/tcl function, copy_idnum_val, was added to
the R-click "S/V" (swap stat val) button bar.
After reading in an MGH annotation file, this will
copy the integer region ID numbers to the .val
field at each vertex.  This allows writing out a
labelfile or valfile as a lightweight version of
an annotation.

The x,y,z coordinates in the labelfile can be
'original' (from $hemi.orig), or can be Talairach
(MNI 305 or MNI 152, as selected by |la|cu|
buttons at the upper left.

This was used to add 8 lightweight 'annotation'
files (labelfiles, valfiles):

 {rh,lh}-CsurfMaps1_MNI152.label
 {rh,lh}-CsurfMaps1_MNI305.label
 CsurfMaps1_newcurv-{rh,lh}.w
 CsurfMaps1_old3byte-{rh,lh}.w

to both the csurf download site and the fsaverage
and fsaverage-ADDITIONS tarfiles:

  https://pages.ucsd.edu/~msereno/csurf:
    fsaverage-labels/CsurfMaps1-parcellation/simple-annot/*
    fsaverage.tgz              # full, updated
    fsaverage-ADDITIONS.tgz    # just additions, updated


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

Better layout of fieldsign and find retin borders panel

tksurfer.c: add compute_laplacian (curv, real, complex phase)

tksurfer.c: write_label_hdr() includes Talairach 152 vs. 305, normd{frac}samp

...


##########################################################################
UPDATE: @@ Apr 2026
##########################################################################

    [tmprelease 260104]
--update-csurf: echo pwd/install dir!
--update-csurf: Mac warns run xattr (new tar), don't autodo b/c req's passwd
--csurf: Preferences->Update Csurf:setupupdatecsurf,updatecsurfcmd: update-csurf
    [tmprelease 260101]
--8 file/label lightweight 'annots' (8M) added to fsaverage/fsaverage-ADDITIONS
 {rh,lh}-CsurfMaps1_MNI152.label
 {rh,lh}-CsurfMaps1_MNI305.label
 CsurfMaps1_newcurv-{rh,lh}.w
 CsurfMaps1_old3byte-{rh,lh}.w
--tksurfer.c: write_label_hdr() includes Talairach 152 vs. 305, normd{frac}samp
--lib/help/tksurfer/val_{lab,write}: update
--tksurfer.tcl: mid-click "val;" makes allverticesflag,val2newcurfflag popup
--tksurfer.tcl: left-click "label:" auto-pops up label_label help
--lib/help/tksurfer/swapstatval: update
--tksurfer.tcl: add copy_idnum_val to S/V (swap stat val) button bar
--tksurfer.c: add/export copy_idnum_val (for writing annot-like wfile/label)
--lib/help/tksurfer/comp_grad: doc hidden compute_laplacian <0,1,2> funct
--tksurfer.c: scale_brain() updates tcl-exported glxzoomfact (not yet used)
--tksurfer.c: trunc pval dots w/fthresh (not fully general for all mod flags)
--tksurfer.tcl: rm 3 Calc Laplacian (includelaplacian=0),leave procs,tksurfer.c
--tksurfer.tcl add 3 Calc Laplacian buttons, comp_disp_laplace proc
--tksurfer.c: add/export compute_laplacian (curv,val,phase) -> valbak
--wrappers.tcl: allow "whitespace" (use proc null), added into GR gradient menu
--tksurfer.tcl: findgradrevctrls help: non-existent findgradrev -> comp_grad
    [tmprelease 251126]
--lib/help/tksurfer/{gradfsarrows,comp_grad}: updates
--tksurfer.tcl: add flipRHpolararrowsflag to FIELDSIGN and GRADIENT ARR
--tksurfer.tcl: do_gradrev: find_grad..,write pval wfile, borddots/val display
--tksurfer.c: add/export pvalborddotflag/dthresh to view .pval above thr as dots
--tksurfer.c: find_gradient_reversals: get same ang from 2D/3D grads dot prod
--lib/help/tksurfer/gradfsarrows: update stale hotkeys, regularize
--tksurfer.tcl: don't trunc lg early-area curv gradients (curv avg flatter/OK)
--tksurfer.c: find_gradient_reversals: replace w/new neighbors-only version
--tksurfer.c: add/export find_gradient_reversals (similar to find_retin_borders)
--tksurfer.tcl: findgradrevctrls popup to run find_gradient_reversals
--tksurfer.tcl: calc gradient reversals make-popup-button to GR button R-click
--lib/help/csurf/setupfield: respect reordered parms
--csurf: Setup Calculate Fieldsign, Borders: dividers, better var description
--lib/help/tksurfer/comp_grad: fix avggradvecbak{3d}flag->reggradvecbak{3d}flag


##########################################################################
UPDATE: 17 Sep 2025
##########################################################################
    [tmprelease 250917]
--lib/help/tksurfer/gradfsarrows: update
--tksurfer.c: bugfix: compute_{gradient,surfgrad} unset valbaks_cart2polarflag
--tksurfer.tcl: do_grad2col bugfixes: accept 3D surfgrad, blk reggrad, colscale
--lib/help/tksurfer/comp_grad: update
--tksurfer.c: add/export flipRHpolararrowsflag (def=1) for draw_arrows{2,3}d
--tksurfer.tcl: add 6 brainregion avg gradient buttons to GR gradient buttonbar
--tksurfer.tcl: add reggradvecbak{3d}flags to FIELDSIGN and GRADIENT ARROWS ppup
--tksurfer.c: draw_arrows{2d,3d}() can also just draw brainregion[i].avgvtx k's
--tksurfer.c: add/exp reggradvecbakflag,reggradvecbak3dflag,reggradvecloadedflag
--tksurfer.c: add/export compute_brainregion_avggrads
--mk0: insttmp finally puts tardate also into all-help
    [tmprelease 250829]
--lib/help/tkurfer/label_toggle: document dthreshfact, reason for it
--tksurfer.tcl: add $dthreshfact hack to LABEL CONTROLS popup
--lib/help/*/*: shorten lines for AllHelp (48 vs. 50 wide to reduce white space)
--lib/help/tksurfer: update 18 helpfiles: incl buttonbar buttontext for search!
--tksurfer.tcl: labelR_val: better error/help if trying to read .cols file
--tksurfer.tcl: listcmd_tcl: don't dup dropdown scripts csurf start from subjdir
--lib/tcl/zz-examples/assemble-render-maps.tcl: dthreshfact anti-labelflash hack
--tksurfer.c export dthreshfact->tcl: desperate hack fix flashy labels w/script
    [tmprelease 250810]
--csurf: add Expert Preferences->Views alt font, pass -fontfile to tksurfer
    [tmprelease 250810]
--csurf: add Expert Preferences->Views alt font, pass -fontfile to tksurfer
    [tmprelease 250808]
--mk0: 04f: combine separate but dependent freetype,ftgl compiles to "libftgl"
--tksurfer.c: add opt -fontfile for diff .ttf font put into $CSURF_DIR/lib/fonts
--tksurfer.c: 1 cm label same col as scalebar, tweak bar thick, font size/pos
--tksurfer.c: separate draw_areanames dthresh (depth) inflated vs. folded surf
    [tmprelease 250804]
--tksurfer.c: fix linux compiler cast warnings
--mk0: 04e: add freetype, ftgl for static tksurfer compile
--tksurfer.c: new fast draw_areanames: cmp testpnt depth w/glReadPixels readback
    [tmprelease 250802]
--tksurfer.c: draw_areanames: test neigh to 6th order to fix sloppy re-select
--tksurfer Makefile: LIB_PATH mv X11 after freetype/ftgl to get static freetype
--lib/help/tksurfer/{label_write: update
--tksurfer.tcl: "Write Region Centers" butt R-clk "W" on "label:" line buttbar
--tksurfer.c: draw_areanames: add brightness cue to reduce edge flashing
--tksurfer.c: draw_areanames: hacky/slow/working select_vertex occlusion test
--mk0: dist/insttmp: copy luxisb.ttf to $CSURF_DIR/lib/fonts
--tksurfer.c: add write_annot_region_centers (scriptsdir:AnnotRegionCenters.txt)
--lib/help/tksurfer/{label_toggle,meshr/g/b,label_read}: update
--tksurfer.c: fix scalebar label scaling/placement
--tksurfer.tcl: if vars exist, add $areanamesflag, annot-warn to LABEL CONTROLS
--tksurfer.c:   newvars: export: fontname,areanamesflag, intern: FTFont
--tksurfer.c:   newfunc: export:draw_areanames intern:initfont,drawstr_centonvec
--tksurfer.c:   #include FTGL/ftgl.h, #define FTGLFONT to included luxisb.ttf
--tksurfer.c: add ifdef'd __cplusplus FTGL font code below (req's g++) 3 above:
--tksurfer.c: add find_regionvtx_nearest_avg, always do (fast) in read_mgh_annot
--tksurfer.c: add vec2glxwinpix so to use glBitmap (vs. glRasterPos) for FTGL
--tksurfer Makefile: logic so just changing CMPL to g++ fixes libs/includes
...