cisstVector API

cisstVector provides fixed-size and dynamic vectors, matrices, and N-arrays with type-safe arithmetic, rotation types, and frame transforms.

Key classes

template<class _elementType> class vctDynamicVector : public vctDynamicVectorBase<vctDynamicVectorOwner<_elementType>, _elementType>

A vector object of dynamic size.

This class defines a vector object of dynamic size with memory allocation. Note that unlike the STL vector class (std::vector), this class is not meant to be used as a dynamic container, but in vector algebra.

The algebraic operations are mostly inherited from the base classes vctDynamicVectorBase and vctDynamicConstVectorBase. Here, we will briefly describe the specific properties of vctDynamicVector, with a few usage examples.

The class is templated by its element type, that is, the vector element. Normally, the element should be an arithmetic type, that is, support all the standard arithmetic operations: +, -, *, /, =, ==, <, >, <=, >=, …
The class uses dynamically allocated memory, and, more importantly, owns the memory. That is, a vctDynamicVector object automatically frees the allocated memory it owns when it is destroyed.

To allocate the memory, use one of the following operations.

// define a typical element type
typedef double ElementType;

// the vectorSize variable can be set to any value at any time
// before creating the vector.
size_t vectorSize = 12;

// constructor allocation
vctDynamicVector<ElementType> v1(vectorSize);

// Create an empty vector and later allocate memory.
vctDynamicVector<ElementType> v2;
v2.SetSize(vectorSize);

// Create a dynamic vector of some size and then change it.
// This operation does not preserve any elements in the resized
// vector
vctDynamicVector<Elements> v3(3 * vectorSize);
v3.SetSize(2 * vectorSize);

// resize a vector and keep as many elements as possible.
v3.resize(vectorSize);

// Store an algebraic result to a new vector.  In this case,
// memory is allocated by the algebraic operation, and then
// attached to the vector object.
vctDynamicVector<double> v4 = v3 - v2;

Vector assignment can be facilitated through the Assign method (defined in the base class) or as follows.

// Initialize all elements to the same value
vctDynamicVector<ElementType> v5(vectorSize, 2.0);

// Initialize the elements by specific value.  NOTE: All the
// arguments MUST be of type ElementType
vctDynamicVector<ElementType> sequence(7,
                                       1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0);

// Assign one vector to another.  This operation reallocates
// space for the target vector.  Note that the right-hand-side
// object can be any ``dynamic'' vector of any element type,
// not just a vctDynamicVector<ElementType>
vctDynamicMatrix<int> someNumbers(numRows, numCols);
v1 = someNumbers.Column(2);

A few more notes.

The stride is always 1, that is, the elements lie in contiguous increasing memory addresses.
There is no direct way of `disowning’ a vctDynamicVector, that is taking ownership of its memory.
When a function returns an allocating dynamic vector object, it is better to return a vctReturnDynamicVector, which is a helper class designed for transfering the ownership of the allocated memory without reallocation.

See also

vctDynamicVectorBase vctDynamicConstVectorBase

Param _elementType:: the type of an element in the vector

Subclassed by mtsHistory< _elementType >, mtsVector< _elementType >, vctReturnDynamicVector< _elementType >

Public Types

typedef vctDynamicVector<_elementType> ThisType

typedef vctDynamicVectorBase<vctDynamicVectorOwner<_elementType>, _elementType> BaseType

typedef BaseType::CopyType CopyType

typedef BaseType::TypeTraits TypeTraits

typedef BaseType::ElementVaArgPromotion ElementVaArgPromotion

Public Functions

VCT_CONTAINER_TRAITS_TYPEDEFS(_elementType)

inline vctDynamicVector(): Default constructor. Initialize an empty vector.

inline explicit vctDynamicVector(size_type size): Constructor: Create a vector of the specified size. Elements initialized with default constructor.

inline vctDynamicVector(size_type size, value_type value): Constructor: Create a vector of the specified size and assign all elements a specific value.

inline vctDynamicVector (size_type size, value_type element0, value_type element1,...) CISST_THROW(std: Constructor for any size greater than or equal to 2, using stdarg macros and variable number of arguments. This operation assumes that all the arguments are of type value_type, and that their number is equal to the size of the vector. The user may need to explicitly cast the parameters to value_type to avoid runtime bugs and errors. We have not checked if stdarg macros can use reference types (probably not), so unlike the other constructors, this constructor takes all arguments by value.

Note

This constructor does not assert that the size is correct, as there is no way to know how many arguments were passed.

inline vctDynamicVector(size_type size, const value_type *values): Constructor: Create a vector of the specified size and assign the elements values from the memory block pointed to

vctDynamicVector(const vctReturnDynamicVector<value_type> &otherVector): Special copy constructor: Take ownership of the data of a temporary vector object of type vctReturnDynamicVector. Disown the other vector.

inline vctDynamicVector(const ThisType &otherVector): Copy constructor: Allocate memory to store a copy of the other vector, and copy the elements of the other vector to this vector.

template<class _otherVectorOwnerType> inline vctDynamicVector(const vctDynamicConstVectorBase<_otherVectorOwnerType, value_type> &otherVector): Copy constructor: Allocate memory and copy all the elements from the other vector.

template<class _otherVectorOwnerType, typename _otherVectorElementType> inline explicit vctDynamicVector(const vctDynamicConstVectorBase<_otherVectorOwnerType, _otherVectorElementType> &otherVector): Copy constructor: Allocate memory and copy all the elements from the other vector. This constructor can also be used for type conversions.

template<size_type __size, stride_type __stride, class __elementType, class __dataPtrType> inline explicit vctDynamicVector(const vctFixedSizeConstVectorBase<__size, __stride, __elementType, __dataPtrType> &fixedVector): Constructor from a fixed-size vector

template<class __vectorOwnerType, typename __elementType> inline ThisType &operator=(const vctDynamicConstVectorBase<__vectorOwnerType, __elementType> &otherVector): Assignment from a dynamic vector to a vector. The operation discards the old memory allocated for this vector, and allocates new memory the size of the input vector. Then the elements of the input vector are copied into this vector.

inline ThisType &operator=(const ThisType &other): Assignment from a dynamic vector to this vector. The operation discards the old memory allocated for this vector, and allocates new memory the size of the input vector. Then the elements of the input vector are copied into this vector.

ThisType &operator=(const vctReturnDynamicVector<value_type> &other): Assignement from a transitional vctReturnDynamicVector to a vctDynamicVector variable. This specialized operation does not perform any element copy. Instead it transfers ownership of the data from the other vector to this vector, and disowns the other vector. The right hand side operand must be a temporary object returned, e.g., from a function or overloaded operator.

inline ThisType &operator=(const value_type &value): Assignement of a scalar to all elements. See also SetAll.

template<class __vectorOwnerType, typename __elementType> inline ThisType &ForceAssign(const vctDynamicConstVectorBase<__vectorOwnerType, __elementType> &other)

template<size_type __size, stride_type __stride, class __elementType, class __dataPtrType> inline ThisType &ForceAssign(const vctFixedSizeConstVectorBase<__size, __stride, __elementType, __dataPtrType> &other)

inline void resize(size_type size): Non-destructive size change. Change the size to the specified size, and copy as many elements as possible from the former vector.

inline void SetSize(size_type size): DESTRUCTIVE size change. Change the size to the specified size. Discard of all the old values.

inline void SetSize(size_type size, const value_type newValue)

inline bool FromStreamRaw(std::istream &inputStream, const char delimiter = ' '): Read from an unformatted text input (e.g., one created by ToStreamRaw). Returns true if successful. This particular implementation assumes that the correct vector size is already set.

inline void DeSerializeRaw(std::istream &inputStream): Binary deserialization

template<class _elementType> vctDynamicVector(const vctReturnDynamicVector<_elementType> &other)

template<class _elementType> vctDynamicVector<_elementType> &operator=(const vctReturnDynamicVector<_elementType> &other)

template<class _elementType> class vctDynamicMatrix : public vctDynamicMatrixBase<vctDynamicMatrixOwner<_elementType>, _elementType>

A matrix object of dynamic size.

This class defines a matrix object of dynamic size with memory allocation.

The algebraic operations are mostly inherited from the base classes vctDynamicMatrixBase and vctDynamicConstMatrixBase. Here, we will briefly describe the specific properties of vctDynamicMatrix, with a few usage examples.

The class is templated by its element type, that is, the matrix element. Normally, the element should be an arithmetic type, that is, support all the standard arithmetic operations: +, -, *, /, =, ==, <, >, <=, >=, …
The class uses dynamically allocated memory, and, more importantly, owns the memory. That is, a vctDynamicMatrix object automatically frees the allocated memory it owns when it is destroyed.

To allocate the memory, use one of the following operations.

// define a typical element type
typedef double ElementType;

// the matrixRows and matrixCols variables can be set to any value at
// any time before creating the matrix.
size_t matrixRows = 12;
size_t matrixCols = 9;

// constructor allocation
vctDynamicMatrix<ElementType> m1(matrixRows, matrixCols);

// Create an empty matrix and later allocate memory.
vctDynamicMatrix<ElementType> m2;
m2.SetSize(matrixRows, matrixCols);

// Create a dynamic matrix of some size and then change it.
// This operation does not preserve any elements in the resized
// matrix
vctDynamicMatrix<Elements> m3(3 * matrixRows, 3 * matrixCols);
m3.SetSize(2 * matrixRows, 2 * matrixCols);

// resize a matrix and keep as many elements as possible.
m3.resize(matrixRows, matrixCols);

// Store an algebraic result to a new matrix.  In this case,
// memory is allocated by the algebraic operation, and then
// attached to the matrix object.
vctDynamicMatrix<double> m4 = m3 - m2;

The default storage order is row first. This can be modified using the different constructors as well as the method SetSize with the flags VCT_ROW_MAJOR or VCT_COL_MAJOR.

// 12 by 7 matrix stored column first
vctDynamicMatrix<double> m1(12, 7, VCT_COL_MAJOR);
// a similar matrix filled with zeroes
vctDynamicMatrix<double> m1(12, 7, 0.0, VCT_COL_MAJOR);
// resize the matrix and change its storage order
m1.SetSize(5, 7, VCT_ROW_MAJOR);

Matrix assignment can be facilitated through the Assign method (defined in the base class) or as follows.

// Initialize all elements to the same value
vctDynamicMatrix<ElementType> v5(matrixRows, matrixCols, 2.0);

// Initialize the elements by specific values.  NOTE: All the
// arguments MUST be of type ElementType
vctDynamicMatrix<ElementType> matrix(2, 4);
matrix.Assign(7.0, 1.0, 2.0, 3.0,
              4.0, 5.0, 6.0, 7.0); // correct
matrix.Assign(7, 1, 2, 3,
              4, 5, 6, 7); // WRONG, missing dot

// Assign one matrix to another.
vctDynamicMatrix<int> matrixInt;
matrixInt.Assign(matrix);
matrixInt = matrix; // same operation

A few more notes.

The elements lie in contiguous increasing memory addresses.
There is no direct way of `disowning’ a vctDynamicMatrix, that is taking ownership of its memory.
When a function returns an allocating dynamic matrix object, it is better to return a vctReturnDynamicMatrix, which is a helper class designed for transfering the ownership of the allocated memory without reallocation.

See also

vctDynamicMatrixBase vctDynamicConstMatrixBase

Param _elementType:: the type of an element in the matrix

Subclassed by mtsMatrix< _elementType >, vctReturnDynamicMatrix< _elementType >

Public Types

enum [anonymous]

Values:

enumerator DIMENSION

typedef vctDynamicMatrixBase<vctDynamicMatrixOwner<_elementType>, _elementType> BaseType

typedef vctDynamicMatrix<_elementType> ThisType

Public Functions

VCT_CONTAINER_TRAITS_TYPEDEFS(_elementType)

VCT_NARRAY_TRAITS_TYPEDEFS(DIMENSION)

inline vctDynamicMatrix(): Default constructor. Initialize an empty matrix.

inline vctDynamicMatrix(size_type rows, size_type cols, bool storageOrder = VCT_DEFAULT_STORAGE)

inline vctDynamicMatrix(const nsize_type &matrixSize, bool storageOrder = VCT_DEFAULT_STORAGE)

inline vctDynamicMatrix(size_type rows, size_type cols, value_type value, bool storageOrder = VCT_DEFAULT_STORAGE): Constructor: Create a matrix of the specified size and assign all elements a specific value. The storage order can be either VCT_ROW_MAJOR or VCT_COL_MAJOR.

inline vctDynamicMatrix(const nsize_type &matrixSize, value_type value, bool storageOrder = VCT_DEFAULT_STORAGE)

vctDynamicMatrix(const vctReturnDynamicMatrix<value_type> &otherMatrix): Special copy constructor: Take ownership of the data of a temporary matrix object of type vctReturnDynamicMatrix. Disown the other matrix.

inline vctDynamicMatrix(const ThisType &otherMatrix): Copy constructor: Allocate memory to store a copy of the other matrix, and copy the elements of the other matrix to this matrix.

template<class __matrixOwnerType, typename __otherMatrixElementType> inline vctDynamicMatrix(const vctDynamicConstMatrixBase<__matrixOwnerType, __otherMatrixElementType> &otherMatrix, bool storageOrder): Copy constructor: Allocate memory and copy all the elements from the other matrix. The storage order can be either VCT_ROW_MAJOR or VCT_COL_MAJOR.

template<class __matrixOwnerType> inline vctDynamicMatrix(const vctDynamicConstMatrixBase<__matrixOwnerType, value_type> &otherMatrix): Copy constructor: Allocate memory and copy all the elements from the other matrix. The storage order of the copied matrix is defined by the source matrix.

template<class __matrixOwnerType, typename __otherMatrixElementType> inline explicit vctDynamicMatrix(const vctDynamicConstMatrixBase<__matrixOwnerType, __otherMatrixElementType> &otherMatrix): Copy constructor: Allocate memory and copy all the elements from the other matrix. The storage order of the copied matrix is defined by the source matrix. This constructor can also be used for type conversions.

template<size_type __rows, size_type __cols, stride_type __rowStride, stride_type __colStride, class __elementType, class __dataPtrType> inline explicit vctDynamicMatrix(const vctFixedSizeConstMatrixBase<__rows, __cols, __rowStride, __colStride, __elementType, __dataPtrType> &other): Constructor from a fixed size matrix.

template<class __matrixOwnerType, typename __elementType> inline ThisType &operator=(const vctDynamicConstMatrixBase<__matrixOwnerType, __elementType> &otherMatrix)

Assignment from a dynamic matrix to a matrix. The operation discards the old memory allocated for this matrix, and allocates new memory the size of the input matrix. Then the elements of the input matrix are copied into this matrix.

Todo:: This assumes a row major storage. Needs more work.

inline ThisType &operator=(const ThisType &otherMatrix): Assignment from a dynamic matrix to this matrix. The operation discards the old memory allocated for this matrix, and allocates new memory the size of the input matrix. Then the elements of the input matrix are copied into this matrix.

template<size_type __rows, size_type __cols, stride_type __rowStride, stride_type __colStride, class __elementType, class __dataPtrType> inline ThisType &operator=(const vctFixedSizeConstMatrixBase<__rows, __cols, __rowStride, __colStride, __elementType, __dataPtrType> &other): Assignment from a fixed size matrix. This operator will resize the left side dynamic matrix to match the right side fixed size matrix.

ThisType &operator=(const vctReturnDynamicMatrix<value_type> &otherMatrix)

Assignement from a transitional vctReturnDynamicMatrix to a vctDynamicMatrix variable. This specialized operation does not perform any element copy. Instead it transfers ownership of the data from the other matrix to this matrix, and disowns the other matrix. The right hand side operand must be a temporary object returned, e.g., from a function or overloaded operator.

Todo:: This operator needs some revisions.

inline ThisType &operator=(const value_type &value): Assignement of a scalar to all elements. See also SetAll.

template<class __matrixOwnerType, typename __elementType> inline ThisType &ForceAssign(const vctDynamicConstMatrixBase<__matrixOwnerType, __elementType> &other)

template<size_type __rows, size_type __cols, stride_type __rowStride, stride_type __colStride, class __elementType, class __dataPtrType> inline ThisType &ForceAssign(const vctFixedSizeConstMatrixBase<__rows, __cols, __rowStride, __colStride, __elementType, __dataPtrType> &other)

inline void resize(size_type rows, size_type cols): Non-destructive size change. Change the size to the specified size, and preserve as many rows and columns as possible from the former matrix.

Note

If the storage order and the sizes (both rows and columns) are unchanged, this method does nothing.

Note

This method doesn’t allow to change the storage order of the elements (i.e. stays either row or column major).

Note

If the size is set to zero, the data pointer is set to null (0).

inline void resize(const nsize_type &newSizes)

inline void SetSize(size_type rows, size_type cols, bool storageOrder): DESTRUCTIVE size change. Change the size to the specified size. Discard of all the old values. The storage order can be either VCT_ROW_MAJOR or VCT_COL_MAJOR. If the storage order is not specified, it is not modified.

inline void SetSize(const nsize_type &matrixSize, bool storageOrder)

inline void SetSize(size_type rows, size_type cols)

inline void SetSize(const nsize_type &matrixSize)

inline void DeSerializeRaw(std::istream &inputStream): Binary deserialization

template<class _elementType> vctDynamicMatrix(const vctReturnDynamicMatrix<_elementType> &other)

template<class _elementType> vctDynamicMatrix<_elementType> &operator=(const vctReturnDynamicMatrix<_elementType> &other)

template<class _elementType, bool _rowMajor> class vctFrame4x4 : public vctFrame4x4Base<vctFixedSizeMatrix<_elementType, 4, 4, _rowMajor>>

Template base class for a 4x4 frame.

This class allows to use a 4 by 4 matrix as a frame in 3D. This is a limited case of the so called homegenous transformations as this class is intended to support only the translation and rotation parts of the transformation. It is not intended to support perspective or scaling operations. The different constructors and normalization methods provided will set the last row to [0 0 0 1].

See also

vctDynamicMatrix, vctFixedSizeMatrix, vctFrameBase

Param _matrixType:: The type of matrix used to store the elements

Public Types

enum [anonymous]

Values:

enumerator ROWS

enumerator COLS

enum [anonymous]

Values:

enumerator DIMENSION

typedef vctFixedSizeMatrix<value_type, ROWS, COLS, _rowMajor> ContainerType

typedef vctFrame4x4Base<ContainerType> BaseType

typedef vctFrame4x4<value_type, _rowMajor> ThisType

typedef cmnTypeTraits<value_type> TypeTraits: Traits used for all useful types and values related to the element type.

Public Functions

VCT_CONTAINER_TRAITS_TYPEDEFS(_elementType)

inline vctFrame4x4(void): Default constructor. Sets the matrix to identity.

inline vctFrame4x4(const ThisType &other): Copy constructor. Uses Assign.

inline ThisType &operator=(const ThisType &other)

template<bool __rowMajor> inline vctFrame4x4(const vctFrame4x4<value_type, __rowMajor> &other): Copy constructor with different storage order, uses Assign

template<bool __rowMajor> inline ThisType &operator=(const vctFrame4x4<value_type, __rowMajor> &other)

template<class __containerType> inline vctFrame4x4(const vctFrame4x4ConstBase<__containerType> &other): Copy constructor from vctFrame4x4ConstBase with a different container type. Uses Assign.

template<class __containerType> inline ThisType &operator=(const vctFrame4x4ConstBase<__containerType> &other)

inline vctFrame4x4(const ContainerType &other): Copy constructor from ContainerType. Uses Assign.

inline ThisType &operator=(const ContainerType &other)

template<class _rotationType, class _translationType> inline vctFrame4x4(const _rotationType &rotation, const _translationType &translation): Constructor from a translation and a rotation.

template<class __containerType> inline explicit vctFrame4x4(const vctFrameBase<__containerType> &other): Constructor from a vctFrameBase. This constructor uses the method From which will test if the input is normalized. If the input is not normalized it will throw an exception of type std::runtime_error.

template<class __containerType> inline vctFrame4x4(const vctFrameBase<__containerType> &other, bool normalizeInput): Constructor from a vctFrameBase. This constructor uses the method FromNormalized or FromRaw based on the second argument (use VCT_NORMALIZE or VCT_DO_NOT_NORMALIZE).

template<class _elementType, bool _rowMajor> class vctMatrixRotation3 : public vctMatrixRotation3Base<vctFixedSizeMatrix<_elementType, 3, 3, _rowMajor>>

Define a rotation matrix for a space of dimension 3.

This class is templated by the element type. It is derived from vctMatrixRotation3Base and uses a vctFixedSizeMatrix as underlying container. It provides a more humain interface for programmers only interested in templating by _elementType.

See also

vctMatrixRotation3Base vctFixedSizeMatrix

Param _elementType:: The type of elements of the matrix.

Constructors with normalization test.

These constructors will check that the input is valid, i.e. normalized. If the input is not normalized, an exception (of type std::runtime_error) will be thrown. Each constructor uses the corresponding From() method based on the input type.

Note

See the cmnThrow() function if an abort is better than an exception for your application.

inline vctMatrixRotation3 (const value_type &element00, const value_type &element01, const value_type &element02, const value_type &element10, const value_type &element11, const value_type &element12, const value_type &element20, const value_type &element21, const value_type &element22) CISST_THROW(std

Constructor from 9 elements.

The parameters are given row first so that the code remains human readable:

vctMatrixRotation3<double> matrix( 0.0, 1.0, 0.0,
                                  -1.0, 0.0, 0.0,
                                   0.0, 0.0, 1.0);

template<stride_type __stride1, class __dataPtrType1, stride_type __stride2, class __dataPtrType2, stride_type __stride3, class __dataPtrType3> inline vctMatrixRotation3 (const vctFixedSizeConstVectorBase< DIMENSION, __stride1, value_type, __dataPtrType1 > &v1, const vctFixedSizeConstVectorBase< DIMENSION, __stride2, value_type, __dataPtrType2 > &v2, const vctFixedSizeConstVectorBase< DIMENSION, __stride3, value_type, __dataPtrType3 > &v3, bool vectorsAreColumns=true) CISST_THROW(std

Constructor from 3 fixed size vectors.

By default the vectors represents the columns of the matrix. If the parameter vectorsAreColumns is set to false, the vectors provided will be used to set the matrix row by row.

template<class __vectorOwnerType1, class __vectorOwnerType2, class __vectorOwnerType3> inline vctMatrixRotation3 (const vctDynamicConstVectorBase< __vectorOwnerType1, value_type > &v1, const vctDynamicConstVectorBase< __vectorOwnerType2, value_type > &v2, const vctDynamicConstVectorBase< __vectorOwnerType3, value_type > &v3, bool vectorsAreColumns=true) CISST_THROW(std

Constructor from 3 dynamic vectors.

By default the vectors represents the columns of the matrix. If the parameter vectorsAreColumns is set to false, the vectors provided will be used to set the matrix row by row.

inline explicit vctMatrixRotation3 (const vctAxisAngleRotation3< value_type > &axisAngleRotation) CISST_THROW(std: Construction from a vctAxisAngleRotation3.

template<class __containerType> inline explicit vctMatrixRotation3 (const vctQuaternionRotation3Base< __containerType > &quaternionRotation) CISST_THROW(std

Constructor from a rotation quaternion. It is important to note that this constructor doesn’t normalize the rotation quaternion but asserts that it is normalized (in debug mode only). See also the method From(quaternion).

Parameters:: quaternionRotation – A unit quaternion

template<class __containerType> inline explicit vctMatrixRotation3 (const vctRodriguezRotation3Base< __containerType > &rodriguezRotation) CISST_THROW(std: Constructor from a vctRodriguezRotation3.

template<vctEulerRotation3Order::OrderType __order> inline explicit vctMatrixRotation3 (const vctEulerRotation3< __order > &eulerRotation) CISST_THROW(std: Constructor from a vctEulerRotation3.

Constructors without normalization test

These constructors will either assume that the input is normalized or normalize the input (a copy of it, if required) based on the last parameter provided.

If the normalization flag is set to VCT_DO_NOT_NORMALIZE, the input is considered already normalized and the constructor will not perform any sanity check. This can lead to numerical instabilities which have to be handled by the caller.
If the normalization flag is set to VCT_NORMALIZE, the input will be normalized. This option should be used whenever it is important to obtain a result as “normalized” as possible.

inline vctMatrixRotation3(const value_type &element00, const value_type &element01, const value_type &element02, const value_type &element10, const value_type &element11, const value_type &element12, const value_type &element20, const value_type &element21, const value_type &element22, bool normalizeInput)

Constructor from 9 elements.

The parameters are given row first so that the code remains human readable:

vctMatrixRotation3<double> matrix( 0.0, 1.0, 0.0,
                                  -1.0, 0.0, 0.0,
                                   0.0, 0.0, 1.0);

template<stride_type __stride1, class __dataPtrType1, stride_type __stride2, class __dataPtrType2, stride_type __stride3, class __dataPtrType3> inline vctMatrixRotation3(const vctFixedSizeConstVectorBase<DIMENSION, __stride1, value_type, __dataPtrType1> &v1, const vctFixedSizeConstVectorBase<DIMENSION, __stride2, value_type, __dataPtrType2> &v2, const vctFixedSizeConstVectorBase<DIMENSION, __stride3, value_type, __dataPtrType3> &v3, bool vectorsAreColumns, bool normalizeInput)

Constructor from 3 fixed size vectors.

By default the vectors represents the columns of the matrix. If the parameter vectorsAreColumns is set to false, the vectors provided will be used to set the matrix row by row.

template<class __vectorOwnerType1, class __vectorOwnerType2, class __vectorOwnerType3> inline vctMatrixRotation3(const vctDynamicConstVectorBase<__vectorOwnerType1, value_type> &v1, const vctDynamicConstVectorBase<__vectorOwnerType2, value_type> &v2, const vctDynamicConstVectorBase<__vectorOwnerType3, value_type> &v3, bool vectorsAreColumns, bool normalizeInput)

Constructor from 3 dynamic vectors.

By default the vectors represents the columns of the matrix. If the parameter vectorsAreColumns is set to false, the vectors provided will be used to set the matrix row by row.

inline vctMatrixRotation3(const vctAxisAngleRotation3<value_type> &axisAngleRotation, bool normalizeInput): Construction from a vctAxisAngleRotation3.

template<class __containerType> inline vctMatrixRotation3(const vctQuaternionRotation3Base<__containerType> &quaternionRotation, bool normalizeInput)

Constructor from a rotation quaternion. It is important to note that this constructor doesn’t normalize the rotation quaternion but asserts that it is normalized (in debug mode only). See also the method From(quaternion).

Parameters:

quaternionRotation – A unit quaternion
normalizeInput – Normalize the input or convert as is (VCT_NORMALIZE or VCT_DO_NOT_NORMALIZE)

template<class __containerType> inline vctMatrixRotation3(const vctRodriguezRotation3Base<__containerType> &rodriguezRotation, bool normalizeInput): Constructor from a vctRodriguezRotation3.

template<vctEulerRotation3Order::OrderType __order> inline vctMatrixRotation3(const vctEulerRotation3<__order> &eulerRotation, bool normalizeInput): Construction from a vctEulerRotation3.

template<stride_type __rowStride, stride_type __colStride, class __dataPtrType> inline explicit vctMatrixRotation3(const vctFixedSizeMatrixBase<ROWS, COLS, __rowStride, __colStride, value_type, __dataPtrType> &matrix): Initialize this rotation matrix with a 3x3 matrix. This constructor only takes a matrix of the same element type.

Note

This constructor does not verify normalization. It is introduced to allow using results of matrix operations and assign them to a rotation matrix.

Note

The constructor is declared explicit, to force the user to be aware of the conversion being made.

Public Types

enum [anonymous]

Values:

enumerator ROWS

enumerator COLS

enum [anonymous]

Values:

enumerator DIMENSION

typedef vctFixedSizeMatrix<value_type, ROWS, COLS, _rowMajor> ContainerType

typedef vctMatrixRotation3Base<ContainerType> BaseType

typedef vctMatrixRotation3ConstBase<ContainerType> ConstBaseType

typedef vctMatrixRotation3<value_type, _rowMajor> ThisType

typedef cmnTypeTraits<value_type> TypeTraits: Traits used for all useful types and values related to the element type.

Public Functions

VCT_CONTAINER_TRAITS_TYPEDEFS(_elementType)

inline vctMatrixRotation3(void): Default constructor. Sets the rotation matrix to identity.

inline vctMatrixRotation3(const ThisType &other)

inline vctMatrixRotation3(const BaseType &other)

inline vctMatrixRotation3(const ConstBaseType &other)

inline explicit vctMatrixRotation3(const vctDynamicMatrixRef<value_type> &other)

inline ThisType &operator=(const ContainerType &other): The assignment from BaseType (i.e. a 3 by 3 fixed size matrix) has to be redefined for this class (C++ restriction). This operator uses the Assign() method inherited from the BaseType. This operator (as well as the Assign method) allows to set a rotation matrix to whatever value without any further validity checking. It is recommended to use it with caution.

inline ThisType &operator=(const ThisType &other)

inline ThisType &operator=(const BaseType &other)

class vctAngleRotation2

Define a rotation based on an angle for a space of dimension 2.

This class is not templated by the element type. It contains an angle of type AngleType.

See also

vctMatrixRotation2Base vctMatrixRotation2

Constructors with normalization test.

These constructors will check that the input is valid, i.e. normalized. If the input is not normalized, an exception (of type std::runtime_error) will be thrown. Each constructor uses the corresponding From() method based on the input type.

Note

See the cmnThrow() function if an abort is better than an exception for your application.

inline explicit vctAngleRotation2 (const AngleType angle) CISST_THROW(std: Constructor from an angle (in radians).

template<class _containerType> inline vctAngleRotation2 (const vctMatrixRotation2Base< _containerType > &matrixRotation) CISST_THROW(std: Constructor from a rotation matrix.

Constructors without normalization test

These constructors will either assume that the input is normalized or normalize the input (a copy of it, if required) based on the last parameter provided.

If the normalization flag is set to VCT_DO_NOT_NORMALIZE, the input is considered already normalized and the constructor will not perform any sanity check. This can lead to numerical instabilities which have to be handled by the caller.
If the normalization flag is set to VCT_NORMALIZE, the input will be normalized. This option should be used whenever it is important to obtain a result as “normalized” as possible.

inline vctAngleRotation2(const AngleType angle, bool normalizeInput): Constructor from an angle (in radians).

template<class _containerType> inline vctAngleRotation2(const vctMatrixRotation2Base<_containerType> &matrixRotation, bool normalizeInput): Constructor from a rotation matrix.

inline const AngleType &Angle(void) const

inline AngleType &Angle(void)

static const ThisType &Identity(): Const reference to the identity. In this case, the angle is set to zero.

Conversion from normalized input.

These methods will check that the input is normalized. If the input is not normalized, an exception (std::runtime_error) will be thrown using cmnThrow().

Note

Since all exceptions are thrown using cmnThrow(), it is possible to configure these methods to use abort() if the normalization requirements are not met (see cmnThrow()).

inline ThisType & From (const AngleType angle) CISST_THROW(std: Conversion from an angle (in radians).

template<class _containerType> inline ThisType & From (const vctMatrixRotation2Base< _containerType > &matrixRotation) CISST_THROW(std: Conversion from a rotation matrix.

Conversion and normalization.

These method will accept any input and attempt to either normalize the input and then convert or convert and then normalize the quaternion itself.

The order depends on the type of input.

inline ThisType &FromNormalized(const AngleType angle): Conversion from an angle (in radians).

template<class _containerType> inline ThisType &FromNormalized(const vctMatrixRotation2Base<_containerType> &matrixRotation): Conversion from a rotation matrix.

Conversion.

These method don’t check if the input is normalized nor try to normalize the results. They should be used with caution since the resulting rotation (in this case a quaternion) might not be normalized.

inline ThisType &FromRaw(const AngleType angle): Conversion from an angle (in radians).

template<class _containerType> inline ThisType &FromRaw(const vctMatrixRotation2Base<_containerType> &matrixRotation): Conversion from a rotation matrix.

inline ThisType &InverseSelf(void): Inverse this angle rotation. This methods assumes that the angle is betweem 0 and 2 * PI. The angle is set to 2 * PI minus the previous value.

inline ThisType &InverseOf(const ThisType &otherRotation): Set this rotation as the inverse of another one. See also InverseSelf().

inline ThisType Inverse(void) const: Create and return by copy the inverse of this rotation. This method is not the most efficient since it requires a copy. See also InverseSelf().

inline ThisType &NormalizedSelf(void): Normalizes the angle. This method ensures that the angle is between 0 and 2 * PI.

inline ThisType &NormalizedOf(const ThisType &otherRotation)

Sets this rotation as the normalized version of another one.

Parameters:: otherRotation – Angle rotation used to compute the normalized rotation.

inline ThisType Normalized(void) const: Returns the normalized version of this rotation. This method returns a copy of the normalized rotation and does not modify this rotation. See also NormalizedSelf().

inline bool IsNormalized(AngleType CMN_UNUSED(tolerance) = TypeTraits::Tolerance()) const

Test if this rotation is normalized. This methods always return “true” since any angle is considered valid. This method is provided mostly for API completion.

Parameters:: tolerance – Tolerance. This variable is not used as this rotation is always normalized. The tolerance parameter is provided just to have the same signature as for other transformations.

inline std::string ToString(void) const

inline void ToStream(std::ostream &outputStream) const: Print the matrix in a human readable format

inline void ToStreamRaw(std::ostream &outputStream, const char CMN_UNUSED(delimiter) = ' ', bool headerOnly = false, const std::string &headerPrefix = "") const: Print in machine processable format

inline void SerializeRaw(std::ostream &outputStream) const: Binary serialization

inline void DeSerializeRaw(std::istream &inputStream): Binary deserialization

Public Types

enum [anonymous]

Values:

enumerator DIMENSION

typedef vctAngleRotation2 ThisType

typedef cmnTypeTraits<AngleType> TypeTraits

Public Functions

VCT_CONTAINER_TRAITS_TYPEDEFS(double)

inline vctAngleRotation2(): Default constructor. Sets the angle to zero.

template<class _elementType> class vctAxisAngleRotation3

Define a rotation based on an axis and an angle for a space of dimension 3.

This class is templated by the element type. It contains a fixed size vector and an angle.

See also

vctQuaternion

Param _elementType:: The type of elements.

Constructors with normalization test.

These constructors will check that the input is valid, i.e. normalized. If the input is not normalized, an exception (of type std::runtime_error) will be thrown. Each constructor uses the corresponding From() method based on the input type.

Note

See the cmnThrow() function if an abort is better than an exception for your application.

template<stride_type __stride, class __dataPtrType> inline vctAxisAngleRotation3 (const vctFixedSizeConstVectorBase< DIMENSION, __stride, value_type, __dataPtrType > &axis, const AngleType angle) CISST_THROW(std

Constructor from an axis and an angle.

Parameters:

axis – A unit vector of size 3.
angle – The angle in radian

template<class _vectorOwnerType> inline vctAxisAngleRotation3 (const vctDynamicConstVectorBase< _vectorOwnerType, value_type > &axis, AngleType angle) CISST_THROW(std

Constructor from an axis and an angle.

Parameters:

axis – A unit vector of size 3.
angle – The angle in radian

template<class _containerType> inline explicit vctAxisAngleRotation3 (const vctQuaternionRotation3Base< _containerType > &quaternionRotation) CISST_THROW(std: Constructor from a vctQuaternionRotation3.

template<class _containerType> inline explicit vctAxisAngleRotation3 (const vctMatrixRotation3Base< _containerType > &matrixRotation) CISST_THROW(std: Constructor from a vctMatrixRotation3.

template<class _containerType> inline explicit vctAxisAngleRotation3 (const vctRodriguezRotation3Base< _containerType > &rodriguezRotation) CISST_THROW(std: Constructor from a vctRodriguezRotation3.

Constructors without normalization test

These constructors will either assume that the input is normalized or normalize the input (a copy of it, if required) based on the last parameter provided:

If the normalization flag is set to VCT_DO_NOT_NORMALIZE, the input is considered already normalized and the constructor will not perform any sanity check. This can lead to numerical instabilities which have to be handled by the caller.
If the normalization flag is set to VCT_NORMALIZE, the input will be normalized. This option should be used whenever it is important to obtain a result as “normalized” as possible.

template<stride_type __stride, class __dataPtrType> inline vctAxisAngleRotation3(const vctFixedSizeConstVectorBase<DIMENSION, __stride, value_type, __dataPtrType> &axis, const AngleType angle, bool normalizeInput)

Constructor from an axis and an angle.

Parameters:

axis – A vector of size 3.
angle – The angle in radian
normalizeInput – Normalize the input or convert as is (VCT_NORMALIZE or VCT_DO_NOT_NORMALIZE)

template<class _vectorOwnerType> inline vctAxisAngleRotation3(const vctDynamicConstVectorBase<_vectorOwnerType, value_type> &axis, AngleType angle, bool normalizeInput)

Constructor from an axis and an angle.

Parameters:

axis – A vector of size 3.
angle – The angle in radian
normalizeInput – Normalize the input or convert as is (VCT_NORMALIZE or VCT_DO_NOT_NORMALIZE)

template<class _containerType> inline vctAxisAngleRotation3(const vctQuaternionRotation3Base<_containerType> &quaternionRotation, bool normalizeInput): Constructor from a vctQuaternionRotation3.

template<class _containerType> inline vctAxisAngleRotation3(const vctMatrixRotation3Base<_containerType> &matrixRotation, bool normalizeInput): Constructor from a vctMatrixRotation3.

template<class _containerType> inline vctAxisAngleRotation3(const vctRodriguezRotation3Base<_containerType> &rodriguezRotation, bool normalizeInput): Constructor from a vctRodriguezRotation3.

inline const AxisType &Axis(void) const: Const reference to the rotation axis data member.

inline AxisType &Axis(void): Reference to the rotation axis data member.

inline const AngleType &Angle(void) const: Const reference to the rotation angle data member (in radians).

inline AngleType &Angle(void): Reference to the rotation angle data member (in radians).

static const ThisType &Identity(): Const reference to the identity. In this case, the axis is set to (1, 0, 0) and the angle is set to zero.

Conversion from normalized input.

These methods will check that the input is normalized. If the input is not normalized, an exception (std::runtime_error) will be thrown using cmnThrow().

Note

Since all exceptions are thrown using cmnThrow(), it is possible to configure these methods to use abort() if the normalization requirements are not met (see cmnThrow()).

template<stride_type __stride, class __dataPtrType> inline ThisType & From (const vctFixedSizeConstVectorBase< DIMENSION, __stride, value_type, __dataPtrType > &axis, const AngleType angle) CISST_THROW(std: Conversion from an angle and an axis.

template<class _vectorOwnerType> inline ThisType & From (const vctDynamicConstVectorBase< _vectorOwnerType, value_type > &axis, AngleType angle) CISST_THROW(std: Conversion from an angle and an axis.

template<class _containerType> inline ThisType & From (const vctQuaternionRotation3Base< _containerType > &quaternionRotation) CISST_THROW(std: Conversion from a vctQuaternionRotation3.

template<class _containerType> inline ThisType & From (const vctMatrixRotation3Base< _containerType > &matrixRotation) CISST_THROW(std: Conversion from a vctMatrixRotation3.

template<class _containerType> inline ThisType & From (const vctRodriguezRotation3Base< _containerType > &rodriguezRotation) CISST_THROW(std: Conversion from a vctRodriguezRotation3.

Conversion and normalization.

These method will accept any input and attempt to either normalize the input and then convert or convert and then normalize the quaternion itself.

The order depends on the type of input.

template<stride_type __stride, class __dataPtrType> inline ThisType &FromNormalized(const vctFixedSizeConstVectorBase<DIMENSION, __stride, value_type, __dataPtrType> &axis, const AngleType angle): Conversion from an axis and an angle.

template<class _containerType> inline ThisType &FromNormalized(const vctQuaternionRotation3Base<_containerType> &quaternionRotation): Conversion from an axis and an angle.

template<class _containerType> inline ThisType &FromNormalized(const vctMatrixRotation3Base<_containerType> &matrixRotation): Conversion from a vctMatrixRotation3.

template<class _containerType> inline ThisType &FromNormalized(const vctRodriguezRotation3Base<_containerType> &rodriguezRotation): Conversion from a vctRodriguezRotation3.

Conversion.

These method don’t check if the input is normalized nor try to normalize the results. They should be used with caution since the resulting rotation (in this case a quaternion) might not be normalized.

template<stride_type __stride, class __dataPtrType> inline ThisType &FromRaw(const vctFixedSizeConstVectorBase<DIMENSION, __stride, value_type, __dataPtrType> &axis, const AngleType angle): Conversion from an axis and an angle.

template<class _containerType> inline ThisType &FromRaw(const vctQuaternionRotation3Base<_containerType> &quaternionRotation): Conversion from a vctQuaternionRotation3.

template<class _containerType> inline ThisType &FromRaw(const vctMatrixRotation3Base<_containerType> &matrixRotation): Conversion from a vctMatrixRotation3.

template<class _containerType> inline ThisType &FromRaw(const vctRodriguezRotation3Base<_containerType> &rodriguezRotation): Conversion from a vctRodriguezRotation3.

inline ThisType &InverseSelf(void): Inverse this axis angle rotation. This methods assumes that the axis is normalized and the angle is betweem 0 and 2 * PI. The axis is not changed but the angle is set to 2 * PI minus the previous value.

inline ThisType &InverseOf(const ThisType &otherRotation): Set this rotation as the inverse of another one. See also InverseSelf().

inline ThisType Inverse(void) const: Create and return by copy the inverse of this rotation. This method is not the most efficient since it requires a copy. See also InverseSelf().

inline ThisType &NormalizedSelf(void): Normalizes this rotation. This method first normalizes the axis and then modifies the angle so that it’s value is between 0 and 2 * PI.

inline ThisType &NormalizedOf(const ThisType &otherRotation)

Sets this rotation as the normalized version of another one.

Parameters:: otherRotation – Axis angle rotation used to compute the normalized rotation.

inline ThisType Normalized(void) const: Returns the normalized version of this rotation. This method returns a copy of the normalized rotation and does not modify this rotation. See also NormalizedSelf().

inline bool IsNormalized(value_type tolerance = TypeTraits::Tolerance()) const

Test if this rotation is normalized. This methods checks that the axis is normalized (with tolerance). Any angle is considered valid.

Parameters:: tolerance – Tolerance for the norm test.

inline bool Equal(const ThisType &other) const

Return true if this rotation is exactly equal to the other rotation, without any tolerance error. Rotations may be effectively equal if one is elementwise equal to the other.

See also

AlmostEqual

inline bool operator==(const ThisType &other) const

inline bool AlmostEqual(const ThisType &other, value_type tolerance = TypeTraits::Tolerance()) const

Return true if this rotation is effectively equal to the other rotation, up to the given tolerance. Rotations may be effectively equal if one is elementwise equal to the other.

The tolerance factor is used to compare each of the elements of the difference vector.

See also

AlmostEquivalent

inline bool AlmostEquivalent(const ThisType &other, value_type tolerance = TypeTraits::Tolerance()) const

Return true if this rotation is effectively equavilent to the other rotation, up to the given tolerance. Rotation may be effectively equivalent if their axis are aligned and their angles are equal, modulus 2 PI (take into account the direction of the axis).

The tolerance factor is used to compare each of the elements of the difference vector.

See also

AlmostEqual

inline std::string ToString(void) const

inline void ToStream(std::ostream &outputStream) const: Print the matrix in a human readable format

inline void ToStreamRaw(std::ostream &outputStream, const char delimiter = ' ', bool headerOnly = false, const std::string &headerPrefix = "") const: Print in machine processable format

inline void SerializeRaw(std::ostream &outputStream) const: Binary serialization

inline void DeSerializeRaw(std::istream &inputStream): Binary deserialization

Public Types

enum [anonymous]

Values:

enumerator DIMENSION

typedef vctAxisAngleRotation3<value_type> ThisType

typedef vctFixedSizeVector<value_type, DIMENSION> AxisType

typedef cmnTypeTraits<_elementType> TypeTraits

Public Functions

VCT_CONTAINER_TRAITS_TYPEDEFS(_elementType)

inline vctAxisAngleRotation3(): Default constructor. Sets the axis to (1, 0, 0) and the angle to zero.

inline ThisType &Assign(const ThisType &other): Assignement method. This method doesn’t perform any test on the input.

template<vctEulerRotation3Order::OrderType _order> class vctEulerRotation3 : public vctEulerRotation3Base

Public Types

typedef vctEulerRotation3<_order> ThisType

typedef vctEulerRotation3Base BaseType

Public Functions

inline vctEulerRotation3()

inline vctEulerRotation3(const ThisType &other)

inline vctEulerRotation3(double phi, double theta, double psi)

inline vctEulerRotation3(double *angles)

inline vctEulerRotation3(const vct3 &angles)

inline ThisType &operator=(const ThisType &other)

template<class __containerType> inline vctEulerRotation3 (const vctMatrixRotation3Base< __containerType > &matrixRotation) CISST_THROW(std: Constructor from a vctMatrixRotation3.

template<class __containerType> inline vctEulerRotation3(const vctMatrixRotation3Base<__containerType> &matrixRotation, bool normalizeInput): Constructor from a vctMatrixRotation3.

inline ~vctEulerRotation3()

template<class _matrixType> inline ThisType & From (const vctMatrixRotation3Base< _matrixType > &matrixRot) CISST_THROW(std: Conversion from a vctMatrixRotation3.

template<class _matrixType> inline ThisType &FromNormalized(const vctMatrixRotation3Base<_matrixType> &matrixRot): Conversion from a vctMatrixRotation3.

template<class _matrixType> inline ThisType &FromRaw(const vctMatrixRotation3Base<_matrixType> &matrixRotation): Conversion from a vctMatrixRotation3.

inline const vct3 &GetAngles(void) const: Returns the Euler angles in radians

inline vct3 &GetAngles(void)

inline vct3 GetAnglesInDegrees(void) const: Returns the Euler angles in degrees

inline ThisType &InverseOf(const ThisType &otherRotation): Set this rotation as the inverse of another one. See also InverseSelf().

inline ThisType Inverse(void) const: Create and return by copy the inverse of this rotation.

inline ThisType &NormalizedOf(const ThisType &otherRotation)

Sets this rotation as the normalized version of another one.

Parameters:: otherRotation – Euler rotation used to compute the normalized rotation.

inline ThisType Normalized(void) const: Returns the normalized version of this rotation. This method returns a copy of the normalized rotation and does not modify this rotation. See also NormalizedSelf().

inline bool Equal(const ThisType &other) const

Return true if this rotation is exactly equal to the other rotation, without any tolerance error. Rotations may be effectively equal if one is elementwise equal to the other.

See also

AlmostEqual

inline bool operator==(const ThisType &other) const

inline bool AlmostEqual(const ThisType &other, double tolerance = TypeTraits::Tolerance()) const

Return true if this rotation is effectively equal to the other rotation, up to the given tolerance. Rotations may be effectively equal if one is elementwise equal to the other.

The tolerance factor is used to compare each of the elements of the difference vector.

See also

AlmostEquivalent

inline bool AlmostEquivalent(const ThisType &other, double tolerance = TypeTraits::Tolerance()) const

Return true if this rotation is effectively equavilent to the other rotation, up to the given tolerance.

The tolerance factor is used to compare each of the elements of the difference vector.

See also

AlmostEqual

inline std::string ToString(void) const

inline void ToStream(std::ostream &outputStream) const: Print the Euler rotation in a human readable format

inline void ToStreamRaw(std::ostream &outputStream, const char delimiter = ' ', bool headerOnly = false, const std::string &headerPrefix = "") const: Print in machine processable format

inline void SerializeRaw(std::ostream &outputStream) const: Binary serialization

inline void DeSerializeRaw(std::istream &inputStream): Binary deserialization