G3D::CoordinateFrame Class Reference

A rigid body RT (rotation-translation) transformation. More...

Public Member Functions
	CoordinateFrame (const Any &any)
	CoordinateFrame ()
	Initializes to the identity coordinate frame. More...
	CoordinateFrame (const Point3 &_translation)
	CoordinateFrame (const Matrix3 &rotation, const Point3 &translation)
	CoordinateFrame (const Matrix3 &rotation)
	CoordinateFrame (const class UprightFrame &f)
	CoordinateFrame (class BinaryInput &b)
	CoordinateFrame (const CoordinateFrame &other)
	~CoordinateFrame ()
void	deserialize (class BinaryInput &b)
bool	fuzzyEq (const CoordinateFrame &other) const
bool	fuzzyIsIdentity () const
float	getHeading () const
	Returns the heading of the lookVector as an angle in radians relative to the world -z axis. More...
void	getXYZYPRDegrees (float &x, float &y, float &z, float &yaw, float &pitch, float &roll) const
void	getXYZYPRRadians (float &x, float &y, float &z, float &yaw, float &pitch, float &roll) const
CoordinateFrame	inverse () const
	Computes the inverse of this coordinate frame. More...
bool	isIdentity () const
Vector3	leftVector () const
	If a viewer looks along the look vector, this is the viewer's "left". More...
CoordinateFrame	lerp (const CoordinateFrame &other, float alpha) const
	Linearly interpolates between two coordinate frames, using Quat::slerp for the rotations. More...
void	lookAt (const Point3 &target)
void	lookAt (const Point3 &target, Vector3 up)
class Ray	lookRay () const
	Returns the ray starting at the camera origin travelling in direction CoordinateFrame::lookVector. More...
Vector3	lookVector () const
	The direction this camera is looking (its negative z axis) More...
void	moveTowards (const CoordinateFrame &goal, float maxTranslation, float maxRotation)
	Transform this coordinate frame towards goal, but not past it, goverened by maximum rotation and translations. More...
Vector3	normalToObjectSpace (const Vector3 &v) const
void	normalToObjectSpace (const Array< Vector3 > &v, Array< Vector3 > &vout) const
Vector3	normalToWorldSpace (const Vector3 &v) const
void	normalToWorldSpace (const Array< Vector3 > &v, Array< Vector3 > &vout) const
bool	operator!= (const CoordinateFrame &other) const
CoordinateFrame	operator* (const CoordinateFrame &other) const
	Compose: create the transformation that is other followed by this. More...
CoordinateFrame	operator+ (const Vector3 &v) const
CoordinateFrame	operator- (const Vector3 &v) const
bool	operator== (const CoordinateFrame &other) const
Point3	pointToObjectSpace (const Point3 &v) const
	Transforms the point into object space. More...
void	pointToObjectSpace (const Array< Point3 > &v, Array< Point3 > &vout) const
Point3	pointToWorldSpace (const Point3 &v) const
	Transforms the point into world space. More...
void	pointToWorldSpace (const Array< Point3 > &v, Array< Point3 > &vout) const
Vector3	rightVector () const
void	serialize (class BinaryOutput &b) const
Any	toAny () const
	Converts the CFrame to an Any. More...
class Matrix4	toMatrix4 () const
	See also Matrix4::approxCoordinateFrame. More...
CoordinateFrame	toObjectSpace (const CoordinateFrame &c) const
	Takes the coordinate frame into object space. More...
Vector4	toObjectSpace (const Vector4 &v) const
class Ray	toObjectSpace (const Ray &r) const
class Plane	toObjectSpace (const Plane &p) const
class Box	toObjectSpace (const AABox &b) const
class Sphere	toObjectSpace (const Sphere &b) const
class Box	toObjectSpace (const Box &b) const
Triangle	toObjectSpace (const Triangle &t) const
Vector4	toWorldSpace (const Vector4 &v) const
Ray	toWorldSpace (const Ray &r) const
Frustum	toWorldSpace (const Frustum &f) const
void	toWorldSpace (const class AABox &b, class AABox &result) const
class Sphere	toWorldSpace (const class Sphere &b) const
class Capsule	toWorldSpace (const class Capsule &b) const
class Box	toWorldSpace (const class AABox &b) const
class Cylinder	toWorldSpace (const class Cylinder &b) const
class Triangle	toWorldSpace (const class Triangle &t) const
class Plane	toWorldSpace (const class Plane &p) const
class Box	toWorldSpace (const class Box &b) const
String	toXML () const
	Produces an XML serialization of this coordinate frame. More...
String	toXYZYPRDegreesString () const
Vector3	upVector () const
	Up direction for this camera (its y axis). More...
Vector3	vectorToObjectSpace (const Vector3 &v) const
	Transforms the vector into object space (no translation). More...
void	vectorToObjectSpace (const Array< Vector3 > &v, Array< Vector3 > &vout) const
Vector3	vectorToWorldSpace (const Vector3 &v) const
	Transforms the vector into world space (no translation). More...
void	vectorToWorldSpace (const Array< Vector3 > &v, Array< Vector3 > &vout) const

Static Public Member Functions
static CoordinateFrame	fromXAxis (const Vector3 &X, const Point3 &origin=Point3::zero())
	Uses G3D::Vector3::getTangents to compute a reference frame from a x-axis and optional origin. More...
static CoordinateFrame	fromXYZYPRDegrees (float x, float y, float z, float yaw=0.0f, float pitch=0.0f, float roll=0.0f)
	Construct a coordinate frame from translation = (x,y,z) and rotations (in that order) about Y, object space X, object space Z. More...
static CoordinateFrame	fromXYZYPRRadians (float x, float y, float z, float yaw=0.0f, float pitch=0.0f, float roll=0.0f)
static CoordinateFrame	fromYAxis (const Vector3 &Y, const Point3 &origin=Point3::zero())
	Uses G3D::Vector3::getTangents to compute a reference frame from a y-axis and optional origin. More...
static CoordinateFrame	fromZAxis (const Vector3 &Z, const Point3 &origin=Point3::zero())
	Uses G3D::Vector3::getTangents to compute a reference frame from a z-axis and optional origin. More...

Public Attributes
Matrix3	rotation
	Takes object space points to world space. More...
Point3	translation
	The origin of this coordinate frame in world space (or its parent's space, if nested). More...

Detailed Description

A rigid body RT (rotation-translation) transformation.

CoordinateFrame abstracts a 4x4 matrix that maps object space to world space:

v_world = C * v_object

CoordinateFrame::rotation is the upper 3x3 submatrix, CoordinateFrame::translation is the right 3x1 column. The 4th row is always [0 0 0 1], so it isn't stored.
So you don't have to remember which way the multiplication and transformation work, it provides explicit toWorldSpace and toObjectSpace methods. Also, points, vectors (directions), and surface normals transform differently, so they have separate methods.

Some helper functions transform whole primitives like boxes in and out of object space.

Convert to Matrix4 using CoordinateFrame::toMatrix4. You can construct a CoordinateFrame from a Matrix4 using Matrix4::approxCoordinateFrame, however, because a Matrix4 is more general than a CoordinateFrame, some information may be lost.

See also

G3D::UprightFrame, G3D::PhysicsFrame, G3D::Matrix4, G3D::Quat

Constructor & Destructor Documentation

CoordinateFrame() [1/8]

G3D::CoordinateFrame::CoordinateFrame

(

const Any &

any

)

Parameters

any	Must be in one of the following forms: CFrame((matrix3 expr), (Point3 expr)) CFrame::fromXYZYPRDegrees(#, #, #, #, #, #) CFrame { rotation = (Matrix3 expr), translation = (Point3 expr) } Point3( ... ) Matrix3( ... )

CoordinateFrame() [2/8]

G3D::CoordinateFrame::CoordinateFrame

(

)

Initializes to the identity coordinate frame.

Referenced by operator*(), operator+(), and operator-().

CoordinateFrame() [3/8]

G3D::CoordinateFrame::CoordinateFrame ( const Point3 &  _translation )

inline

CoordinateFrame() [4/8]

G3D::CoordinateFrame::CoordinateFrame ( const Matrix3 &  rotation, const Point3 &  translation  )

inline

CoordinateFrame() [5/8]

G3D::CoordinateFrame::CoordinateFrame ( const Matrix3 &  rotation )

inline

CoordinateFrame() [6/8]

G3D::CoordinateFrame::CoordinateFrame

(

const class UprightFrame &

f

)

CoordinateFrame() [7/8]

G3D::CoordinateFrame::CoordinateFrame

(

class BinaryInput &

b

)

CoordinateFrame() [8/8]

G3D::CoordinateFrame::CoordinateFrame ( const CoordinateFrame &  other )

inline

~CoordinateFrame()

G3D::CoordinateFrame::~CoordinateFrame ( )

inline

Member Function Documentation

deserialize()

void G3D::CoordinateFrame::deserialize

(

class BinaryInput &

b

)

fromXAxis()

static CoordinateFrame G3D::CoordinateFrame::fromXAxis ( const Vector3 &  X, const Point3 &  origin = Point3::zero()  )

static

Uses G3D::Vector3::getTangents to compute a reference frame from a x-axis and optional origin.

fromXYZYPRDegrees()

static CoordinateFrame G3D::CoordinateFrame::fromXYZYPRDegrees ( float  x, float  y, float  z, float  yaw = 0.0f, float  pitch = 0.0f, float  roll = 0.0f  )

static

Construct a coordinate frame from translation = (x,y,z) and rotations (in that order) about Y, object space X, object space Z.

Note that because object-space axes are used, these are not equivalent to Euler angles; they are known as Tait-Bryan rotations and are more convenient for intuitive positioning.

fromXYZYPRRadians()

static CoordinateFrame G3D::CoordinateFrame::fromXYZYPRRadians ( float  x, float  y, float  z, float  yaw = 0.0f, float  pitch = 0.0f, float  roll = 0.0f  )

static

fromYAxis()

static CoordinateFrame G3D::CoordinateFrame::fromYAxis ( const Vector3 &  Y, const Point3 &  origin = Point3::zero()  )

static

Uses G3D::Vector3::getTangents to compute a reference frame from a y-axis and optional origin.

fromZAxis()

static CoordinateFrame G3D::CoordinateFrame::fromZAxis ( const Vector3 &  Z, const Point3 &  origin = Point3::zero()  )

static

Uses G3D::Vector3::getTangents to compute a reference frame from a z-axis and optional origin.

fuzzyEq()

bool G3D::CoordinateFrame::fuzzyEq

(

const CoordinateFrame &

other

)

const

fuzzyIsIdentity()

bool G3D::CoordinateFrame::fuzzyIsIdentity

(

)

const

getHeading()

float G3D::CoordinateFrame::getHeading ( ) const

inline

Returns the heading of the lookVector as an angle in radians relative to the world -z axis.

That is, a counter-clockwise heading where north (-z) is 0 and west (-x) is PI/2.

Note that the heading ignores the Y axis, so an inverted object has an inverted heading.

getXYZYPRDegrees()

void G3D::CoordinateFrame::getXYZYPRDegrees	(	float &	x,
		float &	y,
		float &	z,
		float &	yaw,
		float &	pitch,
		float &	roll
	)		const

getXYZYPRRadians()

void G3D::CoordinateFrame::getXYZYPRRadians	(	float &	x,
		float &	y,
		float &	z,
		float &	yaw,
		float &	pitch,
		float &	roll
	)		const

inverse()

CoordinateFrame G3D::CoordinateFrame::inverse ( ) const

inline

Computes the inverse of this coordinate frame.

Referenced by toObjectSpace().

isIdentity()

bool G3D::CoordinateFrame::isIdentity

(

)

const

leftVector()

Vector3 G3D::CoordinateFrame::leftVector ( ) const

inline

If a viewer looks along the look vector, this is the viewer's "left".

Useful for strafing motions and building alternative coordinate frames.

lerp()

CoordinateFrame G3D::CoordinateFrame::lerp	(	const CoordinateFrame &	other,
		float	alpha
	)		const

Linearly interpolates between two coordinate frames, using Quat::slerp for the rotations.

See also

moveTowards

lookAt() [1/2]

void G3D::CoordinateFrame::lookAt

(

const Point3 &

target

)

lookAt() [2/2]

void G3D::CoordinateFrame::lookAt	(	const Point3 &	target,
		Vector3	up
	)

lookRay()

class Ray G3D::CoordinateFrame::lookRay

(

)

const

Returns the ray starting at the camera origin travelling in direction CoordinateFrame::lookVector.

lookVector()

Vector3 G3D::CoordinateFrame::lookVector ( ) const

inline

The direction this camera is looking (its negative z axis)

Referenced by HashTrait< G3D::CoordinateFrame >::hashCode(), G3D::FirstPersonManipulator::lookVector(), and G3D::Light::position().

moveTowards()

void G3D::CoordinateFrame::moveTowards	(	const CoordinateFrame &	goal,
		float	maxTranslation,
		float	maxRotation
	)

Transform this coordinate frame towards goal, but not past it, goverened by maximum rotation and translations.

This is a useful alternative to lerp, especially if the goal is expected to change every transformation step so that constant start and end positions will not be available.

Parameters

goal	Step from this towards goal
maxTranslation	Meters
maxRotation	Radians

See also

lerp

normalToObjectSpace() [1/2]

Vector3 G3D::CoordinateFrame::normalToObjectSpace ( const Vector3 &  v ) const

inline

normalToObjectSpace() [2/2]

void G3D::CoordinateFrame::normalToObjectSpace	(	const Array< Vector3 > &	v,
		Array< Vector3 > &	vout
	)		const

normalToWorldSpace() [1/2]

Vector3 G3D::CoordinateFrame::normalToWorldSpace ( const Vector3 &  v ) const

inline

normalToWorldSpace() [2/2]

void G3D::CoordinateFrame::normalToWorldSpace	(	const Array< Vector3 > &	v,
		Array< Vector3 > &	vout
	)		const

operator!=()

bool G3D::CoordinateFrame::operator!= ( const CoordinateFrame &  other ) const

inline

operator*()

CoordinateFrame G3D::CoordinateFrame::operator* ( const CoordinateFrame &  other ) const

inline

Compose: create the transformation that is other followed by this.

operator+()

CoordinateFrame G3D::CoordinateFrame::operator+ ( const Vector3 &  v ) const

inline

operator-()

CoordinateFrame G3D::CoordinateFrame::operator- ( const Vector3 &  v ) const

inline

operator==()

bool G3D::CoordinateFrame::operator== ( const CoordinateFrame &  other ) const

inline

pointToObjectSpace() [1/2]

Point3 G3D::CoordinateFrame::pointToObjectSpace ( const Point3 &  v ) const

inline

Transforms the point into object space.

Assumes that the rotation matrix is orthonormal.

pointToObjectSpace() [2/2]

void G3D::CoordinateFrame::pointToObjectSpace	(	const Array< Point3 > &	v,
		Array< Point3 > &	vout
	)		const

pointToWorldSpace() [1/2]

Point3 G3D::CoordinateFrame::pointToWorldSpace ( const Point3 &  v ) const

inline

Transforms the point into world space.

Referenced by operator*(), and G3D::Light::position().

pointToWorldSpace() [2/2]

void G3D::CoordinateFrame::pointToWorldSpace	(	const Array< Point3 > &	v,
		Array< Point3 > &	vout
	)		const

rightVector()

Vector3 G3D::CoordinateFrame::rightVector ( ) const

inline

Referenced by HashTrait< G3D::CoordinateFrame >::hashCode().

serialize()

void G3D::CoordinateFrame::serialize

(

class BinaryOutput &

b

)

const

toAny()

Any G3D::CoordinateFrame::toAny

(

)

const

Converts the CFrame to an Any.

toMatrix4()

class Matrix4 G3D::CoordinateFrame::toMatrix4

(

)

const

See also Matrix4::approxCoordinateFrame.

toObjectSpace() [1/8]

CoordinateFrame G3D::CoordinateFrame::toObjectSpace ( const CoordinateFrame &  c ) const

inline

Takes the coordinate frame into object space.

this->inverse() * c

toObjectSpace() [2/8]

Vector4 G3D::CoordinateFrame::toObjectSpace ( const Vector4 &  v ) const

inline

toObjectSpace() [3/8]

class Ray G3D::CoordinateFrame::toObjectSpace

(

const Ray &

r

)

const

toObjectSpace() [4/8]

class Box G3D::CoordinateFrame::toObjectSpace

(

const AABox &

b

)

const

toObjectSpace() [5/8]

class Plane G3D::CoordinateFrame::toObjectSpace

(

const Plane &

p

)

const

toObjectSpace() [6/8]

class Sphere G3D::CoordinateFrame::toObjectSpace

(

const Sphere &

b

)

const

toObjectSpace() [7/8]

class Box G3D::CoordinateFrame::toObjectSpace

(

const Box &

b

)

const

toObjectSpace() [8/8]

Triangle G3D::CoordinateFrame::toObjectSpace

(

const Triangle &

t

)

const

toWorldSpace() [1/11]

Vector4 G3D::CoordinateFrame::toWorldSpace ( const Vector4 &  v ) const

inline

Referenced by toObjectSpace().

toWorldSpace() [2/11]

Ray G3D::CoordinateFrame::toWorldSpace

(

const Ray &

r

)

const

toWorldSpace() [3/11]

Frustum G3D::CoordinateFrame::toWorldSpace

(

const Frustum &

f

)

const

toWorldSpace() [4/11]

class Capsule G3D::CoordinateFrame::toWorldSpace

(

const class Capsule &

b

)

const

toWorldSpace() [5/11]

class Box G3D::CoordinateFrame::toWorldSpace

(

const class AABox &

b

)

const

toWorldSpace() [6/11]

class Plane G3D::CoordinateFrame::toWorldSpace

(

const class Plane &

p

)

const

toWorldSpace() [7/11]

class Sphere G3D::CoordinateFrame::toWorldSpace

(

const class Sphere &

b

)

const

toWorldSpace() [8/11]

class Box G3D::CoordinateFrame::toWorldSpace

(

const class Box &

b

)

const

toWorldSpace() [9/11]

class Triangle G3D::CoordinateFrame::toWorldSpace

(

const class Triangle &

t

)

const

toWorldSpace() [10/11]

class Cylinder G3D::CoordinateFrame::toWorldSpace

(

const class Cylinder &

b

)

const

toWorldSpace() [11/11]

void G3D::CoordinateFrame::toWorldSpace	(	const class AABox &	b,
		class AABox &	result
	)		const

toXML()

String G3D::CoordinateFrame::toXML

(

)

const

Produces an XML serialization of this coordinate frame.

Deprecated:

toXYZYPRDegreesString()

String G3D::CoordinateFrame::toXYZYPRDegreesString

(

)

const

upVector()

Vector3 G3D::CoordinateFrame::upVector ( ) const

inline

Up direction for this camera (its y axis).

vectorToObjectSpace() [1/2]

Vector3 G3D::CoordinateFrame::vectorToObjectSpace ( const Vector3 &  v ) const

inline

Transforms the vector into object space (no translation).

vectorToObjectSpace() [2/2]

void G3D::CoordinateFrame::vectorToObjectSpace	(	const Array< Vector3 > &	v,
		Array< Vector3 > &	vout
	)		const

vectorToWorldSpace() [1/2]

Vector3 G3D::CoordinateFrame::vectorToWorldSpace ( const Vector3 &  v ) const

inline

Transforms the vector into world space (no translation).

vectorToWorldSpace() [2/2]

void G3D::CoordinateFrame::vectorToWorldSpace	(	const Array< Vector3 > &	v,
		Array< Vector3 > &	vout
	)		const

Member Data Documentation

rotation

Matrix3 G3D::CoordinateFrame::rotation

Takes object space points to world space.

Referenced by getHeading(), inverse(), leftVector(), lookVector(), normalToObjectSpace(), normalToWorldSpace(), operator*(), operator+(), operator-(), operator==(), pointToObjectSpace(), pointToWorldSpace(), rightVector(), toWorldSpace(), upVector(), vectorToObjectSpace(), and vectorToWorldSpace().

translation

Point3 G3D::CoordinateFrame::translation

The origin of this coordinate frame in world space (or its parent's space, if nested).

Referenced by G3D::AxesShape::boundingSphere(), G3D::AxesShape::center(), G3D::Light::distance(), G3D::AxesShape::getRandomSurfacePoint(), HashTrait< G3D::CoordinateFrame >::hashCode(), inverse(), operator*(), operator+(), operator-(), operator==(), pointToObjectSpace(), pointToWorldSpace(), G3D::Light::position(), G3D::AxesShape::randomInteriorPoint(), and toWorldSpace().