SimpleITK/Tutorials/MICCAI2015: Difference between revisions
No edit summary |
|||
(39 intermediate revisions by 3 users not shown) | |||
Line 1: | Line 1: | ||
__NOTOC__ | __NOTOC__ | ||
<!--We do not want the default TOC automatically created from the headings, | <!--We do not want the default TOC automatically created from the headings, hence __NOTOC__--> | ||
[[File:MiccaiBanner.jpg | 1000px | center | link=http://www.miccai2015.org/]] | [[File:MiccaiBanner.jpg | 1000px | center | link=http://www.miccai2015.org/]] | ||
Line 6: | Line 6: | ||
<center><font size="5">Monday October 5'th 2015</font></center> | <center><font size="5">Monday October 5'th 2015</font></center> | ||
==<font color="red">After The Tutorial</font>== | |||
All of the tutorial material, including slide's from Dr. Tustison's talk on registration, is available on the github repository: | |||
<nowiki>https://github.com/InsightSoftwareConsortium/SimpleITKTutorialMICCAI2015.git</nowiki> | |||
To continue exploring SimpleITK in general and registration in particular, additional notebooks are available from SimpleITK's main notebook repository: | |||
<nowiki>https://github.com/InsightSoftwareConsortium/SimpleITK-Notebooks</nowiki> | |||
==<font color="red">Before The Tutorial</font>== | |||
* Before the tutorial you will have to either install a Python environment as described [[#Three paths forward |below]] or Docker (lightweight virtual machine). | |||
* You will then need to download the IPython notebooks and data: | |||
: Download notebooks from our git repository: get a [https://github.com/InsightSoftwareConsortium/SimpleITKTutorialMICCAI2015/archive/master.zip zip archive] or, preferably, | |||
git clone <nowiki>https://github.com/InsightSoftwareConsortium/SimpleITKTutorialMICCAI2015.git</nowiki> | |||
: Download the data; it is not a small download: get a [http://midas3.kitware.com/midas/download/item/318750/Data.zip zip archive] or if you already have Python installed, in the directory containing the notebooks, run the following command: | |||
python downloaddata.py ./Data ./Data/manifest.json | |||
==Who Should Attend== | ==Who Should Attend== | ||
Line 35: | Line 56: | ||
We '''do not''' require knowledge of C++ templates, CMake or how to compile code. | We '''do not''' require knowledge of C++ templates, CMake or how to compile code. | ||
We '''do require''' basic knowledge of the Python programming language. If you are not familiar with Python but are well versed in MATLAB, Java, C++... then don't worry. You will be up to speed with a minimal investment of time. Please read or skim through the [https://docs.python.org/ | We '''do require''' basic knowledge of the Python programming language. If you are not familiar with Python but are well versed in MATLAB, Java, C++... then don't worry. You will be up to speed with a minimal investment of time. Please read or skim through the [https://docs.python.org/3/tutorial/index.html official Python language tutorial] or any of the tutorials listed [https://wiki.python.org/moin/BeginnersGuide/Programmers here]. | ||
You will need to bring your laptop (don't forget the adapter plug for your power cord if you are coming from outside of Europe). | You will need to bring your laptop (don't forget the adapter plug for your power cord if you are coming from outside of Europe). | ||
The minimal installation of | The minimal installation of Python will have to include the following packages: (1) ipython; (2) numpy; (3) matplotlib; (4) SimpleITK | ||
===Three paths forward=== | |||
= | <font color="red">If you selected to go with your own Python installation</font>, options 1 and 2, then you will have to download the IPython notebooks and data as described [[#Before The Tutorial |above]]. | ||
This path installs the minimal set of required components ('''we assume your system has a working compiler'''): | ====1. Manual ==== | ||
This path installs the minimal set of required components. It is only recommended if you are familiar with Python and Python package management ('''we assume your system has a working compiler'''): | |||
<ol> | <ol> | ||
<li value="0"> [https://www.python.org/downloads/ Download] and install Python version 2.7.9.</li> | <li value="0"> Get Python ( version 3.4 recommended, 2.7 compatible ) | ||
[https://www.python.org/downloads/ Download] and install Python version 2.7.9.</li> | |||
</ol> | </ol> | ||
From the command line: | From the command line: | ||
# if pip is not installed: | # if pip is not installed see [https://pip.pypa.io/en/latest/installing/ pip]'s installation instructions. | ||
# (sudo) pip install virtualenv | # (sudo) pip install virtualenv | ||
# virtualenv sitkpy --no-site-packages | # virtualenv sitkpy --no-site-packages | ||
# unix/mac: source sitkpy/bin/activate | # <u>unix/mac</u>: source sitkpy/bin/activate <br> <u>win</u>: sitkpy\Scripts\activate | ||
# pip install ipython[all] | # pip install -U pip | ||
# pip install 'ipython[all]' numpy matplotlib ipywidgets | |||
# pip install --trusted-host www.simpleitk.org -f <nowiki>http://www.simpleitk.org/SimpleITK/resources/software.html</nowiki> --timeout 30 SimpleITK (for other options see [http://www.itk.org/Wiki/SimpleITK/GettingStarted here]) | |||
# pip install -f http://www.simpleitk.org/SimpleITK/resources/software.html SimpleITK (for other options see [http://www.itk.org/Wiki/SimpleITK/GettingStarted here]) | |||
Note that you may need to install some matplotlib dependencies if they are not already on your system (sudo apt-get install libpng-dev, | Note that you may need to install some matplotlib dependencies if they are not already on your system (sudo apt-get install libpng-dev, | ||
sudo apt-get install libfreetype6-dev). You only need to do this if you receive corresponding error messages when running pip install. | sudo apt-get install libfreetype6-dev). You only need to do this if you receive corresponding error messages when running pip install. | ||
===Disk Space is Cheap=== | ====2. Disk Space is Cheap==== | ||
This path installs a full fledged scientific computing environment. Install (free) Python distributions for scientific and numeric computing from commercial vendors, either [http://continuum.io Continuum’s] Anaconda or [https://store.enthought.com/ Enthought’s] Canopy. If you want the full list of packages | This path installs a full fledged scientific computing environment. Install (free) Python distributions for scientific and numeric computing from commercial vendors, either [http://continuum.io Continuum’s] Anaconda or [https://store.enthought.com/ Enthought’s] Canopy. If you want the full list of packages that come with each of these distributions simply follow these links:[http://docs.continuum.io/anaconda/pkg-docs.html Anaconda], [https://www.enthought.com/products/canopy/package-index/ Canopy]. | ||
{|cellspacing="40" | {|cellspacing="40" | ||
| <font size="3">Anaconda</font> | | <font size="3">Anaconda</font> | ||
Line 74: | Line 97: | ||
From the command line: | From the command line: | ||
#conda update conda | #conda update conda anaconda | ||
#conda create -n sitkpy -c <nowiki>https://conda.binstar.org/simpleitk</nowiki> python=3.4 anaconda SimpleITK ipywidgets | |||
#conda create -n sitkpy anaconda | #<u>unix/mac</u>: source activate sitkpy <br> <u>win</u>: activate sitkpy | ||
#unix/mac: source activate sitkpy | |||
|| <font size="3">Canopy</font> | |||
|| <font size="3">Canopy ( Known to work on Windows )</font> | |||
<ol> | <ol> | ||
Line 89: | Line 111: | ||
From the command line (cd to the directory where canopy is installed): | From the command line (cd to the directory where canopy is installed): | ||
#User/bin/canopy_cli venv -s sitkpy | #User/bin/canopy_cli venv -s sitkpy | ||
#unix/mac: source sitkpy/bin/activate | #<u>unix/mac</u>: source sitkpy/bin/activate <br> <u>win</u>: sitkpy\Scripts\activate | ||
#download the wheel from SourceForge as described [[SimpleITK/GettingStarted | here]] | #download the wheel from SourceForge as described [[SimpleITK/GettingStarted | here]] | ||
#pip install wheel_file_name | #pip install wheel_file_name | ||
|} | |} | ||
====3. Reproducible Environment==== | |||
This path uses a [http://nbviewer.ipython.org/format/slides/github/thewtex/scipy-2015-docker-presentation/blob/master/Docker_for_Improved_Reproducibility_of_Scientific_Python_Analyses.ipynb#/ reproducible computational environment] that will work the same way across platforms and over time. For efficient use of disk, memory, and cpu, rapid execution, and easy distribution, we will use [https://www.docker.com/ Docker] instead of a virtual machine. | |||
<ol> | |||
<li value="0">[http://docs.docker.com/installation/ Install Docker] </li> | |||
</ol> | |||
* ''Windows 10'': uninstall VirtualBox, if installed, and use [http://midas3.kitware.com/midas/download/item/318751/DockerToolbox-1.8.1a-windows-10-test.exe this installer]. | |||
# Obtain the SimpleITK Notebooks Docker image. | |||
## If you have a network connection, run | |||
##: docker pull insighttoolkit/simpleitk-notebooks:2015-miccai | |||
## If you have the USB drive from the conference: | |||
##: docker load -i SimpleITKNotebooksDockerImage.tar | |||
# <font color="red">Even if you encountered errors in the previous step</font>, execute '''./run.sh''' in the SimpleITKTutorialMICCAI2015 repository. | |||
===Additional Programs=== | ===Additional Programs=== | ||
In some SimpleITK notebooks we use an external viewer to look at our images. The default viewer is [http://imagej. | In some SimpleITK notebooks we use an external viewer to look at our images. The default viewer is [http://imagej.nih.gov/ij/ ImageJ]. If you do not have any viewer installed, please install ImageJ. | ||
If you already have another viewer such as ITK-SNAP or Slicer and do not want to install ImageJ, you only need to set an environment variable SITK_SHOW_COMMAND to | If you already have another viewer such as ITK-SNAP or Slicer and do not want to install ImageJ, you only need to set an environment variable SITK_SHOW_COMMAND to | ||
Line 103: | Line 141: | ||
%env SITK_SHOW_COMMAND /Applications/ITK-SNAP.app/Contents/MacOS/ITK-SNAP | %env SITK_SHOW_COMMAND /Applications/ITK-SNAP.app/Contents/MacOS/ITK-SNAP | ||
== | == Program == | ||
* 8:30am: Setup and introduction. | * 8:30am: Setup and introduction [Matthew McCormick and Hans Johnson]. | ||
* 9:00am: SimpleITK basics: loading data, image access, image transformations, image resampling, basic filters. | * 9:00am: SimpleITK basics: loading data, image access, image transformations, image resampling, basic filters [Matthew McCormick]. | ||
* 10:00am: Coffee break. | * 10:00am: The ITKv4 registration framework [Nick Tustison and Brian Avants]. | ||
* 10: | * 10:30am: Coffee break. | ||
* 11:30am: Registration 2: nonrigid registration - Nonrigid registration, Bspline and displacement field transformations. | * 10:45am: Registration 1: composite transform, transformation initialization, embedded multi-resolution, scale parameter estimation, optimization termination criteria [Ziv Yaniv]. | ||
* 11:30am: Registration 2: nonrigid registration - Nonrigid registration, Bspline and displacement field transformations [Ziv Yaniv]. | |||
* 12:30pm: Lunch. | * 12:30pm: Lunch. | ||
==A Taste of What's to Come: SimpleITK Registration, It's Really Simple== | ==A Taste of What's to Come: SimpleITK Registration, It's Really Simple== |
Latest revision as of 19:44, 5 October 2015
After The Tutorial
All of the tutorial material, including slide's from Dr. Tustison's talk on registration, is available on the github repository:
https://github.com/InsightSoftwareConsortium/SimpleITKTutorialMICCAI2015.git
To continue exploring SimpleITK in general and registration in particular, additional notebooks are available from SimpleITK's main notebook repository:
https://github.com/InsightSoftwareConsortium/SimpleITK-Notebooks
Before The Tutorial
- Before the tutorial you will have to either install a Python environment as described below or Docker (lightweight virtual machine).
- You will then need to download the IPython notebooks and data:
- Download notebooks from our git repository: get a zip archive or, preferably,
git clone https://github.com/InsightSoftwareConsortium/SimpleITKTutorialMICCAI2015.git
- Download the data; it is not a small download: get a zip archive or if you already have Python installed, in the directory containing the notebooks, run the following command:
python downloaddata.py ./Data ./Data/manifest.json
Who Should Attend
- Do you want your students to gain practical experience with registration while minimizing their programming load?
- Do you want to easily experiment with various ITK registration configurations, or optimize the settings of a specific registration configuration?
If you answered yes to either of these questions, then this tutorial is for you.
The goal of this half-day tutorial is to introduce students and researchers to SimpleITK’s interface for the ITK version 4 registration framework. SimpleITK is, as the name suggests, a simpler interface to ITK. It provides a procedural interface and bindings to several interpreted languages, facilitating fast experimentation with ITK algorithms. In this tutorial we will use the Python programming language and the IPython Notebook interactive environment to explore the various features of the ITKv4 registration framework. Key features presented include: uniform treatment of linear, deformable and composite transformations, embedded multi-resolution registration and self calibrating optimizers. Using a hands on approach, participants will experiment with various registration tasks, learning how to use SimpleITK in order to gain insight into the effects of registration component selection and parameter settings on accuracy and running time of ITK based registration algorithms.
Organizers
![]() |
![]() |
![]() |
![]() |
![]() |
- Brian Avants, University of Pennsylvania.
- Hans Johnson, University of Iowa.
- Bradley Lowekamp, Medical Science & Computing and National Institutes of Health.
- Matthew McCormick, Kitware Inc.
- Nick Tustison, University of Virginia.
- Ziv Yaniv, TAJ Technologies Inc. and National Institutes of Health.
Prerequisites
We do not require knowledge of C++ templates, CMake or how to compile code.
We do require basic knowledge of the Python programming language. If you are not familiar with Python but are well versed in MATLAB, Java, C++... then don't worry. You will be up to speed with a minimal investment of time. Please read or skim through the official Python language tutorial or any of the tutorials listed here.
You will need to bring your laptop (don't forget the adapter plug for your power cord if you are coming from outside of Europe).
The minimal installation of Python will have to include the following packages: (1) ipython; (2) numpy; (3) matplotlib; (4) SimpleITK
Three paths forward
If you selected to go with your own Python installation, options 1 and 2, then you will have to download the IPython notebooks and data as described above.
1. Manual
This path installs the minimal set of required components. It is only recommended if you are familiar with Python and Python package management (we assume your system has a working compiler):
- Get Python ( version 3.4 recommended, 2.7 compatible ) Download and install Python version 2.7.9.
From the command line:
- if pip is not installed see pip's installation instructions.
- (sudo) pip install virtualenv
- virtualenv sitkpy --no-site-packages
- unix/mac: source sitkpy/bin/activate
win: sitkpy\Scripts\activate - pip install -U pip
- pip install 'ipython[all]' numpy matplotlib ipywidgets
- pip install --trusted-host www.simpleitk.org -f http://www.simpleitk.org/SimpleITK/resources/software.html --timeout 30 SimpleITK (for other options see here)
Note that you may need to install some matplotlib dependencies if they are not already on your system (sudo apt-get install libpng-dev, sudo apt-get install libfreetype6-dev). You only need to do this if you receive corresponding error messages when running pip install.
2. Disk Space is Cheap
This path installs a full fledged scientific computing environment. Install (free) Python distributions for scientific and numeric computing from commercial vendors, either Continuum’s Anaconda or Enthought’s Canopy. If you want the full list of packages that come with each of these distributions simply follow these links:Anaconda, Canopy.
Anaconda
From the command line:
|
Canopy ( Known to work on Windows )
From the command line (cd to the directory where canopy is installed):
|
3. Reproducible Environment
This path uses a reproducible computational environment that will work the same way across platforms and over time. For efficient use of disk, memory, and cpu, rapid execution, and easy distribution, we will use Docker instead of a virtual machine.
- Windows 10: uninstall VirtualBox, if installed, and use this installer.
- Obtain the SimpleITK Notebooks Docker image.
- If you have a network connection, run
- docker pull insighttoolkit/simpleitk-notebooks:2015-miccai
- If you have the USB drive from the conference:
- docker load -i SimpleITKNotebooksDockerImage.tar
- If you have a network connection, run
- Even if you encountered errors in the previous step, execute ./run.sh in the SimpleITKTutorialMICCAI2015 repository.
Additional Programs
In some SimpleITK notebooks we use an external viewer to look at our images. The default viewer is ImageJ. If you do not have any viewer installed, please install ImageJ.
If you already have another viewer such as ITK-SNAP or Slicer and do not want to install ImageJ, you only need to set an environment variable SITK_SHOW_COMMAND to
point to your program of choice. This can also be done inside the ipython notebook:
%env SITK_SHOW_COMMAND /Applications/ITK-SNAP.app/Contents/MacOS/ITK-SNAP
Program
- 8:30am: Setup and introduction [Matthew McCormick and Hans Johnson].
- 9:00am: SimpleITK basics: loading data, image access, image transformations, image resampling, basic filters [Matthew McCormick].
- 10:00am: The ITKv4 registration framework [Nick Tustison and Brian Avants].
- 10:30am: Coffee break.
- 10:45am: Registration 1: composite transform, transformation initialization, embedded multi-resolution, scale parameter estimation, optimization termination criteria [Ziv Yaniv].
- 11:30am: Registration 2: nonrigid registration - Nonrigid registration, Bspline and displacement field transformations [Ziv Yaniv].
- 12:30pm: Lunch.
A Taste of What's to Come: SimpleITK Registration, It's Really Simple
The following script illustrates the use of SimpleITK to perform rigid registration between a CT and MR (registration specific code is highlighted). By the end of the tutorial you will be familiar with the various components that are available as part of the SimpleITK registration framework, easily modifying this example to suite your specific needs.
<source lang="python" highlight="8-28"> import SimpleITK as sitk
- read the images
fixed_image = sitk.ReadImage('training_001_ct.mha', sitk.sitkFloat32) moving_image = sitk.ReadImage('training_001_mr_T1.mha', sitk.sitkFloat32)
- initial alignment of the two volumes
transform = sitk.CenteredTransformInitializer(fixed_image,
moving_image, sitk.Euler3DTransform(), sitk.CenteredTransformInitializerFilter.GEOMETRY)
- multi-resolution rigid registration using Mutual Information
registration_method = sitk.ImageRegistrationMethod() registration_method.SetMetricAsMattesMutualInformation(numberOfHistogramBins=50) registration_method.SetMetricSamplingStrategy(registration_method.RANDOM) registration_method.SetMetricSamplingPercentage(0.01) registration_method.SetInterpolator(sitk.sitkLinear) registration_method.SetOptimizerAsGradientDescent(learningRate=1.0,
numberOfIterations=100, convergenceMinimumValue=1e-6, convergenceWindowSize=10)
registration_method.SetOptimizerScalesFromPhysicalShift() registration_method.SetShrinkFactorsPerLevel(shrinkFactors = [4,2,1]) registration_method.SetSmoothingSigmasPerLevel(smoothingSigmas=[2,1,0]) registration_method.SmoothingSigmasAreSpecifiedInPhysicalUnitsOn() registration_method.SetInitialTransform(transform) registration_method.Execute(fixed_image, moving_image)
sitk.WriteTransform(transform, 'ct2mrT1.tfm') </source>
To run this example you will need to download the CT and MR data. These are part of the training data provided by the Retrospective Image Registration Evaluation Project.
A bit of additional code also allows us to visually follow the registration process: