PLOT and PLOT3D Data Structures

Description



Important: This page describes the internal structures used by Maple to construct 2D and 3D plots. It is recommended that the plot or plot3d commands, or the commands in the plots package be used to generate plots.

•

The Maple plotting functions, plot, plot3d, and others, produce PLOT and PLOT3D data structures describing the images to be displayed. The plots[display] command also produces a _PLOTARRAY structure to represent an array of plots. These data structures are understood by the Maple prettyprinter, which prints the plots in a form like any other Maple object. Because the structures are Maple expressions, they can be manipulated, saved, and printed like any other expression. The remainder of this section describes the form and content of the data structures. The data structures can be viewed using the Maple lprint command.

•

Each graphics image is represented by a function call of the form PLOT(...), PLOT3D(...) or _PLOTARRAY(...). The data values within these function calls specify the objects to be drawn (for example, points or lines) and options that control how the objects are to be drawn (for example, axes style or color). The _PLOTARRAY structure has as its first argument a Matrix or a list of lists containing PLOT or PLOT3D structures.


For example, PLOT(CURVES([[0, 0], [0, 1], [0.5, 0.5], [0, 0]]), COLOR(RGB, 0, 0, 1)) describes a blue triangle in 2D. As in this example, all of the objects and options are represented by function calls where the function name is fully capitalized.


Note: The structure name COLOUR may be used in place of COLOR.

•

Data structure names introduced in Maple 10 or later are prefixed by an underscore.

•

The TRANSPARENCY, _GLOSSINESS and _AXIS[n] structures are not available in all interfaces.

•

If the same option structure is provided more than once, with different values, then the final value specified is generally the one used.


2D and 3D Plot Objects



There are four different object types for 2D plotting: curves, points, polygons, and text. These four are also available for 3D plotting. In addition, grid, mesh, and isosurface structures can be used in 3D plots.


When data is provided as an Array or Matrix, the Array or Matrix must have datatype equal to float[8]. Furthermore, all indices in the Array must start at 1. When data is provided as a list, the elements must be floatingpoint values.


The CURVES structure defines one or more curves in 2D or 3D space, formed by joining a sequence of sample points. Each 2D curve A1, A2, ... is represented by an n by 2 Matrix or Array or a list of the form [[x1, y1], [x2, y2], ..., [xn, yn]]. Each 3D curve is represented by an n by 3 Matrix or Array or a list of the form [[x1, y1, z1], [x2, y2, z2], ..., [xn, yn, zn]].


The POINTS structure defines a set of 2D or 3D points, represented by A. For points in 2D, A can be an n by 2 Matrix or Array or a sequence of the form [x1, y1], [x2, y2], ..., [xn, yn]. For points in 3D, A can be an n by 3 Matrix or Array or a sequence of the form [x1, y1, z1], [x2, y2, z2], ..., [xn, yn, zn].


The POLYGONS structure defines one or more polygons in 2D or 3D space. The format of each A1, A2, ... is identical to that described for the CURVES structure.

•

TEXT(A, string, horizontal, vertical)


The TEXT structure defines a text element in 2D or 3D space. In 2D, the point A is a list [x, y], while in 3D, A is a list [x, y, z]. The horizontal value can be one of the two keywords ALIGNLEFT or ALIGNRIGHT, in which case the string is placed to the left or right of the location defined by A. Similarly, vertical can be one of the keywords ALIGNABOVE or ALIGNBELOW. If horizontal and/or vertical are omitted, the string is centered in the appropriate dimension.


The GRID structure represents surfaces in 3D space defined by a uniform sampling over a rectangular (aligned) region of the plane. The GRID structure takes the form GRID(a..b, c..d, A) where a..b is the xrange, c..d is the yrange, and A is a twodimensional Array. If you have an mbyn grid, then element A[i, j] is the function value at grid point (i, j), for i in 1..m and j in 1..n. The Array A may be replaced by a list of the form [[z11,...z1n], [z21,...z2n],...[zm1...zmn]] where zij is the function value at grid point (i, j).


The ISOSURFACE structure contains the samples of a function taken over a regular grid in 3D space and is rendered as a 3D surface approximating the zero surface of the function. The ISOSURFACE structure takes the form ISOSURFACE(A) where A is a fourdimensional Array. If you have an mbynbyp grid, then A[i, j, k, 1..3] gives the (x, y, z) coordinates of grid point (i, j, k) and A[i, j, k, 4] is the function value at that point, for i in 1..m, j in 1..n and k in 1..p. The Array A can be replaced by a list of m lists. Each sublist in turn contains n lists with p elements, each of which is a list [xijk, yijk, zijk, fijk], representing the (x, y, z) coordinates and the function value of grid point (i, j, k).


The MESH structure represents surfaces in 3D space defined by a grid of values. It takes the form MESH(A) where A is a threedimensional Array. If you have an mbyn grid, then elements A[i, j, 1], A[i, j, 2] and A[i, j, 3] are the x, y and zcoordinates of grid point (i, j), for i in 1..m, j in 1..n. The Array A can be replaced by a list of the form [[[x11, y11, z11],...[x1n, y1n, z1n]], [[x21, y21, z21],...[x2n, y2n, z2n]],...[[xm1, ym1, zm1]...[xmn, ymn, zmn]] where [xij, yij, zij] is the location of grid point (i, j).



2D Plot Options



There are many options that control the rendering of 2D plots. These include:


The AXESLABELS structure contains two strings that are used to label the x and yaxes. It can also contain a FONT object defining the font used to render the labels.


Specifies the number, location, and labeling of the tickmarks on an axes. It contains two values (one for x and the other for y). Each value can be an integer, a list of numbers, a list of equations, or the special value DEFAULT. If the value is an integer, then the driver chooses tick locations such that there are at least as many labels as specified. If the value is a list of numbers, then ticks and labels are specified at exactly those values. If a list of equations is given, then the lefthand side of each equation must be a number and the righthand side a string. Ticks are placed at each specified number and labeled with the corresponding string. Axesticks can also contain a FONT object defining the font used to render the tick labels.


Controls the selection of the lines drawn for the axes on the plot. It can take the five values: BOX, FRAME, NORMAL, NONE, or DEFAULT. BOX axes consist of a rectangular box surrounding the plot with labels and tickmarks on the left and lower lines. FRAME axes style only draws the left and lower axes of the box style with their associated tickmarks and labels. NORMAL style draws two axes lines and attempts to have them intersect at the zero position on the axes. If 0 is not in the axes range, the axes intersect at the lower bound of the range. The NONE style results in no lines or labels and the DEFAULT style chooses a devicespecific axes style.


Specifies information about a single axis, with direction given by the integer n (1 for the xaxis and 2 for the yaxis). The _AXIS[n] structure can contain one of the following substructures:


Specifies a caption to be placed at the top of the plot, where c is any expression, string, or _TYPESET structure. The CAPTION object can also contain a FONT object defining the font used to render the caption.


Specifies the color of the axis. See the description of the general COLOR structure below.


_GRIDLINES(t) or _GRIDLINES(t, s)


Specifies information about gridlines.


This structure can have the form _GRIDLINES(t) or _GRIDLINES(t, s), where t is one of the values allowed for the AXESTICKS structure, described above, and s is a sequence of one or more of the following substructures:


The COLOR, LINESTYLE, and THICKNESS substructures take the same form as the general plot structures of the same name, except that LINESTYLE takes the additional argument _TICKS indicating that tickmarks rather than gridlines are to be displayed. The _MAJORLINES(n) with structure displays the nth gridline as a major line where n is a positive integer. The _SUBTICKS(t) structure displays subticks only if t is set to true.


Specifies the location of the axis, where n is 1, 0, or 1, representing "low", "origin", and "high", respectively. When n is 1 or 1, the axis is placed at the lowest or highest value of the view range. When n is 0, the axis is placed at the origin or at the closest value if the origin is not in the view range.


Specifies the scaling of the axis, where n is 0 or 1, representing linear and logarithmic, respectively.


The COLOR structure can be specified in three different ways: RGB, HSV, or HUE. The RGB color specification requires three floatingpoint values for each color. The three values must each be between 0 and 1 and specify the amount of red, green, and blue light in the final color. For example, COLOR(RGB, 1.0, 0.0, 0.0) is red, while COLOR(RGB, 1.0, 1.0, 0.0) is yellow. The HSV color specification also requires three numbers for each color. The fractional portion of the first value indicates the color and the remaining two values give the purity (saturation) and the brightness of the color. The latter two values must be between zero and one. The HUE color specification only requires a single floatingpoint value and cycles through the colors of the spectrum based on the fractional part of the value. For example, COLOR(HUE, 0.9) is violet, while COLOR(HUE, 0.0) is red. COLOR(HUE, x) is equivalent to COLOR(HSV, x, 0.9, 1.0). Multiple colors may be specified in a single COLOR structure. See the note at the end of this section on local options.


Specifies the font used in rendering TEXT objects. A font is specified by family, typeface, and size. Valid family and typeface combinations are (note that typeface default can be omitted):

Family

Typeface

SYMBOL


TIMES

ROMAN


BOLD


ITALIC


BOLDITALIC

COURIER

DEFAULT


BOLD


OBLIQUE


BOLDOBLIQUE

HELVETICA

DEFAULT


BOLD


OBLIQUE


BOLDOBLIQUE




Symbol font is used to produce Greek symbols. For a listing of which keys to use to produce the Greek symbols, see SYMBOL Font Keyboard Mapping.


Displays a legend that identifies the curves in a 2D plot. The legend l can be any expression, string, or _TYPESET structure.


Specifies the style of the legend, where ls is a sequence of FONT or LOCATION structures.


Specifies the dash pattern to be used when drawing line segments. It is often used to distinguish between different curves in a single image (see local options below). The line style value must be an integer from 1 to 7, corresponding to the following patterns: solid, dash, dot, dashdot, long dash, spacedot, and spacedash.


Takes one of the two values CONSTRAINED or UNCONSTRAINED. If scaling is constrained, then any transformations applied to the image must scale the x and y dimensions equally. The value DEFAULT can be used to select the device default scaling, usually unconstrained.


The actual rendering of the nonTEXT objects in a plot is controlled by the STYLE option setting. In 2D, there are 4 possible styles: POINT, LINE, PATCH, and PATCHNOGRID. The PATCH style which is the default, rendered points as symbols, curves as line segments, and polygons as filled regions with a border. The PATCHNOGRID style omits the border on polygons. The LINE style omits the filled interior of the polygons. The POINT style draws the endpoints of the curve line segments and the vertices of the polygons as symbols. Styles are specified by adding the function call STYLE(style), where style is one of the keywords above, to the PLOT structure.


Specifies the symbol to be used when drawing points. Currently supported values are _ASTERISK, BOX, CROSS, CIRCLE, POINT, _DIAGONALCROSS, DIAMOND, and DEFAULT. The values _SOLIDBOX, _SOLIDCIRCLE, and _SOLIDDIAMOND are also available for 2D plots only. A second argument to SYMBOL specifies the size (in points) of the symbol to be used for plotting. This is a nonnegative integer.


Controls the drawing of any line segments in the image resulting from the graphics primitives (not axes lines). The thickness setting is a nonnegative integer, with 0 representing the thinnest line, and increasing values specifying increasingly thick lines. The default value is 1.


Specifies a title to be placed at the top of the plot, where t is any expression, string, or _TYPESET structure. The TITLE object can also contain a FONT object defining the font used to render the title.


Controls the transparency of a plot object. The transparency is specified as TRANSPARENCY(n), where n is a floatingpoint number in the range 0.0 to 1.0 or the name DEFAULT. A value of 0.0 means "not transparent", while a value of 1.0 means "fully transparent".


Specifies text to be typeset and concatenated, where t is a sequence of arbitrary expressions or strings.

•

VIEW(xmin..xmax, ymin..ymax)


Contains two ranges that specify the subrange of the xy plane that is to be displayed. Either range can be replaced by DEFAULT, in which case the range is chosen to contain all elements in the picture.


Local Options  Where it is applicable, each of the above options can also be placed inside a POINTS, CURVES, TEXT, or POLYGONS object and overrides the global option for the rendering of that object. The COLOR option allows an additional format in this situation. In the case of an object having n subobjects (for example, multiple points, lines, or polygons), one color value can be supplied for each object. The structure then has the form COLOR(t, A) where A is a float[8] Array and t is one of RGB, HSV and HUE. If t is HUE, then A must have dimension 1..n. Otherwise, A must have dimensions 1..n, 1..3, with A[i,1], A[i,2], A[i,3] representing the RGB or HSV values for the ith color. For example, PLOT(POINTS(Array(1..2, 1..2, [[0, 0], [1, 1]], 'datatype'='float[8]', 'order'='C_order'), COLOR(RGB, Array(1..2, 1..3, [[1, 0, 0], [0, 1, 0]], 'datatype'='float[8]', 'order'='C_order'))), SYMBOL(_SOLIDCIRCLE, 30)) draws two points, one in red and the other in green.



3D Plot Options



Each of the 2D objects and options described in the section above are available in 3D plotting with the exception of the legend and gridline options. The extension of the 2D options to 3D is obvious in most cases. For example, points are specified with 3 values instead of 2. Several additional option structures are available and are described below.


Specifies the ambient light on the scene. It contains three numeric values between 0 and 1 specifying the intensity of the red, green, and blue components of the ambient light.


The _AXIS[n] structure, with n equal to 3, works the same way as described for n equal to 1 and 2, and is used to specify information for the zaxis. However, the _GRIDLINES substructure is ignored in 3D plots.


COLOR can take several extra keyword options for 3D plotting.


XYZSHADING, XYSHADING, and ZSHADING specify that an objects color is to be based on its coordinates. For XYZSHADING, color is based on x, y, and zcoordinates and varies over the surface. For XYSHADING, color is based on x and ycoordinates and varies over the surface. For ZSHADING, the color is based on the zcoordinate and varies over the surface.


ZHUE and ZGREYSCALE are modified forms of ZSHADING. For ZHUE, the color for a point is linearly related to the HUE value (range 0  1) based on the relative zcoordinate. For ZGREYSCALE, the relative value of the zcoordinate affects the red, green, and blue appearing at a point in the plot equally which renders the entire plot in shades of gray.


For specification of multiple colors, the COLOR(t, A) structure, where t is RGB, HSV or HUE, is similar to that for the 2D case, except that m by n GRID and MESH structures are also supported. In this situation, A must be an Array with datatype=float[8] and dimensions 1..m, 1..n when t is HUE, or 1..m, 1..n, 1..3 otherwise.


Controls the glossiness of a plotted surface. The glossiness is specified as _GLOSSINESS(g), where g is a floatingpoint number in the range 0.0 to 1.0 or the name DEFAULT. A value of 0.0 results in no light reflected while a value of 1.0 results in maximum reflection. The default value is 0.0. Reflections are rendered only if a point light source is enabled with the LIGHT or LIGHTMODEL structure.


During the rendering of GRID and MESH objects, they are broken down into rectangles and then further split into triangles. When overlaying the grid on the surface, either the rectangular or the triangular breakdown can be shown. GRIDSTYLE(TRIANGULAR) shows the triangular grid, while GRIDSTYLE(RECTANGULAR) omits the diagonal line to form a rectangular grid.

•

LIGHT(phi, theta, r, g, b)


Specifies the direction and intensity of a directed light shining on the scene. The first two numeric values specify the direction to the light in polar coordinates using angles specified in degrees. The next three numeric values specify the intensity in the same manner as AMBIENTLIGHT.


Allows the user to select from several userdefined lighting schemes. The allowed schemes are USER, LIGHT_1, LIGHT_2, LIGHT_3 and LIGHT_4. USER specifies that the light definitions given in the LIGHT and AMBIENTLIGHT options are to be used.

•

ORIENTATION(theta, phi, psi)


Specifies the angles in degrees defining the orientation of the plot, obtained by rotating the plot psi about the xaxis, then phi about the (transformed) zaxis, and then theta about the (transformed) yaxis. These angles, given in degrees, are the Euler angles for the transformation matrix. The angle psi is optional and is assumed to be 0 if not given.


Specifies the perspective from which the surface is viewed, where r is a real number in the range 0..1. The value 1 represents orthogonal projection while the value 0 represents wideangle perspective rendering.


Style can take several extra keyword options for 3D plotting. HIDDEN specifies that the interior of polygons are not to be drawn but that they are to obscure objects behind them. CONTOUR and PATCHCONTOUR specify that contour lines for polygons and surfaces are to be shown (with or without patches).



Animation



The ANIMATE structure contains lists of plot objects and options. Each list defines one frame in the animation and the frames are displayed in sequence on the output device. The options specified in each list override any options specified for the entire plot while the frame is being rendered. By specifying options within the lists for each frame, it is possible to move the lights and the viewpoint during an animation.



