Issues: tksurfer label/annotation edit features
Index
Contents
Summary
In tksurfer, labels can be created via the Custom Fill dialog, and labeled regions can be edited in various ways with the Labels dialog. These features have unexpected effects on the annotation data, which in turn leads to unexpected results if saved in an annotation file, and further unexpected results later when that annotation file is loaded back into tksurfer.
2008-03-01 update: Please also see tksurfer_labeledit which provides more detail in the multiple-labels-per-vertex issue.
Details
First an orientation to the Labels and Custom Fill dialogs, then an examination of the issues.
Label dialog
Below is an image of the Label dialog on which I have indicated names for its components to faciliate discussion. (These are names from the tksurfer.tcl.)
In general, the controls on the right side of the dialog can be used to set new values for properties of the selected label on the left side. Editing moves are sketched in the figure below:
Custom Fill dialog
The custom fill dialog allows various "fill" operations.
Primarily, it allows labeling a set of vertices: Ie: giving a set of vertices a new structure code, with corresponding name, and color. One of the options is to "Create new label" for this fill process.
Issues
There are a number of ways in which the edit moves described above don't completely perform as expected.
MMTable
Where |
Edit move |
Label dialog |
Surface view |
Tool window |
Implications for Save Annotation |
Surface view |
Select region |
Selection changes in slwLabel |
Region of selected label shows highlighted border |
- |
- |
Label dialog |
Select Label in slwLabel |
Selection changes in slwLabel |
Region of selected label shows highlighted border |
- |
None |
Label dialog |
Click on color in cpwColor |
- |
Selected region changes color |
New color NOT reflected in Annotation field, no change to Label |
Vertexwise annotation value of zero gets saved (as checked with hex dump). Hence on next load, the edited region has no label, annotation is zero, label is 'None' |
Label dialog |
Click on structure in slwStructure |
Name of structure appears in alwStructure. Color of structure applied to selected Label |
Selected region changes color |
New color NOT reflected in Annotation field. No change to Label field |
Vertexwise saved annotation value gets derived from new color, which DOES correspond to known structure, hence on later load the expected new structure code is applied to vertices in the edited Label. IE: Save...Load causes Label to change! |
Label dialog |
Press 'Set Name' button (bwCopy) |
In slwLabel, selected label changes name |
No change |
Label field shows new label. However, Annotation field does NOT show new color. |
Saved annotation value gets derived from new color, which DOES correspond to known structure, hence on later load the expected new structure code is applied to vertices in the edited Label. |
Label dialog |
Enter new name in ewName, then hit [Return] |
In slwLabel, the new name replaces the name of the selected Label. |
No change |
Label field shows new name |
New name does not get saved to annotation file |
These problems point to the following suspected underlying issues:
- Custom Fill dialog: Creation of a new label apparently does not create a corresponding entry (including color) in tksurfer's in-memory LUT -- ie: it does not produce a new Structure code number and associated name and color
- Label dialog: Applying a color to the selected label updates vertex color in the surface view, but not the vertex annotation value, as reported in the the Tool Window Annotation field. Applying a new structure code to the selected label (using the "Apply Name" button) indeed updates the label (and its name) as seen in the surface view and tool window, but again not the annotation.
Ie: Editing using the Custom Fill dialog and the Labels dialog causes the vertexwise label and color values to get out-of-sync with the structure LUT and the vertexwise annotation value. When subsequently saved using Export to Annotation, this results in various kinds of edits being unexpectedly omitted from the exported data.
The situation is especially serious following the Custom Fill dialog Create New Label operation. The user might well apply various editing moves in the Labels dialog to the new label. Despite these edits appearing to take effect in the Surface Window and Tool Window, so far as I can discover, there is no sequence of moves that results in any of these edits getting saved to an annotation.
Aside on data structure of Annotation files
I suspect that certain amount of trouble stems from annotation files storing vertexwise annotation value (basically RGB color), instead of structure code. This breaks normalization of the various data objects, and precipitates the need for various synchronizations of parallel forms of what should be the same information.
Perhaps there is a use case supported by this design which makes annotation value semi- independent of structure code, though I have not thought of one. In any case, tksurfer appears to defeat this by being unwilling to save vertexwise color/annotation value unless it's one of the colors in the structure table. Ie: tksurfer prevents annotation values from being some independent list of codes, prefering instead to lose that data (set it to zero).
Aside on Labels procedure doc
This page: TkSurferGuide/TkSurferWorkingWithData/TkSurferLabel provides docs for end users regarding working with Labels. It makes a couple of statements reflecting how users probably want to regard labels:
"You can also export label files for use in other FreeSurfer programs, or export a collection of anatomical labels as an annotation."
"You can also import an annotation file as a series of labels." (This sentence appears to be backwards.)
An annotation file is a binary file that assigns a label index to each vertex in a surface. When the annotation is imported, a label is created for each unique index, and the vertices with those values are added to that label. (This is incorrect: an annotation file stores annotation value, which is color, for each vertex, not label index aka structure number.)
Despite these statements being somewhat incorrect, they show that experienced end users are teaching new users to think of annotation files primarily as a consolidated collection of label data packaged with corresponding "available structure codes" info. This furthers the argument that this is the way annotation values and annotation files should behave.