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:
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.
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.
Next we describe the Gist color cards. Gist color cards contain 200 colors. There are no reserved spots at the start for special colors.
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.
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.
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).
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.
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.
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:
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.
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.
Here is an illustration of a plot of a single region of the previous plot, namely region 2.
Here is the same geometric object plotted with height contours:
Our final example is a plot of regions 2 and 3, with height contours.