HighLevel 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 ‘KSVD’.
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 coordinatedescent with momentum. KSVD will sparse code all signals before doing the dictionary update, thus every iteration of KSVD 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 ‘KSVD’.
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 coordinatedescent with momentum. KSVD will sparse code all signals before doing the dictionary update, thus every iteration of KSVD 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 KSVD 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 pretrained (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 ‘KSVD’.
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 coordinatedescent with momentum. KSVD will sparse code all signals before doing the dictionary update, thus every iteration of KSVD 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
 the current reconstruction and
 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 ‘KSVD’.
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 coordinatedescent with momentum. KSVD will sparse code all signals before doing the dictionary update, thus every iteration of KSVD 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 ‘KSVD’.
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 coordinatedescent with momentum. KSVD will sparse code all signals before doing the dictionary update, thus every iteration of KSVD 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