#include <visp3/visual_features/vpFeatureLuminanceMapping.h>

Inheritance diagram for vpLuminancePCA:

Public Member Functions
	vpLuminancePCA ()

virtual	~vpLuminancePCA ()

	vpLuminancePCA (const std::shared_ptr< vpMatrix > &basis, const std::shared_ptr< vpColVector > &mean, const vpColVector &explainedVariance)

	vpLuminancePCA (const vpLuminancePCA &other)

vpLuminancePCA &	operator= (const vpLuminancePCA &other)

void	init (const std::shared_ptr< vpMatrix > &basis, const std::shared_ptr< vpColVector > &mean, const vpColVector &variance)

std::shared_ptr< vpMatrix >	getBasis () const

std::shared_ptr< vpColVector >	getMean () const

vpColVector	getExplainedVariance () const

void	map (const vpImage< unsigned char > &I, vpColVector &s) VP_OVERRIDE

void	inverse (const vpColVector &s, vpImage< unsigned char > &I) VP_OVERRIDE

void	interaction (const vpImage< unsigned char > &I, const vpMatrix &LI, const vpColVector &s, vpMatrix &L) VP_OVERRIDE

void	save (const std::string &basisFilename, const std::string &meanFileName, const std::string &explainedVarianceFile) const

unsigned int	getProjectionSize () const

unsigned int	getBorder () const

void	setBorder (unsigned border)

Static Public Member Functions
static vpLuminancePCA	load (const std::string &basisFilename, const std::string &meanFileName, const std::string &explainedVarianceFile)

static vpLuminancePCA	learn (const std::vector< vpImage< unsigned char >> &images, const unsigned int projectionSize, const unsigned int imageBorder=0)

static vpLuminancePCA	learn (const vpMatrix &images, const unsigned int projectionSize)

static void	imageAsVector (const vpImage< unsigned char > &I, vpColVector &Ivec, unsigned border)

static void	imageAsMatrix (const vpImage< unsigned char > &I, vpMatrix &Imat, unsigned border)

Protected Attributes
unsigned	m_mappingSize

unsigned	m_border

Detailed Description

Implementation of [35].

Projects an image onto an orthogonal subspace, obtained via Principal Component Analysis (PCA).

The orthogonal basis is obtained through Singular Value Decomposition of a dataset of images (see vpLuminancePCA::learn) where the first basis vectors that explain the most variance are kept.

an image is projected to the representation $\mathbf{s}$ with:

$\mathbf{s} = \mathbf{U}^\top (vec(\mathbf{I}) - vec(\mathbf{\bar I}))$

with $\mathbf{U}$ the subspace projection matrix ( $dim(\mathbf{I}) \times k$ ) and $\mathbf{\bar I}$ is the average image computed from the dataset.

Examples: catchLuminanceMapping.cpp, and photometricMappingVisualServoing.cpp.

Definition at line 150 of file vpFeatureLuminanceMapping.h.

Constructor & Destructor Documentation

◆ vpLuminancePCA() [1/3]

vpLuminancePCA::vpLuminancePCA ( )

inline

Definition at line 153 of file vpFeatureLuminanceMapping.h.

Referenced by learn(), and load().

◆ ~vpLuminancePCA()

virtual vpLuminancePCA::~vpLuminancePCA ( )

inlinevirtual

Destructor.

Definition at line 158 of file vpFeatureLuminanceMapping.h.

◆ vpLuminancePCA() [2/3]

vpLuminancePCA::vpLuminancePCA	(	const std::shared_ptr< vpMatrix > &	basis,
		const std::shared_ptr< vpColVector > &	mean,
		const vpColVector &	explainedVariance
	)

Build a new PCA object.

Parameters

basis	$\mathbf{U}^\top$ a k x dim(I) matrix
mean	$vec(\mathbf{\bar I})$ the mean image represented as a vector
explainedVariance	The explained variance for each of the k vectors.

Definition at line 76 of file vpFeatureLuminanceMapping.cpp.

References init().

◆ vpLuminancePCA() [3/3]

vpLuminancePCA::vpLuminancePCA ( const vpLuminancePCA & other )

Copy constructor: does not make a deep copy of the basis and mean.

Definition at line 98 of file vpFeatureLuminanceMapping.cpp.

Member Function Documentation

◆ getBasis()

std::shared_ptr<vpMatrix> vpLuminancePCA::getBasis ( ) const

inline

Get $\mathbf{U}^\top$ , the subspace projection matrix ( $k \times dim(\mathbf{I})$ )

Returns: std::shared_ptr<vpColVector>

Examples: catchLuminanceMapping.cpp.

Definition at line 191 of file vpFeatureLuminanceMapping.h.

◆ getBorder()

unsigned int vpLuminanceMapping::getBorder ( ) const

inlineinherited

Returns the number of pixels that are removed by the photometric VS computation.

Returns: space size

Examples: catchLuminanceMapping.cpp.

Definition at line 114 of file vpFeatureLuminanceMapping.h.

◆ getExplainedVariance()

vpColVector vpLuminancePCA::getExplainedVariance ( ) const

inline

Get the values of explained variance by each of the eigen vectors.

When all eigenvectors of the dataset are considered, the explained variance total is 1. When they are not all considered (as should be the case), their sum should be below 1.

Returns: vpColVector

Examples: catchLuminanceMapping.cpp, and photometricMappingVisualServoing.cpp.

Definition at line 205 of file vpFeatureLuminanceMapping.h.

◆ getMean()

std::shared_ptr<vpColVector> vpLuminancePCA::getMean ( ) const

inline

Get $vec(\mathbf{\bar I})$ , the mean image computed from the dataset.

Returns: std::shared_ptr<vpColVector>

Examples: catchLuminanceMapping.cpp.

Definition at line 196 of file vpFeatureLuminanceMapping.h.

◆ getProjectionSize()

unsigned int vpLuminanceMapping::getProjectionSize ( ) const

inlineinherited

Returns the size of the space to which an image is mapped to.

Returns: space size

Examples: catchLuminanceMapping.cpp.

Definition at line 107 of file vpFeatureLuminanceMapping.h.

◆ imageAsMatrix()

void vpLuminanceMapping::imageAsMatrix	(	const vpImage< unsigned char > &	I,
		vpMatrix &	Imat,
		unsigned	border
	)

staticinherited

Definition at line 59 of file vpFeatureLuminanceMapping.cpp.

References vpException::dimensionError, vpImage< Type >::getHeight(), vpImage< Type >::getWidth(), and vpArray2D< Type >::resize().

Referenced by vpLuminanceDCT::map().

◆ imageAsVector()

BEGIN_VISP_NAMESPACE void vpLuminanceMapping::imageAsVector	(	const vpImage< unsigned char > &	I,
		vpColVector &	Ivec,
		unsigned	border
	)

staticinherited

Definition at line 43 of file vpFeatureLuminanceMapping.cpp.

References vpException::dimensionError, vpImage< Type >::getHeight(), vpImage< Type >::getWidth(), and vpColVector::resize().

Referenced by map().

◆ init()

void vpLuminancePCA::init	(	const std::shared_ptr< vpMatrix > &	basis,
		const std::shared_ptr< vpColVector > &	mean,
		const vpColVector &	variance
	)

Initialize the PCA object with a basis, mean and explained variance vector.

See also: vpLuminancePCA()

Parameters

basis
mean
variance

Definition at line 83 of file vpFeatureLuminanceMapping.cpp.

References vpFeatureLuminance::DEFAULT_BORDER, vpException::dimensionError, vpArray2D< Type >::getRows(), vpLuminanceMapping::m_border, and vpLuminanceMapping::m_mappingSize.

Referenced by vpLuminancePCA().

◆ interaction()

void vpLuminancePCA::interaction	(	const vpImage< unsigned char > &	I,
		const vpMatrix &	LI,
		const vpColVector &	s,
		vpMatrix &	L
	)

virtual

Compute the interaction matrix associated with the representation s.

Parameters

I	input image used to compute s
LI	Photometric interaction matrix associated to `I` (see vpFeatureLuminance)
s	the already computed representation
L	The output interaction matrix, of dimensions getProjectionSize() x 6

Implements vpLuminanceMapping.

Definition at line 139 of file vpFeatureLuminanceMapping.cpp.

◆ inverse()

void vpLuminancePCA::inverse	(	const vpColVector &	s,
		vpImage< unsigned char > &	I
	)

virtual

Reconstruct I from a representation s.

Parameters

s	the representation
I	Output lossy reconstruction

Implements vpLuminanceMapping.

Examples: catchLuminanceMapping.cpp.

Definition at line 127 of file vpFeatureLuminanceMapping.cpp.

References vpImage< Type >::resize().

◆ learn() [1/2]

vpLuminancePCA vpLuminancePCA::learn	(	const std::vector< vpImage< unsigned char >> &	images,
		const unsigned int	projectionSize,
		const unsigned int	imageBorder = `0`
	)

static

Compute a new Principal Component Analysis on set of images.

Parameters

images	The list of images used to compute the PCA
projectionSize	the number of eigenvectors that are kept for the final projection
imageBorder	The number of pixels to crop on each side of the image before adding it to the image set, effectively taking the center crop. Useful when the images do not have the correct dimensions. Typically, the input image to PCA is smaller than the one used when computing luminance features, since the latter step requires crops the image.

Returns: the PCA computed on the images

Exceptions

if	the images do not have the same dimensions

Examples: catchLuminanceMapping.cpp, and photometricMappingVisualServoing.cpp.

Definition at line 188 of file vpFeatureLuminanceMapping.cpp.

References vpException::badValue, vpArray2D< Type >::getCols(), vpImage< Type >::getHeight(), vpImage< Type >::getWidth(), vpArray2D< Type >::resize(), and vpMatrix::transpose().

◆ learn() [2/2]

vpLuminancePCA vpLuminancePCA::learn	(	const vpMatrix &	images,
		const unsigned int	projectionSize
	)

static

Compute a new Principal Component Analysis on dataset.

Parameters

images	The data matrix, where each column represents a single data point (image)
projectionSize	the number of eigenvectors that are kept for the final projection

Returns: the PCA computed on the images

Definition at line 232 of file vpFeatureLuminanceMapping.cpp.

References vpException::badValue, vpMatrix::getCol(), vpArray2D< Type >::getCols(), vpArray2D< Type >::getRows(), vpColVector::sum(), vpMatrix::svd(), vpMatrix::t(), and vpLuminancePCA().

◆ load()

vpLuminancePCA vpLuminancePCA::load	(	const std::string &	basisFilename,
		const std::string &	meanFileName,
		const std::string &	explainedVarianceFile
	)

static

Save the PCA basis to multiple text files, for later use via the load function.

Parameters

basisFilename	The file in which $\mathbf{U}^\top$ is stored
meanFileName	The file in which $\mathbf{\bar I}$ is stored
explainedVarianceFile	The file containing the explained variance.

Exceptions

if	files cannot be read, or if basis and mean dimensions are incorrect.

Examples: catchLuminanceMapping.cpp.

Definition at line 144 of file vpFeatureLuminanceMapping.cpp.

References vpException::dimensionError, vpArray2D< Type >::getCols(), vpMatrix::loadMatrix(), and vpLuminancePCA().

◆ map()

void vpLuminancePCA::map	(	const vpImage< unsigned char > &	I,
		vpColVector &	s
	)

virtual

Map an image I to a representation s. This representation s has getProjectionSize() rows.

Note that when combined with vpFeatureLuminanceMapping, The image I does not have the same size as the image input of vpFeatureLuminanceMapping::build. I is the center crop of this image.

Parameters

I	The input image
s	The resulting representation that will serve as visual servoing features.

Implements vpLuminanceMapping.

Examples: catchLuminanceMapping.cpp.

Definition at line 117 of file vpFeatureLuminanceMapping.cpp.

References vpImage< Type >::getHeight(), vpImage< Type >::getWidth(), vpLuminanceMapping::imageAsVector(), and vpLuminanceMapping::m_border.

◆ operator=()

vpLuminancePCA & vpLuminancePCA::operator= ( const vpLuminancePCA & other )

Definition at line 103 of file vpFeatureLuminanceMapping.cpp.

References vpLuminanceMapping::m_border, and vpLuminanceMapping::m_mappingSize.

◆ save()

void vpLuminancePCA::save	(	const std::string &	basisFilename,
		const std::string &	meanFileName,
		const std::string &	explainedVarianceFile
	)		const

Save the PCA basis to multiple text files, for later use via the load function.

Parameters

basisFilename	The file in which $\mathbf{U}^\top$ is stored
meanFileName	The file in which $\mathbf{\bar I}$ is stored
explainedVarianceFile	The file containing the explained variance.

Exceptions