diff --git a/skimage/data/mssim_matlab_output.npz b/skimage/data/mssim_matlab_output.npz new file mode 100644 index 00000000..e8585b78 Binary files /dev/null and b/skimage/data/mssim_matlab_output.npz differ diff --git a/skimage/measure/_structural_similarity.py b/skimage/measure/_structural_similarity.py index d3150667..bfe02e6a 100644 --- a/skimage/measure/_structural_similarity.py +++ b/skimage/measure/_structural_similarity.py @@ -3,36 +3,67 @@ from __future__ import division __all__ = ['structural_similarity'] import numpy as np +from scipy.ndimage.filters import uniform_filter, gaussian_filter from ..util.dtype import dtype_range -from ..util.shape import view_as_windows +from ..util.arraypad import crop -def structural_similarity(X, Y, win_size=7, - gradient=False, dynamic_range=None): +def structural_similarity(X, Y, win_size=None, gradient=False, + dynamic_range=None, multichannel=False, + gaussian_weights=False, full=False, **kwargs): """Compute the mean structural similarity index between two images. Parameters ---------- - X, Y : (N,N) ndarray - Images. - win_size : int - The side-length of the sliding window used in comparison. Must - be an odd value. + X, Y : ndarray + Image. Any dimensionality. + win_size : int or None + The side-length of the sliding window used in comparison. Must be an + odd value. If `gaussian_weights` is True, this is ignored and the + window size will depend on `sigma`. gradient : bool If True, also return the gradient. dynamic_range : int - Dynamic range of the input image (distance between minimum and - maximum possible values). By default, this is estimated from - the image data-type. + The dynamic range of the input image (distance between minimum and + maximum possible values). By default, this is estimated from the image + data-type. + multichannel : int or None + If True, treat the last dimension of the array as channels. Similarity + calculations are done independently for each channel then averaged. + gaussian_weights : bool + If True, each patch has its mean and variance spatially weighted by a + normalized Gaussian kernel of width sigma=1.5. + full : bool + If True, return the full structural similarity image instead of the + mean value + + Other Parameters + ---------------- + use_sample_covariance : bool + if True, normalize covariances by N-1 rather than, N where N is the + number of pixels within the sliding window. + K1 : float + algorithm parameter, K1 (small constant, see [1]_) + K2 : float + algorithm parameter, K2 (small constant, see [1]_) + sigma : float + sigma for the Gaussian when `gaussian_weights` is True. Returns ------- - s : float - Structural similarity. - grad : (N * N,) ndarray - Gradient of the structural similarity index between X and Y. + mssim : float or ndarray + The mean structural similarity over the image. + grad : ndarray + The gradient of the structural similarity index between X and Y [2]_. This is only returned if `gradient` is set to True. + S : ndarray + The full SSIM image. This is only returned if `full` is set to True. + + Notes + ----- + To match the implementation of Wang et. al. [1]_, set `gaussian_weights` + to True, `sigma` to 1.5, and `use_sample_covariance` to False. References ---------- @@ -40,6 +71,11 @@ def structural_similarity(X, Y, win_size=7, (2004). Image quality assessment: From error visibility to structural similarity. IEEE Transactions on Image Processing, 13, 600-612. + https://ece.uwaterloo.ca/~z70wang/publications/ssim.pdf + + .. [2] Avanaki, A. N. (2009). Exact global histogram specification + optimized for structural similarity. Optical Review, 16, 613-621. + http://arxiv.org/abs/0901.0065 """ if not X.dtype == Y.dtype: @@ -48,6 +84,61 @@ def structural_similarity(X, Y, win_size=7, if not X.shape == Y.shape: raise ValueError('Input images must have the same dimensions.') + if multichannel: + # loop over channels + args = dict(win_size=win_size, + gradient=gradient, + dynamic_range=dynamic_range, + multichannel=False, + gaussian_weights=gaussian_weights, + full=full) + args.update(kwargs) + nch = X.shape[-1] + mssim = np.empty(nch) + if gradient: + G = np.empty(X.shape) + if full: + S = np.empty(X.shape) + for ch in range(nch): + ch_result = structural_similarity(X[..., ch], Y[..., ch], **args) + if gradient and full: + mssim[..., ch], G[..., ch], S[..., ch] = ch_result + elif gradient: + mssim[..., ch], G[..., ch] = ch_result + elif full: + mssim[..., ch], S[..., ch] = ch_result + else: + mssim[..., ch] = ch_result + mssim = mssim.mean() + if gradient and full: + return mssim, G, S + elif gradient: + return mssim, G + elif full: + return mssim, S + else: + return mssim + + K1 = kwargs.pop('K1', 0.01) + K2 = kwargs.pop('K2', 0.03) + sigma = kwargs.pop('sigma', 1.5) + if K1 < 0: + raise ValueError("K1 must be positive") + if K2 < 0: + raise ValueError("K2 must be positive") + if sigma < 0: + raise ValueError("sigma must be positive") + use_sample_covariance = kwargs.pop('use_sample_covariance', True) + + if win_size is None: + if gaussian_weights: + win_size = 11 # 11 to match Wang et. al. 2004 + else: + win_size = 7 # backwards compatibility + + if np.any((np.asarray(X.shape) - win_size) < 0): + raise ValueError("win_size exceeds image extent") + if not (win_size % 2 == 1): raise ValueError('Window size must be odd.') @@ -55,50 +146,73 @@ def structural_similarity(X, Y, win_size=7, dmin, dmax = dtype_range[X.dtype.type] dynamic_range = dmax - dmin - XW = view_as_windows(X, (win_size, win_size)) - YW = view_as_windows(Y, (win_size, win_size)) + ndim = X.ndim - NS = len(XW) - NP = win_size * win_size + if gaussian_weights: + # sigma = 1.5 to approximately match filter in Wang et. al. 2004 + # this ends up giving a 13-tap rather than 11-tap Gaussian + filter_func = gaussian_filter + filter_args = {'sigma': sigma} - ux = np.mean(np.mean(XW, axis=2), axis=2) - uy = np.mean(np.mean(YW, axis=2), axis=2) + else: + filter_func = uniform_filter + filter_args = {'size': win_size} - # Compute variances var(X), var(Y) and var(X, Y) - cov_norm = 1 / (win_size ** 2 - 1) - XWM = XW - ux[..., None, None] - YWM = YW - uy[..., None, None] - vx = cov_norm * np.sum(np.sum(XWM ** 2, axis=2), axis=2) - vy = cov_norm * np.sum(np.sum(YWM ** 2, axis=2), axis=2) - vxy = cov_norm * np.sum(np.sum(XWM * YWM, axis=2), axis=2) + # ndimage filters need floating point data + X = X.astype(np.float64) + Y = Y.astype(np.float64) + + NP = win_size ** ndim + + # filter has already normalized by NP + if use_sample_covariance: + cov_norm = NP / (NP - 1) # sample covariance + else: + cov_norm = 1.0 # population covariance to match Wang et. al. 2004 + + # compute (weighted) means + ux = filter_func(X, **filter_args) + uy = filter_func(Y, **filter_args) + + # compute (weighted) variances and covariances + uxx = filter_func(X * X, **filter_args) + uyy = filter_func(Y * Y, **filter_args) + uxy = filter_func(X * Y, **filter_args) + vx = cov_norm * (uxx - ux * ux) + vy = cov_norm * (uyy - uy * uy) + vxy = cov_norm * (uxy - ux * uy) R = dynamic_range - K1 = 0.01 - K2 = 0.03 C1 = (K1 * R) ** 2 C2 = (K2 * R) ** 2 - A1, A2, B1, B2 = (v[..., None, None] for v in - (2 * ux * uy + C1, + A1, A2, B1, B2 = ((2 * ux * uy + C1, 2 * vxy + C2, ux ** 2 + uy ** 2 + C1, vx + vy + C2)) + D = B1 * B2 + S = (A1 * A2) / D - S = np.mean((A1 * A2) / (B1 * B2)) + # to avoid edge effects will ignore filter radius strip around edges + pad = (win_size - 1) // 2 + + # compute (weighted) mean of ssim + mssim = crop(S, pad).mean() if gradient: - local_grad = 2 / (NP * B1 ** 2 * B2 ** 2) * \ - (A1 * B1 * (B2 * XW - A2 * YW) - - B1 * B2 * (A2 - A1) * ux[..., None, None] + - A1 * A2 * (B1 - B2) * uy[..., None, None]) - - grad = np.zeros_like(X, dtype=float) - OW = view_as_windows(grad, (win_size, win_size)) - - OW += local_grad - grad /= NS - - return S, grad + # The following is Eqs. 7-8 of Avanaki 2009. + grad = filter_func(A1 / D, **filter_args) * X + grad += filter_func(-S / B2, **filter_args) * Y + grad += filter_func((ux * (A2 - A1) - uy * (B2 - B1) * S) / D, + **filter_args) + grad *= (2 / X.size) + if full: + return mssim, grad, S + else: + return mssim, grad else: - return S + if full: + return mssim, S + else: + return mssim diff --git a/skimage/measure/tests/test_structural_similarity.py b/skimage/measure/tests/test_structural_similarity.py index 35bbeeb8..474e9901 100644 --- a/skimage/measure/tests/test_structural_similarity.py +++ b/skimage/measure/tests/test_structural_similarity.py @@ -1,8 +1,19 @@ +import os import numpy as np -from numpy.testing import assert_equal, assert_raises +import scipy.io +from numpy.testing import (assert_equal, assert_raises, assert_almost_equal, + assert_array_almost_equal) from skimage.measure import structural_similarity as ssim +import skimage.data +from skimage.io import imread +from skimage import data_dir +np.random.seed(5) +cam = skimage.data.camera() +sigma = 20.0 +cam_noisy = np.clip(cam + sigma * np.random.randn(*cam.shape), 0, 255) +cam_noisy = cam_noisy.astype(cam.dtype) np.random.seed(1234) @@ -27,6 +38,17 @@ def test_ssim_image(): S1 = ssim(X, Y, win_size=3) assert(S1 < 0.3) + S2 = ssim(X, Y, win_size=11, gaussian_weights=True) + assert(S1 < 0.3) + + mssim0, S3 = ssim(X, Y, full=True) + assert_equal(S3.shape, X.shape) + mssim = ssim(X, Y) + assert_equal(mssim0, mssim) + + # ssim of image with itself should be 1.0 + assert_equal(ssim(X, X), 1.0) + # NOTE: This test is known to randomly fail on some systems (Mac OS X 10.6) def test_ssim_grad(): @@ -41,6 +63,9 @@ def test_ssim_grad(): assert g[0] < 0.05 assert np.all(g[1] < 0.05) + mssim, grad, s = ssim(X, Y, dynamic_range=255, gradient=True, full=True) + assert np.all(grad < 0.05) + def test_ssim_dtype(): N = 30 @@ -58,6 +83,114 @@ def test_ssim_dtype(): assert S2 < 0.1 +def test_ssim_multichannel(): + N = 100 + X = (np.random.rand(N, N) * 255).astype(np.uint8) + Y = (np.random.rand(N, N) * 255).astype(np.uint8) + + S1 = ssim(X, Y, win_size=3) + + # replicate across three channels. should get identical value + Xc = np.tile(X[..., np.newaxis], (1, 1, 3)) + Yc = np.tile(Y[..., np.newaxis], (1, 1, 3)) + S2 = ssim(Xc, Yc, multichannel=True, win_size=3) + assert_almost_equal(S1, S2) + + # full case should return an image as well + m, S3 = ssim(Xc, Yc, multichannel=True, full=True) + assert_equal(S3.shape, Xc.shape) + + # gradient case + m, grad = ssim(Xc, Yc, multichannel=True, gradient=True) + assert_equal(grad.shape, Xc.shape) + + # full and gradient case + m, grad, S3 = ssim(Xc, Yc, multichannel=True, full=True, gradient=True) + assert_equal(grad.shape, Xc.shape) + assert_equal(S3.shape, Xc.shape) + + # fail if win_size exceeds any non-channel dimension + assert_raises(ValueError, ssim, Xc, Yc, win_size=7, multichannel=False) + + +def test_ssim_nD(): + # test 1D through 4D on small random arrays + N = 10 + for ndim in range(1, 5): + xsize = [N, ] * 5 + X = (np.random.rand(*xsize) * 255).astype(np.uint8) + Y = (np.random.rand(*xsize) * 255).astype(np.uint8) + + mssim = ssim(X, Y, win_size=3) + assert mssim < 0.05 + + +def test_ssim_multichannel_chelsea(): + # color image example + Xc = skimage.data.chelsea() + sigma = 15.0 + Yc = np.clip(Xc + sigma * np.random.randn(*Xc.shape), 0, 255) + Yc = Yc.astype(Xc.dtype) + + # multichannel result should be mean of the individual channel results + mssim = ssim(Xc, Yc, multichannel=True) + mssim_sep = [ssim(Yc[..., c], Xc[..., c]) for c in range(Xc.shape[-1])] + assert_almost_equal(mssim, np.mean(mssim_sep)) + + # ssim of image with itself should be 1.0 + assert_equal(ssim(Xc, Xc, multichannel=True), 1.0) + + +def test_gaussian_mssim_vs_IPOL(): + # Tests vs. imdiff result from the following IPOL article and code: + # http://www.ipol.im/pub/art/2011/g_lmii/ + mssim_IPOL = 0.327309966087341 + mssim = ssim(cam, cam_noisy, gaussian_weights=True, + use_sample_covariance=False) + assert_almost_equal(mssim, mssim_IPOL, decimal=3) + + +def test_gaussian_mssim_vs_author_ref(): + """ + test vs. result from original author's Matlab implementation available at + https://ece.uwaterloo.ca/~z70wang/research/ssim/ + + Matlab test code: + img1 = imread('camera.png') + img2 = imread('camera_noisy.png') + mssim = ssim_index(img1, img2) + """ + mssim_matlab = 0.327314295673357 + mssim = ssim(cam, cam_noisy, gaussian_weights=True, + use_sample_covariance=False) + assert_almost_equal(mssim, mssim_matlab, decimal=3) + + +def test_gaussian_mssim_and_gradient_vs_Matlab(): + # comparison to Matlab implementation of N. Avanaki: + # https://ece.uwaterloo.ca/~nnikvand/Coderep/SHINE%20TOOLBOX/SHINEtoolbox/ + # Note: final line of ssim_sens.m was modified to discard image borders + + ref = np.load(os.path.join(data_dir, 'mssim_matlab_output.npz')) + grad_matlab = ref['grad_matlab'] + mssim_matlab = float(ref['mssim_matlab']) + + mssim, grad = ssim(cam, cam_noisy, gaussian_weights=True, gradient=True, + use_sample_covariance=False) + + assert_almost_equal(mssim, mssim_matlab, decimal=3) + + # check almost equal aside from object borders + assert_array_almost_equal(grad_matlab[5:-5], grad[5:-5]) + + +def test_mssim_vs_legacy(): + # check that ssim with default options matches skimage 0.11 result + mssim_skimage_0pt11 = 0.34192589699605191 + mssim = ssim(cam, cam_noisy) + assert_almost_equal(mssim, mssim_skimage_0pt11) + + def test_invalid_input(): X = np.zeros((3, 3), dtype=np.double) Y = np.zeros((3, 3), dtype=np.int) @@ -68,6 +201,14 @@ def test_invalid_input(): assert_raises(ValueError, ssim, X, X, win_size=8) + # do not allow both image content weighting and gradient calculation + assert_raises(ValueError, ssim, X, X, image_content_weighting=True, + gradient=True) + # some kwarg inputs must be non-negative + assert_raises(ValueError, ssim, X, X, K1=-0.1) + assert_raises(ValueError, ssim, X, X, K2=-0.1) + assert_raises(ValueError, ssim, X, X, sigma=-1.0) + if __name__ == "__main__": np.testing.run_module_suite()