#### toggle labels, vtxcol, MGH borders ####
-------------------------------------------
toggle variable (left-click):
  $labelflag -- toggle displayed label visibility
-------------------------------------------
toggle variable (popup):
  $surfaceflag -- toggle displayed surface (leave labels/etc)
-------------------------------------------
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 (popup):
  $areanamesflag -- visibility of annot area names
-------------------------------------------
variable: $fontsize (popup) -- area names font size
-------------------------------------------
variable: $dthreshfact (popup) -- hack: adj label occlusion
-------------------------------------------
toggle variable (popup):
  $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 (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 tickbox is way too overloaded.
Instead, use the popup control panel you get from
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 (popup):
  $surfaceflag -- toggle displayed surface visibility
-------------------------------------------

When $surfaceflag is 1 (default), you see the
surface :-} .  For an illustration, however, you
might want to turn off the surface to obtain an
overlay that just contains areaname labels,
regular labels/annotations, border lines, or
border dots.  To save an overlay tiff with black
changed into transparent, middle-click "W" on the
"rgb:" line.

-------------------------------------------
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 (popup):
  $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 (popup):
  $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" or
"Pick Annot Idnums to View/Mask" on the "D"
button R-click popup.

Masking by annot idnum(s) occurs whether or not
annotation label itself 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).

-------------------------------------------
toggle variable (ctrl-shift-middle-click):
  $annotbordlineflag -- toggle lines at borders
-------------------------------------------

If ticked, this draws lines at the border between
annotations (or around a single label).  This is
less 'blurry' than the dots border option above.

In more detail, the reason for the 'blurriness'
of the dots is that they mark the vertices at the
edge of each label, but that means there will be
a second parallel row of dots from the edge of
the adjoining label.

By contrast, the $annotbordlineflag option first
finds surface triangles (or quads) where at least
two pairs of corners have different annotation
values and marks those triangles.  Then the
center of each marked triangle is found and line
segements are drawn between the centers of
adjoining marked triangles.

The resulting line between annotations will run
haflway in between the rows of edge dots/vertices
of adjoining annotation regions.

The thickness and color of the border lines can
be controlled by the pontsize and meshline
entries.

-------------------------------------------
toggle variable (ctrl-shift-middle-click):
  $annotbordzzagflag -- toggle zig-zag lines at borders
-------------------------------------------

If ticked, this draws lines between neighboring
surface vertices that have different annotation
values at the two vertices.

This creates a distinctive zigzag pattern (and
provides the basis for the logic above).

-------------------------------------------
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: $pontsize -- border dot width
-------------------------------------------
variable: $meshline -- border line thickness
-------------------------------------------
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 mesh{r,g,b} 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, annot border lines
color, and isocontours (spherical coordinates)
color.

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

This last can be irritating if you accidentally
click on an annotation when trying to adjust the
display of annotation border lines.  Just reset
the desired color an hit <Ret> to redraw.

-------------------------------------------
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.
