GLM_GTX_pca

Functions
template<length_t D, typename T , qualifier Q, typename I >
GLM_FUNC_DECL mat< D, D, T, Q >	computeCovarianceMatrix (I const &b, I const &e)
	Compute a covariance matrix form a pair of iterators b (begin) and e (end) of a container with relative coordinates (e.g., relative to the center of gravity of the object) Dereferencing an iterator of type I must yield a vec<D, T, Qgt;
template<length_t D, typename T , qualifier Q, typename I >
GLM_FUNC_DECL mat< D, D, T, Q >	computeCovarianceMatrix (I const &b, I const &e, vec< D, T, Q > const &c)
	Compute a covariance matrix form a pair of iterators b (begin) and e (end) of a container with absolute coordinates and a precomputed center of gravity c Dereferencing an iterator of type I must yield a vec<D, T, Qgt;
template<length_t D, typename T , qualifier Q>
GLM_INLINE mat< D, D, T, Q >	computeCovarianceMatrix (vec< D, T, Q > const *v, size_t n)
	Compute a covariance matrix form an array of relative coordinates v (e.g., relative to the center of gravity of the object) More...
template<length_t D, typename T , qualifier Q>
GLM_INLINE mat< D, D, T, Q >	computeCovarianceMatrix (vec< D, T, Q > const *v, size_t n, vec< D, T, Q > const &c)
	Compute a covariance matrix form an array of absolute coordinates v and a precomputed center of gravity c More...
template<length_t D, typename T , qualifier Q>
GLM_FUNC_DECL unsigned int	findEigenvaluesSymReal (mat< D, D, T, Q > const &covarMat, vec< D, T, Q > &outEigenvalues, mat< D, D, T, Q > &outEigenvectors)
	Assuming the provided covariance matrix covarMat is symmetric and real-valued, this function find the D Eigenvalues of the matrix, and also provides the corresponding Eigenvectors. More...
template<typename T , qualifier Q>
GLM_FUNC_DECL void	sortEigenvalues (vec< 2, T, Q > &eigenvalues, mat< 2, 2, T, Q > &eigenvectors)
	Sorts a group of Eigenvalues&Eigenvectors, for largest Eigenvalue to smallest Eigenvalue. More...
template<typename T , qualifier Q>
GLM_FUNC_DECL void	sortEigenvalues (vec< 3, T, Q > &eigenvalues, mat< 3, 3, T, Q > &eigenvectors)
	Sorts a group of Eigenvalues&Eigenvectors, for largest Eigenvalue to smallest Eigenvalue. More...
template<typename T , qualifier Q>
GLM_FUNC_DECL void	sortEigenvalues (vec< 4, T, Q > &eigenvalues, mat< 4, 4, T, Q > &eigenvectors)
	Sorts a group of Eigenvalues&Eigenvectors, for largest Eigenvalue to smallest Eigenvalue. More...

Detailed Description

Include <glm/gtx/pca.hpp> to use the features of this extension.

Implements functions required for fundamental 'princple component analysis' in 2D, 3D, and 4D: 1) Computing a covariance matrics from a list of relative position vectors 2) Compute the eigenvalues and eigenvectors of the covariance matrics This is useful, e.g., to compute an object-aligned bounding box from vertices of an object. https://en.wikipedia.org/wiki/Principal_component_analysis

Example:

std::vector<glm::dvec3> ptData;
// ... fill ptData with some point data, e.g. vertices
 
glm::dvec3 center = computeCenter(ptData);
 
glm::dmat3 covarMat = glm::computeCovarianceMatrix(ptData.data(), ptData.size(), center);
 
glm::dvec3 evals;
glm::dmat3 evecs;
int evcnt = glm::findEigenvaluesSymReal(covarMat, evals, evecs);
 
if(evcnt != 3)
    // ... error handling
 
glm::sortEigenvalues(evals, evecs);
 
// ... now evecs[0] points in the direction (symmetric) of the largest spatial distribution within ptData

Function Documentation

computeCovarianceMatrix() [1/2]

GLM_INLINE mat<D, D, T, Q> glm::computeCovarianceMatrix	(	vec< D, T, Q > const *	v,
		size_t	n
	)

Compute a covariance matrix form an array of relative coordinates v (e.g., relative to the center of gravity of the object)

Parameters

v	Points to a memory holding n times vectors
n	Number of points in v

computeCovarianceMatrix() [2/2]

GLM_INLINE mat<D, D, T, Q> glm::computeCovarianceMatrix	(	vec< D, T, Q > const *	v,
		size_t	n,
		vec< D, T, Q > const &	c
	)

Compute a covariance matrix form an array of absolute coordinates v and a precomputed center of gravity c

Parameters

v	Points to a memory holding n times vectors
n	Number of points in v
c	Precomputed center of gravity

findEigenvaluesSymReal()

GLM_FUNC_DECL unsigned int glm::findEigenvaluesSymReal	(	mat< D, D, T, Q > const &	covarMat,
		vec< D, T, Q > &	outEigenvalues,
		mat< D, D, T, Q > &	outEigenvectors
	)

Assuming the provided covariance matrix covarMat is symmetric and real-valued, this function find the D Eigenvalues of the matrix, and also provides the corresponding Eigenvectors.

Note: the data in outEigenvalues and outEigenvectors are in matching order, i.e. outEigenvector[i] is the Eigenvector of the Eigenvalue outEigenvalue[i]. This is a numeric implementation to find the Eigenvalues, using 'QL decomposition` (variant of QR decomposition: https://en.wikipedia.org/wiki/QR_decomposition).

Parameters

[in]	covarMat	A symmetric, real-valued covariance matrix, e.g. computed from computeCovarianceMatrix
[out]	outEigenvalues	Vector to receive the found eigenvalues
[out]	outEigenvectors	Matrix to receive the found eigenvectors corresponding to the found eigenvalues, as column vectors

Returns

The number of eigenvalues found, usually D if the precondition of the covariance matrix is met.

sortEigenvalues() [1/3]

GLM_FUNC_DECL void glm::sortEigenvalues	(	vec< 2, T, Q > &	eigenvalues,
		mat< 2, 2, T, Q > &	eigenvectors
	)

Sorts a group of Eigenvalues&Eigenvectors, for largest Eigenvalue to smallest Eigenvalue.

The data in outEigenvalues and outEigenvectors are assumed to be matching order, i.e. outEigenvector[i] is the Eigenvector of the Eigenvalue outEigenvalue[i].

sortEigenvalues() [2/3]

GLM_FUNC_DECL void glm::sortEigenvalues	(	vec< 3, T, Q > &	eigenvalues,
		mat< 3, 3, T, Q > &	eigenvectors
	)

Sorts a group of Eigenvalues&Eigenvectors, for largest Eigenvalue to smallest Eigenvalue.

The data in outEigenvalues and outEigenvectors are assumed to be matching order, i.e. outEigenvector[i] is the Eigenvector of the Eigenvalue outEigenvalue[i].

sortEigenvalues() [3/3]

GLM_FUNC_DECL void glm::sortEigenvalues	(	vec< 4, T, Q > &	eigenvalues,
		mat< 4, 4, T, Q > &	eigenvectors
	)

Sorts a group of Eigenvalues&Eigenvectors, for largest Eigenvalue to smallest Eigenvalue.

The data in outEigenvalues and outEigenvectors are assumed to be matching order, i.e. outEigenvector[i] is the Eigenvector of the Eigenvalue outEigenvalue[i].