Class to perform rigid object transformations in 3 dimensions. More...

#include "stir_experimental/motion/RigidObject3DTransformation.h"

Inheritance diagram for stir::RigidObject3DTransformation:

[legend]

Public Member Functions
	RigidObject3DTransformation (const Quaternion< float > &quat, const CartesianCoordinate3D< float > &translation)
	Constructor taking quaternion and translation info. More...

RigidObject3DTransformation	inverse () const
	Compute the inverse transformation.

Quaternion< float >	get_quaternion () const
	Get quaternion.

CartesianCoordinate3D< float >	get_translation () const
	Get translation.

BasicCoordinate< 3, float >	transform_point (const BasicCoordinate< 3, float > &point) const override
	Transform point.

float	jacobian (const BasicCoordinate< 3, float > &point) const override
	Computes the jacobian for the transformation (which is always 1)

void	transform_bin (Bin &bin, const ProjDataInfo &out_proj_data_info, const ProjDataInfo &in_proj_data_info) const
	Transform bin from some projection data. More...

void	get_relative_transformation (RigidObject3DTransformation &output, const RigidObject3DTransformation &reference)
	Get relative transformation (not implemented at present)

Public Member Functions inherited from stir::RegisteredParsingObject< RigidObject3DTransformation, ObjectTransformation< 3, float >, ObjectTransformation< 3, float > >
std::string	get_registered_name () const override
	Returns Derived::registered_name.

std::string	parameter_info () override
	Returns a string with all parameters and their values, in a form suitable for parsing again.

Public Member Functions inherited from stir::ObjectTransformation< 3, float >
virtual BasicCoordinate< num_dimensions, float >	transform_point (const BasicCoordinate< num_dimensions, float > &point) const=0
	Transform point.

virtual float	jacobian (const BasicCoordinate< num_dimensions, float > &point) const=0
	Returns the determinant of the Jacobian matrix. More...

Public Member Functions inherited from stir::ParsingObject
	ParsingObject (const ParsingObject &)

ParsingObject &	operator= (const ParsingObject &)

void	ask_parameters ()

bool	parse (std::istream &f)

bool	parse (const char *const filename)

Static Public Member Functions
template<class Iter1T , class Iter2T >
static Succeeded	find_closest_transformation (RigidObject3DTransformation &result, Iter1T start_orig_points, Iter1T end_orig_points, Iter2T start_transformed_points, const Quaternion< float > &initial_rotation=Quaternion< float >(1.F, 0.F, 0.F, 0.F))
	Find the rigid transformation that gives the closest match between 2 sets of points. More...

template<class Iter1T , class Iter2T >
static double	RMSE (const RigidObject3DTransformation &transformation, Iter1T start_orig_points, Iter1T end_orig_points, Iter2T start_transformed_points)
	Compute Root Mean Square Error for 2 sets of points.

Static Public Member Functions inherited from stir::RegisteredParsingObject< RigidObject3DTransformation, ObjectTransformation< 3, float >, ObjectTransformation< 3, float > >
static ObjectTransformation< 3, float > *	read_from_stream (std::istream *)
	Construct a new object (of type Derived) by parsing the istream. More...

Static Public Member Functions inherited from stir::RegisteredObject< Root >
static Root *	read_registered_object (std::istream *in, const std::string &registered_name)
	Construct a new object (of a type derived from Root, its actual type determined by the registered_name parameter) by parsing the istream. More...

static Root *	ask_type_and_parameters ()
	ask the user for the type, and then calls read_registered_object(0, type) More...

static void	list_registered_names (std::ostream &stream)
	List all possible registered names to the stream. More...

Static Public Attributes
static const char *const	registered_name = "rigid"

Friends
RigidObject3DTransformation	compose (const RigidObject3DTransformation &apply_last, const RigidObject3DTransformation &apply_first)
	Composition of 2 transformations. More...

Additional Inherited Members
Public Types inherited from stir::ObjectTransformation< 3, float >
typedef ObjectTransformation	hierarchy_base_type
	typedef used by read_from_file

Protected Types inherited from stir::RegisteredObject< Root >
typedef Root (	RootFactory) (std::istream *)
	The type of a root factory is a function, taking an istream* as argument, and returning a Root*.

typedef FactoryRegistry< std::string, RootFactory, interfile_less >	RegistryType
	The type of the registry.

Protected Member Functions inherited from stir::ParsingObject
virtual void	set_defaults ()
	Set defaults before parsing.

virtual void	initialise_keymap ()
	Initialise all keywords.

virtual bool	post_processing ()
	This will be called at the end of the parsing. More...

virtual void	set_key_values ()
	This will be called before parsing or parameter_info is called. More...

Static Protected Member Functions inherited from stir::RegisteredObject< Root >
static RegistryType &	registry ()
	Static function returning the registry. More...

Protected Attributes inherited from stir::ParsingObject
KeyParser	parser

Detailed Description

Class to perform rigid object transformations in 3 dimensions.

Supported transformations include rotations and translations. Rotations are encoded using quaternions. The convention used is described in
B.K. Horn, Closed-form solution of absolute orientation using unit quaternions, J. Opt. Soc. Am. A Vol.4 No. 6, (1987) p.629.

Warning: STIR uses a left-handed coordinate-system.

The transformation that is applied is as follows

$r' = \mathrm{conj}(q)(r-t)q$

where the quaternion is specified as ${[}q0,qz,qy,qx{]}$ , while the translation is initialised in the usual (in STIR) reverse order, e.g.

CartesianCoordinate3D<float> t(tz,ty,tx);

Note that this transformation is the inverse of Horn's.

This implements a translation followed by a rotation. The quaternion is constructed by as follows:
A rotation around the axis with direction ${[}n_z,n_y,n_x{]}$ and angle $\phi$ corresponds to a quaternion ${[}cos(\phi),sin(\phi) n_z, sin(\phi) n_y, sin(\phi)n_x{]}$ .

Todo:: Document sign choice for rotation.

This class can transform coordinates and Bin object belonging to some projection data.

Warning: The Euler angles are probably different from the ones used in the Shape3D hierarchy.

Todo:: define Euler angles (the code is derived from the Polaris manual)

Constructor & Destructor Documentation

◆ RigidObject3DTransformation()

stir::RigidObject3DTransformation::RigidObject3DTransformation	(	const Quaternion< float > &	quat,
		const CartesianCoordinate3D< float > &	translation
	)

Constructor taking quaternion and translation info.

See also: RigidObject3DTransformation class documentation for conventions

References stir::square().

Member Function Documentation

◆ find_closest_transformation()

template<class Iter1T , class Iter2T >

template Succeeded stir::RigidObject3DTransformation::find_closest_transformation	(	RigidObject3DTransformation &	result,
		Iter1T	start_orig_points,
		Iter1T	end_orig_points,
		Iter2T	start_transformed_points,
		const Quaternion< float > &	initial_rotation = `Quaternion< float >(1.F, 0.F, 0.F, 0.F)`
	)

static

Find the rigid transformation that gives the closest match between 2 sets of points.

Minimises the Mean Square Error, i.e. the sum of

norm_squared(result.transform_point(orig_point) - transformed_point)

The implementation uses Horn's algorithm.

Horn's method needs to compute the maximum eigenvector of a matrix, which is done here using the Power method (see max_eigenvector_using_power_method()).

initial_rotation will be used to initialise the Power method. So, a good choice will result in faster convergence, but would also avoid a problem when the default initial choice would correspond to another eigenvector of the matrix (giving a very bad match).

References stir::average(), stir::VectorWithOffset< T >::begin(), stir::VectorWithOffset< T >::end(), stir::error(), stir::max_eigenvector_using_power_method(), transform_point(), and stir::warning().

◆ transform_bin()

void stir::RigidObject3DTransformation::transform_bin	(	Bin &	bin,
		const ProjDataInfo &	out_proj_data_info,
		const ProjDataInfo &	in_proj_data_info
	)		const

Transform bin from some projection data.

Finds 'closest' (in some sense) bin to the transformed LOR.

if NEW_ROT is not #defined at compilation time, it will throw an exception when arc-corrected data is used.

References stir::ProjDataInfo::get_bin(), stir::Bin::get_bin_value(), stir::ProjDataInfo::get_LOR(), stir::Scanner::get_num_rings(), stir::Scanner::get_ring_spacing(), stir::ProjDataInfo::get_scanner_ptr(), stir::Bin::set_bin_value(), and transform_point().

Referenced by stir::transform_3d_object().

Friends And Related Function Documentation

◆ compose

RigidObject3DTransformation compose	(	const RigidObject3DTransformation &	apply_last,
		const RigidObject3DTransformation &	apply_first
	)

friend

Composition of 2 transformations.

This provides a way to perform 2 transformations after eachother. The following code will work

RigidObject3DTransformation tf_1,tf_2; // initialise somehow
const RigidObject3DTransformation tf_2_1 = compose(tf_2,tf_1));
  const CartesianCoordinate3D<float> point(1.F,-5.F,2.F);
  assert(norm(tf_2.transform_point(tf_1.transform_point(point)) -
              tf_2_ 1.transform_point(point))
         < .01);

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

/home/sirfuser/devel/STIRdistrib/STIR/src/include/stir_experimental/motion/RigidObject3DTransformation.h
/home/sirfuser/devel/STIRdistrib/STIR/src/experimental/motion/RigidObject3DTransformation.cxx

Public Member Functions

Static Public Member Functions

Static Public Attributes

Friends

Additional Inherited Members