Add docs for histogram equalization

doc/image_processing/contrast_enhancement/ahe.rst

@@ -0,0 +1,4 @@
+.. _ahe:
+
+Adaptive histogram equalization (& CLAHE)
+=========================================

doc/image_processing/contrast_enhancement/histogram_equalization.rst

@@ -0,0 +1,100 @@
+.. _he:
+
+######################
+Histogram Equalization 
+######################
+
+Description
+-----------
+
+Histogram equalization also known as histogram flattening, is a non-linear image enhancement
+algorithm that follows the idea that not only should an image cover the entire grayscale space
+but also be uniformly distributed over that range. 
+
+An ideal image would be the one having a flat histogram.
+
+Although care should be taken before applying a non-linear transformation on the image
+histogram, there are good mathematical reasons why a flat histogram is the desired goal.
+
+A simple scenario would be an image with pixels concentrated in an interval, in which case
+histogram equalization transforms pixels to achieve a flat histogram image. Thus enhancing
+the image contrast.
+
+.. figure:: he_chart.png
+    :width: 200px
+    :align: center
+    :height: 100px
+    :alt: Could not load image.
+    :figclass: align-center
+
+    Pixels concentrated in an interval spread out.
+
+Algorithm
+---------
+
+#. First calculate the histogram corresponding to input image.
+#. If it is a multi channeled image (e.g. RGB), convert it to a independent color space
+   (like YCbCr, HSV etc.).
+#. Then calculate the cumulative histogram over the input image.
+#. Normalize the histogram to bring bin values between 0-1. For multi-channeled images 
+   normalize each channel independently (by the number of pixels in image).
+#. If the histogram of image is H(p\ :sub:`x`\)  p\ :sub:`x`\  in  [0, 255], then apply 
+   the transformation p\ :sub:`x'`\  = H(p\ :sub:`x`\),  p\ :sub:`x'`\  is pixel in output
+   image.
+
+**Explanation**
+
+Since we will be transforming the image to match a flat histogram, we match
+the cumulative histogram of the image to the cumulative histogram of a flat histogram.
+
+Cumulative histogram of flat image is  H(p\ :sub:`x'`\)  =  p\ :sub:`x'` .
+
+Hence,
+
+        =>  H(p\ :sub:`x'`\)  =  H(p\ :sub:`x`\)
+
+        =>  p\ :sub:`x'`\     =  H(p\ :sub:`x`\)
+
+Results
+-------
+The algorithm is applied on a few standard images. One of the transformations in shown below:
+
+**Grayscale Image**
+
+.. figure:: barbara.png
+    :width: 600px
+    :align: center
+    :height: 300px
+    :alt: Could not load image.
+    :figclass: align-center
+
+**RGB**
+
+.. figure:: church.png
+    :width: 600px
+    :align: center
+    :height: 250px
+    :alt: Could not load image.
+    :figclass: align-center
+
+
+Demo
+----
+
+Usage Syntax:
+
+    .. code-block:: cpp
+
+            gray8_image_t inp_img;
+            read_image("your_image.png", inp_img, png_tag{});
+            gray8_image_t dst_img(inp_img.dimensions());
+            histogram_equalization(view(inp_img), view(dst_img));
+
+            // To specify mask over input image
+
+            vector<vector<bool>> mask(inp_img.height(), vector<bool>(inp_img.width(), true));
+            histogram_equalization(view(inp_img), view(dst_img), true, mask);
+            
+    .. tip::  Convert an RGB image to a channel independent color space
+              before trying the histogram equalization algorithm.
+

doc/image_processing/contrast_enhancement/histogram_matching.rst

@@ -0,0 +1,4 @@
+.. _hm:
+
+Histogram Matching 
+==================

doc/image_processing/contrast_enhancement/index.rst

@@ -0,0 +1,14 @@
+Contrast Enhancement
+====================
+
+The GIL documentation sections listed below are dedicated to describe image
+processing algorithms used for contrast enhancement.
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Table of Contents
+
+   overview
+   histogram_equalization
+   histogram_matching
+   ahe

doc/image_processing/contrast_enhancement/overview.rst

@@ -0,0 +1,15 @@
+Overview
+========
+
+Contrast Enhancement is a significant part of image processing algorithms. Too dark or too
+light images don't look good to the human eyes. Hence while the primary focus of these 
+algorithms is to enhance visual beauty, some applications of this in medical research is also
+prevalent.
+
+We have a few contrast enhancement algorithms in the GIL image processing suite as well.
+These include :
+    #. :ref:`he`
+    #. :ref:`hm`
+    #. :ref:`ahe` 
+    #. Linear and Non-Linear Contrast stretching
+

doc/image_processing/index.rst

@@ -11,3 +11,5 @@ features, structures and algorithms, for image processing and analysis.
    overview
    basics
    affine-region-detectors
+   contrast_enhancement/index
+