## For instruction on writing tutorials
## http://www.ros.org/wiki/WritingTutorials
####################################
##FILL ME IN
####################################
## for a custom note with links:
## note =
## for the canned note of "This tutorial assumes that you have completed the previous tutorials:" just add the links 
## note.0= 
## descriptive title for the tutorial
## title = Covariance Ellipsoids
## multi-line description to be displayed in search 
## description = Algorithms for 2d and 3d covariance ellipsoids, typically used in slam.
## the next tutorial description (optional)
## next =
## links to next tutorial (optional)
## next.0.link=
## next.1.link=
## what level user is this tutorial for 
## level= IntermediateCategory
## keywords = ecl statistics
####################################

<<IncludeCSTemplate(TutorialCSHeaderTemplate)>>

<<TableOfContents(4)>>

== Overview ==

Implemented by the template class `CovarianceEllipsoid` - this takes two template parameters. The first is the float type used (usually `float`/`double`) and the second, the dimension of the ellipsoid to be determined. 

Specialisations are enabled for 2 and 3 dimensional types only as we haven't had a need to develop a general implementation.

== Typedefs ==

Typedefs exist for the template class in the eigen style:

{{{
#!cplusplus
using ecl::CovarianceEllipsoid2f;
using ecl::CovarianceEllipsoid2d;
using ecl::CovarianceEllipsoid3f;
using ecl::CovarianceEllipsoid3d;
}}}

== Usage ==

You typically feed the covariance ellipsoid with a positive definite symmetric matrix (`eigen` matrix). Take care entering the positive definite symmetric matrix - the class does not yet do checking to make sure it is positive definite symmetric.

You can either input the matrix via the constructor - in which case it will automatically calculate the ellipsoid properties, or pass it in later via the `compute()` method:

{{{
#!cplusplus
Matrix2d M;
M << 3.0, 1.0, 1.0, 5.0; // must be a positive definite, symmetric matrix

CovarianceEllipsoid2d ellipse(M);

// OR

CovarianceEllipsoid2d ellipse;
ellipse.compute(M);
}}}

{{{
#!cplusplus
Matrix2d M;
M << 3.0, 1.0, 1.0, 5.0;
CovarianceEllipsoid2d ellipse(M);

// ellipse minor and major axis lengths
const Vector2d& lengths = ellipse.lengths(); 
double eigen_value_0 = lengths[0]*lengths[0];

// angle between x-axis and major axis of the ellipse
double angle = ellipse.rotation(); 

// values of the intercepts of the ellipse with x and y axes
const Vector2d& intercepts = ellipse.intercepts(); 

// the ellipse axes/covariance eigenvectors as column vectors in a matrix
const Matrix2d& axes = ellipse.axes(); 
}}}

The 3d version is similar, but will only calculate intercepts and axes respectively.
Note that the axes are sorted (to ensure a right-handed co-ordinate system) and normalised.

{{{
#!cplusplus
Matrix3d P;
double sigmaX(0.1);
double sigmaY(0.5);
double sigmaT(0.3);
P << sigmaX*sigmaX, 0, 0, 0, sigmaY*sigmaY, 0, 0, 0, sigmaT*sigmaT;
CovarianceEllipsoid3d ellipse(P);

const Vector3d& lengths = ellipse.lengths();
double eigen_value_0 = lengths[0]*lengths[0];
const Matrix3d& axes = ellipse.axes();
}}}

## AUTOGENERATED DO NOT DELETE 
## TutorialCategory
## FILL IN THE STACK TUTORIAL CATEGORY HERE