Estimates a 3D rigid transformation from two point sets. More...

#include <EstimateRigidTransformation3D.hpp>

Inheritance diagram for TRTK::EstimateRigidTransformation3D< T >:

Collaboration diagram for TRTK::EstimateRigidTransformation3D< T >:

Public Types
typedef super::VectorXT	VectorXT
	Column vector of arbitrary size with value type T.
typedef super::MatrixXT	MatrixXT
	Matrix of arbitrary size with value type T.
typedef super::Vector2T	Vector2T
	2D column vector with value type T.
typedef super::Vector3T	Vector3T
	3D column vector with value type T.
typedef super::Vector4T	Vector4T
	4D column vector with value type T.
typedef super::RowVector2T	RowVector2T
	2D row vector with value type T.
typedef super::RowVector3T	RowVector3T
	3D row vector with value type T.
typedef super::Matrix2T	Matrix2T
	2 x 2 matrix with value type T.
typedef super::Matrix3T	Matrix3T
	3 x 3 matrix with value type T.
typedef super::Matrix4T	Matrix4T
	4 x 4 matrix with value type T.
typedef super::ArrayXT	ArrayXT
	General-purpose array of arbitrary size with value type T.
enum	Error { NOT_ENOUGH_POINTS, UNEQUAL_NUMBER_OF_POINTS, UNKNOWN_ERROR, WRONG_POINT_SIZE }
Public Member Functions
	EstimateRigidTransformation3D ()
	Constructs a new instance of this class.
	EstimateRigidTransformation3D (const std::vector< Coordinate< T > > &source_points, const std::vector< Coordinate< T > > &target_points)
	Constructs a new instance of this class.
	EstimateRigidTransformation3D (const std::vector< Vector3T > &source_points, const std::vector< Vector3T > &target_points)
	Constructs a new instance of this class.
	EstimateRigidTransformation3D (const std::vector< Vector4T, Eigen::aligned_allocator< Vector4T > > &source_points, const std::vector< Vector4T, Eigen::aligned_allocator< Vector4T > > &target_points)
	Constructs a new instance of this class.
virtual	~EstimateRigidTransformation3D ()
	Deletes the instance.
virtual void	compute () override
	Computes the transformation estimation.
void	allowReflection (bool value=true)
	Allow or disallow reflections when computing an estimate.
Matrix3T	getRotationMatrix () const
Vector3T	getTranslationVector () const
virtual value_type	getRMS () const
	Returns the root mean square (RMS) error of the estimated transformation.
virtual const Matrix4T &	getTransformationMatrix () const
void	setSourcePoints (const std::vector< Coordinate< T > > &)
	Sets the source points.
void	setSourcePoints (const std::vector< Vector3T > &)
	Sets the source points.
void	setSourcePoints (const std::vector< Vector4T, Eigen::aligned_allocator< Vector4T > > &)
	Sets the source points.
void	setTargetPoints (const std::vector< Coordinate< T > > &)
	Sets the target points.
void	setTargetPoints (const std::vector< Vector3T > &)
	Sets the target points.
void	setTargetPoints (const std::vector< Vector4T, Eigen::aligned_allocator< Vector4T > > &)
	Sets the target points.
Public Attributes
EIGEN_MAKE_ALIGNED_OPERATOR_NEW typedef T	value_type
	Internally used value type (should be a floating point type).
Protected Attributes
MatrixXT	m_source_points
MatrixXT	m_target_points
Matrix4T	m_transformation_matrix

Detailed Description

template<class T>
class TRTK::EstimateRigidTransformation3D< T >

Estimates a 3D rigid transformation from two point sets.

This class estimates a 3D rigid transformation between two point sets in terms of least squares. The point sets must have the same cardinality, and the points must correspond to each other. There must be at least three corresponding point pairs. By default no reflection is allowed which can be changed by calling the allowReflection() method.

The algorithm estimates a transformation matrix as shown below:

\[ \begin{pmatrix} y_1 \\ y_2 \\ y_3 \\ 1 \end{pmatrix} = \begin{pmatrix} r_{11} & r_{12} & r_{13} & b_1 \\ r_{21} & r_{22} & r_{23} & b_2 \\ r_{31} & r_{32} & r_{33} & b_3 \\ 0 & 0 & 0 & 1 \end{pmatrix} \begin{pmatrix} x_1 \\ x_2 \\ x_3 \\ 1 \end{pmatrix} \qquad \qquad \text{or} \qquad \qquad y = Rx + b \quad \wedge \quad RR^T = I \]

The source points are the set of all \( x \) and the target points are the set of all \( y \).

Note:: Some functions might throw an error object. See the appropriate function for more details.

Note:: The transformation estimation is a least square scheme which decomposes a correlation matrix between the two point sets using the singular value decomposition. For a more detailed explanation of the algorithm, please have a look at the source code.

Here is an more elaborate example to see, how to use the class:

 #include <iostream>
 #include <vector>

 #include <TRTK/Coordinate.hpp>
 #include <TRTK/Transform3D.hpp>
 #include <TRTK/EstimateRigidTransformation3D.hpp>

 using std::cout;
 using std::endl;
 using std::vector;

 using namespace TRTK;


 int main()
 {
     // Construct a transformation which rotates 90 degrees counter-clockwise
     // in the x-y plane with a center of rotation of (1, 3, 0).

     Transform3D<double> transform;
     const double pi = Transform3D<double>::pi;
     transform.translate(-1, -3, 0).rotateZ(pi/2).translate(1, 3, 0);

     // Construct two sets with source and target points, respectively.

     vector<Coordinate<double> > source_points;
     vector<Coordinate<double> > target_points;

     Coordinate<double> source_point1( 1,  2,  0);
     Coordinate<double> source_point2( 3, -2,  0);
     Coordinate<double> source_point3(-1,  1,  1);
     Coordinate<double> source_point4( 2,  0, -1);

     source_points.push_back(source_point1);
     source_points.push_back(source_point2);
     source_points.push_back(source_point3);
     source_points.push_back(source_point4);

     Coordinate<double> target_point1 = transform * source_point1;
     Coordinate<double> target_point2 = transform * source_point2;
     Coordinate<double> target_point3 = transform * source_point3;
     Coordinate<double> target_point4 = transform * source_point4;

     target_points.push_back(target_point1);
     target_points.push_back(target_point2);
     target_points.push_back(target_point3);
     target_points.push_back(target_point4);

     // Perform the transformation estimation.

     EstimateRigidTransformation3D<double> estimateRigidTransformation3D(source_points,
                                                                         target_points);
     estimateRigidTransformation3D.compute();

     // Display the results.

     cout.precision(4);
     cout << std::fixed;

     cout << "Original transformation matrix:" << endl << endl
          << transform.getTransformationMatrix() << endl << endl;

     cout << "Estimated transformation matrix:" << endl << endl
          << estimateRigidTransformation3D.getTransformationMatrix() << endl << endl;

     // Example of how to use the result.

     Transform3D<double> transform2 = estimateRigidTransformation3D.getTransformationMatrix();

     cout << "Source point 1: " << source_point1 << endl
          << "Target point 1: " << target_point1 << endl
          << "Target point 1: " << transform2 * source_point1 << endl;

     return 0;
 }

Output:

 Original transformation matrix:

     0.0000      -1.0000       0.0000       4.0000
     1.0000       0.0000       0.0000       2.0000
     0.0000       0.0000       1.0000       0.0000
     0.0000       0.0000       0.0000       1.0000

 Estimated transformation matrix:

    -0.0000       -1.0000        0.0000        4.0000
     1.0000        0.0000       -0.0000        2.0000
     0.0000        0.0000        1.0000       -0.0000
     0.0000        0.0000        0.0000        1.0000

 Source point 1: (1.0000, 2.0000, 0.0000)
 Target point 1: (2.0000, 3.0000, 0.0000)
 Target point 1: (2.0000, 3.0000, 0.0000)

Note:: If you plan to use this class with an STL container, please have a look at this site.

See also:: EstimateRigidTransformation2D

Author:: Christoph Haenisch

Version:: 0.4.0

Date:: 2019-07-19

Definition at line 205 of file EstimateRigidTransformation3D.hpp.

Member Enumeration Documentation

template<class T>

enum TRTK::EstimateTransformation::Error [inherited]

Enumerator:

NOT_ENOUGH_POINTS	More points are required to estimate the transformation.
UNEQUAL_NUMBER_OF_POINTS	The two point sets do not have the same cardinality.
UNKNOWN_ERROR	An unknown error occured.
WRONG_POINT_SIZE	One or more points have a wrong size.

Definition at line 62 of file EstimateTransformation.hpp.

Constructor & Destructor Documentation

template<class T >

TRTK::EstimateRigidTransformation3D< T >::EstimateRigidTransformation3D ( )

Constructs a new instance of this class.

Template Parameters:

T	scalar type of the coordinates

Definition at line 263 of file EstimateRigidTransformation3D.hpp.

template<class T>

TRTK::EstimateRigidTransformation3D< T >::EstimateRigidTransformation3D	(	const std::vector< Coordinate< T > > &	source_points,
		const std::vector< Coordinate< T > > &	target_points
	)

Constructs a new instance of this class.

Template Parameters:

T	scalar type of the coordinates

Parameters:

[in]	source_points	The points can either be plain 3D or 4D homogeneous coordinates.
[in]	target_points	The points can either be plain 3D or 4D homogeneous coordinates.

No transformation estimation is done. To do so, please call compute().

Exceptions:

ErrorObj If there are any coordinates other than 3D or 4D coordinates, an error object is thrown and its error code is set to WRONG_POINT_SIZE.

Note:: The point sets must have the same cardinality, and the points must correspond to each other.

Definition at line 290 of file EstimateRigidTransformation3D.hpp.

template<class T>

TRTK::EstimateRigidTransformation3D< T >::EstimateRigidTransformation3D	(	const std::vector< Vector3T > &	source_points,
		const std::vector< Vector3T > &	target_points
	)

Constructs a new instance of this class.

Template Parameters:

T	scalar type of the coordinates

Parameters:

[in]	source_points	3D coordinates.
[in]	target_points	3D coordinates.

No transformation estimation is done. To do so, please call compute().

Note:: The point sets must have the same cardinality, and the points must correspond to each other.

Definition at line 312 of file EstimateRigidTransformation3D.hpp.

template<class T>

TRTK::EstimateRigidTransformation3D< T >::EstimateRigidTransformation3D	(	const std::vector< Vector4T, Eigen::aligned_allocator< Vector4T > > &	source_points,
		const std::vector< Vector4T, Eigen::aligned_allocator< Vector4T > > &	target_points
	)

Constructs a new instance of this class.

Template Parameters:

T	scalar type of the coordinates

Parameters:

[in]	source_points	4D homogeneous coordinates.
[in]	target_points	4D homogeneous coordinates.

No transformation estimation is done. To do so, please call compute().

Note:: The point sets must have the same cardinality, and the points must correspond to each other.

Definition at line 334 of file EstimateRigidTransformation3D.hpp.

template<class T >

TRTK::EstimateRigidTransformation3D< T >::~EstimateRigidTransformation3D ( ) [virtual]

Deletes the instance.

Template Parameters:

T	scalar type of the coordinates

Definition at line 348 of file EstimateRigidTransformation3D.hpp.

Member Function Documentation

template<class T >

void TRTK::EstimateRigidTransformation3D< T >::allowReflection ( bool value = true )

Allow or disallow reflections when computing an estimate.

Template Parameters:

T	scalar type of the coordinates

Definition at line 359 of file EstimateRigidTransformation3D.hpp.

template<class T >

void TRTK::EstimateRigidTransformation3D< T >::compute ( ) [override, virtual]

Computes the transformation estimation.

Template Parameters:

T	scalar type of the coordinates

The transformation estimation is a least square scheme which decomposes a correlation matrix between the two point sets using the singular value decomposition. For a more detailed explanation of the algorithm, please have a look at the source code. (A link should be below.)

The direction of the transformation is from the source points to the target points: \( p_{target} = \cal{T} \; \{ p_{source} \} \).

Exceptions:

ErrorObj	If the point sets do not have the same cardinality, an error object is thrown and its error code is set to `UNEQUAL_NUMBER_OF_POINTS`.
ErrorObj	If there are not enough points (at least three) to perform the transformation estimation, an error object is thrown and its error code is set to `NOT_ENOUGH_POINTS`.

Implements TRTK::EstimateTransformation3D< T >.

Definition at line 387 of file EstimateRigidTransformation3D.hpp.

template<class T >

EstimateTransformation3D< T >::value_type TRTK::EstimateTransformation3D< T >::getRMS ( ) const [virtual, inherited]

Returns the root mean square (RMS) error of the estimated transformation.

Template Parameters:

T	scalar type of the coordinates

It is assumed, that the computation was done before.

The value type T must provide a function T sqrt(T value) which yields the square root of value.

Exceptions:

ErrorObj If the point sets do not have the same cardinality, an error object is thrown and its error code is set to UNEQUAL_NUMBER_OF_POINTS.

See also:: compute()

Implements TRTK::EstimateTransformation< T >.

Definition at line 149 of file EstimateTransformation3D.hpp.

template<class T >

EstimateRigidTransformation3D< T >::Matrix3T TRTK::EstimateRigidTransformation3D< T >::getRotationMatrix ( ) const

Template Parameters:

T	scalar type of the coordinates

Returns:: Returns the rotation matrix as part of the sought transformation.

See also:: compute(), getTranslationVector() and getTransformationMatrix()

Definition at line 513 of file EstimateRigidTransformation3D.hpp.

template<class T >

const EstimateTransformation3D< T >::Matrix4T & TRTK::EstimateTransformation3D< T >::getTransformationMatrix ( ) const [virtual, inherited]

Template Parameters:

T	scalar type of the coordinates

Returns:: Returns the sought transformation matrix in the form of a homogeneous 4x4 matrix. (This comprises the rotation as well as the translation, for instances.)

See also:: compute()

Definition at line 195 of file EstimateTransformation3D.hpp.

template<class T >

EstimateRigidTransformation3D< T >::Vector3T TRTK::EstimateRigidTransformation3D< T >::getTranslationVector ( ) const

Template Parameters:

T	scalar type of the coordinates

Returns:: Returns the translation vector as part of the sought transformation.

See also:: compute(), getRotationMatrix() and getTransformationMatrix()

Definition at line 527 of file EstimateRigidTransformation3D.hpp.

template<class T>

void TRTK::EstimateTransformation3D< T >::setSourcePoints ( const std::vector< Coordinate< T > > & source_points ) [inherited]

Sets the source points.

Template Parameters:

T	scalar type of the coordinates

Parameters:

[in] source_points The points can either be plain 3D or 4D homogeneous coordinates.

Exceptions:

ErrorObj If there are any coordinates other than 3D or 4D coordinates, an error object is thrown and its error code is set to WRONG_POINT_SIZE.

Definition at line 215 of file EstimateTransformation3D.hpp.

template<class T>

void TRTK::EstimateTransformation3D< T >::setSourcePoints ( const std::vector< Vector3T > & source_points ) [inherited]

Sets the source points.

Template Parameters:

T	scalar type of the coordinates

Parameters:

[in] source_points 3D coordinates.

Definition at line 247 of file EstimateTransformation3D.hpp.

template<class T>

void TRTK::EstimateTransformation3D< T >::setSourcePoints ( const std::vector< Vector4T, Eigen::aligned_allocator< Vector4T > > & source_points ) [inherited]

Sets the source points.

Template Parameters:

T	scalar type of the coordinates

Parameters:

[in] source_points 4D homogeneous coordinates.

Definition at line 265 of file EstimateTransformation3D.hpp.

template<class T>

void TRTK::EstimateTransformation3D< T >::setTargetPoints ( const std::vector< Vector3T > & target_points ) [inherited]

Sets the target points.

Template Parameters:

T	scalar type of the coordinates

Parameters:

[in] target_points 3D coordinates.

Definition at line 325 of file EstimateTransformation3D.hpp.

template<class T>

void TRTK::EstimateTransformation3D< T >::setTargetPoints ( const std::vector< Vector4T, Eigen::aligned_allocator< Vector4T > > & target_points ) [inherited]

Sets the target points.

Template Parameters:

T	scalar type of the coordinates

Parameters:

[in] target_points 4D homogeneous coordinates.

Definition at line 343 of file EstimateTransformation3D.hpp.

template<class T>

void TRTK::EstimateTransformation3D< T >::setTargetPoints ( const std::vector< Coordinate< T > > & target_points ) [inherited]

Sets the target points.

Template Parameters:

T	scalar type of the coordinates

Parameters:

[in] target_points The points can either be plain 3D or 4D homogeneous coordinates.

Exceptions:

ErrorObj If there are any coordinates other than 3D or 4D coordinates, an error object is thrown and its error code is set to WRONG_POINT_SIZE.

Definition at line 293 of file EstimateTransformation3D.hpp.

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

D:/Programmierung/C/TRTK/include/TRTK/EstimateRigidTransformation3D.hpp

TRTK::EstimateRigidTransformation3D< T > Class Template Reference

Public Types

Public Member Functions

Public Attributes

Protected Attributes

Detailed Description

template<class T> class TRTK::EstimateRigidTransformation3D< T >

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

template<class T>
class TRTK::EstimateRigidTransformation3D< T >