brains:BRAINSTracer

From NITRC Wiki

Return to brains:MainPage

Contents 1 Rationale 2 Tracing With Spline Curves 3 Graphical User Interface 3.1 2D Planar Views 3.2 3D View 3.3 Overview Panel 3.4 Results Panel 3.5 Module Panels 4 Tutorial: Create an Anatomical Trace 5 Editing Contours 6 Copying Curves between Slices 7 Surface Generation 8 Usage 8.1 Command LIne Flags 9 Menus 9.1 File 9.2 View 9.3 Window 9.4 Traces 9.5 Points 9.6 Options 9.7 Modules 9.8 Help 10 Viewer Hot Keys 11 Viewer Mouse Interaction 12 Trace Interaction

Rationale

The BRAINS2 tracing feature has been around for many years, and is a key feature of the program. A generation of graduate students and research assistants has used it for manual tracing of brain anatomy, and their work is key to many research projects. There are several features of the BRAINS2 tracer that have made it a popular program for many institutions beyond the University of Iowa:

• Precision. The traced outlines are saved with sub-voxel positional accuracy.

Throughput. Once a user has learned to use the tracer, they can trace anatomy very quickly.

• Stability. The tracer has been continuously in development and maintenance for two decades, and has no outstanding bugs or instabilities.
• Institutional Standard. Since the same program has been in continuous use for so long, there is a reservoir of highly proficient tracers who are both highly productive in their own work, and a resource for training new tracers.

But any program module as venerable as the Brains2 tracer has drawbacks as well, that can best be addressed by development of a replacement

• Platform dependence. The tracer is built with the XForms library, and only functions where the X11 Windowing system is available.
• Learning Curve. The tracer's user interface was developed before current standards for user interaction were commonly known. Consequently it is idiosyncratic, and prior experience with other software is of little help in using it.
• Code complexity. Internally, the tracer software is complex, mostly undocumented code. The original developers have long since left the building. The code interacts directly with X11 events and OpenGL function calls, rather than using a high-level library with a well-defined execution model.

This new visualization and tracing tool is based on cross-platform libraries including ITK, VTK, KWWidgets, and Slicer3. This software environment is a rich enough platform to make development of new tools like this tracer much easier than trying to retool the existing tracer to fit in the new environment.

Tracing With Spline Curves

Past tools, including the BRAINS2 Tracer, have generally supported two methods of tracing: a Click and Move technique, where straight lines are drawn between the locations of successive mouse clicks and a Pencil Draw technique, where the mouse button is held down and points are added every time the mouse cursor moves.

The Click and Move method has one big disadvantage – there are few if any straight lines in biological anatomy. The Pencil Draw technique has two disadvantages – it requires a very steady hand to draw a smooth boundary around a feature, and it generates many points, which makes correcting a contour tedious.

BRAINSTracer (and VTK, which supplies the vtkContourWidget used) takes a different approach, a variation on Click and Move: the user clicks on points along the feature boundary, but instead of straight lines, a spline curve through the control points is used. The curved boundaries can be progressively refined by adding new control points between existing ones. It generally takes fewer points to define a feature in this manner than it would with either of the older methods.

Graphical User Interface

The BRAINSTracer window comprises a several elements. A standard menubar at the top Below the menubar, a group of buttons that selects an particular view and shows it by itself. A tree view on the left. The names of all traces, surfaces and images are shown, and for each such item, a right mouse click brings up a list of operation available appropriate to the data type. 4 rectangular views of the current image volume.

2D Planar Views

The 2D Planar view is where you create the contours that outline the chosen anatomical feature. It comprises these elements:

• Main view, where a slice of the image volume is displayed.
• Slider control to the left, to select which slice upon which to trace
• Buttons to Add a new contour, copy contours to the previous/next slice, and a menu to select the contour to edit, create new contour sets, or delete an existing set.

3D View

The 3D View shows the planes defined by the three 2D Views, arrange in space. It also displays the traced contours, surfaces, and Talairach grids. This view can be manipulated to help you see the features in which you’re interested, but it does not support manipulation of the traces. This view can also be used for display of volume rendering.

Overview Panel

This panel shows the user all of the objects that have been loaded into BRAINSTracer. Several options are also available based on object type.

• ROI - Display the spline based contours for each view. Currently visible traces are shown in Bold text. Right clicking on any trace will bring up a menu with the following options.
  • Hide - Hide the display of the trace
  • Show - Make the trace visible
  • Edit Properties - Edit the display properties for the trace
  • Generate Surface - Generate a surface from the contour
  • Measure Volume - Measure the volume of the trace in CC's
  • Save Trace - Save the trace
  • Delete - Delete the selected trace

• Images - The primary or underlay image is displayed in Bold text.
  • The user can switch the underlay image by left clicking on the name of the the desired underlay image.
  • The user can select on overlay image that will be display with opacity by right clicking on the overlay image and selecting the opacity. This will overlay this image using a red color table. Selecting an opacity of 0% will turn the overlay image display off.

• Surface

• Point Set

• Talairach- List of currently loaded Talairach Grids and Bounding boxes. Currently visible talairach structured grids are shown in Bold text. Right clicking on any trace will bring up a menu with the following options:
  • Hide - Hide the selected Talairach Bounding box
  • Show - Show the selected Talairach Bounding box
  • Adjust - Modify points of the Talairach Bounding box
  • Edit Properties - Edit the display properties for the selected Talairach structured grid
  • Save - Save the selected Talairach structured grid
  • Delete - Delete the selected Talairach structured grid

Results Panel

This panel is used to report all measurements results to the user. This can be volume of a trace, angle or distance. We will also add the ability to measure the volume and surface area of a surface in future releases. The units of the measurements are reported in the table. The table can be saved to a comma separated file.

Module Panels

If the user should select one of the available modules from the Available Modules menu, then a new panel will appear in the Main Panel region with the name of the module. This allows the user to specify parameters for the module and then run the module interactively by pressing the Run button in the lower left. In this example we show the Bayesian Classifier module from BRAINS.

Tutorial: Create an Anatomical Trace

1. Run BRAINSTracer. You can specify the image volume to trace on the command line, e.g. BRAINSTracer –input T1.nii.gz, or you can load an image via the File menu once the BRAINSTracer window appears.
2. Choose an acquisition plane upon which to trace – Axial, Sagittal, or Coronal.
3. Use the slider to the left of the window to change slices until you find a slice in which the feature you wish to trace is visible.
4. Click the “Add Trace” button below the window for your chosen plane.
5. Click somewhere on the boundary of the feature you wish to trace.
6. Click again elsewhere on the boundary of the feature. A line will appear between the points where you’ve clicked.
7. Click again on the boundary of the feature. You’ll now see a curve from the first point to the last point.
8. Continue clicking around the boundary of the feature until you get close to the first point you created.
9. Click on the first point of the curve. This closes the curve.

Editing Contours

When you first create a contour around an anatomical feature, the contour curve may not conform exactly to the boundary. You can refine the contour in several ways. Click on the contour outline between any two points to add a new control point. Due to the mathematical behavior of spline curves, if two points along a traced contour are too far apart, the curve can ‘bow in’ or ‘bow out’ depending on the position of other points defining the curve. The more points along the feature boundary you click, the closer the curve will follow the boundry. Click on any control point and drag it closer to your desired feature boundary. Again, because of the mathemics of splines, this can affect the curvature of contour segments to either side of the point you’ve dragged. Placing the mouse cursor over a point (until it is surrounded by a green circle), and then pressing the ‘delete’ key will delete that point.

Copying Curves between Slices

There are two buttons at the bottom of each 2D Plane view labeled “Copy to Previous” and “Copy to Next.” These buttons copy all contours for the current slice to the previous or next slice. This allows you to quickly work through a feature on several planes, because most of the time the difference between the outline of a feature doesn’t change that much in adjacent slices.

This allows for a ‘trace once, edit many times’ workflow. Once you carefully trace one slice you can select “Copy to Next”, and then switch to the next slice. In many cases, you will only have to nudge a few control points to follow the boundary of the feature.

If you copy the traces to a slice and they are really not appropriate to the feature, you can use the ‘Traces->plane->Delete Slice Contours’ menu item, and it will erase all contours for the current slice from the current Trace.

Surface Generation

The curves defined by the user or created by loading a mask and be used to generate a triangle surface. The surface generation pipeline includes the following steps:

1. Convert the contour to a binary image
2. Application of an anti-aliasing filter to the binary image
3. Surface generation using marching cubes
4. Surface Decimation
5. Surface smoothing using a windowed sinc filter.

Parameters for the surface generation can be set from the options menu. To generate a surface right click on the contour of interest from the Object tree and select the Generate Surface option.

Usage

Command LIne Flags

--inputImage filename1 ... filenameN

Load one or more images. '--inputImages' also accepted. Any image file format supported by ITK can be used.

--inputSurface filename1 ... filenameN

Load one or more surface files. '--inputSurfaces' also accepted. VTK '*.vtk', VTK '*.xml', and STL '*.stl' file formats can be used.

--inputROI filename1 ... filenameN

Load one or more ROI files. '--inputROIs' also accepted. VTK XML '*.xml' and Slicer fiducial '*.fcsv' files can be used.

--inputTalairach filename1 ... filenameN

Load one or more Talairach bounds files. '--inputTalairach' also accepted. Accepts VTK structured grid files in VTK and XML format.

--script tcl_script_file1 ... tcl_script_fileN

Execute one or more Tcl Scripts. Also accepts--scripts.

--modulePath directory1 ... directoryN

Add one or more directories to the paths searched by the ScanModules menu item to discover Slicer Execution Model programs.

Menus

File

• Load Image - Load an image. All ITK supported image types can be loaded. If you select a DICOM image, the entire DICOM series will be loaded. File format support includes but is not limited to the following formats:
  • NifTI
  • Analyze
  • Meta
  • NRRD
  • DICOM
• Load Trace - Load a spline based trace. The user selects the orientation of the trace to be loaded:
  • Axial
  • Coronal
  • Sagittal
• Save Trace - Save the specified trace to disk.
• Load Surface - Load a surface file from disk. Currently the following formats are supported:
  • STL - requires the file to have the .stl extension
  • Old VTK - requires the file to have the .vtk extension
  • VTK XML - All other extensions are assumed to be in this format
• Load Talairach - Load a Talairach representation. This can be either a Bounding box representation or a grid representation. The bounding box representation simply stores the AC, PC, SLA, and IRP points. The Talairach grid defines the Talairach coordinate system. The data is stored as VTK structured grids. The following formats are supported:
  • Old VTK - Requires the file to have the .vtk extension
  • VTK XML format - All other extensions are assumed to be in this format
• Load Mask - Load a binary image and create a spline contour based on the binary structure. It is recommended that you use the NifTI format or some other format that supports image orientation and origin. The old BRAINS mask format does not and should not be used. It is provided for backwards compatibility only.
• Save Mask - Create a binary image from the user specified contour and save it to specified file. The image type for the image is determined based on the file extension.
• Load Point Set
• Exit - Exit BRAINSTracer

View

• Application Settings - Set settings for the program that will be reloaded upon restart.
• Font Size - Set the size of the font to be used in the program. This is for the GUI and not the image viewers
• Font Family - Set the font style to be used in the GUI
• Views - Select the specified image viewer layout. Any single image viewer (Axial, Coronal, Sagittal, 3D) can be displayed or a 2x2 grid of all views can be displayed. The Icons below the main menu as well as the left and right arrows between the image viewers can also be used to customize the layout. Currently, the viewer layout is not restored upon restart.
• Slice Orientation - Display the letters to define the orientation for the image viewers (R, L, S, I, A, P).
• Slice Annotations - Display image based annotations including Window/Level, Position, Image Size, Spacing, and Zoom Factor on the 2D views.
• Contour Properties - Bring up a Color Dialog Box to change the color of the contour
• Capture Axial View - Create a snapshot in Jpeg format of the axial view. The user is prompted for a file name.
• Capture Coronal View - Create a snapshot in Jpeg format of the coronal view. The user is prompted for a file name.
• Capture Sagittal View - Create a snapshot in Jpeg format of the sagittal view. The user is prompted for a file name.
• Capture 3D View - Create a snapshot in Jpeg format of the 3D view. The user is prompted for a file name.
• 3D View Volume Rendering - Enable 3D volume rendering in the 3D view. By default three orthogonal slice views are shown in 3D. Hardware acceleration allows this to work in real time for 256x256x256 size datasets. On hardware that is not accelerated, this will be very slow.
• Show Clip Cube - Allows the user to define cutting planes for the volume rendering
• Volume Shading
• Volume Rendering Type - Select the type of volume rendering
  • Texture mapping
  • Ray cast
• Volume Raycast Function - Function used for ray cast based volume rendering:
  • Composite
  • MIP

Window

• Hide Main Panel - Hide/Show the main panel. This is the tabbed panel that can be placed on either the right or left hand side of the GUI.
• Show Bottom Panel - Hide/Show the bottom panel. This panel is currently not used in BRAINSTracer.
• Toolbars - No optional toolbars have yet been defined for BRAINSTracer
• Error Log - Hide/Show the Error log dialog box. This can be used to diagnosis errors in loading of data.
• TCL Interactor - Display the TCL command prompt that can be used for scripting.

Traces

• Axial - Manipulation of the traces for the current slice. Currently the user can only delete traces on the current slice.
• Coronal- Manipulation of the traces for the current slice. Currently the user can only delete traces on the current slice.
• Sagittal- Manipulation of the traces for the current slice. Currently the user can only delete traces on the current slice.

Points

• Add Point Set
• Load Point Set
• Delete Point Set

Options

• Surface Generation - Display the surface generation parameters. This includes
  • Anti-aliasing filter - RMS Error
  • Anti-aliasing filter - Number of Iterations
  • Sinc Smoothing - Number of iterations
  • Decimation factor - Percent of vertices to retain

Modules

• Load BRAINS - Load the BRAINS TCL libraries including ITK. This will allow the user to use the BRAINS command line for processing of data and results can be displayed in the viewer. it will also bring up the TCL Interactor dialog box.
• Scan Modules - Scan for command line modules that can be run interactively
• Available Modules - List of available modules. Selecting a module will bring up the user interface in the Main Panel in a new tab.
• Angle Tool - Turn on the angle widget tool in the specified view. Measurements can be saved to the Results tab
• Distance Tool - Turn on the distance widget tool in the specified view. Measurements can be saved to the Results tab

Help

• Keyboard Shortcuts
• About

Viewer Hot Keys

• f - Place the cursor location into the center of the viewer
• i - Toggle linear versus nearest neighbor resampling of images
• r - Reset the image viewer including window/level, zoom, and center
• d - Toggle on/off distance tool

Viewer Mouse Interaction

• Left - Adjust cursor location
• Left+ Motion - Change slice location
• Middle - Window/Level
• Right - Adjust zoom
• Right+Crtl - Context based pop-up menu

Trace Interaction

• Delete - Delete the selected point
• Left - Place new spline point or adjust spline point location
• Middle - Translate the trace position in plane when point selected