ENH: better docstring and test for warp_coords

skimage/transform/__init__.py

@@ -3,7 +3,7 @@ from .radon_transform import *
 from .finite_radon_transform import *
 from ._project import homography as fast_homography
 from .integral import *
-from ._geometric import (warp, estimate_transform,
+from ._geometric import (warp, warp_coords, estimate_transform,
                          SimilarityTransform, AffineTransform,
                          ProjectiveTransform, PolynomialTransform)
 from ._warps import swirl, homography

skimage/transform/_geometric.py

@@ -699,19 +699,28 @@ def matrix_transform(coords, matrix):
 
 
 def warp_coords(orows, ocols, bands, coord_transform_fn,
-        dtype='float64'):
-    """
-    Return `coords` ndarray suitable for `scipy.ndimage.map_coordinates`, which will yield an
-    image of shape (orows, ocols, bands) by drawing from source points according to the
-    `coord_transform_fn`.
+                dtype=np.float64):
+    """Build the source coordinates for the output pixels of an image warp.
 
     Parameters
     ----------
-    orows: number of output rows
-    ocols: number of output columns
-    bands: number of color bands (aka channels)
-    coord_transform_fn: something like GeometricTransform.inverse_map
-    dtype: dtype for return value (should probably be 'float32' or 'float64')
+    orows : int
+        number of output rows
+    ocols : int
+        number of output columns
+    bands : int
+        number of color bands (aka channels)
+    coord_transform_fn : callable like GeometricTransform.inverse_map
+        Return input coordinates for given output coordinates
+    dtype : np.dtype or string
+        dtype for return value (sane choices: float32 or float64)
+
+    Returns
+    -------
+    coords : (orows * ocols, ) array 
+            Coordinates for `scipy.ndimage.map_coordinates`, that will yield
+            an image of shape (orows, ocols, bands) by drawing from source
+            points according to the `coord_transform_fn`.
 
     Notes
     -----

skimage/transform/tests/test_warps.py

@@ -2,7 +2,7 @@ import sys
 from numpy.testing import assert_array_almost_equal, run_module_suite
 import numpy as np
 
-from skimage.transform import (warp, fast_homography,
+from skimage.transform import (warp, warp_coords, fast_homography,
                                AffineTransform,
                                ProjectiveTransform,
                                SimilarityTransform)
@@ -115,5 +115,21 @@ def test_warp_identity():
     assert np.all(0 == warped_rgb_lena[:, :, 1])
 
 
+def test_warp_coords_example():
+    from skimage import data
+    from scipy.ndimage import map_coordinates
+    def shift_right(xy):
+        print 'xyshape', xy.shape
+        xy[:, 0] -= 10
+        return xy
+
+    image = data.lena().astype(np.float32)
+    print 'testing'
+    print image.dtype, image.shape
+    coords = warp_coords(512, 512, 3, shift_right)
+    print 'warp_coords', coords.dtype, coords.shape
+    warped_image = map_coordinates(coords, image)
+
+
 if __name__ == "__main__":
     run_module_suite()