TransformByComponents Class Reference

Specify a transform matrix by its components. More...

#include <Mesh/Geometry/transformbycomponents.h>

Inheritance diagram for TransformByComponents:

Public Member Functions
	TransformByComponents ()
	TransformByComponents (const TransformByComponents &t)
	TransformByComponents (const TransformMatrix &matrix)
	~TransformByComponents () override
bool	canSerialize () const override
const Vector3d &	getEulerAngles () const
const TransformMatrix &	getMatrix () const
const Vector3d &	getScaleFactors () const
const Vector3d &	getShearFactors () const
const Vector3d &	getTranslation () const
bool	load (const DataExecution::SerializedItem &item) override
TransformByComponents &	operator= (const TransformByComponents &t)
bool	save (DataExecution::SerializedItem &item) const override
void	setEulerAngles (const Vector3d &angles)
void	setScaleFactors (const Vector3d &scale)
void	setScaleFactors (double uniformScale)
void	setShearFactors (const Vector3d &shear)
void	setTranslation (const Vector3d &trans)
Public Member Functions inherited from Serialize
virtual	~Serialize ()=default
virtual bool	canSerialize () const =0
virtual bool	load (const SerializedItem &item)=0
virtual bool	save (SerializedItem &item) const =0

Detailed Description

This class is a compliment to TransformMatrix. Its purpose is to store a transform's components rather than the fully general transform matrix, allowing client code to manipulate these components directly without going through a conversion process from the general transform matrix. This is important where numerical rounding or non-uniqueness of rotation angles matter (which it usually does for any user interface widgets representing the transform in some way).

Unlike TransformMatrix, this class is not meant to be used in computationally intensive situations. You would normally extract a TransformMatrix from a TransformByComponents class and then re-use that TransformMatrix for subsequent computations.

All rotations are stored in radians.

Note

You can replace any TransformGroup input for an operation with TransformByComponents because the serialized form of both is the same. Some of the function names are slightly different, but at least serialized workspaces will remain supported. You can also replace any TransformMatrix with a TransformByComponents and any serialized data will read in correctly, but unlike for TransformGroup, once your data is saved as a TransformByComponents, you cannot then later switch back to a TransformMatrix because the TransformMatrix class cannot load the serialized data any more.

Constructor & Destructor Documentation

TransformByComponents() [1/3]

TransformByComponents

(

)

The default constructed transform is no transform at all. The matrix will be an identity matrix.

TransformByComponents() [2/3]

TransformByComponents

(

const TransformByComponents &

t

)

Parameters

t	The transform to copy. Its matrix is also copied rather than recomputing it from the components.

TransformByComponents() [3/3]

TransformByComponents

(

const TransformMatrix &

matrix

)

Parameters

matrix

The TransformMatrix whose components are to be extracted and subsequently used to set the components for this object. If there is any problem in extracting the components from matrix, the components will be silently set to values indicating no transform (ie the same as the default constructor). Hence, it is the caller's responsibility to ensure that matrix can have its components extracted.

Note that it is generally wise to avoid using this constructor if possible. It will not necessarily preserve the same angles if a set of components is converted to a matrix and back to components again. This is because of the non-uniqueness of euler angles for any given rotation as well as numerical rounding involved in the extraction of components from the matrix.

~TransformByComponents()

~TransformByComponents ( )

override

Member Function Documentation

canSerialize()

bool canSerialize ( ) const

overridevirtual

Returns

True if this object can be serialized.

For objects that can be serialized, the save and load functions will be used to do the serialization. If this function returns false, both load() and save() must also return false.

Implements Serialize.

getEulerAngles()

const Vector3d & getEulerAngles

(

)

const

Returns

The euler angle rotation components in radians.

See also

setEulerAngles()

getMatrix()

const TransformMatrix & getMatrix

(

)

const

Returns

The matrix representation of the components.

Because the matrix is updated every time the components change, calling this function is cheap since no calculation is required.

getScaleFactors()

const Vector3d & getScaleFactors

(

)

const

Returns

The scale factor components. To achieve uniform scaling, all three components must be the same. To achieve mirroring, components can be negative.

See also

setScaleFactors()

getShearFactors()

const Vector3d & getShearFactors

(

)

const

Returns

The shear factor components. Note that uses of non-zero shear are almost non-existent at time of writing, so this functionality might be relatively untested.

See also

setShearFactors()

getTranslation()

const Vector3d & getTranslation

(

)

const

Returns

The translation components.

See also

setTranslation()

load()

bool load ( const DataExecution::SerializedItem &  item )

overridevirtual

Parameters

item	Supplies the state to be loaded into this object.

This function will load the state of this object from item. For many object types, this is most easily implemented in terms of the object's input operator (>>).

It would be reasonable for subclass implementations to assume that the data provided in item is in the same form as would have been saved from a call to save.

Returns

If the state of the object could not be loaded, the function returns false. A return value of true implies that the object state was successfully loaded. If canSerialize() returns false, this function must do nothing except return false as well.

Implements Serialize.

operator=()

TransformByComponents & operator=

(

const TransformByComponents &

t

)

Parameters

t	The transform components to assign to this object. The internal matrix is also copied, not recomputed.

save()

bool save ( DataExecution::SerializedItem &  item ) const

overridevirtual

Parameters

item	Where to save the state of this object.

This function will serialise the object by saving it to item. For most object types, this is most easily implemented in terms of the object's output operator (<<).

It is allowable for an object to only serialize part of itself. This would be useful if the data it represents has a set of defaults and only those values different to the defaults need to be serialized. Such an implementation then needs to be careful how it handles the complimentary load member function.

Returns

If an object could not be serialised or if the underlying object type does not support serialisation, this function should return false. A return value of true implies that the object was successfully saved to item. If canSerialize() returns false, this function must do nothing except return false as well.

Implements Serialize.

setEulerAngles()

void setEulerAngles

(

const Vector3d &

angles

)

Parameters

angles

The euler angle rotation components in radians.

Note

Calling this function causes the internal matrix to be recomputed.

See also

getEulerAngles()

setScaleFactors() [1/2]

void setScaleFactors

(

const Vector3d &

scale

)

Parameters

scale

The scale factor components. To achieve uniform scaling, set all three components to the same value or call the other overload of this function which takes a single double value to apply to all three components. To achieve mirroring, scale components can be negative.

Note

Calling this function causes the internal matrix to be recomputed.

See also

setScaleFactors()

setScaleFactors() [2/2]

void setScaleFactors

(

double

uniformScale

)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

setShearFactors()

void setShearFactors

(

const Vector3d &

shear

)

Parameters

shear

The shear factor components. Note that uses of non-zero shear are almost non-existent at time of writing, so this functionality might be relatively untested.

Note

Calling this function causes the internal matrix to be recomputed.

See also

getShearFactors()

setTranslation()

void setTranslation

(

const Vector3d &

trans

)

Parameters

trans

The new translation components.

Note

Calling this function causes the internal matrix to be recomputed.

See also

getTranslation()