###################################################################
UPDATE:  25 Sep 2023
###################################################################

----------------------------------------------
tksurfer displays/prints region areas from labels/annotations
----------------------------------------------

When a surface is read, two distinct measurements
of vertexwise area are loaded into the surface
data structure (the vertexwise area is the sum of
1/3 of the area of each of the 3-10 triangles
surrounding each vertex).

The first measurement, "orig area", is read from
the {rh/lh}.area files, which are typically
generated during standard surface reconstruction
from the {rh/lh}.white surfaces.  The second areal
measurement ("curr area") is calculated from the
current surface (e.g., inflated), which will
typically differ moderately from the "white"
surface.  Flattenings will typically have larger
deviations from "original area" because they are
inherently more distorted.

This information is now made more accessible when
reading single-area *.label file and annotations
(*.annot, *.gifti, etc.), as follows:

(1) When a single-area label is read, the "orig
area" and the "curr area" of the label is printed
on the pop-up displayed after displaying the
label.

(2) When an annotation is read, the area of each
region is now printed to the csurf log, and also
written to a file in the scripts directory in
either the SUBJECTS_DIR or FUNCTIONALS_DIR
(depending on whether you started tksurfer from
the SURFACE button or the SURFACE-STATS button):

  $SUBJECTS_DIR/$subject/scripts/<prefix>.ctab.area
  $FUNCTIONALS_DIR/$session/image/scripts/<prefix>.ctab.area

(3) The pop-up generated by a double-middle click
on a region in a displayed annotation now also
includes the "orig area".

N.B.: if you have installed the fixed surfaces
and area files in fsaverage-ADDITIONS.tgz (or
have used update-fsverage, or have installed the
fixed fsaverage.tgz -- all equivalent effect,
doing any one of those highly recommended!), the
"original area" will have been calculated from
fsaverage $hemi.inflated_avg surfaces rather than
from the fsaverage $hemi.white surfaces.

This is because when the surface coordinates of
individual surfaces are surface-averaged to
generate the fsaverage smoothwm/white surfaces,
the surface area of the average is substantially
reduced (because idiosyncratic sulcal 'crinkles'
are removed).  By contrast, by first inflating
each individual surface and then surface-averaging
the individual inflated surfaces (fsaverage
inflate_avg), the original surface area is
preserved.


----------------------------------------------
labelcol_to_vtxcol
----------------------------------------------

A new tcl/C function, labelcol_to_vtxcol, copies
currently displayed label colors to the vertex
color "paint" field of each vertex.  This is
parallel to currcol_to_vtxcol which does the same
thing for the the current data color.  In both
cases, the vertex color "paint" field can be saved
into a vertex color (*.cols) file with
write_vtxcol_label.

This was done for blink-comparing annotations by
turning one into a vtxcol file.

The labels are above the data/curv/vtxcol layer.

No interface button yet.


----------------------------------------------
tksurfer "val:" line can display 1D bfloat's
----------------------------------------------

The surface resampling program, mri_surf2surf,
can generate vertex list files in 1D bfloat
output format.  These are generated in csurf, for
example, during cross subject averaging using the
panel made by csurf -> CrossSessTools -> Cross
Sess SphereAvg.

The "val:" entry dropdown in tksurfer now loads
any *_000.bfloat files in the current scandir and
can display them with "R".  If the selected file
is part of a complex-valued pair, the other file
(real or imaginary) will also be autoloaded.


----------------------------------------------
fourier.c phase-corrections use AFNI TAXIS_OFFSETS
----------------------------------------------

Sub-TR time axis offsets (AFNI TAXIS_OFFSETS) are
now automatically read by READ HEADER in the Setup
Functional Scan panel, and then passed to
fourier.c if the "UseTAXIS" tickbox is ticked in
the Setup Fourier panel (new fourier.c option
-taxisoffsets), and are used to make sub-TR phase
corrections for multiband and other more complex
slice orders.

Arbitrary slice time offsets can also be manually
pasted into the "Slice Time Offsets List:" field
in the Setup Functional Scan panel.

N.B.: The AFNI TAXIS_OFFSETS field in the AFNI
HEAD file will only be correct if the BRIK has
been generated from the IMA (Siemens DICOM) file
by AFNI to3d using tpattern equals "FROM_IMAGE".
Using, e.g., tpattern "seq+z", "alt+z", etc.,
will NOT generate correct TAXIS_OFFSETS for a
multiband scan.  Versions of ima2brik >= 0.4b
work correctly.

Since the slice time (fourier phase) corrections
(for non-sparse scans) will, on average, retard
the output phase by 1/2 the duration of TR, after
the corrections are applied, all phases are
advanced by the same amount (TR/2).  This allows
direct blink comparison between corrected and
uncorrected scans.

The effects of this correction are quite subtle
for phase-encoded mapping experiments using
standard short-TR multiband acquisitions.


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

add full fsaverage subj w/updated surfs to https://pages.ucsd.edu/~msereno/csurf

tksurfer -- R-click "surf:" to see current surface header in pop-up

pick annot regions to show now works with borders-only, too

also load csurf-style (dash after hemi) annot into annot2roi.tcl combo (!)

fix truncated csurf helpfile on Linux

fix small bug in read_gifti_to_annot (was append line of junk to ctab file)



##########################################################################
UPDATE: 25 Sep 2023
##########################################################################

--lib/help/tksurfer/{label,label_read}: update
--tksurfer.c: print_annot_to_log_ctab also prints $ctabfname.area w/area append
--tksurfer.tcl: count_mgh_annot_neigh2stat->areaneigh2stat,fix R-clk "D" menubar
--tksurfer.c: read_{mgh,gifti,poi,obj}_annot now always count_mgh_annot_neigh
--tksurfer.c: count_mgh_annot_neigh2stat -> count_mgh_annot_neigh+areaneigh2stat
--tksurfer.c: fix read_gifti_to_annot off-by-1 bug (extra junk entry in ctab)
--tksurfer.c: use print_annot_to_log_ctab() for read_gifti_to_annot
--tksurfer.c: count_vtxs_per_brainregion: ignore alpha at compare annot,mghannot
--tksurfer.c: rename: read_poi_annot -> read_poi_to_annot
--tksurfer.c: hack fix 0vtx cnt by set_annot_alpha *after* count (fixed above)
    [tmprelease 230923]
--tksurferc: functify print_annot_to_log_ctab() for read_mgh_annot
--tksurfer.c: read_mgh_annot:print_annot_to_log_ctab writes areas to csurf log
--tksurfer.tcl: fix "D" read-1-label popup: borders (new def), incl area, help
--tksurfer.c: double-mid click also prints brainregion area
--tksurfer.c: fix read_{gifti,poi,obj}_to_annot() as below
--tksurfer.c: read_mgh_annot() uses 2 functs below 
--tksurfer.c: functify: count_vtxs_per_brainregion, calc_area_per_brainregion
--tksurfer.c: read_label_to_annot_using_col() updates filled_{origarea,currarea}
    [tmprelease: 230721]
--ima2brik: don't check for missing 3dAFNItoANALYZE, fix parse "which" output
--src/afni/bin/zz-Darwin-test: 10.7to3d,lib{bz2.1,fontconfig.1,freetype.6}.dylib
    [tmprelease: 230423]
--lib/help/csurf/{setupfunct,setupfour}: better slice timing documentation
--csurf: fouriercmd: can use fourier ... -taxisoffsets <TR> <sl> <s2> .. <slast>
--fourier.c: new opt: -taxisoffsets inp AFNI TAXIS_OFFSETS to slicetime correct
--fourier.c: document half-cycle phase correct for direct comp to SIMUL
--csurf: addfourscan: UseTAXIS vs. UseSliceOrd, check/warn parms
--csurf: READ HEADER ask biff already-read TAXIS_OFFSETS (b/c 3dvolreg non-prop)
--csurf: Setup Align/Funct: add Multiband Accel Factor, Slice Time Offsets List
--csurf: new saved functscanlists parms: mbaccel, taxisoffsets
--csurf: new procs: getafnitaxisoffsets, getafnimbaccel
--tksurfer.tcl: readtemplateframe leave popup, select_curv remake if diff frmcnt
    [tmprelease: 230129]
--tksurfer.c: if annotmaskflag, don't leave padded border of masked annots
--tksurfer.c: make annotmaskflag also work when just borders (annotbordflag)
--tksurfer.tcl: default left-click "R" now req's *.label (was allowing *.annot)
--tksurfer.tcl: R-click "surf:" read_binary_surface printheaderflag -> surfhdr
--tksurfer.c: export new printheaderflag that doesn't exit (justheaderflag does)
--tksurfer.c: new func printf1k: like printf but also appends to genstrret_1k
    [tmprelease: 221227]
--tksurfer.tcl: R-click on upper right "surf:" label lists vertexcnt,facecnt
--lib/help/csurf/{csurf,setuprawavg,setupimport}: bshort update
--lib/help/tksurfer/{val,val_read}: bfloat update
--tksurfer.tcl: read_real_or_complex_binary_values: std fmt cmplx bfloat's OK
--tksurfer.tcl: "val:" entry loads scandir *_000.bfloat's
--tksurfer.tcl: "val:" entry accepts *_000.bfloat, checks corresponding *.hdr
--tksurfer.c: export vertexcnt,facecnt to tcl for err check
--tksurfer.c: read_binary_values accepts mri_surf2surf *_000.bfloat's
    [tmprelease: 221217]
--mk0: fix onearch! (dir check was using csurf, not csurfsrc!)
--mk0: change 'tail +N' to 'tail -n +N' fix Linux fail on lib/help/csurf/csurf
--ima2brik: fix crash on partial transfer
--mri2mpg: convert from csh to sh, chk for ffmpeg, always clear zzMPG
--mk0: rm ._ junk from Mac tarfile (COPYFILE_DISABLE), quit if pwd!=csurf
    [tmprelease: 221025]
--add labelcol_to_vtxcol() to get label "paint" for other label compare
--make a complete CsurfMps1-updated fs5.3 fsaverage
--update-fsaverage: also copy HCP annot, mapping data labels,cols
--dist/fsaverage-ADDITIONS: update README.txt's
--{README.txt,UPDATES.txt}: incl update-{csurf,fsaverage}
    [tmprelease: 221017]
--annot2roi.tcl: load csurf-dash-style CsurfMaps1 annots in dropdown, mk it def


##########################################################################
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
...