98. opengl.camera — OpenGL camera handling

Python OpenGL framework for pyFormex

This OpenGL framework is intended to replace (in due time) the current OpenGL framework in pyFormex.

  1. 2013 Benedict Verhegghe and the pyFormex project.

98.1. Classes defined in module opengl.camera

class opengl.camera.Camera(focus=(0.0, 0.0, 0.0), angles=(0.0, 0.0, 0.0), dist=1.0, fovy=45.0, aspect=1.3333333333333333, clip=(0.01, 100.0), perspective=True, area=(0.0, 0.0, 1.0, 1.0), locked=False, keep_aspect=True, tracking=False)[source]

A camera for 3D model rendering.

The Camera class holds all the camera parameters related to the rendering of a 3D scene onto a 2D canvas. These includes parameters related to camera position and orientation, as well as lens related parameters (opening angle, front and back clipping planes). The class provides the required matrices to transform the 3D world coordinates to 2D canvas coordinates, as well as a wealth of methods to change the camera settings in a convenient way so as to simulate smooth camera manipulation.

The basic theory of camera handling and 3D rendering can be found in a lot of places on the internet, especially in OpenGL related places. However, while the pyFormex rendering engine is based on OpenGL, the way it stores and handles the camera parameters is more sophisticated than what is usually found in popular tutorials on OpenGL rendering. Therefore we give here a extensive description of how the pyFormex camera handling and 3D to 2D coordinate transformation works.

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:

  • ctr: [ 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.

Properties:

  • modelview: Matrix4: the OpenGL Modelview transformation matrix

  • projection: Matrix4: the OpenGL Projection transformation matrix

98.2. Functions defined in module opengl.camera

opengl.camera.normalize(x, w)[source]

Normalized coordinates inside a window.

Parameters:

  • x: an (np,nc) array with coordinates.

  • w: a (2,nc) array with minimal and width of the window that will be mapped to the range -1..1.

Returns an array with the x values linearly remapped thus that values w[0] become -1 and values w[0]+w[1] become +1.

opengl.camera.denormalize(x, w)[source]

Map normalized coordinates to fit a window

Parameters:

  • x: an (np,nc) array with normalized coordinates.

  • w: a (2,nc) array with minimal and width values of the window.

Returns an array with the x values linearly remapped thus that values -1 coincide with the minimum window values and +1 with the minimum+width values.

opengl.camera.perspective_matrix(left, right, bottom, top, near, far)[source]

Create a perspective Projection matrix.

opengl.camera.orthogonal_matrix(left, right, bottom, top, near, far)[source]

Create an orthogonal Projection matrix.

opengl.camera.pick_matrix(x, y, w, h, viewport)[source]

Create a pick Projection matrix