###################################################################
UPDATE: 04 Oct 2016
###################################################################


Read GIFTI surfaces

First make a new empty subject (e.g., hcp-mmp1)
with File -> New Subject, and put the *.gii
surfaces into the surf subdirectory inside the new
subject.

To view one of the GIFTI surfaces, select it from
the "surface:" dropdown and click SURFACE.

To view a GIFTI surface using tksurfer directly,
use a command line like this:

  tksurfer hcp-mmp1 rh Q1-Q6_RelatedParcellation210.R.inflated_MSMAll_2_d41_WRN_DeDrift.32k_fs_LR.surf.gii

Currently, csurf reads surfaces with Base64Binary
and GZipBase64Binary encoding (but not yet rarely
used ASCII or ExternalFileBinary encoding).

The tcl/C function read_binary_surface
auto-detects the GIFTI format:

  setfile insurf ~/surf/Q1-Q6_Related...surf.gii
  read_binary_surface

Since flattened GIFTI surfaces are stand-alone
surfaces (i.e., not tksurfer-like patch files that
rely on a parent full surface), they will be
loaded into the "surface:" dropdown, not the
"patch:" dropdown.


Read GIFTI vertexwise data

A GIFTI file containing a single column of
vertexwise data overlay (e.g., *.shape.gii or
*.func.gii), can be read onto a surface as a value
file by selecting it from the tksurfer "val:"
dropdown and loading the data onto the surface
with "R" on the "val:" line (vertex count must
match the current surface).

The tcl/C function read_binary_values
auto-detects the GIFTI format:

  setfile val ~/surf/Q1-Q6_Related...surf.gii
  read_binary_values

Currently, csurf *cannot* read CIFTI files (see
next for HOWTO use HCP MMP1 parcellation.  CIFTI
files are a peculiar kind of NIFTI file
(originally ANALYZE) that has an embedded XML
file before the 3D data array, but after the
binary NIFTI header.

For example, the XML insert in a
*.CorticalAreas_dil_Colors.* file contains a
color lookup table for region names, as well as a
list of vertices for both hemispheres, followed
by -- in what would normally be the 3D data part
of the NIFTI file -- lists of region ID values
for the vertices in both hemispheres.


Using the HCP MMP1 parcellation

The HCP MMP1 parcellation can be used directly as
an MGH annotation file without the need to load
any GIFTI surfaces (so I didn't really need to
read GIFTI surfaces after all...).

Kathryn Mills has instructions for using Workbench
and MGH Freesurfer tools to resample the HCP MMP1
parcellation to full ic7.tri fsaverage resolution
here:

  https://figshare.com/articles/HCP-MMP1_0_projected_on_fsaverage/3498446

The fsaverage annotatation files themselves:

  lh.HCP-MMP1.annot
  rh.HCP-MMP1.annot

are here:

  https://ndownloader.figshare.com/articles/3498446/versions/2 (.zip)

or here:

  http://www.cogsci.ucsd.edu/~sereno/.tmp/dist/csurf/fsaverage-labels/

To load/use these freesurfer annotations in csurf:

  1) unzip or download the 2 .annot files
  2) put them in: $SUBJECTS_DIR/fsaverage/labels/
  3) select subject "fsaverage", open with SURFACE
  4) select ~/label/rh.HCP-MMP1.annot from the "label:"
       dropdown (near bottom, after labels)
  5) display with "D" on "label:" line

The transparency can be adjusted with "tran"
(tksurfer upper left -- 255 is opaque), curvature
can changed from red/green to grays with the
"overlay" tick (or toggled on/off with the "curv"
tick at upper middle).

To toggle viewing just the region borders versus
filled-in regions, shift-middle-click on the
tick to the left of "label:".  Here is what the
right hemi looks like (borders and filled-in):

  http://www.cogsci.ucsd.edu/~sereno/.tmp/dist/csurf/fsaverage-labels/HCP-MMP1-annotbord-rh-inflated_avg-lat.tiff
  http://www.cogsci.ucsd.edu/~sereno/.tmp/dist/csurf/fsaverage-labels/HCP-MMP1-annotfull-rh-inflated_avg-lat.tiff
 
You can extract or operate on data from one (or
all) of the annotation regions using the "W"
button on the "label:" line (see R-click help for
"W" button).

To select one region, click it (the region name
will appear in the log).  This loads the unique
RGB color of the region into the r,g,b fields to
the right of MESH.  To get a pop-up with the
region name, double-middle-click it (yup).

The csurf operations available for an annotation
region are:

  "W" -> write ASCII label of curr vertex data under region
  "T" -> extract timecourses from raw 3d BRIK for region
  "S" -> extract stats from raw 3d stats BRIK for region
  "X" -> run searchlight cross-correlation for region


New non-parametric correction option to surf-based FDR

The function, find_FRD_from_pvals, not has an
non-parametric correction factor for arbitrary
distributions ("arbitrFDRcovarflag" tick on
pop-up).  As you might guess, this reduces
requires a more stringent uncorrected p-value to
obtain a desired p-value.  The cut-off, p, is
determined from:

    p = i/n * q/c;

where i is the current sorted sample index, n is
the total number of samples, q is the desired
p-value, and c is approx. equal to:

   1.0/(log(cnt) + 0.5772)

instead of being 1.0


Save surface-based spotlights to ASCII file

A new function was added:

  write_spotlights <fillneartype:0-2> <criterion>

which writes a single ASCII file of concatenated
surface-based spotlights (vertex list for each
center vertex in a label file) in the following
format:

  #!ascii , 82934 spotlight centers, lab=/usr0/sessions/fsaverage/label/rh-MY_AREA.label, surf=rh.inflated,  fillneartype=1, criterion=250
  spotlight 0 vertex 3457
  3456
  3459
  ...
  spotlight 1 vertex 3878
  3874
  3881
  ...
  [etc, to spotlight 82933]

This tcl/C function is accessible with a
shift-ctrl-right-click (yup) on the "W" button on the
"label:" line.  The parameters to this function:

  <fillneartype:0-2>   0=number, 1=area, 2=radius
  <criterion>          num vertices, area mm^2, or rad mm

are interactively set by middle-clicking the N, A,
or R buttons at the lower right ($fillneartype)
and entering a criterion (e.g., num vtxs) in the
nearby entry ($criterion):

This is if you want to use the spotlights
for something other than built-in tksurfer
cross-correlation and retinotopy border-finding
functions.


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

better tcl script examples, hints


##########################################################################
UPDATE: 04 Oct 2016
##########################################################################

[IN PROG]

--lib/help/csurf/{csurf,rc-surfaces,rc-surface: update for GIFTI}
--lib/help/tksurfer/{clks,surf,val}: update for GIFTI
--lib/help/tksurfer/{clks,surf,val}: update for GIFTI
--tksurfer.c: double-middle-click selects vertex and prints annot (if loaded)
--tksurfer.c: double-middle-click selects vertex and prints annot (if loaded)
--tksurfer.tcl: "val:" entry loads *.$hemi.*.{func,shape}.gii
--csurf: load "surface:" dropdown w/non-hemi-prefixed GIFTI surfs incl flat
--tksurfer.c: read_binary_values now accepts one-frame GIFTI
--tksurfer.c: new/exported var, giivalframe: choose later frame in .gii valfile
--tksurfer.c: if surfext is *.gii ignore/fix hemi, don't append hemi to fpref
--tksurfer.tcl: "surf:" entry loads *.$hemi.*.surf.gii, no preappend hemi 
--tksurfer.c: read_binary_surface reads GIFTI base64/gzip (no ASCII yet)
--tksurfer/Makefile: $(INC_XML), $(LIB_XML_ST), -lezxml
--mk0{.csh}: compile, myinstall ezxml.{h,a}
--add csurf/dist/ezxml-0.8.6.tar.gz
--tksurfer.c: new #include: ezxml.h
--tksurfer.c: add meminflate() for in-memory gunzip, bs64_{enc,dec}() for base64
--lib/help/tkmedit/trunc
--tkmedit.tcl: shift-middle-TRUNC to countvox (white_{lo,hi}lim, to log)
--tkmedit.c: add/export countvox <low> <high>, lims included so lo=hi OK
--lib/help/tksurfer/fill: update: fillbutton, script left_click coords
--lib/help/tksurfer/{label_write,fillcrit,fill2*}: update
--tksurfer.tcl: 6th overload (shift-ctrl-right-clk) label "W": write_spotlights
--tksurfer.c: write_spotlights: ASCII to ~/label/$hemi-Spotlights.txt for label
--mk0{.csh}: dist/insttmp: lib/tcl/zz-examples/{crosscorr,renderoffscreen}.tcl
--lib/help/tksurfer/script: better hints/examples
--tksurfer.tcl: add arbitrFDRcovarflag tick to mid-click-"CS" popup
--tksurfer.c: find_FRD_from_pvals: add nonpar FDR correct: div by log(n)+0.5772
--tksurfer.tcl: better "label:" line "C" OK help after recut sparse/uniq label
--lib/help/tksurfer/smooth: document tcl wrapper

##########################################################################
UPDATE: 24 Jun 2016
##########################################################################
--lib/help/tksurfer/{label_readcut,mesh}: HOWTO make/disp sparse uniqvtx labels
--tksurfer.tcl: middle-click MESH toggles pointsflag
--tksurfer.tcl: ctrl-left-click "C" recut label respecting normdsampuniqvtxflag
...