Rename tv_denoise to denoise_tv and deprecate

skimage/filter/__init__.py

@@ -3,6 +3,6 @@ from .ctmf import median_filter
 from ._canny import canny
 from .edges import (sobel, hsobel, vsobel, scharr, hscharr, vscharr, prewitt,
                     hprewitt, vprewitt)
-from .denoise import tv_denoise, denoise_bilateral
+from .denoise import tv_denoise, denoise_tv, denoise_bilateral
 from ._rank_order import rank_order
 from .thresholding import threshold_otsu, threshold_adaptive

skimage/filter/denoise.py

@@ -1,9 +1,10 @@
 import numpy as np
 from skimage import img_as_float
+from skimage._shared.utils import deprecated
 import _denoise
 
 
-def _tv_denoise_3d(im, weight=100, eps=2.e-4, n_iter_max=200):
+def _denoise_tv_3d(im, weight=100, eps=2.e-4, n_iter_max=200):
     """Perform total-variation denoising on 3-D arrays.
 
     Parameters
@@ -38,7 +39,7 @@ def _tv_denoise_3d(im, weight=100, eps=2.e-4, n_iter_max=200):
     >>> mask = (x -22)**2 + (y - 20)**2 + (z - 17)**2 < 8**2
     >>> mask = mask.astype(np.float)
     >>> mask += 0.2*np.random.randn(*mask.shape)
-    >>> res = tv_denoise_3d(mask, weight=100)
+    >>> res = denoise_tv_3d(mask, weight=100)
     """
     px = np.zeros_like(im)
     py = np.zeros_like(im)
@@ -83,7 +84,7 @@ def _tv_denoise_3d(im, weight=100, eps=2.e-4, n_iter_max=200):
     return out
 
 
-def _tv_denoise_2d(im, weight=50, eps=2.e-4, n_iter_max=200):
+def _denoise_tv_2d(im, weight=50, eps=2.e-4, n_iter_max=200):
     """Perform total-variation denoising.
 
     Parameters
@@ -128,7 +129,7 @@ def _tv_denoise_2d(im, weight=50, eps=2.e-4, n_iter_max=200):
     >>> import scipy
     >>> lena = scipy.lena().astype(np.float)
     >>> lena += 0.5 * lena.std()*np.random.randn(*lena.shape)
-    >>> denoised_lena = tv_denoise(lena, weight=60.0)
+    >>> denoised_lena = denoise_tv(lena, weight=60.0)
     """
     px = np.zeros_like(im)
     py = np.zeros_like(im)
@@ -166,7 +167,7 @@ def _tv_denoise_2d(im, weight=50, eps=2.e-4, n_iter_max=200):
     return out
 
 
-def tv_denoise(im, weight=50, eps=2.e-4, n_iter_max=200):
+def denoise_tv(im, weight=50, eps=2.e-4, n_iter_max=200):
     """Perform total-variation denoising on 2-d and 3-d images.
 
     Parameters
@@ -220,28 +221,31 @@ def tv_denoise(im, weight=50, eps=2.e-4, n_iter_max=200):
     >>> import scipy
     >>> lena = scipy.lena().astype(np.float)
     >>> lena += 0.5 * lena.std()*np.random.randn(*lena.shape)
-    >>> denoised_lena = tv_denoise(lena, weight=60)
+    >>> denoised_lena = denoise_tv(lena, weight=60)
     >>> # 3D example on synthetic data
     >>> x, y, z = np.ogrid[0:40, 0:40, 0:40]
     >>> mask = (x -22)**2 + (y - 20)**2 + (z - 17)**2 < 8**2
     >>> mask = mask.astype(np.float)
     >>> mask += 0.2*np.random.randn(*mask.shape)
-    >>> res = tv_denoise_3d(mask, weight=100)
+    >>> res = denoise_tv_3d(mask, weight=100)
     """
     im_type = im.dtype
     if not im_type.kind == 'f':
         im = img_as_float(im)
 
     if im.ndim == 2:
-        out = _tv_denoise_2d(im, weight, eps, n_iter_max)
+        out = _denoise_tv_2d(im, weight, eps, n_iter_max)
     elif im.ndim == 3:
-        out = _tv_denoise_3d(im, weight, eps, n_iter_max)
+        out = _denoise_tv_3d(im, weight, eps, n_iter_max)
     else:
         raise ValueError('only 2-d and 3-d images may be denoised with this '
                          'function')
     return out
 
 
+tv_denoise = deprecated('skimage.filter.denoise_tv')(denoise_tv)
+
+
 def denoise_bilateral(image, win_size=5, sigma_color=1, sigma_range=1, bins=1e4,
                       mode='constant', cval=0):
     """Denoise image using bilateral filter.

skimage/filter/tests/test_denoise.py

@@ -8,7 +8,7 @@ lena = img_as_float(data.lena()[:256, :256])
 lena_gray = color.rgb2gray(lena)
 
 
-def test_tv_denoise_2d():
+def test_denoise_tv_2d():
     # lena image
     img = lena_gray
     # add noise to lena
@@ -16,7 +16,7 @@ def test_tv_denoise_2d():
     # clip noise so that it does not exceed allowed range for float images.
     img = np.clip(img, 0, 1)
     # denoise
-    denoised_lena = filter.tv_denoise(img, weight=60.0)
+    denoised_lena = filter.denoise_tv(img, weight=60.0)
     # which dtype?
     assert denoised_lena.dtype in [np.float, np.float32, np.float64]
     from scipy import ndimage
@@ -29,19 +29,19 @@ def test_tv_denoise_2d():
             < np.sqrt((grad**2).sum()) / 2)
 
 
-def test_tv_denoise_float_result_range():
+def test_denoise_tv_float_result_range():
     # lena image
     img = lena_gray
     int_lena = np.multiply(img, 255).astype(np.uint8)
     assert np.max(int_lena) > 1
-    denoised_int_lena = filter.tv_denoise(int_lena, weight=60.0)
+    denoised_int_lena = filter.denoise_tv(int_lena, weight=60.0)
     # test if the value range of output float data is within [0.0:1.0]
     assert denoised_int_lena.dtype == np.float
     assert np.max(denoised_int_lena) <= 1.0
     assert np.min(denoised_int_lena) >= 0.0
 
 
-def test_tv_denoise_3d():
+def test_denoise_tv_3d():
     """Apply the TV denoising algorithm on a 3D image representing a sphere."""
     x, y, z = np.ogrid[0:40, 0:40, 0:40]
     mask = (x - 22)**2 + (y - 20)**2 + (z - 17)**2 < 8**2
@@ -50,12 +50,12 @@ def test_tv_denoise_3d():
     mask += 20 * np.random.random(mask.shape)
     mask[mask < 0] = 0
     mask[mask > 255] = 255
-    res = filter.tv_denoise(mask.astype(np.uint8), weight=100)
+    res = filter.denoise_tv(mask.astype(np.uint8), weight=100)
     assert res.dtype == np.float
     assert res.std() * 255 < mask.std()
 
     # test wrong number of dimensions
-    assert_raises(ValueError, filter.tv_denoise, np.random.random((8, 8, 8, 8)))
+    assert_raises(ValueError, filter.denoise_tv, np.random.random((8, 8, 8, 8)))
 
 
 def test_denoise_bilateral_2d():