7.7 Animation: movie and spin3

7.7.1 The movie module and function

Calling Sequence

movie (draw_frame [, time_limit = 120.]

[, min_interframe = 0.0]

[, bracket_time = array ([2., 2.], Float )]

[, lims = None]

[, timing = 0])

Description

Note: All but the first argument are keyword arguments, with defaults as shown.

This function runs a movie based on the given draw_frame function. The movie stops after a total elapsed time of time_limit seconds, which defaults to 60 (one minute), or when the draw_frame function returns zero. (N. B. Currently the timing option described here and in a subsequent paragraph is not completely implemented.)

draw_frame is a function described as follows:

def draw_frame (i) :

# Input argument i is the frame number.

# draw_frame should return non-zero if there are more

# frames in this movie. A zero return will stop the

# movie.

# draw_frame must NOT include any fma command if the

# making_movie variable is set (movie sets this variable

# before calling draw_frame)

If min_interframe is specified, a pause will be added as necessary to slow down the movie. min_interframe is a time in seconds (default 0). The keyword bracket_time (again a time in seconds) can be used to adjust the duration of the pauses after the first and last frames. It may also be a two element array [beg, end]. If the pause at the end is greater than five seconds, you will be prompted to explain that hitting <RETURN> will abort the final pause. (Well, the Python version does not currently have this capability due to the difficulty of implementing it consistently over various platforms.)

timing = 1 enables a timing printout for your movie.

If every frame of your movie has the same limits, use the lims keyword argument to fix the limits during the movie.

Example

In the following example, the movie demonstrates the effect of a moving light source on the currently drawn surface. (The plot functions creating the surface have not been shown; it is assumed that the data for the surface is on the current display list.)

The draw_frame function is as follows:

def demo5_light (i) :

global making_movie

if i >= 30 : return 0

theta = pi / 4 + (i - 1) * 2 * pi/29

light3 (sdir =

array ( [cos(theta), .25, sin(theta)], Float))

# without an explicit call to draw3, the light3

# function would cause no changes until Python

# paused for input from the keyboard, since

# unlike the primitive plotting functions (plg, plf,

# plfp, ...) the fma call made by the movie function

# will not trigger the 3-D display list. any movie

# frame display function which uses the 3-D drawing

# functions in pl3d.py will need to do this. the

# !making_movie flag supresses the fma in draw3 if

# this function is called by movie (which issues

# its own fma), but allows it otherwise

draw3 ( not making_movie )

return 1

Here is the Python code necessary to run a movie. This particular animation shows the surface with a peak and valley which we saw earlier in this chapter(See "Examples" on page 68), with a moving light source. A few frames of the movie are shown on the next page.

set_draw3_ (0)

x = span (-1, 1, 64, 64)

y = transpose (x)

z = (x + y) * exp (-6.*(x*x+y*y))

orient3 ( )

light3 (diffuse=.2,specular=1 )

limits_(square = 1)

plwf (z,y,x,shade=1,edges=0)

[xmin, xmax, ymin, ymax] = draw3 (1)

limits (xmin, xmax, ymin, ymax)

making_movie = 1

movie(demo5_light, lims = [xmin, xmax, ymin, ymax])

making_movie = 0

TABLE 1. Selected Frames Showing Moving Light Source

7.7.2 The spin3 function

spin3 is a function which takes an existing 3-D plot and spins it about an axis. It actually calls movie for you, with a draw_frame function which is internal to the pl3d module and not available outside this module, because its name begins with an underscore.

Calling Sequence

spin3 (nframes = 30,

axis = array ([-1, 1, 0], Float),

tlimit = 60.,

dtmin = 0.0,

bracket_time = array ([2., 2.], Float),

lims = None,

timing = 0,

angle = 2. * pi)

Description

Spin the current 3-D display list about axis (default [-1, 1, 0]) over nframes (default 30). Note that all arguments are keywords. Also note that the timing keywords are allowed but are not currently implemented. Their meanings are:

tlimit: the total time allowed for the movie in seconds (default 60).

dtmin: the minimum allowed interframe time in seconds (default 0.0).

bracket_time: (as for movie function in movie.py).

lims: the axis limits, if you wish to specify them.

timing = 1 if you want timing measured and printed out, 0 if not.

angle: the total angle about the axis through which the object will be rotated. During each step of the rotation, the object will rotate angle / (nframes - 1).

Example

In this example, we take the surface discussed previously (see "Example" on page 75) and rotate it about an axis. Assume that the sequence of code given there has been executed, giving the figure shown there. Then we do the following to run the movie:

spin3 () # (lims = [l0, l1, l2, l3])

Four frames from the resulting movie are shown on the next page.

TABLE 2. Frames from Movie of Rotating Isosurfaces