matrix3x3 Class Reference

Represents a real 3x3 matrix. More...

#include <matrix3x3.h>

List of all members.

Public Member Functions
	matrix3x3 (void)
	constructs the zero-matrix
	matrix3x3 (double s)
	constructs s times the unit matrix
	matrix3x3 (vector3 row1, vector3 row2, vector3 row3)
	constructs a matrix from row vectors
	matrix3x3 (double d[3][3])
	constructs a matrix from a 3x3-array of doubles
void	GetArray (double *m)
	access function
matrix3x3	inverse (void) const throw (OBError)
	Calculates the inverse of a matrix.
matrix3x3	transpose (void) const
	Calculates the transpose of a matrix.
void	randomRotation (OBRandom &rnd)
	generates a matrix for a random rotation
double	determinant () const
	returns the determinant of the matrix
bool	isSymmetric (void) const
	Checks if a matrix is symmetric.
bool	isOrthogonal (void) const
	Checks if a matrix is orthogonal.
bool	isDiagonal (void) const
	Checks if a matrix is diagonal.
bool	isUnitMatrix (void) const
	Checks if a matrix is the unit matrix.
double	Get (int row, int column) const
	access function
void	Set (int row, int column, double v)
	access function
void	SetColumn (int column, const vector3 &v) throw (OBError)
	access function
void	SetRow (int row, const vector3 &v) throw (OBError)
	access function
vector3	GetColumn (unsigned int col) const throw (OBError)
	access function
vector3	GetRow (unsigned int row) const throw (OBError)
	access function
matrix3x3 &	operator/= (const double &c)
	divides all entries of the matrix by a scalar c
void	SetupRotMat (double, double, double)
void	PlaneReflection (const vector3 &norm)
	calculates a matrix that represents reflection on a plane
void	RotAboutAxisByAngle (const vector3 &axis, const double angle)
	calculates a rotation matrix
void	FillOrth (double, double, double, double, double, double)
matrix3x3	findEigenvectorsIfSymmetric (vector3 &eigenvals) const throw (OBError)
	find the eigenvalues and -vectors of a symmetric matrix
Static Public Member Functions
static void	jacobi (unsigned int n, double *a, double *d, double *v)
	eigenvalue calculation
Friends
vector3	operator * (const matrix3x3 &, const vector3 &)
	matrix-vector multiplication
matrix3x3	operator * (const matrix3x3 &, const matrix3x3 &)
	matrix-matrix multiplication
std::ostream &	operator<< (std::ostream &, const matrix3x3 &)

---

Detailed Description

Represents a real 3x3 matrix.

Rotating points in space can be performed by a vector-matrix multiplication. The matrix3x3 class is designed as a helper to the vector3 class for rotating points in space. The rotation matrix may be initialised by passing in the array of floating point values, by passing euler angles, or a rotation vector and angle of rotation about that vector. Once set, the matrix3x3 class can be used to rotate vectors by the overloaded multiplication operator. The following demonstrates the usage of the matrix3x3 class:

  matrix3x3 mat;
  mat.SetupRotMat(0.0,180.0,0.0); //rotate theta by 180 degrees
  vector3 v = VX;
  v *= mat; //apply the rotation

---

Constructor & Destructor Documentation

matrix3x3

(

void

)

[inline]

constructs the zero-matrix

matrix3x3

(

double

s

)

[inline]

constructs s times the unit matrix

matrix3x3	(	vector3	row1,
		vector3	row2,
		vector3	row3
	)			[inline]

constructs a matrix from row vectors

matrix3x3

(

double

d[3][3]

)

[inline]

constructs a matrix from a 3x3-array of doubles

constructs a matrix from a 3x3-array of doubles. The first index represents the row, the second index the column

---

Member Function Documentation

void GetArray

(

double *

m

)

[inline]

access function

writes the matrix into the 1-dimensional array m, row by row. The array must be able to hold 9 doubles, otherwise your prgram will segfault.

matrix3x3 inverse

(

void

)

const throw (OBError)

Calculates the inverse of a matrix.

This method checks if the absolute value of the determinant is smaller than 1e-6. If so, nothing is done and an exception is thrown. Otherwise, the inverse matrix is calculated and returned. *this is not changed.

Warning:

If the determinant is close to zero, but not == 0.0, this method may behave in unexpected ways and return almost random results; details may depend on your particular floating point implementation. The use of this method is therefore highly discouraged, unless you are certain that the determinant is in a reasonable range, away from 0.0 (Stefan Kebekus)

matrix3x3 transpose

(

void

)

const

Calculates the transpose of a matrix.

void randomRotation

(

OBRandom &

rnd

)

generates a matrix for a random rotation

the axis of the rotation will be uniformly distributed on the unit sphere, the angle will be uniformly distributed in the interval 0..360 degrees.

double determinant

(

)

const

returns the determinant of the matrix

bool isSymmetric

(

void

)

const

Checks if a matrix is symmetric.

This method returns false if there are indices i,j such that fabs(*this[i][j]-*this[j][i]) > 1e-6. Otherwise, it returns true.

bool isOrthogonal

(

void

)

const [inline]

Checks if a matrix is orthogonal.

This method checks if a matrix describes an orthogonal transformation, i.e. if all column vectors are normalized and are mutually orthogonal. An orthogonal transformation is a transformation the preserves length and angle.

The check is performed using the method isUnitMatrix() to check if

    *this * transpose()

is a unit matrix. The criterion is therefore numerically quite tight.

bool isDiagonal

(

void

)

const

Checks if a matrix is diagonal.

This method returns false if there are indices i != j such that fabs(*this[i][j]) > 1e-6. Otherwise, it returns true.

bool isUnitMatrix

(

void

)

const

Checks if a matrix is the unit matrix.

This method returns false if there are indices i != j such that fabs(*this[i][j]) > 1e-6, or if there is an index i such that fabs(*this[i][j]-1) > 1e-6. Otherwise, it returns true.

double Get	(	int	row,
		int	column
	)			const [inline]

access function

Warning:

row or column are not in the range 0..2, random results are returned, and your program may even segfault. (Stefan Kebekus)

Todo:

Replace this method with a more fool-proof version.

void Set	(	int	row,
		int	column,
		double	v
	)			[inline]

access function

Warning:

if row or column are not in the range 0..2, random variables are overwritten, and your program may segfault. (Stefan Kebekus)

Todo:

Replace this method with a more fool-proof version.

void SetColumn	(	int	column,
		const vector3 &	v
	)			throw (OBError)

access function

Warning:

If column is not in the range 0..2, the vector remains unchanged and an exception is thrown.

void SetRow	(	int	row,
		const vector3 &	v
	)			throw (OBError)

access function

Warning:

If column is not in the range 0..2, the vector remains unchanged and an exception is thrown.

vector3 GetColumn

(

unsigned int

col

)

const throw (OBError)

access function

Warning:

If col is not in the range 0..2, an exception is thrown.

vector3 GetRow

(

unsigned int

row

)

const throw (OBError)

access function

Warning:

If row is not in the range 0..2, an exception is thrown.

matrix3x3 & operator/=

(

const double &

c

)

divides all entries of the matrix by a scalar c

void SetupRotMat	(	double	,
		double	,
		double
	)

void PlaneReflection

(

const vector3 &

norm

)

calculates a matrix that represents reflection on a plane

Replaces *this with a matrix that represents reflection on the plane through 0 which is given by the normal vector norm.

Warning:

If the vector norm has length zero, this method will generate the 0-matrix. If the length of the axis is close to zero, but not == 0.0, this method may behave in unexpected ways and return almost random results; details may depend on your particular floating point implementation. The use of this method is therefore highly discouraged, unless you are certain that the length is in a reasonable range, away from 0.0 (Stefan Kebekus)

Deprecated:

This method will probably replaced by a safer algorithm in the future.

Todo:

Replace this method with a more fool-proof version.

Parameters:

norm

specifies the normal to the plane

void RotAboutAxisByAngle	(	const vector3 &	v,
		const double	angle
	)

calculates a rotation matrix

Replaces *this with a matrix that represents rotation about the axis by a an angle.

Warning:

If the vector axis has length zero, this method will generate the 0-matrix. If the length of the axis is close to zero, but not == 0.0, this method may behave in unexpected ways and return almost random results; details may depend on your particular floating point implementation. The use of this method is therefore highly discouraged, unless you are certain that the length is in a reasonable range, away from 0.0 (Stefan Kebekus)

Deprecated:

This method will probably replaced by a safer algorithm in the future.

Todo:

Replace this method with a more fool-proof version.

Parameters:

	v	specifies the axis of the rotation
	angle	angle in degrees (0..360)

void FillOrth	(	double	,
		double	,
		double	,
		double	,
		double	,
		double
	)

matrix3x3 findEigenvectorsIfSymmetric

(

vector3 &

eigenvals

)

const throw (OBError)

find the eigenvalues and -vectors of a symmetric matrix

This method employs the static method matrix3x3::jacobi(...) to find the eigenvalues and eigenvectors of a symmetric matrix. On entry it is checked if the matrix really is symmetric: if isSymmetric() returns 'false', an OBError is thrown.

Note:

The jacobi algorithm is should work great for all symmetric 3x3 matrices. If you need to find the eigenvectors of a non-symmetric matrix, you might want to resort to the sophisticated routines of LAPACK.

Parameters:

eigenvals

a reference to a vector3 where the eigenvalues will be stored. The eigenvalues are ordered so that eigenvals[0] <= eigenvals[1] <= eigenvals[2].

Returns:

an orthogonal matrix whose ith column is an eigenvector for the eigenvalue eigenvals[i]. Here 'orthogonal' means that all eigenvectors have length one and are mutually orthogonal. The ith eigenvector can thus be conveniently accessed by the GetColumn() method, as in the following example.

  // Calculate eigenvectors and -values
  vector3 eigenvals;
  matrix3x3 eigenmatrix = somematrix.findEigenvectorsIfSymmetric(eigenvals);
  
  // Print the 2nd eigenvector
  cout << eigenmatrix.GetColumn(1) << endl;

With these conventions, a matrix is diagonalized in the following way:

  // Diagonalize the matrix
  matrix3x3 diagonalMatrix = eigenmatrix.inverse() * somematrix * eigenmatrix;

void jacobi	(	unsigned int	n,
		double *	a,
		double *	d,
		double *	v
	)			[static]

eigenvalue calculation

This static function computes the eigenvalues and eigenvectors of a SYMMETRIC nxn matrix. This method is used internally by OpenBabel, but may be useful as a general eigenvalue finder.

The algorithm uses Jacobi transformations. It is described e.g. in Wilkinson, Reinsch "Handbook for automatic computation, Volume II: Linear Algebra", part II, contribution II/1. The implementation is also similar to the implementation in this book. This method is adequate to solve the eigenproblem for small matrices, of size perhaps up to 10x10. For bigger problems, you might want to resort to the sophisticated routines of LAPACK.

Note:

If you plan to find the eigenvalues of a symmetric 3x3 matrix, you will probably prefer to use the more convenient method findEigenvectorsIfSymmetric()

Parameters:

	n	the size of the matrix that should be diagonalized
	a	array of size n^2 which holds the symmetric matrix whose eigenvectors are to be computed. The convention is that the entry in row r and column c is addressed as a[n*r+c] where, of course, 0 <= r < n and 0 <= c < n. There is no check that the matrix is actually symmetric. If it is not, the behaviour of this function is undefined. On return, the matrix is overwritten with junk.
	d	pointer to a field of at least n doubles which will be overwritten. On return of this function, the entries d[0]..d[n-1] will contain the eigenvalues of the matrix.
	v	an array of size n^2 where the eigenvectors will be stored. On return, the columns of this matrix will contain the eigenvectors. The eigenvectors are normalized and mutually orthogonal.

---

Friends And Related Function Documentation

vector3 operator *	(	const matrix3x3 &	m,
		const vector3 &	v
	)			[friend]

matrix-vector multiplication

calculates the product m*v of the matrix m and the column vector represented by v

matrix3x3 operator *	(	const matrix3x3 &	A,
		const matrix3x3 &	B
	)			[friend]

matrix-matrix multiplication

std::ostream& operator<<	(	std::ostream &	co,
		const matrix3x3 &	m
	)			[friend]

---

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

• matrix3x3.h
• matrix3x3.cpp

---

This file is part of the documentation for Open Babel, version 2.0.2.

Documentation copyright © 1998-2005, the Open Babel Developers.
Open Babel is hosted by:
Generated on Thu Nov 30 20:18:09 2006 by  1.5.1.