Camera Class Reference

A perspective or orthographic camera. More...

#include <easy3d/renderer/camera.h>

Public Types
enum	Type { PERSPECTIVE , ORTHOGRAPHIC }
	Enumerates the two possible types of Camera. More...

Public Member Functions
	Camera ()
virtual	~Camera ()
	Camera (const Camera &camera)
	Copy constructor. More...
Camera &	operator= (const Camera &camera)
Position and orientation
vec3	position () const
vec3	upVector () const
vec3	viewDirection () const
vec3	rightVector () const
quat	orientation () const
void	set_from_model_view_matrix (const mat4 &mv) const
	Sets the Camera's position() and orientation() from an OpenGL ModelView matrix. More...
void	set_from_calibration (float fx, float fy, float skew, float cx, float cy, const mat3 &R, const vec3 &t, bool convert=true)
	Defines the position(), orientation() and fieldOfView() of the camera from calibrated camera intrinsic and extrinsic parameters. This is an overload of set_from_calibration(). More...
void	set_from_calibration (const mat34 &proj)
	Defines the position(), orientation() and fieldOfView() of the camera from calibrated camera intrinsic and extrinsic parameters. This is an overload of set_from_calibration(). More...
void	set_projection_matrix (const mat4 &proj)
	Temporally change the projection matrix. More...
void	set_modelview_matrix (const mat4 &mv)
	Temporally change the modelview matrix. More...
void	setPosition (const vec3 &pos) const
void	setOrientation (const quat &q) const
void	setOrientation (float theta, float phi) const
void	setUpVector (const vec3 &up, bool noMove=true) const
void	setViewDirection (const vec3 &direction) const
Positioning tools
void	lookAt (const vec3 &target) const
void	showEntireScene () const
void	fitSphere (const vec3 &center, float radius) const
void	fitBoundingBox (const vec3 &min, const vec3 &max) const
void	fitScreenRegion (int xmin, int ymin, int xmax, int ymax) const
	Moves the Camera so that the rectangular screen region fits the screen. More...
void	centerScene () const
KeyFrameInterpolator *	keyframe_interpolator () const
	Return the keyframe interpolator.
void	interpolateToLookAt (const vec3 &point)
	Perform keyframe interpolation to look at point. More...
void	interpolateToFitScene ()
	Perform keyframe interpolation to fit the scene bounding box. More...
void	interpolateTo (const Frame &frame, float duration)
	Perform keyframe interpolation to frame, done in duration second. More...
Type	type () const
	Returns the Camera::Type of the Camera. Set by setType(). Mainly used by loadProjectionMatrix(). More...
float	fieldOfView () const
	Returns the vertical field of view of the Camera (in radians). More...
float	horizontalFieldOfView () const
	Returns the horizontal field of view of the Camera (in radians). More...
float	aspectRatio () const
	Returns the Camera aspect ratio defined by screenWidth() / screenHeight(). More...
int	screenWidth () const
	Returns the width (in pixels) of the Camera screen. More...
int	screenHeight () const
	Returns the height (in pixels) of the Camera screen. More...
float	pixelGLRatio (const vec3 &position) const
float	zNearCoefficient () const
	Returns the coefficient which is used to set zNear() when the Camera is inside the sphere defined by sceneCenter() and zClippingCoefficient() * sceneRadius(). More...
float	zClippingCoefficient () const
	Returns the coefficient used to position the near and far clipping planes. More...
virtual float	zNear () const
virtual float	zFar () const
virtual void	getOrthoWidthHeight (float &halfWidth, float &halfHeight) const
void	getFrustumPlanesCoefficients (float coef[6][4]) const
void	getFrustumPlanesCoefficients2 (float coef[6][4]) const
	Return the 6 plane equations of the Camera frustum. More...
void	setType (Type type)
void	setFieldOfView (float fov)
void	setHorizontalFieldOfView (float hfov)
	Sets the horizontalFieldOfView() of the Camera (in radians). More...
void	setFOVToFitScene ()
void	setAspectRatio (float aspect)
	Defines the Camera aspectRatio(). More...
void	setScreenWidthAndHeight (int width, int height)
void	setZNearCoefficient (float coef)
	Sets the zNearCoefficient() value.
void	setZClippingCoefficient (float coef)
	Sets the zClippingCoefficient() value.
Scene radius and center
float	sceneRadius () const
	Returns the radius of the scene observed by the Camera. More...
vec3	sceneCenter () const
	Returns the position of the scene center, defined in the world coordinate system. More...
float	distanceToSceneCenter () const
void	setSceneRadius (float radius)
void	setSceneCenter (const vec3 &center)
void	setSceneBoundingBox (const vec3 &min, const vec3 &max)
void	setPivotPoint (const vec3 &point)
vec3	pivotPoint () const
ManipulatedCameraFrame *	frame () const
	Returns the ManipulatedFrame attached to the Camera. More...
void	setFrame (ManipulatedCameraFrame *const mcf)
void	computeProjectionMatrix ()
void	computeModelViewMatrix ()
const mat4 &	projectionMatrix () const
const mat4 &	modelViewMatrix () const
mat4	modelViewProjectionMatrix () const
World to Camera coordinate systems conversions
vec3	cameraCoordinatesOf (const vec3 &src) const
vec3	worldCoordinatesOf (const vec3 &src) const

2D screen to 3D world coordinate systems conversions
Signal	frame_modified
	A signal indicating the frame has been modified.
vec3	projectedCoordinatesOf (const vec3 &src, const Frame *frame=nullptr) const
vec3	unprojectedCoordinatesOf (const vec3 &src, const Frame *frame=nullptr) const
void	convertClickToLine (int x, int y, vec3 &orig, vec3 &dir) const

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 ManipulatedFrame (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.

If a pivotPoint() has been set, the Camera observes a scene and rotates around its pivotPoint().

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 scene radius, scene center, and zClippingCoefficient() by the zNear() and zFar() methods. Reasonable values on the scene extends hence have to be provided to 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. Use playPath() to make the Camera follow the path.

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.

A Camera can also be used outside of a viewer 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.

To use the camera, you need to do the following:

• Create and (if necessary) setup camera in the constructor of your viewer.

  camera_ = new Camera;
  camera_->setType(Camera::PERSPECTIVE);
  camera_->setUpVector(vec3(0, 0, 1));        // Z pointing up
  camera_->setViewDirection(vec3(-1, 0, 0));  // X pointing out
  camera_->showEntireScene();                 // position and orient the camera
  camera_->connect(this, &Viewer::update);    // connect the viewer's update function

• Call camera_->setScreenWidthAndHeight() at both
  • creation or initialization (i.e., before the viewer appears) of the application;
  • change of the window size.
• Call camera_->frame()->action_start() on mouse down and camera_->frame()->action_end() on mouse up.
• Call camera_->frame()->action_rotate() on mouse move for rotation and camera_->frame()->action_translate() on mouse move for translation and camera_->frame()->action_zoom() on mouse move for zoom

To make the entire scene visible, call camera_->setSceneBoundingBox() and camera_->showEntireScene() ;

To retrieve the model view projection matrix, call camera_->modelViewProjectionMatrix()

Examples

Tutorial_204_Viewer_Qt, and Tutorial_207_RealCamera.

Member Enumeration Documentation

Type

enum 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 (convertClickToLine(), projectedCoordinatesOf(), pixelGLRatio()...) are affected by this Type.

Constructor & Destructor Documentation

Camera() [1/2]

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.

~Camera()

~Camera ( )

virtual

Virtual destructor.

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

Camera() [2/2]

Camera

(

const Camera &

camera

)

Copy constructor.

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

Member Function Documentation

aspectRatio()

float aspectRatio ( ) const

inline

Returns the Camera aspect ratio defined by screenWidth() / screenHeight().

When the Camera is attached to a Viewer, these values and hence the aspectRatio() are automatically fitted to the viewer's window aspect ratio using setScreenWidthAndHeight().

cameraCoordinatesOf()

vec3 cameraCoordinatesOf

(

const vec3 &

src

)

const

Returns the Camera frame coordinates of a point src defined in world coordinates.

worldCoordinatesOf() performs the inverse transformation.

Note that the point coordinates are simply converted in a different coordinate system. They are not projected on screen. Use projectedCoordinatesOf() for that.

centerScene()

void centerScene

(

)

const

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().

computeModelViewMatrix()

void computeModelViewMatrix

(

)

Computes the modelView matrix associated with the Camera's position() and orientation().

This matrix converts from the world coordinates system to the Camera coordinates system, so that coordinates can then be projected on screen using the projection matrix (see computeProjectionMatrix()).

Use getModelViewMatrix() to retrieve this matrix.

Note

You must call this method if your Camera is not associated with a Viewer and is used for offscreen computations (using (un)projectedCoordinatesOf() for instance). loadModelViewMatrix() does it otherwise.

computeProjectionMatrix()

void computeProjectionMatrix

(

)

Computes the projection matrix associated with the Camera.

If type() is Camera::PERSPECTIVE, defines a GL_PROJECTION matrix similar to what would gluPerspective() do using the fieldOfView(), window aspectRatio(), zNear() and zFar() parameters.

If type() is Camera::ORTHOGRAPHIC, the projection matrix is as what glOrtho() would do. Frustum's width and height are set using getOrthoWidthHeight().

Both types use zNear() and zFar() to place clipping planes. These values are determined from sceneRadius() and sceneCenter() so that they best fit the scene size.

Use getProjectionMatrix() to retrieve this matrix. Overload loadProjectionMatrix() if you want your Camera to use an exotic projection matrix.

Note

You must call this method if your Camera is not associated with a Viewer and is used for off screen computations (using (un)projectedCoordinatesOf() for instance). loadProjectionMatrix() does it otherwise.

convertClickToLine()

void convertClickToLine	(	int	x,
		int	y,
		vec3 &	orig,
		vec3 &	dir
	)		const

Gives the coefficients of a 3D half-line passing through the Camera eye and pixel (x,y).

The origin of the half line (eye position) is stored in orig, while dir contains the properly oriented and normalized direction of the half line.

x and y are expressed in Qt format (origin in the upper left corner). Use screenHeight() - y to convert to OpenGL units.

This method is useful for analytical intersection in a selection method.

See the select example for an illustration.

distanceToSceneCenter()

float distanceToSceneCenter

(

)

const

Returns the distance from the Camera center to sceneCenter(), projected along the Camera Z axis. Used by zNear() and zFar() to optimize the Z range.

fieldOfView()

float fieldOfView ( ) const

inline

Returns the vertical field of view of the Camera (in radians).

Value is set using setFieldOfView(). Default value is pi/4 radians. This value is meaningless if the Camera type() is Camera::ORTHOGRAPHIC. The field of view corresponds the one used in gluPerspective (see manual). It sets the Y (vertical) aperture of the Camera. The X (horizontal) angle is inferred from the window aspect ratio (see aspectRatio() and horizontalFieldOfView()). Use setFOVToFitScene() to adapt the fieldOfView() to a given scene.

Examples

Tutorial_207_RealCamera.

fitBoundingBox()

void fitBoundingBox	(	const vec3 &	min,
		const vec3 &	max
	)		const

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

fitScreenRegion()

void fitScreenRegion	(	int	xmin,
		int	ymin,
		int	xmax,
		int	ymax
	)		const

Moves the Camera so that the rectangular screen region fits the screen.

The rectangular screen region is defined in pixel units, with origin in the upper left corner. 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.

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.

Examples

Tutorial_204_Viewer_Qt.

fitSphere()

void fitSphere	(	const vec3 &	center,
		float	radius
	)		const

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

The Camera is simply translated to center the sphere in the screen and make it fit the frustum. Its orientation() and its fieldOfView() are unchanged.

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

frame()

ManipulatedCameraFrame * frame ( ) const

inline

Returns the ManipulatedFrame attached to the Camera.

This ManipulatedFrame defines its position() and orientation() and can translate mouse events into Camera displacement. Set using setFrame().

Examples

Tutorial_203_Viewer_wxWidgets, Tutorial_204_Viewer_Qt, and Tutorial_207_RealCamera.

getFrustumPlanesCoefficients()

void getFrustumPlanesCoefficients

(

float

coef[6][4]

)

const

Returns the 6 plane equations of the Camera frustum.

The six 4-component vectors of coef respectively correspond to the left, right, near, far, top and bottom Camera frustum planes. Each vector holds a plane equation of the form:

a*x + b*y + c*z + d = 0 

where a, b, c and d are the 4 components of each vector, in that order.

See the frustumCulling example for an application.

This format is compatible with the glClipPlane() function. One camera frustum plane can hence be applied in an other viewer to visualize the culling results:

// Retrieve plane equations
double coef[6][4];
mainViewer->camera()->getFrustumPlanesCoefficients(coef);
 
// These two additional clipping planes (which must have been enabled)
// will reproduce the mainViewer's near and far clipping.
glClipPlane(GL_CLIP_PLANE0, coef[2]);
glClipPlane(GL_CLIP_PLANE1, coef[3]);

getFrustumPlanesCoefficients2()

void getFrustumPlanesCoefficients2

(

float

frustum[6][4]

)

const

Return the 6 plane equations of the Camera frustum.

Returns the 6 plane equations of the Camera frustum. This is another implementation of getFrustumPlanesCoefficients(...).

getOrthoWidthHeight()

void getOrthoWidthHeight ( float &  halfWidth, float &  halfHeight  ) const

virtual

Returns the halfWidth and halfHeight of the Camera orthographic frustum.

These values are only valid and used when the Camera is of type() Camera::ORTHOGRAPHIC. They are expressed in OpenGL units and are used by loadProjectionMatrix() to define the projection matrix using:

 glOrtho(
-halfWidth, halfWidth, -halfHeight, halfHeight, zNear(), zFar() ) 

These values are proportional to the Camera (z projected) distance to the pivotPoint(). When zooming on the object, the Camera is translated forward and its frustum is narrowed, making the object appear bigger on screen, as intuitively expected.

Overload this method to change this behavior if desired, as is done in the standardCamera example.

horizontalFieldOfView()

float horizontalFieldOfView ( ) const

inline

Returns the horizontal field of view of the Camera (in radians).

Value is set using setHorizontalFieldOfView() or setFieldOfView(). These values are always linked by:

horizontalFieldOfView() = 2.0 * std::atan( std::tan(fieldOfView()/2.0) * aspectRatio() ).

interpolateTo()

void interpolateTo	(	const Frame &	fr,
		float	duration
	)

Perform keyframe interpolation to frame, done in duration second.

Smoothly interpolates the Camera on a KeyFrameInterpolator path so that it goes to fr.

fr is expressed in world coordinates. duration tunes the interpolation speed (default is 1 second).

See also interpolateToFitScene() and interpolateToZoomOnPixel().

interpolateToFitScene()

void interpolateToFitScene

(

)

Perform keyframe interpolation to fit the scene bounding box.

Interpolates the Camera on a one second KeyFrameInterpolator path so that the entire scene fits the screen at the end.

The scene is defined by its sceneCenter() and its sceneRadius(). See showEntireScene().

The orientation() of the Camera is not modified. See also interpolateToZoomOnPixel().

Examples

Tutorial_204_Viewer_Qt.

interpolateToLookAt()

void interpolateToLookAt

(

const vec3 &

p

)

Perform keyframe interpolation to look at point.

Makes the Camera smoothly zoom on a visible 3D point p. See also interpolateToFitScene().

Examples

Tutorial_204_Viewer_Qt.

lookAt()

void lookAt

(

const vec3 &

target

)

const

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().

See also setUpVector(), setOrientation(), showEntireScene(), fitSphere() and fitBoundingBox().

modelViewMatrix()

const mat4 & modelViewMatrix

(

)

const

Fills m with the Camera modelView matrix values.

First calls computeModelViewMatrix() to define the Camera modelView matrix.

Note that this matrix may not be the one you would get from a glGetDoublev(GL_MODELVIEW_MATRIX, m). It actually represents the state of the GL_MODELVIEW after Viewer::preDraw(), at the beginning of Viewer::draw(). It converts from the world to the Camera coordinate system. As soon as you modify the GL_MODELVIEW in your Viewer::draw() method (using glTranslate, glRotate... or similar methods), the two matrices differ.

The result is an OpenGL 4x4 matrix, which is given in column-major order (see glMultMatrix man page for details).

See also getProjectionMatrix() and setFromModelViewMatrix().

Examples

Tutorial_203_Viewer_wxWidgets, and Tutorial_204_Viewer_Qt.

modelViewProjectionMatrix()

mat4 modelViewProjectionMatrix

(

)

const

Fills m with the product of the ModelView and Projection matrices.

Calls getModelViewMatrix() and getProjectionMatrix() and then fills m with the product of these two matrices.

operator=()

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 Viewer, 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.

orientation()

quat orientation

(

)

const

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

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

Examples

Tutorial_203_Viewer_wxWidgets, and Tutorial_204_Viewer_Qt.

pivotPoint()

vec3 pivotPoint

(

)

const

The point the Camera pivots around with the Viewer::ROTATE mouse binding. Defined in world coordinate system.

Default value is the sceneCenter().

Attention

setSceneCenter() changes this value.

Examples

Tutorial_203_Viewer_wxWidgets, and Tutorial_204_Viewer_Qt.

pixelGLRatio()

float pixelGLRatio

(

const vec3 &

position

)

const

Returns the ratio between pixel and OpenGL units at position.

A line of n * pixelGLRatio() OpenGL units, located at position in the world coordinates system, will be projected with a length of n pixels on screen.

Use this method to scale objects so that they have a constant pixel size on screen. The following code will draw a 20 pixel line, starting at sceneCenter() and always directed along the screen vertical direction:

glBegin(GL_LINES);
glVertex3fv(sceneCenter());
glVertex3fv(sceneCenter() + 20 * pixelGLRatio(sceneCenter()) *
camera()->upVector()); glEnd(); 

position()

vec3 position

(

)

const

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.

Examples

Tutorial_203_Viewer_wxWidgets, and Tutorial_204_Viewer_Qt.

projectedCoordinatesOf()

vec3 projectedCoordinatesOf	(	const vec3 &	src,
		const Frame *	frame = nullptr
	)		const

Returns the screen projected coordinates of a 3D point src defined in the frame coordinate system.

When frame in NULL (default), src is expressed in the world coordinate system.

The x and y coordinates of the returned vec3 are expressed in pixel, (0,0) being the upper left corner of the window. The z coordinate ranges between 0.0 (near plane) and 1.0 (excluded, far plane). See the gluProject man page for details.

unprojectedCoordinatesOf() performs the inverse transformation.

See the screenCoordSystem example.

This method only uses the intrinsic Camera parameters (see getModelViewMatrix(), getProjectionMatrix() and getViewport()) and is completely independent of the OpenGL GL_MODELVIEW, GL_PROJECTION and viewport matrices. You can hence define a virtual Camera and use this method to compute projections out of a classical rendering context.

Attention

However, if your Camera is not attached to a Viewer (used for offscreen computations for instance), make sure the Camera matrices are updated before calling this method. Call computeModelViewMatrix() and computeProjectionMatrix() to do so.

If you call this method several times with no change in the matrices, consider precomputing the projection times modelview matrix to save computation time if required (P x M in the gluProject man page).

Here is the code corresponding to what this method does (kindly submitted by Robert W. Kuhn) :

 vec3 project(vec3 point)
{
 int    Viewport[4];
 double Projection[16], Modelview[16];
 double matrix[16];
 
 // Precomputation begin
 glGetIntegerv(GL_VIEWPORT         , Viewport);
 glGetDoublev (GL_MODELVIEW_MATRIX , Modelview);
 glGetDoublev (GL_PROJECTION_MATRIX, Projection);
 
 for (unsigned short m=0; m<4; ++m)
 {
   for (unsigned short l=0; l<4; ++l)
   {
     double sum = 0.0;
     for (unsigned short k=0; k<4; ++k)
    sum += Projection[l+4*k]*Modelview[k+4*m];
     matrix[l+4*m] = sum;
   }
 }
 // Precomputation end
 
 double v[4], vs[4];
 v[0]=point[0]; v[1]=point[1]; v[2]=point[2]; v[3]=1.0;
 
 vs[0]=matrix[0 ]*v[0] + matrix[4 ]*v[1] + matrix[8 ]*v[2] + matrix[12 ]*v[3];
 vs[1]=matrix[1 ]*v[0] + matrix[5 ]*v[1] + matrix[9 ]*v[2] + matrix[13 ]*v[3];
 vs[2]=matrix[2 ]*v[0] + matrix[6 ]*v[1] + matrix[10]*v[2] + matrix[14 ]*v[3];
 vs[3]=matrix[3 ]*v[0] + matrix[7 ]*v[1] + matrix[11]*v[2] + matrix[15 ]*v[3];
 
 vs[0] /= vs[3];
 vs[1] /= vs[3];
 vs[2] /= vs[3];
 
 vs[0] = vs[0] * 0.5 + 0.5;
 vs[1] = vs[1] * 0.5 + 0.5;
 vs[2] = vs[2] * 0.5 + 0.5;
 
 vs[0] = vs[0] * Viewport[2] + Viewport[0];
 vs[1] = vs[1] * Viewport[3] + Viewport[1];
 
 return vec3(vs[0], Viewport[3]-vs[1], vs[2]);
 }

Examples

Tutorial_204_Viewer_Qt.

projectionMatrix()

const mat4 & projectionMatrix

(

)

const

Fills m with the Camera projection matrix values.

Based on computeProjectionMatrix() to make sure the Camera projection matrix is up to date.

This matrix only reflects the Camera's internal parameters and it may differ from the GL_PROJECTION matrix retrieved using glGetDoublev(GL_PROJECTION_MATRIX, m). It actually represents the state of the GL_PROJECTION after Viewer::preDraw(), at the beginning of Viewer::draw(). If you modified the GL_PROJECTION matrix (for instance using Viewer::startScreenCoordinatesSystem()), the two results differ.

The result is an OpenGL 4x4 matrix, which is given in column-major order (see glMultMatrix man page for details).

See also getModelViewMatrix() and setFromProjectionMatrix().

rightVector()

vec3 rightVector

(

)

const

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(vec3(1.0, 0.0, 0.0)).

sceneCenter()

vec3 sceneCenter ( ) const

inline

Returns the position of the scene center, defined in the world coordinate system.

The scene observed by the Camera should be roughly centered on this position, and included in a sceneRadius() sphere. This approximate description of the scene permits a zNear() and zFar() clipping planes definition, and allows convenient positioning methods such as showEntireScene(). Default value is (0,0,0) (world origin). Use setSceneCenter() to change it.

See also

setSceneBoundingBox().

Examples

Tutorial_204_Viewer_Qt.

sceneRadius()

float sceneRadius ( ) const

inline

Returns the radius of the scene observed by the Camera.

You need to provide such an approximation of the scene dimensions so that the Camera can adapt its zNear() and zFar() values. See the sceneCenter() documentation.

See also

setSceneBoundingBox().

Examples

Tutorial_204_Viewer_Qt, and Tutorial_207_RealCamera.

screenHeight()

int screenHeight ( ) const

inline

Returns the height (in pixels) of the Camera screen.

Set using setScreenWidthAndHeight(). This value is automatically fitted to the viewer's window dimensions when the Camera is attached to a Viewer.

screenWidth()

int screenWidth ( ) const

inline

Returns the width (in pixels) of the Camera screen.

Set using setScreenWidthAndHeight(). This value is automatically fitted to the Viewer's window dimensions when the Camera is attached to a viewer.

set_from_calibration() [1/2]

void set_from_calibration

(

const mat34 &

proj

)

Defines the position(), orientation() and fieldOfView() of the camera from calibrated camera intrinsic and extrinsic parameters. This is an overload of set_from_calibration().

Parameters

proj	The projection matrix, which can be computed as P = K * M * [R|t], where R is a 3x3 matrix representing the camera rotation and T is a 3-vector describing the camera translation (rotation first then translation).

Attention

: M is a 3 by 3 matrix. In case you need to convert from the vision convention to the OpenGL convention (i.e., invert Y and Z axes), M(1, 1) and M(2, 2) must be set to -1, i.e., M(1, 1) = -1; // invert the Y axis M(2, 2) = -1; // invert the Z axis This is because the camera coordinates in computer vision goes X right, Y down, Z forward, while the camera coordinates in OpenGL goes X right, Y up, Z inward.

This function assumes the camera parameters were obtained by standard camera calibration, in which image coordinates are denoted in pixels, with the origin point (0, 0) corresponding to the top-left corner of the image. The X axis starts at the left edge of an image and goes towards the right edge. The Y axis starts at the top of the image towards image bottom. All image pixels have non-negative coordinates.

See also

set_from_calibration.

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.

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 * std::atan(1.0/projectionMatrix[5]).

This code was written by Sylvain Paris. Modified and bug fixed by Liangliang Nan.

set_from_calibration() [2/2]

void set_from_calibration	(	float	fx,
		float	fy,
		float	skew,
		float	cx,
		float	cy,
		const mat3 &	R,
		const vec3 &	t,
		bool	convert = true
	)

Defines the position(), orientation() and fieldOfView() of the camera from calibrated camera intrinsic and extrinsic parameters. This is an overload of set_from_calibration().

Parameters

fx,fy	the focal length
cx,cy	the principal point
skew	distortion
R	the rotation matrix. It denotes the coordinate system transformation from 3D world coordinates to 3D camera coordinates.
t	the camera translation. It is the position of the origin of the world coordinate system expressed in the camera coordinate system.

Note

t is often mistakenly considered the position of the camera. The position C of the camera expressed in world coordinates is C = -inverse(rot) * t = -transpose(rot) * t.

Parameters

convert

true to convert from vision convention to OpenGL convention (i.e., invert Y and Z axes). This is because the camera coordinates of computer vision goes X right, Y down, Z forward, while the camera coordinates of OpenGL goes X right, Y up, Z inward.

Attention

This function assumes the camera parameters were obtained by standard camera calibration, in which image coordinates are denoted in pixels, with the origin point (0, 0) corresponding to the top-left corner of the image. The X axis starts at the left edge of an image and goes towards the right edge. The Y axis starts at the top of the image towards image bottom. All image pixels have non-negative coordinates.

See also

set_from_calibration.

Examples

Tutorial_207_RealCamera.

set_from_model_view_matrix()

void set_from_model_view_matrix

(

const mat4 &

mv

)

const

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

This enables a Camera initialisation from another OpenGL application. After this method has been called, getModelViewMatrix() returns a matrix equivalent to mv. Only the orientation() and position() of the Camera are modified.

set_modelview_matrix()

void set_modelview_matrix

(

const mat4 &

mv

)

Temporally change the modelview matrix.

Parameters

mv	The modelview matrix.

Attention

This function directly changes the modelview matrix. It actually doesn't change any of the camera parameters (i.e., position, orientation, fov, zFar, zNear, etc.). This is only useful if you want to temporally use a different projection matrix for rendering (e.g., grabbing a large snapshot from the framebuffer).

set_projection_matrix()

void set_projection_matrix

(

const mat4 &

proj

)

Temporally change the projection matrix.

Parameters

proj	The projection matrix.

Attention

This function directly changes the projection matrix. It actually doesn't change any of the camera parameters (i.e., position, orientation, fov, zFar, zNear, etc.). This is only useful if you want to temporally use a different projection matrix for rendering (e.g., grabbing a large snapshot from the framebuffer).

setAspectRatio()

void setAspectRatio ( float  aspect )

inline

Defines the Camera aspectRatio().

This value is actually inferred from the screenWidth() / screenHeight() ratio. You should use setScreenWidthAndHeight() instead. This method might however be convenient when the Camera is not associated with a Viewer. It actually sets the screenHeight() to 100 and the screenWidth() accordingly. See also setFOVToFitScene().

Note

If you absolutely need an aspectRatio() that does not correspond to your viewer's window dimensions, overload loadProjectionMatrix() or multiply the created OpenGL projection matrix by a scaled diagonal matrix in your viewer's draw() method.

setFieldOfView()

void setFieldOfView

(

float

fov

)

Sets the vertical fieldOfView() of the Camera (in radians).

Note that focusDistance() is set to sceneRadius() / std::tan(fieldOfView()/2) by this method.

Examples

Tutorial_207_RealCamera.

setFOVToFitScene()

void setFOVToFitScene

(

)

Changes the Camera fieldOfView() so that the entire scene (defined by Viewer::sceneCenter() and Viewer::sceneRadius()) is visible from the Camera position().

The position() and orientation() of the Camera are not modified and you first have to orientate the Camera in order to actually see the scene (see lookAt(), showEntireScene() or fitSphere()).

This method is especially useful for shadow maps computation. Use the Camera positioning tools (setPosition(), lookAt()) to position a Camera at the light position. Then use this method to define the fieldOfView() so that the shadow map resolution is optimally used:

// The light camera needs size hints in order to optimize its fieldOfView
lightCamera->setSceneRadius(sceneRadius());
lightCamera->setSceneCenter(sceneCenter());
 
// Place the light camera.
lightCamera->setPosition(lightFrame->position());
lightCamera->lookAt(sceneCenter());
lightCamera->setFOVToFitScene();

See the (soon available) shadowMap contribution example for a practical implementation.

Attention

The fieldOfView() is clamped to M_PI/2.0. This happens when the Camera is at a distance lower than std::sqrt(2.0) * sceneRadius() from the sceneCenter(). It optimizes the shadow map resolution, although it may miss some parts of the scene.

setFrame()

void setFrame

(

ManipulatedCameraFrame *const

mcf

)

Sets the Camera frame().

If you want to move the Camera, use setPosition() and setOrientation() or one of the Camera positioning methods (lookAt(), fitSphere(), showEntireScene()...) instead.

If you want to save the Camera position(), there's no need to call this method either. Use addKeyFrameToPath() and playPath() instead.

This method is actually mainly useful if you derive the ManipulatedFrame class and want to use an instance of your new class to move the Camera.

A NULL mcf pointer will silently be ignored. The calling method is responsible for deleting the previous frame() pointer if needed in order to prevent memory leaks.

setHorizontalFieldOfView()

void setHorizontalFieldOfView ( float  hfov )

inline

Sets the horizontalFieldOfView() of the Camera (in radians).

horizontalFieldOfView() and fieldOfView() are linked by the aspectRatio(). This method actually calls setFieldOfView(( 2.0 * std::atan (std::tan(hfov / 2.0) / aspectRatio()) )) so that a call to horizontalFieldOfView() returns the expected value.

setOrientation() [1/2]

void setOrientation

(

const quat &

q

)

const

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

Examples

Tutorial_207_RealCamera.

setOrientation() [2/2]

void setOrientation	(	float	theta,
		float	phi
	)		const

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 Viewer::saveSnapshot() documentation for details.

setPivotPoint()

void setPivotPoint

(

const vec3 &

point

)

Changes the pivotPoint() to point (defined in the world coordinate system).

Examples

Tutorial_204_Viewer_Qt.

setPosition()

void setPosition

(

const vec3 &

pos

)

const

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

Examples

Tutorial_207_RealCamera.

setSceneBoundingBox()

void setSceneBoundingBox	(	const vec3 &	min,
		const vec3 &	max
	)

Similar to setSceneRadius() and setSceneCenter(), but the scene limits are defined by a (world axis aligned) bounding box.

Examples

Tutorial_203_Viewer_wxWidgets, and Tutorial_204_Viewer_Qt.

setSceneCenter()

void setSceneCenter

(

const vec3 &

center

)

Sets the sceneCenter().

Attention

This method also sets the pivotPoint() to sceneCenter().

setSceneRadius()

void setSceneRadius

(

float

radius

)

Sets the sceneRadius() value. Negative values are ignored.

Attention

This methods also sets focusDistance() to sceneRadius() / std::tan(fieldOfView()/2) and flySpeed() to 1% of sceneRadius().

Examples

Tutorial_204_Viewer_Qt.

setScreenWidthAndHeight()

void setScreenWidthAndHeight	(	int	width,
		int	height
	)

Sets Camera screenWidth() and screenHeight() (expressed in pixels).

You should not call this method when the Camera is associated with a Viewer, since the latter automatically updates these values when it is resized (hence overwriting your values).

Non-positive dimension are silently replaced by a 1 pixel value to ensure frustum coherence.

If your Camera is used without a Viewer (offscreen rendering, shadow maps), use setAspectRatio() instead to define the projection matrix.

Examples

Tutorial_203_Viewer_wxWidgets, and Tutorial_204_Viewer_Qt.

setType()

void setType

(

Type

type

)

Defines the Camera type().

Changing the camera Type alters the viewport and the objects' sizes can be changed. This method guarantees that the two frustum match in a plane normal to viewDirection(), passing through the pivotPoint().

Prefix the type with Camera if needed, as in:

camera()->setType(Camera::ORTHOGRAPHIC);

Examples

Tutorial_203_Viewer_wxWidgets, and Tutorial_204_Viewer_Qt.

setUpVector()

void setUpVector	(	const vec3 &	up,
		bool	noMove = true
	)		const

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 pivotPoint() stays projected at the same position on screen. This is especially useful when the Camera is used as 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 walk-through fly mode (see the Viewer::MOVE_FORWARD and Viewer::MOVE_BACKWARD Viewer::MouseAction).

The frame()'s ManipulatedFrame::sceneUpVector() is set accordingly.

See also setViewDirection(), lookAt() and setOrientation().

Examples

Tutorial_201_Viewer_default, Tutorial_204_Viewer_Qt, Tutorial_305_Texture, Tutorial_310_TextMesher, Tutorial_602_ConvexPartition, and Tutorial_701_Cloud_NormalEstimation.

setViewDirection()

void setViewDirection

(

const vec3 &

direction

)

const

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().

Examples

Tutorial_201_Viewer_default, Tutorial_204_Viewer_Qt, Tutorial_305_Texture, Tutorial_310_TextMesher, Tutorial_602_ConvexPartition, and Tutorial_701_Cloud_NormalEstimation.

showEntireScene()

void showEntireScene

(

)

const

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 Viewer::init() after you defined a new sceneRadius().

Examples

Tutorial_203_Viewer_wxWidgets, and Tutorial_204_Viewer_Qt.

type()

Type type ( ) const

inline

Returns the Camera::Type of the Camera. Set by setType(). Mainly used by loadProjectionMatrix().

A Camera::PERSPECTIVE Camera uses a classical projection mainly defined by its fieldOfView(). With a Camera::ORTHOGRAPHIC type(), the fieldOfView() is meaningless and the width and height of the Camera frustum are inferred from the distance to the pivotPoint() using getOrthoWidthHeight(). Both types use zNear() and zFar() (to define their clipping planes) and aspectRatio() (for frustum shape).

Examples

Tutorial_203_Viewer_wxWidgets, and Tutorial_204_Viewer_Qt.

unprojectedCoordinatesOf()

vec3 unprojectedCoordinatesOf	(	const vec3 &	src,
		const Frame *	frame = nullptr
	)		const

Returns the world unprojected coordinates of a point src defined in the screen coordinate system.

The src.x and src.y input values are expressed in pixels, (0,0) being the upper left corner of the window. src.z is a depth value ranging in [0..1[ (respectively corresponding to the near and far planes). Note that src.z is not a linear interpolation between zNear and zFar. /code src.z = zFar() / (zFar() - zNear()) * (1.0 - zNear() / z); /endcode Where z is the distance from the point you project to the camera, along the viewDirection(). See the gluUnProject man page for details.

The result is expressed in the frame coordinate system. When frame is NULL (default), the result is expressed in the world coordinates system. The possible frame Frame::referenceFrame() are taken into account.

projectedCoordinatesOf() performs the inverse transformation.

This method only uses the intrinsic Camera parameters (see getModelViewMatrix(), getProjectionMatrix() and getViewport()) and is completely independent of the OpenGL GL_MODELVIEW, GL_PROJECTION and viewport matrices. You can hence define a virtual Camera and use this method to compute un-projections out of a classical rendering context.

Attention

However, if your Camera is not attached to a Viewer (used for offscreen computations for instance), make sure the Camera matrices are updated before calling this method (use computeModelViewMatrix(), computeProjectionMatrix()). See also setScreenWidthAndHeight().

This method is not computationally optimized. If you call it several times with no change in the matrices, you should buffer the entire inverse projection matrix (modelview, projection and then viewport) to speed-up the queries. See the gluUnProject man page for details.

Examples

Tutorial_204_Viewer_Qt.

upVector()

vec3 upVector

(

)

const

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(vec3(0.0, 1.0, 0.0)) ).

viewDirection()

vec3 viewDirection

(

)

const

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(vec3(0.0, 0.0, -1.0)) ).

worldCoordinatesOf()

vec3 worldCoordinatesOf

(

const vec3 &

src

)

const

Returns the world coordinates of the point whose position src is defined in the Camera coordinate system.

cameraCoordinatesOf() performs the inverse transformation.

zClippingCoefficient()

float zClippingCoefficient ( ) const

inline

Returns the coefficient used to position the near and far clipping planes.

The near (resp. far) clipping plane is positioned at a distance equal to zClippingCoefficient() * sceneRadius() in front of (resp. behind) the sceneCenter(). This guarantees an optimal use of the z-buffer range and minimizes aliasing. See the zNear() and zFar() documentations. Default value is square root of 3.0 (so that a cube of size sceneRadius() is not clipped). However, since the sceneRadius() is used for other purposes (see showEntireScene(), flySpeed(), ...) and you may want to change this value to define more precisely the location of the clipping planes. See also zNearCoefficient(). For a total control on clipping planes' positions, an other option is to overload the zNear() and zFar() methods.

Attention

When you visualize the Camera paths, set a larger value (suggested value is 5.0) so that the Camera paths are not clipped. Don't forget to restore the previous zClippingCoefficient() value back when you leave this mode.

zFar()

float zFar ( ) const

virtual

Returns the far clipping plane distance used by the Camera projection matrix.

The far clipping plane is positioned at a distance equal to zClippingCoefficient() * sceneRadius() behind the sceneCenter():

 zFar =
distanceToSceneCenter() + zClippingCoefficient()*sceneRadius(); 

See the zNear() documentation for details.

zNear()

float zNear ( ) const

virtual

Returns the near clipping plane distance used by the Camera projection matrix.

The clipping planes' positions depend on the sceneRadius() and sceneCenter() rather than being fixed small-enough and large-enough values. A good scene dimension approximation will hence result in an optimal precision of the z-buffer.

The near clipping plane is positioned at a distance equal to zClippingCoefficient() * sceneRadius() in front of the sceneCenter():

zNear = distanceToSceneCenter() - zClippingCoefficient()*sceneRadius();

In order to prevent negative or too small zNear() values (which would degrade the z precision), zNearCoefficient() is used when the Camera is inside the sceneRadius() sphere:

 const double zMin = zNearCoefficient() *
zClippingCoefficient() * sceneRadius(); if (zNear < zMin) zNear = zMin;
// With an ORTHOGRAPHIC type, the value is simply clamped to 0.0

See also the zFar(), zClippingCoefficient() and zNearCoefficient() documentations.

If you need a completely different zNear computation, overload the zNear() and zFar() methods in a new class that publicly inherits from Camera and use Viewer::setCamera():

class MyCamera :: public Camera
{
  virtual double Camera::zNear() const { return 0.001; };
  virtual double Camera::zFar() const { return 100.0; };
}

See the standardCamera example for an application.

Attention

The value is always positive although the clipping plane is positioned at a negative z value in the Camera coordinate system. This follows the gluPerspective standard.

zNearCoefficient()

float zNearCoefficient ( ) const

inline

Returns the coefficient which is used to set zNear() when the Camera is inside the sphere defined by sceneCenter() and zClippingCoefficient() * sceneRadius().

In that case, the zNear() value is set to zNearCoefficient() * zClippingCoefficient() * sceneRadius(). See the zNear() documentation for details. Default value is 0.001, which is appropriate for most applications. In case you need a high dynamic ZBuffer precision, you can increase this value (~0.1). A lower value will prevent clipping of very close objects at the expense of a worst Z precision. Only meaningful when Camera type is Camera::PERSPECTIVE.

---

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

• /Users/lnan/Documents/Projects/Easy3D/easy3d/renderer/camera.h
• /Users/lnan/Documents/Projects/Easy3D/easy3d/renderer/camera.cpp