From 8a4bd8510dea297ad857230bcb0bce43c059399f Mon Sep 17 00:00:00 2001
From: Brian Holt <bdholt1@gmail.com>
Date: Fri, 10 Feb 2012 18:16:49 +0000
Subject: [PATCH] added HOG example

---
 doc/examples/plot_hog.py | 105 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 105 insertions(+)
 create mode 100644 doc/examples/plot_hog.py

diff --git a/doc/examples/plot_hog.py b/doc/examples/plot_hog.py
new file mode 100644
index 00000000..da82cd83
--- /dev/null
+++ b/doc/examples/plot_hog.py
@@ -0,0 +1,105 @@
+r'''
+===============================
+Histogram of Oriented Gradients
+===============================
+
+The Histogram of Oriented Gradient (HOG) feature descriptor is popular
+for object detection 
+<http://en.wikipedia.org/wiki/Histogram_of_oriented_gradients>`__.
+
+In the following example, we compute the HOG descriptor and display 
+a visualisation.
+
+Algorithm overview
+------------------
+
+Compute a Histogram of Oriented Gradients (HOG) by
+    1) (optional) global image normalisation
+    2) computing the gradient image in x and y
+    3) computing gradient histograms
+    3) normalising across blocks
+    4) flattening into a feature vector
+        
+The first stage applies an optional global image normalisation
+equalisation that is designed to reduce the influence of illumination
+effects. In practice we use gamma (power law) compression, either
+computing the square root or the log of each colour channel.
+Image texture strength is typically proportional to the local surface
+illumination so this compression helps to reduce the effects of local
+shadowing and illumination variations.
+        
+The second stage computes first order image gradients. These capture
+contour, silhouette and some texture information, while providing
+further resistance to illumination variations. The locally dominant
+colour channel is used, which provides colour invariance to a large
+extent. Variant methods may also include second order image derivatives,
+which act as primitive bar detectors - a useful feature for capturing,
+e.g. bar like structures in bicycles and limbs in humans.
+
+The third stage aims to produce an encoding that is sensitive to
+local image content while remaining resistant to small changes in
+pose or appearance. The adopted method pools gradient orientation
+information locally in the same way as the SIFT [Lowe 2004]
+feature. The image window is divided into small spatial regions,
+called "cells". For each cell we accumulate a local 1-D histogram
+of gradient or edge orientations over all the pixels in the
+cell. This combined cell-level 1-D histogram forms the basic
+"orientation histogram" representation. Each orientation histogram
+divides the gradient angle range into a fixed number of
+predetermined bins. The gradient magnitudes of the pixels in the
+cell are used to vote into the orientation histogram.
+
+The fourth stage computes normalisation, which takes local groups of
+cells and contrast normalises their overall responses before passing
+to next stage. Normalisation introduces better invariance to illumination,
+shadowing, and edge contrast. It is performed by accumulating a measure
+of local histogram "energy" over local groups of cells that we call
+"blocks". The result is used to normalise each cell in the block.
+Typically each individual cell is shared between several blocks, but
+its normalisations are block dependent and thus different. The cell
+thus appears several times in the final output vector with different
+normalisations. This may seem redundant but it improves the performance.
+We refer to the normalised block descriptors as Histogram of Oriented
+Gradient (HOG) descriptors.
+
+The final step collects the HOG descriptors from all blocks of a dense
+overlapping grid of blocks covering the detection window into a combined
+feature vector for use in the window classifier.                        
+
+References
+----------
+
+.. [1] Dalal, N and Triggs, B, Histograms of Oriented Gradients for
+      Human Detection, IEEE Computer Society Conference on Computer
+      Vision and Pattern Recognition 2005 San Diego, CA, USA
+'''
+
+from scikits.image.feature import hog
+from scikits.image import data
+from scikits.image.color import rgb2grey
+
+import numpy as np
+import matplotlib.pyplot as plt
+
+
+# Construct test image
+
+image = data.lena()
+
+# HOG
+
+grey = rgb2grey(image)
+
+fd, hog_image = hog(grey, orientations=8, pixels_per_cell=(16, 16),
+                    cells_per_block=(1, 1), visualise=True)
+
+plt.figure(figsize=(12, 5))
+
+plt.subplot(121)
+plt.imshow(grey, cmap=plt.cm.gray)
+plt.title('Input image')
+
+plt.subplot(122)
+plt.imshow(hog_image, cmap=plt.cm.gray)
+plt.title('Histogram of Oriented Gradients')
+plt.show()