PLOT and PLOT3D Data Structures
Important: This page describes the internal structures used by Maple to construct 2-D and 3-D 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 2-D. 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.
2-D and 3-D Plot Objects
There are four different object types for 2-D plotting: curves, points, polygons, and text. These four are also available for 3-D plotting. In addition, grid, mesh, and isosurface structures can be used in 3-D plots.
When data is provided as an Array or Matrix, the Array or Matrix must have datatype equal to float. Furthermore, all indices in the Array must start at 1. When data is provided as a list, the elements must be floating-point values.
CURVES(A1, A2, ...)
The CURVES structure defines one or more curves in 2-D or 3-D space, formed by joining a sequence of sample points. Each 2-D 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 3-D 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 2-D or 3-D points, represented by A. For points in 2-D, 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 3-D, 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].
POLYGONS(A1, A2, ...)
The POLYGONS structure defines one or more polygons in 2-D or 3-D space. The format of each A1, A2, ... is identical to that described for the CURVES structure.
TEXT(A, t, horizontal, vertical)
The TEXT structure defines a text element in 2-D or 3-D space. In 2-D, the point A is a list [x, y], while in 3-D, A is a list [x, y, z]. The t value can be any expression, string, or _TYPESET structure. The horizontal value can be one of the two keywords ALIGNLEFT or ALIGNRIGHT, in which case t 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, t is centered in the appropriate dimension.
GRID(a..b, c..d, A)
The GRID structure represents surfaces in 3-D 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 x-range, c..d is the y-range, and A is a two-dimensional Array. If you have an m-by-n 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 3-D space and is rendered as a 3-D surface approximating the zero surface of the function. The ISOSURFACE structure takes the form ISOSURFACE(A) where A is a four-dimensional Array. If you have an m-by-n-by-p 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 3-D space defined by a grid of values. It takes the form MESH(A) where A is a three-dimensional Array. If you have an m-by-n grid, then elements A[i, j, 1], A[i, j, 2] and A[i, j, 3] are the x-, y- and z-coordinates 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).
2-D Plot Options
There are many options that control the rendering of 2-D plots. These include:
The AXESLABELS structure contains two labels for the x- and y-axes. Each one can be any expression, string, or _TYPESET structure. The AXESLABELS structure 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 left-hand side of each equation must be a number and the right-hand side an expression, string or _TYPESET structure. Ticks are placed at each specified number and labeled with the corresponding text. 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 device-specific axes style.
Specifies information about a single axis, with direction given by the integer n (1 for the x-axis and 2 for the y-axis). The _AXIS[n] structure can contain one of the following substructures:
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) structure displays the n-th 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.
_TICKMARKS(t) or _TICKMARKS(t, s)
Specifies information about tickmarks. This structure takes the same arguments as the _GRIDLINES structure described above, except that the _MAJORLINES suboption is not available.
Specifies a caption to be placed at the bottom of the plot, where c is any expression, string, or _TYPESET structure. The CAPTION object can also contain an optional FONT object f defining the font used to render the caption.
The COLOR structure can be specified in three different ways: RGB, HSV, or HUE. The RGB color specification requires three floating-point 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 floating-point 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):
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 2-D 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, dot, dash, dash-dot, long dash, space-dash, and space-dot.
Takes one of the values: CONSTRAINED, UNCONSTRAINED or DEFAULT. 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 non-TEXT objects in a plot is controlled by the STYLE option setting. In 2-D, there are 5 possible styles: LINE, PATCH, PATCHNOGRID, POINT and POINTLINE. The PATCH style which is the default, renders 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. The POINTLINE style combines the features of the POINT and LINE styles. 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, _DIAGONALCROSS, DIAMOND, POINT, _SOLIDBOX, _SOLIDCIRCLE, _SOLIDDIAMOND, _SOLIDSPHERE, SPHERE and DEFAULT. _SOLIDSPHERE and SPHERE are available for 3-D plots only. A second argument to SYMBOL specifies the size (in points) of the symbol to be used for plotting. This is a non-negative integer.
Controls the drawing of any line segments in the image resulting from the graphics primitives (not axes lines). The thickness setting is a non-negative 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 an optional FONT object f 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 floating-point 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.
Contains two ranges that specify the subrange of the x-y 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 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 i-th color. For example, PLOT(POINTS(Array(1..2, 1..2, [[0, 0], [1, 1]], 'datatype'='float', 'order'='C_order'), COLOR(RGB, Array(1..2, 1..3, [[1, 0, 0], [0, 1, 0]], 'datatype'='float', 'order'='C_order'))), SYMBOL(_SOLIDCIRCLE, 30)) draws two points, one in red and the other in green.
3-D Plot Options
Each of the 2-D objects and options described in the section above are available in 3-D plotting with the exception of the legend and gridline options. The extension of the 2-D options to 3-D 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.
AMBIENTLIGHT(r, g, b)
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 z-axis. However, the _GRIDLINES substructure is ignored in 3-D plots.
COLOR can take several extra keyword options for 3-D 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 z-coordinates and varies over the surface. For XYSHADING, color is based on x- and y-coordinates and varies over the surface. For ZSHADING, the color is based on the z-coordinate 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 z-coordinate. For ZGREYSCALE, the relative value of the z-coordinate 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 2-D case, except that m by n GRID and MESH structures are also supported. In this situation, A must be an Array with datatype=float 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 floating-point 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 user-defined 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 x-axis, then phi about the (transformed) y-axis, and then theta about the (transformed) z-axis. 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 wide-angle perspective rendering.
Style can take several extra keyword options for 3-D 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).
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.
Download Help Document