From d5710c82ab09cec222fc8b3361634bc08ed2e41e Mon Sep 17 00:00:00 2001
From: Emmanuelle Gouillart <emmanuelle.gouillart@nsup.org>
Date: Mon, 27 Aug 2012 17:04:25 +0200
Subject: [PATCH] Example in route_through_array

---
 skimage/graph/mcp.py | 41 ++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 40 insertions(+), 1 deletion(-)

diff --git a/skimage/graph/mcp.py b/skimage/graph/mcp.py
index 68921371..941d6e89 100644
--- a/skimage/graph/mcp.py
+++ b/skimage/graph/mcp.py
@@ -1,7 +1,8 @@
 from ._mcp import MCP, MCP_Geometric, make_offsets
 
 
-def route_through_array(array, start, end, fully_connected=True, geometric=True):
+def route_through_array(array, start, end, fully_connected=True,
+                        geometric=True):
     """Simple example of how to use the MCP and MCP_Geometric classes.
 
     See the MCP and MCP_Geometric class documentation for explanation of the
@@ -28,6 +29,44 @@ def route_through_array(array, start, end, fully_connected=True, geometric=True)
         List of n-d index tuples defining the path from `start` to `end`.
     cost : float
         Cost of the path.
+
+    Examples
+    --------
+    >>> from skimage.graph import route_through_array
+    >>> image = np.arange((36)).reshape((6, 6))
+    >>> image
+    array([[ 0,  1,  2,  3,  4,  5],
+           [ 6,  7,  8,  9, 10, 11],
+           [12, 13, 14, 15, 16, 17],
+           [18, 19, 20, 21, 22, 23],
+           [24, 25, 26, 27, 28, 29],
+           [30, 31, 32, 33, 34, 35]])
+    >>> # Find the path with lowest cost
+    >>> indices, weight = route_through_array(image, (0, 0), (5, 5))
+    >>> indices = np.array(indices).T
+    >>> path = np.zeros_like(image)
+    >>> path[indices[0], indices[1]] = 1
+    >>> path
+    array([[1, 1, 1, 1, 1, 0],
+           [0, 0, 0, 0, 0, 1],
+           [0, 0, 0, 0, 0, 1],
+           [0, 0, 0, 0, 0, 1],
+           [0, 0, 0, 0, 0, 1],
+           [0, 0, 0, 0, 0, 1]])
+    >>> # Forbid diagonal steps
+    >>> indices, weight = route_through_array(image, (0, 0), (5, 5), \
+    fully_connected=False)
+    >>> indices = np.array(indices).T
+    >>> path = np.zeros_like(image)
+    >>> path[indices[0], indices[1]] = 1
+    >>> path
+    array([[1, 1, 1, 1, 1, 1],
+           [0, 0, 0, 0, 0, 1],
+           [0, 0, 0, 0, 0, 1],
+           [0, 0, 0, 0, 0, 1],
+           [0, 0, 0, 0, 0, 1],
+           [0, 0, 0, 0, 0, 1]])
+
     """
     start, end = tuple(start), tuple(end)
     if geometric: