Merge pull request #345 from JoostJM/add-filter-formulas

DOCS: Add formula for LoG

docs/installation.rst

@@ -7,9 +7,9 @@ There are three ways you can use pyradiomics:
 2. Use 3D Slicer Radiomics extension
 3. Use pyradiomics Docker
 
-------------
+----------------------
 1. Install from source
-------------
+----------------------
 
 * Ensure you have the version control system ``git`` installed on your machine.
 
@@ -44,9 +44,9 @@ There are three ways you can use pyradiomics:
   * ``python -m pip install -r requirements.txt``
   * ``python setup.py install``
 
-------------
+------------------------------------
 2. Use 3D Slicer Radiomics extension
-------------
+------------------------------------
 
 3D Slicer is a free open source research platform for medical image computing. Learn more and download 3D Slicer binary for your platform here: http://slicer.org.
 
@@ -56,9 +56,9 @@ of tools in 3D Slicer to automate your segmentation tasks.
 
 More detailed instructions about installing 3D Slicer Radiomics extension are available here: https://github.com/Radiomics/SlicerRadiomics
 
-------------
+-------------------------
 3. Use pyradiomics Docker
-------------
+-------------------------
 
 This approach may be preferred if you are interested in using pyradiomics from the command line, but have difficulties installing the library on your system.
 
@@ -77,9 +77,9 @@ an extra step is required to specify which directories will be used for file exc
 The argument above will make the ``HOST_DIR`` path available within the container at ``CONTAINER_DIR`` location. The files that will be read or written by the
 converter run from the docker container should be referred to via the ``CONTAINER_DIR`` path.
 
--------------------
+-----------------
 Setting up Docker
--------------------
+-----------------
 
 Docker (http://docker.com) is a project that automates deployment of applications inside software containers. Docker
 application is defined by _images_ that contain all of the components and steps needed to initialize the application instance. A _container_ is a running instance of the image. We provide an image that contains the compiled `pyradiomics` library in the `docker/pyradiomics:CLI` image. By using `pyradiomics` Docker container you can use `pyradiomics` on any operating system that supports Docker without having to compile `pyradiomics`. All you need to do is install Docker on your system, and download the `pyradiomics` Docker image.

radiomics/imageoperations.py

@@ -628,13 +628,35 @@ def getOriginalImage(inputImage, **kwargs):
 
 
 def getLoGImage(inputImage, **kwargs):
-  """
+  r"""
   Applies a Laplacian of Gaussian filter to the input image and yields a derived image for each sigma value specified.
 
+  A Laplacian of Gaussian image is obtained by convolving the image with the second derivative (Laplacian) of a Gaussian
+  kernel.
+
+  The Gaussian kernel is used to smooth the image and is defined as
+
+  .. math::
+
+    G(x, y, z, \sigma) = \frac{1}{(\sigma \sqrt{2 \pi})^3}e^{-\frac{x^2 + y^2 + z^2}{2\sigma^2}}
+
+  The Gaussian kernel is convolved by the laplacian kernel :math:`\nabla^2G(x, y, z)`, which is sensitive to areas with
+  rapidly changing intensities, enhancing edges. The width of the filter in the Gaussian kernel is determined by
+  :math:`\sigma` and can be used to emphasize more fine (low :math:`\sigma` values) or coarse (high :math:`\sigma`
+  values) textures.
+
+  .. warning::
+
+    The LoG filter implemented in PyRadiomics is a 3D LoG filter, and therefore requires 3D input. Features using a
+    single slice (2D) segmentation can still be extracted, but the input image *must* be a 3D image, with a minimum size
+    in all dimensions :math:`\geq \sigma`. If input image is too small, a warning is logged and :math:`\sigma` value is
+    skipped. Moreover, the image size *must* be at least 4 voxels in each dimensions, if this constraint is not met, no
+    LoG derived images can be generated.
+
   Following settings are possible:
 
-  - sigma: List of floats or integers, must be greater than 0. Sigma values to
-    use for the filter (determines coarseness).
+  - sigma: List of floats or integers, must be greater than 0. Filter width (mm) to use for the Gaussian kernel
+    (determines coarseness).
 
   .. warning::
     Setting for sigma must be provided. If omitted, no LoG image features are calculated and the function
@@ -643,6 +665,12 @@ def getLoGImage(inputImage, **kwargs):
   Returned filter name reflects LoG settings:
   log-sigma-<sigmaValue>-3D.
 
+  References:
+
+  - `SimpleITK Doxygen documentation <https://itk.org/SimpleITKDoxygen/html/classitk_1_1simple_1_1LaplacianRecursiveGaussianImageFilter.html>`_
+  - `ITK Doxygen documentation <https://itk.org/Doxygen/html/classitk_1_1LaplacianRecursiveGaussianImageFilter.html>`_
+  - `<https://en.wikipedia.org/wiki/Blob_detection#The_Laplacian_of_Gaussian>`_
+
   :return: Yields log filtered image for each specified sigma, corresponding image type name and ``kwargs`` (customized
     settings).
   """