6_Extending_the_Toolkit.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "# Extending ITK with your own module"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Why?\n",
    "\n",
    "* New algorithm\n",
    "* Easy integration in ITK\n",
    "* Reproducible science\n",
    "* Easy Python wrapping"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": true,
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "## Requirements\n",
    "\n",
    "* CMake\n",
    "* C++ development environment"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Why use C++\n",
    "\n",
    "* C++ allows the developer to have full access to ITK\n",
    "    * Memory management\n",
    "    * Thread management\n",
    "* Any dimension and pixel type supported.\n",
    "* Key element missing in Python: Iterators."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": true,
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "## Iterators\n",
    "\n",
    "* An iterator is a fast and safe way to access an entire range of memory.\n",
    "* It can be used to process an entire image."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": true,
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## ITK Modules\n",
    "\n",
    "* ITK is organized in modules\n",
    "* Each module typically contains filters that are related (e.g. Segmentation, Registration, Filtering)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## What are remote modules\n",
    "\n",
    "* Remote modules are an easy way to develop new ITK filters and integrate them in ITK.\n",
    "* Allows the developer to easily publish and share their new algorithms.\n",
    "* ITK continuously contains the best available algorithms.\n",
    "* Remote modules are separate project from ITK. The developer(s) is (are) responsible of maintaining the project.\n",
    "* Remote modules integrate one or more filters implemented in C++ and their corresponding Python bindings."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": true,
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Examples\n",
    "\n",
    "* ITKTextureFeatures\n",
    "* ITKUltrasound\n",
    "* ITKIsotropicWavelets"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "## ITKTextureFeatures\n",
    "\n",
    "### Two filters:\n",
    "* itkCoocurrenceTextureFeaturesImageFilter: computes textural features based on intensity-based co-occurrence matrices in the image.\n",
    "* itkRunLengthTextureFeaturesImageFilter: computes textural features based on equally valued intensity clusters of different sizes or run lengths in the image.\n",
    "\n",
    "<div style=\"width: 100%; display: table;\">\n",
    "    <div style=\"display: table-row\">\n",
    "        <div style=\"width: 350px; display: table-cell;\">\n",
    "            <figure>\n",
    "                <img src=\"data/CBCT-TextureInput.png\">\n",
    "                <figcaption>Fig1. - CBCT of the test condyle</figcaption>\n",
    "            </figure> \n",
    "        </div>\n",
    "        <div style=\"width: 350px; display: table-cell;\">\n",
    "            <figure>\n",
    "                <img src=\"data/CBCT-TextureRunLengthNonUniformity.png\">\n",
    "                <figcaption>Fig2. - texture’s run length non uniformity</figcaption>\n",
    "            </figure> \n",
    "        </div>\n",
    "    </div>\n",
    "</div>\n",
    "\n",
    "- https://github.com/InsightSoftwareConsortium/ITKTextureFeatures\n",
    "- http://www.insight-journal.org/browse/publication/985\n",
    "\n",
    "```\n",
    "python -m pip install itk-texturefeatures\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "##  ITKUltrasound\n",
    "\n",
    "* High performance ultrasound image formation and analysis based on the Insight Toolkit (ITK).\n",
    "* Introduction of an itk::StreamingResampleImageFilter.\n",
    "<figure>\n",
    "    <img src=\"data/Ultrasound-B-mode.png\" width=600>\n",
    "    <figcaption>Fig1. Large, scan converted B-Mode image of anechoic spheres in a tissue mimicking ultrasound phantom. The image was processed without swapping to disk.</figcaption>\n",
    "</figure>\n",
    "\n",
    "- https://github.com/KitwareMedical/ITKUltrasound\n",
    "- http://www.insight-journal.org/browse/publication/722\n",
    "\n",
    "```\n",
    "python -m pip install itk-ultrasound\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "##  ITKIsotropicWavelets\n",
    "\n",
    "* Multiresolution (MRA) analysis framework using isotropic and steerable wavelets in the frequency domain.\n",
    "* Provides the backbone for state of the art filters for denoising, feature detection or phase analysis in N-dimension\n",
    "\n",
    "- https://github.com/InsightSoftwareConsortium/ITKIsotropicWavelets\n",
    "- http://www.insight-journal.org/browse/publication/986\n",
    "\n",
    "```\n",
    "python -m pip install itk-isotropicwavelets\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Creation of a remote module: Overview\n",
    "\n",
    "1. The developer creates a new module containing new ITK filters.\n",
    "    * The new module is its own independent GitHub project.\n",
    "    * The new module can be easily be compiled and used in combination with ITK.\n",
    "2. The developer writes an Insight Journal article\n",
    "    * The module is more visible to the community.\n",
    "    * An option can be added to ITK to compile the remote module as part of ITK."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": true,
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Creation of a remote module: details\n",
    "\n",
    "* The template project source code is here:\n",
    "        https://github.com/InsightSoftwareConsortium/ITKModuleTemplate"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "* Run the following commands:\n",
    "        python -m pip install cookiecutter\n",
    "        python -m cookiecutter gh:InsightSoftwareConsortium/ITKModuleTemplate"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "* Provide requested information.\n",
    "        Answer the following questions (Pressing \"Enter\" will use the default option):\n",
    "        full_name [Insight Software Consortium]:\n",
    "        email [itk+community@discourse.itk.org]:\n",
    "        github_username [itkrobot]:\n",
    "        project_name [ITKModuleTemplate]: \n",
    "        module_name [ModuleTemplate]: \n",
    "        python_package_name [itk-moduletemplate]: \n",
    "        download_url [https://github.com/InsightSoftwareConsortium/ITKModuleTemplate]: \n",
    "        project_short_description [This is a template that serves as a starting point for a new module.]: \n",
    "        project_long_description [ITK is an open-source, cross-platform library that provides developers with an extensive suite of software tools for image analysis. Developed through extreme programming methodologies, ITK employs leading-edge algorithms for registering and segmenting multidimensional scientific images.]: "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": true,
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "##  New Module Content\n",
    "<pre>\n",
    "        (itk) fbudin:ITKModuleTemplate/ $ tree -a\n",
    "        .\n",
    "        ├── appveyor.yml\n",
    "        ├── .circleci\n",
    "        │   └── config.yml\n",
    "        ├── CMakeLists.txt\n",
    "        ├── CTestConfig.cmake\n",
    "        ├── include\n",
    "        │   ├── itkMinimalStandardRandomVariateGenerator.h\n",
    "        │   ├── itkMyFilter.h\n",
    "        │   ├── itkMyFilter.hxx\n",
    "        │   ├── itkNormalDistributionImageSource.h\n",
    "        │   └── itkNormalDistributionImageSource.hxx\n",
    "        ├── itk-module.cmake\n",
    "        ├── LICENSE\n",
    "        ├── README.rst\n",
    "        ├── setup.py\n",
    "</pre>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "<pre>\n",
    "        ├── src\n",
    "        │   ├── CMakeLists.txt\n",
    "        │   └── itkMinimalStandardRandomVariateGenerator.cxx\n",
    "        ├── test\n",
    "        │   ├── Baseline\n",
    "        │   │   ├── itkMyFilterTestOutput.mha.sha512\n",
    "        │   │   └── itkNormalDistributionImageSourceTestOutput.mha.sha512\n",
    "        │   ├── CMakeLists.txt\n",
    "        │   ├── itkMinimalStandardRandomVariateGeneratorTest.cxx\n",
    "        │   ├── itkMyFilterTest.cxx\n",
    "        │   └── itkNormalDistributionImageSourceTest.cxx\n",
    "        ├── .travis.yml\n",
    "        └── wrapping\n",
    "            ├── CMakeLists.txt\n",
    "            ├── itkMinimalStandardRandomVariateGenerator.wrap\n",
    "            └── itkNormalDistributionImageSource.wrap\n",
    "</pre>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": true,
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "##  Directory structure\n",
    "\n",
    "* `src`  and `include`: header files and source code\n",
    "* `test`: unit tests\n",
    "* `wrapping`: Required files to automatically create Python bindings."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Filter code\n",
    "\n",
    "<pre>\n",
    "template< typename TInputImage, typename TOutputImage >\n",
    "void\n",
    "MyFilter< TInputImage, TOutputImage >\n",
    "::DynamicThreadedGenerateData( const OutputRegionType & outputRegion)\n",
    "{\n",
    "  OutputImageType * output = this->GetOutput();\n",
    "  const InputImageType * input = this->GetInput();\n",
    "  using InputRegionType = typename InputImageType::RegionType;\n",
    "  InputRegionType inputRegion = InputRegionType(outputRegion.GetSize());\n",
    "\n",
    "  itk::ImageRegionConstIterator<InputImageType> in(input, inputRegion);\n",
    "  itk::ImageRegionIterator<OutputImageType> out(output, outputRegion);\n",
    "\n",
    "  for (in.GoToBegin(), out.GoToBegin(); !in.IsAtEnd() && !out.IsAtEnd(); ++in, ++out)\n",
    "  {\n",
    "    out.Set( in.Get() );\n",
    "  }\n",
    "}\n",
    "</pre>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": true,
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Continuous integration\n",
    "\n",
    "* Appveyor (Windows)\n",
    "* Travis (MacOS)\n",
    "* CircleCI (Linux)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Python packages\n",
    "\n",
    "* Automatically generated in the continuous integration platforms.\n",
    "* Download wheel to personal computer\n",
    "* Upload wheel to PyPI (`pip install`)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": true,
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Where to find more information:\n",
    "\n",
    "* ITK Software Guide\n",
    "    * [Configuring and building ITK](https://itk.org/ITKSoftwareGuide/html/Book1/ITKSoftwareGuide-Book1ch2.html#x22-130002)\n",
    "    * [Create a remote module](https://itk.org/ITKSoftwareGuide/html/Book1/ITKSoftwareGuide-Book1ch9.html#x55-1640009.7)\n",
    "    * [How to write a filter](https://itk.org/ITKSoftwareGuide/html/Book1/ITKSoftwareGuide-Book1ch8.html#x54-1330008)\n",
    "    * [Iterators](https://itk.org/ITKSoftwareGuide/html/Book1/ITKSoftwareGuide-Book1ch6.html#x44-1020006)\n",
    "    * [Modules](https://itk.org/ITKSoftwareGuide/html/Book1/ITKSoftwareGuide-Book1ch9.html#x48-1480009)\n",
    "* [Discourse forum](https://discourse.itk.org/)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Exercises"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "### Exercise 1: Create the skeleton of a remote module\n",
    "\n",
    "* Hint1: You can run command lines by prefixing them with the symbol '!'\n",
    "* Hint2: You will need to add the argument '--no-input' to the command you are using. This is a limitation due to this notebook environment."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "### Exercise 2: Modify the filter\n",
    "\n",
    "* Add a constant value\n",
    "* Multiply by a constant factor\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "### Enjoy ITK!"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.6.2"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}