The Frame class represents a coordinate system, defined by a position and an orientation. More...

#include <easy3d/renderer/frame.h>

Inheritance diagram for Frame:

Public Member Functions
	Frame ()
	Default constructor.

virtual	~Frame ()

	Frame (const Frame &frame)
	Copy constructor.

Frame &	operator= (const Frame &frame)
	Assignment operator.

World coordinates position and orientation
	Frame (const vec3 &position, const quat &orientation)
	Constructor with position and orientation.

void	setPosition (const vec3 &position)
	Sets the position of the Frame.

void	setPositionWithConstraint (vec3 &position)
	Sets the position of the Frame with constraint.

void	setOrientation (const quat &orientation)
	Sets the orientation of the Frame.

void	setOrientationWithConstraint (quat &orientation)
	Sets the orientation of the Frame with constraint.

void	setPositionAndOrientation (const vec3 &position, const quat &orientation)
	Sets the position and orientation of the Frame.

void	setPositionAndOrientationWithConstraint (vec3 &position, quat &orientation)
	Sets the position and orientation of the Frame with constraint.

vec3	position () const
	Returns the position of the Frame.

quat	orientation () const
	Returns the orientation of the Frame.

Local translation and rotation w/r reference Frame
void	setTranslation (const vec3 &translation)
	Sets the translation of the Frame.

void	setTranslationWithConstraint (vec3 &translation)
	Sets the translation of the Frame with constraint.

void	setRotation (const quat &rotation)
	Sets the rotation of the Frame.

void	setRotationWithConstraint (quat &rotation)
	Sets the rotation of the Frame with constraint.

void	setTranslationAndRotation (const vec3 &translation, const quat &rotation)
	Sets the translation and rotation of the Frame.

void	setTranslationAndRotationWithConstraint (vec3 &translation, quat &rotation)
	Sets the translation and rotation of the Frame with constraint.

vec3	translation () const
	Returns the translation of the Frame.

quat	rotation () const
	Returns the rotation of the Frame.

Frame hierarchy
const Frame *	referenceFrame () const
	Returns the reference Frame.

void	setReferenceFrame (const Frame *refFrame)
	Sets the reference Frame.

bool	settingAsReferenceFrameWillCreateALoop (const Frame *const frame) const
	Checks if setting the reference Frame will create a loop.

Frame modification
void	translate (vec3 &t)
	Translates the Frame.

void	translate (const vec3 &t)
	Translates the Frame.

void	rotate (quat &q)
	Rotates the Frame.

void	rotate (const quat &q)
	Rotates the Frame.

void	rotateAroundPoint (quat &rotation, const vec3 &point)
	Rotates the Frame around a point.

void	rotateAroundPoint (const quat &rotation, const vec3 &point)
	Rotates the Frame around a point.

void	alignWithFrame (const Frame *const frame, bool move=false, float threshold=0.0f)
	Aligns the Frame with another Frame.

void	projectOnLine (const vec3 &origin, const vec3 &direction)
	Projects the Frame on a line.

Coordinate system transformation of 3D coordinates
vec3	coordinatesOf (const vec3 &src) const
	Transforms a 3D point to the Frame's coordinate system.

vec3	inverseCoordinatesOf (const vec3 &src) const
	Transforms a 3D point from the Frame's coordinate system to the world coordinate system.

vec3	localCoordinatesOf (const vec3 &src) const
	Transforms a 3D point to the Frame's local coordinate system.

vec3	localInverseCoordinatesOf (const vec3 &src) const
	Transforms a 3D point from the Frame's local coordinate system to the world coordinate system.

vec3	coordinatesOfIn (const vec3 &src, const Frame *const in) const
	Transforms a 3D point to another Frame's coordinate system.

vec3	coordinatesOfFrom (const vec3 &src, const Frame *const from) const
	Transforms a 3D point from another Frame's coordinate system to the Frame's coordinate system.

Coordinate system transformation of vectors
vec3	transformOf (const vec3 &src) const
	Transforms a 3D vector to the Frame's coordinate system.

vec3	inverseTransformOf (const vec3 &src) const
	Transforms a 3D vector from the Frame's coordinate system to the world coordinate system.

vec3	localTransformOf (const vec3 &src) const
	Transforms a 3D vector to the Frame's local coordinate system.

vec3	localInverseTransformOf (const vec3 &src) const
	Transforms a 3D vector from the Frame's local coordinate system to the world coordinate system.

vec3	transformOfIn (const vec3 &src, const Frame *const in) const
	Transforms a 3D vector to another Frame's coordinate system.

vec3	transformOfFrom (const vec3 &src, const Frame *const from) const
	Transforms a 3D vector from another Frame's coordinate system to the Frame's coordinate system.

Constraint on the displacement
Constraint *	constraint () const
	Returns the current constraint applied to the Frame.

void	setConstraint (Constraint *const constraint)
	Sets the constraint attached to the Frame.

Associated matrices
mat4	matrix () const
	Returns the transformation matrix of the Frame.

mat4	worldMatrix () const
	Returns the world transformation matrix of the Frame.

void	setFromMatrix (const mat4 &m)
	Sets the Frame from a transformation matrix.

Inversion of the transformation
Signal	modified
	Signal emitted when the Frame is modified.

Frame	inverse () const
	Returns the inverse of the Frame.

Frame	worldInverse () const
	Returns the inverse of the Frame's world transformation.

Detailed Description

The Frame class represents a coordinate system, defined by a position and an orientation.

A Frame is a 3D coordinate system, represented by a position() and an orientation(). The order of these transformations is important: the Frame is first translated and then rotated around the new translated origin.

A Frame is useful to define the position and orientation of a 3D rigid object, using its matrix() method. Many functions are provided to transform a 3D point from one coordinate system (Frame) to another. You may also want to transform a 3D vector (such as a normal), which corresponds to applying only the rotational part of the frame transformation.

The translation() and the rotation() that are encapsulated in a Frame can also be used to represent a rigid transformation of space. Such a transformation can also be interpreted as a change of coordinate system.

Hierarchy of Frames

The position and the orientation of a Frame are actually defined with respect to a referenceFrame(). The default referenceFrame() is the world coordinate system (represented by a NULL referenceFrame()). Frames can hence easily be organized in a tree hierarchy, which root is the world coordinate system.

Constraints

An interesting feature of Frames is that their displacements can be constrained. When a Constraint is attached to a Frame, it filters the input of translate() and rotate(), and only the resulting filtered motion is applied to the Frame. Constraints are especially useful for the ManipulatedFrame instances, in order to forbid some mouse motions.

Derived classes

The ManipulatedFrame class inherits Frame and implements a mouse motion conversion, so that a Frame (and hence an object) can be manipulated in the scene with the mouse.

Examples: Tutorial_204_Viewer_Qt/main.cpp, and Tutorial_206_CameraInterpolation/main.cpp.

Constructor & Destructor Documentation

◆ Frame() [1/3]

Frame ( )

Default constructor.

Initializes the Frame object with default values.

◆ ~Frame()

virtual ~Frame ( )

virtual

Virtual destructor. Empty.

◆ Frame() [2/3]

Frame ( const Frame & frame )

Copy constructor.

Parameters

frame The Frame object to copy from.

Creates a new Frame object as a copy of the given Frame object.

◆ Frame() [3/3]

Frame	(	const vec3 &	position,
		const quat &	orientation )

Constructor with position and orientation.

Parameters

position	The position of the Frame.
orientation	The orientation of the Frame.

Initializes the Frame object with the given position and orientation.

Member Function Documentation

◆ alignWithFrame()

void alignWithFrame	(	const Frame *const	frame,
		bool	move = false,
		float	threshold = 0.0f )

Aligns the Frame with another Frame.

Parameters

frame	The Frame to align with.
move	Whether to move the Frame.
threshold	The threshold for alignment.

◆ constraint()

Constraint * constraint ( ) const

inline

Returns the current constraint applied to the Frame.

Returns: The current constraint.

A NULL value (default) means that no Constraint is used to filter Frame translation and rotation.

◆ coordinatesOf()

vec3 coordinatesOf ( const vec3 & src ) const

Transforms a 3D point to the Frame's coordinate system.

Parameters

src	The source point.

Returns: The transformed point.

◆ coordinatesOfFrom()

vec3 coordinatesOfFrom	(	const vec3 &	src,
		const Frame *const	from ) const

Transforms a 3D point from another Frame's coordinate system to the Frame's coordinate system.

Parameters

src	The source point.
from	The source Frame.

Returns: The transformed point.

◆ coordinatesOfIn()

vec3 coordinatesOfIn	(	const vec3 &	src,
		const Frame *const	in ) const

Transforms a 3D point to another Frame's coordinate system.

Parameters

src	The source point.
in	The target Frame.

Returns: The transformed point.

◆ inverse()

Frame inverse ( ) const

Returns the inverse of the Frame.

Returns: The inverse of the Frame.

See also: worldInverse()

◆ inverseCoordinatesOf()

vec3 inverseCoordinatesOf ( const vec3 & src ) const

Transforms a 3D point from the Frame's coordinate system to the world coordinate system.

Parameters

src	The source point.

Returns: The transformed point.

◆ inverseTransformOf()

vec3 inverseTransformOf ( const vec3 & src ) const

Transforms a 3D vector from the Frame's coordinate system to the world coordinate system.

Parameters

src	The source vector.

Returns: The transformed vector.

◆ localCoordinatesOf()

vec3 localCoordinatesOf ( const vec3 & src ) const

Transforms a 3D point to the Frame's local coordinate system.

Parameters

src	The source point.

Returns: The transformed point.

◆ localInverseCoordinatesOf()

vec3 localInverseCoordinatesOf ( const vec3 & src ) const

Transforms a 3D point from the Frame's local coordinate system to the world coordinate system.

Parameters

src	The source point.

Returns: The transformed point.

◆ localInverseTransformOf()

vec3 localInverseTransformOf ( const vec3 & src ) const

Transforms a 3D vector from the Frame's local coordinate system to the world coordinate system.

Parameters

src	The source vector.

Returns: The transformed vector.

◆ localTransformOf()

vec3 localTransformOf ( const vec3 & src ) const

Transforms a 3D vector to the Frame's local coordinate system.

Parameters

src	The source vector.

Returns: The transformed vector.

◆ matrix()

mat4 matrix ( ) const

Returns the transformation matrix of the Frame.

Returns: The transformation matrix.

◆ operator=()

Frame & operator= ( const Frame & frame )

Assignment operator.

Parameters

frame The Frame object to assign from.

Returns: A reference to this Frame object.

Performs a deep copy of all member variables from the given Frame object.

◆ orientation()

quat orientation ( ) const

Returns the orientation of the Frame.

Returns: The orientation of the Frame.

◆ position()

vec3 position ( ) const

Returns the position of the Frame.

Returns: The position of the Frame.

Examples: Tutorial_204_Viewer_Qt/main.cpp, and Tutorial_206_CameraInterpolation/main.cpp.

◆ projectOnLine()

void projectOnLine	(	const vec3 &	origin,
		const vec3 &	direction )

Projects the Frame on a line.

Parameters

origin	The origin of the line.
direction	The direction of the line.

◆ referenceFrame()

const Frame * referenceFrame ( ) const

inline

Returns the reference Frame.

Returns: The reference Frame.

Returns the reference Frame, in which coordinates system the Frame is defined. The translation() and rotation() of the Frame are defined with respect to the referenceFrame() coordinate system. A NULL referenceFrame() (default value)means that the Frame is defined in the world coordinate system. Use position() and orientation() to recursively convert values along the referenceFrame() chain and to get values expressed in the world coordinate system. The values match when the referenceFrame() is NULL. Use setReferenceFrame() to set this value and create a Frame hierarchy. Convenient functions allow you to convert 3D coordinates from one Frame to another: see coordinatesOf(), localCoordinatesOf(), coordinatesOfIn() and their inverse functions. Vectors can also be converted using transformOf(), transformOfIn, localTransformOf() and their inverse functions.

◆ rotate() [1/2]

void rotate ( const quat & q )

Rotates the Frame.

Parameters

q	The rotation quaternion.

◆ rotate() [2/2]

void rotate ( quat & q )

Rotates the Frame.

Parameters

q	The rotation quaternion.

◆ rotateAroundPoint() [1/2]

void rotateAroundPoint	(	const quat &	rotation,
		const vec3 &	point )

Rotates the Frame around a point.

Parameters

rotation	The rotation quaternion.
point	The point to rotate around.

◆ rotateAroundPoint() [2/2]

void rotateAroundPoint	(	quat &	rotation,
		const vec3 &	point )

Rotates the Frame around a point.

Parameters

rotation	The rotation quaternion.
point	The point to rotate around.

◆ rotation()

quat rotation ( ) const

inline

Returns the rotation of the Frame.

Returns: The rotation of the Frame.

Returns the Frame rotation, defined with respect to the referenceFrame(). Use orientation() to get the result in the world coordinates.

◆ setConstraint()

void setConstraint ( Constraint *const constraint )

inline

Sets the constraint attached to the Frame.

Parameters

constraint The new constraint.

A NULL value means no constraint. The previous constraint should be deleted by the calling method if needed.

◆ setFromMatrix()

void setFromMatrix ( const mat4 & m )

Sets the Frame from a transformation matrix.

Parameters

m	The transformation matrix.

◆ setOrientation()

void setOrientation ( const quat & orientation )

Sets the orientation of the Frame.

Parameters

orientation The new orientation of the Frame.

◆ setOrientationWithConstraint()

void setOrientationWithConstraint ( quat & orientation )

Sets the orientation of the Frame with constraint.

Parameters

orientation The new orientation of the Frame.

◆ setPosition()

void setPosition ( const vec3 & position )

Sets the position of the Frame.

Parameters

position The new position of the Frame.

◆ setPositionAndOrientation()

void setPositionAndOrientation	(	const vec3 &	position,
		const quat &	orientation )

Sets the position and orientation of the Frame.

Parameters

position	The new position of the Frame.
orientation	The new orientation of the Frame.

◆ setPositionAndOrientationWithConstraint()

void setPositionAndOrientationWithConstraint	(	vec3 &	position,
		quat &	orientation )

Sets the position and orientation of the Frame with constraint.

Parameters

position	The new position of the Frame.
orientation	The new orientation of the Frame.

◆ setPositionWithConstraint()

void setPositionWithConstraint ( vec3 & position )

Sets the position of the Frame with constraint.

Parameters

position The new position of the Frame.

◆ setReferenceFrame()

void setReferenceFrame ( const Frame * refFrame )

Sets the reference Frame.

The Frame translation() and rotation() are then defined in the referenceFrame() coordinate system. Use position() and orientation() to express these in the world coordinate system.

Parameters

refFrame The reference Frame.

◆ setRotation()

void setRotation ( const quat & rotation )

inline

Sets the rotation of the Frame.

Parameters

rotation The new rotation of the Frame.

Sets the rotation of the Frame, locally defined with respect to the referenceFrame(). Emits the modified() signal.

◆ setRotationWithConstraint()

void setRotationWithConstraint ( quat & rotation )

Sets the rotation of the Frame with constraint.

Parameters

rotation The new rotation of the Frame.

◆ settingAsReferenceFrameWillCreateALoop()

bool settingAsReferenceFrameWillCreateALoop ( const Frame *const frame ) const

Checks if setting the reference Frame will create a loop.

Parameters

frame The Frame to check.

Returns: true if setting the reference Frame will create a loop, false otherwise.

◆ setTranslation()

void setTranslation ( const vec3 & translation )

inline

Sets the translation of the Frame.

Parameters

translation The new translation of the Frame.

Sets the translation of the Frame, locally defined with respect to the referenceFrame(). Emits the modified() signal.

◆ setTranslationAndRotation()

void setTranslationAndRotation	(	const vec3 &	translation,
		const quat &	rotation )

Sets the translation and rotation of the Frame.

Parameters

translation	The new translation of the Frame.
rotation	The new rotation of the Frame.

◆ setTranslationAndRotationWithConstraint()

void setTranslationAndRotationWithConstraint	(	vec3 &	translation,
		quat &	rotation )

Sets the translation and rotation of the Frame with constraint.

Parameters

translation	The new translation of the Frame.
rotation	The new rotation of the Frame.

◆ setTranslationWithConstraint()

void setTranslationWithConstraint ( vec3 & translation )

Sets the translation of the Frame with constraint.

Parameters

translation The new translation of the Frame.

◆ transformOf()

vec3 transformOf ( const vec3 & src ) const

Transforms a 3D vector to the Frame's coordinate system.

Parameters

src	The source vector.

Returns: The transformed vector.

◆ transformOfFrom()

vec3 transformOfFrom	(	const vec3 &	src,
		const Frame *const	from ) const

Transforms a 3D vector from another Frame's coordinate system to the Frame's coordinate system.

Parameters

src	The source vector.
from	The source Frame.

Returns: The transformed vector.

◆ transformOfIn()

vec3 transformOfIn	(	const vec3 &	src,
		const Frame *const	in ) const

Transforms a 3D vector to another Frame's coordinate system.

Parameters

src	The source vector.
in	The target Frame.

Returns: The transformed vector.

◆ translate() [1/2]

void translate ( const vec3 & t )

Translates the Frame.

Parameters

t	The translation vector.

◆ translate() [2/2]

void translate ( vec3 & t )

Translates the Frame.

Parameters

t	The translation vector.

◆ translation()

vec3 translation ( ) const

inline

Returns the translation of the Frame.

Returns: The translation of the Frame.

Returns the Frame translation, defined with respect to the referenceFrame(). Use position() to get the result in the world coordinates.

◆ worldInverse()

Frame worldInverse ( ) const

inline

Returns the inverse of the Frame's world transformation.

Returns: The inverse of the Frame's world transformation.

The result Frame has a NULL referenceFrame() and a NULL constraint(). The orientation() of the new Frame is the quat::inverse() of the original orientation. Its position() is the negated and inverse rotated image of the original position. Use inverse() for a local (i.e. with respect to referenceFrame()) transformation inverse.

See also: inverse()

◆ worldMatrix()

mat4 worldMatrix ( ) const

Returns the world transformation matrix of the Frame.

Returns: The world transformation matrix.

Examples: Tutorial_207_RealCamera/main.cpp.

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

G:/3_code/Easy3D/easy3d/renderer/frame.h

Public Member Functions

Inversion of the transformation

Detailed Description

Hierarchy of Frames

Constraints

Derived classes

Constructor & Destructor Documentation

◆ Frame() [1/3]

◆ ~Frame()

◆ Frame() [2/3]

◆ Frame() [3/3]

Member Function Documentation

◆ alignWithFrame()

◆ constraint()

◆ coordinatesOf()

◆ coordinatesOfFrom()

◆ coordinatesOfIn()

◆ inverse()

◆ inverseCoordinatesOf()

◆ inverseTransformOf()

◆ localCoordinatesOf()

◆ localInverseCoordinatesOf()

◆ localInverseTransformOf()

◆ localTransformOf()

◆ matrix()

◆ operator=()

◆ orientation()

◆ position()

◆ projectOnLine()

◆ referenceFrame()

◆ rotate() [1/2]

◆ rotate() [2/2]

◆ rotateAroundPoint() [1/2]

◆ rotateAroundPoint() [2/2]

◆ rotation()

◆ setConstraint()

◆ setFromMatrix()

◆ setOrientation()

◆ setOrientationWithConstraint()

◆ setPosition()

◆ setPositionAndOrientation()

◆ setPositionAndOrientationWithConstraint()

◆ setPositionWithConstraint()

◆ setReferenceFrame()

◆ setRotation()

◆ setRotationWithConstraint()

◆ settingAsReferenceFrameWillCreateALoop()

◆ setTranslation()

◆ setTranslationAndRotation()

◆ setTranslationAndRotationWithConstraint()

◆ setTranslationWithConstraint()

◆ transformOf()

◆ transformOfFrom()

◆ transformOfIn()

◆ translate() [1/2]

◆ translate() [2/2]

◆ translation()

◆ worldInverse()

◆ worldMatrix()