7.1 Setting Up For 3-D Graphics

7.1.1 The Plotting List

The 3-D PyGist graphics keeps an internal list called _draw3_list containing complete information about the currently active frame (which may or may not be visible depending on whether draw3 has been invoked). Regular users should never need to access this list; however, there is an access function available called get_draw3_list_ which code developers and maintainers may use to get at the list; get_draw3_n_ returns the number of elements in the viewing and lighting portion of the list, described below. Likewise, ordinary users do not really need to know the structure of this list in detail; however, every user of the 3-D graphics should be aware of the contents of the list, how it affects the graph, and what functions to use to alter it.

_draw3_list is a Python list, organized as follows:

[rotation, origin, camera_dist, ambient, diffuse, specular, spower, sdir, fnc₁, args₁, fnc₂, args₂,...]

The elements of this list are divided into the viewing transformation, lighting specifications, and display information, as follows:

Viewing:

rotation: a 3-by-3 rotation matrix giving the angles of view.

origin: a 3-vector giving the coordinates of the origin in the user's coordinate system.

camera_dist: A real number giving the camera distance; the value None (the default) translates to infinity.

Lighting:

ambient: a light level (in arbitrary units) that is added to every part of the surface regardless of its orientation. It might be said to be the amount of light which a surface exudes on its own. A surface with ambient of 0 is totally black unless illuminated.

diffuse: a light level which is proportional to cos(theta), where theta is the angle between the surface normal and the viewing direction, so that surfaces directly facing the viewer are bright, while surfaces viewed edge on are unlit (and surfaces facing away, if drawn, are shaded as if they faced the viewer).

specular: a light level proportional to a high power spower of 1 + cos (alpha), where alpha is the angle between the specular reflection angle and the viewing direction. The light source for the calculation of alpha lies in the direction sdir (a 3 element vector) in the viewer's coordinate system at infinite distance. You can have ns light sources by making specular, spower, and sdir (or any combination) be vectors of length ns (3-by-ns in the case of sdir).

Display:

fnc₁, fnc₂, etc.: Plotting function(s) (whose argument lists are arg₁, arg₂, etc., respectively) defining the component(s) of this graph. During its normal operating mode, the 3-D graphics accumulates information about calls to plotting functions until the user calls the function draw3. These calls are then executed when draw3 is invoked.

7.1.2 Functions For Setting Viewing Parameters

Angular orientation

orient3 (phi = angle₁, theta = angle₂)

rot3 (xa = angle_x, ya = angle_y, za = angle_z)

Description

Note that most of the functions in 3-D PyGist accept keyword arguments. These arguments may be entered in any order; omitted arguments will default to a sensible value.

orient3 sets the orientation of the object to (angle₁, angle₂). Orientations are a subset of the possible rotation matrices in which the z axis of the object appears vertical on the screen (that is, the object z axis projects onto the viewer y axis). The theta angle is the angle from the viewer y axis to the object z axis, positive if the object z axis is tilted towards you (toward viewer +z). phi is zero when the object x axis coincides with the viewer x axis. If neither phi nor theta is specified, phi defaults to - pi / 4 and theta defaults to pi / 6. If only phi is specified, theta remains unchanged, unless the current theta is near pi / 2, in which case theta returns to pi / 6, or unless the current orientation does not have a vertical z axis, in which case theta returns to its default. If only theta is specified, phi retains its current value. Unlike rot3, orient3 is not a cumulative operation.

rot3 rotates the current 3D plot by angle_x about viewer's x axis, angle_y about viewer's y axis, and angle_z about viewer's z-axis.

Physical orientation

mov3 (xa = val₁, ya = val₂, za = val₃)

aim3 (xa = val₁, ya = val₂, za = val₃)

setz3 (zc = dist)

Description

mov3 moves the current 3D plot by val₁ along the viewer's x axis, val₂ along the viewer's y axis, and val₃ along the viewer's z axis. aim3 moves the current 3D plot to put the point (val₁, val₂, val₃) in object coordinates at the point (0, 0, 0) -- the aim point -- in the viewer's coordinates. In both functions, if any of the val₁, val₂, or val₃ is missing, it defaults to 0.

setz3 sets the camera position to dist (x = y = 0) in the viewer's coordinate system. If dist is None or if zc is missing, set the camera to infinity (default).

Examples

Our examples are postponed until later in the chapter, when we have covered enough material to give complete sequences of computations and PyGraph function calls, and show the resulting plots.

7.1.3 Lighting Parameters

Calling Sequence

light3 (ambient=a_level, diffuse=d_level, specular=s_level,

spower=n, sdir=xyz)

This function is used to set the lighting parameters for the current drawing list.

7.1.4 Display List

Calling Sequences

<plot function> (arg₁, arg₂, arg₃, ...)

clear3 ( )

When one of the plotting functions (plwf, pl3surf, pl3tree) is called and the internal variable _draw3 has been set to zero, or else if it is nonzero and the idler is a do-nothing routine, Then this plot call will add <plot function> to the display list, and will process the arguments into a Python list, which will be added to the display list after the function name.

The function clear3 clears the display list of all plotting functions. It leaves orientation and lighting information unchanged.