qglviewer::Camera Class Reference

#include <QGLViewer/camera.h>

Inheritance diagram for qglviewer::Camera:

[legend]

Collaboration diagram for qglviewer::Camera:

[legend]

Detailed Description

A perspective or orthographic camera.

A Camera defines some intrinsic parameters (fieldOfView(), position(), viewDirection(), upVector()...) and useful positioning tools that ease its placement (showEntireScene(), fitSphere(), lookAt()...). It exports its associated OpenGL projection and modelview matrices and can interactively be modified using the mouse.

Mouse manipulation

The position() and orientation() of the Camera are defined by a ManipulatedCameraFrame (retrieved using frame()). These methods are just convenient wrappers to the equivalent Frame methods. This also means that the Camera frame() can be attached to a Frame::referenceFrame() which enables complex Camera setups.

Different displacements can be performed using the mouse. The list of possible actions is defined by the QGLViewer::MouseAction enum. Use QGLViewer::setMouseBinding() to attach a specific action to an arbitrary mouse button-state key binding. These actions are detailed in the mouse page.

The default button binding are: QGLViewer::ROTATE (left), QGLViewer::ZOOM (middle) and QGLViewer::TRANSLATE (right). With this configuration, the Camera observes a scene and rotates around its revolveAroundPoint(). You can switch between this mode and a fly mode using the QGLViewer::CAMERA_MODE (see QGLViewer::toggleCameraMode()) keyboard shortcut (default is 'Space').

Other functionalities

The type() of the Camera can be Camera::ORTHOGRAPHIC or Camera::PERSPECTIVE (see Type()). fieldOfView() is meaningless with Camera::ORTHOGRAPHIC.

The near and far planes of the Camera are fitted to the scene and determined from QGLViewer::sceneRadius(), QGLViewer::sceneCenter() and zClippingCoefficient() by the zNear() and zFar() methods. Reasonable values on the scene extends hence have to be provided to the QGLViewer in order for the Camera to correctly display the scene. High level positioning methods also use this information (showEntireScene(), centerScene()...).

A Camera holds KeyFrameInterpolator that can be used to save Camera positions and paths. You can interactively addKeyFrameToPath() to a given path using the default Alt+F[1-12] shortcuts. Use playPath() to make the Camera follow the path (default shortcut is F[1-12]). See the keyboard page for details on key customization.

Use cameraCoordinatesOf() and worldCoordinatesOf() to convert to and from the Camera frame() coordinate system. projectedCoordinatesOf() and unprojectedCoordinatesOf() will convert from screen to 3D coordinates. convertClickToLine() is very useful for analytical object selection.

Stereo display is possible on machines with quad buffer capabilities (with Camera::PERSPECTIVE type() only). Test the stereoViewer example to check.

A Camera can also be used outside of a QGLViewer or even without OpenGL for its coordinate system conversion capabilities. Note however that some of them explicitly rely on the presence of a Z-buffer.

Definition at line 84 of file camera.h.


Position and orientation

Vec	position () const
Vec	upVector () const
Vec	viewDirection () const
Vec	rightVector () const
Quaternion	orientation () const
void	setFromModelViewMatrix (const GLdouble *const modelViewMatrix)
void	setFromProjectionMatrix (const float matrix[12])
void	setPosition (const Vec &pos)
void	setOrientation (const Quaternion &q)
void	setOrientation (float theta, float phi)
void	setUpVector (const Vec &up, bool noMove=true)
void	setViewDirection (const Vec &direction)
Frustum

Type	type () const
float	fieldOfView () const
float	horizontalFieldOfView () const
float	aspectRatio () const
int	screenWidth () const
int	screenHeight () const
void	getViewport (GLint viewport[4]) const
float	pixelGLRatio (const Vec &position) const
float	zNearCoefficient () const
float	zClippingCoefficient () const
virtual float	zNear () const
virtual float	zFar () const
virtual void	getOrthoWidthHeight (GLdouble &halfWidth, GLdouble &halfHeight) const
void	getFrustumPlanesCoefficients (GLdouble coef[6][4]) const
void	setType (Type type)
void	setFieldOfView (float fov)
void	setHorizontalFieldOfView (float hfov)
void	setFOVToFitScene ()
void	setAspectRatio (float aspect)
void	setScreenWidthAndHeight (int width, int height)
void	setZNearCoefficient (float coef)
void	setZClippingCoefficient (float coef)
Scene radius and center

float	sceneRadius () const
Vec	sceneCenter () const
float	distanceToSceneCenter () const
void	setSceneRadius (float radius)
void	setSceneCenter (const Vec &center)
bool	setSceneCenterFromPixel (const QPoint &pixel)
void	setSceneBoundingBox (const Vec &min, const Vec &max)
Revolve Around Point

Vec	revolveAroundPoint () const
void	setRevolveAroundPoint (const Vec &rap)
bool	setRevolveAroundPointFromPixel (const QPoint &pixel)
Associated frame

ManipulatedCameraFrame *	frame () const
void	setFrame (ManipulatedCameraFrame *const mcf)
KeyFramed paths

KeyFrameInterpolator *	keyFrameInterpolator (int i) const
void	setKeyFrameInterpolator (int i, KeyFrameInterpolator *const kfi)
virtual void	addKeyFrameToPath (int i)
virtual void	playPath (int i)
virtual void	deletePath (int i)
virtual void	resetPath (int i)
virtual void	drawAllPaths ()
OpenGL matrices

virtual void	loadProjectionMatrix (bool reset=true) const
virtual void	loadModelViewMatrix (bool reset=true) const
void	computeProjectionMatrix () const
void	computeModelViewMatrix () const
virtual void	loadProjectionMatrixStereo (bool leftBuffer=true) const
virtual void	loadModelViewMatrixStereo (bool leftBuffer=true) const
void	getProjectionMatrix (GLdouble m[16]) const
void	getModelViewMatrix (GLdouble m[16]) const
void	getModelViewProjectionMatrix (GLdouble m[16]) const
void	getProjectionMatrix (GLfloat m[16]) const
void	getModelViewMatrix (GLfloat m[16]) const
Drawing

virtual void	draw (bool drawFarPlane=true, float scale=1.0) const
static void	drawCamera (float scale=1.0, float aspectRatio=1.33, float fieldOfView=M_PI/4.0)
World to Camera coordinate systems conversions

Vec	cameraCoordinatesOf (const Vec &src) const
Vec	worldCoordinatesOf (const Vec &src) const
void	getCameraCoordinatesOf (const float src[3], float res[3]) const
void	getWorldCoordinatesOf (const float src[3], float res[3]) const
2D screen to 3D world coordinate systems conversions

Vec	projectedCoordinatesOf (const Vec &src, const Frame *frame=NULL) const
Vec	unprojectedCoordinatesOf (const Vec &src, const Frame *frame=NULL) const
void	getProjectedCoordinatesOf (const float src[3], float res[3], const Frame *frame=NULL) const
void	getUnprojectedCoordinatesOf (const float src[3], float res[3], const Frame *frame=NULL) const
void	convertClickToLine (const QPoint &pixel, Vec &orig, Vec &dir) const
Vec	pointUnderPixel (const QPoint &pixel, bool &found) const
Fly speed

float	flySpeed () const
void	setFlySpeed (float speed)
Stereo parameters

float	IODistance () const
float	physicalDistanceToScreen () const
float	physicalScreenWidth () const
float	focusDistance () const
void	setIODistance (float distance)
void	setPhysicalDistanceToScreen (float distance)
void	setPhysicalScreenWidth (float width)
void	setFocusDistance (float distance)
XML representation

virtual QDomElement	domElement (const QString &name, QDomDocument &document) const
virtual void	initFromDOMElement (const QDomElement &element)
Positioning tools

void	lookAt (const Vec &target)
void	showEntireScene ()
void	fitSphere (const Vec &center, float radius)
void	fitBoundingBox (const Vec &min, const Vec &max)
void	fitScreenRegion (const QRect &rectangle)
void	centerScene ()
void	interpolateToZoomOnPixel (const QPoint &pixel)
void	interpolateToFitScene ()
void	interpolateTo (const Frame &fr, float duration)
Public Types
enum	Type { PERSPECTIVE, ORTHOGRAPHIC }
Public Member Functions
	Camera ()
virtual	~Camera ()
	Camera (const Camera &camera)
Camera &	operator= (const Camera &camera)
Private Attributes
ManipulatedCameraFrame *	frame_
int	screenWidth_
int	screenHeight_
float	fieldOfView_
Vec	sceneCenter_
float	sceneRadius_
float	zNearCoef_
float	zClippingCoef_
float	orthoCoef_
Type	type_
GLdouble	modelViewMatrix_ [16]
GLdouble	projectionMatrix_ [16]
float	IODistance_
float	focusDistance_
float	physicalDistanceToScreen_
float	physicalScreenWidth_
QMap< int, KeyFrameInterpolator * >	kfi_
KeyFrameInterpolator *	interpolationKfi_
Friends
class	::QGLViewer

Member Enumeration Documentation

enum qglviewer::Camera::Type

Enumerates the two possible types of Camera.

See type() and setType(). This type mainly defines different Camera projection matrix (see loadProjectionMatrix()). Many other methods (pointUnderPixel(), convertClickToLine(), projectedCoordinatesOf(), pixelGLRatio()...) take this Type into account.

Enumerator:

PERSPECTIVE
ORTHOGRAPHIC

Definition at line 105 of file camera.h.

Constructor & Destructor Documentation

Camera::Camera ( )

Default constructor.

sceneCenter() is set to (0,0,0) and sceneRadius() is set to 1.0. type() is Camera::PERSPECTIVE, with a M_PI/4 fieldOfView().

See IODistance(), physicalDistanceToScreen(), physicalScreenWidth() and focusDistance() documentations for default stereo parameter values.

Definition at line 40 of file camera.cpp.

References computeProjectionMatrix(), fieldOfView(), interpolationKfi_, modelViewMatrix_, orthoCoef_, PERSPECTIVE, projectionMatrix_, setFrame(), setIODistance(), setPhysicalDistanceToScreen(), setPhysicalScreenWidth(), setSceneCenter(), setSceneRadius(), setScreenWidthAndHeight(), setType(), setZClippingCoefficient(), and setZNearCoefficient().

Camera::~Camera ( ) [virtual]

Virtual destructor.

The frame() is deleted, but the different keyFrameInterpolator() are not deleted (in case they are shared).

Definition at line 89 of file camera.cpp.

References frame_, and interpolationKfi_.

Camera::Camera ( const Camera & camera )

Copy constructor. Performs a deep copy using operator=().

Definition at line 97 of file camera.cpp.

References interpolationKfi_, modelViewMatrix_, projectionMatrix_, and setFrame().

Member Function Documentation

Camera & Camera::operator= ( const Camera & camera )

Equal operator.

All the parameters of camera are copied. The frame() pointer is not modified, but its Frame::position() and Frame::orientation() are set to those of camera.

Attention:

The Camera screenWidth() and screenHeight() are set to those of camera. If your Camera is associated with a QGLViewer, you should update these value after the call to this method:

 *(camera()) = otherCamera;
 camera()->setScreenWidthAndHeight(width(), height());

The same applies to sceneCenter() and sceneRadius(), if needed.

Definition at line 127 of file camera.cpp.

References computeModelViewMatrix(), computeProjectionMatrix(), fieldOfView(), focusDistance(), frame_, interpolationKfi_, IODistance(), kfi_, orientation(), orthoCoef_, physicalDistanceToScreen(), physicalScreenWidth(), position(), qglviewer::KeyFrameInterpolator::resetInterpolation(), sceneCenter(), sceneRadius(), screenHeight(), screenWidth(), setFieldOfView(), setFocusDistance(), setIODistance(), qglviewer::Frame::setOrientation(), setPhysicalDistanceToScreen(), setPhysicalScreenWidth(), qglviewer::Frame::setPosition(), qglviewer::Frame::setReferenceFrame(), setSceneCenter(), setSceneRadius(), setScreenWidthAndHeight(), setType(), setZClippingCoefficient(), setZNearCoefficient(), type(), zClippingCoefficient(), and zNearCoefficient().

Vec qglviewer::Camera::position ( ) const [inline]

Returns the Camera position (the eye), defined in the world coordinate system.

Use setPosition() to set the Camera position. Other convenient methods are showEntireScene() or fitSphere(). Actually returns frame()->position().

This position corresponds to the projection center of a Camera::PERSPECTIVE Camera. It is not located in the image plane, which is at a zNear() distance ahead.

Definition at line 117 of file camera.h.

Referenced by computeModelViewMatrix(), convertClickToLine(), getFrustumPlanesCoefficients(), interpolateToFitScene(), interpolateToZoomOnPixel(), lookAt(), qglviewer::ManipulatedFrame::mouseDoubleClickEvent(), qglviewer::ManipulatedFrame::mouseMoveEvent(), operator=(), sofa::gui::qt::viewer::qgl::QtGLViewer::saveView(), and qglviewer::ManipulatedFrame::wheelEvent().

Vec qglviewer::Camera::upVector ( ) const [inline]

Returns the normalized up vector of the Camera, defined in the world coordinate system.

Set using setUpVector() or setOrientation(). It is orthogonal to viewDirection() and to rightVector().

It corresponds to the Y axis of the associated frame() (actually returns frame()->inverseTransformOf(Vec(0.0, 1.0, 0.0)) ).

Definition at line 126 of file camera.h.

Referenced by getFrustumPlanesCoefficients(), and setViewDirection().

Vec qglviewer::Camera::viewDirection ( ) const [inline]

Returns the normalized view direction of the Camera, defined in the world coordinate system.

Change this value using setViewDirection(), lookAt() or setOrientation(). It is orthogonal to upVector() and to rightVector().

This corresponds to the negative Z axis of the frame() ( frame()->inverseTransformOf(Vec(0.0, 0.0, -1.0)) ).

Definition at line 137 of file camera.h.

Referenced by centerScene(), convertClickToLine(), fitScreenRegion(), fitSphere(), getFrustumPlanesCoefficients(), and qglviewer::ManipulatedFrame::mouseDoubleClickEvent().

Vec qglviewer::Camera::rightVector ( ) const [inline]

Returns the normalized right vector of the Camera, defined in the world coordinate system.

This vector lies in the Camera horizontal plane, directed along the X axis (orthogonal to upVector() and to viewDirection()). Set using setUpVector(), lookAt() or setOrientation().

Simply returns frame()->inverseTransformOf(Vec(1.0, 0.0, 0.0)).

Definition at line 145 of file camera.h.

Referenced by getFrustumPlanesCoefficients().

Quaternion qglviewer::Camera::orientation ( ) const [inline]

Returns the Camera orientation, defined in the world coordinate system.

Actually returns frame()->orientation(). Use setOrientation(), setUpVector() or lookAt() to set the Camera orientation.

Definition at line 154 of file camera.h.

Referenced by interpolateToFitScene(), interpolateToZoomOnPixel(), operator=(), sofa::gui::qt::viewer::qgl::QtGLViewer::saveView(), and setUpVector().

void Camera::setFromModelViewMatrix ( const GLdouble *const modelViewMatrix )

Sets the Camera's position() and orientation() from an OpenGL ModelView matrix.

This enables a Camera initialisation from an other OpenGL application. modelView is a 16 GLdouble vector representing a valid OpenGL ModelView matrix, such as one can get using:

GLdouble mvm[16];
glGetDoublev(GL_MODELVIEW_MATRIX, mvm);
myCamera->setFromModelViewMatrix(mvm);

After this method has been called, getModelViewMatrix() returns a matrix equivalent to modelView.

Only the orientation() and position() of the Camera are modified.

Note:: If you defined your matrix as GLdouble mvm[4][4], pass &(mvm[0][0]) as a parameter.

Definition at line 1149 of file camera.cpp.

References qglviewer::Quaternion::rotate(), qglviewer::Quaternion::setFromRotationMatrix(), setOrientation(), and setPosition().

void Camera::setFromProjectionMatrix ( const float matrix[12] )

Defines the Camera position(), orientation() and fieldOfView() from a projection matrix.

matrix has to be given in the format used by vision algorithm. It has 3 lines and 4 columns. It transforms a point from the world homogeneous coordinate system (4 coordinates: sx, sy, sz and s) into a point in the screen homogeneous coordinate system (3 coordinates: sx, sy, and s, where x and y are the pixel coordinates on the screen).

Its three lines correspond to the homogeneous coordinates of the normals to the planes x=0, y=0 and z=0, defined in the Camera coordinate system.

The elements of the matrix are ordered in line major order: you can call setFromProjectionMatrix(&(matrix[0][0])) if you defined your matrix as a float matrix[3][4].

Attention:: Passing the result of getProjectionMatrix() or getModelViewMatrix() to this method is not possible (purposefully incompatible matrix dimensions). matrix is more likely to be the product of these two matrices, without the last line.

Use setFromModelViewMatrix() to set position() and orientation() from a GL_MODELVIEW matrix. fieldOfView() can also be retrieved from a perspective GL_PROJECTION matrix using 2.0 * atan(1.0/projectionMatrix[5]).

This code was written by Sylvain Paris.

Definition at line 1187 of file camera.cpp.

References det(), ind(), qglviewer::Vec::normalize(), setFieldOfView(), qglviewer::Quaternion::setFromRotationMatrix(), setOrientation(), and setPosition().

void qglviewer::Camera::setPosition ( const Vec & pos ) [inline, slot]

Sets the Camera position() (the eye), defined in the world coordinate system.

Definition at line 161 of file camera.h.

Referenced by sofa::gui::qt::viewer::qgl::QtGLViewer::resetView(), setFromModelViewMatrix(), setFromProjectionMatrix(), sofa::gui::qt::viewer::qgl::QtGLViewer::SwitchToAutomateView(), and sofa::gui::qt::viewer::qgl::QtGLViewer::viewAll().

void Camera::setOrientation ( const Quaternion & q ) [slot]

Sets the Camera orientation(), defined in the world coordinate system.

Definition at line 1088 of file camera.cpp.

References frame(), qglviewer::Frame::setOrientation(), and qglviewer::ManipulatedCameraFrame::updateFlyUpVector().

Referenced by sofa::gui::qt::viewer::qgl::QtGLViewer::resetView(), setFromModelViewMatrix(), setFromProjectionMatrix(), setOrientation(), and sofa::gui::qt::viewer::qgl::QtGLViewer::SwitchToAutomateView().

void Camera::setOrientation	(	float	theta,
		float	phi
	)			`[slot]`

Sets the orientation() of the Camera using polar coordinates.

theta rotates the Camera around its Y axis, and then phi rotates it around its X axis. The polar coordinates are defined in the world coordinates system: theta = phi = 0 means that the Camera is directed towards the world Z axis. Both angles are expressed in radians.

See also setUpVector(). The position() of the Camera is unchanged, you may want to call showEntireScene() after this method to move the Camera.

This method can be useful to create Quicktime VR panoramic sequences, see the QGLViewer::saveSnapshot() documentation for details.

Definition at line 1078 of file camera.cpp.

References setOrientation().

void Camera::setUpVector	(	const Vec &	up,
		bool	noMove = `true`
	)			`[slot]`

Rotates the Camera so that its upVector() becomes up (defined in the world coordinate system).

The Camera is rotated around an axis orthogonal to up and to the current upVector() direction. Use this method in order to define the Camera horizontal plane.

When noMove is set to false, the orientation modification is compensated by a translation, so that the revolveAroundPoint() stays projected at the same position on screen. This is especially useful when the Camera is an observer of the scene (default mouse binding).

When noMove is true (default), the Camera position() is left unchanged, which is an intuitive behavior when the Camera is in a walkthrough fly mode (see the QGLViewer::MOVE_FORWARD and QGLViewer::MOVE_BACKWARD QGLViewer::MouseAction).

Definition at line 1054 of file camera.cpp.

References frame(), orientation(), revolveAroundPoint(), qglviewer::Frame::rotate(), qglviewer::Frame::setPosition(), and qglviewer::ManipulatedCameraFrame::updateFlyUpVector().

void Camera::setViewDirection ( const Vec & direction ) [slot]

Rotates the Camera so that its viewDirection() is direction (defined in the world coordinate system).

The Camera position() is not modified. The Camera is rotated so that the horizon (defined by its upVector()) is preserved. See also lookAt() and setUpVector().

Definition at line 1099 of file camera.cpp.

References frame(), qglviewer::Frame::inverseTransformOf(), qglviewer::Quaternion::setFromRotatedBasis(), qglviewer::Frame::setOrientationWithConstraint(), qglviewer::Vec::squaredNorm(), and upVector().

Referenced by lookAt().

void Camera::lookAt ( const Vec & target ) [slot]

Sets the Camera orientation(), so that it looks at point target (defined in the world coordinate system).

The Camera position() is not modified. Simply setViewDirection().

Definition at line 950 of file camera.cpp.

References position(), and setViewDirection().

Referenced by interpolateToZoomOnPixel().

void Camera::showEntireScene ( ) [slot]

Moves the Camera so that the entire scene is visible.

Simply calls fitSphere() on a sphere defined by sceneCenter() and sceneRadius().

You will typically use this method in QGLViewer::init() after you defined a new sceneRadius().

Definition at line 929 of file camera.cpp.

References fitSphere(), sceneCenter(), and sceneRadius().

Referenced by interpolateToFitScene(), QGLViewer::performClickAction(), sofa::gui::qt::viewer::qgl::QtGLViewer::resetView(), and sofa::gui::qt::viewer::qgl::QtGLViewer::viewAll().

void Camera::fitSphere	(	const Vec &	center,
		float	radius
	)			`[slot]`

Moves the Camera so that the sphere defined by (center, radius) is visible and fits the window.

The Camera is simply translated along its viewDirection() so that the sphere fits the screen. Its orientation() and its fieldOfView() are unchanged.

You should therefore orientate the Camera before you call this method. See lookAt(), setOrientation() and setUpVector().

Definition at line 962 of file camera.cpp.

References fieldOfView(), frame(), horizontalFieldOfView(), orthoCoef_, ORTHOGRAPHIC, PERSPECTIVE, qMax, revolveAroundPoint(), qglviewer::Frame::setPositionWithConstraint(), type(), and viewDirection().

Referenced by fitBoundingBox(), and showEntireScene().

void Camera::fitBoundingBox	(	const Vec &	min,
		const Vec &	max
	)			`[slot]`

Moves the Camera so that the (world axis aligned) bounding box (min, max) is entirely visible, using fitSphere().

Definition at line 986 of file camera.cpp.

References fitSphere(), and qMax.

void Camera::fitScreenRegion ( const QRect & rectangle ) [slot]

Moves the Camera so that the rectangular screen region defined by rectangle (pixel units, with origin in the upper left corner) fits the screen.

The Camera is translated (its orientation() is unchanged) so that rectangle is entirely visible. Since the pixel coordinates only define a frustum in 3D, it's the intersection of this frustum with a plane (orthogonal to the viewDirection() and passing through the sceneCenter()) that is used to define the 3D rectangle that is eventually fitted.

Definition at line 1000 of file camera.cpp.

References aspectRatio(), convertClickToLine(), distanceToSceneCenter(), fieldOfView(), frame(), horizontalFieldOfView(), norm(), orthoCoef_, ORTHOGRAPHIC, PERSPECTIVE, qMax, revolveAroundPoint(), qglviewer::Frame::setPositionWithConstraint(), type(), and viewDirection().

Referenced by qglviewer::ManipulatedCameraFrame::mouseReleaseEvent().

void Camera::centerScene ( ) [slot]

Moves the Camera so that its sceneCenter() is projected on the center of the window. The orientation() and fieldOfView() are unchanged.

Simply projects the current position on a line passing through sceneCenter(). See also showEntireScene().

Definition at line 939 of file camera.cpp.

References frame(), qglviewer::Frame::projectOnLine(), sceneCenter(), and viewDirection().

Referenced by QGLViewer::performClickAction().

void Camera::interpolateToZoomOnPixel ( const QPoint & pixel ) [slot]

Makes the Camera smoothly zoom on the pointUnderPixel() pixel.

Nothing happens if no pointUnderPixel() is found. Otherwise a KeyFrameInterpolator is created that animates the Camera on a one second path that brings the Camera closer to the point under pixel.

void Camera::interpolateTo	(	const Frame &	fr,
		float	duration
	)			`[slot]`

qglviewer::Camera Class Reference

Detailed Description

Mouse manipulation

Other functionalities

Position and orientation

Frustum

Scene radius and center

Revolve Around Point

Associated frame

KeyFramed paths

OpenGL matrices

Drawing

World to Camera coordinate systems conversions

2D screen to 3D world coordinate systems conversions

Fly speed

Stereo parameters

XML representation

Positioning tools

Public Types

Public Member Functions

Private Attributes

Friends

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation