IGSTK:Tutorial

From IGSTK
Jump to: navigation, search

Preface

This tutorial provides an example-driven description of how the Image-Guided Software Toolkit (IGSTK) is used to develop image-guided surgical applications. IGSTK is an open source project supporting the development of robust software for image-guided surgical applications. IGSTK relies on open-source toolkits ITK and VTK. ITK provides image processing, segmentation and registration functionalites and VTK provides visualization functionalities. For graphical and user interface functionalities, FLTK or other GUI toolkit can be used. IGSTK is built using CMake and nightly tested using DART, on common operating systems such as Linux, Windows and MacOs (http://public.kitware.com/dashboard.php?name=igstk)

How to download and build the toolkit

Before building IGSTK, you must download, configure and build VTK and ITK that are required to build IGSTK. For GUI functionalities, you might want to download FLTK or any other GUI toolkit. The example applications and test programs that come with the toolkit use FLTK. It is very important to make sure that you use the appropriate versions of those toolkits since that will ensure that your the code is coherent with the current version of IGSTK. For detail information on how to build different versions of IGSTK, please refer to the Wiki page http://public.kitware.com/IGSTKWIKI/index.php/How_to_build_IGSTK

IGSTK Components

IGSTK has several high-level components. To ensure safety and robustness, state machine design pattern is incorporated into these components. State machine pattern ensures that a component is always in a valid state which can guarantee repeatable and deterministic behavior. The key components available in IGSTK are listed below.

  1. Image I/O classes: These classes provide the ability to read and display medical images in DICOM format.
  2. Viewer classes: These classes are used for presenting results and displays to the physician. An internal pulse generator is used to update the scene at specified refresh rate to keep the visual information up-to-date.
  3. SpatialObject and SpatialObjectRepresentation classes: SpatialObjects classes model physical objects including image data and simple geometrical shapes such as anatomical structures and surgical devices, while SpatialObjectRepresentations classes are responsible for displaying its associate SpatialObject in the scene. IGSTK has a variety of SpatialObjects and corresponding SpatialObjectsRepresentations, including basic shapes (Cone, Cylinder, Ellipsoid and so on), ImageSpatialObject, UltrasoundProbeObject, and GroupObject to make composite SpatialObjects.
  4. Tracker classes: These classes are abstraction of tracking devices. They communicate with hardware and store data including position, orientation, and other relevant information pertaining to tracked surgical tools. The IGTSK Tracker component is developed based on code donated by Atamai Inc. and warped with state machine. The internals of the Tracker require a separate thread to communicate with tracking hardware at an acceptable frequency. An pulse generator inside the class is used to automatically update the location information of the tracked device with expiration time and propagate this changes to SpatialObjects. IGSTK now supports NDI AURORA, POLARIS, and VICRA trackers (Northern Digital Inc., Waterloo, Canada) and Flock of Birds tracker (Ascension Technology Corporation, Burlington, VT USA). The full list of supported devices can be found at Supported Tracking System.
  5. Registration classes: IGSTK provides the capability for a rigid body landmark-based registration. In addition, IGSTK has a registration error estimation class which predicts target registration error given the target location with respect to the landmarks, the landmarks configuration and landmarks registration error.
  6. Calibration classes: The calibration component of IGSTK provides a class which calculates the calibration transform from the tracker's sensor/marker reported by the tracking system to the pivot position of the pointer. Moreover, this component provides a principal axis calibration class which calibrates the tracker tools and get the transform from the initial tracked tool's orietatnions which is defined by the principal axis and plane normal to the user specified orientation.

A Hello World Application

HelloWorld application

This example illustrates the minimal application that can be written using IGSTK. The application uses three main components. They are the View, the SpatialObjects and the Tracker. The View is the visualization window that is presented to the user in the graphical user interface (GUI) of the application. The SpatialObjects are used for representing geometrical shapes in the scene of the surgical room. In this simplified example, we only use them to represent a cylinder and a sphere. The Tracker is the device that provides position and orientation information about some of the objects in the scene. A Tracker can track multiple objects, and each one of them is referred as a TrackerTool. In this minimal example we use a MouseTracker that is a class intended mainly for demonstration and debugging purposes. This tracker get the values of positions from the position of the mouse on the screen. The position values are then passed to the sphere object in the scene.

Given that this application has a graphical user interface, we use FLTK in order to define a very simple GUI. FLTK stores the description of the interface in files with extension .fl. The FLTK tool takes this file and uses it for generating C code in two files. One header file with extension .h, and an implementation file with extension .cxx. The FLTK file for the description of the helloworld application contains the following main code fragments.

FLTK main window is declared and labeled as follows.

   Fl_Window MainWindow {
     label {IGSTK: HelloWorld Example} open
     xywh {619 249 515 375} type Double resizable visible
   } 

A display window is instantiated as follows

     Fl_Box Display {
       label Display
       xywh {5 5 505 330} box FLAT_BOX color 0 labelcolor 7
       code0 {\#include <igstkView3D.h>}
       class {igstk::View3D}
     }

A button to activate mouse tracking is inserted and the callback function for this button (SetTracking) is invoked

     Fl_Light_Button TrackingBt {
       label Tracking
       callback {this->SetTracking(o->value());}
       xywh {5 345 85 25} labelsize 11
       code0 {\#include "igstkTracker.h"}
     }

The application starts tracking the mouse motion after this buttion is clicked. A button to quit the application and its associated callback function is invoked as follows.

     Fl_Button {} {
       label Quit
       callback {this->Quit()}
       xywh {421 345 90 25}
     }
  

After defining the necessary buttons and display window, the callback functions for the buttons are defined. In this callback functions, the relevant IGSTK component methods are invoked.

 Function {SetTracking( bool tracking )} {return_type {virtual void}
 } {
   code {if( tracking )
 {
 this->m_Tracker->StartTracking();
 }
else
 {
 this->m_Tracker->StopTracking();
 }} {}
 }
 Function {~HelloWorldGUI()} {return_type virtual
 } {}
 Function {SetTracker( TrackerType * tracker)} {return_type {virtual void}
 } {
   code {this->m_Tracker = tracker;} {}
 }
 Function {HasQuitted()} {return_type {virtual bool}
 } {
   code {return this->quit;} {}
 }
} 

In order to use this GUI in the main program of our application we must include the header file generated by fluid.

This is done in the following line.

   include "HelloWorldGUI.h"

The geometrical description of the Cylinder and the Sphere in the scene are managed by SpatialObjects. For this purpose we need the two classes "EllipsoidObject" and "CylinderObject". Their two header files are included below.


   include "igstkEllipsoidObject.h"
   include "igstkCylinderObject.h"

The visual representation of SpatialObjects in the visualization window is done with Representation objects. Every SpatialObject has one or several representation objects associated with it. We include now the header files of the "EllipsoidObjectRepresentation" and CylinderObjectRepresentation.


   include "igstkEllipsoidObjectRepresentation.h"
   include "igstkCylinderObjectRepresentation.h"

As we mention earlier, the tracker in this minimal application is represented by a "MouseTracker". This class provides the same interface of a real tracking device but with the convenience of running based on the movement of the mouse in the screen. The header file of this class is included below.

   include "igstkMouseTracker.h"

Since image guided surgery applications are used in a critical environment, it is quite important to be able to trace the behavior of the application during the intervention. For this purpose IGSTK uses a "Logger" class and some helpers. The logger is a class that receives messages from IGSTK classes and forward those messages to LoggerOutput classes. Typical logger output classes are the standard output, a file and a popup window. The Logger classes and their helpers are taken from the Insight Toolkit (ITK).


 include "itkLogger.h"
 include "itkStdStreamLogOutput.h"

We are now ready for writing the code of the actual application. The first IGSTK command to be invoked in an application is the one that initialize the parameters of the clock. Timing is critical for all the operations performed in an IGS application. Timing signals make possible to synchronize the operation of different components and to ensure that the scene that is rendered on the screen actually displays a consistent state of the environment on the operating room.

igstk::RealTimeClock::Initialize();


First, we instantiate the GUI application.

  HelloWorldGUI * m_GUI = new HelloWorldGUI();
  m_GUI->MainWindow->show();

Next, we instantiate the ellipsoidal spatial object that we will be attaching to the tracker as follows.

 igstk::EllipsoidObject::Pointer ellipsoid = igstk::EllipsoidObject::New();

The ellipsoid radius can be set to one in all dimensions ( X,Y and Z) using the SetRadius member function as follows.

 ellipsoid->SetRadius(1,1,1);

To visualize the ellipsoid spatial object, an object representation class is created and the ellipsoid spatial object is added to it.

 igstk::EllipsoidObjectRepresentation::Pointer ellipsoidRepresentation = 
 igstk::EllipsoidObjectRepresentation::New();
 ellipsoidRepresentation->RequestSetEllipsoidObject( ellipsoid );
 ellipsoidRepresentation->SetColor(0.0,1.0,0.0);
 ellipsoidRepresentation->SetOpacity(1.0);

Similarly, a cylinder spatial object and cylinder spatial object representation object are instantiated as follows.

 igstk::CylinderObject::Pointer cylinder = igstk::CylinderObject::New();
 cylinder->SetRadius(0.1);
 cylinder->SetHeight(3);
 igstk::CylinderObjectRepresentation::Pointer cylinderRepresentation =      
 igstk::CylinderObjectRepresentation::New();
 cylinderRepresentation->RequestSetCylinderObject( cylinder );
 cylinderRepresentation->SetColor(1.0,0.0,0.0);
 cylinderRepresentation->SetOpacity(1.0);
 

Next, the spatial objects are added to the view by invoking RequestAddObject funtion.

 m_GUI->Display->RequestAddObject( ellipsoidRepresentation );
 m_GUI->Display->RequestAddObject( cylinderRepresentation );


To enable vtkWindow interactions, "RequestEnableInteractions" function is invoked

 m_GUI->Display->RequestEnableInteractions();

To track the mouse location, MouseTracker is initialized as follows

 igstk::MouseTracker::Pointer tracker = igstk::MouseTracker::New();

Next, the tracker is opened, initialized and the ellipsoid object is attached to it

 tracker->Open();
 tracker->Initialize();
 tracker->AttachObjectToTrackerTool( toolPort, toolNumber, ellipsoid );

The GUI application SetTracker method is invoked using the defined mouse tracker as an argument.

 m_GUI->SetTracker( tracker );

A logger is setup as follows

 itk::Logger::Pointer logger = itk::Logger::New();
 itk::StdStreamLogOutput::Pointer logOutput = itk::StdStreamLogOutput::New();
 itk::StdStreamLogOutput::Pointer fileOutput = itk::StdStreamLogOutput::New();
 
 std::ofstream ofs( "log.txt" );
 fileOutput->SetStream( ofs );
 logger->AddLogOutput( logOutput );
 
 m_GUI->Display->SetLogger( logger ); 
 tracker->SetLogger( logger );


Setup the frequency for refreshing the view

 m_GUI->Display->RequestSetRefreshRate( 60 ); // 60 Hz
 m_GUI->Display->RequestStart();


Next, the application is run until the "Quit" button is clicked.

 while( !m_GUI->HasQuitted() )
   {
   Fl::wait(0.001);
   igstk::PulseGenerator::CheckTimeouts();
   }

In this simple application, when the mouse is moved, the ellipsoid spatial object moves as well tracking the position of the mouse. The full source code for this application is found in Examples/HelloWorld sub-directory.

Documentation

Class hierarchy, API and list of classes in IGSTK can be found in

http://public.kitware.com/IGSTK/NightlyDoc/

Mailing List

If you have specific questions on how to use any component of the IGSTK toolkit or if you need help in designing an image guided surgery application using IGSTK, post your questions to the IGSTK users mailing list. To join this mailing list, use the following link

http://www.itk.org/mailman/listinfo/igstk-users