###################################################################
UPDATE:  @@ Sep 2025
###################################################################

-------------------------------------------------------------------
Summary:
  (1) better percent resp popup for middle-click "W" on "val:" line 
  (2) distinguish val/stat smooth, ignore dispersion opt for complex smooth
  (3) gather SMOOTH/fillholes/searchlight functs into R-clk-SMOOTH buttonbar
  ...
-------------------------------------------------------------------


-------------------------------------------
(1) better percent resp popup for middle-click "W" on "val:" line
-------------------------------------------

There are three ways in csurf to obtain percent
response measures from Fourier transformed
timecourses:

(A) single vertex:
 load 3D _x,_y Fourier transform data BRIKs
 ctrl-middle-click vertex
   => look in csurf log

(B) avg percent resp over label
 find/make label
 load 3D _x,_y Fourier transform data BRIKs
 shift-left-click "T" on "label:" line
   => percent resp in log, on final popup

(C) vertexwise percent:
 load 3D rawata
 load 2D _x,_y Fourier transform data wfiles
 vertexwise percent displayed
   => makes wfile

Previously, method (C) required entering the
rawdata average (used where no rawdata was
available, e.g., cross subject, phase averaged
data).  Now it can also be calculated from the
rawdata itself if it is available.

------------
New R-click help for method (C) above:
------------

An alternative middle-click on the "W" button
brings up a popup that converts raw Fourier
transform data to vertexwise percent responses,
displays the results, and writes them to a wfile
(infix: _%).

To do this, we need the time series average
brightness.  This can either be calculated from
the raw time series BRIK if this is available, or
it can be entered directly, if it is not
available (e.g., phase average, or cross-subj
average).

(1) First, load the raw Fourier amplitude wfiles
to the surface.  Pick the _x (or _y) surface
wfile from the "val:" dropdown and click "R"
(picking either loads both).

(2) Second, if raw data is present, load it.
This can be done quickly by ctrl-mid-clicking the
surface (to display a single vertex timecourse,
which auto-loads the rawdata), or more verbosely
as follows:

  click "val:" label to change it to "val3d:"
  click "RD" to get read rawdata popup
  select rawdata timeseries BRIK in dropdown
  click READ RAWDATA & REGISTRATION on popup

[now back to the RAW FOURIER TO PERCENT popup]

(3) Third, find average rawata brightness.  If
rawdata has been loaded, click:

  COMPUTE AVG t-SERIES EACH VTX

on the popup.  Once this finishes, the
$avg_rawamp entry will be set to "vtxwise", and
the number of $time_points will be set.

If no rawdata is available, manually enter the
average rawdata brightness (voxels in brain - or
brains), and number of timepoints.

  avg_rawamp:  avg brain voxel timecourse brightness
  time_points:    TRs in timecourse (e.g., 512)

(4) Finally, compute percent response by
clicking:

  COMPUTE PERCENT RESP

on the FOURIER TO PERCENT RESPONSE popup.  The
.stat field at each vertex will now be filled
with response percent, which will then be swapped
to the viewable .val field, and then the color
scale adjusted to display real values.  Finally,
the .stat field result will be written to a wfile
with a "_%" infix.

To return to viewing the complex data, re-swap
stat and val, by left-clicking S/V.

Implementation details

The tcl/C function to calculate the vertexwise
raw data average is:

  compute_tseriesavg2stat

The tcl/C function to calculate percent resp is:

  compute_dftamp2pcnt2stat $avg_rawamp $time_points

In tksurfer.tcl, the proc writedftampctrls makes
the popup and the two popup buttons call the
following tcl proc's:

  do_computetseravgs
  do_writedftamp

which finally call the two C/tcl functs above.

N.B.: results are valid only if the
complex-valued raw Fourier transform of
timeseries at stim freq frequency has been read
onto surface (this data typically has _x,_y
infixes).

This *vertexwise* operation partly overlaps with
shift-left-click on the "T" button, which by
contrast, displays the average response percent
*across an entire label*.

The tcl/C functions run by do_writedftamp are:

  compute_dftamp2pcnt2stat $avg_rawamp $time_points
  swap_stat_val
  set complexvalflag 0
  setfile val ${stem}_%-${hemi}.w
  write_binary_values

Entering -1.0 for $avg_rawamp is a flag meaning
use average rawdata amplitude currently saved in
.stat field (vs. use the argument value, which
should be positive).

Here is the C-code for compute_dftamp2pcnt2stat:

  if (avgrawamp == -1.0) usestat = 1;
  for (k=0; k<vertexcnt; k++) {
    dftamp = hypot(vertex[k].val,vertex[k].val2);
    pcnt = dftamp;            /* assume _x,_y in val/val2 */
    pcnt /= (float)tcnt;      /* norm discrete FT */
    if (usestat)
      pcnt /= vertex[k].stat; /* resp frac (use .stat) */
    else
      pcnt /= avgrawamp;      /* resp frac (use func arg) */
    pcnt *= 2.0;              /* incl pos+neg freqs */
    pcnt *= 2.0;              /* report peak-to-peak */
    pcnt *= 100.0;            /* percent */
    vertex[k].stat = pcnt;    /* save to .stat */
  }

As always, to see exactly what's going on, click
the "tcl:" label to see tcl commands executed by
interface clicks.

N.B.: ctrl-middle-clicking a vertex to display
the timecourse can also display the percent
response once the 3D _x,_y BRIKs have been loaded
as follows:

  click "val:" label to change it to "val3d:"
  click "RD" to get read rawdata popup
  select _x (or _y) 3D BRIK in dropdown
  click "R" on "val3d:" line (auto-reads both)

When a vertex is clicked, the Fourier data is
re-sampled to the surface.  To see the exact same
percent responses as the functions here (which
use the _x,_y wfile that have already been
sampled to the surface), be sure the surface
smoothing of the _x,_y files (or lack of it) is
the same in both cases.


-------------------------------------------
(2) distinguish val/stat smooth, ignore dispersion opt for complex smooth
-------------------------------------------

The csurf View Functional Data panel (see line
starting with "Smooth: Surf(val,stat)") now
distinguishes the number of smoothsteps on the
data overlay (val,val2) vs. the statistical
mask (stat).  The line that starts with
"Smooth: Surf(val,stat)" now has two entries to
independently control smoothsteps on val(,val2)
and stat.

There is also an option (unmarked tickbox before
the first smoothsteps entry) to use an alternate
smoothing function when rendering complex-valued
data (C/tcl function: smooth_complexang_realamp)
that ignores phase dispersion by averaging
the complex angle but then averaging the real
amplitudes (instead of vector averaging the
complex vectors).  The default (unticked)
is to use vector averaging (C/tcl function:
smooth_val).

This function will reduce the data (val/val2)
amplitude less than smooth_val in regions with
rapidly changing phase.  By the same token,
it will reduce noise less (which tends to be
characterized by rapid spatial changes in phase).


-------------------------------------------
(3) gather SMOOTH/fillholes/searchlight functs into R-clk-SMOOTH buttonbar
-------------------------------------------

There are 12 different kinds of curv/val/label
smoothing and hole-filling operations (some prev
only on large F3 panel) that have now been
gathered into one convenient button bar available
from a R-click on the "SMOOTH" button.  These
are:

  Surface Smooth (cv)  - .curv (curv/sulc/area)
  Surface Smooth (val) - .val(.val2), and .stats if there
  Surface Smooth (s)   - .stat only
  Surface Smooth (w)   - .val(.val2), distance-weighted
  Surface Smooth (sp)  - .val(.val2), sparse: fixed-val interp
  Surface Smooth (vo)  - .val(.val2), but not .stats (valonly)
  Surface Smooth (cr)  - .val(.val2), complex ang w/real amp
  Surface Smooth (gr)  - .valbak(.val2bak) gradient arrows

  Fill Annot/Label Holes, 1-Neigh (smoothsteps = annotholes)
  Fill .val Field Holes, 1-Neigh Avg (smoothsteps = valholes)
  Fill Annot/Label Holes, Adj Neighs/Criterion (smoothsteps = annotholes-neigh)
  Erode Edges of Annot/Label (smoothsteps = annoterode)

In addition, there are two bottom buttons to
bring up popups to control searchlight-like
smoothing operations:

  Searchlight Operations Popup (avg,countIDs,variance,no-overlap,sum)
  Non-overlap Paintballs to .stat Popup (e.g., mk cerebellar patches!)


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

add compute_avg_edgewidth, mid-clk DIST reports avg inter-vtx dist

cleanup/regularize render panel labels

lower fsaverage data/stat smooth defaults

expose more gradient arrow outlier removal parameters

...


##########################################################################
UPDATE: @@ Sep 2025
##########################################################################

[IN PROGRESS]

    [tmprelease 250617]
--lib/help/tksurfer/nonbinaryfs,mk0,tksurfer.tcl -> helpfile name: gradfsarrows
--tksurfer.tcl: fstickctrls warn re-calc grad areaoutliermin,rmgradoutliersflag
--tksurfer.c: centerarrowsflag now also works for curved 3d surface arrows
--lib/help/tksurfer/{arrownorm,nonbinaryfs}: update
--tksurfer.tcl: warn (both popups) re-calc gradient if change rmgradoutliersflag
--tksurfer.tcl: FIELDSIGN and GRADIENT ARR: $rmgradoutliersflag
--tksurfer.tcl: FIELDSIGN and GRADIENT ARR: $sdoutlierfact, $areaoutliermin
--tksurfer.tcl: FIELDSIGN and GRADIENT ARR: $centerarrowsflag, $angoffrevarrflag
--tksurfer.tcl: FIELDSIGN popup: sdoutlierfact,areaoutliermin,rmgradoutliersflag
--tksurfer.tcl: ARROWS/NORMALS/POINTS popup: add $rmgradoutliersflag
--tksurfer.c:  add/export: double sdoutlierfact,areaoutliermin
--tksurfer.tcl: bind to warn filledarrowsflag w/3Dsurf (no space Lbracket,plus!)
    [tmprelease 250604]
--tksurfer.tcl: move up fstickctrls to unoverlap buttonbar if from R-click GR
--lib/help/tkmedit/*: regularize header lines in 109 helpfiles
--lib/help/tksurfer/*: regularize header lines in 280 helpfiles
--tksurfer.tcl: R-clk GR, clk unmarked fstick -> fieldsign/gradient arrows ctrls
--tksurfer.tcl: mid-clk DIST now reports edges (tksurfer.c genstrret_1k append)
--tksurfer.c: compute_avg_edgewidth appends edge count to genstrret_1k
--lib/help/tksurfer/dist: update, Euler, howto calc edges from vtxs,faces
--tksurfer.tcl: middle-click on DIST button does compute_avg_edgewidth
--tksurfer.c: add/export compute_avg_edgewidth, output to log and $genstrret_1k
--csurf: add missing SMOOTH types to help panel (valonly,stat,grad)
--lib/help/tksurfer/smooth_stat: new (update mk0, add R-clk to tksurfer.tcl))
--lib/help/tksurfer/smooth: update (add smooth_stat to SMOOTH buttonbar)
--tksurfer.tcl: add smooth_stat to SMOOTH R-click buttonbar (no vis radiobutton)
--lib/help/tksurfer/softtruncwidth: new, "soft" popup cp avoids new allhelp ent
--lib/help/tksurfer/{smooth,smooth_steps,smooth_weight}: smooth_stat, alt smooth
--tksurfer.c: add smooth_stat (vs. currently using swap stat val and smooth_val)
--lib/help/tksurfer/smooth_weight: update for popup
--tksurfer.tcl: mini popup on R-click "w" smoothing to control $halfweightdist
    [tmprelease 250529]
--lib/help/tksurfer/smooth: update
--tksurfer.tcl: check appropriate fields loaded for all SMOOTH/fillholes functs
--tksurfer.tcl: combine SMOOTH/smoothsteps buttonbars, expand -> all smoothtypes
--lib/help/tksurfer/restore: document restore_zero_position, make_lateral_view
--tksurfer.tcl: tick isocont makes popup (prev just R-click isocont label)
    [tmprelease 250519]
--lib/help/csurf/setuprender: fix $revphaseflag, $angleoffset, other flags
--tksurfer.tcl: "sft" -> "soft" (unoverlap sfthresh!)
--csurf: defsmooth down if fsaverage: ecc:20/20->3/2 (rend,stat), pol:10/10->2/1
--csurf: block auto change to fsaverage if started from scripts dir
--lib/help/csurf/setuprender: update: for new "labels"
--csurf: update/homogenize/improve View Functional Data panel dual-field labels
    [tmprelease 250516]
--lib/tcl/{eccen,polar,twocond}-{views,flat}.tcl: pass/use $smoothstepsstat
--lib/tcl/{eccen,polar,twocond}-{views,flat}.tcl: separate val/stat smooth parms
--lib/tcl/{eccen,polar,twocond}-{views,flat}.tcl: $smoothoverlaymaskflag ignored
--csurf: addrenderscan: rm "m" tickbox (smoothoverlaymaskflag now only 3D/tkmed)
--csurf: addrenderscan: add entry to distinguish data and stat smoothing
--csurf: surftestrender: pass $smoothstepsstat by env to scripts
--csurf: setdefaultparms: new: renderscanlists(def,smoothstepsstat) 5 ;#statonly
--lib/help/csurf/setuprender: update
--lib/help/tksurfer/{val_clear,smooth}: update
--tksurfer.tcl: add clear_stat button for "val:" line "CLR" buttonbar
--lib/tcl/{eccen,polar,twocond}-{views,flat}.tcl: can use $cpxangrealampflag
--csurf: addrender: cryptic "m" tick (smoothoverlaymaskflag) explain if changed
--csurf: addrender: bare tick to ignore dispersion w/smooth (cpxangrealampflag)
--csurf: surftestrender: pass $cpxangrealampflag by env to scripts
--csurf: setdefaultparms: renderscanlists(def,cpxangrealampflag) 0 ;#ignore disp
--lib/help/csurf/setuprender: add refs to 3 kinds of FT->percent at end
    [tmprelease 250513]
--lib/help/tksurfer/val_write: major update
--tksurfer.tcl: add COMPUTE AVG t-SERIES EACH VTX (do_computetseravgs) to popup
--tksurfer.tcl: rewrite RAW FOURIER TO PERCENT RESPONSE pop-up
--tksurfer.c: compute_dftamp2pcnt2stat div by avgrawamp in .stat if avgrawamp=-1
--tksurfer.c: compute_tseriesavg2stat from rawdata, export rawdata_{xyzt}dim
--lib/help/tksurfer/val_write: fix backwards "cat" command (!), FT amp doc
--csurf: empty tarfiledate -> "none" (local compile vs. mk0 insttmp tarfile)


##########################################################################
UPDATE: 06 Apr 2025
##########################################################################

--update-csurf: Mac add unquarantine note at end
--update README.txt: maybe unquarantine (w/tar! don't auto-do since req's pwd)
--FreeSurferEnv.{sh,csh}: mention getonearch in unrecognized architecture error
--getonearch: fix for mac uname -p now returning "arm" (was "arm64")
--csurf/tksurfer.tcl/tkmedit.tcl: appnap OFF apple silicon (kernvers=BigSur=20+)
--add cerebmap20-dentate.tgz to csurf/cereb/updates distro
--make cerebmap20 compat cerebmap20-dentate-nuc from cereb2c-export-dentate-nuc
--rescale surfaces in cereb2c-export-dentate-nuc: flipscale{flat}.tcl, NOTES
--csurf: versions to startup stdout, regularize title bar versions
--tkmedit.tcl: save imgs w/"w" warns/allows save to new name ims read over start
--tksurfer.tcl: add to RESTORE button command/buttonmenu: restore_zero_position
--lib/help/tksurfer/patch: document restore_zero_position, rotate_brain_x -90
--mv font/g++/tksurfer.c/Makefile to new dir: tksurfer-ftgl
    [tmprelease 250217]
--update-sdsu-sereno: re-download UCSD fsaverage-labels, fsaverage-ADDITIONS.tgz
--tksurfer.c: couldn't get vtx-spec working, curr state left in tksurfer-ftgl.c
--tksurfer.c: add freetype/ftgl, compile OK, single lower left display
--mk0: add luxisb.ttf to $CSURF_DIR/lib/fonts
--tksurfer.c: g++: rm "or", clamp rgb, fix !const char's, signed/unsigned cmp's
--tksurfer.c: g++: (void *)->(short ***),etc in contig multidim array mallocs
--bin/noarch/mkbothlut: automatically does below
--HCP-MMP1ColorLUT-both.txt: ??? 255 255 255->Unknown 0 0 0 0 (fix tkmedit olay)
--cd $CSURF_DIR/dist/fsaverage-ADDITIONS/scripts; sh zz-getREADME.sh
--update README.txt's on pages.ucsd.edu, download to fsaverage-ADDITIONS
--bin/noarch/update-fsaverage; add CsurfMaps1.{mgz,+orig.BRIK}, orig+orig.BRIK
--fsaverage-ADDITIONS/mri: add orig+orig.BRIK (+6M inst .tgz)
--lib/tcl/annot2roi.tcl: add savesingleROIbriksflag (def=0)
--tksurfer.c: savesingleROIbriksflag: if def=0, delete 7G of single-ROI BRIKs
    [tmprelease 250122]
--lib/help/tkmedit/{im2entry,im2read}: update
--lib/help/tksurfer/script_annot2roi: update
--fsaverage-ADDITIONS: add HCP-MMP1.mgz, HCP-MMP1+orig.{BRIK,HEAD} ($subj/mri)
--tkmedit.c: detect {HCP-MMP1,Csurf}ColorLUT-both.txt, rm seq_renum_lut (seq'd)
--tkmedit.tcl: detect {HCP-MMP1,Csurf}ColorLUT-both.txt, rm seq_renum_lut(seq'd)
--mk0: add mkbothlut: tclscript to mk hemi-specific lib/lut/*ColorLUT.txt files
--tksurfer.c: merge_idnum_briks makes unique idnums (lh,rh+maxrh)
--lib/help/tkmedit/im2{entry,read}: update
--update-sdsu-sereno: fix cerebellum updates bug
--lib/help/tksurfer/script_annot2roi: update
--tksurfer.{c,tcl}: rename fill_brik_holes -> fill_idnumbrik_holes
--update-fsaverage: add CsurfMaps 3D ROI files
    [tmprelease 250115]
--fsaverage-ADDITIONS: add CsurfMaps1.mgz, CsurfMaps1+orig.{BRIK,HEAD}
--tkmedit.c: timeout overlay double-mid-click popups
--tkmedit.tcl: im2 read mgz parcellation also calls seq_num_lut if match Csurf*
--tkmedit.c: read_val2rgblut uses seq_renum_lut if CsurfColorLUT.txt recog'd
--tkmedit.c: add/export seq_renum_lut for annot-derived sequential LUTs
--annot2roi.tcl: use neighfracthresh (def=0.8) vs. threshneigh
...