wassname/scikit-image
1
0
Fork 0
mirror of https://github.com/wassname/scikit-image.git synced 2026-07-06 05:16:40 +08:00
Code Issues Packages Projects Releases Wiki Activity

STY: Clean up docstrings.

Browse Source
This commit is contained in:
Stefan van der Walt
2011-11-30 15:56:21 -08:00
parent 7691fdc3c6
commit 8579ef0183
2 changed files with 51 additions and 42 deletions
Download Patch File Download Diff File Expand all files Collapse all files
doc/examples/plot_contours.py
+8 -10
View File
@@ -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
<http://www.essi.fr/~lingrand/MarchingCubes/algo.html>`__ 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).
<http://www.essi.fr/~lingrand/MarchingCubes/algo.html>`__ 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).
"""
skimage/measure/find_contours.py
+43 -32
View File
@@ -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.')