5 update readme.md, wrapping, include files in response to code review (#6)

* Issue 3: Flesh out README.rst

* DOC: Removing itkMinimalStandardRandomVariateGenerator

* DOC: Doxygen comments and fixes for variable names.  Removal of cache for input image.

* DOC: Installation, Usage section.  Touch ups.

* DOC: In response to review by thewtex

* DOC: In response to review by dzenanz

Co-authored-by: Lee Newberg <[email protected]>

Author: Leengit

CMakeLists.txt

@@ -2,8 +2,6 @@ cmake_minimum_required(VERSION 3.10.2)
 project(StructurePreservingColorNormalization)
 set(CMAKE_CXX_STANDARD 11)
 
-set(StructurePreservingColorNormalization_LIBRARIES StructurePreservingColorNormalization)
-
 if(NOT ITK_SOURCE_DIR)
   find_package(ITK REQUIRED)
   list(APPEND CMAKE_MODULE_PATH ${ITK_CMAKE_DIR})

README.rst

@@ -14,7 +14,7 @@ ITKColorNormalization
 Overview
 --------
 
-This performs "Structure Preserving Color Normalization" on an H&E image using a reference image.
+This image filter performs *Structure Preserving Color Normalization* on an H&E image using a reference image.
 
 H&E (hematoxylin and eosin) are stains used to color parts of cells in a histological image, often for medical diagnosis.
 Hematoxylin is a compound that stains cell nuclei a purple-blue color.  Eosin is a compound that stains extracellular matrix
@@ -33,20 +33,105 @@ absorption characteristics using a technique mimicking that presented in [AGHMMS
 finds a good solution for a non-negative matrix factorization by first transforming it to the problem of finding a convex
 hull for a set of points in a cloud.
 
+The lead developer of InsightSoftwareConsortium/ITKColorNormalization is `Lee Newberg <https://github.com/Leengit)>`_.
+
+Installation for python
+-----------------------
+
+From the web page https://github.com/InsightSoftwareConsortium/ITKColorNormalization/actions, click on a recently
+successfully built workflow.  This takes you to a page of \"Build, test, package\" and a list of Artifacts, such as
+WindowWheel3.8, WindowWheel3.7, WindowWheel3.6, WindowWheel3.5, MacOSWheels, LinuxWheel38, LinuxWheel37, LinuxWheel36, and
+LinuxWheel35.  Click on the artifact that matches your operating system and version of python, to download a zip file.  Find
+the downloaded zip file, perhaps within your Downloads folder, and unzip it.  This gives you a file with a name like
+itk_spcn-0.1.0-cp38-cp38-manylinux1_x86_64.whl.
+
+In a terminal session, create a python virtual environment with a command like
+
+.. code-block:: shell
+
+    python -m venv /tmp/venv
+
+Make your current terminal session use the virtual environment with a command like the following.  Note that the line begins
+with a single \".\" followed by a space.
+
+.. code-block:: shell
+
+    . /tmp/venv/bin/activate
+
+Install the wheel in the virtual environment with a command like
+
+.. code-block:: shell
+
+    /tmp/venv/bin/pip install itk_spcn-0.1.0-cp38-cp38-manylinux1_x86_64.whl
+
+You can stop using the virtual environment in your terminal session with the following command.
+
+.. code-block:: shell
+
+    deactivate
+
+Usage
+-----
+
+If you have not done so already, make your current terminal session use the previously created virtual environment with a
+command like the following.  Note that the line begins with a single \".\" followed by a space.
+
+.. code-block:: shell
+
+    . /tmp/venv/bin/activate
+
+Launch python using your virtual environment with \`python\` or \`python3\`.  In python, type the following to load the itk
+package and two images:
+
+.. code-block:: python
+
+    import itk
+    input_image = itk.imread('path/to/input_file.mha')
+    reference_image = itk.imread('path/to/reference_file.mha')
+
+You can use the eager interface for ITK.  The input_image and reference_image are processed to produce normalized_image,
+which is the input_image with the color scheme of the reference_image.  The color_index_suppressed_by_hematoxylin and
+color_index_suppressed_by_eosin arguments are optional if the input_image pixel type is RGB or RGBA.  Here you are indicating
+that the color channel most suppressed by hematoxylin is 0 (which is red for RGB and RGBA pixels) and that the color most
+suppressed by eosin is 1 (which is green for RGB and RGBA pixels)\; these are the defaults for RGB and RGBA pixels.
+
+.. code-block:: python
+
+    normalized_image = itk.structure_preserving_color_normalization_filter(
+        input_image,
+        reference_image,
+        color_index_suppressed_by_hematoxylin=0,
+        color_index_suppressed_by_eosin=1)
+
+Alternatively, create a pipeline.  The function itk.StructurePreservingColorNormalizationFilter.New() uses its argument to
+determine the pixel type for the filter\; the actual image is not used in the first line of the following.  As above, the
+calls to SetColorIndexSuppressedByHematoxylin and SetColorIndexSuppressedByEosin are optional if the pixel type is RGB or
+RGBA.
+
+.. code-block:: python
+
+    spcn_filter = itk.StructurePreservingColorNormalizationFilter.New(input_image)
+    spcn_filter.SetColorIndexSuppressedByHematoxylin(0)
+    spcn_filter.SetColorIndexSuppressedByEosin(1)
+    spcn_filter.SetInput(0, input_image)
+    spcn_filter.SetInput(1, reference_image)
+    spcn_filter.SetOutput(normalized_image)
+    spcn_filter.Update()
+
 Bibliography
 ------------
 
-.. [AGHMMSWZ2013] Arora S, Ge R, Halpern Y, Mimno D, Moitra A, Sontag D, Wu Y, Zhu M. A Practical Algorithm for Topic
-   Modeling with Provable Guarantees. Proceedings of the 30th International Conference on Machine Learning, PMLR
-   28(2):280-288, 2013.
+.. [AGHMMSWZ2013] Arora S, Ge R, Halpern Y, Mimno D, Moitra A, Sontag D, Wu Y, Zhu M.  A Practical Algorithm for Topic
+   Modeling with Provable Guarantees.  *Proceedings of the 30th International Conference on Machine Learning*, `PMLR 2013\;
+   28(2):280-288 <http://proceedings.mlr.press/v28/arora13.html>`_.
 
-.. [NCKZ2018] Newberg LA, Chen X, Kodira CD, Zavodszky MI. Computational de novo discovery of distinguishing genes for
-   biological processes and cell types in complex tissues. PLoS One. 2018;13(3):e0193067. Published 2018
-   Mar 1. doi:10.1371/journal.pone.0193067
+.. [NCKZ2018] Newberg LA, Chen X, Kodira CD, Zavodszky MI.  Computational de novo discovery of distinguishing genes for
+   biological processes and cell types in complex tissues.  *PLoS One*, 2018\; 13(3):e0193067.
+   `doi:10.1371/journal.pone.0193067 <https://doi.org/10.1371/journal.pone.0193067>`_.
 
-.. [RAS2019] Ramakrishnan G, Anand D, Sethi A.  Fast GPU-Enabled Color Normalization for Digital Pathology.
-   arXiv:1901.03088. 2019 Jan.
+.. [RAS2019] Ramakrishnan G, Anand D, Sethi A.  Fast GPU-Enabled Color Normalization for Digital Pathology.  `arXiv 2019\;
+   1901.03088 <https://arxiv.org/abs/1901.03088>`_.
 
-.. [VPSAWBSSEN2016] Vahadane A, Peng T, Sethi A, Albarqouni S, Wang L, Baust M, Steiger K, Schlitter AM, Esposito I,
-   Navab N. Structure-Preserving Color Normalization and Sparse Stain Separation for Histological Images. IEEE Trans Med
-   Imaging. 2016 Aug;35(8):1962-71. doi: 10.1109/TMI.2016.2529665. Epub 2016 Apr 27. PMID: 27164577.
+.. [VPSAWBSSEN2016] Vahadane A, Peng T, Sethi A, Albarqouni S, Wang L, Baust M, Steiger K, Schlitter AM, Esposito I, Navab N.
+   Structure-Preserving Color Normalization and Sparse Stain Separation for Histological Images.  *IEEE Trans Med Imaging*,
+   2016\; 35(8):1962-71.  `doi:10.1109/TMI.2016.2529665 <https://doi.org/10.1109/TMI.2016.2529665>`_.