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:
The elements of this list are divided into the viewing transformation, lighting specifications, and display information, as follows:
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 (angle1, angle2). 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 anglex about viewer's x axis, angley about viewer's y axis, and anglez about viewer's z-axis.
mov3 moves the current 3D plot by val1 along the viewer's x axis, val2 along the viewer's y axis, and val3 along the viewer's z axis. aim3 moves the current 3D plot to put the point (val1, val2, val3) in object coordinates at the point (0, 0, 0) -- the aim point -- in the viewer's coordinates. In both functions, if any of the val1, val2, or val3 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).
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.
This function is used to set the lighting parameters for the current drawing list.
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.