Updated README

Author: jrosebr1

.gitignore

@@ -0,0 +1 @@
+.DS_Store

README.md

@@ -1,2 +1,82 @@
 # imutils
 A series of convenience functions to make basic image processing functions such as translation, rotation, resizing, skeletonization, and displaying Matplotlib images easier with OpenCV and Python.
+
+For more information, along with a detailed code review check out the following posts on the [PyImageSearch.com](http://www.pyimagesearch.com) blog:
+
+- *Links to be added soon*
+
+## Translation
+Translation is the shifting of an image in either the *x* or *y* direction. To translate an image in OpenCV you would need to supply the *(x, y)*-shift, denoted as *(t<sub>x</sub>, t<sub>y</sub>)* to construct the translation matrix *M*:
+
+![Translation equation](docs/images/translation_eq.png?raw=true)
+
+And from there, you woud need to apply the `cv2.warpAffine` function.
+
+Instead of manually constructing the translation matrix *M* and calling `cv2.warpAffine`, you can simply make a call to the `translate` function of `imutils`.
+
+#### Example:
+<pre># translate the image x=25 pixels to the right and y=75 pixels up
+translated = imutils.translate(workspace, 25, -75)</pre>
+
+#### Output:
+<img src="docs/images/translation.png?raw=true" alt="Translation example"/ style="max-width: 500px;">
+
+## Rotation
+Rotating an image in OpenCV is accomplished by making a call to `cv2.getRotationMatrix2D` and `cv2.warpAffine`. Further care has to be taken to supply the *(x, y)*-coordinate of the point the image is to be rotated about. These calculation calls can quickly add up and make your code bulky and less readable. The `rotate` function in `imutils` helps resolve this problem.
+
+#### Example:
+<pre># loop over the angles to rotate the image
+for angle in xrange(0, 360, 90):
+	# rotate the image and display it
+	rotated = imutils.rotate(bridge, angle=angle)
+	cv2.imshow("Angle=%d" % (angle), rotated)</pre>
+
+#### Output:
+<img src="docs/images/rotation.png?raw=true" alt="Rotation example"/ style="max-width: 500px;">
+
+## Resizing
+Resizing an image in OpenCV is accomplished by calling the `cv2.resize` function. However, special care needs to be taken to ensure that the aspect ratio is maintained.  This `resize` function of `imutils` maintains the aspect ratio and provides the keyword arguments `width` and `height` so the image can be resized to the intended width/height while (1) maintaining aspect ratio and (2) ensuring the dimensions of the image do not have to be explicitly computed by the developer.
+
+Another optional keyword argument, `inter`, can be used to specify interpolation method as well.
+
+#### Example:
+<pre># loop over varying widths to resize the image to
+for width in (400, 300, 200, 100):
+	# resize the image and display it
+	resized = imutils.resize(workspace, width=width)
+	cv2.imshow("Width=%dpx" % (width), resized)</pre>
+
+#### Output:
+<img src="docs/images/resizing.png?raw=true" alt="Resizing example"/ style="max-width: 500px;">
+
+## Skeletonization
+Skeletonization is the process of constructing the "topological skeleton" of an object in an image, where the object is presumed to be white on a black background. OpenCV does not provide a function to explicity construct the skeleton, but does provide the morphological and binary functions to do so.
+
+For convenience, the `skeletonize` function of `imutils` can be used to construct the topological skeleton of the image.
+
+The first argument, `size` is the size of the structuring element kernel. An optional argument, `structuring`, can be used to control the structuring element -- it defaults to `cv2.MORPH_RECT`	, but can be any valid structuring element.
+
+#### Example:
+<pre># skeletonize the image
+gray = cv2.cvtColor(logo, cv2.COLOR_BGR2GRAY)
+skeleton = imutils.skeletonize(gray, size=(3, 3))
+cv2.imshow("Skeleton", skeleton)</pre>
+
+#### Output:
+<img src="docs/images/skeletonization.png?raw=true" alt="Skeletonization example"/ style="max-width: 500px;">
+
+## Displaying with Matplotlib
+In the Python bindings of OpenCV, images are represented as NumPy arrays in BGR order. This works fine when using the `cv2.imshow` function. However, if you intend on using Matplotlib, the `plt.imshow` function assumes the image is in RGB order. A simple call to `cv2.cvtColor` will resolve this problem, or you can use the `opencv2matplotlib` conveince function.
+
+#### Example:
+<pre># INCORRECT: show the image without converting color spaces
+plt.figure("Incorrect")
+plt.imshow(cactus)
+
+# CORRECT: convert color spaces before using plt.imshow
+plt.figure("Correct")
+plt.imshow(imutils.opencv2matplotlib(cactus))
+plt.show()</pre>
+
+#### Output:
+<img src="docs/images/matplotlib.png?raw=true" alt="Matplotlib example"/ style="max-width: 500px;">

demo.py

@@ -0,0 +1,72 @@
+# author:	Adrian Rosebrock
+# website:	http://www.pyimagesearch.com
+
+# USAGE
+# python demo.py
+
+# import the necessary packages
+import matplotlib.pyplot as plt
+import imutils
+import cv2
+
+# load the example images
+bridge = cv2.imread("demo_images/bridge.jpg")
+cactus = cv2.imread("demo_images/cactus.jpg")
+logo = cv2.imread("demo_images/pyimagesearch_logo.jpg")
+workspace = cv2.imread("demo_images/workspace.jpg")
+
+# 1. TRANSLATION
+# show the original image
+cv2.imshow("Original", workspace)
+
+# translate the image x-50 pixels to the left and y=100 pixels down
+translated = imutils.translate(workspace, -50, 100)
+cv2.imshow("Translated", translated)
+cv2.waitKey(0)
+
+# translate the image x=25 pixels to the right and y=75 pixels up
+translated = imutils.translate(workspace, 25, -75)
+cv2.imshow("Translated", translated)
+cv2.waitKey(0)
+cv2.destroyAllWindows()
+
+# 2. ROTATION
+# loop over the angles to rotate the image
+for angle in xrange(0, 360, 90):
+	# rotate the image and display it
+	rotated = imutils.rotate(bridge, angle=angle)
+	cv2.imshow("Angle=%d" % (angle), rotated)
+
+# wait for a keypress, then close all the windows
+cv2.waitKey(0)
+cv2.destroyAllWindows()
+
+# 3. RESIZING
+# loop over varying widths to resize the image to
+for width in (400, 300, 200, 100):
+	# resize the image and display it
+	resized = imutils.resize(workspace, width=width)
+	cv2.imshow("Width=%dpx" % (width), resized)
+
+# wait for a keypress, then close all the windows
+cv2.waitKey(0)
+cv2.destroyAllWindows()
+
+# 4. SKELETONIZATION
+# skeletonize the image using a 3x3 kernel
+cv2.imshow("Original", logo)
+gray = cv2.cvtColor(logo, cv2.COLOR_BGR2GRAY)
+skeleton = imutils.skeletonize(gray, size=(3, 3))
+cv2.imshow("Skeleton", skeleton)
+cv2.waitKey(0)
+cv2.destroyAllWindows()
+
+# 5. MATPLOTLIB
+# INCORRECT: show the image without converting color spaces
+plt.figure("Incorrect")
+plt.imshow(cactus)
+
+# CORRECT: convert color spaces before using plt.imshow
+plt.figure("Correct")
+plt.imshow(imutils.opencv2matplotlib(cactus))
+plt.show()

demo_images/bridge.jpg

@@ -1,34 +1,32 @@
 # author:	Adrian Rosebrock
 # website:	http://www.pyimagesearch.com
 
-PEP8
-
 # import the necessary packages
 import numpy as np
 import cv2
 
 def translate(image, x, y):
-	# Define the translation matrix and perform the translation
+	# define the translation matrix and perform the translation
 	M = np.float32([[1, 0, x], [0, 1, y]])
 	shifted = cv2.warpAffine(image, M, (image.shape[1], image.shape[0]))
 
-	# Return the translated image
+	# return the translated image
 	return shifted
 
 def rotate(image, angle, center=None, scale=1.0):
-	# Grab the dimensions of the image
+	# grab the dimensions of the image
 	(h, w) = image.shape[:2]
 
-	# If the center is None, initialize it as the center of
+	# if the center is None, initialize it as the center of
 	# the image
 	if center is None:
 		center = (w / 2, h / 2)
 
-	# Perform the rotation
+	# perform the rotation
 	M = cv2.getRotationMatrix2D(center, angle, scale)
 	rotated = cv2.warpAffine(image, M, (w, h))
 
-	# Return the rotated image
+	# return the rotated image
 	return rotated
 
 def resize(image, width=None, height=None, inter=cv2.INTER_AREA):
@@ -57,7 +55,7 @@ def resize(image, width=None, height=None, inter=cv2.INTER_AREA):
 		dim = (width, int(h * r))
 
 	# resize the image
-	resized = cv2.resize(image, dim, interpolation = inter)
+	resized = cv2.resize(image, dim, interpolation=inter)
 
 	# return the resized image
 	return resized