4.1 Surface Objects

Instantiation

from surface import *

sf = Surface ( <keylist>)

Description

A Surface represents a two-dimensional object in three-dimensional space. It may be purely geometric, or there may be a function defined on the Surface which needs representation too, in which case we have essentially a four dimensional object. The Surface itself is projected on the plane of the graph from some angle; its third dimension may be represented by shading (as if it is shiny and there is a light source from some direction), by superimposing a wire mesh on the Surface, or by coloring it according to height (when there isn't a function on it which needs representation). A function defined on the Surface may have its values denoted by coloring the Surface or by drawing contours on the Surface.

The following keyword arguments may be used in the instantiation of a Surface:

z, x, y, c, color_card, opt_3d, mesh_type, mask, z_c_switch, z_contours_scale, c_contours_scale, z_contours_array, c_contours_array, number_of_z_contours, number_of_c_contours

In addition, Surfaces have two methods new (for clearing out a used Surface to an empty shell and redefining its geometry) and set (for changing the value of arbitrary keywords). These methods work exactly as they do for two dimensional objects.

Keyword Arguments

The following keyword arguments can be specified for a Surface object. Note that not all keywords are available in both PyGist and PyNarcisse. Generally, using an inapproriate keyword will not cause an error; it will be ignored or else the graphics engine will make a clever guess.

z = <value> (required). z is a two dimensional array. If x and y are not specified, then z will be graphed on equally spaced mesh points.

x = <value>, y = <value> (if one is present, then so must the other be.) If c (below) is not present, this represents a 3d plot. Either x and y have dimensions matching z, or else they are one-dimensional and x's length matches the first dimension of z, and y's length matches the second.

c = <value> If present, then the Surface will be colored according to the values of c. (This is a so-called four-dimensional graph.) c must have the same dimensions as z.

color_card = <value>

specifies which color card (another name for palette) you wish to use, e. g., "rainbowhls" (the default), "random", etc. Although a characteristic of a Graph2d, it can be a Surface characteristic since 'link'ed surfaces can have different color cards (valid for Narcisse only). Following is a list of color cards available in Narcisse and Gist, with a brief description of each. The graphics interface is intelligent enough to make a good guess if you specify a Gist color card to Narcisse or vice versa; and if there is no near equivalent, it will simply assign the default color card.

First we list the Narcisse Color Cards. Narcisse color cards contain 64 colors. The first ten, in order, are always bg, fg, blue, green, yellow, orange, red, purple, black, and white. The other 54 are described roughly in the table, starting with the lowest index.

TABLE 4. Narcisse Color cards

absolute	from black to light grey in the middle of the palette, then back down to dark grey at the end.
binary	repeatedly runs through the colors light blue, blue, cyan, green, purple, red, yellow, and orange.
bluegreen	continuously shading from light green to deep blue.
default	grey scale, from black at the low end to white at the top
negative	first half is black; second is grey scale from white to dark grey
positive	first half shades from dark grey to white; second is black
rainbow	shades through the rainbow colors from purple at the low end through red at the high.
rainbowhls	low end is blue, shades through rainbow colors to red, then purple.
random	different every time you use it.
redblue	shades from blue at the low end to red at the high end.
redgreen	shades from light green at the low end to red at the high end.
shifted	shades from medium grey at the low end to white in the middle, then from black in the middle to medium grey at the high end.

Next we describe the Gist color cards. Gist color cards contain 200 colors. There are no reserved spots at the start for special colors.

TABLE 5. Gist Color Cards

earth.gp	black, dark to light blues and then greens, all brown-tinged, tan, beige, some grey, pink, ivory, and white at the top.
stern.gp	black, grey, red, magenta, purple, lightening into blue, bluegreen, green, ivory, light grey, white.
rainbow.gp	red through purple, in the normal rainbow order.
heat.gp	very dark red, lightens up through shades of red to orange, yellow, ivory, and white.
gray.gp	grey scale running from black at the low end to white at the high.
yarg.gp	same, but white at the bottom to black at the top.

opt_3d = <value> where <value> is a string or a sequence of strings giving the 3d or 4d surface characteristics. A surface is colored by height in z if a 3d option is specified, and by the value of the function c if a 4d option is specified. With a wire grid option, the grid is colored (Narcisse only); with a flat option, the quadrilaterals set off by grid points are colored; with a smooth option, the surface itself is colored by height (filled contours); and with an iso option, the contour lines are colored (Narcisse only). flat and iso options may be used together in any combination. wire grid options are independent of the other options. Legal arguments for opt_3d are:

'wm'--monochrome wire grid (the default); 'w3' and 'w4'--3d and 4d coloring of wire grid. 'w3' and 'w4' are not currently available in Gist.

'f3' and 'f4'--flat 3d and 4d coloring options.

'i3' and 'i4'--3d and 4d isoline (contour line) options. Colored isolines are not currently available in Gist.

's3' and 's4'--3d and 4d smooth coloring (filled contour) options.

mesh_type = <string> in one of the wire modes, tells what form the wire grid takes: "x": x lines only; "y": y lines only; "xy": both x lines and y lines (the default). Only the latter is available in Gist.

mask = <string>: specifies whether hidden lines will be eliminated, and if so, how complex the algorithm that will be used to determine what is hidden. "none" : transparent wire grid (the default); "min": simple masking; "max" : better masking; "sort": slowest but most sophisticated. Only "none" and "sort" are available in Gist.

z_c_switch = 0 or 1 : set to 1 means switch z and c in the plot.

z_contours_scale, c_contours_scale = "lin" or "log".

z_contours_array, c_contours_array = actual array of numbers to use for contours, if you don't want them computed automatically.

number_of_z_contours, number_of_c_contours = <integer> specifies how many contours to use; they will be computed automatically depending on the data.

Examples

The following set of computations defines a surface and functional values on the surface, which will be used in the subsequent plots. Note that this is very similar to the QuadMesh example. (See "Examples" on page 24.) However, now we shall see the surface in three-dimensional space, with contours and contour lines. We will do many plots of this surface, in order to show the many available options.

s = 1000.

kmax = 25

lmax = 35

xr = multiply.outer (arange (1, kmax + 1, typecode = Float),

ones (lmax, Float))

yr = multiply.outer (ones (kmax, Float), arange (1, lmax + 1,

typecode = Float))

zt = 5. + xr + .2 * random_sample (kmax, lmax)

rt = 100. + yr + .2 * random_sample (kmax, lmax)

z = s * (rt + zt)

z = z + .02 * z * random_sample (kmax, lmax)

ut = rt / sqrt (rt ** 2 + zt ** 2)

vt = zt / sqrt (rt ** 2 + zt ** 2)

ireg = multiply.outer ( ones (kmax), ones (lmax))

ireg [0:1, 0:lmax] = 0

ireg [0:kmax, 0:1] = 0

ireg [1:15, 7:12] = 2

ireg [1:15, 12:lmax] = 3

ireg [3:7, 3:7] = 0

freg = ireg.astype (Float) + .2 * (1. -

random_sample (kmax, lmax))

z [3:10, 3:12] = z [3:10, 3:12] * .9

z [5, 5] = z [5, 5] * .9

z [17:22, 15:18] = z [17:22, 15:18] * 1.2

z [16, 16] = z [16, 16] * 1.1

s1 = Surface (z = z, mask = "max", opt_3d = ["wm", "i3"])

g1 = Graph3d ( s1 , titles = "Surface with contour lines",

xyequal = 1.,

theta = 45., phi = 10., roll = 0.)

g1.plot ( )

The plot appears on the next page.

In the following plot, we change the 3d options to "wm" (wire mode, i. e., mesh lines are plotted) and "f3" (flat 3d, meaning cells are colored according to their average height).

s1.set (opt_3d = ["wm", "f3"])

g1.change (titles = "Flat mode")

g1.plot ()

Now let us leave "wm" set, and switch to "s3" (smooth 3d, i. e., the surface is drawn with contours filled with color according to height.

s1.set (opt_3d = ["wm", "s3"])

g1.change (titles = "Smooth mode")

g1.plot ()

The next plot illustrates how we can use the axis_limits keyword to trim off a portion of the figure, when plotting contours. If both axis limits are given as 0.0, then PyGist takes this as a signal to compute limits based on the data. if either or both limits are nonzero, then PyGist will not display parts of the graph whose z values fall outside the limits. In this particular example, we have set the minimum z value to 0.0, so the part of the surface below the xy plane will be suppressed. The same thing may be done with 4d plots, by specifying a fourth set of limits, which apply to the variable being plotted. The scale is exaggerated in the z direction; a larger y_factor might ameliorate this problem.

s1.new (x = xr, y = yr, z = z - z [kmax/2, lmax/2],

mask = "max", opt_3d = ["wm" , "i3"])

g1.change ( titles = "Part of surface above xy plane",

phi = 30., y_factor = 2.0,

axis_limits = [[0., 0.],[0., 0.], [0., 100000.]])

If we try to do the same plot in flat mode, the z axis limits do not work as advertised. Plots can be trimmed as above only in one of the contour plotting modes: "i3", "i4", "s3", or "s4". We are going to use the same Surface and Graph3d objects, changing only the Graph3d's title, but therefore leaving the z axis limits unchanged. Thus we have the following:

s1.set (opt_3d = ["wm", "f3"])

g1.change (titles = "Flat mode")

g1.plot ()

Next we go to smooth (filled contour) mode. The contours are colored based on the maximum and minimum z values taken over the whole surface, not on the ones plotted.

s1.set (opt_3d = ["wm", "s3"])

g1.change (titles = "Smooth mode")

g1.plot ()

Below is a plot of the same surface, but this time it is a so-called 4d plot, meaning that contours are drawn and filled according to the value of a variable on the mesh, rather than its height. In this case the variable is freg, defined a few pages previously (see page 48). Note that all axis limits are set back to defaults.

s1.set (z = z, c = freg, opt_3d = ["wm", "s4"])

g1.change ( titles = "Surface colored by mesh values",

phi = 20., xyequal = 1,

axis_limits = [[0., 0.], [0., 0.], [0., 0.], [0., 0.]])

g1.plot ( )

Here is an illustration of a plot of a single region of the previous plot, namely region 2.

xr1 = xr [0:16, 6:13]

yr1 = yr [0:16, 6:13]

z1 = z [0:16, 6:13]

zs1 = freg [0:16, 6:13]

s1.set (x = xr1, y = yr1, z = z1, c = zs1)

g1.change ( titles = "Region 2 colored by mesh values",

phi = 10.)

g1.plot ( )

Here is the same geometric object plotted with height contours:

s1.new (x = xr1, y = yr1, z = z1, opt_3d = ["wm", "s3"],

mask = "max")

g1.change ( titles = "Region 2 with mesh and contours",

phi = 10.)

g1.plot ( )

Our final example is a plot of regions 2 and 3, with height contours.

zs1 = z [0:16, 6:lmax - 1]

s1.new (z = zs1, opt_3d = ["wm", "s3"], mask = "max")

g1.change ( titles = "Regions 2 and 3, mesh and contours",

theta = 70., phi = 10., roll = 0.)

g1.plot ( )