27. camera — OpenGL camera handling

Classes defined in module camera

class camera.Camera(center=[0.0, 0.0, 0.0], long=0.0, lat=0.0, twist=0.0, dist=1.0)

A camera for OpenGL rendering.

The Camera class holds all the camera related settings related to the rendering of a scene in OpenGL. These include camera position, the viewing direction of the camera, and the lens parameters (opening angle, front and back clipping planes). This class also provides convenient methods to change the settings so as to get smooth camera manipulation.

Camera position and orientation:

The camera viewing line is defined by two points: the position of the camera and the center of the scene the camera is looking at. We use the center of the scene as the origin of a local coordinate system to define the camera position. For convenience, this could be stored in spherical coordinates, as a distance value and two angles: longitude and latitude. Furthermore, the camera can also rotate around its viewing line. We can define this by a third angle, the twist. From these four values, the needed translation vector and rotation matrix for the scene rendering may be calculated.

Inversely however, we can not compute a unique set of angles from a given rotation matrix (this is known as ‘gimball lock’). As a result, continuous (smooth) camera rotation by e.g. mouse control requires that the camera orientation be stored as the full rotation matrix, rather than as three angles. Therefore we store the camera position and orientation as follows:

• focus: [ x,y,z ] : the reference point of the camera: this is always a point on the viewing axis. Usually, it is set to the center of the scene you are looking at.
• dist: distance of the camera to the reference point.
• rot: a 3x3 rotation matrix, rotating the global coordinate system thus that the z-direction is oriented from center to camera.

These values have influence on the ModelView matrix.

Camera lens settings:

The lens parameters define the volume that is seen by the camera. It is described by the following parameters:

• fovy: the vertical lens opening angle (Field Of View Y),
• aspect: the aspect ratio (width/height) of the lens. The product fovy * aspect is the horizontal field of view.
• near, far: the position of the front and back clipping planes. They are given as distances from the camera and should both be strictly positive. Anything that is closer to the camera than the near plane or further away than the far plane, will not be shown on the canvas.

Camera methods that change these values will not directly change the ModelView matrix. The loadModelView() method has to be called explicitely to make the settings active.

These values have influence on the Projection matrix.

Methods that change the camera position, orientation or lens parameters will not directly change the related ModelView or Projection matrix. They will just flag a change in the camera settings. The changes are only activated by a call to the loadModelView() or loadProjection() method, which will test the flags to see whether the corresponding matrix needs a rebuild.

The default camera is at distance 1.0 of the center point [0.,0.,0.] and looking in the -z direction. Near and far clipping planes are by default set to 0.1, resp 10 times the camera distance.

getRot()

Return the camera rotation matrix.

lock(onoff=True)

Lock/unlock a camera.

When a camera is locked, its position and lens parameters can not be changed. This can e.g. be used in multiple viewports layouts to create fixed views from different angles.

setAngles(angles)

Set the rotation angles.

angles is either:

• a tuple of angles (long,lat,twist)
• a named view corresponding to one of the predefined viewing directions in views.py
• None

setRotation(long, lat, twist=0)

Set the rotation matrix of the camera from three angles.

report()

Return a report of the current camera settings.

dolly(val)

Move the camera eye towards/away from the scene center.

This has the effect of zooming. A value > 1 zooms out, a value < 1 zooms in. The resulting enlargement of the view will approximately be 1/val. A zero value will move the camera to the center of the scene. The front and back clipping planes may need adjustment after a dolly operation.

move(dx, dy, dz)

Move the camera over translation (dx,dy,dz) in global coordinates.

The center of the camera is moved over the specified translation vector. This has the effect of moving the scene in opposite direction.

rotate(val, vx, vy, vz)

Rotate the camera around current axis (vx,vy,vz).

saveModelView()

Save the ModelView matrix.

setModelView()

Set the ModelView matrix from camera parameters.

loadModelView(m=None)

Load the ModelView matrix.

There are three uses of this function:

• Without argument and if the viewing parameters have not changed since the last save of the ModelView matrix, this will just reload the ModelView matrix from the saved value.
• If an argument is supplied, it should be a legal ModelView matrix and that matrix will be loaded (and saved) as the new ModelView matrix.
• Else, a new ModelView matrix is set up from the camera parameters, and it is loaded and saved.

In the latter two cases, the new ModelView matrix is saved, and if a camera attribute modelview_callback has been set, a call to this function is done, passing the camera instance as parameter.

loadCurrentRotation()

Load the current ModelView matrix with translations canceled out.

transform(v)

Transform a vertex using the currently saved Modelview matrix.

toWorld(v)

Transform a vertex from camera to world coordinates.

This multiplies The specified vector can have 3 or 4 (homogoneous) components. This uses the currently saved rotation matrix.

setLens(fovy=None, aspect=None)

Set the field of view of the camera.

We set the field of view by the vertical opening angle fovy and the aspect ratio (width/height) of the viewing volume. A parameter that is not specified is left unchanged.

resetArea()

Set maximal camera area.

Resets the camera window area to its maximum values corresponding to the fovy setting, symmetrical about the camera axes.

setArea(hmin, vmin, hmax, vmax, relative=True, center=False, clip=True)

Set the viewable area of the camera.

zoomArea(val=0.5, area=None)

Zoom in/out by shrinking/enlarging the camera view area.

The zoom factor is relative to the current setting. Values smaller than 1.0 zoom in, larger values zoom out.

transArea(dx, dy)

Pan by moving the vamera area.

dx and dy are relative movements in fractions of the current area size.

setClip(near, far)

Set the near and far clipping planes

setPerspective(on=True)

Set perspective on or off

loadProjection(force=False, pick=None, keepmode=False)

Load the projection/perspective matrix.

The caller will have to setup the correct GL environment beforehand. No need to set matrix mode though. This function will switch to GL_PROJECTION mode before loading the matrix

If keepmode=True, does not switch back to GL_MODELVIEW mode.

A pick region can be defined to use the camera in picking mode. pick defines the picking region center and size (x,y,w,h).

This function does it best at autodetecting changes in the lens settings, and will only reload the matrix if such changes are detected. You can optionally force loading the matrix.

project(x, y, z)

Map the object coordinates (x,y,z) to window coordinates.

unProject(x, y, z)

Map the window coordinates (x,y,z) to object coordinates.

setTracking(onoff=True)

Enable/disable coordinate tracking using the camera

Functions defined in module camera

camera.tand(arg)

Return the tan of an angle in degrees.