Annotation Documentation

Home < Annotation Documentation

Return to miAnnotation

miAnnotation

miAnnotation (Medical Image Annotation)

GUI

General Information

Module Type & Category

Type: Interactive

Category: Base

Authors, Collaborators & Contact

Kilian Pohl: pohl@csail.mit.edu
Yong Zhang: yzhang@bwh.harvard.edu

Module Description

The miAnnotation Module is designed for users to annotate medical images to capture information latent in the scans.

Usage

Eight (8) different types of annotations can be created in the following ways:

Region Of Interest (ROI): Click on the ROI Icon on the middle panel of the miAnnotation main panel, a new ROI annotation will then be created on the right-hand-side 3D view. There are seven (7) control points on the ROI annotation for the user to interact with. The six (6) control points located on the six surface of the ROI box can be dragged using mouse left-button to enlarge or shrink the box. The one (1) control point located in the center of the box can be dragged using mouse left-button to relocate the box in the 3D view. A new ROI entry will also be created in the annotation table. The properties of the ROI annotation can be edited by clicking the edit icon in the annotation table.

Text: Click on the text Icon on the middle panel of the miAnnotation main panel, a new text annotation will then be created on the right-hand-side 3D view. The default location of the new text annotation is on the bottom left corner of the viewer. The user can move the text annotation to any other locations by clicking and dragging the text annotation using the mouse middle-button. A new text entry will also be created in the annotation table. The content of the text annotation can be edited from the entry in the annotation table. The properties of the text annotation can be edited by clicking the edit icon in the annotation table.

Ruler: Click on the ruler Icon on the middle panel of the miAnnotation main panel, a new ruler annotation will then be created on the right-hand-side 3D view. The default location of the new ruler annotation is in the middle of the viewer spanned from left to right. The user can click and drag any one of the two control points of the ruler annotation to interact with it. A new ruler entry will also be created in the annotation table. The value of the ruler measurement can be automatically updated when the user interact with the ruler. The properties of the ruler annotation can be edited by clicking the edit icon in the annotation table.

Angle: Click on the angle Icon on the middle panel of the miAnnotation main panel, a new angle annotation will then be initialized on the right-hand-side 3D view. The users are required to manually click three (3) times in the 3D viewer using mouse left-button to create the real angle annotation. After creating the angle annotation, the user can click and drag any one of the three control points of the angle annotation to interact with it. A new angle entry will also be created in the annotation table. The value of the angle measurement can be automatically updated when the user interact with the angle. The properties of the annotation can be edited by clicking the edit icon in the annotation table.

Fiducial: Click on the fiducial Icon on the middle panel of the miAnnotation main panel, then the users are required to manually click in any of the 2D viewers using mouse left-button to create a new fiducial annotation. The new annotation will also be displayed in the 3D viewer. After creating the annotation, the user can click and drag it to interact with it. A new fiducial entry will also be created in the annotation table. The properties of the annotation can be edited by clicking the edit icon in the annotation table.

Bidimensional Lines: Click on the bidimensional lines Icon on the middle panel of the miAnnotation main panel, then the users are required to manually click in the 3D viewers using mouse left-button to create two lines. These two lines are automatically orthogonal. After creating the annotation, the user can click and drag any of the four control points to interact with it. A new bidimensional line entry will also be created in the annotation table. The properties of the annotation can be edited by clicking the edit icon in the annotation table.

Spline: Click on the spline Icon on the middle panel of the miAnnotation main panel, then a new spline annotation point is created right in the center of the 3d viewer. The users are able to manually click and drag the spline point using mouse left-button to other locations in the 3D viewer. Up to five (5) points can be clicked and dragged from the initial location of the spline annotation. After creating the annotation, the user can click and drag any of the five control points to form different splines to fit their needs. Or the user can click and drag the entire spline annotation to move it as a whole. A new spline entry will also be created in the annotation table. The properties of the annotation can be edited by clicking the edit icon in the annotation table.

Sticky Note: Click on the stick note Icon on the middle panel of the miAnnotation main panel, then a new stick note is created. There are no displays of the note in any of the 2D or 3D viewers. After creating the annotation, a new sticky note entry will be created in the annotation table. The properties of the annotation can be edited by clicking the edit icon in the annotation table.

Use Cases, Examples

This module is especially appropriate for these use cases:

Use Case 1: This module is useful for basic measurements of volume, area, length, angle.
Use Case 2: Use eight different annotations to annotate medical images.

Tutorials

Links to tutorials explaining how to use this module:

Tutorial (coming soon)
Data Set (coming soon)

Quick Tour of Features and Use

Annotated GUI layout: (see below for a detailed description of each element, listed by panel.)

File:UIDesignSlicer3.4FiducialsGUIDraft5Anno.png

Modify All Fiducial Lists & Their Fiducial Points panel:

File:SlicerFiducialsModifyAllPanel-3.4.png
	Global Control of Fiducial Lists icons.
	File:SlicerFiducialListsSelectAll-3.4.png Select all fiducial points from all lists.	File:SlicerFiducialListsSelectNone-3.4.png Deselect all fiducial points from all lists.	File:SlicerFiducialListsDeleteAll-3.4.png Delete all fiducials lists and the fiducials they contain.
	File:SlicerHideExposeAllFiducialLists-3.4.png Hide or expose all fiducial lists (preserve fiducial visibility settings).	File:SlicerLockOrUnlock.png Lock or unlock all fidicuial lists so that they cannot or can be moved in 3D.	File:SlicerVisibleOrInvisible.png Set visibility on all fiducials in all fiducial lists (preserve hide/expose settings).

Modify a Selected Fiducial List & Its Fiducials panel:

File:SlicerFiducialListDisplayPanelCollapsed-3.4.png
	Control a Selected List icons
	File:SlicerHideFiducialList.png File:SlicerExposeFiducialList.png Hide or expose the selected fiducial list (preserves fiducial visibility settings)	File:SlicerFiducialListLock-3.4.png File:SlicerFiducialListUnlock-3.4.png Lock or unlock the selected fiducial list.	File:SlicerVisibleOrInvisible.png Set visibility on all fiducials in the selected list	File:SlicerDeleteFiducialList-3.4.png Delete all fiducial points in the selected list and then delete the list.

Add and Modify Individual Fiducials panel:

You can reset the positions of the fiducials in the table that appears in the Add, Configure and Delete section of the Fiducials GUI.

File:SlicerFiducialsAddModifyIndividualFiducials-3.4.jpg
	Add & Modify Individual Fiducials icons.
	File:SlicerFiducialsSelectAllInList-3.4.png Select all fiducial points from this fiducial list.	File:SlicerFiducialsSelectNoneInList-3.4.png Deselect all fiducial points from this fiducial list.	File:SlicerFiducialsAddNew-3.4.jpg Add a fiducial point to the current fiducial list, at (0,0,0).	File:SlicerFiducialsUp.png Move last clicked fiducial up one in the list.	File:SlicerFiducialsDown.png Move last clicked fiducial down one in the list.
	File:SlicerFiducialsDeleteLastClicked-3.4.png Delete the last fiducial that was clicked on in the table.	File:SlicerFiducialsDeleteAll-3.4.png Delete all fiducial points from this fiducial list.

File:SlicerFiducialsListBox-3.4.jpg
	Selected: flag set to checked if this fiducial is selected
	Visible : icon set to an open eye if this fiducial is visible, close if invisible.
	Name: text to be displayed at this fiducial location
	X : X axis location of this fiducial, corresponding to R in RAS
	Y : Y axis location of this fiducial, corresponding to A in RAS
	Z : Z axis location of this fiducial, corresponding to S in RAS
	Locked : icon set to a closed lock if this fiducial is locked

File:SlicerFiducialsDistance-3.6.jpg
	Distance: distance between first two selected fiducials, updated as selection changes and fiducials are moved.
	List Distance: distance between all selected fiducials in list, updated as selection changes and fiducials are moved.
	Renumber Fiducials: Renumber the fiducials in this list. Removes any numbers from the ends of the labels and then appends a number denoting the current place in the list, starting from entered value, 0 if none. Note: does not affect the auto name generation for the next added fiducial.	Rename Fiducials: Rename the fiducials in this list. Preserves any numbers at the end of the labels. Note: does not affect the auto name generation for the next added fiducial - change the list name from the node selector.
	Numbering Scheme: Set the numbering scheme used to assign integers to the next added fiducial in the list. UseID uses the point ID, UseIndex uses the list index of the point, UsePrevious increments the number at the end of the previous point.

Click on a value and hit the 'Enter' key (or double click) on one of the X, Y, or Z position values to edit it manually. You can do the same on the fiducial name to change it. The default name is generated from the name of the list, which can be changed in the Data Module.

The distance between the first two selected fiducials in the list will be computed automatically and appear in a label below the list of fiducials. This distance is in milimetres.

To align slices with fiducials, move the fiducial while holding down the Control key. You can use the '`' (backtick) key to jump to the next fiducial, Control-` to jump backwards through the list.

Use the backspace or delete key to delete a fiducial over which you are hovering in 2D.

Argument Lists: Fiducials can be passed as a list of points to a command line module, for example to do ACPC registration. Only the points that are selected in the list are passed to the command line module, so you can adjust which points are used for calculating the output.

Other List Display Properties panel:

File:SlicerFiducialListDisplayPanelExpanded-3.4.png
	Glyph Type: Select the glyph used to represent this point in 3D. There is a long list of glyph types available, each list can have a different glyph type, as well as colour and size properties. The default is the 2D starburst, but 3D glyphs are also available. File:FiducialsGlyphTypes.jpg
	Selected Color: Select the color used to represent the fiducials when they are selected.
	Unselected Color: Select the color used to represent the fiducials when they are not selected.
	Glyph Scale: Select the scale of the glyph. For the 3d glyphs (Sphere and Diamond3D), 1 corresponds to 1mm in diameter.
	Text Scale: Select the scale of the fiducial label text.
	Opacity: Select the opacity of the fiducial glyph and text. 0 = invisible.
	Ambient: Set the ambient material property for the fiducial glyph.
	Diffuse: Set the diffuse material property for the fiducial glyph.
	Specular: Set the specular material property for the fiducial glyph.
	Power: Set the power material property for the fiducial glyph.

The following image shows what these types of glyphs look like in 3D: File:SlicerFiducialsGlyphs3D-3.4.jpg

and in 2D (the 3D glyphs default to a star burst in 2D): File:SlicerFiducialsGlyphs2D-3.4.jpg

Loading and Saving Lists

Fiducial lists can be written out to disk using the File menu, Save option. The files can be loaded into Slicer via the File menu, Add Data interface.

Fiducial list files are plain text, with the extension fcvs.

An example file:

# Fiducial List file /home/username/L.fcsv
# name = L
# numPoints = 5
# symbolScale = 5.5
# symbolType = 11
# visibility = 1
# textScale = 12.5
# color = 0.4,1,1
# selectedColor = 0.807843,0.560784,1
# opacity = 1
# ambient = 0
# diffuse = 1
# specular = 0
# power = 1
# locked = 0
# columns = label,x,y,z,sel,vis
L-P,-58.0508,64.4069,0,1,1
L-P1,31.7797,-1.69492,0,1,1
L-P2,-2.11864,-49.1527,0,0,1
L-P3,-72.4576,-54.2374,0,1,0
L-P4,-63.1356,3.38984,0,1,1

Lines are commented out by placing a hash mark (#) at the beginning of the line. There is an optional header section that lists display options. If no display options are included, the defaults are used when the list is read into Slicer. The header line formats follow the description of the point format.

The points are listed one per line in the following format:

 pointName,X,Y,Z,selected,visibility

pointName	a text string that is displayed at the location of the fiducial.
X,Y,Z	3 floating points that represent the 3D RAS location of the fiducial, in mm.
selected	an integer value, either 0 or 1, denoting if the fiducial is selected or not.
visibility	an integer value, either 0 or 1, denoting if the fiducial is visible or not.

The header section of the fiducial list file consists of lines starting with a hash mark and a space (# ). A keyword = value pair follows the space. The keyword is parsed and compared against the list of known keywords:

Fiducial List file header
Fiducial List file	Path to the fiducial list file when it was last saved from Slicer.
name	A name for the list, new points will be named according to this string and the point number
numPoints	The number of points in the list, skipped for now, as the list is built up by adding a point for each line in the points section of the file
symbolScale	Floating point, used to scale the glyphs for all the fiducial points.
symbolType	Integer selected from the range representing glyph types, default is 11 for a star burst. 0 Vertex2D 1 Dash2D 2 Cross2D 3 ThickCross2D 4 Triangle2D 5 Square2D 6 Circle2D 7 Diamond2D 8 Arrow2D 9 ThickArrow2D 10 HookedArrow2D 11 StarBurst2D 12 Sphere3D 13 Diamond3D
visibility	Integer, 0 means the list as a whole is invisible, 1 means that any visible fiducial points are visible.
textScale	Floating point number that is used to scale the label text for all the fiducial points
color	Three comma separated floating point numbers that give the red, green, blue values to be used for the glyph and text when the fiducial is not selected.
selectedColor	Three comma separated floating point numbers that give the red, green, blue values to be used for the glyph and text when the fiducial is selected.
opacity	Floating point number 0.0-1.0, material property on the glyph
ambient	Floating point number 0.0-1.0, material property on the glyph
diffuse	Floating point number 0.0-1.0, material property on the glyph
specular	Floating point number 0.0-1.0, material property on the glyph
power	Floating point number 0.0-1.0, material property on the glyph
locked	Integer, 1 means the list as a whole is locked (points can't be moved in the 2d or 3d windows), 0 means the list as a whole is unlocked.
columns	This entry gives you the flexibility to reorder your data for each point, the default is label,x,y,z,sel,vis . It's a comma separated list of keywords giving the format of the following lines for each point.

Importing Lists into a Spreadsheet

To import a fiducial list into OpenOffice.org's Calc, version 3.1.1:

In Slicer3, open the File, Save dialog and select the fiducial list to save.
Set the file name, ending with .fcsv, and the directory in which to save it
Open OpenOffice.org's Calc
Click on File, Open
Expand the File type menu
Select Text CSV as the file type
Make sure All Files is selected for the directory listing filter
Browse to the directory in which you saved your .fcsv file and select it, then click Open
The Text Import window will pop up
In the Separator options, set it so that only comma is selected (the color and selectedColor comment lines will get separated into columns, but so will the column s comment to give headers for the rows of points)
Click Open and the import will finish, with the fiducial points starting on row 18

To open a list in Excel 2007:

In Slicer3, open the File, Save dialog and select the fiducial list to save.
Set the file name, ending with .fcsv, and the directory in which to save it
Click on the symbol in the top left to open the menu, select Open (if Import is an option, use it instead)
Set the filter to All Files (*.*)
Browse to the directory in which you saved your .fcsv file and select it, then click Open
Text Import Wizard will open
In Original Data Type, select Delimited
Click Next
In Delimiters, select Comma only
Click Next
The Column data format should be fine as General
Click Finish

Development

Notes from the Developer(s)

From Slicer3.5 to Slicer3.6, the underlying implementation of the fiducials in the 3D scene has been changed to use vtkSeedWidgets.

Dependencies

No other modules or packages are required for this module's use.

Tests

On the Dashboard, these tests verify that the module is working on various platforms:

vtkMRMLFiducialListNodeTest1 Libs/MRML/Testing/vtkMRMLFiducialListNodeTest1.cxx
vtkMRMLFiducialListStorageNodeTest1 Libs/MRML/Testing/vtkMRMLFiducialListStorageNodeTest1.cxx
Slicer3FiducialsTest1 Base/GUI/Testing/TestFiducials.tcl
Slicer3FiducialsTest2 Base/GUI/Testing/TestFiducialsAdd.tcl
Slicer3FiducialsTestGlyphs Base/GUI/Testing/TestFiducialsGlyphs.tcl
Slicer3FiducialsTestChangeGlyphs Base/GUI/Testing/TestFiducialsAddSymbolScale.tcl

Known bugs

Follow this link to the Slicer3 bug tracker.

Usability issues

Follow this link to the Slicer3 bug tracker. Please select the usability issue category when browsing or contributing.

Source code & documentation

Source Code:

Links to documentation generated by doxygen:

More Information

Acknowledgment

This work is part of the National Alliance for Medical Image Computing (NAMIC), funded by the National Institutes of Health through the NIH Roadmap for Medical Research, Grant U54 EB005149.

References