A class to define and apply a 3D transform. More...

#include <vimt3d_transform_3d.h>

Public Types
enum	Form { Identity, Translation, ZoomOnly, RigidBody, Similarity, Affine }
	Defines form of transformation. More...
Public Member Functions
	vimt3d_transform_3d ()
	Construct as identity transform.
	~vimt3d_transform_3d ()
	Destructor.
bool	is_identity () const
	True if identity.
Form	form () const
	Form of transformation.
vnl_matrix< double >	matrix () const
	Gets 4x4 Matrix representing transformation.
void	matrix (vnl_matrix< double > &M) const
	Gets 4x4 Matrix representing transformation.
void	params (vnl_vector< double > &v) const
	Fills v with parameters.
void	set_matrix (const vnl_matrix< double > &M)
	Define the transform in terms of a 4x4 homogeneous matrix.
void	set (const vnl_vector< double > &v, Form)
	Sets transform using v.
void	set_identity ()
	Sets transform to identity.
void	set_translation (double t_x, double t_y, double t_z)
	Sets the transformation to be a translation.
void	set_zoom_only (double s_x, double s_y, double s_z, double t_x, double t_y, double t_z)
	Sets the transformation to be anisotropic scaling, followed by translation.
void	set_zoom_only (double s, double t_x, double t_y, double t_z)
	Sets the transformation to be isotropic scaling, followed by translation.
void	set_rigid_body (double r_x, double r_y, double r_z, double t_x, double t_y, double t_z)
	Sets the transformation to be rotation, followed by translation.
void	set_rigid_body (const vnl_quaternion< double > &unit_q, double t_x, double t_y, double t_z)
	Sets the transformation to be rotation, followed by translation.
void	set_similarity (double s, double r_x, double r_y, double r_z, double t_x, double t_y, double t_z)
	Sets the transformation to be isotropic scaling, followed by rotation, then translation.
void	set_similarity (double scale, const vnl_quaternion< double > &unit_q, double t_x, double t_y, double t_z)
	Sets the transformation to be similarity: scale, rotation, followed by translation.
void	set_affine (double s_x, double s_y, double s_z, double r_x, double r_y, double r_z, double t_x, double t_y, double t_z)
	Sets the transformation to be a special case of Affine: anisotropic scaling, followed by rotation, then translation.
void	set_affine (double s_x, double s_y, double s_z, vgl_vector_3d< double > c_x, vgl_vector_3d< double > c_y, vgl_vector_3d< double > c_z, double t_x, double t_y, double t_z)
	Sets the transformation to be a special case of Affine: anisotropic scaling, followed by rotation, then translation.
void	set_affine (const vgl_point_3d< double > &p, const vgl_vector_3d< double > &u, const vgl_vector_3d< double > &v, const vgl_vector_3d< double > &w)
	Sets the transformation to be a special case of Affine.
vgl_point_3d< double >	origin () const
	Returns the coordinates of the origin.
void	set_origin (const vgl_point_3d< double > &)
	Modifies the transformation so that origin == p.
vgl_point_3d< double >	operator() (double x, double y, double z) const
	Applies transformation to (x,y,z).
vgl_point_3d< double >	operator() (vgl_point_3d< double > p) const
	Applies transformation to point p.
vimt3d_transform_3d	inverse () const
	Returns the inverse of the current transform.
vgl_vector_3d< double >	delta (vgl_point_3d< double >, vgl_vector_3d< double > dp) const
	Returns change in transformed point when original point moved by dp.
void	print_summary (vcl_ostream &os) const
	Print class to os.
void	print_all (vcl_ostream &os) const
	Print class to os.
void	config (vcl_istream &is)
	Set transformation from stream;.
void	b_write (vsl_b_ostream &bfs) const
	Save class to binary file stream.
void	b_read (vsl_b_istream &bfs)
	Load class from binary file stream.
bool	operator== (const vimt3d_transform_3d &) const
	True if t is the same as this.
void	simplify (double tol=1e-10)
	Reduce to the simplest form possible.
Protected Member Functions
void	calcInverse () const
void	setCheck (int n1, int n2, const char *str) const
void	angles (double &phi_x, double &phi_y, double &phi_z) const
void	setRotMat (double r_x, double r_y, double r_z)
Protected Attributes
double	xx_
double	xy_
double	xz_
double	xt_
double	yx_
double	yy_
double	yz_
double	yt_
double	zx_
double	zy_
double	zz_
double	zt_
double	tx_
double	ty_
double	tz_
double	tt_
Form	form_
double	xx2_
double	xy2_
double	xz2_
double	xt2_
double	yx2_
double	yy2_
double	yz2_
double	yt2_
double	zx2_
double	zy2_
double	zz2_
double	zt2_
double	tx2_
double	ty2_
double	tz2_
double	tt2_
bool	inv_uptodate_
Friends
vimt3d_transform_3d	operator* (const vimt3d_transform_3d &L, const vimt3d_transform_3d &R)
	Calculates the product LR.

Detailed Description

A class to define and apply a 3D transform.

The transform which can be up to an affine transformation. In order of complexity the transform can be

Identity x->x, y->y, z->z
Translation x->x + tx, y->y + ty, z->z + tz
RigidBody (Rotation, followed by translation)
Similarity (Isotropic scaling, followed by rotation, then translation)
ZoomOnly (Anisotropic scaling, followed by translation)
Affine

One useful special case of Affine involves anisotropic scaling, followed by rotation, then translation.

The transform types Translation, ZoomOnly, RigidBody and Similarity have a defined order in which scaling, rotation and translation components are applied, and the components are thus separable. Other transformations (e.g. translation followed by rotation) can be obtained by composing multiple transforms. The resulting transform will in general be termed affine.

The transformation can be represented by a 4x4 matrix of homogeneous co-ordinates.

   ( xx xy xz xt )
   ( yx yy yz yt )
   ( zx zy zz zt )
   ( tx ty tz tt )

For efficiency the elements are stored explicitly, rather than in a vnl_matrix<double>, to avoid lots of copying of matrices with all the attendant memory allocation.

Definition at line 48 of file vimt3d_transform_3d.h.

Member Enumeration Documentation

enum vimt3d_transform_3d::Form

Defines form of transformation.

Enumerator:

Identity
Translation
ZoomOnly	Anisotropic scaling, followed by translation.
RigidBody	Rotation, followed by translation.
Similarity	Isotropic scaling, followed by rotation, then translation.
Affine

Definition at line 53 of file vimt3d_transform_3d.h.

Constructor & Destructor Documentation

vimt3d_transform_3d::vimt3d_transform_3d ( ) [inline]

Construct as identity transform.

Definition at line 61 of file vimt3d_transform_3d.h.

vimt3d_transform_3d::~vimt3d_transform_3d ( ) [inline]

Destructor.

Definition at line 72 of file vimt3d_transform_3d.h.

Member Function Documentation

void vimt3d_transform_3d::angles	(	double &	phi_x,
		double &	phi_y,
		double &	phi_z
	)		const `[protected]`

Definition at line 63 of file vimt3d_transform_3d.cxx.

void vimt3d_transform_3d::b_read ( vsl_b_istream & bfs )

Load class from binary file stream.

Definition at line 1098 of file vimt3d_transform_3d.cxx.

void vimt3d_transform_3d::b_write ( vsl_b_ostream & bfs ) const

Save class to binary file stream.

Definition at line 1085 of file vimt3d_transform_3d.cxx.

void vimt3d_transform_3d::calcInverse ( ) const [protected]

Definition at line 698 of file vimt3d_transform_3d.cxx.

void vimt3d_transform_3d::config ( vcl_istream & is )

Set transformation from stream;.

You can specify the vector as used in the set() operation.

   form: rigidbody
   vector: { 0.1 0.1 0.1 2 2 2 }

or with explicit parameter names from the set_...() methods.

   form: rigidbody
   r_x: 0.1
   r_y: 0.1
   r_z: 0.1
   t_x: 2
   t_y: 2
   t_z: 2

Definition at line 990 of file vimt3d_transform_3d.cxx.

vgl_vector_3d<double> vimt3d_transform_3d::delta	(	vgl_point_3d< double >	,
		vgl_vector_3d< double >	dp
	)		const `[inline]`

Returns change in transformed point when original point moved by dp.

Parameters:

p	point
dp	movement from point

Returns:: T(p+dp)-T(p)

Definition at line 270 of file vimt3d_transform_3d.h.

Form vimt3d_transform_3d::form ( ) const [inline]

Form of transformation.

Definition at line 78 of file vimt3d_transform_3d.h.

vimt3d_transform_3d vimt3d_transform_3d::inverse ( ) const

Returns the inverse of the current transform.

Returns:: inverse of current transform.

Definition at line 674 of file vimt3d_transform_3d.cxx.

bool vimt3d_transform_3d::is_identity ( ) const [inline]

True if identity.

Definition at line 75 of file vimt3d_transform_3d.h.

vnl_matrix< double > vimt3d_transform_3d::matrix ( ) const

Gets 4x4 Matrix representing transformation.

Definition at line 25 of file vimt3d_transform_3d.cxx.

void vimt3d_transform_3d::matrix ( vnl_matrix< double > & M ) const

Gets 4x4 Matrix representing transformation.

Return values:

M	a 4x4 Matrix representing transformation

Definition at line 34 of file vimt3d_transform_3d.cxx.

vgl_point_3d<double> vimt3d_transform_3d::operator()	(	double	x,
		double	y,
		double	z
	)		const `[inline]`

Applies transformation to (x,y,z).

Parameters:

x	x coordinate
y	y co-ord
z	z co-ord ret: Point = T(x,y,z)

Definition at line 234 of file vimt3d_transform_3d.h.

vgl_point_3d<double> vimt3d_transform_3d::operator() ( vgl_point_3d< double > p ) const [inline]

Applies transformation to point p.

Parameters:

p Point

Returns:: Point = T(p)

Definition at line 259 of file vimt3d_transform_3d.h.

bool vimt3d_transform_3d::operator== ( const vimt3d_transform_3d & t ) const

True if t is the same as this.

Note:: All underlying parameters xx_, xy_, etc are required to be equal, but the declared Form (etc RigidBody) need not be equal.

Definition at line 771 of file vimt3d_transform_3d.cxx.

vgl_point_3d<double> vimt3d_transform_3d::origin ( ) const [inline]

Returns the coordinates of the origin.

Definition at line 218 of file vimt3d_transform_3d.h.

void vimt3d_transform_3d::params ( vnl_vector< double > & v ) const

Fills v with parameters.

Definition at line 162 of file vimt3d_transform_3d.cxx.

void vimt3d_transform_3d::print_all ( vcl_ostream & os ) const

Print class to os.

This function prints the actual parameters xx_,xy_,xz_,xt_, yx_,yy_,yz_,yt_, zx_,zy_,zz_,zt_, tx_,ty_,tz_,tt_

Definition at line 946 of file vimt3d_transform_3d.cxx.

void vimt3d_transform_3d::print_summary ( vcl_ostream & os ) const

Print class to os.

This function prints the extracted params.

See also:: params(); set()

Definition at line 882 of file vimt3d_transform_3d.cxx.

void vimt3d_transform_3d::set	(	const vnl_vector< double > &	v,
		Form	form
	)

Sets transform using v.

Definition at line 300 of file vimt3d_transform_3d.cxx.

void vimt3d_transform_3d::set_affine	(	double	s_x,
		double	s_y,
		double	s_z,
		double	r_x,
		double	r_y,
		double	r_z,
		double	t_x,
		double	t_y,
		double	t_z
	)

Sets the transformation to be a special case of Affine: anisotropic scaling, followed by rotation, then translation.

Parameters:

s_x	Scaling factor in x
s_y	Scaling factor in y
s_z	Scaling factor in z
r_x	Angle of rotation in x
r_y	Angle of rotation in y
r_z	Angle of rotation in z
t_x	Translation in x
t_y	Translation in y
t_z	Translation in z

Note:: This creates a special case of Affine. Although this special case is separable, in general Affine transformations are not separable.

Definition at line 574 of file vimt3d_transform_3d.cxx.

void vimt3d_transform_3d::set_affine	(	double	s_x,
		double	s_y,
		double	s_z,
		vgl_vector_3d< double >	c_x,
		vgl_vector_3d< double >	c_y,
		vgl_vector_3d< double >	c_z,
		double	t_x,
		double	t_y,
		double	t_z
	)

Sets the transformation to be a special case of Affine: anisotropic scaling, followed by rotation, then translation.

Parameters:

s_x	Scaling factor in x
s_y	Scaling factor in y
s_z	Scaling factor in z
c_x	First column of rotation matrix
c_y	Second column of rotation matrix
c_z	Third column of rotation matrix
t_x	Translation in x
t_y	Translation in y
t_z	Translation in z

Note:: This creates a special case of Affine. Although this special case is separable, in general Affine transformations are not separable. The rotation matrix is assumed to be valid.

Definition at line 600 of file vimt3d_transform_3d.cxx.

void vimt3d_transform_3d::set_affine	(	const vgl_point_3d< double > &	p,
		const vgl_vector_3d< double > &	u,
		const vgl_vector_3d< double > &	v,
		const vgl_vector_3d< double > &	w
	)

Sets the transformation to be a special case of Affine.

T(x,y,z) = p +x.u +y.v + z.w

Parameters:

p	Origin point
u	Vector to which the x-axis is mapped. The length of u indicates scaling in x.
v	Vector to which the y-axis is mapped. The length of v indicates scaling in y.
w	Vector to which the z-axis is mapped. The length of w indicates scaling in z.

Note:: Currently, the implementation assumes that u,v,w are orthogonal and form a right-handed system. There are asserts for this condition.; This creates a special case of Affine. Although this special case is separable, in general Affine transformations are not separable.

Definition at line 632 of file vimt3d_transform_3d.cxx.

void vimt3d_transform_3d::set_identity ( )

Sets transform to identity.

Definition at line 385 of file vimt3d_transform_3d.cxx.

void vimt3d_transform_3d::set_matrix ( const vnl_matrix< double > & M )

Define the transform in terms of a 4x4 homogeneous matrix.

Parameters:

M	4x4 homogeneous matrix defining the transform.

Note:: Client must ensure that M is a valid representation of an affine (or simpler) transform.; The form will be set to Affine - call simplify() if you need the simplest form.

Definition at line 49 of file vimt3d_transform_3d.cxx.

void vimt3d_transform_3d::set_origin ( const vgl_point_3d< double > & p )

Modifies the transformation so that origin == p.

Modifies the transformation so that operator()(vgl_point_3d<double> (0,0)) == p. The rest of the transformation is unaffected. If the transformation was previously the identity, it becomes a translation.

Definition at line 372 of file vimt3d_transform_3d.cxx.

void vimt3d_transform_3d::set_rigid_body	(	double	r_x,
		double	r_y,
		double	r_z,
		double	t_x,
		double	t_y,
		double	t_z
	)

Sets the transformation to be rotation, followed by translation.