###################################################################
UPDATE:  02 Oct 2022
###################################################################

----------------------------------------------
New function: write_adjphase_vertices
----------------------------------------------

Prompted by a request from Sam Schwarzkopf, I
added a new function to tksurfer available by a
shift-right-click on the "label:" line "W" button
(or more conveniently from the R-click pop-up
button menu):

  write_adjphase_vertices

During normal operation, the complex-valued phase
in Fourier analyzed data is processed on the fly
to generate an interactively tweakable color map.
But the underlying phase data - which contains
offsets due to hemodynamic delays as well as the
starting stimulus position, as well as phase
reversals for opposite hemispheres - is never
modified by csurf.

This function provides a way to generate a
complex-valued label with estimated polar angle
that removes those offsets and reversals.

It requires that the original complex-valued
Fourier analyzed polar angle data has been loaded,
and that $angle_cycles is set to a non-integral
value (like 1.0001, to trigger a polar angle color
scale).  This function takes account of the
settings of $angle_cycles, $angle_offset,
$revphaseflag, and $invphaseflag to write out an
adjusted phase.

To obtain a label file containing polar angles
approximately between -pi/2 and pi/2 (positive for
the upper field, and negative for the lower field,
same for either hemisphere) given a standard
64-sec cycle mapper stimulus starting at zero
degrees (right horizontal meridian) and
progressing in a counterclockwise direction,
adjust those parameters for each hemisphere
approximately as follows, before calling
write_adjphase_vertices:

  ### right hemisphere
  set angle_cycles 1.001
  set angle_offset 0.96
  set revphaseflag 1

  ### left hemisphere
  set angle_cycles 1.001
  set angle_offset 0.46
  set revphaseflag 0

The phases are written out as a 6-arg, ASCII
label file containing amplitude 1 complex
numbers.

Increasing $angle_cycles will linearly expand the
range of polar angles in the output file.  This
can be useful for data averaged across subjects,
where there will be a reduced range of polar
angles due to slight intersubject spatial
offsets, especially in the case of small visual
areas.  This causes a 'regression to the
horizontal meridian' in cross-subject average
data (too much blue).

To interactively check what the output will be,
click a vertex and check the value of "adja" in
the csurf log (final value on the first log line
output from a click on a vertex).  Ignore the
displayed colors (which will be reversed from the
'standard' polar angle scale, which is
lower/horiz/upper -> green/blue/red).

If the resulting adjusted phase label file is
read back in, to verify that the polar angles in
it are correct, click a vertex and look at the
val/val2 phase angle on the third log line output
from a click on a vertex, *not* the value of
"adja", which will now, confusingly, be
re-adjusted.

To see the standard colors for the adjusted data,
set parameters as follows (N.B.: same for both
hemispheres, since always right hemifield):

  set angle_cycles 1.6
  set angle_offset 0.5
  set revphaseflag 1

----------------------------------------------
New update script: update-csurf
----------------------------------------------

A new script, update-csurf (sh), downloads the
latest csurf and automatically installs it in the
current directory (currently working for 64-bit
mac and linux).

If there is already a csurf installed in the
current directory, it is first moved aside/renamed
with its release date suffix (e.g., csurf-220912).
The newly installed csurf will be just 'csurf'.

N.B.: On Mac, if you download the csurf tarfile
using a browser and click it to unpack it, it will
be marked with the quarantine metadata flag.  You
can remove this from the command line with:

  sudo xattr -r -d com.apple.quarantine csurf

The update-csurf script uses curl (on Mac) to
download the tarfile and tar to unpack it, which
*won't* mark the result as quarantined.

----------------------------------------------
New update script: update-fsaverage
----------------------------------------------

The second new script, update-fsaverage (sh), can
be used after csurf has been installed.  It
updates the subject 'fsaverage' in the current
SUBJECTS_DIR with the new CsurfMaps1 parcellation
(annotation gii files) from Sereno, Sood, and
Huang (2022), along with the fixed surfaces and
flattenings used there.  These files are copied
from $CSURF_DIR/subjects/fsaverage-ADDITIONS.

The 'fsaverage' subject in SUBJECTS_DIR must be
writable (e.g., a copy of the 'fsaverage' in the
FreeSurfer distribution).

The files installed include:

(1) annotation/parcellation files

  lh-CsurfMaps1.annot
  lh-CsurfMaps1.label.gii
  rh-CsurfMaps1.annot
  rh-CsurfMaps1.label.gii

(2) updated fsaverage inflated_avg surfaces

  The artifactual large triangles at the 'poles'
  of the inflated_avg surface in the standard
  FreeSurfer distribution are fixed and the
  original files moved aside.

(3) more verdical average .area files

  These are made from inflated_avg, the average of
  inflated surfaces instead of the average of
  smoothwm/white.  Surface-averaging folded
  surfaces (e.g., smoothwm) removes idiosyncratic
  sulcal 'crinkles', reducing overall average
  surface area in the sulci by almost one-third.
  The inflated_avg surface avoids this anisotropic
  shrinkage by first inflating, then averaging.
  Original .area files are first moved aside with
  an ORIG suffix for easy revert.

(4) True-area flattenings made from fixed inflate_avg

  The flattenings in the standard FreeSurfer
  distribution are made from the 'inflated'
  surface, which has been made by inflating the
  anisotropically shrunken average 'smoothwm'
  surface.  New un-shrunken flattenings were made
  from the inflated_avg surfaces:

    {lh,rh}.cortex2.patch.3d
    {lh,rh}.cortex2.patch.flat
    {lh,rh}.cortex2a.patch.flat

  The relaxation cuts are not extremely deep, so
  the surface can't relax to its full original
  surface area.  The curr surface area of the two
  flattenings are 73% of the surface area of the
  original cut 3d inflated_avg surface.

  To correct for this in a final image (e.g., to
  show inflated and flattened at same scale),
  scale up the flat bitmaps 1.17x (relative to the
  1 cm scale bar on the image):

    1.17 = sqrt(1/0.73)

  Or, alternatively, you can just shrink the scale
  bar by:

    0.854 = sqrt(0.73/1)

  The square root is because scale factors are 1D
  linear, not area.

(5) Figure images

  This are accessible from csurf -> SubjectTools
  -> View Saved Subj Bitmaps (saved as tiffs in
  $SUBJECTS_DIR/fsaverage/rgb).


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

fixed swapped fthresh/sfthresh mask in mask in compute_surfgrad (grad arrows)

fixed IRIX and PPC compiles :-}

csurf title bar shows tarfile date on startup or Help -> Csurf

better kill for multiple instances of Tools -> View Saved Bitmaps


##########################################################################
UPDATE: 02 Oct 2022
##########################################################################

--fsaverage-ADDITIONS: update README.txt's, add update-csurf/fsaverage
--mk0: insttmp asks OK rm /tmp/csurf, /tmp/Csurf.app
--lib/help/tksurfer/label,label_{readcut,clear,read2val,write}: update
--csurf: print README.txt tarfile date (if there!) into csurf title bar
--bin/noarch/update-csurf: new sh script, added to mk0
--bin/noarch/update-fsaverage: new sh script, added to mk0, fsaverage-ADDITIONS
--tksurfer.c: add strcpyrmhemi() to avoid strcpy restrict violations (4 places)
--tksurfer.c: read_mgh_annot now runs set_annot_alpha(255) (also obj,poi,gii)
--tksurfer.c: restrict: (1) if obj mod thru ptr (2) r/w only allowed by that ptr
--tksurfer.c: no strcpy to origvar: restrict'd arg: 2 ptrs can't access 1 thing
--tksurfer.c: 10.6-compiled is fine, restrict crash appeared w/10.15 compile
--tksurfer.c: alfname/$annot def: CsurfMaps1, read_mgh_annot autoresets alphs
--fourier.c: strsep -> strtok for IRIX
--{tksurfer,tkmedit}.tcl: recognize IRIX64 so libTix8.4.3.so loads on sgi
--tk{surfer,medit,register}.c: incl zsh explanation in warning unset env var 
--tkregister.c: IRIX: re-add CWBorderPixel, rgbabuftoscreen ifdef glDrawPixels
--tkmedit.c: IRIX: add CWBorderPixel attr, drawslice{2} IRIX ifdef glDrawPixels
--tksurfer.c: fix IRIX: rm #if 0'd singlequotes, re-add CWBorderPixel attr
--csurf: recognize IRIX64 so libTix8.4.3.so loads on sgi
--mk0: fix IRIX libezxml compile, tgz's, add rmcm, rm now stale mk0.csh
--tksurfer.c: write src annot/gii file comment in subj/sess scripts/<name>.ctab
--tksurfer.c: printvtxdata dumps adjusted colorscale angle (adja), baks only !0
--lib/help/tksurfer/label_{read,write}: update
--tksurfer.c: linrampphase2vtxcol: min redraw not working yet, commented out
--tksurfer.c: linrampphase2vtxcol comment out redraw to avoid redo set_color
--tksurfer.tcl: checklabelfile: warn read cmplx label as if real and vice versa
--tksurfer.tcl: 11th overload Shift-R-clk-"W" "label:": write_adjphase_vertices
--tksurfer.c: write_adjphase_vertices(): adjusted non-integer angle_cycles phase
--tksurfer.tcl: RESTORE rot subj w/"cereb" in name to posterior (vs. side) view
--csurf: rotate any subj with "cereb" in name to posterior (vs. side) view
--csurf: fix SubjectTools -> Inflate Surface Patch (was calling mkfinalsurfaces)
--csurf: repeat Help ExpertPref: RmSkull,FilterWM,FillWM,InflateP,Flatten,Sphere
--help/csurf/fillhires: update w/fill arbitrary volume example
--csurf: getcmdpidnam: add'l cmdpid's for better kill w/multiple bitmaps wins
--tkmedit.c: in all3views, click in subfield changes plane (duh!) for arr butt
--dist/fsaverage-ADDITIONS: updated rgb/mpg
--tksurfer.c -- fixed swapped fthresh/sfthresh mask in compute_surfgrad

##########################################################################
UPDATE: 24 Mar 2022
##########################################################################

--csurf: list other brik2cor options on setup struct panel
--csurf: setup structs: 3-way opt (cancel, use, don't use) if no -zeropixwidth
--csurf: double-clk setupscans upper-left "Session:" label for current location
--csurf: block check scandir callback from set iscandir if aspect equals struct
--csurf: double-clk setupscan panel raises csurf only from bottom buttons frame
--csurf: Setup Structural Scans auto-converts *.nii (AFNI 3dcopy)
--lib/help/tksurfer/read_im{2,3}: example set infile names
--lib/help/tksurfer/col1col2: new helpfile, add to mk0{.csh}
--tksurfer.tcl: helpwins for F3 panel col1,col2 for "bi" scale
--lib/help/tksurfer/val2rgb_{read,write}: explicit example set in/out filename
--wrappers.tcl: controls,buttonbar: mv panel right of tk b/c far left tkmedit
--wrappers.tcl: controls,buttonbar: mv panel below GL if F3 b/c tksurfer F3 top
--lib/help/tksurfer/outsurf{NULL,asc,glb,obj,off,stl,vtk}_write: update
--wrappers.tcl: helpwin: mv less right for narrow tksurfer F3, small tkmedit GL
--csurf: all-help panel: separate read/write (SurfaceR,SurfaceW), c2lab to Label
--tksurfer.tcl,mk0: rename helpfile: hemisurf->insurf_read, bind F3 insurf "R"
--tkmedit.c: nudge startup GLX glxwinx0 back to right (for left Mac dock)
--tkmedit.tcl: SAVEIMGS ignores post-startup $inoutim change (write 1st read-in)
--lib/help/tksurfer/{patch,curv,area}_{read,write,mask,cut}: explicit set file
...