Plotting
********

Definitions for Plotting
========================

 -- Function: CLOSEPS ()
     This should usually becalled at the end of a sequence of plotting
     commands.   It closes the current output stream PSTREAM, and sets
     it to nil.   It also may be called at the start of a plot, to ensure
     pstream is closed if it was open.    All commands which write to
     pstream, open it if necessary.   CLOSEPS is separate from the other
     plotting commands, since we may want to plot 2 ranges or superimpose
     several plots, and so must keep the stream open.

 -- Variable: PLOT_OPTIONS
     Members of this list indicate defaults for plotting.  They may be altered using SET_PLOT_OPTION

          [X, - 3, 3]
          [Y, - 3, 3]

     are the x range and y range respectively.

     [TRANSFORM_XY, FALSE] if not false, should be the output of

          make_transform([x,y,z], [f1(x,y,z),f2(x,y,z),f3(x,y,z)])

     which produces a transformation from 3 space to 3 space, which will be applied to the graph.   A built in one is polar_xy which gives the same as

          make_transform([r,th,z],[r*cos(th),r*sin(th),z])

     [RUN_VIEWER,TRUE] if not false, means run the viewer software dont just output a data file.

     [GRID,30,30] means plot3d should divide the x range into 30 intervals and similarly the y range.

     [COLOUR_Z,false] aplies to colouring done with plot_format ps.

     [PLOT_FORMAT,ZIC] is for plot3d and currently  ZIC, GNUPLOT, PS, and GEOMVIEW are supported.

     There are good quality public domain viewers for these formats. They are izic, gnuplot, ghostview, and geomview.

     izic is available by ftp from zenon.inria.fr.  Contact one of

     {fournier,kajler,mourrain}@sophia.inria.fr.

     It has beautiful colour gouraud shading, and very fast wireframe.   It runs on X windows.

     geomview is from the geometry institute in minnesota, and is available by anonymous ftp from there.   It is currently not quite as pretty as izic, but provides excellent support for multiple objects and multiple lights.

     gnuplot is everywhere as is ghostview.   We also provide mgnuplot a tcl interface for gnuplot, which lets you rotate the plots using the mouse and a scale.

 -- Function: PLOT3D (expr,xrange,yrange,...,options,..)
 -- Function: PLOT3D ([expr1,expr2,expr3],xrange,yrange,...,options,..)

          plot3d(2^(-u^2+v^2),[u,-5,5],[v,-7,7]);

     would plot z = 2^(-u^2+v^2) with u and v varying in [-5,5] and [-7,7] respectively, and with u on the x axis, and v on the y axis.

     An example of the second pattern of arguments is

          plot3d([cos(x)*(3+y*cos(x/2)),sin(x)*(3+y*cos(x/2)),y*sin(x/2)],
             [x,-%pi,%pi],[y,-1,1],['grid,50,15])

     which will plot a moebius band, parametrized by the 3 expressions given as the first argument to plot3d.  An additional optional argument [grid,50,15] gives the grid number of rectangles in the x direction and y direction.

          /* REal part of z ^ 1/3 */
           plot3d(r^.33*cos(th/3),[r,0,1],[th,0,6*%pi],
               ['grid,12,80],['plot_format,ps],
               ['transform_xy,polar_to_xy],['view_direction,1,1,1.4],
               ['colour_z,true])

     Here the View_direction indicates the direction from which we take a projection.  We actually do this from infinitely far away, but parallel to the line from view_direction to the origin.  This is currently only used in 'ps' plot_format, since the other viewers allow interactive rotating of the object.

     Another example is a moebius band:

          plot3d([cos(x)*(3+y*cos(x/2)),
                    sin(x)*(3+y*cos(x/2)),y*sin(x/2)],
                     [x,-%pi,%pi],[y,-1,1],['grid,50,15]);

     or a klein bottle:

          plot3d([5*cos(x)*(cos(x/2)*cos(y)+sin(x/2)*sin(2*y)+3.0) - 10.0,
                    -5*sin(x)*(cos(x/2)*cos(y)+sin(x/2)*sin(2*y)+3.0),
                     5*(-sin(x/2)*cos(y)+cos(x/2)*sin(2*y))],
                     [x,-%pi,%pi],[y,-%pi,%pi],['grid,40,40])

     or a torus

          plot3d([cos(y)*(10.0+6*cos(x)),
                     sin(y)*(10.0+6*cos(x)),
                     -6*sin(x)], [x,0,2*%pi],[y,0,2*%pi],
                      ['grid,40,40])

     We can output to gnplot too:

           plot3d(2^(x^2-y^2),[x,-1,1],[y,-2,2],[plot_format,gnuplot])

 -- Function: PLOT2D_PS (expr,range)
     writes to pstream a sequence of postscript commands which plot EXPR for RANGE. EXPR should be an expression of 1 variable. RANGE should be of the form [variable,min,max] over which to plot expr. see CLOSEPS.

 -- Function: PLOT2D (expr,range,...,options,..)
 -- Function: PLOT2D ([expr1,expr2,..,exprn],xrange,...,options,..)
     EXPR is an expression to be plotted on y axis as a function of 1 variable. RANGE is of the form [var,min,max] and expr is assumed to be an expression to be plotted against VAR. In the second form of the function a list of expressions may be given to plot against.   Truncation in the y direction will be performed, for the default y range.   It may be specified as an option or using SET_PLOT_OPTION.

          plot2d(sin(x),[x,-5,5]);
          plot2d(sec(x),[x,-2,2],[y,-20,20],[nticks,200]);

 -- Function: xgraph_curves(list)
     graphs the list of `point sets' given in list by using xgraph.

     A point set may be of the form

          [x0,y0,x1,y1,x2,y2,...] or
          [[x0,y0],[x1,y1],....]

     A point set may also contain symbols which give labels or other information.

           xgraph_curves([pt_set1,pt_set2,pt_set3]);

     would graph the three point sets as three curves.

          pt_set:append(["NoLines: True","LargePixels: true"],
                  [x0,y0,x1,y1,...])

     would make the point set [and subsequent ones], have no lines between points, and to use large pixels. See the man page on xgraph for more options to specify.

          pt_set:append([concat("\"","x^2+y")],[x0,y0,x1,y1,...])

     would make there be a "label" of "x^2+y" for this particular point set.    The " at the beginning is what tells xgraph this is a label.

          pt_set:append([concat("TitleText: Sample Data")],[x0,...])

     would make the main title of the plot be "Sample Data" instead of "Maxima PLot".

     A temporary file xgraph-out is used.

 -- Function: SET_PLOT_OPTION (option)
     option is of the format of one of the elements of the PLOT_OPTIONS list. Thus

          SET_PLOT_OPTION([grid,30,40])

     would change the default grid used by plot3d.   Note that if the symbol grid has a value, then you should quote it here:

          SET_PLOT_OPTION(['grid,30,40])

     so that the value will not be substituted.

 -- Function: PSDRAW_CURVE (ptlist)

     Draws a curve connecting the points in PTLIST.   The latter may be of the form [x0,y0,x1,y1,...] or [[x0,y0],[x1,y1],...] The function JOIN is handy for taking a list of x's and a list of y's and splicing them together. PSDRAW_CURVE simply invokes the more primitive function PSCURVE.   Here is the definition:

          (defun $psdraw_curve (lis)
            (p "newpath")
            ($pscurve lis)
            (p "stroke"))

     ?DRAW2D  may also be used to produce a list

           points1:?draw2d(1/x,[.05,10],.03)

 -- Function: PSCOM (com)

     COM will be inserted in the poscript file eg

            pscom("4.5 72 mul 5.5 72 mul translate  14 14 scale");