restoration
¶Image restoration module.
[R303]  François Orieux, JeanFrançois Giovannelli, and Thomas Rodet, “Bayesian estimation of regularization and point spread function parameters for WienerHunt deconvolution”, J. Opt. Soc. Am. A 27, 15931607 (2010) http://www.opticsinfobase.org/josaa/abstract.cfm?URI=josaa2771593 
[R304]  Richardson, William Hadley, “BayesianBased Iterative Method of Image Restoration”. JOSA 62 (1): 55–59. doi:10.1364/JOSA.62.000055, 1972 
[R305]  B. R. Hunt “A matrix theory proof of the discrete convolution theorem”, IEEE Trans. on Audio and Electroacoustics, vol. au19, no. 4, pp. 285288, dec. 1971 
skimage.restoration.denoise_bilateral (image) 
Denoise image using bilateral filter. 
skimage.restoration.denoise_nl_means (image) 
Perform nonlocal means denoising on 2D or 3D grayscale images, and 2D RGB images. 
skimage.restoration.denoise_tv_bregman (...) 
Perform totalvariation denoising using splitBregman optimization. 
skimage.restoration.denoise_tv_chambolle (im) 
Perform totalvariation denoising on ndimensional images. 
skimage.restoration.inpaint_biharmonic (img, mask) 
Inpaint masked points in image with biharmonic equations. 
skimage.restoration.nl_means_denoising (...) 
Deprecated function. Use skimage.restoration.denoise_nl_means instead. 
skimage.restoration.richardson_lucy (image, psf) 
RichardsonLucy deconvolution. 
skimage.restoration.unsupervised_wiener (...) 
Unsupervised WienerHunt deconvolution. 
skimage.restoration.unwrap_phase (image[, ...]) 
Recover the original from a wrapped phase image. 
skimage.restoration.wiener (image, psf, balance) 
WienerHunt deconvolution 
skimage.restoration.
denoise_bilateral
(image, win_size=None, sigma_color=None, sigma_spatial=1, bins=10000, mode='constant', cval=0, multichannel=True, sigma_range=None)[source]¶Denoise image using bilateral filter.
This is an edgepreserving and noise reducing denoising filter. It averages pixels based on their spatial closeness and radiometric similarity.
Spatial closeness is measured by the gaussian function of the euclidian distance between two pixels and a certain standard deviation (sigma_spatial).
Radiometric similarity is measured by the gaussian function of the euclidian distance between two color values and a certain standard deviation (sigma_color).
Parameters:  image : ndarray, shape (M, N[, 3])
win_size : int
sigma_color : float
sigma_spatial : float
bins : int
mode : {‘constant’, ‘edge’, ‘symmetric’, ‘reflect’, ‘wrap’}
cval : string
multichannel : bool


Returns:  denoised : ndarray

References
[R325]  http://users.soe.ucsc.edu/~manduchi/Papers/ICCV98.pdf 
Examples
>>> from skimage import data, img_as_float
>>> astro = img_as_float(data.astronaut())
>>> astro = astro[220:300, 220:320]
>>> noisy = astro + 0.6 * astro.std() * np.random.random(astro.shape)
>>> noisy = np.clip(noisy, 0, 1)
>>> denoised = denoise_bilateral(noisy, sigma_color=0.05, sigma_spatial=15)
skimage.restoration.
denoise_nl_means
(image, patch_size=7, patch_distance=11, h=0.1, multichannel=True, fast_mode=True)[source]¶Perform nonlocal means denoising on 2D or 3D grayscale images, and 2D RGB images.
Parameters:  image : 2D or 3D ndarray
patch_size : int, optional
patch_distance : int, optional
h : float, optional
multichannel : bool, optional
fast_mode : bool, optional


Returns:  result : ndarray

Notes
The nonlocal means algorithm is well suited for denoising images with specific textures. The principle of the algorithm is to average the value of a given pixel with values of other pixels in a limited neighbourhood, provided that the patches centered on the other pixels are similar enough to the patch centered on the pixel of interest.
In the original version of the algorithm [R326], corresponding to
fast=False
, the computational complexity is
image.size * patch_size ** image.ndim * patch_distance ** image.ndim
Hence, changing the size of patches or their maximal distance has a strong effect on computing times, especially for 3D images.
However, the default behavior corresponds to fast_mode=True
, for which
another version of nonlocal means [R327] is used, corresponding to a
complexity of
image.size * patch_distance ** image.ndim
The computing time depends only weakly on the patch size, thanks to
the computation of the integral of patches distances for a given
shift, that reduces the number of operations [R326]. Therefore, this
algorithm executes faster than the classic algorith
(fast_mode=False
), at the expense of using twice as much memory.
This implementation has been proven to be more efficient compared to
other alternatives, see e.g. [R328].
Compared to the classic algorithm, all pixels of a patch contribute to the distance to another patch with the same weight, no matter their distance to the center of the patch. This coarser computation of the distance can result in a slightly poorer denoising performance. Moreover, for small images (images with a linear size that is only a few times the patch size), the classic algorithm can be faster due to boundary effects.
The image is padded using the reflect mode of skimage.util.pad before denoising.
References
[R326]  (1, 2, 3) Buades, A., Coll, B., & Morel, J. M. (2005, June). A nonlocal algorithm for image denoising. In CVPR 2005, Vol. 2, pp. 6065, IEEE. 
[R327]  (1, 2) J. Darbon, A. Cunha, T.F. Chan, S. Osher, and G.J. Jensen, Fast nonlocal filtering applied to electron cryomicroscopy, in 5th IEEE International Symposium on Biomedical Imaging: From Nano to Macro, 2008, pp. 13311334. 
[R328]  (1, 2) Jacques Froment. ParameterFree Fast Pixelwise NonLocal Means Denoising. Image Processing On Line, 2014, vol. 4, p. 300326. 
Examples
>>> a = np.zeros((40, 40))
>>> a[10:10, 10:10] = 1.
>>> a += 0.3 * np.random.randn(*a.shape)
>>> denoised_a = denoise_nl_means(a, 7, 5, 0.1)
skimage.restoration.
denoise_tv_bregman
(image, weight, max_iter=100, eps=0.001, isotropic=True)[source]¶Perform totalvariation denoising using splitBregman optimization.
Totalvariation denoising (also know as totalvariation regularization) tries to find an image with less totalvariation under the constraint of being similar to the input image, which is controlled by the regularization parameter.
Parameters:  image : ndarray
weight : float
eps : float, optional
max_iter : int, optional
isotropic : boolean, optional


Returns:  u : ndarray

References
[R329]  http://en.wikipedia.org/wiki/Total_variation_denoising 
[R330]  Tom Goldstein and Stanley Osher, “The Split Bregman Method For L1 Regularized Problems”, ftp://ftp.math.ucla.edu/pub/camreport/cam0829.pdf 
[R331]  Pascal Getreuer, “Rudin–Osher–Fatemi Total Variation Denoising using Split Bregman” in Image Processing On Line on 2012–05–19, http://www.ipol.im/pub/art/2012/gtvd/article_lr.pdf 
[R332]  http://www.math.ucsb.edu/~cgarcia/UGProjects/BregmanAlgorithms_JacquelineBush.pdf 
skimage.restoration.
denoise_tv_chambolle
(im, weight=0.1, eps=0.0002, n_iter_max=200, multichannel=False)[source]¶Perform totalvariation denoising on ndimensional images.
Parameters:  im : ndarray of ints, uints or floats
weight : float, optional
eps : float, optional
n_iter_max : int, optional
multichannel : bool, optional


Returns:  out : ndarray

Notes
Make sure to set the multichannel parameter appropriately for color images.
The principle of total variation denoising is explained in http://en.wikipedia.org/wiki/Total_variation_denoising
The principle of total variation denoising is to minimize the total variation of the image, which can be roughly described as the integral of the norm of the image gradient. Total variation denoising tends to produce “cartoonlike” images, that is, piecewiseconstant images.
This code is an implementation of the algorithm of Rudin, Fatemi and Osher that was proposed by Chambolle in [R333].
References
[R333]  (1, 2) A. Chambolle, An algorithm for total variation minimization and applications, Journal of Mathematical Imaging and Vision, Springer, 2004, 20, 8997. 
Examples
2D example on astronaut image:
>>> from skimage import color, data
>>> img = color.rgb2gray(data.astronaut())[:50, :50]
>>> img += 0.5 * img.std() * np.random.randn(*img.shape)
>>> denoised_img = denoise_tv_chambolle(img, weight=60)
3D example on synthetic data:
>>> x, y, z = np.ogrid[0:20, 0:20, 0:20]
>>> 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 = denoise_tv_chambolle(mask, weight=100)
skimage.restoration.
inpaint_biharmonic
(img, mask, multichannel=False)[source]¶Inpaint masked points in image with biharmonic equations.
Parameters:  img : (M[, N[, ..., P]][, C]) ndarray
mask : (M[, N[, ..., P]]) ndarray
multichannel : boolean, optional


Returns:  out : (M[, N[, ..., P]][, C]) ndarray

References
[R334]  N.S.Hoang, S.B.Damelin, “On surface completion and image inpainting by biharmonic functions: numerical aspects”, http://www.ima.umn.edu/~damelin/biharmonic 
Examples
>>> img = np.tile(np.square(np.linspace(0, 1, 5)), (5, 1))
>>> mask = np.zeros_like(img)
>>> mask[2, 2:] = 1
>>> mask[1, 3:] = 1
>>> mask[0, 4:] = 1
>>> out = inpaint_biharmonic(img, mask)
skimage.restoration.
nl_means_denoising
(*args, **kwargs)[source]¶Deprecated function. Use skimage.restoration.denoise_nl_means
instead.
Perform nonlocal means denoising on 2D or 3D grayscale images, and 2D RGB images.
Parameters:  image : 2D or 3D ndarray
patch_size : int, optional
patch_distance : int, optional
h : float, optional
multichannel : bool, optional
fast_mode : bool, optional


Returns:  result : ndarray

Notes
The nonlocal means algorithm is well suited for denoising images with specific textures. The principle of the algorithm is to average the value of a given pixel with values of other pixels in a limited neighbourhood, provided that the patches centered on the other pixels are similar enough to the patch centered on the pixel of interest.
In the original version of the algorithm [R335], corresponding to
fast=False
, the computational complexity is
image.size * patch_size ** image.ndim * patch_distance ** image.ndim
Hence, changing the size of patches or their maximal distance has a strong effect on computing times, especially for 3D images.
However, the default behavior corresponds to fast_mode=True
, for which
another version of nonlocal means [R336] is used, corresponding to a
complexity of
image.size * patch_distance ** image.ndim
The computing time depends only weakly on the patch size, thanks to
the computation of the integral of patches distances for a given
shift, that reduces the number of operations [R335]. Therefore, this
algorithm executes faster than the classic algorith
(fast_mode=False
), at the expense of using twice as much memory.
This implementation has been proven to be more efficient compared to
other alternatives, see e.g. [R337].
Compared to the classic algorithm, all pixels of a patch contribute to the distance to another patch with the same weight, no matter their distance to the center of the patch. This coarser computation of the distance can result in a slightly poorer denoising performance. Moreover, for small images (images with a linear size that is only a few times the patch size), the classic algorithm can be faster due to boundary effects.
The image is padded using the reflect mode of skimage.util.pad before denoising.
References
[R335]  (1, 2, 3) Buades, A., Coll, B., & Morel, J. M. (2005, June). A nonlocal algorithm for image denoising. In CVPR 2005, Vol. 2, pp. 6065, IEEE. 
[R336]  (1, 2) J. Darbon, A. Cunha, T.F. Chan, S. Osher, and G.J. Jensen, Fast nonlocal filtering applied to electron cryomicroscopy, in 5th IEEE International Symposium on Biomedical Imaging: From Nano to Macro, 2008, pp. 13311334. 
[R337]  (1, 2) Jacques Froment. ParameterFree Fast Pixelwise NonLocal Means Denoising. Image Processing On Line, 2014, vol. 4, p. 300326. 
Examples
>>> a = np.zeros((40, 40))
>>> a[10:10, 10:10] = 1.
>>> a += 0.3 * np.random.randn(*a.shape)
>>> denoised_a = denoise_nl_means(a, 7, 5, 0.1)
skimage.restoration.
richardson_lucy
(image, psf, iterations=50, clip=True)[source]¶RichardsonLucy deconvolution.
Parameters:  image : ndarray
psf : ndarray
iterations : int
clip : boolean, optional


Returns:  im_deconv : ndarray

References
[R338]  http://en.wikipedia.org/wiki/Richardson%E2%80%93Lucy_deconvolution 
Examples
>>> from skimage import color, data, restoration
>>> camera = color.rgb2gray(data.camera())
>>> from scipy.signal import convolve2d
>>> psf = np.ones((5, 5)) / 25
>>> camera = convolve2d(camera, psf, 'same')
>>> camera += 0.1 * camera.std() * np.random.standard_normal(camera.shape)
>>> deconvolved = restoration.richardson_lucy(camera, psf, 5)
skimage.restoration.
unsupervised_wiener
(image, psf, reg=None, user_params=None, is_real=True, clip=True)[source]¶Unsupervised WienerHunt deconvolution.
Return the deconvolution with a WienerHunt approach, where the
hyperparameters are automatically estimated. The algorithm is a
stochastic iterative process (Gibbs sampler) described in the
reference below. See also wiener
function.
Parameters:  image : (M, N) ndarray
psf : ndarray
reg : ndarray, optional
user_params : dict
clip : boolean, optional


Returns:  x_postmean : (M, N) ndarray
chains : dict

Other Parameters:  
The keys of ``user_params`` are: threshold : float
burnin : int
min_iter : int
max_iter : int
callback : callable (None by default)

Notes
The estimated image is design as the posterior mean of a probability law (from a Bayesian analysis). The mean is defined as a sum over all the possible images weighted by their respective probability. Given the size of the problem, the exact sum is not tractable. This algorithm use of MCMC to draw image under the posterior law. The practical idea is to only draw highly probable images since they have the biggest contribution to the mean. At the opposite, the less probable images are drawn less often since their contribution is low. Finally the empirical mean of these samples give us an estimation of the mean, and an exact computation with an infinite sample set.
References
[R339]  François Orieux, JeanFrançois Giovannelli, and Thomas Rodet, “Bayesian estimation of regularization and point spread function parameters for WienerHunt deconvolution”, J. Opt. Soc. Am. A 27, 15931607 (2010) http://www.opticsinfobase.org/josaa/abstract.cfm?URI=josaa2771593 
Examples
>>> from skimage import color, data, restoration
>>> img = color.rgb2gray(data.astronaut())
>>> from scipy.signal import convolve2d
>>> psf = np.ones((5, 5)) / 25
>>> img = convolve2d(img, psf, 'same')
>>> img += 0.1 * img.std() * np.random.standard_normal(img.shape)
>>> deconvolved_img = restoration.unsupervised_wiener(img, psf)
skimage.restoration.
unwrap_phase
(image, wrap_around=False, seed=None)[source]¶Recover the original from a wrapped phase image.
From an image wrapped to lie in the interval [pi, pi), recover the original, unwrapped image.
Parameters:  image : 1D, 2D or 3D ndarray of floats, optionally a masked array
wrap_around : bool or sequence of bool, optional
seed : int, optional


Returns:  image_unwrapped : array_like, double

Raises:  ValueError

References
[R340]  Miguel Arevallilo Herraez, David R. Burton, Michael J. Lalor, and Munther A. Gdeisat, “Fast twodimensional phaseunwrapping algorithm based on sorting by reliability following a noncontinuous path”, Journal Applied Optics, Vol. 41, No. 35 (2002) 7437, 
[R341]  AbdulRahman, H., Gdeisat, M., Burton, D., & Lalor, M., “Fast threedimensional phaseunwrapping algorithm based on sorting by reliability following a noncontinuous path. In W. Osten, C. Gorecki, & E. L. Novak (Eds.), Optical Metrology (2005) 32–40, International Society for Optics and Photonics. 
Examples
>>> c0, c1 = np.ogrid[1:1:128j, 1:1:128j]
>>> image = 12 * np.pi * np.exp((c0**2 + c1**2))
>>> image_wrapped = np.angle(np.exp(1j * image))
>>> image_unwrapped = unwrap_phase(image_wrapped)
>>> np.std(image_unwrapped  image) < 1e6 # A constant offset is normal
True
skimage.restoration.
wiener
(image, psf, balance, reg=None, is_real=True, clip=True)[source]¶WienerHunt deconvolution
Return the deconvolution with a WienerHunt approach (i.e. with Fourier diagonalisation).
Parameters:  image : (M, N) ndarray
psf : ndarray
balance : float
reg : ndarray, optional
is_real : boolean, optional
clip : boolean, optional


Returns:  im_deconv : (M, N) ndarray

Notes
This function applies the Wiener filter to a noisy and degraded image by an impulse response (or PSF). If the data model is
y = Hx + n
where n is noise, H the PSF and x the unknown original image, the Wiener filter is
\hat x = F^\dag (\Lambda_H^2 + \lambda \Lambda_D^2) \Lambda_H^\dag F y
where F and F^\dag are the Fourier and inverse Fourier transfroms respectively, \Lambda_H the transfer function (or the Fourier transfrom of the PSF, see [Hunt] below) and \Lambda_D the filter to penalize the restored image frequencies (Laplacian by default, that is penalization of high frequency). The parameter \lambda tunes the balance between the data (that tends to increase high frequency, even those coming from noise), and the regularization.
These methods are then specific to a prior model. Consequently, the application or the true image nature must corresponds to the prior model. By default, the prior model (Laplacian) introduce image smoothness or pixel correlation. It can also be interpreted as highfrequency penalization to compensate the instability of the solution with respect to the data (sometimes called noise amplification or “explosive” solution).
Finally, the use of Fourier space implies a circulant property of H, see [Hunt].
References
[R342]  François Orieux, JeanFrançois Giovannelli, and Thomas Rodet, “Bayesian estimation of regularization and point spread function parameters for WienerHunt deconvolution”, J. Opt. Soc. Am. A 27, 15931607 (2010) http://www.opticsinfobase.org/josaa/abstract.cfm?URI=josaa2771593 
[R343]  B. R. Hunt “A matrix theory proof of the discrete convolution theorem”, IEEE Trans. on Audio and Electroacoustics, vol. au19, no. 4, pp. 285288, dec. 1971 
Examples
>>> from skimage import color, data, restoration
>>> img = color.rgb2gray(data.astronaut())
>>> from scipy.signal import convolve2d
>>> psf = np.ones((5, 5)) / 25
>>> img = convolve2d(img, psf, 'same')
>>> img += 0.1 * img.std() * np.random.standard_normal(img.shape)
>>> deconvolved_img = restoration.wiener(img, psf, 1100)