-------------------------------------------
function: read_second_images <CORdir *or* .mgz>
-------------------------------------------
keyboard equivalent: none

The "R" button on the "im2:" line reads in a
second set of images to allow them to be blink
COMPARE'd with the first, editable image set.

It can also be used to read a segmentation
overlay (*.mgz format, see below, handled by the
tkmedit.tcl function, detectshowlabel).

The second image buffer cannot be edited or
directly saved, but can be swapped.

N.B.: edits done while viewing the secondary
"im2:" COMPARE buffer will be applied invisibly
to primary, editable "im:" image set (useful, for
example, when editable=wm and image2=orig).

The default output of PF (planefilter) or PFGAU
(gaussian planefilter) is to "im2:".

Reading a different data set with "R" on the
"im2:" line displaces any data currently in the
secondary buffer without question.

To swap the contents of the "im:" (editable) and
"im2:" (compare) buffers, do an alternate
middle-click on the COMPARE button.

If the image in the secondary "im2:" buffer has
been previously edited, you can apply those edits
to the primary buffer with shift-middle-click
COMPARE (edits-to-black are not completely
black).

3D Segmentation/ROIs Overlay

A byte or int-containing MGH 3D segmentation file
(e.g., aparc+aseg) can also be read by "R" to
generate a transparent ROI label overlay of the
data in the primary (editable) buffer, if the
second image set filename stem is:

  aseg
  aseg.auto
  aseg.auto_noCCseg
  aparc+aseg
  aparc.a2005s+aseg
  aparc.a2009s+aseg
  wmparc
  wm.asegedit
  wm.seg
  ribbon
  lh.ribbon
  rh.ribbon
  CsurfMaps1
  MY_ANNOT
  HCP-MMP1

in most cases, the colors will be specified by
also reading:

  $CSURF_DIR/lib/lut/FreeSurferColorLUT.txt

If the image filename starts with "Csurf" or
"MY_ANNOT", the overlay colors will instead be 
read from:

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

If the image filename start with "HCP-MMP1", the
overlay colors will instead be read from:

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

For more information, do a R-click to get help on
the popup from running the tksurfer annot2roi.tcl
script (also: csurf -> Help -> All Help Contents
-> TkSurfer -> TclScript -> annot2ROIs.

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

See R-click help for the "im2:" entry for
details.  To add to the list, update
$mghseglabstemlist at the top of tkmedit.tcl.

To use the segmentation to extract timecourses,
see the R-click help for the "T" button on the
"roiup:" line (F2 interface).
