High-Level Algorithms

High level interfaces to the different algorithms and methods. Using algorithms from optimize we get denoising, inpainting etc

Training

class dictlearn.algorithms.Trainer(signals, method='online', regularization='l0')
Parameters:
  • signals – Training data, shape (n_features, n_samples)
  • method – Training algorithm, ‘online’ or ‘batch’
  • regularization – ‘l0’ or ‘l1’, ‘l0’ is faster, but ‘l1’ can sometimes be more accurate
train(dictionary=None, n_atoms=None, iters=None, n_nonzero=10, tolerance=0, n_threads=1, verbose=False, **kwargs)

Train a dictionary on training signals using ‘Online Dictionary Learning (ODL)’ or ‘K-SVD’.

Both methods update the dictionary once very iteration. ODL will find the sparse coding on one signal and then update the dictionary using a variant of block coordinate-descent with momentum. K-SVD will sparse code all signals before doing the dictionary update, thus every iteration of K-SVD is a lot slower. Both produces similar results given the same running time

Parameters:
  • dictionary – Optional. Dictionary, ndarray with shape (signal_size, n_atoms)
  • n_atoms – Number of dictionary atoms, default 2*signal_size
  • iters – Training iterations, default 10 if ‘batch’, 1000 for ‘online’
  • n_nonzero – Max number of nonzero coefficients in sparse codes. Default 10
  • tolerance – Sparse coding tolerance. Adds coefficients to the sparse approximation until the tolerance is achieved, or all coefficients are active
  • n_threads – Number of threads to use. Default 1
  • verbose – Print progress if True. Default False
class dictlearn.algorithms.ImageTrainer(image, patch_size=8, method='online', regularization='l0')
Parameters:
  • image – Train dictionary on this image (data). Can be a path to image, numpy array, dl.Patches or dl.Patches3D. If path or numpy array then dl.Patches are created. If the image is to large for keeping all image patches in memory pass dl.Patches3D instance
  • patch_size – Size of image patches
  • method – Method for training, ‘online’, or ‘batch’
  • regularization – Regularization to use, ‘l0’ or ‘l1’
train(dictionary=None, n_atoms=None, iters=None, n_nonzero=10, tolerance=0, n_threads=1, verbose=False, **kwargs)

Train a dictionary on training signals using ‘Online Dictionary Learning (ODL)’ or ‘K-SVD’.

Both methods update the dictionary once very iteration. ODL will find the sparse coding on one signal and then update the dictionary using a variant of block coordinate-descent with momentum. K-SVD will sparse code all signals before doing the dictionary update, thus every iteration of K-SVD is a lot slower. Both produces similar results given the same running time

Parameters:
  • dictionary – Optional. Dictionary, ndarray with shape (signal_size, n_atoms)
  • n_atoms – Number of dictionary atoms, default 2*signal_size
  • iters – Training iterations, default 10 if ‘batch’, 1000 for ‘online’
  • n_nonzero – Max number of nonzero coefficients in sparse codes. Default 10
  • tolerance – Sparse coding tolerance. Adds coefficients to the sparse approximation until the tolerance is achieved, or all coefficients are active
  • n_threads – Number of threads to use. Default 1
  • verbose – Print progress if True. Default False

Denoise

class dictlearn.algorithms.Denoise(image, patch_size=8, method='online', regularization='l0')

Image Denoising with Dictionary Learning

Train a dictionary on the noisy image, then denoise using sparse coding. If method = ‘ksvd’ a dictionary is learned using K-SVD and the image is denoised using the sparse coefficients from the last training iteration. If method = ‘batch’ or ‘online’ an additional sparse coding step is used to compute the sparse codes for denoising.

Both adaptive and static denoising is supported.

Example adaptive denoise:

>>> denoiser = Denoise('noisy/image.png', 12)
>>> denoiser.train(iters=5000, n_nonzero=2, n_atoms=256)
>>> cleaned = denoiser.denoise(sigma=30)

Example pre-trained (static) dictionary:

>>> import numpy as np
>>> dictionary = np.load('dictionary.npy')
>>> denoiser = Denoise('noisy/image.png', 12)
>>> denoiser.dictionary = dictionary
>>> denoiser.train()  # Optional training
>>> cleaned = denoiser.denoise(sigma=30)

The size of the image patches and sigma in denoise() will have a large effect on the denoised image. If either are too large the image will look blurry, if too low the difference between the original noisy image and the denoised image will be small. A patch size in [8, 12] is usually a good choice for most images. If the image has very small details then a smaller patch size might be needed. If the structures in the image are large and smooth, larger patches can produce better results.

The value of sigma is highly dependent on the image and its scale. If the image is in [0, 1] then 0 <= sigma <= 1. An image in [0, 255] gives sigma in [0, 255].

Parameters:
  • image – Noisy image. Can be a path to image, numpy array, dl.Patches or dl.Patches3D. If path or numpy array then dl.Patches are created. If the image is to large for keeping all image patches in memory pass dl.Patches3D instance
  • patch_size – Size of image patches
  • method – Method for training, ‘online’, ‘batch’ or ‘ksvd’
  • regularization – Regularization to use, ‘l0’ or ‘l1’
denoise(sigma=20, n_threads=1, noise_gain=1.15)

Denoise the image

Sigma is the parameter that has the largest effect on the final result. For the best results sigma should be close to the variance of the noise. If the difference between the original and the denoised image is small sigma is probably too low. If the denoised image is very blurry then sigma is too large.

Blurry image? Reduce sigma

Noisy image? Increase sigma

Parameters:
  • sigma – Noise variance
  • n_threads – Number of threads. Default 1
  • noise_gain – Average number of nonzero coefficients in sparse approximation. Default 1.15, which has been shown to give good results.
Returns:

Reconstructed and denoised image
train(dictionary=None, n_atoms=None, iters=None, n_nonzero=10, tolerance=0, n_threads=1, verbose=False, **kwargs)

Train a dictionary on training signals using ‘Online Dictionary Learning (ODL)’ or ‘K-SVD’.

Both methods update the dictionary once very iteration. ODL will find the sparse coding on one signal and then update the dictionary using a variant of block coordinate-descent with momentum. K-SVD will sparse code all signals before doing the dictionary update, thus every iteration of K-SVD is a lot slower. Both produces similar results given the same running time

Parameters:
  • dictionary – Optional. Dictionary, ndarray with shape (signal_size, n_atoms)
  • n_atoms – Number of dictionary atoms, default 2*signal_size
  • iters – Training iterations, default 10 if ‘batch’, 1000 for ‘online’
  • n_nonzero – Max number of nonzero coefficients in sparse codes. Default 10
  • tolerance – Sparse coding tolerance. Adds coefficients to the sparse approximation until the tolerance is achieved, or all coefficients are active
  • n_threads – Number of threads to use. Default 1
  • verbose – Print progress if True. Default False

Inpaint

class dictlearn.algorithms.Inpaint(image, mask, patch_size=8, method='online')

Image inpainting

Fill in missing areas of an image, or remove unwanted objects. Works very well if the missing areas are fairly small, and smaller than the image patches. If the missing areas are large use TextureSynthesis

>>> import dictlearn as dl
>>> import numpy as np
>>> image imread('some/img.png')
>>> # Mask with 60% of pixels marked missing
>>> mask = np.random.rand(*image.shape) < 0.6
>>> corrupted = image * mask
>>> # Plot corrupted
>>> inp = Inpaint(corrupted, mask)
>>> reconstructed = inp.train().inpaint()
Parameters:
  • image – Corrupted image
  • mask – Binary mask for image. Pixels in mask marked 0 is will be inpainted. locations marked 1 is kept as is.
  • patch_size – Size of image patches. Default 8
  • method – Inpainting method. ‘online’ or ‘itkrmm’.
inpaint(n_nonzero=20, group_size=60, search_space=20, stride=4, callback=None, tol=0, verbose=False)
Parameters:
  • n_nonzero – Number of nonzero coefficients for reconstruction
  • group_size – Size of group for ‘online’ inpaint. Finds the ‘group_size’ most similar image patches and trains a dictionary on this group
  • search_space – How far from the current pixel (i, j) to search for similar patches. Will search all pixels (i - s, j - s) to (i + s, j + s), s = search_space.
  • stride – Distance between image patches
  • callback –

    Callback function for online inpaint. Called with two arguments

    1. the current reconstruction and
    2. current iteration
  • tol – For method = ‘itkrmm’, tolerance for sparse coding reconstruction. Set this the same way as sigma in denoise, to also denoise the image if needed. If the image is noise free, use n_nonzero
  • verbose – Print progress
Returns:

Inpainted image
train(**kwargs)

Train a dictionary on training signals using ‘Online Dictionary Learning (ODL)’ or ‘K-SVD’.

Both methods update the dictionary once very iteration. ODL will find the sparse coding on one signal and then update the dictionary using a variant of block coordinate-descent with momentum. K-SVD will sparse code all signals before doing the dictionary update, thus every iteration of K-SVD is a lot slower. Both produces similar results given the same running time

Parameters:
  • dictionary – Optional. Dictionary, ndarray with shape (signal_size, n_atoms)
  • n_atoms – Number of dictionary atoms, default 2*signal_size
  • iters – Training iterations, default 10 if ‘batch’, 1000 for ‘online’
  • n_nonzero – Max number of nonzero coefficients in sparse codes. Default 10
  • tolerance – Sparse coding tolerance. Adds coefficients to the sparse approximation until the tolerance is achieved, or all coefficients are active
  • n_threads – Number of threads to use. Default 1
  • verbose – Print progress if True. Default False
class dictlearn.algorithms.TextureSynthesis(image, mask, patch_size=8, method='online')

Inpaint by texture synthesis

For each missing pixel we create an image patch centered at this pixel, and search the image for the most similar patch. Then the missing pixel is replaced with the center pixel in the most similar patch. Repeat until all pixels are filled.

denoise(sigma=20, n_threads=1, noise_gain=1.15)

Denoise the image

Sigma is the parameter that has the largest effect on the final result. For the best results sigma should be close to the variance of the noise. If the difference between the original and the denoised image is small sigma is probably too low. If the denoised image is very blurry then sigma is too large.

Blurry image? Reduce sigma

Noisy image? Increase sigma

Parameters:
  • sigma – Noise variance
  • n_threads – Number of threads. Default 1
  • noise_gain – Average number of nonzero coefficients in sparse approximation. Default 1.15, which has been shown to give good results.
Returns:

Reconstructed and denoised image
inpaint(max_iters=None, verbose=False)
Parameters:
  • max_iters – If None, run until the entire image is filled. Otherwise stop after ‘max_iters’ iterations
  • verbose – Print progress
train(**kwargs)

Train a dictionary on training signals using ‘Online Dictionary Learning (ODL)’ or ‘K-SVD’.

Both methods update the dictionary once very iteration. ODL will find the sparse coding on one signal and then update the dictionary using a variant of block coordinate-descent with momentum. K-SVD will sparse code all signals before doing the dictionary update, thus every iteration of K-SVD is a lot slower. Both produces similar results given the same running time

Parameters:
  • dictionary – Optional. Dictionary, ndarray with shape (signal_size, n_atoms)
  • n_atoms – Number of dictionary atoms, default 2*signal_size
  • iters – Training iterations, default 10 if ‘batch’, 1000 for ‘online’
  • n_nonzero – Max number of nonzero coefficients in sparse codes. Default 10
  • tolerance – Sparse coding tolerance. Adds coefficients to the sparse approximation until the tolerance is achieved, or all coefficients are active
  • n_threads – Number of threads to use. Default 1
  • verbose – Print progress if True. Default False

Structure Detection

dictlearn.detection.smallest_cluster(features, n_clusters, verbose=False)

Extract the smallest cluster of samples for the data ‘features’.

See examples/vessel_enhancement.py

Parameters:
  • features – array of features, shape (n_samples, n_features)
  • n_clusters – Number of features
  • verbose –
Returns:

Prediction vector of shape (n_samples,) where prediction[i] == True if features i belongs to the smallest cluster and prediction[i] == False if belongs to any other cluster