###################################################################
UPDATE:  07 May 2025
###################################################################

-------------------------------------------------------------------
Summary:
  (1) better instructions, testing, getonearch bugfix for latest Apple Silicon
  (2) new functs to make/process 3D cortical ribbon ROIs from rh/lh-*.annots
  (3) new 3D cortical ribbon ROIs/parcellations (Csurf, HCP-MMP1)
  (4) how to view 3D ROIs/parcellations/overlays in tkmedit
  (5) tcl script to make left+right color lookup table
  (6) cerebellar dentate nucleus surface recon and flattening
-------------------------------------------------------------------


-------------------------------------------
(1) Better instructions, testing, getonearch bugfix latest Apple Silicon
-------------------------------------------

[no effect on Linux distribution]

Finally got access to latest Apple Silicon for
testing.

A recent Apple change in the uname -p response broke
getonearch, which broke FreeSurferEnv.{sh,csh},
which broke startup of any csurf program :-{ Now
fixed.

The current distribution requires Rosetta 2:

  softwareupdate --install-rosetta --agree-to-license

Working on native arm64/universal compile, to get
rid of this requirement.  Very good performance
through Rosetta 2.

Apple seeoms to have fixed the long-standing
appnap bug that was catastrophically slowing down
X11 apps, so I have turned off my hack fix
(pop-up/kill xterm over X11 window so resulting
expose event speeds draw).  If problems comes
back, can toggle the hack on/off in csurf
Preferences.


-------------------------------------------
(2) new functs to make/process 3D cortical ribbon ROIs from rh/lh-*.annots
-------------------------------------------

There are three new functions for making 3D ROIs
from fsaverage surface annotations, for both
individual subjects, as well as for fsaverage
itself:

(a) fill_idnumbrik_holes <in.BRIK> <neighfracthresh:0-1>

This function examines the 26 voxels surround an
empty (idnum=0=Unknown) voxel.  If more than
$threshneigh (default=13) contain idnums, it
replaces the hole with the most common
surrounding idnum.  N.B.: This writes over its
input.

(b) merge_idnum_briks <in1.BRIK> <in2.BRIK> <out.BRIK>

This function merges right and left hemisphere 3D
ROI (idnum) BRIKs.  If a voxel from the first
BRIK is already occupied, if the second BRIK has
an occupied voxel there, it will overwrite the
voxel in the first BRIK.  The input BRIKs must
have the same dimensions and orientations.

(c) read_shortbrik_write_mgz

This function converts a 256^3 1mm^3 BRIK into an
*.mgz parcellation (typically for fsaverage).


-------------------------------------------
(3) New 3D ROIs/parcellations
-------------------------------------------

3D parcellations for the fsaverage orig volume
made from the fsaverage orig surfaces are now
included in the csurf distribution in
$CSURF_DIR/subjects/fsaverage-ADDITIONS/mri):

  CsurfMaps1.mgz
  CsurfMaps1+orig.BRIK
  CsurfMaps1+orig.HEAD 

  HCP-MMP1.mgz
  HCP-MMP1+orig.BRIK
  HCP-MMP1+orig.HEAD 

and can also be downloaded from here:

  https://pages.ucsd.edu/~msereno/csurf/fsaverage-labels/

These color tables have uniquely numbered
and colored left and right hemisphere regions
and are suitable for standard 3D analyses.
The corresponding color tables can be found
in the distribution here:

  $CSURF_DIR/lib/lut/CsurfColorLUT-both.txt
  $CSURF_DIR/lib/lut/HCP-MMP1ColorLUT-both.txt

These extend from a cortical thickness depth
fraction of 0.0 to 1.1 above the fsaverage orig
(gray-white matter boundary) surface.

These were generated with the improved
annot2roi.tcl tcl script popup, which uses
the new functions above.


-------------------------------------------
(4) How to view 3D ROIs/parcellations/overlays in tkmedit
-------------------------------------------

To view a 3D parcellation in tkmedit, select one
(e.g., CsurfMaps1.mgz, HCP-MMP1.mgz) from the
"im2:" dropdown at the middle bottom, and click
the adjoining "R" (read) button.

Double-middle-click a region to get a popup with
the region name, idnum, and color.


-------------------------------------------
(5) tcl script to make left+right color lookup tables
-------------------------------------------

There are multiple conflicting conventions for
region ID color tables in FreeSurfer.  Here are
features of some variants:

  FreeSurferColorLUT.txt  (ASCII)
    -- for assembling *.annot file from indiv. *.label files
    -- non-sequential region id nums (gaps present)
    -- mostly hemisphere-specific names, different conventions

  CsurfColorLUT.txt  (ASCII)
    -- for assembling *.annot file from indiv. *.label files
         (used by csurf tksurfer write_mgh_annot)
    -- non-sequential region id nums (gaps present)
    -- non-hemisphere-specific names
    -- used by csurf tksurfer write_mgh_annot to make annotation

  <hemi>-<annotation-infix>.annot  (binary)
    -- for displaying/using parcellation on hemisphere surface
    -- contains an embedded color lookup table
    -- each region must have a unique RGB color
    -- always sequential region id nums (0=Unknown/unlabeled)
    -- always one hemisphere

  <annotation-infix>.ctab  (ASCII)
    -- written to subject's scriptsdir when tksurfer reads annotation
    -- this is embedded color lookup table
    -- always sequential region id nums (0=Unknown/unlabeled)
    -- names may or may not be hemisphere-specific

For a full-brain 3D cortical ribbon ROI
parcellation (e.g., Csurf or HCP-MMP1), we need
hemisphere-specific names, unique ROI idnums, and
unique RGB colors.

Therefore, a new tcl script, mkbothlut, is
provided to combine freesurfer single-hemisphere
color lookup tables (LUTs) into a LUT suitable for
use with the 3D cortical ribbon ROIs/parcellations
above.  Here is the usage:

---------------------------------------------------
  Use: cd $CSURF_DIR/lib/lut
       mkbothlut CsurfColorLUT.txt
                *or*
       mkbothlut HCP-MMP1ColorLUT.txt   [looks for 2 files lh-*,rh-*]

  Make hemi-uniq idnums/names/cols from ONE hemi-agnostic csurf color LUT:
    (1) add max LH region idnum to RH region idnums (LH then RH)
    (2) prefix region names w/L_,R_ (LH is 1st)
    (3) add 1 to r/red region color

            *or*

  Make hemi-uniq idnums from TWO HCP-MMP1 color LUTs (rh-,lh- prefix):
    (1) concat files (rename from *.ctab scriptsdir outp on read annot)
    (2) add max LH region idnum to RH region idnums (LH then RH)

  outfile: CsurfColorLUT-both.txt
                *or*
  outfile: HCP-MMP1ColorLUT-both.txt
---------------------------------------------------

Here are the properties of the two kinds of output
files:

  CsurfColorLUT-both.txt  (ASCII)
    -- sequential, no gaps, LH is first
    -- hemisphere-specific names (e.g., R_MT_lower/L_MT_lower)
    -- unique left/right RGB colors (add 1 to red region color)

  MCP-MMP1LUT-both.txt (ASCII)
    -- sequential, no gaps, LH is first
    -- hemisphere-specific names (e.g., R_MT/L_MT)
    -- [checks unique left/right RGB colors]

These color lookup tables are now included in the
current csurf distribution, or available here:

  https://pages.ucsd.edu/~msereno/csurf/fsaverage-labels/


-------------------------------------------
(6) cerebellar dentate nucleus surface recon and flattening
-------------------------------------------

In the process of revising a cerebellar atlas paper (earlier version):

  https://www.biorxiv.org/content/10.1101/2024.08.27.610006v1.full.pdf

I have distributed a left and right deep
cerebellar dentate nucleus surface reconstruction
and flattening in the same coordinate system as
the original cerebellar cortex reconstruction:

  https://pages.ucsd.edu/~msereno/cereb/updates/dentate-nucleus

I also added the vermis labels and flattenings,
including labels that now continue into the
anterior lobe:

  https://pages.ucsd.edu/~msereno/cereb/updates/vermis-labels/cerebmap20


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

new flag to toggle border/no-borders of newly read labels

fix annot2roi.tcl combo box csurf '-' style annotations not loaded (!)

fix HCP-MMP1 colortable so tkmedit underlay not washed out

g++ compile now error clean

savesingleROIbriksflag so avoid indiv ROI BRIK bloat

add restore_zero_position to R-click RESTORE button menu

clean g++ compile (for eventual ftgl font parcellation text labels)


##########################################################################
UPDATE: 07 May 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
--tksurfer.c: fill_brik_holes: threshneigh arg (1-26) -> neighfracthresh (0-1)
--tksurfer.c: use above in fill_brik_holes/merge_idnum_briks/shortcorbrik2intmgz
--tksurfer.c: new lazy global 3D tmpshortbrik avoid Mac repeat malloc/free crash
--tksurfer.c: add makeshort3D: fill_brik_holes/merge_idnum_briks/shortcorbrik2..
--lib/help/tksurfer/script_annot2roi: major update
--annot2roi.tcl: mk "annot:" dropdown like main "label:" (.annot only,!setfile)
--annot2roi.tcl: convert merged BRIK to mgz parc if subject is fsaverage
--annot2roi.tcl: if both right/left hemi idnum ROI BRIKs present, merge them
--tksurfer.c: add/export merge_idnum_briks (non-general: short, same dims)
--tksurfer.c: add get_brikoris (not exported)
--tksurfer.c: get_{brik,bfloat}dims return vs. harsh xit, pass BRIK vs. HEAD
--tkmedit.tcl: add CsurfMaps1,MY_ANNOT to 'mgh'seglabstemlist to autodetect parc
--annot2roi.tcl: add fill3Dholesflag to run fill_brik_holes
--tksurfer.c: fill_brik_holes: patch all-in-one BRIK pial surface holes
--annot2roi.tcl: disable/normal feedback for search/nosearch, frac/mm options
--tksurfer.c: add/export shortcorbrik2intmgz: 256^3 all-in-one BRIK -> mgz parc
--tksurfer.c: get_brikbyteorder: not exported
--annot2roi.tcl: rm redundant sampclustctrls popup (main panel has enough)
--tksurfer.tcl: add R-click help for entry labels on sampclustctrls
--wrappers.tcl: controls proc: uniq window id from new global: $ctrlswinid
--tksurfer.tcl: regularize sampclustctrls{win}, return win for reposition
--tksurfer.tcl: fix comment-bug crasher "E## force opaque ignoring "tran" entry"
--tksurfer.tcl: select_patch: after 100 to (try to) improve missed shift key
--annot2roi.tcl: improve feedback sequence, better bugouts
--annot2roi.tcl: add sampclustctrls popup, unoverlap by reposition up
--annot2roi.tcl: fix combobox wasn't loading '-' style like CsurfMaps1 (!!)
--annot2roi.tcl: fsaverage 3D ROIs: auto-make pseudoscandir/funct/regdat
--annot2roi.tcl: fsaverage 3D ROIs: force user to mk pseudofunct scandir w/csurf
--tksurfer.c: smooth_steps alt functs report filled/eroded
--tksurfer.tcl: add annoterode button to R-click smooth_steps help
    [tmprelease 241208]
--tksurfer.tcl: $newreadfulllabflag (tcl) overrides def just show label borders
--lib/help/tksurfer/{redraw,arrownorm,label_write}: bigcursorflag behavior
--csurf: change startup subject to fsaverage if it exists
--lib/help/tksurfer/{redraw,arrownorm}: update
--tksurfer.tcl: add toggle bigcursor button to REDRAW right-clk popup
    [tmprelease 241129]
--mk0: 04a: also incl EMAIL in dist and insttmp, UPDATES in dist
--tksurfer.c: .._nearest_annot: foreign surf vtxcnt unknown: allow 'off edge' k
--tksurfer.tcl: labelW_randcolannot/write_statids2randcolannot chks overwrite
--tksurfer.tcl: better HOWTO save/see result on 'paintballs' popups
--tksurfer.tcl: isocont popup action button sets isocontourflag
--tksurfer.tcl: R-clk smoothsteps buttbar for numer/non-numer smooth steps opts

##########################################################################
UPDATE: 12 Nov 2024
##########################################################################

--lib/help/tksurfer/{smooth_steps,label_read,selectdmax}: update
--tksurfer.c: read_label_to_nearest_annot_using_col: ignore ripflag vtxs
--tksurfer.c: fill_annot_holes_neigh: ignore ripflag vtxs to speed high neiorder
--tksurfer.c: fill_annot_holes_neigh: add neiorder=5 for smaller surfaces
--tksurfer.c: fix fill_annot_holes bugs (fill val sometimes 0, then paren bug)
--tksurfer.tcl: rm "annotholes-more" b/c fill_annot_holes_neigh is more general
--tksurfer.c: rm fill_annot_holes_more (redundant w/fill_annot_holes_neigh)
--tksurfer.tcl: "annotholes-neigh" uses funct: C/tcl fill_annot_holes_neigh
--tksurfer.tcl: overload smooth steps: add "{annot,label}holes-neigh popup
--tksurfer.c: add fill_annot_holes_neigh(neiorder,annotedfrac) general funct
--tksurfer.tcl: smoothsteps: "{annot,label}holes-more" -> fill_annot_holes_more
--tksurfer.c: add fill_annot_holes_more(): (filled nei minus 3 (vs. minus 2)
--tksurfer.tcl: add no-hotkey "D" button: read_label_to_nearest_annot_using_col
--tksurfer.c: read_label_to_nearest_annot_using_col(): for updated surfaces
    [tmprelease 241028]
--tksurfer.c: fix write_label_hdr check-fp-writable-code on Linux (& O_ACCMODE)
--tksurfer.tcl: disp annot prints totarea all regions (except Unknown) for csurf
--tksurfer.c: tot area annot regions (except Unknown) to genstrret_1k/csurflog
--tksurfer.tcl: add $lighttwosidedflag to lights popup from R-click help buttbar
--tksurfer.tcl: fix R-click report popups for current ta/cu button state
    [tmprelease 240709]
...