From 8e8e2b99a0fc0ce572b31451078628709a80e7d5 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Johannes=20Scho=CC=88nberger?=
 <hannesschoenberger@gmail.com>
Date: Sun, 15 Jul 2012 19:03:44 +0200
Subject: [PATCH] add short tutorial for geometric transformations

---
 doc/examples/applications/plot_geometric.py | 134 ++++++++++++++++++++
 1 file changed, 134 insertions(+)
 create mode 100644 doc/examples/applications/plot_geometric.py

diff --git a/doc/examples/applications/plot_geometric.py b/doc/examples/applications/plot_geometric.py
new file mode 100644
index 00000000..90fbce51
--- /dev/null
+++ b/doc/examples/applications/plot_geometric.py
@@ -0,0 +1,134 @@
+"""
+===============================
+Using geometric transformations
+===============================
+
+In this example, we will see how to use geometric transformations in the context
+of image processing.
+"""
+
+import math
+import numpy as np
+import matplotlib.pyplot as plt
+
+from skimage import data
+from skimage import transform as tf
+
+margins = dict(hspace=0.01, wspace=0.01, top=1, bottom=0, left=0, right=1)
+
+"""
+Basics
+======
+
+Several different geometric transformation types are supported: similarity,
+affine, projective and polynomial.
+
+Geometric transformations can either be created using the explicit parameters
+(e.g. scale, shear, rotation and translation) or the transformation matrix:
+"""
+
+#: create using explicit parameters
+tform = tf.SimilarityTransformation()
+scale = 1
+rotation = math.pi/2
+translation = (0, 1)
+tform.from_params(scale, rotation, translation)
+print tform.matrix
+
+#: create using transformation matrix
+matrix = tform.matrix.copy()
+matrix[1, 2] = 2
+tform2 = tf.SimilarityTransformation(matrix)
+
+"""
+These transformation objects can be used to forward and reverse transform
+coordinates between the source and destination coordinate systems:
+"""
+
+coord = [1, 0]
+print tform2.forward(coord)
+print tform2.reverse(tform.forward(coord))
+
+"""
+Image warping
+=============
+
+Geometric transformations can also be used to warp images:
+"""
+
+text = data.text()
+tform.from_params(1, math.pi/4, (text.shape[0] / 2, -100))
+
+# uses tform.reverse, alternatively use tf.warp(text, tform.reverse)
+rotated = tf.warp(text, tform)
+back_rotated = tf.warp(rotated, tform.forward)
+
+plt.figure(figsize=(8, 3))
+plt.subplot(131)
+plt.imshow(text)
+plt.axis('off')
+plt.gray()
+plt.subplot(132)
+plt.imshow(rotated)
+plt.axis('off')
+plt.gray()
+plt.subplot(133)
+plt.imshow(back_rotated)
+plt.axis('off')
+plt.gray()
+plt.subplots_adjust(**margins)
+
+"""
+.. image:: PLOT2RST.current_figure
+
+Parameter estimation
+====================
+
+In addition to the basic functionality mentioned above you can also estimate the
+parameters of a geometric transformation using the least-squares method.
+
+This can amongst other things be used for image registration or rectification,
+where you have a set of control points or homologous points in two images.
+
+Let's assume we want to recognize letters on a photograph which was not taken
+from the front but at a certain angle. In the simplest case of a plane paper
+surface the letters are projectively distorted. Simple matching algorithms would
+not be able to match such symbols. One solution to this problem would be to warp
+the image so that the distortion is removed and then apply a matching algorithm:
+"""
+
+text = data.text()
+
+src = np.array((
+    (155, 15),
+    (65, 40),
+    (260, 130),
+    (360, 95)
+))
+dst = np.array((
+    (0, 0),
+    (0, 50),
+    (300, 50),
+    (300, 0)
+))
+
+tform3 = tf.estimate_transformation('projective', src, dst)
+warped = tf.warp(text, tform3, output_shape=(50, 300))
+
+plt.figure(figsize=(8, 3))
+plt.subplot(211)
+plt.imshow(text)
+plt.plot(src[:, 0], src[:, 1], '.r')
+plt.axis('off')
+plt.gray()
+plt.subplot(212)
+plt.imshow(warped)
+plt.axis('off')
+plt.gray()
+plt.subplots_adjust(**margins)
+
+"""
+.. image:: PLOT2RST.current_figure
+"""
+
+plt.show()