#################################################################################################
https://pages.ucsd.edu/~msereno/csurf/fsaverage-labels/CsurfMaps1-parcellation/simple-annot/README.txt
#################################################################################################

Lightweight (simple-annot) versions of full annotation

The eight files in here:

  % ls -al
  -rw-r--r-- 1 sereno   655383 Jan  1 16:00 CsurfMaps1_newcurv-lh.w
  -rw-r--r-- 1 sereno   655383 Jan  1 16:00 CsurfMaps1_newcurv-rh.w
  -rw-r--r-- 1 sereno   504152 Jan  1 16:52 CsurfMaps1_old3byte-lh.w
  -rw-r--r-- 1 sereno   501744 Jan  1 16:00 CsurfMaps1_old3byte-rh.w
  -rw-r--r-- 1 sereno  6254705 Jan  1 16:00 lh-CsurfMaps1_MNI152.label
  -rw-r--r-- 1 sereno  6262280 Jan  1 16:00 lh-CsurfMaps1_MNI305.label
  -rw-r--r-- 1 sereno  6096170 Jan  1 16:00 rh-CsurfMaps1_MNI152.label
  -rw-r--r-- 1 sereno  6100257 Jan  1 16:00 rh-CsurfMaps1_MNI305.label

can be placed in the "label" subdirectory of the FreeSurfer average
subject, fsaverage.

N.B.: these files are already included in the updated fsaverage subject
tarfiles here:

  https://pages.ucsd.edu/~msereno/csurf/fsaverage-ADDITIONS.tgz  (just adds)
  https://pages.ucsd.edu/~msereno/csurf/fsaverage.tgz           (fs5.3 + adds)

These files are lightweight valfile and labelfile versions of the left
and right hemisphere CsurfMaps1 MGH annotation files:

  lh-CsurfMaps1.annot
  rh-CsurfMaps1.annot

taken from the publication:

  Sereno MI, Sood MR and Huang R-S (2022)
  Topological Maps and Brain Computations From Low to High.
  Frontiers in System Neuroscience 16:787737
  https://pages.ucsd.edu/~msereno/papers/MapsLowToHigh22.pdf
  (doi: 10.3389/fnsys.2022.787737)

Each file contains vertexwise integer annotation region ID numbers of the
parcellation (stored as floating point 'values').  The files are provided
in freesurfer binary valuefile (wfile) format and ASCII label format.

Binary wfiles (*.w)

The binary *.w files are provided in two different freesurfer format
versions -- "old3byte" and "newcurv".  Details of binary these file
formats are shown below.  Byte sizes are in brackets, repeating groups
indicated by "...", and byteorder MSB (most significant byte first,
'bigendian').  There are MATLAB utilities (read_wfile.m, read_curv.m)
in the standard freesurfer/matlab directory for reading these MSB binary
files into MATLAB.

  ----------------------------------------------
  valfile/wfile -- only vertices w/non-zero values
  ----------------------------------------------
     [magic:  none]
     header:  latency[2],vertexcnt[3]
     data:    {vtxnum[3],floatval[4]}, ...
  ----------------------------------------------

  ----------------------------------------------
  newcurv -- all vertices, implicitly numbered
  ----------------------------------------------
     [magic:  -1     # i.e., 16777215 read in 3bytes]
     header:  -1[3],vcnt[4],fcnt[4],valspervtx[4]
     data:    floatcurv[4], ...
  ----------------------------------------------

ASCII label files (*.label)

The ASCII *.label files are also provided in two versions, which
have included vertex x,y,z coordinates as either MNI 305 coordinates
(freesurfer standard) or MNI 152 coordinates.  Each x,y,z point is moved
outward along the local surface normal from the "orig" surface vertex
by a fraction of 0.4 (40%) of the cortical thickness at each vertex.

Viewing files in csurf

These valfiles files don't look like typical MRI data, so to best
display/verify the integer values in csurf, you can make a random
color lookup table with the csurf-supplied program, mkrandlut (in
$CSURF_DIR/bin/noarch):

  mkrandlut <minval> <maxval> <step> [rseed]

Since the CsurfMaps1 parcellation has 117 regions (plus 0=Unknown),
execute the following commands in a shell to write a val2rgb.lut file
to the cwd:

  cd $SUBJECTS_DIR/fsaverage/scripts
  $CSURF_DIR/bin/noarch/mkrandlut 0 117 1

Then click upper middle "Col:" in tksurfer to get the colscale popup,
select color scale 12 ("lt"), and read the val2rgb.lut file with "R"
on the tksurfer "lut:" line.

