From 8579ef0183a45b213ed934fdc0880f4ecca40a5b Mon Sep 17 00:00:00 2001 From: Stefan van der Walt Date: Wed, 30 Nov 2011 15:56:21 -0800 Subject: [PATCH] STY: Clean up docstrings. --- doc/examples/plot_contours.py | 18 ++++---- skimage/measure/find_contours.py | 75 ++++++++++++++++++-------------- 2 files changed, 51 insertions(+), 42 deletions(-) diff --git a/doc/examples/plot_contours.py b/doc/examples/plot_contours.py index 8f707d52..020d3dfc 100644 --- a/doc/examples/plot_contours.py +++ b/doc/examples/plot_contours.py @@ -3,18 +3,16 @@ Contour finding =============== -``skimage.measure.find_contours`` uses a marching squares method to -find constant valued contours in an image. Array values are linearly -interpolated to provide better precision of the output contours. -Contours which intersect the image edge are open; all others -are closed. +``skimage.measure.find_contours`` uses a marching squares method to find +constant valued contours in an image. Array values are linearly interpolated +to provide better precision of the output contours. Contours which intersect +the image edge are open; all others are closed. The `marching squares algorithm -`__ is a special -case of the marching cubes algorithm (Lorensen, William and Harvey -E. Cline. Marching Cubes: A High Resolution 3D Surface Construction -Algorithm. Computer Graphics (SIGGRAPH 87 Proceedings) 21(4) July -1987, p. 163-170). +`__ is a special case of +the marching cubes algorithm (Lorensen, William and Harvey E. Cline. Marching +Cubes: A High Resolution 3D Surface Construction Algorithm. Computer Graphics +(SIGGRAPH 87 Proceedings) 21(4) July 1987, p. 163-170). """ diff --git a/skimage/measure/find_contours.py b/skimage/measure/find_contours.py index f46d4e77..582c1b52 100755 --- a/skimage/measure/find_contours.py +++ b/skimage/measure/find_contours.py @@ -5,8 +5,9 @@ from collections import deque _param_options = ('high', 'low') -def find_contours(array, level, fully_connected='low', positive_orientation='low'): - '''Find iso-valued contours in a 2D array for a given level value. +def find_contours(array, level, + fully_connected='low', positive_orientation='low'): + """Find iso-valued contours in a 2D array for a given level value. Uses the "marching squares" method to compute a the iso-valued contours of the input 2D array for a particular level value. Array values are linearly @@ -14,35 +15,36 @@ def find_contours(array, level, fully_connected='low', positive_orientation='low Parameters ---------- - array : convertible to a 2D ndarray object - Input data in which to find isocontours. + array : 2D ndarray of double + Input data in which to find contours. level : float Value along which to find contours in the array. - fully_connected : either 'low' or 'high' - Indicates whether array elements below the given level value are to - be considered fully- connected (and hence elements above the value - will only be face connected), or vice-versa. (See below for details.) + fully_connected : str, {'low', 'high'} + Indicates whether array elements below the given level value are to be + considered fully-connected (and hence elements above the value will + only be face connected), or vice-versa. (See notes below for details.) positive_orientation : either 'low' or 'high' - Indicates whether the output contours will produce - positively-oriented polygons around islands of low- or high-valued - elements. If 'low' then contours will wind counter- clockwise around - elements below the iso-value. Alternately, this means that low-valued - elements are always on the left of the contour. (See below for - details.) + Indicates whether the output contours will produce positively-oriented + polygons around islands of low- or high-valued elements. If 'low' then + contours will wind counter- clockwise around elements below the + iso-value. Alternately, this means that low-valued elements are always + on the left of the contour. (See below for details.) Returns ------- - A list of contours, where each contour is an ndarray of shape (n, 2) - consisting of n (x,y) coordinates along the contour. + contours : list of (n,2)-ndarrays + Each contour is an ndarray of shape ``(n, 2)``, + consisting of n ``(x, y)`` coordinates along the contour. + Notes + ----- The marching squares algorithm is a special case of the marching cubes - algorithm (Lorensen, William and Harvey E. Cline. Marching Cubes: A High - Resolution 3D Surface Construction Algorithm. Computer Graphics (SIGGRAPH - 87 Proceedings) 21(4) July 1987, p. 163-170). A simple explanation is - available here: http://www.essi.fr/~lingrand/MarchingCubes/algo.html + algorithm [1]_. A simple explanation is available here:: + + http://www.essi.fr/~lingrand/MarchingCubes/algo.html There is a single ambiguous case in the marching squares algorithm: when - a given 2x2-element square has two high-valued and two low-valued + a given ``2 x 2``-element square has two high-valued and two low-valued elements, each pair diagonally adjacent. (Where high- and low-valued is with respect to the contour value sought.) In this case, either the high-valued elements can be 'connected together' via a thin isthmus that @@ -50,7 +52,7 @@ def find_contours(array, level, fully_connected='low', positive_orientation='low connected together across a diagonal, they are considered 'fully connected' (also known as 'face+vertex-connected' or '8-connected'). Only high-valued or low-valued elements can be fully-connected, the other set - will be considred as 'face-connected' or '4-connected'. By default, + will be considered as 'face-connected' or '4-connected'. By default, low-valued elements are considered fully-connected; this can be altered with the 'fully_connected' parameter. @@ -67,23 +69,32 @@ def find_contours(array, level, fully_connected='low', positive_orientation='low 'positive_orientation' parameter. The order of the contours in the output list is determined by the position - of the smallest x,y (in lexicographical order) coordinate in the contour. - This is a side-effect of how the input array is traversed, but can be - relied upon. + of the smallest ``x,y`` (in lexicographical order) coordinate in the + contour. This is a side-effect of how the input array is traversed, but + can be relied upon. - IMPORTANT NOTE ON COORDINATES AND VALUES: - Array coordinates/values are assumed to refer to the _center_ of the - array element. Take a simple example: [0, 1]. The interpolated position of - 0.5 in this array is midway between the 0-element (at x=0) and the - 1-element (at x=1), and thus would fall at x=0.5. + .. warning:: + + Array coordinates/values are assumed to refer to the *center* of the + array element. Take a simple example input: ``[0, 1]``. The interpolated + position of 0.5 in this array is midway between the 0-element (at + ``x=0``) and the 1-element (at ``x=1``), and thus would fall at + ``x=0.5``. This means that to find reasonable contours, it is best to find contours midway between the expected "light" and "dark" values. In particular, - given a binarized array, DO NOT choose to find contours at the low or high + given a binarized array, *do not* choose to find contours at the low or high value of the array. This will often yield degenerate contours, especially around structures that are a single array element wide. Instead choose - a middle value, as above.''' + a middle value, as above. + References + ---------- + .. [1] Lorensen, William and Harvey E. Cline. Marching Cubes: A High + Resolution 3D Surface Construction Algorithm. Computer Graphics + (SIGGRAPH 87 Proceedings) 21(4) July 1987, p. 163-170). + + """ array = np.asarray(array, dtype=np.double) if array.ndim != 2: raise RuntimeError('Only 2D arrays are supported.')