#### re-cut, make-hole-with, add a label ####
-------------------------------------------
funct: "Re-cut Label File (left-click-C)"
  set label <infile>
  read_label_cut_clearvals <0=label>
-------------------------------------------
funct: "Make Hole w/Label File (mid-click-C)"
  set label <infile>
  read_label_cut_clearvals <1=hole>
-------------------------------------------
funct: "Add Label File to Existing (shift-mid-clk-C)"
  set label <infile>
  read_label_cut_clearvals <2=add>
-------------------------------------------
funct: "Re-cut CurrLabeled (ctrl-left-click-C)"
  labeled_cut_clearvals <0=label>
-------------------------------------------
funct: "Make Hole w/CurrLabeled (ctrl-mid-click-C)"
  labeled_cut_clearvals <1=hole>
-------------------------------------------
funct: "Re-cut Label w/Uniq (ctrl-shift-left-clk-C)"
  clear_uniqvoxdata
  setfile label */$scandir/$hemi-UniqSampVtxs.label
  read_uniqsamp_vertices
  set label <infile>
  read_label_cut_clearvals 0
-------------------------------------------


Detailed Description of Label "C" Button Actions

-------------------------------------------
funct: "Re-cut Label File (left-click-C)"
  set label <infile>
  read_label_cut_clearvals <0=label>
-------------------------------------------

Re-cut a label (leave just label) and zero the
.val/.val2 fields from the cut-away parts.

This has multiple uses, for example, to touch up
a label (use PTS button after re-cutting), to set
up to append another label (see below), to write
out a wfile (subset or full-surface modes)
containiing only values in the label.

Ignores data values in label file itself.  Use
shift-middle-click-R (read and re-cut) instead if
you want to read the values in the label into the
.val field.

This operation does *not* restore any currently
invisible vertices.  Thus, it can be used to find
the overlap between two (or more) labels as
follows:

  1) clear all displayed labels with "CLR"

  2) select 1st label ("label:" dropdown)
      "C" => display, recut 1st label

  3) select 2nd overlapping label
      "C" => also recut 2nd label

  etc..

The final result is the overlap (AND) of two (or
more) labels.  To find the area of the label or
overlap, select a point in area, and use FILL.

N.B.: if the labels don't overlap, nothing will
be left!

Click lower right INIT to start over or recut a
different label.

If a wfile is loaded before doing this, a wfile
(as opposed to an ASCII *.label file) containing
surface values for only the label (or label
intersection) can be saved with "W" on the "val:"
line.

-------------------------------------------
funct: "Make Hole w/Label File (mid-click-C)"
  set label <infile>
  read_label_cut_clearvals <1=hole>
-------------------------------------------

Cut vertices in the label out of the currently
displayed surface (cut out a hole) and zero the
.val/.val2 fields from the cut-away parts.

Ignores values in label file itself.

This is useful for removing overlap between
labels as follows:

  1) tick "er" ($erodingfillflag) near FILL button

  2) start by recut oversized label (left-click-C)

  3) select label for cutting in "label:" dropdown

  4) cut hole (middle-click-C) to remove overlap

  5) type orig label name in "label:" dropdown!!

  6) save fixed label (left-click-W)

N.B.: If the "er" is unticked, this operation
will result in labels that share vertices at
their boundary (may be desired).

This is also useful for editing wfiles (as
opposed to labels) to remove artifacts as
follows:

  1) display a wfile (not label) with "R" on the
       "val:" line

  2) fill artifact in it with ROI and fthresh,
       possibly restricting fill w/tmp cuts

  3) save the resulting artifact label

  4) INIT, to restore surface cuts

  5) middle-click "C" on the "label:" line to
       cut out the artifact and zero .val/.val2

  6) save modified wfile with "W" on "val:" line

This can also be used to create complex labels by
subtracting (multiple) subregions.

When saving the final label after this operation
(with left-W on the "label:" line), be sure to
verify (there will be a warning popup) that the
"label:" entry has the intended output file name!

-------------------------------------------
funct: "Add Label File to Existing (shift-mid-clk-C)"
  set label <infile>
  read_label_cut_clearvals <2=add>
-------------------------------------------

Make all vertices in the label visible.  No
effect if those vertices are already visible.

If this operation restores part of the surface
that previously had data read onto it (with "R"),
that data will be restored.

N.B.: ignores values in label file itself.

This operation can be used to combine (merge)
labels as follows:

  1) clear all displayed labels with "CLR"

  2) select 1st label ("label:" dropdown)
      "leftclick-C" => display, recut 1st label

  3) select 2nd label to add
      "Shift-middleclick-C" => add 2nd label

  etc...

When saving the final label, be sure to verify
that the "label:" entry has the correct intended
output file name!

The composite cut label can be immediately saved
with "W", or after first reading data into it.
Later on, the label can be used to capture
surface data from any other data set from the
same subject as follows:

  1) load any surface data

  2) select label from dropdown and display
       it with "D" as a transparent label
       over the data

  3) change name of label in "label:" entry
       if you don't want to overwrite the
       data currently in the label

  4) use Shift-MiddleClick-"W" (tcl funct:
       write_val_annoted_vertices) to write label

-------------------------------------------
funct: "Re-cut CurrLabeled (ctrl-left-click-C)"
  labeled_cut_clearvals <0=label>
-------------------------------------------

Cut a label (leave just labeled) using currently
display label(s) and zero the .val/.val2 fields
from the cut-away parts.

Same as first option but uses currently displayed
label(s) instead of reading a file.

Can be used to combine labels or to mask
activations in preparation for making a vertex
color label.

-------------------------------------------
funct: "Make Hole w/CurrLabeled (ctrl-mid-click-C)"
  labeled_cut_clearvals <1=hole>
-------------------------------------------

Cut vertices in currently display label(s) out of
surface (cut out a hole) and zero the .val/.val2
fields from the cut-away parts.

Same as second option but uses currently
displayed label(s) instead of reading a file.

-------------------------------------------
funct: "Re-cut Label w/Uniq (ctrl-shift-left-clk-C)"
  clear_uniqvoxdata
  setfile label */$scandir/$hemi-UniqSampVtxs.label
  read_uniqsamp_vertices
  set label <infile>
  read_label_cut_clearvals 0
-------------------------------------------

Same as a default left-click but also auto-reads
$hemi-UniqSampVtxs.label (generated at PAINT time
if UniqVtx was ticked) so recut label will only
contain 'representative' vertices -- that is, a
single vertex for each sampled voxel nearest to
the average position of the vertices that sampled
that voxel.

At re-cut time, since the resulting sparse label
will typically contain only a single vertex from
any given face, it cannot be displayed as a
continuous surfacepatch, so $pointsflag will be
turned on to make the sparse label visible
(middle-click the MESH button to toggle
$pointsflag).

Once the sparse label has been written,
re-displaying it with the "D" button will pad the
single vertices with their surrounding faces so
it can be seen (see the R-click for the ROI
button for a full explanation of why it has to be
this way).

