1.0.2 API documentation: GLM_GTX_pca

| 1.0.2 API documentation

Functions
GLM_GTX_pca
Experimental extensions

## 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_DISCARD_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_DISCARD_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_DISCARD_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_DISCARD_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_DISCARD_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_DISCARD_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]`.

glm::sortEigenvalues
GLM_FUNC_DISCARD_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.
glm::computeCovarianceMatrix
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 ...
glm::dvec3
vec< 3, double, defaultp > dvec3
3 components vector of double-precision floating-point numbers.
Definition: vector_double3.hpp:15
glm::dmat3
mat< 3, 3, double, defaultp > dmat3
3 columns of 3 components matrix of double-precision floating-point numbers.
Definition: matrix_double3x3.hpp:20
glm::findEigenvaluesSymReal
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...