Sparse Dictionary Learning class. More...

#include <SparseDictionary.h>

Inheritance diagram for DirectGraphicalModels::fex::CSparseDictionary:

Public Member Functions
	CSparseDictionary (void)

virtual	~CSparseDictionary (void)

void	train (const Mat &X, word nWords, dword batch=2000, unsigned int nIt=1000, float lRate=SC_LRATE_D, const std::string &fileName=std::string())
	Trains dictionary \(D\). More...

void	save (const std::string &fileName) const
	Saves dictionary \(D\) into a binary file. More...

void	load (const std::string &fileName)
	Loads dictionary \(D\) from the file. More...

bool	empty (void) const
	Checks whether the dictionary has been trained or loaded. More...

Mat	getDictionary (void) const
	Returns dictionary \(D\). More...

int	getBlockSize (void) const
	Returns size of the block, i.e. \(\sqrt{sampleLen}\). More...

word	getNumWords (void) const
	Returns the number words in dictionary \(D\). More...

Static Public Member Functions
static Mat	getDictionary (const std::string &fileName)
	Returns dictionary \(D\) from file. More...

static Mat	img2data (const Mat &img, int blockSize, float varianceThreshold=0.0f)
	Converts image into data \(X\). More...

static Mat	data2img (const Mat &X, cv::Size imgSize)
	Converts data \(X\) into an image. More...

Protected Types
enum	grad_type { GRAD_D, GRAD_W }

Static Protected Member Functions
static void	calculate_W (const Mat &X, const Mat &D, Mat &W, float lambda, float epsilon, unsigned int nIt=800, float lRate=SC_LRATE_W)
	Evaluates weighting coefficients matrix \(W\). More...

static void	calculate_D (const Mat &X, Mat &D, const Mat &W, float gamma, unsigned int nIt=800, float lRate=SC_LRATE_D)
	Evaluates dictionary \(D\). More...

static Mat	calculateGradient (grad_type gType, const Mat &X, const Mat &D, const Mat &W, float lambda, float epsilon, float gamma)
	Calculates the gradient matrices \(\frac{\partial J(D, W)}{\partial D}\) and \(\frac{\partial J(D, W)}{\partial W}\). More...

static float	calculateCost (const Mat &X, const Mat &D, const Mat &W, float lambda, float epsilon, float gamma)
	Calculates the value of \(J(D, W)\) function. More...

Private Attributes
Mat	m_D
	The dictionary \(D\): Mat(size: nWords x sampleLen; type: CV_32FC1);. More...

Detailed Description

Sparse Dictionary Learning class.

This class performs the Sparse dictionary learning, i.e. estimation of dictionary words (bases) \(\vec{d}_i\in D\), such that arbitrary data vector \(\vec{x}\) could be represended via a linear combination:

\[ \begin{align} \sum^{nWords}_{i=1} w_{i,j} \cdot \vec{d}_i = \vec{x}_j, & & \forall j \in [0; nSamples), & \text{ or} \\ \vec{w}_j \times D = \vec{x}_j, & & \forall j \in [0; nSamples), & \end{align} \]

where \(D\) is the dictionary.
The implementation is based on Sparse Coding: Autoencoder Interpretation article, where the task of the dictionary learning turns into the following minimization problem:

\[ \text{arg}\,\min\limits_{D,W} J(D, W) = \left\| W \times D - X \right\|^{2}_{2} + \lambda\left\|W\right\|_1 + \gamma\left\|D\right\|^{2}_{2}, \]

where \(D\in\mathbb{R}^{sampleLen \times nWords}\), \(W\in\mathbb{R}^{nWords \times nSamples}\) is the matrix, containing weighting coefficients for every word and every sample and \(X\in\mathbb{R}^{sampleLen \times nSamples}\) contains the training data as row-vectors samples.
In order to minimize \(J(D, W)\) we use the Gradient Descent algorithm.
We also use \(\sum_{i,j}\sqrt{w^{2}_{i,j} + \epsilon}\) in place of \(\left\|W\right\|_1\) to make \(J(D, W)\) differentiable at \(W = 0\).
In order to train the dictionary, one may use the code:

using namespace DirectGraphicalModels;
using namespace DirectGraphicalModels::fex;
  CSparseCoding *sparseCoding = new CSparseCoding(img);
  Mat X = CSparseDictionary::img2data(img, blockSize);  // sampleLen = blockSize * blockSize
  parallel::shuffleRows(X);
  sparseCoding->train(X, nWords);
  sparseCoding->save("dictionary.dic");

Author: Sergey G. Kosov, serge.nosp@m.y.ko.nosp@m.sov@p.nosp@m.roje.nosp@m.ct-10.nosp@m..de

Definition at line 47 of file SparseDictionary.h.

Member Enumeration Documentation

◆ grad_type

enum DirectGraphicalModels::fex::CSparseDictionary::grad_type

protected

Enumerator
GRAD_D
GRAD_W

Definition at line 194 of file SparseDictionary.h.

Constructor & Destructor Documentation

◆ CSparseDictionary()

DirectGraphicalModels::fex::CSparseDictionary::CSparseDictionary ( void )

inline

Definition at line 50 of file SparseDictionary.h.

◆ ~CSparseDictionary()

virtual DirectGraphicalModels::fex::CSparseDictionary::~CSparseDictionary ( void )

inlinevirtual

Definition at line 51 of file SparseDictionary.h.

Member Function Documentation

◆ calculate_D()

void DirectGraphicalModels::fex::CSparseDictionary::calculate_D	(	const Mat &	X,
		Mat &	D,
		const Mat &	W,
		float	gamma,
		unsigned int	nIt = `800`,
		float	lRate = `SC_LRATE_D`
	)

staticprotected

Evaluates dictionary \(D\).

Finds the \(D\), that minimizes \(J(D, W)\) for the given \(W\):

\[ \text{arg}\,\min\limits_{D} J(D, W) = \left\| W \times D - X \right\|^{2}_{2} + \gamma\left\|D\right\|^{2}_{2}, \]

Parameters

[in]	X	Training data \(X\): Mat(size nSamples x sampleLen; type CV_32FC1)
[in,out]	D	Dictionary \(D\): Mat(size nWords x sampleLen; type CV_32FC1)
[in]	W	Weighting coefficients \(W\): Mat(size nSamples x nWords; type CV_32FC1)
[in]	gamma	Regularisation parameter: \(\gamma\)
[in]	nIt	Number of iterations
[in]	lRate	Learning rate parameter, which is charged with the speed of convergence

Definition at line 235 of file SparseDictionary.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ calculate_W()

void DirectGraphicalModels::fex::CSparseDictionary::calculate_W	(	const Mat &	X,
		const Mat &	D,
		Mat &	W,
		float	lambda,
		float	epsilon,
		unsigned int	nIt = `800`,
		float	lRate = `SC_LRATE_W`
	)

staticprotected

Evaluates weighting coefficients matrix \(W\).

Finds the \(W\), that minimizes \(J(D, W)\) for the given \(D\):

\[ \text{arg}\,\min\limits_{W} J(D, W) = \left\| W \times D - X \right\|^{2}_{2} + \lambda\sum_{i,j}{\sqrt{w^{2}_{i,j} + \epsilon}} \]

Parameters

[in]	X	Training data \(X\): Mat(size nSamples x sampleLen; type CV_32FC1)
[in]	D	Dictionary \(D\): Mat(size nWords x sampleLen; type CV_32FC1)
[in,out]	W	Weighting coefficients \(W\): Mat(size nSamples x nWords; type CV_32FC1)
[in]	lambda	Regularisation parameter \(\lambda\)
[in]	epsilon	L1-regularisation parameter: \(\epsilon\)
[in]	nIt	Number of iterations
[in]	lRate	Learning rate parameter, which is charged with the speed of convergence

Definition at line 220 of file SparseDictionary.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ calculateCost()

float DirectGraphicalModels::fex::CSparseDictionary::calculateCost	(	const Mat &	X,
		const Mat &	D,
		const Mat &	W,
		float	lambda,
		float	epsilon,
		float	gamma
	)

staticprotected

Calculates the value of \(J(D, W)\) function.

Parameters

X	Training data \(X\): Mat(size nSamples x sampleLen; type CV_32FC1)
D	Dictionary \(D\): Mat(size nWords x sampleLen; type CV_32FC1)
W	Weighting coefficients \(W\): Mat(size nSamples x nWords; type CV_32FC1)
lambda	Regularisation parameter \(\lambda\)
epsilon	L1-regularisation parameter: \(\epsilon\)
gamma	Regularisation parameter: \(\gamma\)

Returns: The value of \(J(D, W)\) function

Definition at line 273 of file SparseDictionary.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ calculateGradient()

Mat DirectGraphicalModels::fex::CSparseDictionary::calculateGradient	(	grad_type	gType,
		const Mat &	X,
		const Mat &	D,
		const Mat &	W,
		float	lambda,
		float	epsilon,
		float	gamma
	)

staticprotected

Calculates the gradient matrices \(\frac{\partial J(D, W)}{\partial D}\) and \(\frac{\partial J(D, W)}{\partial W}\).

This function calculates the gradient matrices:

\[\begin{align} \frac{\partial J(D, W)}{\partial D} &= \frac{2}{nSapmles} \cdot W^\top\times [W \times D - X] + 2\cdot\gamma\cdot D, &\text{ if gType = GRAD_D} \\ \frac{\partial J(D, W)}{\partial W} &= \frac{2}{nSapmles} \cdot [W \times D - X] \times D^\top + \lambda\frac{W}{\sqrt{W^2 + \epsilon}}, &\text{ if gType = GRAD_W} \end{align}\]

Parameters

gType	Gradient type
X	Training data \(X\): Mat(size nSamples x sampleLen; type CV_32FC1)
D	Dictionary \(D\): Mat(size nWords x sampleLen; type CV_32FC1)
W	Weighting coefficients \(W\): Mat(size nSamples x nWords; type CV_32FC1)
lambda	Regularisation parameter \(\lambda\)
epsilon	L1-regularisation parameter: \(\epsilon\)
gamma	Regularisation parameter: \(\gamma\)

Returns: Gradient matrix

Definition at line 249 of file SparseDictionary.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ data2img()

Mat DirectGraphicalModels::fex::CSparseDictionary::data2img	(	const Mat &	X,
		cv::Size	imgSize
	)

static

Converts data \(X\) into an image.

This function performs reverse transformation of img2data() function, thus the code

Mat X = CSparseDictionary::img2data(img, blockSize, 0);

Mat res = CSparseDictionary::data2img(X, img.size());

gives res identical to img.

Parameters

X	The input data \(X\) (depth: 8 or 16 bit)
imgSize	The size of the image to return

Returns: Resulting image: Mat(size: imgSize; type: CV_8UC1 or CV_16UC1)

Definition at line 192 of file SparseDictionary.cpp.

◆ empty()

bool DirectGraphicalModels::fex::CSparseDictionary::empty ( void ) const

inline

Checks whether the dictionary has been trained or loaded.

Return values

true	if the dictionary has been trained or loaded
false	otherwise

Definition at line 82 of file SparseDictionary.h.

Here is the caller graph for this function:

◆ getBlockSize()

int DirectGraphicalModels::fex::CSparseDictionary::getBlockSize ( void ) const

inline

Returns size of the block, i.e. \(\sqrt{sampleLen}\).

Returns: blockSize

Definition at line 103 of file SparseDictionary.h.

Here is the call graph for this function:

◆ getDictionary() [1/2]

Mat DirectGraphicalModels::fex::CSparseDictionary::getDictionary ( void ) const

inline

Returns dictionary \(D\).

Returns: Dictionary \(D\): Mat(size: nWords x sampleLen; type: CV_32FC1)

Definition at line 87 of file SparseDictionary.h.

Here is the caller graph for this function:

◆ getDictionary() [2/2]

static Mat DirectGraphicalModels::fex::CSparseDictionary::getDictionary ( const std::string & fileName )

inlinestatic

Returns dictionary \(D\) from file.

Parameters

fileName Full file name

Returns: Dictionary \(D\): Mat(size: nWords x sampleLen; type: CV_32FC1)

Definition at line 93 of file SparseDictionary.h.

Here is the call graph for this function:

◆ getNumWords()

word DirectGraphicalModels::fex::CSparseDictionary::getNumWords ( void ) const

inline

Returns the number words in dictionary \(D\).

Returns: nWords

Definition at line 108 of file SparseDictionary.h.

Here is the call graph for this function:

◆ img2data()

Mat DirectGraphicalModels::fex::CSparseDictionary::img2data	(	const Mat &	img,
		int	blockSize,
		float	varianceThreshold = `0.0f`
	)

static

Converts image into data \(X\).

This functions generates a set of data samples (blockSize x blockSize patches) from a single image. The extracted pathces are overlapping, thus the maximal number of data samples is: nMaxSamples = (img.width - blockSize + 1) x (img.height - blockSize + 1)

It is recommended to suffle the samples with parallel::shuffleRows() function before training dictionary with train()

Parameters

img	The input image (1 or 3 channels, 8 or 16 bit image)
blockSize	Size of the quadratic patch In order to use this calss with fex::CSparseCoding::get() the size of the block should be odd
varianceThreshold	The extracted samples with variance greater or equal to varianceThreshold will be included to \(X\). If varianceThreshold = 0 all the samples are included, thus nSamples = nMaxSamples

Returns: Data \(X\): Mat(size: nSamples x blockSize^2; type: CV_8UC1 or CV_16UC1)

Definition at line 161 of file SparseDictionary.cpp.

Here is the caller graph for this function:

◆ load()

void DirectGraphicalModels::fex::CSparseDictionary::load ( const std::string & fileName )

Loads dictionary \(D\) from the file.

Parameters

fileName Full file name

Definition at line 87 of file SparseDictionary.cpp.

Here is the caller graph for this function:

◆ save()

void DirectGraphicalModels::fex::CSparseDictionary::save ( const std::string & fileName ) const

Saves dictionary \(D\) into a binary file.

Parameters

fileName Full file name

Definition at line 78 of file SparseDictionary.cpp.

Here is the caller graph for this function:

◆ train()

void DirectGraphicalModels::fex::CSparseDictionary::train	(	const Mat &	X,
		word	nWords,
		dword	batch = `2000`,
		unsigned int	nIt = `1000`,
		float	lRate = `SC_LRATE_D`,
		const std::string &	fileName = `std::string()`
	)

Trains dictionary \(D\).

This function creates and trains new dictionary \(D\) on data \(X\)

Parameters

X	Training data \(X\): Mat(size nSamples x sampleLen; type CV_8UC1 or CV_16UC1) May be derived from an image with img2data() fucntion
nWords	Length of the dictionary (number of words)
batch	The number of randomly chosen samples from X to be used in every distinct iteration of training This parameter must be smaller or equal to the number of samples in training data \(X\)
nIt	Number of iterations
lRate	Learning rate parameter, which is charged with the speed of convergence
fileName	Path and file name to store intermediate dictionaries \(D\) (every 5 iterations). If specified the resulting file name will be the follows: fileName<it/5>.dic

Definition at line 9 of file SparseDictionary.cpp.

Here is the call graph for this function:

Member Data Documentation

◆ m_D

Mat DirectGraphicalModels::fex::CSparseDictionary::m_D

private

The dictionary \(D\): Mat(size: nWords x sampleLen; type: CV_32FC1);.

Definition at line 190 of file SparseDictionary.h.

The documentation for this class was generated from the following files:

D:/Projects/DGM/modules/FEX/SparseDictionary.h
D:/Projects/DGM/modules/FEX/SparseDictionary.cpp

Public Member Functions

Static Public Member Functions

Protected Types

Static Protected Member Functions

Private Attributes

Detailed Description

Member Enumeration Documentation

◆ grad_type

Constructor & Destructor Documentation

◆ CSparseDictionary()

◆ ~CSparseDictionary()

Member Function Documentation

◆ calculate_D()

◆ calculate_W()

◆ calculateCost()

◆ calculateGradient()

◆ data2img()

◆ empty()

◆ getBlockSize()

◆ getDictionary() [1/2]

◆ getDictionary() [2/2]

◆ getNumWords()

◆ img2data()

◆ load()

◆ save()

◆ train()

Member Data Documentation

◆ m_D