The Plotting List

The 3D 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 3D 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 1 , args 1 , fnc 2 , args 2 ,...]

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:

fnc1, fnc2, etc.:

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