Differences between revisions 10 and 11
Deletions are marked like this. Additions are marked like this.
Line 7: Line 7:

2008-03-01 update: Please also see ["tksurfer_labeledit"] which provides more detail in the multiple-labels-per-vertex issue.

Issues: tksurfer label/annotation edit features

Index TableOfContents

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

attachment:tksurfer_labels_dlog_comps.jpg

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:

attachment:tksurfer_labels_dlog_edits.jpg

Custom Fill dialog

The custom fill dialog allows various "fill" operations.

attachment:tksurfer_customfill_dlog.gif

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.

Author/s

GrahamWideman

gwissue_labeledit (last edited 2008-04-29 11:45:10 by localhost)