kjb::Matrix Class Reference

This class implements matrices, in the linear-algebra sense, with real-valued elements. More...

#include <m_matrix.h>

Public Types
typedef double	Value_type
	data type of the elements More...
typedef Value_type	value_type
	data type of the elements More...
typedef int	Size_type
	size type of the elements More...
typedef kjb_c::Matrix	Impl_type
	the underlying implementation More...
typedef Matrix	Mat_type
	the associated matrix type More...
typedef Vector	Vec_type
	the associated vector type More...
typedef Value_type(*	Mapper )(Value_type)
	element transformer fun More...

Public Member Functions
	Matrix ()
	Default ctor builds a matrix of zero rows, zero columns. More...
	Matrix (int rows, int cols)
	Ctor builds a matrix of specified number of rows and columns. More...
	Matrix (unsigned rows, unsigned cols)
	Ctor builds a matrix of specified number of rows and columns. More...
	Matrix (unsigned rows, unsigned cols, Value_type val)
	Ctor builds a matrix of specified number of rows and columns. More...
	Matrix (unsigned long rows, unsigned long cols)
	Ctor builds a matrix of specified number of rows and columns. More...
	Matrix (unsigned long rows, unsigned long cols, Value_type val)
	Ctor builds a matrix of specified number of rows and columns. More...
	Matrix (int rows, int cols, Value_type num)
	Ctor builds a matrix of specified size, all entries set to num. More...
	Matrix (int rows, int cols, const Value_type *data)
	Ctor builds a matrix and initializes entries from an array. More...
	Matrix (const Vec_type &)
	Ctor builds a single-column matrix from a vector. More...
	Matrix (const Int_matrix &)
	Ctor builds a matrix from one with integer values. More...
	Matrix (const Matrix_view &)
	Ctor builds a matrix from a view of another matrix. More...
	Matrix (const Const_matrix_view &)
	Ctor builds a matrix from a constant view of another matrix. More...
	Matrix (Impl_type *mat_ptr)
	Conversion ctor: claim ownership of an existing matrix pointer (i.e., make a shallow copy). More...
	Matrix (const Impl_type &mat_ref)
	Ctor copies contents (i.e., a deep copy) of an existing C-struct matrix. More...
	Matrix (const std::string &file_name)
	Read matrix from file. More...
	Matrix (const Matrix &mat_ref)
	Copy ctor. More...
	~Matrix ()
Matrix &	zero_out (int num_rows, int num_cols)
	Resize matrix, replace contents with the identity matrix. More...
Matrix &	zero_out (int rows)
	Resize matrix to be square, and clobber contents with zeroes. More...
Matrix &	zero_out ()
	Clobber contents of matrix with zeroes. More...
Matrix &	limit_values (Value_type low, Value_type high)
	Make sure all values in this matrix are between the two given values. More...
Matrix &	operator= (const Impl_type &mat_ref)
	Clone of square version of zero_out(int) More...
Matrix &	operator= (const Matrix &src)
	Assign contents from a kjb::Matrix, a C++ object. More...
void	swap (Matrix &other)
	Swap the representations of two matrices. More...
int	get_num_rows () const
	Return the number of rows in the matrix. More...
int	get_num_cols () const
	Return the number of columns in the matrix. More...
int	get_length () const
	Return the number of elements in the matrix. More...
int	size () const
	Return the number of elements in the matrix. (alias of get_length) More...
Impl_type *&	get_underlying_representation_with_guilt ()
	Get pointer to the underlying kjb_c::Matrix C struct. More...
const Impl_type *	get_c_matrix () const
	Get const pointer to the underlying kjb_c::Matrix C struct. More...
Matrix &	resize (int new_rows, int new_cols, Value_type pad=Value_type(0))
	Resize this matrix, retaining previous values. Space is reused if possible. Otherwise requires a new allocation and old space is freed. More...
Matrix &	realloc (int new_rows, int new_cols)
	resize this matrix, losing previous data. Faster than resize(), because data copy is skipped. More...
Matrix &	reserve (int new_rows, int new_cols)
	allocate sufficient storage to hold the given dimensions, but leave actual matrix size unchanged. Useful when calling Matrix::vertcat inside a tight loop, to avoid multiple reallocations More...
Matrix	transpose () const
	Transpose this matrix. More...
Matrix	inverse () const
	Invert this matrix. More...
double	abs_of_determinant () const
	Gets the absolute value of the determinant of this matrix. More...
double	trace () const
	Gets trace of this matrix. More...
Vec_type	get_diagonal () const
	Retrieves the diagonal of this matrix; returned as a vector. More...
Int_matrix	floor () const
	Return the floor(3) of each element of the matrix. More...
Int_matrix	ceil () const
	Return the ceil(3) of each element of the matrix. More...
Int_matrix	threshold (double t) const
	Convert to a binary matrix; zero if value is below threshold, one if value is greater than or equal to threshold. More...
void	check_bounds (int row, int col) const
	Test whether the given row and column indices are valid. More...
Value_type &	operator[] (int i)
	Subscript matrix like a one-dimensional C array, e.g., A[10], using row-major ordering, and returning an lvalue. More...
const Value_type &	operator[] (int i) const
	Subscript matrix like a one-dimensional C array, e.g., A[10], using row-major ordering, and returning an rvalue. More...
Value_type &	operator() (int i)
	MATLAB-style one-dimensional subscript of matrix, e.g., A(10), using row-major ordering, and returning an lvalue. More...
const Value_type &	operator() (int i) const
	MATLAB-style one-dimensional subscript of matrix, e.g., A(10), using row-major ordering, and returning an rvalue. More...
Value_type &	operator() (int row, int col)
	Access matrix like a Fortran or MATLAB two-dimensional array, e.g., A(2,4), and return an lvalue. More...
const Value_type &	operator() (int row, int col) const
	Access matrix like a Fortran or MATLAB two-dimensional array, e.g., A(2,4), and return an rvalue. More...
Matrix_view	operator() (const Index_range &rows, const Index_range &cols)
Const_matrix_view	operator() (const Index_range &rows, const Index_range &cols) const
Matrix_vector_view	operator[] (const Index_range &i)
Const_matrix_vector_view	operator[] (const Index_range &i) const
Value_type &	at (int i)
	Access matrix like a one-dimensional array, using row-major ordering, and returning an lvalue. More...
const Value_type &	at (int i) const
	Access matrix like a one-dimensional array, using row-major ordering, and returning an rvalue. More...
Value_type &	at (int row, int col)
	Access matrix with bounds checking and return an lvalue. More...
const Value_type &	at (int row, int col) const
	Access matrix with bounds checking and return an rvalue. More...
Matrix &	replace (int row, int col, const Matrix &A)
	Replace a submatrix of this matrix with the given matrix. More...
Matrix &	vertcat (const Matrix &A)
	Concat this matrix with another vertically. (named after the equivalent Matlab function) More...
Matrix &	horzcat (const Matrix &A)
	Concat this matrix with another horizontally. (named after the equivalent Matlab function) Because of how memory is arranged, this is generally slower than vertcat. More...
Vec_type	get_row (int row) const
	Return a specified row of this matrix, in the form of a Vector. More...
Vec_type	get_col (int col) const
	Return a specified column of this matrix, in the form of a Vector. More...
template<typename OutputIterator >
OutputIterator	get_all_rows (OutputIterator result) const
	Return all rows of this matrix into the provided iterator. More...
template<typename OutputIterator >
OutputIterator	get_all_cols (OutputIterator result) const
	Return all columns of this matrix into the provided iterator. More...
template<class Generic_vector >
void	set_row (int row, const Generic_vector &v)
	Replace a row of the matrix with the given vector. More...
template<class Iterator >
void	set_row (int row, Iterator begin, Iterator end)
	Dispatch for set_row. Don't call directly. More...
template<class Generic_vector >
void	set_col (int col, const Generic_vector &v)
	Replace a column of the matrix with the given vector. "vector" can be any collection of values convertible to double. More...
template<class Iterator >
void	set_col (int col, Iterator begin, Iterator end)
	Dispatch for set_col. Don't call directly. More...
void	fill_row (int row, Value_type x)
void	fill_col (int col, Value_type x)
Matrix	submatrix (int row, int col, int num_rows, int num_cols) const
	Get the submatrix given by the parameters; i.e., get A(row, col, row + num_rows, col + num_cols), where A is this matrix. More...
int	read (const char *filename=0)
	Reads the matrix contents from a file specified by name. More...
int	write (const char *filename=0) const
	Writes the matrix contents to a file specified by name. More...
int	write_raw (const char *filename=0) const
	Writes the matrix contents to a file specified by name. More...
Matrix &	operator*= (const Matrix &op2)
	Compute product of this matrix (on the left) and another, and replace this matrix with the result. More...
Matrix &	multiply (const Matrix &op2)
	Compute product of this matrix (on the left) and another, and replace this matrix with the result, like *=. More...
Matrix &	operator*= (Value_type op2)
	Multiply this matrix by a scalar, in place. More...
Matrix &	multiply (Value_type op2)
	Multiply this matrix by a scalar, in place. More...
Matrix &	operator/= (Value_type op2)
	Divide each entry in the matrix by a scalar value. More...
Matrix &	divide (Value_type op2)
	Divide each entry in the matrix by a scalar value. More...
Matrix &	scale_matrix_rows_by_sums ()
	something luca will document eventually More...
Matrix &	operator+= (const Matrix &op2)
	Add, in place, a matrix to this matrix. More...
Matrix &	operator+= (double x)
	Subtract a scalar from all elements of this matrix, in place. More...
Matrix &	add (const Matrix &op2)
	Add, in place, a matrix to this matrix. More...
Matrix &	operator-= (const Matrix &op2)
	Subtract another matrix from this matrix, in place. More...
Matrix &	shift_rows_by (const Vector &v)
	Shift each row by a vector, in place. More...
Matrix &	shift_columns_by (const Vector &v)
	Shift each column by a vector, in place. More...
Matrix &	ew_multiply_rows_by (const Vector &v)
	elementwise multiply each row by a vector, in place More...
Matrix &	ew_multiply_by (const Matrix &m)
	elementwise multiply by another matrix More...
Matrix &	operator-= (double x)
	Subtract a scalar from all elements of this matrix, in place. More...
Matrix &	subtract (const Matrix &op2)
	Subtract another matrix from this matrix, in place. More...
Matrix &	negate ()
	Transform this matrix into the additive inverse of its former value, in place. More...
Mat_type &	mapcar (Mapper)
	Transform the elements of a matrix. More...
void	convert_to_euler_rotation_matrix (float phi, float theta, float psi)
	Creates an euler rotation matrix without reallocating memory, when possible. More...
void	convert_to_euler_homo_rotation_matrix (float phi, float theta, float psi)
void	convert_to_3d_rotation_matrix (double phi, double x, double y, double z)
void	convert_to_2d_rotation_matrix (double phi)
void	convert_to_3d_rotation_matrix (double phi, const Vector &vec)
void	convert_to_3d_rotation_matrix_from_vector (double phi, const Vector &vec)
void	convert_to_3d_homo_rotation_matrix (double phi, double x, double y, double z)
void	convert_to_2d_homo_rotation_matrix (double phi)
void	convert_to_3d_homo_rotation_matrix (double phi, const Vector &vec)
void	convert_to_3d_homo_rotation_matrix_from_vector (double phi, const Vector &vec)
void	convert_to_3d_scaling_matrix (double x, double y, double z)
void	convert_to_3d_scaling_matrix (const Vector &vec)
void	convert_to_3d_scaling_matrix_from_vector (const Vector &vec)
void	convert_to_3d_homo_scaling_matrix (double x, double y, double z)
void	convert_to_3d_homo_scaling_matrix (const Vector &vec)
void	convert_to_3d_homo_scaling_matrix_from_vector (const Vector &vec)
void	convert_to_3d_homo_translation_matrix (double x, double y, double z)
void	convert_to_3d_homo_translation_matrix (const Vector &vec)
void	convert_to_3d_homo_translation_matrix_from_vector (const Vector &vec)
int	display (const char *title=NULL) const
Matrix	map (Value_type(*f)(Value_type)) const
Vec_type	filter (bool(*f)(Value_type))
Value_type	reduce (Value_type(*f)(Value_type x, Value_type y), Value_type init=0.0) const
	call function f using every element of the matrix as an input More...
void	ow_add_scalar (Value_type c)
	add a scalar value to each element of a matrix, in place More...
void	ow_add_row_vector (const Vec_type v)
	add a row vector to each row of a matrix, in place More...
void	ow_add_col_vector (const Vec_type v)
	add a column vector to each column of a matrix, in place More...
void	ow_multiply_col_vector_ew (const Vec_type v)
	multiply a column vector by each column of a matrix, elementwise, in place More...
void	ow_multiply_row_vector_ew (const Vec_type v)
	multiply a row vector by each row of a matrix, elementwise, in place More...
void	ow_vertical_flip ()
	flip the matrix vertically (swap last, first row, etc.) More...
void	ow_horizontal_flip ()
	flip the matrix horizontally (swap left, right columns, etc.) More...

Static Public Member Functions
static Matrix	create_euler_rotation_matrix (float phi, float theta, float psi)
	Creates an euler rotation matrix and stores it into an instance of claa Matrix. More...
static Matrix	create_euler_homo_rotation_matrix (float phi, float theta, float psi)
static Matrix	create_3d_rotation_matrix (double phi, double x, double y, double z)
static Matrix	create_2d_rotation_matrix (double phi)
static Matrix	create_3d_rotation_matrix (double phi, const Vector &vec)
static Matrix	create_3d_rotation_matrix_from_vector (double phi, const Vector &vec)
static Matrix	create_3d_homo_rotation_matrix (double phi, double x, double y, double z)
static Matrix	create_2d_homo_rotation_matrix (double phi)
static Matrix	create_3d_homo_rotation_matrix (double phi, const Vector &vec)
static Matrix	create_3d_homo_rotation_matrix_from_vector (double phi, const Vector &vec)
static Matrix	create_3d_scaling_matrix (double x, double y, double z)
static Matrix	create_3d_scaling_matrix (const Vector &vec)
static Matrix	create_3d_scaling_matrix_from_vector (const Vector &vec)
static Matrix	create_3d_homo_scaling_matrix (double x, double y, double z)
static Matrix	create_3d_homo_scaling_matrix (const Vector &vec)
static Matrix	create_3d_homo_scaling_matrix_from_vector (const Vector &vec)
static Matrix	create_3d_homo_translation_matrix (double x, double y, double z)
static Matrix	create_3d_homo_translation_matrix (const Vector &vec)
static Matrix	create_3d_homo_translation_matrix_from_vector (const Vector &vec)

Friends
bool	operator< (const Matrix &op1, const Matrix &op2)
	Returns true if a is lexicographically less-than b. More...

Detailed Description

This class implements matrices, in the linear-algebra sense, with real-valued elements.

For better maintainability, refer to the element type using this class's Value_type typedef, instead of referring to 'double' directly.

Most methods of this class are implemented in the C language portion of the KJB library, with this class forming a thin (usually inlined) layer.

Member Typedef Documentation

typedef kjb_c::Matrix kjb::Matrix::Impl_type

the underlying implementation

typedef Value_type(* kjb::Matrix::Mapper)(Value_type)

element transformer fun

typedef Matrix kjb::Matrix::Mat_type

the associated matrix type

typedef int kjb::Matrix::Size_type

size type of the elements

typedef double kjb::Matrix::Value_type

data type of the elements

typedef Value_type kjb::Matrix::value_type

data type of the elements

typedef Vector kjb::Matrix::Vec_type

the associated vector type

Constructor & Destructor Documentation

kjb::Matrix::Matrix ( )

inline

Default ctor builds a matrix of zero rows, zero columns.

kjb::Matrix::Matrix ( int  rows, int  cols  )

inline

Ctor builds a matrix of specified number of rows and columns.

kjb::Matrix::Matrix ( unsigned  rows, unsigned  cols  )

inline

Ctor builds a matrix of specified number of rows and columns.

Warning

Native type for number of rows, columns is int, not unsigned.

kjb::Matrix::Matrix ( unsigned  rows, unsigned  cols, Value_type  val  )

inline

Ctor builds a matrix of specified number of rows and columns.

Warning

Native type for number of rows, columns is int, not unsigned.

kjb::Matrix::Matrix ( unsigned long  rows, unsigned long  cols  )

inline

Ctor builds a matrix of specified number of rows and columns.

Warning

Native type for number of rows, cols is int, not unsigned long.

kjb::Matrix::Matrix ( unsigned long  rows, unsigned long  cols, Value_type  val  )

inline

Ctor builds a matrix of specified number of rows and columns.

Warning

Native type for number of rows, cols is int, not unsigned long.

kjb::Matrix::Matrix ( int  rows, int  cols, Value_type  num  )

inline

Ctor builds a matrix of specified size, all entries set to num.

kjb::Matrix::Matrix	(	int	rows,
		int	cols,
		const Value_type *	data
	)

Ctor builds a matrix and initializes entries from an array.

The data array must be of length at least (rows x cols). The matrix is filled in row-major order.

kjb::Matrix::Matrix

(

const Vec_type &

vec

)

Ctor builds a single-column matrix from a vector.

kjb::Matrix::Matrix

(

const Int_matrix &

imat

)

Ctor builds a matrix from one with integer values.

kjb::Matrix::Matrix

(

const Matrix_view &

mat_view

)

Ctor builds a matrix from a view of another matrix.

kjb::Matrix::Matrix

(

const Const_matrix_view &

mat_view

)

Ctor builds a matrix from a constant view of another matrix.

kjb::Matrix::Matrix ( Impl_type *  mat_ptr )

inline

Conversion ctor: claim ownership of an existing matrix pointer (i.e., make a shallow copy).

This method is the proper way to say, ''Here is a kjb_c::Matrix struct that I am responsible for deleting, and I must make sure that it gets destroyed when it goes out of scope.'' This is a good way to wrap a matrix "dynamically," after it has already been created.

Anyplace you find yourself using free_matrix() in your C++ code, you should consider using instead this class and this ctor.

If the input pointer equals NULL then a zero size matrix is constructed.

This constructor is guaranteed not to throw whenever the input is not equal to NULL. This is an important promise for exception safety.

Warning

Do not create two Matrix objects from the same source this way or you will get a double deletion bug.

kjb::Matrix::Matrix ( const Impl_type &  mat_ref )

inlineexplicit

Ctor copies contents (i.e., a deep copy) of an existing C-struct matrix.

Warning

This method should be seldom used: kjb_c::Matrix objects should rarely be left in an unwrapped state.

This kind of conversion is relatively expensive, thus we restrict its use to explicit invocation.

kjb::Matrix::Matrix

(

const std::string &

file_name

)

Read matrix from file.

See Also

kjb_c::read_matrix

kjb::Matrix::Matrix ( const Matrix &  mat_ref )

inline

Copy ctor.

kjb::Matrix::~Matrix ( )

inline

Member Function Documentation

double kjb::Matrix::abs_of_determinant

(

)

const

Gets the absolute value of the determinant of this matrix.

See Also

kjb_c::get_determinant_abs()

Matrix& kjb::Matrix::add ( const Matrix &  op2 )

inline

Add, in place, a matrix to this matrix.

Matrix::Value_type & kjb::Matrix::at

(

int

i

)

Access matrix like a one-dimensional array, using row-major ordering, and returning an lvalue.

const Matrix::Value_type & kjb::Matrix::at

(

int

i

)

const

Access matrix like a one-dimensional array, using row-major ordering, and returning an rvalue.

Matrix::Value_type & kjb::Matrix::at	(	int	row,
		int	col
	)

Access matrix with bounds checking and return an lvalue.

const Matrix::Value_type & kjb::Matrix::at	(	int	row,
		int	col
	)		const

Access matrix with bounds checking and return an rvalue.

Int_matrix kjb::Matrix::ceil

(

)

const

Return the ceil(3) of each element of the matrix.

Warning

You might want to check the max() and min(), to avoid overflow.

void kjb::Matrix::check_bounds ( int  row, int  col  ) const

inline

Test whether the given row and column indices are valid.

Exceptions

Index_out_of_bounds

exception, plus an explanatory message.

Although this is a public method, users seldom will call it directly. Its main purpose is to support the at() methods.

void kjb::Matrix::convert_to_2d_homo_rotation_matrix

(

double

phi

)

Creates a 3d homogeneous rotation matrix and stores it into m_matrix. m_matrix is not reallocated if its dimensions are 3X3 The rotation angle is in radian

Parameters

phi	rotation angle (positive means counter clockwise) around the origin

void kjb::Matrix::convert_to_2d_rotation_matrix

(

double

phi

)

Creates a 3d rotation matrix and stores it into m_matrix. m_matrix is not reallocated if its dimensions are 3X3 The rotation angle is in radian

Parameters

phi	rotation angle (positive means counter clockwise) around the origin

void kjb::Matrix::convert_to_3d_homo_rotation_matrix	(	double	phi,
		double	x,
		double	y,
		double	z
	)

Creates a 3d homogeneous rotation matrix and stores it into m_matrix. m_matrix is not reallocated if its dimensions are 3X3 The rotation angle is in radian

Parameters

phi	rotation angle
x	x-coordinate of the vector to rotate around
y	y-coordinate of the vector to rotate around
z	z-coordinate of the vector to rotate around

void kjb::Matrix::convert_to_3d_homo_rotation_matrix	(	double	phi,
		const Vector &	vec
	)

Creates a 3d homogeneous rotation matrix and stores it into m_matrix. m_matrix is not reallocated if its dimensions are 3X3 The rotation angle is in radian

Parameters

phi	rotation angle (positive means counterclockwise)
vec	the vector to rotate around

void kjb::Matrix::convert_to_3d_homo_rotation_matrix_from_vector	(	double	phi,
		const Vector &	vec
	)

Creates a 3d homogeneous rotation matrix and stores it into m_matrix. m_matrix is not reallocated if its dimensions are 3X3 The rotation angle is in radian

Parameters

phi	rotation angle (positive means counterclockwise)
vec	the vector to rotate around

Deprecated:

Use convert_to_3d_homo_rotation_matrix( phi, vec) in new code.

void kjb::Matrix::convert_to_3d_homo_scaling_matrix	(	double	x,
		double	y,
		double	z
	)

Creates a 3d homogeneous scaling matrix and stores it into m_matrix. m_matrix is not reallocated if its dimensions are 3X3

Parameters

x	the amount of scaling along the x axis
y	the amount of scaling along the y axis
z	the amount of scaling along the z axis

void kjb::Matrix::convert_to_3d_homo_scaling_matrix

(

const Vector &

vec

)

Creates a 3d homogeneous scaling matrix and stores it into m_matrix. m_matrix is not reallocated if its dimensions are 3X3

Parameters

vec	the vector containing the amount of scaling along the x, y, and z axes respectively

void kjb::Matrix::convert_to_3d_homo_scaling_matrix_from_vector

(

const Vector &

vec

)

Creates a 3d homogeneous scaling matrix and stores it into m_matrix. m_matrix is not reallocated if its dimensions are 3X3

Parameters

vec	the vector containing the amount of scaling along the x, y, and z axes respectively

Deprecated:

Use convert_to_3d_homo_scaling_matrix( vec ) in new code.

void kjb::Matrix::convert_to_3d_homo_translation_matrix	(	double	x,
		double	y,
		double	z
	)

Creates a 3d homogeneous translation matrix and stores it into m_matrix. m_matrix is not reallocated if its dimensions are 3X3

Parameters

x	the amount of translation along the x axis
y	the amount of translation along the y axis
z	the amount of translation along the z axis

void kjb::Matrix::convert_to_3d_homo_translation_matrix

(

const Vector &

vec

)

Creates a 3d homogeneous translation matrix and stores it into m_matrix. m_matrix is not reallocated if its dimensions are 3X3

Parameters

vec	the vector containing the amount of translation along the x, y, and z axes respectively

void kjb::Matrix::convert_to_3d_homo_translation_matrix_from_vector

(

const Vector &

vec

)

Creates a 3d homogeneous translation matrix and stores it into m_matrix. m_matrix is not reallocated if its dimensions are 3X3

Parameters

vec	the vector containing the amount of translation along the x, y, and z axes respectively

Deprecated:

Use convert_to_3d_homo_translation_matrix( vec ) in new code.

void kjb::Matrix::convert_to_3d_rotation_matrix	(	double	phi,
		double	x,
		double	y,
		double	z
	)

Creates a 3d rotation matrix and stores it into m_matrix. m_matrix is not reallocated if its dimensions are 3X3 The rotation angle is in radian

Parameters

phi	rotation angle (positive means counterclockwise)
x	x-coordinate of the vector to rotate around
y	y-coordinate of the vector to rotate around
z	z-coordinate of the vector to rotate around

void kjb::Matrix::convert_to_3d_rotation_matrix	(	double	phi,
		const Vector &	vec
	)

Creates a 3d rotation matrix and stores it into m_matrix. m_matrix is not reallocated if its dimensions are 3X3 The rotation angle is in radian

Parameters

phi	rotation angle (positive means counterclockwise)
vec	the vector to rotate around

void kjb::Matrix::convert_to_3d_rotation_matrix_from_vector	(	double	phi,
		const Vector &	vec
	)

Creates a 3d rotation matrix and stores it into m_matrix. m_matrix is not reallocated if its dimensions are 3X3 The rotation angle is in radian

Parameters

phi	rotation angle (positive means counterclockwise)
vec	the vector to rotate around

Deprecated:

Use convert_to_3d_rotation_matrix( phi, vec ) in new code.

void kjb::Matrix::convert_to_3d_scaling_matrix	(	double	x,
		double	y,
		double	z
	)

Creates a 3d scaling matrix and stores it into m_matrix. m_matrix is not reallocated if its dimensions are 3X3

Parameters

x	the amount of scaling along the x axis
y	the amount of scaling along the y axis
z	the amount of scaling along the z axis

void kjb::Matrix::convert_to_3d_scaling_matrix

(

const Vector &

vec

)

Creates a 3d scaling matrix and stores it into m_matrix. m_matrix is not reallocated if its dimensions are 3X3

Parameters

vec	the vector containing the amount of scaling along the x, y, and z axes respectively

void kjb::Matrix::convert_to_3d_scaling_matrix_from_vector

(

const Vector &

vec

)

Creates a 3d scaling matrix and stores it into m_matrix. m_matrix is not reallocated if its dimensions are 3X3

Parameters

vec	the vector containing the amount of scaling along the x, y, and z axes respectively

Deprecated:

Use convert_to_3d_scaling_matrix( vec ) in new code.

void kjb::Matrix::convert_to_euler_homo_rotation_matrix	(	float	phi,
		float	theta,
		float	psi
	)

Creates an euler homogeneous rotation matrix and stores it into m_matrix. m_matrix is not reallocated if its dimensions are 3X3 All rotation angles are in radian

Parameters

phi	rotation angle around the z axis
theta	rotation angle around the x axis
psi	rotation angle around the y axis

void kjb::Matrix::convert_to_euler_rotation_matrix	(	float	phi,
		float	theta,
		float	psi
	)

Creates an euler rotation matrix without reallocating memory, when possible.

Creates an euler rotation matrix and stores it into m_matrix. m_matrix is not reallocated if its dimensions are 3X3 All rotation angles are in radian

Parameters

phi	rotation angle around the z axis
theta	rotation angle around the x axis
psi	rotation angle around the y axis

Matrix kjb::Matrix::create_2d_homo_rotation_matrix ( double  phi )

static

Creates a 3d homogeneous rotation matrix and stores it into an instance of class Matrix. The rotation angle is in radian.

Parameters

phi	rotation angle (positive means counterclockwise) around the origin

Returns

a 2d homogeneous rotation matrix

Matrix kjb::Matrix::create_2d_rotation_matrix ( double  phi )

static

Creates a 2d rotation matrix and stores it into an instance of class Matrix The rotation angle is in radian

Parameters

phi	rotation angle (positive means counter clockwise) around the origin

Returns

a 2d rotation matrix

Matrix kjb::Matrix::create_3d_homo_rotation_matrix ( double  phi, double  x, double  y, double  z  )

static

Creates a 3d homogeneous rotation matrix and stores it into an instance of class Matrix The rotation angle is in radian.

Parameters

phi	rotation angle (positive means counterclockwise)
x	x-coordinate of the vector to rotate around
y	y-coordinate of the vector to rotate around
z	z-coordinate of the vector to rotate around

Returns

a 3d homogeneous rotation matrix

Matrix kjb::Matrix::create_3d_homo_rotation_matrix ( double  phi, const Vector &  vec  )

static

Creates a 3d homogeneous rotation matrix and stores it into an instance of class Matrix The rotation angle is in radian

Parameters

phi	rotation angle (positive means counterclockwise)
vec	the vector to rotate around

Returns

a 3d homogeneous rotation matrix

Matrix kjb::Matrix::create_3d_homo_rotation_matrix_from_vector ( double  phi, const Vector &  vec  )

static

Creates a 3d homogeneous rotation matrix and stores it into an instance of class Matrix The rotation angle is in radian

Parameters

phi	rotation angle (positive means counterclockwise)
vec	the vector to rotate around

Returns

a 3d homogeneous rotation matrix

Deprecated:

Use create_3d_homo_rotation_matrix( phi, vec ) in new code.

Matrix kjb::Matrix::create_3d_homo_scaling_matrix ( double  x, double  y, double  z  )

static

Creates a 3d homogeneous scaling matrix and stores it into an instance of class Matrix

Parameters

x	the amount of scaling along the x axis
y	the amount of scaling along the y axis
z	the amount of scaling along the z axis

Returns

a 3d homogeneous scaling matrix

Matrix kjb::Matrix::create_3d_homo_scaling_matrix ( const Vector &  vec )

static

Creates a 3d homogeneous scaling matrix and stores it into an instance of class Matrix

Parameters

vec	the vector containing the amount of scaling along the x, y, and z axes respectively

Returns

a 3d rotation matrix

Matrix kjb::Matrix::create_3d_homo_scaling_matrix_from_vector ( const Vector &  vec )

static

Creates a 3d homogeneous scaling matrix and stores it into an instance of class Matrix

Parameters

vec	the vector containing the amount of scaling along the x, y, and z axes respectively

Returns

a 3d rotation matrix

Deprecated:

Use create_3d_homo_scaling_matrix( vec ) in new code.

Matrix kjb::Matrix::create_3d_homo_translation_matrix ( double  x, double  y, double  z  )

static

Creates a 3d homogeneous translation matrix and stores it into an instance of class Matrix

Parameters

x	the amount of translation along the x axis
y	the amount of translation along the y axis
z	the amount of translation along the z axis

Returns

a 3d homogeneous scaling matrix

Matrix kjb::Matrix::create_3d_homo_translation_matrix ( const Vector &  vec )

static

Creates a 3d homogeneous translation matrix and stores it into an instance of class Matrix

Parameters

vec	the vector containing the amount of translation along the x, y, and z axes respectively

Returns

a 3d translation matrix

Matrix kjb::Matrix::create_3d_homo_translation_matrix_from_vector ( const Vector &  vec )

static

Creates a 3d homogeneous translation matrix and stores it into an instance of class Matrix

Parameters

vec	the vector containing the amount of translation along the x, y, and z axes respectively

Returns

a 3d translation matrix

Deprecated:

Use create_3d_homo_translation_matrix( vec ) in new code.

Matrix kjb::Matrix::create_3d_rotation_matrix ( double  phi, double  x, double  y, double  z  )

static

Creates a 3d rotation matrix and stores it into an instance of class Matrix The rotation angle is in radian

Parameters

phi	rotation angle (positive means counterclockwise)
x	x-coordinate of the vector to rotate around
y	y-coordinate of the vector to rotate around
z	z-coordinate of the vector to rotate around

Returns

a 3d rotation matrix

Matrix kjb::Matrix::create_3d_rotation_matrix ( double  phi, const Vector &  vec  )

static

Creates a 3d rotation matrix and stores it into an instance of class Matrix The rotation angle is in radian

Parameters

phi	rotation angle
vec	the vector to rotate around

Returns

a 3d rotation matrix

Matrix kjb::Matrix::create_3d_rotation_matrix_from_vector ( double  phi, const Vector &  vec  )

static

Creates a 3d rotation matrix and stores it into an instance of class Matrix The rotation angle is in radian

Parameters

phi	rotation angle
vec	the vector to rotate around

Returns

a 3d rotation matrix

Deprecated:

Use create_3d_rotation_matrix( phi, vec ) in new code.

Matrix kjb::Matrix::create_3d_scaling_matrix ( double  x, double  y, double  z  )

static

Creates a 3d scaling matrix and stores it into an instance of class Matrix

Parameters

x	x-coordinate of the vector to rotate around
y	y-coordinate of the vector to rotate around
z	z-coordinate of the vector to rotate around

Returns

a 3d scaling matrix

Matrix kjb::Matrix::create_3d_scaling_matrix ( const Vector &  vec )

static

Creates a 3d scaling matrix and stores it into an instance of class Matrix The rotation angle is in radian

Parameters

vec	the vector to rotate around

Returns

a 3d scaling matrix

Matrix kjb::Matrix::create_3d_scaling_matrix_from_vector ( const Vector &  vec )

static

Creates a 3d scaling matrix and stores it into an instance of class Matrix The rotation angle is in radian

Parameters

vec	the vector to rotate around

Returns

a 3d scaling matrix

Deprecated:

Use create_3d_scaling_matrix( vec ) in new code.

Matrix kjb::Matrix::create_euler_homo_rotation_matrix ( float  phi, float  theta, float  psi  )

static

Creates a homogeneous euler rotation matrix, and stores it into an instance of class Matrix. All rotation angles are in radian

Parameters

phi	rotation angle around the z axis
theta	rotation angle around the x axis
psi	rotation angle around the y axis

Returns

a homogeneous euler rotation matrix

Matrix kjb::Matrix::create_euler_rotation_matrix ( float  phi, float  theta, float  psi  )

static

Creates an euler rotation matrix and stores it into an instance of claa Matrix.

Creates an euler rotation matrix and stores it into an instance of class Matrix All rotation angles are in radian

Parameters

phi	rotation angle around the z axis
theta	rotation angle around the x axis
psi	rotation angle around the y axis

Returns

an euler rotation matrix

int kjb::Matrix::display

(

const char *

title = NULL

)

const

Matrix& kjb::Matrix::divide ( Value_type  op2 )

inline

Divide each entry in the matrix by a scalar value.

Returns

an lvalue to this matrix

Exceptions

Divide_by_zero

if the scalar value is zero.

Matrix & kjb::Matrix::ew_multiply_by

(

const Matrix &

m

)

elementwise multiply by another matrix

Author

Colin Dawson

Matrix & kjb::Matrix::ew_multiply_rows_by

(

const Vector &

v

)

elementwise multiply each row by a vector, in place

Author

Colin Dawson

void kjb::Matrix::fill_col	(	int	col,
		Value_type	x
	)

void kjb::Matrix::fill_row	(	int	row,
		Value_type	x
	)

Matrix::Vec_type kjb::Matrix::filter

(

bool(*)(Value_type)

f

)

Int_matrix kjb::Matrix::floor

(

)

const

Return the floor(3) of each element of the matrix.

Warning

You might want to check the max() and min(), to avoid overflow.

const Impl_type* kjb::Matrix::get_c_matrix ( ) const

inline

Get const pointer to the underlying kjb_c::Matrix C struct.

Matrix::Vec_type kjb::Matrix::get_col

(

int

col

)

const

Return a specified column of this matrix, in the form of a Vector.

Matrix::Vec_type kjb::Matrix::get_diagonal

(

)

const

Retrieves the diagonal of this matrix; returned as a vector.

See Also

kjb_c::get_determinant_abs()

int kjb::Matrix::get_length ( ) const

inline

Return the number of elements in the matrix.

Warning

There is a remote chance this could overflow an int.

int kjb::Matrix::get_num_cols ( ) const

inline

Return the number of columns in the matrix.

int kjb::Matrix::get_num_rows ( ) const

inline

Return the number of rows in the matrix.

Matrix::Vec_type kjb::Matrix::get_row

(

int

row

)

const

Return a specified row of this matrix, in the form of a Vector.

Impl_type*& kjb::Matrix::get_underlying_representation_with_guilt ( )

inline

Get pointer to the underlying kjb_c::Matrix C struct.

Warning

: This should only be used if you know what you're doing. generally, it should only be used to write wrapper functions for c functions.

Matrix & kjb::Matrix::horzcat

(

const Matrix &

A

)

Concat this matrix with another horizontally. (named after the equivalent Matlab function) Because of how memory is arranged, this is generally slower than vertcat.

Matrix kjb::Matrix::inverse

(

)

const

Invert this matrix.

See Also

kjb_c::get_matrix_inverse()

kjb_c::set_matrix_inversion_options()

Warning

may disappear – use matrix_inverse() instead

Matrix & kjb::Matrix::limit_values	(	Value_type	low,
		Value_type	high
	)

Make sure all values in this matrix are between the two given values.

Returns

an lvalue of this object

Matrix kjb::Matrix::map ( Value_type(*)(Value_type)  f ) const

inline

Deprecated:

use mapcar

Matrix & kjb::Matrix::mapcar

(

Mapper

fun

)

Transform the elements of a matrix.

Apply a transformation fun to each element of the matrix, in place, and return an lvalue of the modified matrix.

Matrix& kjb::Matrix::multiply ( const Matrix &  op2 )

inline

Compute product of this matrix (on the left) and another, and replace this matrix with the result, like *=.

Exceptions

Dimension_mismatch

if the number of columns of this matrix does not equal the number of rows of right factor op2.

Warning

This is not really an in-place operation – do not expect a speed-up using this operation instead of plain old star.

Matrix& kjb::Matrix::multiply ( Value_type  op2 )

inline

Multiply this matrix by a scalar, in place.

Matrix& kjb::Matrix::negate ( )

inline

Transform this matrix into the additive inverse of its former value, in place.

Value_type& kjb::Matrix::operator() ( int  i )

inline

MATLAB-style one-dimensional subscript of matrix, e.g., A(10), using row-major ordering, and returning an lvalue.

Warning

No bounds checking!

See Also

at() method, which provides bounds checking.

const Value_type& kjb::Matrix::operator() ( int  i ) const

inline

MATLAB-style one-dimensional subscript of matrix, e.g., A(10), using row-major ordering, and returning an rvalue.

Warning

No bounds checking!

See Also

at() method, which provides bounds checking.

Value_type& kjb::Matrix::operator() ( int  row, int  col  )

inline

Access matrix like a Fortran or MATLAB two-dimensional array, e.g., A(2,4), and return an lvalue.

Warning

No bounds checking!

See Also

at() method, which provides bounds checking.

The comparison to Fortran does not imply column-major ordering.

const Value_type& kjb::Matrix::operator() ( int  row, int  col  ) const

inline

Access matrix like a Fortran or MATLAB two-dimensional array, e.g., A(2,4), and return an rvalue.

Warning

No bounds checking!

See Also

at() method, which provides bounds checking.

The comparison to Fortran does not imply column-major ordering.

Matrix_view kjb::Matrix::operator()	(	const Index_range &	rows,
		const Index_range &	cols
	)

Access a submatrix using Matlab-like syntax. Returned object has Matrix semantics, but operates on the elements of this matrix indexed by the rows and cols parameters.

Note

Accepted input types are int, Index_range.all, string, Int_vector, or vector<int>

Warning

Matrix_view is fairly lightweight, but constructing Matrix_view and Index_range adds overhead compared to integer-based indexing. In addition, bounds checking occurs at EVERY index, so this shouldn't be used where performance is a concern.

Const_matrix_view kjb::Matrix::operator()	(	const Index_range &	rows,
		const Index_range &	cols
	)		const

Matrix& kjb::Matrix::operator*= ( const Matrix &  op2 )

inline

Compute product of this matrix (on the left) and another, and replace this matrix with the result.

Exceptions

Dimension_mismatch

if the number of columns of this matrix does not equal the number of rows of right factor op2.

Warning

This is not really an in-place operation – do not expect a speed-up using this operation instead of plain old star.

Matrix& kjb::Matrix::operator*= ( Value_type  op2 )

inline

Multiply this matrix by a scalar, in place.

Matrix& kjb::Matrix::operator+= ( const Matrix &  op2 )

inline

Add, in place, a matrix to this matrix.

Matrix & kjb::Matrix::operator+=

(

double

x

)

Subtract a scalar from all elements of this matrix, in place.

Matrix& kjb::Matrix::operator-= ( const Matrix &  op2 )

inline

Subtract another matrix from this matrix, in place.

Matrix & kjb::Matrix::operator-=

(

double

x

)

Subtract a scalar from all elements of this matrix, in place.

Matrix& kjb::Matrix::operator/= ( Value_type  op2 )

inline

Divide each entry in the matrix by a scalar value.

Returns

an lvalue to this matrix

Exceptions

Divide_by_zero

if the scalar value is zero.

Matrix & kjb::Matrix::operator=

(

const Impl_type &

mat_ref

)

Clone of square version of zero_out(int)

Deprecated:

The name is misleading; instead of this, use zero_out(int) in new code.

Assign contents from a kjb_c::Matrix, a C struct; make a deep copy.

Note

Consider using a shallow copy and swap() instead of assignment, to prevent unnecessary deep copying.

Implementation note: this routine formerly had a clause in it to prevent calling copy_matrix() when mat_ref pointed to a zero-element matrix. This clause has been removed because it was later decided that copy_matrix() should work even in that case.

Matrix& kjb::Matrix::operator= ( const Matrix &  src )

inline

Assign contents from a kjb::Matrix, a C++ object.

Note

Consider using swap() instead of assignment, to prevent unnecessary deep copying.

Value_type& kjb::Matrix::operator[] ( int  i )

inline

Subscript matrix like a one-dimensional C array, e.g., A[10], using row-major ordering, and returning an lvalue.

Warning

No bounds checking!

See Also

at() method, which provides bounds checking.

const Value_type& kjb::Matrix::operator[] ( int  i ) const

inline

Subscript matrix like a one-dimensional C array, e.g., A[10], using row-major ordering, and returning an rvalue.

Warning

No bounds checking!

See Also

at() method, which provides bounds checking.

Matrix_vector_view kjb::Matrix::operator[]

(

const Index_range &

i

)

Const_matrix_vector_view kjb::Matrix::operator[]

(

const Index_range &

i

)

const

void kjb::Matrix::ow_add_col_vector

(

const Vec_type

v

)

add a column vector to each column of a matrix, in place

void kjb::Matrix::ow_add_row_vector

(

const Vec_type

v

)

add a row vector to each row of a matrix, in place

void kjb::Matrix::ow_add_scalar

(

Value_type

c

)

add a scalar value to each element of a matrix, in place

Note

should we add an operator+= for this? -kyle

void kjb::Matrix::ow_horizontal_flip

(

)

flip the matrix horizontally (swap left, right columns, etc.)

void kjb::Matrix::ow_multiply_col_vector_ew

(

const Vec_type

v

)

multiply a column vector by each column of a matrix, elementwise, in place

void kjb::Matrix::ow_multiply_row_vector_ew

(

const Vec_type

v

)

multiply a row vector by each row of a matrix, elementwise, in place

void kjb::Matrix::ow_vertical_flip

(

)

flip the matrix vertically (swap last, first row, etc.)

int kjb::Matrix::read ( const char *  filename = 0 )

inline

Reads the matrix contents from a file specified by name.

See Also

kjb_c::read_matrix()

This routine reads the matrix contents from the specified file and overwrites the current contents.

If filename is NULL or the first character is null, then the input is read from standard input.

Matrix& kjb::Matrix::realloc ( int  new_rows, int  new_cols  )

inline

resize this matrix, losing previous data. Faster than resize(), because data copy is skipped.

Matrix::Value_type kjb::Matrix::reduce	(	Value_type(*)(Value_type x, Value_type y)	f,
		Matrix::Value_type	init = 0.0
	)		const

call function f using every element of the matrix as an input

Parameters

init	Initial value

Matrix & kjb::Matrix::replace	(	int	row,
		int	col,
		const Matrix &	A
	)

Replace a submatrix of this matrix with the given matrix.

Matrix& kjb::Matrix::reserve ( int  new_rows, int  new_cols  )

inline

allocate sufficient storage to hold the given dimensions, but leave actual matrix size unchanged. Useful when calling Matrix::vertcat inside a tight loop, to avoid multiple reallocations

Matrix & kjb::Matrix::resize	(	int	new_rows,
		int	new_cols,
		Value_type	pad = Value_type(0)
	)

Resize this matrix, retaining previous values. Space is reused if possible. Otherwise requires a new allocation and old space is freed.

Matrix& kjb::Matrix::scale_matrix_rows_by_sums ( )

inline

something luca will document eventually

Matrix & kjb::Matrix::shift_columns_by

(

const Vector &

v

)

Shift each column by a vector, in place.

Author

Colin Dawson

Matrix & kjb::Matrix::shift_rows_by

(

const Vector &

v

)

Shift each row by a vector, in place.

Author

Colin Dawson

int kjb::Matrix::size ( ) const

inline

Return the number of elements in the matrix. (alias of get_length)

Note

Included for compatibility with "vector-style" interface

Warning

There is a remote chance this could overflow an int.

Matrix kjb::Matrix::submatrix ( int  row, int  col, int  num_rows, int  num_cols  ) const

inline

Get the submatrix given by the parameters; i.e., get A(row, col, row + num_rows, col + num_cols), where A is this matrix.

Matrix& kjb::Matrix::subtract ( const Matrix &  op2 )

inline

Subtract another matrix from this matrix, in place.

void kjb::Matrix::swap ( Matrix &  other )

inline

Swap the representations of two matrices.

Int_matrix kjb::Matrix::threshold

(

double

t

)

const

Convert to a binary matrix; zero if value is below threshold, one if value is greater than or equal to threshold.

double kjb::Matrix::trace

(

)

const

Gets trace of this matrix.

Matrix kjb::Matrix::transpose

(

)

const

Transpose this matrix.

Returns

an lvalue to this matrix.

Warning

may disappear – use matrix_transpose() instead

Matrix & kjb::Matrix::vertcat

(

const Matrix &

A

)

Concat this matrix with another vertically. (named after the equivalent Matlab function)

int kjb::Matrix::write ( const char *  filename = 0 ) const

inline

Writes the matrix contents to a file specified by name.

See Also

kjb_c::write_matrix_full_precision()

If filename is NULL or the first character is null, then the output is written to standard output.

int kjb::Matrix::write_raw ( const char *  filename = 0 ) const

inline

Writes the matrix contents to a file specified by name.

See Also

kjb_c::write_raw_matrix()

If filename is NULL or the first character is null, then the output is written to standard output.

Matrix & kjb::Matrix::zero_out	(	int	num_rows,
		int	num_cols
	)

Resize matrix, replace contents with the identity matrix.

See Also

create_identity_matrix()

The name of this method is misleading but I can't think of a better one. It's not really an initialization routine, more like a re-init. Resize matrix, and clobber contents with zeroes.

Returns

an lvalue of this object

See Also

create_zero_matrix(int,int) – more appropriate in some situations.

Matrix & kjb::Matrix::zero_out

(

int

rows

)

Resize matrix to be square, and clobber contents with zeroes.

Returns

an lvalue of this object

See Also

create_zero_matrix(int) – more appropriate in some situations.

Matrix & kjb::Matrix::zero_out

(

)

Clobber contents of matrix with zeroes.

Returns

an lvalue of this object

See Also

create_zero_matrix() – more appropriate in some situations.

Friends And Related Function Documentation

bool operator< ( const Matrix &  op1, const Matrix &  op2  )

friend

Returns true if a is lexicographically less-than b.

---

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

• /work/kobus/src/lib/m_cpp/m_matrix.h
• /work/kobus/src/lib/m_cpp/m_matrix.cpp