G3D::Matrix Class Reference

N x M matrix. More...

Classes
class	Impl
	Used internally by Matrix. More...

Public Types
typedef float	T
	Internal precision. More...

Public Member Functions
	Matrix ()
	Matrix (const Matrix3 &M)
	Matrix (const Matrix4 &M)
	Matrix (int R, int C)
	Returns a new matrix that is all zero. More...
Matrix	abs () const
void	abs (Matrix &out) const
Matrix	adjoint () const
bool	allNonZero () const
	Returns true if all elements are non-zero. More...
bool	allZero () const
bool	anyNonZero () const
	Returns true if any element is non-zero. More...
bool	anyZero () const
Matrix	arrayCos () const
void	arrayCos (Matrix &out) const
void	arrayDivInPlace (const Matrix &B)
	Mutates this. More...
void	arrayExp (Matrix &out) const
Matrix	arrayExp () const
Matrix	arrayLog () const
void	arrayLog (Matrix &out) const
Matrix	arrayMul (const Matrix &B) const
void	arrayMulInPlace (const Matrix &B)
	Mutates this. More...
Matrix	arraySin () const
void	arraySin (Matrix &out) const
Matrix	arraySqrt () const
void	arraySqrt (Matrix &out) const
Matrix	col (int c) const
int	cols () const
	Number of columns. More...
T	determinant () const
Matrix	gaussJordanPseudoInverse () const
	(ATA)-1AT) computed using Gauss-Jordan elimination. More...
T	get (int r, int c) const
Matrix	inverse () const
	A-1 computed using the Gauss-Jordan algorithm, for square matrices. More...
Matrix	lsub (const T &B) const
	scalar B - this More...
void	mulRow (int r, const T &v)
void	negate (Matrix &out) const
Matrix	negate () const
double	norm () const
	2-norm (sqrt(sum(squares)) More...
double	normSquared () const
	2-norm squared: sum(squares). More...
int	numElements () const
Matrix	operator!= (const T &scalar) const
Matrix	operator* (const Matrix &B) const
	Matrix multiplication. More...
Matrix	operator* (const T &B) const
	See also A *= B, which is more efficient in many cases. More...
Matrix &	operator*= (const T &B)
	Generally more efficient than A * B. More...
Matrix &	operator*= (const Matrix &B)
	No performance advantage over A * B because matrix multiplication requires intermediate storage. More...
Matrix	operator+ (const Matrix &B) const
	See also A += B, which is more efficient in many cases. More...
Matrix	operator+ (const T &v) const
	See also A += B, which is more efficient in many cases. More...
Matrix &	operator+= (const T &B)
	Generally more efficient than A + B. More...
Matrix &	operator+= (const Matrix &B)
	Generally more efficient than A + B. More...
Matrix	operator- (const Matrix &B) const
	See also A -= B, which is more efficient in many cases. More...
Matrix	operator- (const T &v) const
	See also A -= B, which is more efficient in many cases. More...
Matrix	operator- () const
Matrix &	operator-= (const T &B)
	Generally more efficient than A - B. More...
Matrix &	operator-= (const Matrix &B)
	Generally more efficient than A - B. More...
Matrix &	operator/= (const T &B)
	Generally more efficient than A / B. More...
Matrix	operator< (const T &scalar) const
Matrix	operator<= (const T &scalar) const
Matrix	operator== (const T &scalar) const
Matrix	operator> (const T &scalar) const
Matrix	operator>= (const T &scalar) const
Matrix	pseudoInverse (float tolerance=-1) const
	Computes the Moore-Penrose pseudo inverse, equivalent to (ATA)-1AT). More...
Matrix	row (int r) const
int	rows () const
	The number of rows. More...
void	serialize (TextOutput &t) const
	Serializes in Matlab source format. More...
void	set (int r, int c, T v)
void	setCol (int c, const Matrix &vec)
void	setRow (int r, const Matrix &vec)
Vector2int16	size () const
Matrix	subMatrix (int r1, int r2, int c1, int c2) const
	Returns a new matrix that is a subset of this one, from r1:r2 to c1:c2, inclusive. More...
void	svd (Matrix &U, Array< T > &d, Matrix &V, bool sort=true) const
	Singular value decomposition. More...
Matrix	svdPseudoInverse (float tolerance=-1) const
	Called from pseudoInverse when the matrix has size > 4 along some dimension. More...
void	swapAndNegateCols (int c0, int c1)
	Swaps columns c0 and c1 and negates both. More...
void	swapRows (int r0, int r1)
Matrix3	toMatrix3 () const
Matrix4	toMatrix4 () const
String	toString (const String &name) const
String	toString () const
Vector2	toVector2 () const
Vector3	toVector3 () const
Vector4	toVector4 () const
Matrix	transpose () const
	AT More...
void	transpose (Matrix &out) const
	Transpose in place; more efficient than transpose. More...

Static Public Member Functions
template<class S >
static Matrix	fromDiagonal (const Array< S > &d)
static Matrix	fromDiagonal (const Matrix &d)
static Matrix	identity (int N)
	Returns a new identity matrix. More...
static Matrix	one (int R, int C)
	Returns a new matrix that is all one. More...
static Matrix	random (int R, int C)
	Uniformly distributed values between zero and one. More...
static const char *	svdCore (float **U, int rows, int cols, float *D, float **V)
	Low-level SVD functionality. More...
static Matrix	zero (int R, int C)
	Returns a new matrix that is all zero. More...

Static Public Attributes
static int	debugNumAllocOps
	Incremented every time a new matrix object is allocated. More...
static int	debugNumCopyOps
	Incremented every time the elements of a matrix are copied. More...

Detailed Description

N x M matrix.

The actual data is tracked internally by a reference counted pointer; it is efficient to pass and assign Matrix objects because no data is actually copied. This avoids the headache of pointers and allows natural math notation:

   Matrix A, B, C;
   // ...

   C = A * f(B);
   C = C.inverse();

   A = Matrix::identity(4);
   C = A;
   C.set(0, 0, 2.0); // Triggers a copy of the data so that A remains unchanged.

   // etc.

The Matrix::debugNumCopyOps and Matrix::debugNumAllocOps counters increment every time an operation forces the copy and allocation of matrices. You can use these to detect slow operations when efficiency is a major concern.

Some methods accept an output argument instead of returning a value. For example, A = B.transpose() can also be invoked as B.transpose(A). The latter may be more efficient, since Matrix may be able to re-use the storage of A (if it has approximatly the right size and isn't currently shared with another matrix).

See also

G3D::Matrix3, G3D::Matrix4, G3D::Vector2, G3D::Vector3, G3D::Vector4, G3D::CoordinateFrame

BETA API Likely to receive incompatible changes in future releases.

Member Typedef Documentation

T

typedef float G3D::Matrix::T

Internal precision.

Currently float, but this may become a templated class in the future to allow operations like Matrix<double> and Matrix<ComplexFloat>.

Not necessarily a plain-old-data type (e.g., could ComplexFloat), but must be something with no constructor, that can be safely memcpyd, and that has a bit pattern of all zeros when zero.

Constructor & Destructor Documentation

Matrix() [1/4]

G3D::Matrix::Matrix ( )

inline

Referenced by adjoint(), inverse(), and transpose().

Matrix() [2/4]

G3D::Matrix::Matrix ( const Matrix3 &  M )

inline

Matrix() [3/4]

G3D::Matrix::Matrix ( const Matrix4 &  M )

inline

Matrix() [4/4]

G3D::Matrix::Matrix ( int  R, int  C  )

inline

Returns a new matrix that is all zero.

Member Function Documentation

abs() [1/2]

Matrix G3D::Matrix::abs ( ) const

inline

Referenced by abs().

abs() [2/2]

void G3D::Matrix::abs

(

Matrix &

out

)

const

adjoint()

Matrix G3D::Matrix::adjoint ( ) const

inline

allNonZero()

bool G3D::Matrix::allNonZero

(

)

const

Returns true if all elements are non-zero.

Referenced by anyZero().

allZero()

bool G3D::Matrix::allZero ( ) const

inline

anyNonZero()

bool G3D::Matrix::anyNonZero

(

)

const

Returns true if any element is non-zero.

Referenced by allZero().

anyZero()

bool G3D::Matrix::anyZero ( ) const

inline

arrayCos() [1/2]

Matrix G3D::Matrix::arrayCos ( ) const

inline

arrayCos() [2/2]

void G3D::Matrix::arrayCos

(

Matrix &

out

)

const

arrayDivInPlace()

void G3D::Matrix::arrayDivInPlace

(

const Matrix &

B

)

Mutates this.

arrayExp() [1/2]

void G3D::Matrix::arrayExp

(

Matrix &

out

)

const

arrayExp() [2/2]

Matrix G3D::Matrix::arrayExp ( ) const

inline

arrayLog() [1/2]

Matrix G3D::Matrix::arrayLog ( ) const

inline

arrayLog() [2/2]

void G3D::Matrix::arrayLog

(

Matrix &

out

)

const

arrayMul()

Matrix G3D::Matrix::arrayMul ( const Matrix &  B ) const

inline

arrayMulInPlace()

void G3D::Matrix::arrayMulInPlace

(

const Matrix &

B

)

Mutates this.

arraySin() [1/2]

void G3D::Matrix::arraySin

(

Matrix &

out

)

const

arraySin() [2/2]

Matrix G3D::Matrix::arraySin ( ) const

inline

arraySqrt() [1/2]

void G3D::Matrix::arraySqrt

(

Matrix &

out

)

const

arraySqrt() [2/2]

Matrix G3D::Matrix::arraySqrt ( ) const

inline

col()

Matrix G3D::Matrix::col

(

int

c

)

const

cols()

int G3D::Matrix::cols ( ) const

inline

Number of columns.

Referenced by adjoint(), numElements(), size(), and transpose().

determinant()

T G3D::Matrix::determinant ( ) const

inline

fromDiagonal() [1/2]

template<class S >

static Matrix G3D::Matrix::fromDiagonal ( const Array< S > &  d )

inlinestatic

fromDiagonal() [2/2]

static Matrix G3D::Matrix::fromDiagonal ( const Matrix &  d )

static

gaussJordanPseudoInverse()

Matrix G3D::Matrix::gaussJordanPseudoInverse ( ) const

inline

(A^TA)^-1A^T) computed using Gauss-Jordan elimination.

get()

T G3D::Matrix::get	(	int	r,
		int	c
	)		const

identity()

static Matrix G3D::Matrix::identity ( int  N )

static

Returns a new identity matrix.

inverse()

Matrix G3D::Matrix::inverse ( ) const

inline

A^-1 computed using the Gauss-Jordan algorithm, for square matrices.

Run time is O(R³), where R is the number of rows.

lsub()

Matrix G3D::Matrix::lsub ( const T &  B ) const

inline

scalar B - this

Referenced by operator-().

mulRow()

void G3D::Matrix::mulRow	(	int	r,
		const T &	v
	)

negate() [1/2]

Matrix G3D::Matrix::negate ( ) const

inline

Referenced by operator-().

negate() [2/2]

void G3D::Matrix::negate

(

Matrix &

out

)

const

norm()

double G3D::Matrix::norm

(

)

const

2-norm (sqrt(sum(squares))

normSquared()

double G3D::Matrix::normSquared

(

)

const

2-norm squared: sum(squares).

(i.e., dot product with itself)

numElements()

int G3D::Matrix::numElements ( ) const

inline

one()

static Matrix G3D::Matrix::one ( int  R, int  C  )

static

Returns a new matrix that is all one.

operator!=()

Matrix G3D::Matrix::operator!=

(

const T &

scalar

)

const

operator*() [1/2]

Matrix G3D::Matrix::operator* ( const Matrix &  B ) const

inline

Matrix multiplication.

To perform element-by-element multiplication, see arrayMul.

operator*() [2/2]

Matrix G3D::Matrix::operator* ( const T &  B ) const

inline

See also A *= B, which is more efficient in many cases.

operator*=() [1/2]

Matrix& G3D::Matrix::operator*=

(

const T &

B

)

Generally more efficient than A * B.

operator*=() [2/2]

Matrix& G3D::Matrix::operator*=

(

const Matrix &

B

)

No performance advantage over A * B because matrix multiplication requires intermediate storage.

operator+() [1/2]

Matrix G3D::Matrix::operator+ ( const Matrix &  B ) const

inline

See also A += B, which is more efficient in many cases.

operator+() [2/2]

Matrix G3D::Matrix::operator+ ( const T &  v ) const

inline

See also A += B, which is more efficient in many cases.

operator+=() [1/2]

Matrix& G3D::Matrix::operator+=

(

const T &

B

)

Generally more efficient than A + B.

operator+=() [2/2]

Matrix& G3D::Matrix::operator+=

(

const Matrix &

B

)

Generally more efficient than A + B.

operator-() [1/3]

Matrix G3D::Matrix::operator- ( const Matrix &  B ) const

inline

See also A -= B, which is more efficient in many cases.

operator-() [2/3]

Matrix G3D::Matrix::operator- ( const T &  v ) const

inline

See also A -= B, which is more efficient in many cases.

operator-() [3/3]

Matrix G3D::Matrix::operator- ( ) const

inline

operator-=() [1/2]

Matrix& G3D::Matrix::operator-=

(

const T &

B

)

Generally more efficient than A - B.

operator-=() [2/2]

Matrix& G3D::Matrix::operator-=

(

const Matrix &

B

)

Generally more efficient than A - B.

operator/=()

Matrix& G3D::Matrix::operator/=

(

const T &

B

)

Generally more efficient than A / B.

operator<()

Matrix G3D::Matrix::operator<

(

const T &

scalar

)

const

operator<=()

Matrix G3D::Matrix::operator<=

(

const T &

scalar

)

const

operator==()

Matrix G3D::Matrix::operator==

(

const T &

scalar

)

const

operator>()

Matrix G3D::Matrix::operator>

(

const T &

scalar

)

const

operator>=()

Matrix G3D::Matrix::operator>=

(

const T &

scalar

)

const

pseudoInverse()

Matrix G3D::Matrix::pseudoInverse

(

float

tolerance = -1

)

const

Computes the Moore-Penrose pseudo inverse, equivalent to (A^TA)^-1A^T).

The SVD method is used for performance when the matrix has more than four rows or columns

Referenced Code: http://en.wikipedia.org/wiki/MooreE2%80%93Penrose_pseudoinverse

Parameters

tolerance

Use -1 for automatic tolerance.

random()

static Matrix G3D::Matrix::random ( int  R, int  C  )

static

Uniformly distributed values between zero and one.

row()

Matrix G3D::Matrix::row

(

int

r

)

const

rows()

int G3D::Matrix::rows ( ) const

inline

The number of rows.

Referenced by adjoint(), numElements(), size(), and transpose().

serialize()

void G3D::Matrix::serialize

(

TextOutput &

t

)

const

Serializes in Matlab source format.

set()

void G3D::Matrix::set	(	int	r,
		int	c,
		T	v
	)

Referenced by fromDiagonal().

setCol()

void G3D::Matrix::setCol	(	int	c,
		const Matrix &	vec
	)

setRow()

void G3D::Matrix::setRow	(	int	r,
		const Matrix &	vec
	)

size()

Vector2int16 G3D::Matrix::size ( ) const

inline

Referenced by G3D::Matrix::Impl::operator new().

subMatrix()

Matrix G3D::Matrix::subMatrix	(	int	r1,
		int	r2,
		int	c1,
		int	c2
	)		const

Returns a new matrix that is a subset of this one, from r1:r2 to c1:c2, inclusive.

svd()

void G3D::Matrix::svd	(	Matrix &	U,
		Array< T > &	d,
		Matrix &	V,
		bool	sort = true
	)		const

Singular value decomposition.

Factors into three matrices such that this = U * fromDiagonal(d) * V.transpose().

The matrix must have at least as many rows as columns.

Run time is O(C²*R).

Parameters

sort	If true (default), the singular values are arranged so that D is sorted from largest to smallest.

svdCore()

static const char* G3D::Matrix::svdCore ( float **  U, int  rows, int  cols, float *  D, float **  V  )

static

Low-level SVD functionality.

Useful for applications that do not want to construct a Matrix but need to perform the SVD operation.

this = U * D * V'

Assumes that rows >= cols

Returns

nullptr on success, a string describing the error on failure.

Parameters

U	rows x cols matrix to be decomposed, gets overwritten with U, a rows x cols matrix with orthogonal columns.
D	vector of singular values of a (diagonal of the D matrix). Length cols.
V	returns the right orthonormal transformation matrix, size cols x cols

Referenced Code: Based on Dianne Cook's implementation, which is adapted from

svdecomp.c in XLISP-STAT 2.1, which is code from Numerical Recipes adapted by Luke Tierney and David Betz. The Numerical Recipes code is adapted from Forsythe et al, who based their code on Golub and Reinsch's original implementation.

svdPseudoInverse()

Matrix G3D::Matrix::svdPseudoInverse

(

float

tolerance = -1

)

const

Called from pseudoInverse when the matrix has size > 4 along some dimension.

swapAndNegateCols()

void G3D::Matrix::swapAndNegateCols	(	int	c0,
		int	c1
	)

Swaps columns c0 and c1 and negates both.

swapRows()

void G3D::Matrix::swapRows	(	int	r0,
		int	r1
	)

toMatrix3()

Matrix3 G3D::Matrix::toMatrix3

(

)

const

toMatrix4()

Matrix4 G3D::Matrix::toMatrix4

(

)

const

toString() [1/2]

String G3D::Matrix::toString

(

const String &

name

)

const

toString() [2/2]

String G3D::Matrix::toString ( ) const

inline

toVector2()

Vector2 G3D::Matrix::toVector2

(

)

const

toVector3()

Vector3 G3D::Matrix::toVector3

(

)

const

toVector4()

Vector4 G3D::Matrix::toVector4

(

)

const

transpose() [1/2]

Matrix G3D::Matrix::transpose ( ) const

inline

A^T

Referenced by gaussJordanPseudoInverse().

transpose() [2/2]

void G3D::Matrix::transpose

(

Matrix &

out

)

const

Transpose in place; more efficient than transpose.

zero()

static Matrix G3D::Matrix::zero ( int  R, int  C  )

static

Returns a new matrix that is all zero.

Referenced by fromDiagonal().

Member Data Documentation

debugNumAllocOps

int G3D::Matrix::debugNumAllocOps

static

Incremented every time a new matrix object is allocated.

Useful for profiling your own code that uses Matrix to determine when it is slow due to allocation.

debugNumCopyOps

int G3D::Matrix::debugNumCopyOps

static

Incremented every time the elements of a matrix are copied.

Useful for profiling your own code that uses Matrix to determine when it is slow due to copying.