Move to measure submodule

Code moved to new "measure" submodule and another test and better
documentation added.

skimage/measure/__init__.py

@@ -0,0 +1 @@
+from find_contours import find_contours

skimage/measure/find_contours.py

@@ -41,7 +41,7 @@ def find_contours(array, level, fully_connected='low', positive_orientation='low
     87 Proceedings) 21(4) July 1987, p. 163-170). 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
+    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
     elements, each pair diagonally adjacent. (Where high- and low-valued is
     with respect to the contour value sought.) In this case, either the
@@ -54,7 +54,7 @@ def find_contours(array, level, fully_connected='low', positive_orientation='low
     low-valued elements are considered fully-connected; this can be altered 
     with the 'fully_connected' parameter.
     
-     Output contours are not guaranteed to be closed: contours which intersect
+    Output contours are not guaranteed to be closed: contours which intersect
     the array edge will be left open. All other contours will be closed. (The
     closed-ness of a contours can be tested by checking whether the beginning
     point is the same as the end point.)
@@ -69,7 +69,20 @@ def find_contours(array, level, fully_connected='low', positive_orientation='low
     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.'''
+    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.
+    
+    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
+    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.'''
     
     array = np.asarray(array)
     if array.ndim != 2:

skimage/measure/setup.py

@@ -3,7 +3,7 @@
 def configuration(parent_package='', top_path=None):
     from numpy.distutils.misc_util import Configuration, get_numpy_include_dirs
 
-    config = Configuration('find_contours', parent_package, top_path)
+    config = Configuration('measure', parent_package, top_path)
     config.add_data_dir('tests')
 
 

skimage/measure/tests/test_find_contours.py

@@ -16,8 +16,10 @@ a[1, 1:-1] = 0
 ##        [ 1.,  0.,  1.,  1.,  1.,  1.,  1.,  1.],
 ##        [ 1.,  1.,  1.,  1.,  1.,  1.,  1.,  1.]], dtype=float32)
 
+x,y = np.mgrid[-1:1:5j,-1:1:5j]
+r = np.sqrt(x**2 + y**2)
 
-def test_find_contours():
+def test_binary():
   contours = find_contours(a, 0.5)
   assert len(contours) == 1
   assert_array_equal(contours[0],
@@ -47,6 +49,16 @@ def test_find_contours():
                       [ 6.5,  1. ],
                       [ 6. ,  1.5]])
 
+def test_float():
+  contours = find_contours(r, 0.5)
+  assert len(contours) == 1
+  assert_array_equal(contours[0],
+                    [[ 2.,  3.],
+                     [ 1.,  2.],
+                     [ 2.,  1.],
+                     [ 3.,  2.],
+                     [ 2.,  3.]])
+
 
     
 if __name__ == '__main__':

skimage/setup.py

@@ -15,7 +15,7 @@ def configuration(parent_package='', top_path=None):
     config.add_subpackage('color')
     config.add_subpackage('draw')
     config.add_subpackage('feature')
-    config.add_subpackage('find_contours')
+    config.add_subpackage('measure')
 
     def add_test_directories(arg, dirname, fnames):
         if dirname.split(os.path.sep)[-1] == 'tests':