draw (Maxima Manual)

42 draw

Introduction to draw
Functions and Variables for draw
Functions and Variables for pictures
Functions and Variables for worldmap

42.1 Introduction to draw

draw is a Maxima-Gnuplot interface.

There are three main functions to be used at Maxima level: draw2d, draw3d and draw.

Follow this link for more elaborated examples of this package:

http://riotorto.users.sourceforge.net/gnuplot

You need Gnuplot 4.2 or newer to run this program.

42.2.1 Scenes

Scene constructor: gr2d (graphic option, …, graphic object, …) ¶

Function gr2d builds an object describing a 2D scene. Arguments are graphic options, graphic objects, or lists containing both graphic options and objects. This scene is interpreted sequentially: graphic options affect those graphic objects placed on its right. Some graphic options affect the global appearence of the scene.

This is the list of graphic objects available for scenes in two dimensions:

bars, ellipse, explicit, image, implicit, label, parametric, points, polar, polygon, quadrilateral, rectangle, triangle, vector, and geomap (this one defined in package worldmap).

See also draw and draw2d. To make use of this object, write first load("draw").

Scene constructor: gr3d (graphic option, …, graphic object, …) ¶

Function gr3d builds an object describing a 3d scene. Arguments are graphic options, graphic objects, or lists containing both graphic options and objects. This scene is interpreted sequentially: graphic options affect those graphic objects placed on its right. Some graphic options affect the global appearence of the scene.

This is the list of graphic objects available for scenes in three dimensions:

cylindrical, elevation_grid, explicit, implicit, label, mesh, parametric, parametric_surface, points, quadrilateral, spherical, triangle, tube, vector, and geomap (this one defined in package worldmap).

See also draw and draw3d. To make use of this object, write first load("draw").

42.2.2 Functions

Function: draw (gr2d, …, gr3d, …, options, …) ¶

Plots a series of scenes; its arguments are gr2d and/or gr3d objects, together with some options, or lists of scenes and options. By default, the scenes are put together in one column.

Function draw accepts the following global options: terminal, columns, dimensions, file_name and delay.

Functions draw2d and draw3d are short cuts to be used when only one scene is required, in two or three dimensions, respectively.

See also gr2d and gr3d. To make use of this function, write first load("draw").

Example:

(%i1) load("draw")$
(%i2) scene1: gr2d(title="Ellipse",
                   nticks=30,
                   parametric(2*cos(t),5*sin(t),t,0,2*%pi))$
(%i3) scene2: gr2d(title="Triangle",
                   polygon([4,5,7],[6,4,2]))$
(%i4) draw(scene1, scene2, columns = 2)$

The two draw sentences are equivalent:

(%i1) load("draw")$
(%i2) draw(gr3d(explicit(x^2+y^2,x,-1,1,y,-1,1)));
(%o2)                          [gr3d(explicit)]
(%i3) draw3d(explicit(x^2+y^2,x,-1,1,y,-1,1));
(%o3)                          [gr3d(explicit)]

An animated gif file:

(%i1) load("draw")$
(%i2) draw(
        delay     = 100,
        file_name = "zzz",
        terminal  = 'animated_gif,
        gr2d(explicit(x^2,x,-1,1)),
        gr2d(explicit(x^3,x,-1,1)),
        gr2d(explicit(x^4,x,-1,1)));
End of animation sequence
(%o2)          [gr2d(explicit), gr2d(explicit), gr2d(explicit)]

See also gr2d, gr3d, draw2d and draw3d.

Function: draw2d (option, graphic_object, …) ¶

This function is a short cut for draw(gr2d(options, ..., graphic_object, ...)).

It can be used to plot a unique scene in 2d.

To make use of this function, write first load("draw").

42.2.3 Graphics options

Graphic option: adapt_depth ¶

Default value: 10

adapt_depth is the maximum number of splittings used by the adaptive plotting routine.

This option is relevant only for 2d explicit functions.

Graphic option: axis_3d ¶

Default value: true

If axis_3d is true, the x, y and z axis are shown in 3d scenes.

Since this is a global graphics option, its position in the scene description does not matter.

Example:

(%i1) load("draw")$
(%i2) draw3d(axis_3d = false,
             explicit(sin(x^2+y^2),x,-2,2,y,-2,2) )$

See also axis_bottom, axis_left, axis_top, and axis_right for axis in 2d.

Graphic option: axis_bottom ¶

Default value: true

If axis_bottom is true, the bottom axis is shown in 2d scenes.

Since this is a global graphics option, its position in the scene description does not matter.

Example:

(%i1) load("draw")$
(%i2) draw2d(axis_bottom = false,
             explicit(x^3,x,-1,1))$

See also axis_left, axis_top, axis_right, and axis_3d.

Graphic option: axis_left ¶

Default value: true

If axis_left is true, the left axis is shown in 2d scenes.

Since this is a global graphics option, its position in the scene description does not matter.

Example:

(%i1) load("draw")$
(%i2) draw2d(axis_left = false,
             explicit(x^3,x,-1,1))$

See also axis_bottom, axis_top, axis_right, and axis_3d.

Graphic option: axis_right ¶

Default value: true

If axis_right is true, the right axis is shown in 2d scenes.

Since this is a global graphics option, its position in the scene description does not matter.

Example:

(%i1) load("draw")$
(%i2) draw2d(axis_right = false,
             explicit(x^3,x,-1,1))$

See also axis_bottom, axis_left, axis_top, and axis_3d.

Graphic option: axis_top ¶

Default value: true

If axis_top is true, the top axis is shown in 2d scenes.

Since this is a global graphics option, its position in the scene description does not matter.

Example:

(%i1) load("draw")$
(%i2) draw2d(axis_top = false,
             explicit(x^3,x,-1,1))$

See also axis_bottom, axis_left, axis_right, and axis_3d.

Graphic option: background_color ¶

Default value: white

Sets the background color for terminals gif, png, jpg, and gif. Default background color is white.

This option das not work with terminals epslatex and epslatex_standalone.

42.2.4 Graphics objects

Graphic object: bars ([x1, h1, w1], [x2, h2, w2, …]) ¶

Draws vertical bars in 2D.

bars([x1, h1, w1], [x2, h2, w2, ...]) draws bars centered at values x1, x2, … with heights h1, h2, … and widths w1, w2, …

This object is affected by the following graphic options: key, fill_color, fill_density and line_width.

Example:

(%i1) load("draw")$
(%i2) draw2d(
       key          = "Group A",
       fill_color   = blue,
       fill_density = 0.2,
       bars([0.8,5,0.4],[1.8,7,0.4],[2.8,-4,0.4]),
       key          = "Group B",
       fill_color   = red,
       fill_density = 0.6,
       line_width   = 4,
       bars([1.2,4,0.4],[2.2,-2,0.4],[3.2,5,0.4]),
       xaxis = true);

Graphic object: cylindrical (radius, z, minz, maxz, azi, minazi, maxazi) ¶

Draws 3D functions defined in cylindrical coordinates.

cylindrical(radius, z, minz, maxz, azi, minazi, maxazi) plots function radius(z, azi) defined in cylindrical coordinates, with variable z taking values from minz to maxz and azimuth azi taking values from minazi to maxazi.

This object is affected by the following graphic options: xu_grid, yv_grid, line_type, key, wired_surface, enhanced3d and color.

Example:

(%i1) load("draw")$
(%i2) draw3d(cylindrical(1,z,-2,2,az,0,2*%pi))$

Graphic object: elevation_grid (mat, x0, y0, width, height) ¶

Draws matrix mat in 3D space. z values are taken from mat, the abscissas range from x0 to x0 + width and ordinates from y0 to y0 + height. Element a(1,1) is projected on point (x0,y0+height), a(1,n) on (x0+width,y0+height), a(m,1) on (x0,y0), and a(m,n) on (x0+width,y0).

This object is affected by the following graphic options: line_type, line_width, key, wired_surface, enhanced3d, and color.

In older versions of Maxima, elevation_grid was called mesh. See also mesh.

Example:

(%i1) load("draw")$
(%i2) m: apply(
            matrix,
            makelist(makelist(random(10.0),k,1,30),i,1,20)) $
(%i3) draw3d(
         color = blue,
         elevation_grid(m,0,0,3,2),
         xlabel = "x",
         ylabel = "y",
         surface_hide = true);

Graphic object: ellipse (xc, yc, a, b, ang1, ang2) ¶

Draws ellipses and circles in 2D.

ellipse (xc, yc, a, b, ang1, ang2) plots an ellipse centered at [xc, yc] with horizontal and vertical semi axis a and b, respectively, starting at angle ang1 with an amplitude equal to angle ang2.

This object is affected by the following graphic options: nticks, transparent, fill_color, border, line_width, line_type, key and color.

Example:

(%i1) load("draw")$
(%i2) draw2d(transparent = false,
             fill_color  = red,
             color       = gray30,
             transparent = false,
             line_width  = 5,
             ellipse(0,6,3,2,270,-270),
             /* center (x,y), a, b, start & end in degrees */
             transparent = true,
             color       = blue,
             line_width  = 3,
             ellipse(2.5,6,2,3,30,-90),
             xrange      = [-3,6],
             yrange      = [2,9] )$

Graphic object: errors ([x1, x2, …], [y1, y2, …]) ¶

Draws points with error bars, horizontally, vertically or both, depending on the value of option error_type.

If error_type = x, arguments to errors must be of the form [x, y, xdelta] or [x, y, xlow, xhigh]. If error_type = y, arguments must be of the form [x, y, ydelta] or [x, y, ylow, yhigh]. If error_type = xy or error_type = boxes, arguments to errors must be of the form [x, y, xdelta, ydelta] or [x, y, xlow, xhigh, ylow, yhigh].

42.3 Functions and Variables for pictures

Function: get_pixel (pic, x, y) ¶: Returns pixel from picture. Coordinates x and y range from 0 to width-1 and height-1, respectively.

Function: make_level_picture (data) ¶

Function: make_level_picture (data, width, height) ¶

Returns a levels picture object. make_level_picture(data) builds the picture object from matrix data. make_level_picture(data, width, height) builds the object from a list of numbers; in this case, both the width and the height must be given.

The returned picture object contains the following four parts:

symbol level
image width
image height
an integer array with pixel data ranging from 0 to 255. Argument data must contain only numbers ranged from 0 to 255; negative numbers are substituted by 0, and those which are greater than 255 are set to 255.

Example:

Level picture from matrix.

(%i1) load("draw")$
(%i2) make_level_picture(matrix([3,2,5],[7,-9,3000]));
(%o2)         picture(level, 3, 2, {Array:  #(3 2 5 7 0 255)})

Level picture from numeric list.

(%i1) load("draw")$
(%i2) make_level_picture([-2,0,54,%pi],2,2);
(%o2)            picture(level, 2, 2, {Array:  #(0 0 54 3)})

Function: make_rgb_picture (redlevel, greenlevel, bluelevel) ¶

Returns an rgb-coloured picture object. All three arguments must be levels picture; with red, green and blue levels.

The returned picture object contains the following four parts:

symbol rgb
image width
image height
an integer array of length 3*width*height with pixel data ranging from 0 to 255. Each pixel is represented by three consecutive numbers (red, green, blue).

Example:

(%i1) load("draw")$
(%i2) red: make_level_picture(matrix([3,2],[7,260]));
(%o2)           picture(level, 2, 2, {Array:  #(3 2 7 255)})
(%i3) green: make_level_picture(matrix([54,23],[73,-9]));
(%o3)           picture(level, 2, 2, {Array:  #(54 23 73 0)})
(%i4) blue: make_level_picture(matrix([123,82],[45,32.5698]));
(%o4)          picture(level, 2, 2, {Array:  #(123 82 45 33)})
(%i5) make_rgb_picture(red,green,blue);
(%o5) picture(rgb, 2, 2, 
              {Array:  #(3 54 123 2 23 82 7 73 45 255 0 33)})

Function: negative_picture (pic) ¶: Returns the negative of a (level or rgb) picture.

Function: picture_equalp (x,y) ¶: Returns true in case of equal pictures, and false otherwise.

Function: picturep (x) ¶: Returns true if the argument is a well formed image, and false otherwise.

Function: read_xpm (xpm_file) ¶: Reads a file in xpm and returns a picture object.

Function: rgb2level (pic) ¶: Transforms an rgb picture into a level one by averaging the red, green and blue channels.

Function: take_channel (im,color) ¶

If argument color is red, green or blue, function take_channel returns the corresponding color channel of picture im.

Example:

(%i1) load("draw")$
(%i2) red: make_level_picture(matrix([3,2],[7,260]));
(%o2)           picture(level, 2, 2, {Array:  #(3 2 7 255)})
(%i3) green: make_level_picture(matrix([54,23],[73,-9]));
(%o3)           picture(level, 2, 2, {Array:  #(54 23 73 0)})
(%i4) blue: make_level_picture(matrix([123,82],[45,32.5698]));
(%o4)          picture(level, 2, 2, {Array:  #(123 82 45 33)})
(%i5) make_rgb_picture(red,green,blue);
(%o5) picture(rgb, 2, 2, 
              {Array:  #(3 54 123 2 23 82 7 73 45 255 0 33)})
(%i6) take_channel(%,'green);  /* simple quote!!! */
(%o6)           picture(level, 2, 2, {Array:  #(54 23 73 0)})

42.4 Functions and Variables for worldmap

This package automatically loads package draw.

Variables and Functions
Graphic objects

42.4.1 Variables and Functions

Global variable: boundaries_array ¶

Default value: false

boundaries_array is where the graphic object geomap looks for boundaries coordinates.

Each component of boundaries_array is an array of floating point quantities, the coordinates of a polygonal segment or map boundary.

42.4.2 Graphic objects

Graphic object: geomap (numlist) ¶

Graphic object: geomap (numlist, 3Dprojection) ¶

Draws cartographic maps in 2D and 3D.

This function works together with global variable boundaries_array.

Argument numlist is a list containing numbers or lists of numbers. All these numbers must be integers greater or equal than zero, representing the components of global array boundaries_array.

Each component of boundaries_array is an array of floating point quantities, the coordinates of a polygonal segment or map boundary.

geomap (numlist) flattens its arguments and draws the associated boundaries in boundaries_array.

This object is affected by the following graphic options: line_width, line_type and color.

Examples:

A simple map defined by hand:

(%i1) load("worldmap")$
(%i2) /* Vertices of boundary #0: {(1,1),(2,5),(4,3)} */
   ( bnd0: make_array(flonum,6),
     bnd0[0]:1.0, bnd0[1]:1.0, bnd0[2]:2.0,
     bnd0[3]:5.0, bnd0[4]:4.0, bnd0[5]:3.0 )$
(%i3) /* Vertices of boundary #1: {(4,3),(5,4),(6,4),(5,1)} */
   ( bnd1: make_array(flonum,8),
     bnd1[0]:4.0, bnd1[1]:3.0, bnd1[2]:5.0, bnd1[3]:4.0,
     bnd1[4]:6.0, bnd1[5]:4.0, bnd1[6]:5.0, bnd1[7]:1.0)$
(%i4) /* Vertices of boundary #2: {(5,1), (3,0), (1,1)} */
   ( bnd2: make_array(flonum,6),
     bnd2[0]:5.0, bnd2[1]:1.0, bnd2[2]:3.0,
     bnd2[3]:0.0, bnd2[4]:1.0, bnd2[5]:1.0 )$
(%i5) /* Vertices of boundary #3: {(1,1), (4,3)} */
   ( bnd3: make_array(flonum,4),
     bnd3[0]:1.0, bnd3[1]:1.0, bnd3[2]:4.0, bnd3[3]:3.0)$
(%i6) /* Vertices of boundary #4: {(4,3), (5,1)} */
   ( bnd4: make_array(flonum,4),
     bnd4[0]:4.0, bnd4[1]:3.0, bnd4[2]:5.0, bnd4[3]:1.0)$
(%i7) /* Pack all together in boundaries_array */
   ( boundaries_array: make_array(any,5),
     boundaries_array[0]: bnd0, boundaries_array[1]: bnd1,
     boundaries_array[2]: bnd2, boundaries_array[3]: bnd3,
     boundaries_array[4]: bnd4 )$
(%i8) draw2d(geomap([0,1,2,3,4]))$

The auxiliary package worldmap sets the global variable boundaries_array to the real world boundaries in coordinates. The data is in the public domain and come from http://www-cger.nies.go.jp/grid-e/gridtxt/grid19.html. The package worldmap defines also boundaries for countries, continents and coastlines as lists with the necessary components of boundaries_array (see file share/draw/worldmap.mac for more information). The package worldmap automatically loads package worldmap.

(%i1) load("worldmap")$
(%i2) c1: gr2d(geomap([Canada,United_States,
                       Mexico,Cuba]))$
(%i3) c2: gr2d(geomap(Africa))$
(%i4) c3: gr2d(geomap(Oceania,China,Japan))$
(%i5) c4: gr2d(geomap([France,Portugal,Spain,
                       Morocco,Western_Sahara]))$
(%i6) draw(columns  = 2,
           c1,c2,c3,c4)$

Package worldmap is also useful for plotting countries as polygons. In this case, graphic object geomap is no longer necessary and the polygon object is used instead. Since lists are now used and not arrays, maps rendering will be slower. See also make_poly_country and make_poly_continent to understand the following code.

(%i1) load("worldmap")$
(%i2) mymap: append(
   [color      = white],  /* borders are white */
   [fill_color = red],             make_poly_country(Bolivia),
   [fill_color = cyan],            make_poly_country(Paraguay),
   [fill_color = green],           make_poly_country(Colombia),
   [fill_color = blue],            make_poly_country(Chile),
   [fill_color = "#23ab0f"],       make_poly_country(Brazil),
   [fill_color = goldenrod],       make_poly_country(Argentina),
   [fill_color = "midnight-blue"], make_poly_country(Uruguay))$
(%i3) apply(draw2d, mymap)$

geomap(numlist) projects map boundaries on the sphere of radius 1 centered at (0,0,0). It is possible to change the sphere or the projection type by using geomap(numlist,3Dprojection).

Available 3D projections:

[spherical_projection,x, y, z, r]: projects map boundaries on the sphere of radius r centered at (x, y, z).

(%i1) load("worldmap")$
(%i2) draw3d(geomap(Australia), /* default projection */
             geomap(Australia,
                    [spherical_projection,2,2,2,3]))$

[cylindrical_projection, x, y, z, r, rc]: re-projects spherical map boundaries on the cylinder of radius rc and axis passing through the poles of the globe of radius r centered at (x, y, z).
```
(%i1) load("worldmap")$
(%i2) draw3d(geomap([America_coastlines,Eurasia_coastlines],
                    [cylindrical_projection,2,2,2,3,4]))$
```
[conic_projection, x, y, z, r, alpha]: re-projects spherical map boundaries on the cones of angle alpha, with axis passing through the poles of the globe of radius r centered at (x, y, z). Both the northern and southern cones are tangent to sphere.
```
(%i1) load("worldmap")$
(%i2) draw3d(geomap(World_coastlines,
                    [conic_projection,0,0,0,1,90]))$
```

See also https://riotorto.users.sourceforge.net/Maxima/gnuplot/geomap/ for more elaborated examples.