Utility functions

This module contains several utility functions which can be used e.g. for thresholding the alpha-shearlet coefficients or for using the alpha-shearlet transform for denoising.

Finally, it also contains the functions my_ravel() and my_unravel() which can be used to convert the alpha-shearlet coefficients into a 1-dimensional vector and back. This is in particular convenient for the subsampled transform, where this conversion is not entirely trivial, since the different “coefficient images” have varying dimensions.

Thresholding

AlphaTransformUtility.threshold(coeffs, thresh_value, mode)

Given a set of coefficients, this function performs a thresholding procedure, i.e., either soft or hard thresholding.

Required parameters

Parameters:
  • coeffs –

    The coefficients to be thresholded.

    Either a three-dimensional numpy.ndarray or a generator producing two dimensional numpy.ndarray objects.

  • thresh_value (float) – The thresholding cutoff c for the coefficients, see also mode for more details.
  • mode (string) –

    Either 'hard' or 'soft'. This parameter determines whether the hard thresholding operator

    \Lambda_cx =\begin{cases} x, & \text{if }|x|\geq c,\\ 0, & \text{if }|x|<c, \end{cases}

    or the soft thresholding operator

    \Lambda_cx =\begin{cases} x\cdot \frac{|x|-c}{|x|}, & \text{if }|x|\geq c,\\ 0, & \text{if }|x|<c \end{cases}

    is applied to each entry of the coefficients.

Return value

Returns:A generator producing the thresholded coefficients. Each thresholded “coefficient image”, i.e., each thresholded 2-dimensional array, is produced in turn.

Denoising

AlphaTransformUtility.denoise(img, trafo, noise_lvl, multipliers=None)

Given a noisy image \tilde f, this function performs a denoising procedure based on shearlet thresholding. More precisely:

  1. A scale dependent threshold parameter c=(c_j)_j is calculated according to c_j=m_j\cdot \lambda / \sqrt{N_1\cdot N_2}, where m_j is a multiplier for the jth scale, \lambda is the noise level present in the image \tilde f and N_1\times N_2 are its dimensions.
  2. The alpha-shearlet transform of \tilde f is calculated using trafo.
  3. Hard thesholding with threshold parameter (cutoff) c is performed on alpha-shearlet coefficients, i.e., for each scale j, each of the coefficients belonging to the jth scale is set to zero if its absolute value is smaller than c_j and otherwise it is left unchanged.
  4. The (pseudo)-inverse of the alpha-shearlet transform is applied to the thresholded coefficients and this reconstruction is the return value of the function.

Required parameters

Parameters:
  • img (numpy.ndarray) – The “image” (2 dimensional array) that should be denoised.
  • trafo –

    An object of class AlphaTransform.AlphaShearletTransform. This object is used to calculate the (inverse) alpha-shearlet transform during the denoising procedure.

    The dimension of the transform and of img need to coincide.

  • noise_lvl (float) –

    The (presumed) noise level present in img. If img = img_clean + noise, then noise_lvl should be approximately equal to the \ell^2 norm of noise.

    In particular, if im is obtained by adding Gaussian noise with standard deviation \sigma (in each entry) to a noise free image f, then the noise level \lambda is given by \lambda= \sigma\cdot \sqrt{N_1\cdot N_2}; see also AdaptiveAlpha.optimize_denoising().

Keyword parameter

Parameters:multipliers (list) –

A list of multipliers (floats) for each scale. multipliers[j] determines the value of m_j and thus of the cutoff c_j = m_j \cdot \lambda / \sqrt{N_1 \cdot N_2} for scale j.

In particular, len(multipliers) needs to be equal to the number of the scales of trafo.

Return value

Returns:The denoised image, i.e., the result of the denoising procedure described above.

Vectorizing the alpha-shearlet coefficients

AlphaTransformUtility.my_ravel(coeff)

The subsampled alpha-shearlet transform returns a list of differently sized(!) two-dimensional arrays. Likewise, the fully sampled transform yields a three dimensional numpy array containing the coefficients. The present function can be used (in both cases) to convert this list into a single one-dimensional numpy array.

Note

In order to invert this conversion to a one-dimensional array, use the associated function my_unravel(). Precisely, my_unravel() satisfies my_unravel(my_trafo, my_ravel(coeff)) == coeff, if coeff is obtained from calling my_trafo.transform(im) for some image im.

The preceding equality holds at least up to (negligible) differences (the left-hand side is a generator while the right-hand side could also be a list).

Required parameter

Parameters:coeff (list) – A list (or a generator) containing/producing two-dimensional numpy arrays.

Return value

Returns:A one-dimensional numpy.ndarray from which coeff can be reconstructed.
AlphaTransformUtility.my_unravel(trafo, coeff)

This method is a companion method to my_ravel(). See the documentation of that function for more details.

Required parameters

Parameters:
  • trafo – An object of class AlphaTransform.AlphaShearletTransform.
  • coeff (numpy.ndarray) – A one-dimensional numpy array, obtained via my_ravel(coeff_unrav), where coeff_unrav is of the same dimensions as the output of trafo.transform(im), where im is an image.

Return value

Returns:A generator producing the same values as coeff_unrav, i.e., an “unravelled” version of coeff.

Miscelaneous utility functions

AlphaTransformUtility.find_free_file(file_template)

This function finds the first nonexistent (“free”) file obtained by “counting upwards” using the passed template/pattern.

Required Parameter

Parameters:file_template (string) –

This should be a string whose format() method can be called using only an integer argument, e.g. '/home/test_{0:0>2d}.txt', which would result in find_free_file consecutively checking the following files for existence:

/home/test_00.txt, /home/test_01.txt, ...

Return value

Returns:file_template.format(i) for the first value of i for which the corresponding file does not yet exist.
AlphaTransformUtility.scale_gen(trafo)

Required parameter

Parameters:trafo – An object of class AlphaTransform.AlphaShearletTransform.

Return value

Returns:A generator producing integers. The i-th produced integer is the scale (starting from -1 for the low-pass part) of the i-th alpha-shearlet associated to trafo.

Hence, if coeff = trafo.transform(im), then the following iteration produces the associated scale to each “coefficient image”:

for scale, c in zip(scale_gen(trafo), coeff):
    ...
AlphaTransformUtility.image_load(path)

Given a ‘.npy’ or ‘.png’ file, this function loads the file and returns its content as a two-dimensional numpy.ndarray of float values.

For ‘.png’ images, the pixel values are normalized to be between 0 and 1 (instead of between 0 and 255) and color images are converted to grey-scale.

Required parameter

Parameters:path (string) – Path to the image to be converted, either of a ‘.png’ or ‘.npy’ file.

Return value

Returns:The loaded image as a two-dimensional numpy.ndarray.