Slicer3 for developers – S.Pujol -1- National Alliance for Medical Image Computing Slicer3 Course for developers Sonia Pujol, Ph.D. Surgical Planning Laboratory Harvard Medical School

Slicer3 for developers – S.Pujol -2- National Alliance for Medical Image Computing Material This course requires a user compiled version of the Slicer3 software and the training dataset accessible at the following locations: Slicer 3 Software and building instructions HelloWorld.zip archive Disclaimer It is the responsibility of the user of 3DSlicer to comply with both the terms of the license and with the applicable laws, regulations and rules.

Slicer3 for developers – S.Pujol -3- National Alliance for Medical Image Computing Learning objective Following this tutorial, you’ll be able 1)to plug-in an external program into Slicer3 2)to implement an image filter and to run the analysis from Slicer3 3)to write and run a test using the CTest tool

Slicer3 for developers – S.Pujol -4- National Alliance for Medical Image Computing Overview Part A: integration of the HelloWorld program into Slicer3 Part B: implementation of a Discrete Gaussian filter within the HelloWorld module Part C: implementation of a test for the HelloWorld module

Slicer3 for developers – S.Pujol -5- National Alliance for Medical Image Computing Part A: Integrating an executable to Slicer3

Slicer3 for developers – S.Pujol -6- National Alliance for Medical Image Computing Slicer3 Execution Model This course is based on the Execution Model which provides a mechanism for incorporating command line programs as Slicer modules. The Slicer modules are described using XML files which are used to generate the C++ command line code and the Graphical User Interface (GUI). Execution Model URL

Slicer3 for developers – S.Pujol -7- National Alliance for Medical Image Computing HelloWorld_CourseMaterial.tgz archive unzip HelloWorld.zip spgr.* (124 SPGR images) HelloWorld.cxx (application) HelloWorld.xml (Execution Model)

Slicer3 for developers – S.Pujol -8- National Alliance for Medical Image Computing HelloWorld.xml Demonstration Hello World Slicer Developer Example 1.0 Sonia Pujol, Ph.D. 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 EB Input/Output Input/output parameters helloWorldInputVolume Input Volume input 0 None Input volume helloWorldOutputVolume Output Volume output 1 Output filtered Module Description Module Parameters

Slicer3 for developers – S.Pujol -9- National Alliance for Medical Image Computing Module Description Demonstration Hello World Slicer Developer Example 1.0 Sonia Pujol, Ph.D. 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 EB

Slicer3 for developers – S.Pujol -10- National Alliance for Medical Image Computing Module Parameters Input/Output Input/output parameters helloWorldInputVolume Input Volume input 0 None Input volume helloWorldOutputVolume Output Volume output 1 None Output filtered Input Volume Output Volume

Slicer3 for developers – S.Pujol -11- National Alliance for Medical Image Computing # include int main(int argc, char * argv []) { std::cout<< “Hello World !”<<std::endl; return 0 ; } Modifying the source code

Slicer3 for developers – S.Pujol -12- National Alliance for Medical Image Computing Modifying the source code # include #include “HelloWorldCLP.h” int main(int argc, char * argv []) { PARSE_ARGS; std::cout<< “Hello World !”<<std::endl; return EXIT_SUCCESS ; }

Slicer3 for developers – S.Pujol -13- National Alliance for Medical Image Computing Slicer architecture Applications Base CMake Libs Modules Resources Scripts Testing.svn Utilities Slicer3 Slicer3-build Slicer3-lib

Slicer3 for developers – S.Pujol -14- National Alliance for Medical Image Computing Slicer architecture Applications Base CMake Libs Modules Resources Scripts Testing.svn Utilities Slicer3 CLI Copy the files HelloWorld.cxx HelloWorld.xml into the directory Slicer3\Applications\CLI

Slicer3 for developers – S.Pujol -15- National Alliance for Medical Image Computing Slicer architecture Applications Base CMake Libs Modules Resources Scripts Testing.svn Utilities Slicer3 CLI Open the file CMakeLists.txt located in the directory Slicer3/Applications/CLI

Slicer3 for developers – S.Pujol -16- National Alliance for Medical Image Computing Editing CMakeLists.txt Add the following lines to CMakeLists.txt located in Slicer3/Applications/CLI (above the SUBDIRS lines): SET (CLP HelloWorld) SET (${CLP}_SOURCE ${CLP}.cxx) GENERATECLP(${CLP}_SOURCE ${CLP}.xml) GENERATECLP generates the file HelloWorldCLP.h for parsing the command line arguments. ‘CLP’ means Command Line Processing

Slicer3 for developers – S.Pujol -17- National Alliance for Medical Image Computing Editing CMakeLists.txt ADD_EXECUTABLE creates the stand-alone executable HelloWorld.exe that can be run from a command line. Add the following lines to CMakeLists.txt located in Slicer3/Applications/CLI after the ‘GENERATECLP’ line you just added ADD_EXECUTABLE(${CLP} ${${CLP}_SOURCE}) TARGET_LINK_LIBRARIES (${CLP} ITKIO ITKBasicFilters ITKCommon)

Slicer3 for developers – S.Pujol -18- National Alliance for Medical Image Computing Building Slicer3 Open the solution Slicer3.sln located in Slicer3-build/ and build Slicer3 Windows

Slicer3 for developers – S.Pujol -19- National Alliance for Medical Image Computing Building Slicer3 Close the solution Slicer3.sln and re-load it again in the building environment

Slicer3 for developers – S.Pujol -20- National Alliance for Medical Image Computing Building Slicer3 Select the solution HelloWorld, and launch ‘BuildHelloWorld’ Windows

Slicer3 for developers – S.Pujol -21- National Alliance for Medical Image Computing Building Slicer3 Mac and Linux instructions Go in the directory /CLI: cd Slicer3-build/Applications/CLI Run make to build ‘HelloWorld’

Slicer3 for developers – S.Pujol -22- National Alliance for Medical Image Computing Launch Slicer3 Launch the executable located in /Slicer3-build: on Windows:./Slicer3.exe on Linux/Mac:./Slicer3

Slicer3 for developers – S.Pujol -23- National Alliance for Medical Image Computing HelloWorld module in Slicer3 Select the category ‘Demonstration’, and the module ‘HelloWorld’ in the Modules menu

Slicer3 for developers – S.Pujol -24- National Alliance for Medical Image Computing HelloWorld Module in Slicer3 The program ‘HelloWorld’ is now integrated into Slicer3

Slicer3 for developers – S.Pujol -25- National Alliance for Medical Image Computing Part B: Implementing an image filter

Slicer3 for developers – S.Pujol -26- National Alliance for Medical Image Computing Goal In this section, we’ll implement a Gaussian smoothing operator to ‘blur’ the images and remove detail and noise. This implementation will allow us to run the filter on volumes loaded in Slicer, and to integrate the resulting filtered volumes as MRML nodes.

Slicer3 for developers – S.Pujol -27- National Alliance for Medical Image Computing Discrete Gaussian Filter Input volumeOutput volume Variance Discrete Gaussian Filter

Slicer3 for developers – S.Pujol -28- National Alliance for Medical Image Computing Implementing Input/Output functionalities Add the following lines to HelloWorld.cxx #include #include "HelloWorldCLP.h" int main(int argc, char * argv []) { PARSE_ARGS; std::cout << "Hello World!" << std::endl; return EXIT_SUCCESS ; } #include "itkImage.h" #include "itkImageFileReader.h" #include "itkImageFileWriter.h "

Slicer3 for developers – S.Pujol -29- National Alliance for Medical Image Computing int main ( int argc, char * argv[]){ PARSE_ARGS; std::cout << "Hello World!" << std::endl; typedef itk::Image ImageType; typedef itk::ImageFileReader ReaderType; typedef itk::ImageFileWriter WriterType; ReaderType::Pointer reader = ReaderType::New(); WriterType::Pointer writer = WriterType::New(); return EXIT_SUCCESS; } Implementing Input/Output functionalities Add the following command lines to set-up the reading and writing functionalities in the ‘main’ procedure in HelloWorld.cxx

Slicer3 for developers – S.Pujol -30- National Alliance for Medical Image Computing int main ( int argc, char * argv[]){ PARSE_ARGS; std::cout << "Hello World!" << std::endl; typedef itk::Image ImageType; typedef itk::ImageFileReader ReaderType; typedef itk::ImageFileWriter WriterType; ReaderType::Pointer reader = ReaderType::New(); WriterType::Pointer writer = WriterType::New(); reader->SetFileName( helloWorldInputVolume.c_str() ); writer->SetFileName (helloWorldOutputVolume.c_str()); return EXIT_SUCCESS; } Implementing Input/Output functionalities Set the input and output volumes parameters defined in HelloWorld.xml

Slicer3 for developers – S.Pujol -31- National Alliance for Medical Image Computing Demonstration Hello World Slicer Developer Example 1.0 Sonia Pujol 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 EB Input/Output Input/output parameters …. Discrete Gaussian Parameters Parameters of the Discrete Gaussian Filter HelloWorld.xml Add a new parameter group to HelloWorld.xml

Slicer3 for developers – S.Pujol -32- National Alliance for Medical Image Computing Adding a new parameter to HelloWorld.xml Discrete Gaussian Parameters Parameters of the Discrete Gaussian Filter variance --variance Variance ( width of the filter kernel) Variance 0.5 Add the parameter ‘variance’ which corresponds to the variance of the Discrete Gaussian Filter to HelloWorld.xml

Slicer3 for developers – S.Pujol -33- National Alliance for Medical Image Computing #include "itkDiscreteGaussianImageFilter.h" int main ( int argc, char * argv[]){ PARSE_ARGS; std::cout << "Hello World!" << std::endl; typedef itk::Image ImageType; typedef itk::ImageFileReader ReaderType; typedef itk::ImageFileWriter WriterType; ReaderType::Pointer reader = ReaderType::New(); WriterType::Pointer writer = WriterType::New(); reader->SetFileName( helloWorldInputVolume.c_str() ); writer->SetFileName(helloWorldOutputVolume.c_str()); typedef itk::DiscreteGaussianImageFilter FilterType; FilterType::Pointer filter = FilterType::New(); return EXIT_SUCCESS;} Implementing the filter in HelloWorld.cxx Implement the filter itk::DiscreteGaussianImageFilter

Slicer3 for developers – S.Pujol -34- National Alliance for Medical Image Computing Implementing the filter in HelloWorld.cxx Add the following lines for the filter execution: try { filter->SetInput(reader->GetOutput()); filter->SetVariance(variance); writer->SetInput(filter->GetOutput()); writer->Update(); } catch (itk::ExceptionObject &excep) { std::cerr << argv[0] << ": exception caught !" << std::endl; return EXIT_FAILURE; }

Slicer3 for developers – S.Pujol -35- National Alliance for Medical Image Computing int main ( int argc, char * argv[]){ PARSE_ARGS; std::cout << "Hello World!" << std::endl; typedef itk::Image ImageType; typedef itk::ImageFileReader ReaderType; typedef itk::ImageFileWriter WriterType; ReaderType::Pointer reader = ReaderType::New(); WriterType::Pointer writer = WriterType::New(); reader->SetFileName( helloWorldInputVolume.c_str() ); writer->SetFileName (helloWorldOutputVolume.c_str()); typedef itk::DiscreteGaussianImageFilter FilterType; FilterType::Pointer filter = FilterType::New(); try { filter->SetInput(reader->GetOutput()); filter->SetVariance(variance); writer->SetInput(filter->GetOutput()); writer->Update();} catch (itk::ExceptionObject &excep){ std::cerr << argv[0] << ": exception caught !" << std::endl; return EXIT_FAILURE;} return EXIT_SUCCESS;} HelloWorld.cxx Re-Compile HelloWorld - Linux and Mac: Type make in Slicer3-build/ - Windows: build Slicer3.sln

Slicer3 for developers – S.Pujol -36- National Alliance for Medical Image Computing Running the Filter Go in File  Add Volume and load the dataset spgr.nrrd

Slicer3 for developers – S.Pujol -37- National Alliance for Medical Image Computing Browse to the Category ‘Demonstration’ in the Modules menu, and select the module ‘HelloWorld’ Running the Filter

Slicer3 for developers – S.Pujol -38- National Alliance for Medical Image Computing Select the input volume ‘spgr.nhdr’, the output volume ‘Create New’. Enter the value ‘0.9’ for the variance and click on Apply Running the Filter

Slicer3 for developers – S.Pujol -39- National Alliance for Medical Image Computing Slicer displays the filtered volume ‘HelloWorldVolume1’. Running the Filter

Slicer3 for developers – S.Pujol -40- National Alliance for Medical Image Computing Select the Foreground volume ‘spgr.nhdr’ and fade between the Background and Foreground images to visualize the effect of the filter. Running the Filter

Slicer3 for developers – S.Pujol -41- National Alliance for Medical Image Computing Part C: Testing

Slicer3 for developers – S.Pujol -42- National Alliance for Medical Image Computing Goal This section describes a simple example for testing that the ‘help’ functionality of our newly implemented module ‘HelloWorld’ works correctly. CTest is a core element of Slicer3’s quality control system for software development.

Slicer3 for developers – S.Pujol -43- National Alliance for Medical Image Computing HelloWorld Test 1 The goal of ‘HelloWorldTest1’ is to test the following command:./HelloWorld --help To implement this test, add the following line to the CMakeLists.txt file located in the directory: Slicer3\Applications\CLI\CMakeLists.txt IF (WIN32) ADD_TEST(HelloWorldTest1 ${EXECUTABLE_OUTPUT_PATH}/${CMAKE_BUILD_TYPE}/${CLP} --help) ELSE(WIN32) ADD_TEST(HelloWorldTest1 ${EXECUTABLE_OUTPUT_PATH}/${CLP} --help) ENDIF (WIN32)

Slicer3 for developers – S.Pujol -44- National Alliance for Medical Image Computing CMakeLists.txt Run make on Linux/Mac or re-build Slicer3.sln on Windows

Slicer3 for developers – S.Pujol -45- National Alliance for Medical Image Computing HelloWorldTest1 Go in the /Slicer3-build directory, and type the following command to run the test../Slicer3-lib/CMake-build/bin/ctest.exe -R HelloWorldTest1

Slicer3 for developers – S.Pujol -46- National Alliance for Medical Image Computing HelloWorldTest1 When the module successfully passes the test, the output below is generated:

Slicer3 for developers – S.Pujol -47- National Alliance for Medical Image Computing Conclusion This course described functionalities for integrating, developing and testing external program within Slicer3. The Execution Model of Slicer3 provides a simple mechanism for incorporating command line programs as Slicer modules.