2010 October 12 / j|d|a|v|i|s|@|c|a|r|l|e|t|o|n|.|e|d|u

Camera

An Camera is a frustum or box that describes the viewing volume of a perspective or orthogonal camera (or the field of illumination of a spot or directional light). To the user, a camera appears to be an actual camera situated in world space, with definite position, orientation, and lens characteristics. The camera's position and orientation are controlled by an underlying Open Dynamics Engine Body. All messages that the camera receives and doesn't recognize are delegated to the ODE Body. In most cases this means that you can talk to Camera as if it's a subclass of ODE's Body. For example, you can set the camera's position by calling myBody3D.setPosition(xyz) instead of myBody3D.getBody().setPosition(xyz).

__init__(self, isOrthogonal=False, world=None)

Initializes the camera to its default settings. The camera is either perspective or orthogonal; this cannot be changed. The world argument should be an ODE World object, where the body will live; if world is None, then the body lives in the world of the current window.

getBody(self)

Returns the underlying ODE Body, which is never None. Note however that in most cases you do not need to get the ODE Body; all messages that the Camera receives, that it doesn't recognize, are delegated to the ODE Body automatically.

translate(self, v)

Changes the position by adding v = (dx, dy, dz).

rotate(self, angle, axis)

Prepends the given angle-axis rotation to the receiver's orientation.

revolve(self, angle, axis, center)

Revolves the object about the given center point by the angle-axis rotation; changes position but not orientation.

revolveRotate(self, angle, axis, center)

Revolves the object about the given center point by the given angle-axis rotation, also prepending the rotation to the object's orientation. Useful for keeping a camera or light pointed at an object as it revolves about it.

dolly(self, distance)

Moves the camera forward by distance (or backward, if negative). In orthogonal mode, this has no visual effect.

getIsOrthogonal(self)

Returns whether the camera is orthogonal or not (perspective).

setNearFar(self, near, far)

Controls world-space distance to near and far clipping planes. The user must keep far > near. The defaults are 1 and 100.

getNear(self)

Returns the distance to the near clipping plane, in world space.

getFar(self)

Returns the distance to the far clipping plane, in world space.

setAspectRatio(self, ratio)

Sets the aspect ratio (width / height).

getAspectRatio(self)

Returns the aspect ratio (width / height).

setHeight(self, height)

Sets the height of the viewing volume (on the near plane).

getHeight(self)

Returns the height of the viewing volume (on the near plane).

setAngle(self, angle)

Sets the perspective frustum angle (not the half angle) in radians.

getAngle(self)

Returns the perspective frustum angle (not the half angle) in radians.

project(self, xyz)

Projects a world point to a screen point, using the camera's state as well as the OpenGL viewport. That is, returns a tuple (x, y, z) of screen coordinates for the given world coordinates. This method is the inverse of unproject().

unproject(self, xyz)

Unprojects a screen point to a world point, using the camera's state as well as the OpenGL viewport. That is, returns a tuple (x, y, z) of world coordinates for the given screen coordinates. The screen coordinates are typically obtained by reading a depth value out of a particular pixel. This method is the inverse of project().

getDirection(self)

Returns the unit 3-vector in the direction that the camera is pointing.

getPickLine(self, xy)

Returns a pair (p, v), where p is a point and v is a unit vector, such that p + t v parametrizes the line through the scene that passes through screen coordinates xy (i.e. (x, y, 0.5)).

moveScreenPoint(self, xyPrevious, xyCurrent)

This is a simple way to implement Window's member drag handler so that the mouse controls the camera. The camera adjusts so that what used to appear at the previous xy screen coordinates now appears at the current xy screen coordinates. In perspective mode, it does this by rotating the camera; in orthogonal mode, it translates the camera in a direction perpendicular to the line of sight.

getUpwardCorrection(self)

Returns the angle-axis rotation about the camera's sightline that, when prepended to the camera's current orientation, makes the camera upright. If this calculation is impossible (because the camera's sightline is vertical) then None is returned.

containPoints(self, points)

Given a sequence of points in global coordinates, adjusts the viewing volume so that it contains all of the points. The convex hull of the points should have positive volume. May change any of near, far, aspect ratio, height, and angle. Returns Boolean indicating success. For orthogonal cameras, always succeeds but may translate the camera. For perspective cameras, never translates the camera but sometimes fails --- namely, if any point is behind the camera.

getLocalVertices(self)

Returns a list of the 8 vertices of the viewing volume in local coordinates.

getVertices(self)

Returns a list of the 8 vertices of the frustum as points in world space.