Referential holds information about coordinates system and axes. More...

#include <cartodata/transformation/referential.h>

Inheritance diagram for carto::Referential:

[legend]

Collaboration diagram for carto::Referential:

[legend]

Public Types
enum	Orientation { Undefined , L , R , A , P , S , I , T , t , U , u , V , v , W , w , X , x , Y , y , Z , z }
	Axis orientation enum. More...

Public Member Functions
	Referential (unsigned ndim=3)
	Build a referential with the given number of dimensions.

	Referential (const Referential &ref)

	Referential (Object ref)

	~Referential ()

Referential &	operator= (const Referential &ref)

unsigned	order () const
	number of axes (or space dimensions)

void	ensureOrder (unsigned ndim)
	update the order, keeping existing orientation information

const std::string &	uuid () const
	a referential has an unique identifier

std::string &	uuid ()

std::string	orientationStr () const
	orientation of the referential, as a string of one letter per axis

std::string	orientationStr (const std::string &orient) const
	extended orientation information according to the needed number of axes

std::vector< int >	axesOrientation () const
	orientation of the referential, as a vector of constants.

bool	isDirect () const

rc_ptr< Transformation >	toOrientation (const std::string &orient, const std::vector< float > &transl=std::vector< float >(), bool allow_resize=false) const
	Build a transformation matrix to go from this referential to a given orientation.

rc_ptr< Transformation >	toOrientation (const std::string &orient, const std::vector< int > &transl, bool allow_resize=false) const
	same as above but translation is given as ints

rc_ptr< Transformation >	toOrientation (const std::vector< int > &orient, const std::vector< float > &transl=std::vector< float >()) const
	Build a transformation matrix to go from this referential to a given orientation.

std::string	lpiReferentialUuid () const
	LPI oriented referential.

void	setUuid (const std::string &uuid)
	force a new UUID

void	setOrientation (const std::string &orient, bool allow_resize=false)
	set a new orientation for the referential.

void	setOrientation (const std::vector< int > &orient)
	set a new orientation for the referential.

void	setLpiReferential (const std::string &lpi_uuid)
	set the LPI original referential UUID

Object	header () const
	referential header, may contain anything useful

void	setHeader (const Object header)

Object	exportedHeader () const
	export a ready-to-save version of the header, where, especially, the axes_orientation property is an orientation string

bool	is3DOriented () const
	tells if the orientation is comatible with a 3D transformation (all axes after the 3th are the default ones)

bool	is3DOriented (const std::string &orient) const
	tells if the given orientation is 3D compatible

bool	isLpiOriented () const
	tells if the orientation is the default LPI one.

std::vector< int >	orientationFromTransform (const AffineTransformationBase &tr) const
	target orientation for a given transform matrix.

Static Public Member Functions
static std::string	orientationStr (Orientation orient)
	orientation string for a single axis orientation (1 char)

static std::string	orientationStr (const std::vector< int > &orient)
	build the orientation string from a vector of constants

static Orientation	orientationCode (const std::string &orient)
	orientation constant for a single orientation axis character

static std::vector< int >	orientationVector (const std::string &orient, unsigned dim=0)
	build an orientation vector from a string.

static void	setAxisTransform (AffineTransformationBase &tr, int src_axis, int dst_axis, int inv_mult, const std::vector< float > &transl=std::vector< float >())
	Build one line of transformation matrix.

static bool	is3DOriented (const std::vector< int > &orient)
	tells if the given orientation is 3D compatible

static Referential	fromHeader (const Object header, bool except_if_undefined=false)
	Build a Referential object from a header.

Detailed Description

Referential holds information about coordinates system and axes.

It also provides utility methods to transform to other coordinates orientations.

Orientation describes the coordinates system axes, what they represent and in which direction they go.

The orientation description is either a vector of constants (Orientaton enum), or a string containing one letter per axis. Each letter or Orientation enum value describes the axis and its direction. It is based on the Left/Right, Anterior/Posterior, Superior/Inferior convention, see:

http://www.grahamwideman.com/gw/brain/orientation/orientterms.htm

For brain images, axes orientations are described relatively to the head: AP (anterior to posterior) or PA, LR (left to right) or RL, SI (superior to inferior) or IS. To summarize the 3 axes we sometimes use the 3 initials of the directions axes are pointing to: RAS (X: to Right, Y: to Anterior, Z: to Superior), LAS, LPI, etc.

This convention used in the neuroimaging community is valid for 3D images. Here we extend it to up to 10 dimensions, using letters T to Z, with uppercase for increasing order, and lowercase for decreasing order. Thus, T can hopefully correspond to "time". But be careful that letters X, Y, Z here do not correspond to the common "1st, 2nd and 3rd axes": here it is the meaning of axes.

Orientation strings may be given as "incomplete" strings, and will in most cases be extended to the actual number of dimensions, using default axes to complement. Thus, for a 5D referential, "LPI" is the same sas "LPITU".

Definition at line 77 of file referential.h.

Member Enumeration Documentation

◆ Orientation

enum carto::Referential::Orientation

Axis orientation enum.

Enumerator
Undefined
L
R
A
P
S
I
T
t
U
u
V
v
W
w
X
x
Y
y
Z
z

Definition at line 82 of file referential.h.

Constructor & Destructor Documentation

◆ Referential() [1/3]

carto::Referential::Referential ( unsigned ndim = 3 )

Build a referential with the given number of dimensions.

Referenced by fromHeader(), operator=(), and Referential().

◆ Referential() [2/3]

carto::Referential::Referential ( const Referential & ref )

References carto::RCObject::ref, and Referential().

◆ Referential() [3/3]

carto::Referential::Referential ( Object ref )

References carto::RCObject::ref.

◆ ~Referential()

carto::Referential::~Referential ( )

Member Function Documentation

◆ axesOrientation()

std::vector< int > carto::Referential::axesOrientation ( ) const

inline

orientation of the referential, as a vector of constants.

Each number corresponds to an Orientation enum value, but cast to int

Definition at line 128 of file referential.h.

◆ ensureOrder()

void carto::Referential::ensureOrder ( unsigned ndim )

update the order, keeping existing orientation information

◆ exportedHeader()

Object carto::Referential::exportedHeader ( ) const

export a ready-to-save version of the header, where, especially, the axes_orientation property is an orientation string

◆ fromHeader()

static Referential carto::Referential::fromHeader	(	const Object	header,
		bool	except_if_undefined = false )

static

Build a Referential object from a header.

This is basically the same as the constructor Referential( Object ) except that if except_if_undefined is set, and if the header does not specify an orientation, then an exception is thrown.

References header(), and Referential().

◆ header()

Object carto::Referential::header ( ) const

inline

referential header, may contain anything useful

Definition at line 199 of file referential.h.

Referenced by fromHeader(), and setHeader().

◆ is3DOriented() [1/3]

bool carto::Referential::is3DOriented ( ) const

tells if the orientation is comatible with a 3D transformation (all axes after the 3th are the default ones)

◆ is3DOriented() [2/3]

bool carto::Referential::is3DOriented ( const std::string & orient ) const

tells if the given orientation is 3D compatible

◆ is3DOriented() [3/3]

static bool carto::Referential::is3DOriented ( const std::vector< int > & orient )

static

tells if the given orientation is 3D compatible

◆ isDirect()

bool carto::Referential::isDirect ( ) const

◆ isLpiOriented()

bool carto::Referential::isLpiOriented ( ) const

tells if the orientation is the default LPI one.

Referenced by lpiReferentialUuid().

◆ lpiReferentialUuid()

std::string carto::Referential::lpiReferentialUuid ( ) const

inline

LPI oriented referential.

AIMS volumes are initially in LPI orientation. If flipped, the referential will change to a diferent one. The LPI referential is the original one before any flip is applied.

Definition at line 174 of file referential.h.

References isLpiOriented().

◆ operator=()

Referential & carto::Referential::operator= ( const Referential & ref )

References carto::RCObject::ref, and Referential().

◆ order()

unsigned carto::Referential::order ( ) const

inline

number of axes (or space dimensions)

Definition at line 116 of file referential.h.

◆ orientationCode()

static Orientation carto::Referential::orientationCode ( const std::string & orient )

static

orientation constant for a single orientation axis character

◆ orientationFromTransform()

std::vector< int > carto::Referential::orientationFromTransform ( const AffineTransformationBase & tr ) const

target orientation for a given transform matrix.

The matrix should be a flip matrix, not any affine transform.

◆ orientationStr() [1/4]

std::string carto::Referential::orientationStr ( ) const

orientation of the referential, as a string of one letter per axis

◆ orientationStr() [2/4]

std::string carto::Referential::orientationStr ( const std::string & orient ) const

extended orientation information according to the needed number of axes

◆ orientationStr() [3/4]

static std::string carto::Referential::orientationStr ( const std::vector< int > & orient )

static

build the orientation string from a vector of constants

◆ orientationStr() [4/4]

static std::string carto::Referential::orientationStr ( Orientation orient )

static

orientation string for a single axis orientation (1 char)

◆ orientationVector()

static std::vector< int > carto::Referential::orientationVector	(	const std::string &	orient,
		unsigned	dim = 0 )

static

build an orientation vector from a string.

If dim is given, the vector will be extended to this number of dimensions.

◆ setAxisTransform()

static void carto::Referential::setAxisTransform	(	AffineTransformationBase &	tr,
		int	src_axis,
		int	dst_axis,
		int	inv_mult,
		const std::vector< float > &	transl = std::vector< float >() )

static

Build one line of transformation matrix.

This rather internal function is used to build a transformation matrix. This function builds one line to get from a source axis to a destination one.

◆ setHeader()

void carto::Referential::setHeader ( const Object header )

References header().

◆ setLpiReferential()

void carto::Referential::setLpiReferential ( const std::string & lpi_uuid )

set the LPI original referential UUID

◆ setOrientation() [1/2]

void carto::Referential::setOrientation	(	const std::string &	orient,
		bool	allow_resize = false )

set a new orientation for the referential.

if allow_resize is false, the given orientation will decide the new axes number. If true, it will be updated to keep the older number of dimensions.

No other information will be changed.

Referenced by carto::Creator< Volume< T > >::create().

◆ setOrientation() [2/2]

void carto::Referential::setOrientation ( const std::vector< int > & orient )

set a new orientation for the referential.

◆ setUuid()

void carto::Referential::setUuid ( const std::string & uuid )

force a new UUID

References uuid().

◆ toOrientation() [1/3]

rc_ptr< Transformation > carto::Referential::toOrientation	(	const std::string &	orient,
		const std::vector< float > &	transl = std::vector< float >(),
		bool	allow_resize = false ) const

Build a transformation matrix to go from this referential to a given orientation.

If allow_resize is false, the matrix will have exactly the order of the given orientation. If it it true, it will be extended to the order of the referential.

The translation vector is used to build the last column of the transformation matrix: it is the origin shift needed when an axis is reversed. Typically it is the volume dimension (in mm, or the dimension -1 in voxels)

Referenced by toOrientation().

◆ toOrientation() [2/3]

rc_ptr< Transformation > carto::Referential::toOrientation	(	const std::string &	orient,
		const std::vector< int > &	transl,
		bool	allow_resize = false ) const

inline

same as above but translation is given as ints

Definition at line 149 of file referential.h.

References toOrientation().

◆ toOrientation() [3/3]

rc_ptr< Transformation > carto::Referential::toOrientation	(	const std::vector< int > &	orient,
		const std::vector< float > &	transl = std::vector< float >() ) const

Build a transformation matrix to go from this referential to a given orientation.

Same as above, but orientation is given as a vector of constants.

◆ uuid() [1/2]

std::string & carto::Referential::uuid ( )

inline

Definition at line 121 of file referential.h.

◆ uuid() [2/2]

const std::string & carto::Referential::uuid ( ) const

inline

a referential has an unique identifier

Definition at line 120 of file referential.h.

Referenced by setUuid().

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

cartodata/transformation/referential.h

Public Types

Public Member Functions

Static Public Member Functions

Detailed Description

Member Enumeration Documentation

◆ Orientation

Constructor & Destructor Documentation

◆ Referential() [1/3]

◆ Referential() [2/3]

◆ Referential() [3/3]

◆ ~Referential()

Member Function Documentation

◆ axesOrientation()

◆ ensureOrder()

◆ exportedHeader()

◆ fromHeader()

◆ header()

◆ is3DOriented() [1/3]

◆ is3DOriented() [2/3]

◆ is3DOriented() [3/3]

◆ isDirect()

◆ isLpiOriented()

◆ lpiReferentialUuid()

◆ operator=()

◆ order()

◆ orientationCode()

◆ orientationFromTransform()

◆ orientationStr() [1/4]

◆ orientationStr() [2/4]

◆ orientationStr() [3/4]

◆ orientationStr() [4/4]

◆ orientationVector()

◆ setAxisTransform()

◆ setHeader()

◆ setLpiReferential()

◆ setOrientation() [1/2]

◆ setOrientation() [2/2]

◆ setUuid()

◆ toOrientation() [1/3]

◆ toOrientation() [2/3]

◆ toOrientation() [3/3]

◆ uuid() [1/2]

◆ uuid() [2/2]