#### toggle labels, vtxcol, MGH borders ####
-------------------------------------------
toggle variable (left-click):
  $labelflag -- toggle displayed label visibility
-------------------------------------------
toggle variable (middle-click):
  $vtxcolflag -- toggle vtxcol visibility
-------------------------------------------
toggle variable (shift-middle-click):
  $annotbordflag -- toggle MGH border visibility
-------------------------------------------
  [next 2 only appear if g++ compile]
-------------------------------------------
toggle variable (no shortcut):
  $areanamesflag -- visibility of annot area names
-------------------------------------------
variable: $fontsize (popup) -- area names font size
-------------------------------------------
variable: $dthreshfact (popup) -- hack: adj label occlusion
-------------------------------------------
toggle variable (no shortcut, tcl-only):
  $newreadfulllabflag -- toggle new read shows full labels
-------------------------------------------
toggle variable (shift-right-click):
  $annotmaskflag -- toggle MGH masking-by-idnum(s)
-------------------------------------------
toggle variable (shift-left-click):
  $padlabelvtxsflag -- toggle show neigh of each label vtx
-------------------------------------------
toggle variable (ctrl-shift-middle-click):
  $annotborddotflag -- toggle white dots at borders
------------------------------------------- 
variable: $pointsize (popup) -- area names font size
-------------------------------------------
variable: $meshr (popup) -- area names font size
-------------------------------------------
variable: $meshg (popup) -- area names font size
-------------------------------------------
variable: $meshb (popup) -- area names font size
-------------------------------------------
funct (ctrl-shift-right-click): prune dot borders
  tcl/C funct: prune_annotbord
-------------------------------------------
funct (on labeltick pop-up): restore dot borders
  tcl/C funct: find_annot_borders
-------------------------------------------


The unlabeled tickbox to left of "label:" has six
different functions that affect how labels are
displayed.  This much-too-overloaded tixbox also
pops up a more convenient control panel on a
R-click help.

-------------------------------------------
toggle variable (left-click):
  $labelflag -- toggle displayed label visibility
-------------------------------------------

When $labelflag is 1 (checkbutton to left of
"label:" is selected), any labels that have been
displayed with "D" on the "label:" line, will be
shown as a transparent overlay on top of
curvature or other vertexwise data (if any).
This allows blinking between label(s) and
curvature and/or data.  Use "tran" at upper left
to control displayed label transparency
(opaque=255).

N.B.: displaying a label with "D" ignores any
overlay data values in the label.

-------------------------------------------
toggle variable (middle-click):
  $vtxcolflag -- toggle vtxcol visibility
-------------------------------------------

A non-default middle-click on this checkbutton
toggles $vtxcolflag, and thus visiblity of
vertex-color labels.  Vertex-color labels are
vertex-wise 'paint' with fixed colors (not
sensitive to color scale parameters), which can
be created from any label data.

These can be used to assemble activation patterns
from different experiments (e.g., visual areas
and somatosensory areas).

These colors are read in using middle-click on
the "label:" "R" button.  If $vtxcolflag is set
by a middle-click, they non-destructively
re-color/occlude the existing color of data
vertices.

The state of $labelflag (and the checkbutton
check) is unaffected by this middle-click.

-------------------------------------------
toggle variable (shift-middle-click):
  $annotbordflag -- toggle MGH border visibility
-------------------------------------------

A different non-default *shift*-middle-click on
this checkbutton toggles $annotbordflag, which
determines whether MGH annotation labels, or
standard displayed single labels, are shown
completely, or just at their borders.

This flag also effects the operation of the
functions that use displayed labels/annotations to
dump currently loaded .val's (surface data)
to another label:

for regular single labels:

  shift-middle-click "label:" line "W":
    =>  write_val_annoted_vertices

for MGH annotations:

  shift-left-click "label:" line "W":
    =>  write_val_annotedcol_vertices <r> <g> <b>

  shift-ctrl-left-click "label:" line "W":
    =>  write_val_annotedcols_vertices

The state of $labelflag (and the checkbutton
check) is unaffected by this middle-click.

-------------------------------------------
toggle variable (no shortcut):
  $areanamesflag -- visibility of annot area names
-------------------------------------------
[only appears if g++ compile]

Toggle visibility of brain region names for
any loaded MGH annotation (default OFF=0).

This requires that an MGH annotation has been
loaded.  If none loaded, first do:

  (1) select .annot from dropdown 
  (2) load with "D" button on "label:" line

The label names are centered on the vertex in
each annotation region that is closest to the 3D
average of the vertices in each region.  This 3D
average is calculated (by read_mgh_annot) on
whatever surface (folded, inflated, flattened)
that the annotation has been read onto (if
surface interactively changed, re-read annotation
to re-calc).

See next for manual control of fontsize.

-------------------------------------------
variable: $fontsize (popup) -- area names font size
-------------------------------------------
[only appears if g++ compile]

The fontsize is autoscaled along with brain by
the SCALE slider.

It is also scaled by the size of the GLX/OpenGL
display window (lower left "winxy:" entry).

Finally, it can be manually fine-tuned by using
$fontsize (default 9, for roughly 9 point at
initial startup).

-------------------------------------------
variable: $dthreshfact (popup) -- hack: adj label occlusion
-------------------------------------------

This is a hack to adjust the depth test threshold
for removing areanames that should be occluded.
The default is 1.0.  Turning it up (e.g., to
50.0) makes the occlusion test more permissive
(more possibly occluded labels will be visible),
while turning it down (<1.0) makes it more
restrictive (labels more likely to be removed).

In more detail, removing labels that should be
occluded works like this:

1) dot product of 3rd column of model view matrix
     with vertex normal to find if label location
     is facing away from viewer (but this leaves
     labels at vertices that face the viewer but
     are occluded by other parts of brain)
2) project vertex into image space using model
     view matrix, projection matrix, and viewport
     size
3) find vertex's depth in the image space
4) draw a transparent dot at that vtx location
5) use glReadPixels to find the depth of the
     final pixel drawn at that location
6) if the pixel is nearer to viewer, the dot was
     occluded by something else (add threshold to
     comparison - what $dthreshfact adjusts)
7) but (6) can still fail from depths being
     similar/noisy, causing flashing w/gradual
     pose change
8) modulate label brighness by dot product from
     (1) for depth cue, but also so flashy labels
     at the edges less apparent :-}

-------------------------------------------
toggle variable (no shortcut, tcl-only):
  $newreadfulllabflag -- toggle new read shows full labels
-------------------------------------------

If ticked, this causes subsequently read-in
labels to be displayed in full (by unticking
$annotbordflag upon reading a new label).  This
doesn't disable $annotbordflag, which still works
as expected.

The reason for this flag is that sometimes you
always want just borders, for example, when
looking at relationship between labels and
activations).  In other cases, you always want
full labels, for example, when cutting, viewing,
and editing labels.

-------------------------------------------
toggle variable (shift-right-click):
  $annotmaskflag -- toggle MGH masking-by-idnum(s)
-------------------------------------------

A different non-default *shift*-right-click on
this checkbutton toggles $annotmaskflag, which
determines whether MGH annotation labels will
be used to mask parts of the overlay.

The tcl/C functions controlling which annotation
regions are optionally masked are:

  set_idnum_visibility <idnum> <0=masked,1=visible>
  set_idnums_visibility <0=allmasked,1=allvisible>

Run these from popup at: shift-right-click-"D"

Masking by annot idnum(s) occurs whether or not
annotation label is visible.

-------------------------------------------
toggle variable (shift-left-click):
  $padlabelvtxsflag -- toggle show neigh of each label vtx
-------------------------------------------

Another non-default shift-left-click on this
checkbutton toggles $padlabelvtxflag.  When
ticked, when the *next* label is displayed, the
neighbors of each vertex will also be labeled.

This is designed to make labels consisting of
single vertices more visible.  There is always a
warning whenever a new label is read with this
ticked.

-------------------------------------------
toggle variable (ctrl-shift-middle-click):
  $annotborddotflag -- toggle white dots at borders
-------------------------------------------

Another non-default *control*-shift-middle-click
on this checkbutton toggles $annotborddotflag,
which determines whether dots are drawn at the
borders of currently loaded labels or an MGH
annotation (usu. turn off $annotbordflag when
using this).

The one-pixel dots may appear too prominent when
rendered at the standard 600x600 pixel window
resolution.  One way to to decrease relative
prominence of the dots is to increase the size of
the rendering window with "winxy:" at the lower
right.  Another way is to use the prune_annotbord
function (see next).

A right-click help on the tickbox at the far left
of the "label:" line brings up a pop-up with
controls for dotsize and color (mesh color
controls re-used here).

-------------------------------------------
variable: $pointsize -- for middle-click MESH button
-------------------------------------------

Sets the point size of vertex points (toggle on
with a middle-click on MESH).  This is mainly
useful for displaying sparse labels that don't
have enough vertices to be displayed as faces (at
re-cut time).  An example is when a uniq vtx
label is re-cut by a ctrl-left-click "C" on the
"label:" line.

-------------------------------------------
variable: $meshr (popup) -- area names font size
-------------------------------------------
variable: $meshg (popup) -- area names font size
-------------------------------------------
variable: $meshb (popup) -- area names font size
-------------------------------------------

These are copies of the entries to the right of
the upper left MESH button.  These rgb values
have multiple uses.

In addition to controlling the mesh (polygon
edges) color, they also control points color,
annot border dots color, isocontours
(spherical coordinates) color.

They also report color of clicked MGH annotation,
and can be set to extract .val(.val2) underlying
a particular annotation region color.

-------------------------------------------
Ctrl-Shift-Right-click (tcl/C funct: prune_annotbord)
-------------------------------------------

Another non-default control-shift-left-click on
this checkbutton prunes the density of displayed
annotation border dots using the tcl/C function,
prune_annotbord().

This works by eliminating dots with all or
all-minus-one neighbors already displaying a dot.

N.B.: to restore full borders, simply re-read the
annotation.

-------------------------------------------
tcl/C funct: find_annot_borders
-------------------------------------------

Another way to restore the original density of
border dots, is to run the tcl function,
find_annot_borders.  This can be accessed from
the "RESTORE ANNOT ODTS" button at the bottom of
the labeltick pop-up.
