Camera class provides object-oriented approach to setting up projection and orientation properties of 3D view. More...

#include <Graphic3d_Camera.hxx>

Inheritance diagram for Graphic3d_Camera:

Public Types
enum	Projection { Projection_Orthographic, Projection_Perspective, Projection_Stereo, Projection_MonoLeftEye, Projection_MonoRightEye }
	Enumerates supported monographic projections. More...

enum	FocusType { FocusType_Absolute, FocusType_Relative }
	Enumerates approaches to define stereographic focus. More...

enum	IODType { IODType_Absolute, IODType_Relative }
	Enumerates approaches to define Intraocular distance. More...

Public Member Functions
	Graphic3d_Camera ()
	Default constructor. Initializes camera with the following properties: Eye (0, 0, -2); Center (0, 0, 0); Up (0, 1, 0); Type (Orthographic); FOVy (45); Scale (1000); IsStereo(false); ZNear (0.001); ZFar (3000.0); Aspect(1); ZFocus(1.0); ZFocusType(Relative); IOD(0.05); IODType(Relative) More...

	Graphic3d_Camera (const Handle< Graphic3d_Camera > &theOther)
	Copy constructor. More...

void	CopyMappingData (const Handle< Graphic3d_Camera > &theOtherCamera)
	Initialize mapping related parameters from other camera handle. More...

void	CopyOrientationData (const Handle< Graphic3d_Camera > &theOtherCamera)
	Initialize orientation related parameters from other camera handle. More...

void	Copy (const Handle< Graphic3d_Camera > &theOther)
	Copy properties of another camera. More...

Public camera properties
void	SetEye (const gp_Pnt &theEye)
	Sets camera Eye position. More...

const gp_Pnt &	Eye () const
	Get camera Eye position. More...

void	SetCenter (const gp_Pnt &theCenter)
	Sets Center of the camera. More...

const gp_Pnt &	Center () const
	Get Center of the camera. More...

void	SetUp (const gp_Dir &theUp)
	Sets camera Up direction vector, orthogonal to camera direction. More...

void	OrthogonalizeUp ()
	Orthogonalize up direction vector. More...

gp_Dir	OrthogonalizedUp () const
	Return a copy of orthogonalized up direction vector. More...

const gp_Dir &	Up () const
	Get camera Up direction vector. More...

void	SetAxialScale (const gp_XYZ &theAxialScale)
	Set camera axial scale. More...

const gp_XYZ &	AxialScale () const
	Get camera axial scale. More...

void	SetDistance (const Standard_Real theDistance)
	Set distance of Eye from camera Center. More...

Standard_Real	Distance () const
	Get distance of Eye from camera Center. More...

void	SetDirection (const gp_Dir &theDir)
	Sets camera look direction. More...

gp_Dir	Direction () const
	Get camera look direction. More...

void	SetScale (const Standard_Real theScale)
	Sets camera scale. For orthographic projection the scale factor corresponds to parallel scale of view mapping (i.e. size of viewport). For perspective camera scale is converted to distance. The scale specifies equal size of the view projection in both dimensions assuming that the aspect is 1.0. The projection height and width are specified with the scale and correspondingly multiplied by the aspect. More...

Standard_Real	Scale () const
	Get camera scale. More...

void	SetProjectionType (const Projection theProjection)
	Change camera projection type. When switching to perspective projection from orthographic one, the ZNear and ZFar are reset to default values (0.001, 3000.0) if less than 0.0. More...

Projection	ProjectionType () const

Standard_Boolean	IsOrthographic () const
	Check that the camera projection is orthographic. More...

Standard_Boolean	IsStereo () const
	Check whether the camera projection is stereo. Please note that stereo rendering is now implemented with support of Quad buffering. More...

void	SetFOVy (const Standard_Real theFOVy)
	Set Field Of View (FOV) in y axis for perspective projection. More...

Standard_Real	FOVy () const
	Get Field Of View (FOV) in y axis. More...

void	ZFitAll (const Standard_Real theScaleFactor, const Bnd_Box &theMinMax, const Bnd_Box &theGraphicBB)
	Change Z-min and Z-max planes of projection volume to match the displayed objects. The methods ensures that view volume will be close by depth range to the displayed objects. Fitting assumes that for orthogonal projection the view volume contains the displayed objects completely. For zoomed perspective view, the view volume is adjusted such that it contains the objects or their parts, located in front of the camera. More...

void	SetZRange (const Standard_Real theZNear, const Standard_Real theZFar)
	Change the Near and Far Z-clipping plane positions. For orthographic projection, theZNear, theZFar can be negative or positive. For perspective projection, only positive values are allowed. Program error exception is raised if non-positive values are specified for perspective projection or theZNear >= theZFar. More...

Standard_Real	ZNear () const
	Get the Near Z-clipping plane position. More...

Standard_Real	ZFar () const
	Get the Far Z-clipping plane position. More...

void	SetAspect (const Standard_Real theAspect)
	Changes width / height display ratio. More...

Standard_Real	Aspect () const
	Get camera display ratio. More...

void	SetZFocus (const FocusType theType, const Standard_Real theZFocus)
	Sets stereographic focus distance. More...

Standard_Real	ZFocus () const
	Get stereographic focus value. More...

FocusType	ZFocusType () const
	Get stereographic focus definition type. More...

void	SetIOD (const IODType theType, const Standard_Real theIOD)
	Sets Intraocular distance. More...

Standard_Real	IOD () const
	Get Intraocular distance value. More...

IODType	GetIODType () const
	Get Intraocular distance definition type. More...

Basic camera operations
void	Transform (const gp_Trsf &theTrsf)
	Transform orientation components of the camera: Eye, Up and Center points. More...

gp_XYZ	ViewDimensions () const
	Calculate view plane size at center (target) point and distance between ZFar and ZNear planes. More...

void	Frustum (gp_Pln &theLeft, gp_Pln &theRight, gp_Pln &theBottom, gp_Pln &theTop, gp_Pln &theNear, gp_Pln &theFar) const
	Calculate WCS frustum planes for the camera projection volume. Frustum is a convex volume determined by six planes directing inwards. The frustum planes are usually used as inputs for camera algorithms. Thus, if any changes to projection matrix calculation are necessary, the frustum planes calculation should be also touched. More...

Projection methods
gp_Pnt	Project (const gp_Pnt &thePnt) const
	Project point from world coordinate space to normalized device coordinates (mapping). More...

gp_Pnt	UnProject (const gp_Pnt &thePnt) const
	Unproject point from normalized device coordinates to world coordinate space. More...

gp_Pnt	ConvertView2Proj (const gp_Pnt &thePnt) const
	Convert point from view coordinate space to projection coordinate space. More...

gp_Pnt	ConvertProj2View (const gp_Pnt &thePnt) const
	Convert point from projection coordinate space to view coordinate space. More...

gp_Pnt	ConvertWorld2View (const gp_Pnt &thePnt) const
	Convert point from world coordinate space to view coordinate space. More...

gp_Pnt	ConvertView2World (const gp_Pnt &thePnt) const
	Convert point from view coordinate space to world coordinates. More...

Camera modification state
Standard_Size	ProjectionState () const
	Returns modification state of camera projection matrix. More...

Standard_Size	ModelViewState () const
	Returns modification state of camera model-view matrix. More...

Lazily-computed orientation and projection matrices derived from camera parameters
const Graphic3d_Mat4d &	OrientationMatrix () const
	Get orientation matrix. More...

const Graphic3d_Mat4 &	OrientationMatrixF () const
	Get orientation matrix of Standard_ShortReal precision. More...

const Graphic3d_Mat4d &	ProjectionMatrix () const
	Get monographic or middle point projection matrix used for monographic rendering and for point projection / unprojection. More...

const Graphic3d_Mat4 &	ProjectionMatrixF () const
	Get monographic or middle point projection matrix of Standard_ShortReal precision used for monographic rendering and for point projection / unprojection. More...

const Graphic3d_Mat4d &	ProjectionStereoLeft () const

const Graphic3d_Mat4 &	ProjectionStereoLeftF () const

const Graphic3d_Mat4d &	ProjectionStereoRight () const

const Graphic3d_Mat4 &	ProjectionStereoRightF () const

void	InvalidateProjection ()
	Invalidate state of projection matrix. The matrix will be updated on request. More...

void	InvalidateOrientation ()
	Invalidate orientation matrix. The matrix will be updated on request. More...

Public Member Functions inherited from Standard_Transient
	Standard_Transient ()
	Empty constructor. More...

	Standard_Transient (const Standard_Transient &)
	Copy constructor – does nothing. More...

Standard_Transient &	operator= (const Standard_Transient &)
	Assignment operator, needed to avoid copying reference counter. More...

virtual	~Standard_Transient ()
	Destructor must be virtual. More...

virtual void	Delete () const
	Memory deallocator for transient classes. More...

virtual const Handle_Standard_Type &	DynamicType () const
	Returns a type information object about this object. More...

Standard_Boolean	IsInstance (const Handle_Standard_Type &theType) const
	Returns a true value if this is an instance of Type. More...

Standard_Boolean	IsInstance (const Standard_CString theTypeName) const
	Returns a true value if this is an instance of TypeName. More...

Standard_Boolean	IsKind (const Handle_Standard_Type &theType) const
	Returns true if this is an instance of Type or an instance of any class that inherits from Type. Note that multiple inheritance is not supported by OCCT RTTI mechanism. More...

Standard_Boolean	IsKind (const Standard_CString theTypeName) const
	Returns true if this is an instance of TypeName or an instance of any class that inherits from TypeName. Note that multiple inheritance is not supported by OCCT RTTI mechanism. More...

virtual Handle_Standard_Transient	This () const
	Returns a Handle which references this object. Must never be called to objects created in stack. More...

Standard_Integer	GetRefCount () const
	Get the reference counter of this object. More...

Managing projection and orientation cache
	DEFINE_STANDARD_RTTI (Graphic3d_Camera)
	Camera up direction vector. More...

Detailed Description

Camera class provides object-oriented approach to setting up projection and orientation properties of 3D view.

Member Enumeration Documentation

enum Graphic3d_Camera::FocusType

Enumerates approaches to define stereographic focus.

FocusType_Absolute : focus is specified as absolute value.
FocusType_Relative : focus is specified relative to (as coefficient of) camera focal length.

Enumerator
FocusType_Absolute
FocusType_Relative

enum Graphic3d_Camera::IODType

Enumerates approaches to define Intraocular distance.

IODType_Absolute : Intraocular distance is defined as absolute value.
IODType_Relative : Intraocular distance is defined relative to (as coefficient of) camera focal length.

Enumerator
IODType_Absolute
IODType_Relative

enum Graphic3d_Camera::Projection

Enumerates supported monographic projections.

Projection_Orthographic : orthographic projection.
Projection_Perspective : perspective projection.
Projection_Stereo : stereographic projection.
Projection_MonoLeftEye : mono projection for stereo left eye.
Projection_MonoRightEye : mono projection for stereo right eye.

Enumerator
Projection_Orthographic
Projection_Perspective
Projection_Stereo
Projection_MonoLeftEye
Projection_MonoRightEye

Constructor & Destructor Documentation

Graphic3d_Camera::Graphic3d_Camera ( )

Default constructor. Initializes camera with the following properties: Eye (0, 0, -2); Center (0, 0, 0); Up (0, 1, 0); Type (Orthographic); FOVy (45); Scale (1000); IsStereo(false); ZNear (0.001); ZFar (3000.0); Aspect(1); ZFocus(1.0); ZFocusType(Relative); IOD(0.05); IODType(Relative)

Graphic3d_Camera::Graphic3d_Camera ( const Handle< Graphic3d_Camera > & theOther )

Copy constructor.

Parameters

theOther [in] the camera to copy from.

Member Function Documentation

Standard_Real Graphic3d_Camera::Aspect ( ) const

inline

Get camera display ratio.

Returns: display ratio.

const gp_XYZ& Graphic3d_Camera::AxialScale ( ) const

inline

Get camera axial scale.

Returns: Camera's axial scale.

const gp_Pnt& Graphic3d_Camera::Center ( ) const

inline

Get Center of the camera.

Returns: the point where the camera looks at.

gp_Pnt Graphic3d_Camera::ConvertProj2View ( const gp_Pnt & thePnt ) const

Convert point from projection coordinate space to view coordinate space.

Parameters

thePnt [in] the point in NDC.

Returns: point in VCS.

gp_Pnt Graphic3d_Camera::ConvertView2Proj ( const gp_Pnt & thePnt ) const

Convert point from view coordinate space to projection coordinate space.

Parameters

thePnt [in] the point in VCS.

Returns: point in NDC.

gp_Pnt Graphic3d_Camera::ConvertView2World ( const gp_Pnt & thePnt ) const

Convert point from view coordinate space to world coordinates.

Parameters

thePnt [in] the 3D point in VCS.

Returns: point in WCS.

gp_Pnt Graphic3d_Camera::ConvertWorld2View ( const gp_Pnt & thePnt ) const

Convert point from world coordinate space to view coordinate space.

Parameters

thePnt [in] the 3D point in WCS.

Returns: point in VCS.

void Graphic3d_Camera::Copy ( const Handle< Graphic3d_Camera > & theOther )

Copy properties of another camera.

Parameters

theOther [in] the camera to copy from.

void Graphic3d_Camera::CopyMappingData ( const Handle< Graphic3d_Camera > & theOtherCamera )

Initialize mapping related parameters from other camera handle.

void Graphic3d_Camera::CopyOrientationData ( const Handle< Graphic3d_Camera > & theOtherCamera )

Initialize orientation related parameters from other camera handle.

Graphic3d_Camera::DEFINE_STANDARD_RTTI ( Graphic3d_Camera )

Camera up direction vector.

gp_Dir Graphic3d_Camera::Direction ( ) const

Get camera look direction.

Returns: camera look direction.

Standard_Real Graphic3d_Camera::Distance ( ) const

Get distance of Eye from camera Center.

Returns: the distance.

const gp_Pnt& Graphic3d_Camera::Eye ( ) const

inline

Get camera Eye position.

Returns: camera eye location.

Standard_Real Graphic3d_Camera::FOVy ( ) const

inline

Get Field Of View (FOV) in y axis.

Returns: the FOV value in degrees.

void Graphic3d_Camera::Frustum	(	gp_Pln &	theLeft,
		gp_Pln &	theRight,
		gp_Pln &	theBottom,
		gp_Pln &	theTop,
		gp_Pln &	theNear,
		gp_Pln &	theFar
	)		const

Calculate WCS frustum planes for the camera projection volume. Frustum is a convex volume determined by six planes directing inwards. The frustum planes are usually used as inputs for camera algorithms. Thus, if any changes to projection matrix calculation are necessary, the frustum planes calculation should be also touched.

Parameters

theLeft	[out] the frustum plane for left side of view.
theRight	[out] the frustum plane for right side of view.
theBottom	[out] the frustum plane for bottom side of view.
theTop	[out] the frustum plane for top side of view.
theNear	[out] the frustum plane for near side of view.
theFar	[out] the frustum plane for far side of view.

IODType Graphic3d_Camera::GetIODType ( ) const

inline

Get Intraocular distance definition type.

Returns: definition type used for Intraocular distance.

void Graphic3d_Camera::InvalidateOrientation ( )

Invalidate orientation matrix. The matrix will be updated on request.

void Graphic3d_Camera::InvalidateProjection ( )

Invalidate state of projection matrix. The matrix will be updated on request.

Standard_Real Graphic3d_Camera::IOD ( ) const

inline

Get Intraocular distance value.

Returns: absolute or relative IOD value depending on its definition type.

Standard_Boolean Graphic3d_Camera::IsOrthographic ( ) const

inline

Check that the camera projection is orthographic.

Returns: boolean flag that indicates whether the camera's projection is orthographic or not.

Standard_Boolean Graphic3d_Camera::IsStereo ( ) const

inline

Check whether the camera projection is stereo. Please note that stereo rendering is now implemented with support of Quad buffering.

Returns: boolean flag indicating whether the stereographic L/R projection is chosen.

Standard_Size Graphic3d_Camera::ModelViewState ( ) const

inline

Returns modification state of camera model-view matrix.

const Graphic3d_Mat4d& Graphic3d_Camera::OrientationMatrix ( ) const

Get orientation matrix.

Returns: camera orientation matrix.

const Graphic3d_Mat4& Graphic3d_Camera::OrientationMatrixF ( ) const

Get orientation matrix of Standard_ShortReal precision.

Returns: camera orientation matrix.

gp_Dir Graphic3d_Camera::OrthogonalizedUp ( ) const

Return a copy of orthogonalized up direction vector.

void Graphic3d_Camera::OrthogonalizeUp ( )

Orthogonalize up direction vector.

gp_Pnt Graphic3d_Camera::Project ( const gp_Pnt & thePnt ) const

Project point from world coordinate space to normalized device coordinates (mapping).

Parameters

thePnt [in] the 3D point in WCS.

Returns: mapped point in NDC.

const Graphic3d_Mat4d& Graphic3d_Camera::ProjectionMatrix ( ) const

Get monographic or middle point projection matrix used for monographic rendering and for point projection / unprojection.

Returns: monographic projection matrix.

const Graphic3d_Mat4& Graphic3d_Camera::ProjectionMatrixF ( ) const

Get monographic or middle point projection matrix of Standard_ShortReal precision used for monographic rendering and for point projection / unprojection.

Returns: monographic projection matrix.

Standard_Size Graphic3d_Camera::ProjectionState ( ) const

inline

Returns modification state of camera projection matrix.

const Graphic3d_Mat4d& Graphic3d_Camera::ProjectionStereoLeft ( ) const

Returns: stereographic matrix computed for left eye. Please note that this method is used for rendering for Projection_Stereo.

const Graphic3d_Mat4& Graphic3d_Camera::ProjectionStereoLeftF ( ) const

Returns: stereographic matrix of Standard_ShortReal precision computed for left eye. Please note that this method is used for rendering for Projection_Stereo.

const Graphic3d_Mat4d& Graphic3d_Camera::ProjectionStereoRight ( ) const

Returns: stereographic matrix computed for right eye. Please note that this method is used for rendering for Projection_Stereo.

const Graphic3d_Mat4& Graphic3d_Camera::ProjectionStereoRightF ( ) const

Returns: stereographic matrix of Standard_ShortReal precision computed for right eye. Please note that this method is used for rendering for Projection_Stereo.

Projection Graphic3d_Camera::ProjectionType ( ) const

inline

Returns: camera projection type.

Standard_Real Graphic3d_Camera::Scale ( ) const

Get camera scale.

Returns: camera scale factor.

void Graphic3d_Camera::SetAspect ( const Standard_Real theAspect )

Changes width / height display ratio.

Parameters

theAspect [in] the display ratio.

void Graphic3d_Camera::SetAxialScale ( const gp_XYZ & theAxialScale )

Set camera axial scale.

Parameters

theAxialScale [in] the axial scale vector.

void Graphic3d_Camera::SetCenter ( const gp_Pnt & theCenter )

Sets Center of the camera.

Parameters

theCenter [in] the point where the camera looks at.

void Graphic3d_Camera::SetDirection ( const gp_Dir & theDir )

Sets camera look direction.

Parameters

theDir [in] the direction.

void Graphic3d_Camera::SetDistance ( const Standard_Real theDistance )

Set distance of Eye from camera Center.

Parameters

theDistance [in] the distance.

void Graphic3d_Camera::SetEye ( const gp_Pnt & theEye )

Sets camera Eye position.

Parameters

theEye [in] the location of camera's Eye.

void Graphic3d_Camera::SetFOVy ( const Standard_Real theFOVy )

Set Field Of View (FOV) in y axis for perspective projection.

Parameters

theFOVy [in] the FOV in degrees.

void Graphic3d_Camera::SetIOD	(	const IODType	theType,
		const Standard_Real	theIOD
	)

Sets Intraocular distance.

Parameters

theType	[in] the IOD definition type. IOD can be defined as absolute value or relatively to (as coefficient of) camera focal length.
theIOD	[in] the Intraocular distance.

void Graphic3d_Camera::SetProjectionType ( const Projection theProjection )

Change camera projection type. When switching to perspective projection from orthographic one, the ZNear and ZFar are reset to default values (0.001, 3000.0) if less than 0.0.

Parameters

theProjectionType [in] the camera projection type.

void Graphic3d_Camera::SetScale ( const Standard_Real theScale )

Sets camera scale. For orthographic projection the scale factor corresponds to parallel scale of view mapping (i.e. size of viewport). For perspective camera scale is converted to distance. The scale specifies equal size of the view projection in both dimensions assuming that the aspect is 1.0. The projection height and width are specified with the scale and correspondingly multiplied by the aspect.

Parameters

theScale [in] the scale factor.

void Graphic3d_Camera::SetUp ( const gp_Dir & theUp )

Sets camera Up direction vector, orthogonal to camera direction.

Parameters

theUp [in] the Up direction vector.

void Graphic3d_Camera::SetZFocus	(	const FocusType	theType,
		const Standard_Real	theZFocus
	)

Sets stereographic focus distance.

Parameters

theType	[in] the focus definition type. Focus can be defined as absolute value or relatively to (as coefficient of) coefficient of camera focal length.
theZFocus	[in] the focus absolute value or coefficient depending on the passed definition type.

void Graphic3d_Camera::SetZRange	(	const Standard_Real	theZNear,
		const Standard_Real	theZFar
	)

Change the Near and Far Z-clipping plane positions. For orthographic projection, theZNear, theZFar can be negative or positive. For perspective projection, only positive values are allowed. Program error exception is raised if non-positive values are specified for perspective projection or theZNear >= theZFar.

Parameters

theZNear	[in] the distance of the plane from the Eye.
theZFar	[in] the distance of the plane from the Eye.

void Graphic3d_Camera::Transform ( const gp_Trsf & theTrsf )

Transform orientation components of the camera: Eye, Up and Center points.

Parameters

theTrsf [in] the transformation to apply.

gp_Pnt Graphic3d_Camera::UnProject ( const gp_Pnt & thePnt ) const

Unproject point from normalized device coordinates to world coordinate space.

Parameters

thePnt [in] the NDC point.

Returns: 3D point in WCS.

const gp_Dir& Graphic3d_Camera::Up ( ) const

inline

Get camera Up direction vector.

Returns: Camera's Up direction vector.

gp_XYZ Graphic3d_Camera::ViewDimensions ( ) const

Calculate view plane size at center (target) point and distance between ZFar and ZNear planes.

Returns: values in form of gp_Pnt (Width, Height, Depth).

Standard_Real Graphic3d_Camera::ZFar ( ) const

inline

Get the Far Z-clipping plane position.

Returns: the distance of the plane from the Eye.

void Graphic3d_Camera::ZFitAll	(	const Standard_Real	theScaleFactor,
		const Bnd_Box &	theMinMax,
		const Bnd_Box &	theGraphicBB
	)

Change Z-min and Z-max planes of projection volume to match the displayed objects. The methods ensures that view volume will be close by depth range to the displayed objects. Fitting assumes that for orthogonal projection the view volume contains the displayed objects completely. For zoomed perspective view, the view volume is adjusted such that it contains the objects or their parts, located in front of the camera.

Parameters

theScaleFactor	[in] the scale factor for Z-range. The range between Z-min, Z-max projection volume planes evaluated by z fitting method will be scaled using this coefficient. Program error exception is thrown if negative or zero value is passed.
theMinMax	[in] applicative min max boundaries.
theScaleFactor	[in] real graphical boundaries (not accounting infinite flag).

Standard_Real Graphic3d_Camera::ZFocus ( ) const

inline

Get stereographic focus value.

Returns: absolute or relative stereographic focus value depending on its definition type.

FocusType Graphic3d_Camera::ZFocusType ( ) const

inline

Get stereographic focus definition type.

Returns: definition type used for stereographic focus.

Standard_Real Graphic3d_Camera::ZNear ( ) const

inline

Get the Near Z-clipping plane position.

Returns: the distance of the plane from the Eye.

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

Graphic3d_Camera.hxx

Public Types

Public Member Functions

Managing projection and orientation cache

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation