###################################################################
LATEST EMAIL UPDATE: 13 May 2015
###################################################################

sorry for the sooner-than-usual csurf spam.  Here is another
update with some new functionality, 2 visible bug fixes,
and new documentation:

New (~45M) tarfiles are at:

 http://www.cogsci.ucsd.edu/~sereno/.tmp/dist/csurf/UPDATES.txt
 http://www.cogsci.ucsd.edu/~sereno/.tmp/dist/csurf/csurf0.8-linux-150513.tgz
 http://www.cogsci.ucsd.edu/~sereno/.tmp/dist/csurf/csurf0.8-linux64-150513.tgz
 http://www.cogsci.ucsd.edu/~sereno/.tmp/dist/csurf/csurf0.8-mac-150513.tgz


Surface Labels -> 3D AFNI mask ROI BRIK

The main new thing is the ability to dump out
a 3D ROI AFNI mask BRIK from any regular label,
a single region in an MGH .annot file, or all
regions in an .annot file.  The BRIK is 0/1.

This is available from yet more overloading of the
"D" button on the "label:" line. I've appended the
new "D" button help which has all the details.  The
basic label->ROI function is:

  shift-middle-click "D" button after picking label

It warns you what it's going to try to do.


Bug Fixes

There were two visible bug fixes:

  (1) Forgot to global a variable (brainregioncnt) which was
  preventing using the new searchlight correlation facility
  (the "label:" line "X" button) from working when you tried
  to use an MGH .annot brain region.

  (2) The new facility to remember color scale settings
  while swapping between two data sets with the S/V button
  was mistakenly unsetting the color scale the first
  time you swapped.


Document Updates

The overloaded buttons on the label line now
have summaries at the top, so you don't have
to dig down to find them.

### 13 May 2015 (surf label -> 3D ROI, bugfix, doc updates)
 1) "label:" line "D" button can make 3D AFNI mask BRIK from label
 2) bugfixes: swap settings OK 1st time, searchlight corr OK w/.annot

To install the new csurf:

cd <dir-where-csurf-currently-installed>
  mv csurf csurf-YYMMDD
  tar xvfz csurf0.8-{mac,linux}-YYMMDD.tgz

cheers,
marty

########################################################################
Help for the "label:" line "D" button
########################################################################

-------------------------------------------
funct (left-click): display labels
  read_label_to_annot_using_col $r $g $b
  read_mgh_annot
-------------------------------------------
funct (middle-click): undo cut
  read_label_to_undo_cut
-------------------------------------------
funct (shift-middle-click): label => 3D ROI
  write_label_timecourses_stats 3
-------------------------------------------
funct (shift-left-click): annot => 3D-ROI
  write_annotcol_timecourses_stats $r $g $b 3
-------------------------------------------
funct (ctrl-shift-left-click): all annots => 3D ROI
  write_annotcols_timecourses_stats 3
-------------------------------------------


Detailed Description of Label "D" Button Actions

-------------------------------------------
funct (left-click)
  read_label_to_annot_using_col $r $g $b
  read_mgh_annot
-------------------------------------------

A default left-click on the "D" button reads two
different kind of files available in the "label:"
dropdown -- standard ASCII single-label files and
binary MGH annotation files.

Label file (.label suffix)

Display the position of a label as a transparent
colored overlay, ignoring both val's and coord's
it contains -- that is, use only vertex nums.

Reads vertex numbers from from an ASCII label
file whose name is current value of $label (entry
at left) and color the labeled vertices using
specified r,g,b values (0-255).

The r,g,b values that the "D" button passes to
this function are taken from the current values
of the r,g,b entries to the right of the MESH
button.

The opacity of all labels is controlled by the
"tran" field ($labelalpha, default=128 is half
transparent, set to 255 for completely opaque).

To use label to extract surface vertex data in
.val(.val2) fields, see "W" button R-click help
(e.g., tcl funct: write_val_annoted_vertices).

Use the "label:" line "CLR" button to clear the
displayed transparent label.

MGH Annotation file (.annot suffix)

The "D" button can also read a binary MGH
annotation file, which typically contains a set
of differently colored labels, as a transparent
overlay.  In this case the "D" button also reads
the color LUT embedded in the annotation file,
which maps unique colors to brain region names
and numbers.

A left-click on a surface vertex loads the
annotation color into the r,g,b field to the
right of the MESH button.  The corresponding
brain region name and ID number is printed in the
csurf log.

To use the MGH annotation to extract surface
vertex data in the .val(.val2) fields under one
of the colored labels, see "W" button R-click
help (tcl funct: write_val_annotedcol_vertices).

Use the "label:" line "CLR" button to clear the
displayed transparent label, and also, the
embedded MGH color LUT.

-------------------------------------------
Alt funct (middle-click): read_label_to_undo_cut
keyboard equivalent: none
-------------------------------------------

If the "D" button is middle-clicked (instead of
default left-clicked), vertices in label are read
and used to uncut the surface (if cut).  If
vertex not cut, no effect.

To repair unintended surface cuts on a patch,
first make a label that covers the parts of the
cut(s) you want to undo.

There are two critical points:

(1) the cut-fixing label has to be *made* on an
  *uncut* surface (e.g., inflated).  This is so
  that the missing vertices can be labeled.  To
  transfer the location, you can FILL a small
  AREA cut around the unintended cut as a marker
  label then display it on the uncut surface.

(2) the cut-fixing label can only be *applied*
  to an already-cut but *still 3D* surface (e.g.,
  full.patch.3d).  This is because the missing
  (invisible) vertices on an already-flattened
  patch will no longer be located inside the cut
  (they will still be back in their original 3D
  location).

Re-read the cut surface, select the label on
the "label:" entry, and middle click the "D"
button to repair the cut.

Before applying, you can display the cut-fixing
label with a left click on the "D" button.

-------------------------------------------
Alt2 funct (shift-middle-click):
tcl: write_label_timecourses_stats 3 => 3d ROI
-------------------------------------------

If the "D" button is shift-middle-clicked
(instead of default left-clicked), the currently
selected label is converted to a 3D ROI mask
(0,1) AFNI BRIK at the resolution and orientation
of the raw data set (the rawdata set must be
present in the scandir for this to work).

The sampling of the 3D data set is done according
to the current sample settings (right-click the
"label:" label for a popup), and uses the name of
the label as a BRIK prefix.  For example, a label
named:

  rh-MY_AREA.label

will be converted to an ROI BRIK named:

  rh-MY_AREA+orig.BRIK

-------------------------------------------
Alt3 funct (shift-left-click):
tcl: write_annotcol_timecourses_stats $r $g $b 3
-------------------------------------------

A shift-left-click on the "D" button (instead of
default left-clicked), can be used to extract a
3D ROI mask (0,1) AFNI BRIK for one of the brain
regions in a loaded MGH annotation file.

As above, the ROI will be at the resolution and
orientation of the raw data set (so the rawdata
set must be present in the scandir for this to
work).  The steps are:

 (1) select MGH annotation from label dropdown
 (2) load it with left-click "D"
 (3) click one of the brain regions to load r,g,b color
 (4) shift-left-click "D" to extract 3D ROI

The sampling of the 3D data set is done according
to the current sample settings (right-click the
"label:" label for a popup).

The name of the ROI BRIK will be taken from the
MGH annotation file name for the current r,g,b
color.

For example, for annotation file:

  rh.aparc.a2009s.annot

clicking on the STS will set r,g,b (just to right
of MESH) to 223,220,60, and the output BRIK will
be named:

  rh-region_S_temporal_sup+orig.BRIK

-------------------------------------------
Alt4 funct (ctrl-shift-left-click):
tcl: write_annotcols_timecourses_stats 3
-------------------------------------------

Same as previous, but automatically dumps *all*
of the brain regions in an MGH annotation files
to AFNI ROI mask BRIK's.  Takes a min.
########################################################################
end of "D" button help
########################################################################

#########################################
Latest addition to $CSURF_DIR/UPDATES.txt
#########################################

---------------- 13May2015 FreeSurfer0.8/csurf0.8 tarballs -------------------
--fix bug: forgot-to-global-brainregioncnt prevented using do_corr w/MGH annot
--fix bug: lastcolscale was -1 on first complex swap from dup'd fixcolscale var
--csurf: SubjTools->ReMake surf 1hemi only tessellates 1 despite possible stale
--lib/help/csurf/tksurfer: label button overloads, top summaries, writearea, GR
--lib/help/tksurfer/area_{disp,read}: top summaries
--lib/help/tksurfer/{label_{read,readcut,clear,read2val,write}: top summaries
--tksurfer.tcl: warn popups for non-def overload actions "label:" line "D" butt
--tksurfer.c: annotcol2brainregionname exp->tcl, write outp to $brainregionname
--lib/help/tksurfer/label_read: new "D" overloads
--tksurfer.tcl: "label:" ctrl-shift-left-"D" conv all annot regions to ROIs
--tksurfer.tcl: "label:" shift-left-"D" conv 1 clicked annot region to ROI mask
--tksurfer.tcl: "label:" shift-mid-"D" conv label to AFNI ROI mask BRIK
--tksurfer.c: write rawdata-res 3D ROI mask BRIK of vox sampled by label/annot
--tksurfer.c: AFNI write_head()
--mk{.csh}: add new helpfile, label_label, to dist
--lib/help/tksurfer/label_label: new helpfile
--lib/help/tksurfer/{curv_bgcol,val3d_paint,label_stat,label_timecourses}
--tksurfer.tcl: R-click "label:" now brings up help panel (better consistency)
--tksurfer.tcl: bind sample controls popup to (default) L-click "label:"
--tksurfer.tcl: "winxy:" reports clamped-to-screensize number after short delay
---------------- 02May2015 FreeSurfer0.8/csurf0.8 tarballs -------------------
--csurf: Fourier panel PAINT skips surfclust if cluster area is zero
--tksurfer.c: multitimecourseflag restore orig overlay behavio, tcl script only
--lib/help/csurf/tksurfer: improve GL/tk win overloaded clicks docs
--tksurfer.c: popup at init rawdata load 1 timecourse, skip show orig/samp surf
--lib/help/tksurfer/{val_jt,val_vd}: doc fixed controls
--tksurfer.c: fix videen-style fthresh trunc, disable videen fmid/fslope
...




