XPLOT Tutorial

Maorong Zou

February 9, 1994

What Is Xplot

Xplot is an interactive 3D plotting program for X windows. It is capable of displaying simple objects that have easily described geometries. Currently, it only runs on 8bit pseudo color visuals. The way of using xplot is as follows. First one defines the object by specifying its geometry. Then plot it. Once an object is displayed on the screen, its appearance can be modified interactively by mouse input.

About This Document

This document is a simple tutorial introduction to xplot. It will show you, by examples, how to use the program. You need a color X terminal to run xplot.

Installation

Just copy the two executable xplot into a place that is in your search path, usually this is /usr/local/bin or /public/bin.

Comments

Comments are welcome. Please direct them to mzou@math.utexas.edu.

Getting Started With Xplot

To invoke xplot, just type xplot in an xterm window. After you have done this, you will see the following message: 

     X P L O T,  Version Beta  Feb.  9 1994
     Maorong Zou, Dept. of Math. UT Austin       

In[1]:
This means xplot has been succesfully loaded and it is ready for your inputs.

Your First Plot

Let us first plot a very simple harmonic wave function defined by sin(x)cos(y), x,y in [-pi,pi]. The following line defines an xplot object for the above surface. 
In[1]: ex1 =surface{[sin(x)*cos(y)][x: -pi,pi][y: -pi,pi]};
After the above line has been entered, an object called ex1 is defined (assuming there are no syntax errors). To plot it, just enter the following command. 
In[2]: plot ex1;
In just a few seconds, a window will pop out and the object ex1 is displayed in it with the default graphics attributes.

Take A Different View

Having our surface displayed on the screen, you might want to take a different view of it. There are many ways to do this, we can rotate, translate or scale the objeect.

Move the mouse into the main display window, press the left button and move the pointer around. Notice how the object moves. The left button is tied to rotation about the screen axis. The middle button is tied to screen translation and the right button is binded to scaling.

The object can also be transformed by sliding the three sliders around the main display window. These sliders are controled by the first six menu buttons on the bottom of the display window. Among which the C Slider button is probably the most useful one, it resets all sliders to their center position. Initially, the sliders are binded to rotations about the screen coordinates.

You may have noticed that when you move the object, only part of it is visiable. This is a feature designed to make intermediate transition between frames smooth. You can disable this feature by pressing the Fast button once.

In case you lose your object, there is a button in the lower right corner called Reset View , push it once will undo all the translations. You can also look at the top right window to see where is your object. The part inside the yellow box is the visible part of your object.

Modify the Appearance of the Object

At startup, there are 10 gadgets on the bottom right region of the window (which will be called the gadget panel thereafter). The first five, namely Filled Polygon , Wire over Poly , Wireframe Only , Zbuffered Wire and Box on control the display mode. These buttons are really self-explainary. The next four buttons control the lighting mode. By default, xplot uses a fixed light source. You can toggle to either a moving light source (moving with the object, so the color of the object will not change when moved) or a depthcue coloring. Both of the latter coloring schemes are faster than the default. The depthcue shading is particully useful when your object consists of curves only.

Change the Color of the Object

On the top menubar, there is a menu called Materials , you can choose any of the ten or so predefined materials. However you can use at most two of them at the same time. I.e., when multiple objects are displayed, you can use only two different materials.

When the Material menu button is pressed, the gadget panel will be updated. You can modify many of the material properties there by pressing buttons and/or sliding sliders.

You can also change the background color and the light source by pressing the Light menu button and modifying the corresponding gadgets in the gadget panel.

Save the Object to a Postscript File

You can save the main display window to a postscript file or a ppm file by pressing the SaveImage menu button and the OK button on the gadget window.

Plot Multiple Objects

Xplot is capable of displaying multiple objects. Objects are either surfaces of lines or points. Here is an example: 
In[3]: sphere = surf{[2*sin(x)*cos(y),2*sin(x)*sin(y),2*cos(x)]\
                      [x=0:pi][y=0:2*pi][sample=20:30]};
In[4]: torus = tube{[4*sin(x),4*cos(x),0][x=0:2*pi][sample=400:20]\
    	            [radius=0.5*abs(sin(x))]};
In[5]: plot sphere, torus;

A Curve Example

The objects in our first two examples are all surfaces, now let us plot a curve defined by
(sin(x)(5+cos(20x)),cos(x)(5+cos(20x)),sin(20x)) x in [0,2*pi],
i.e, it is a curve which winding around the torus 20 times. To get it plotted, the first task is to define an xplot object for it. The following inputs will define the object (called curve_example ) and plot it. 
In[6]: curve_example=curve{[sin(x)*(5+cos(20*x)),\
                            cos(x)*(5+cos(20*x)),sin(20*x)]\
                           [x: 0,2*pi][sample=2000][color=green]};
In[10]: plot curve_example;
Observe the picture. Can you tell which part of the curve is nearest to you? Now it is the time to use the depthcue shading by pressing the Depthcue button on the gadget panel. If you cannot find this button there, press the Misc menu button on the top menubar, it will bring the initial gadgets back.

If you have both curves and surfaces in your display, depthcueing is not the best coloring scheme. In these case, you can achieve a better coloring by check the Lighted Line button on the gadget panel. Of course, you have to disable the depthcueing by check the Fixed light src box once or twice.

Quit Xplot

Xplot consists of two parts, the command interpreter and the data visualizer. When a plot or plot2d command is issued, control is transfered to the graphic display. You can exit the display window only by press the Quit button. To quit the command interpreter, just type quit or exit . All your commands will be saved to a file called xplot.save by default. You can save your commands to a different file by entering the command quit ``filename'' . Files saved by xplot can be later loaded via the load command. For example, 
In[11]: load "xp.xample"
will load all the commands in file xp.example ,

Functions, Variables

Dummy Variables

The variables used to define functions are called dummy variables (function arguments). We have used x and/or y in all of our function definitions. This is because they are the default dummy variables. The other two default dummy variables are z and w. If you like to use other dummy variables, you can overwrite the default by the set dummy command. For example, if you want to use s and t as you function arguments, you can use the following command. 
In[1]: set dummy t s;
To see what the current dummy variables are, use the show dummy command.

Function And Variable Definitions

Function and variables are defined from math operators and functions in the usual way. Once defined, a variable (function) can be referenced anywhere. For example, the following are all valid definitions. 
In[2]: a = sin(1.0)*sqrt(2.0);
In[3]: b = a^12 + 1.3;
In[4]: f(x,y,z) = x^2+x*y*z+z*z +sgn(x)*( abs(x))^0.3;
In[5]: g(x,y) = (x >= y)? (x+a): y*f(y,x,1);
In[6]: h(x,y) = log(abs(sinh(x+y)));
In[7]: j(x) = x * 0.001 * ( rand() % 1000);
Xplot accepts most of the standard math functions and math operators.

Important Note: xplot only accepts functions of at most 4 variables.

Graphical Objects

We have already seen examples of xplot objects. In this section, we give more examples to show you what kinds of attributes you can assign to your objects.

Curves, Surfaces

The general definition syntax is: 
   = keyword {  }
where is the name you given to the object, keyword is either surface or curve, can either be the coordinate functions together with variable range, or a data file. For curves, is a subset of sample, color, style, with each attribute enclosed in square brackets. Color can be only be one of red, green, blue, yellow, cyan, magenta, white (red is the default). Style can be either solid (the default) or points .

For example, 

In[1]: curve_example=curve{[``curve_data''][sample: 2345]\
                           [color: cyan][style: points]};
For surfaces, is sample . For example. 
#------------------------------------------------------
# This is a half-sphere with 2 caps removed. Notice the
# y range is a function of x.

In[2]: sphere2 = surface{[-sqrt(1-x*x-y*y)][x: -0.8:0.8]\
                         [y: -sqrt(1-x*x):sqrt(1-x*x)] \
                         [sample: 30:30]}


#------------------------------------------------------
# The following surface is the famous Mandelbrot set.
# To plot it, use 'plot2d Mandelbrot' .

In[5]: M(x,y,z,w) = \
        ( (w>100)?(0.1) : \
                  ((real(z)**2+imag(z)**2>10000.0)?(0.001*w) :\
                                  ( M(x,y,z*z+x+y*i,w+1)) ) );

In[6]: m_set=surface{[M(x,y,0,0)][x=-1.8:0.8][y=-1.1:1.1] \
                      [sample=100:100] };

#------------------------------------------------------
# The Julia set for the map z -> z*z + (0.32+0.043*i)
# To plot, use 'plot2d Julia' .  

In[8]:  creal = 0.32;   cimag = 0.043;
           J(x,y,z)=( (z>100)?(0.1): \
                    ((x*x+y*y>10000.0)? (0.001*z): \
                   (J(x*x-y*y+creal,2.0*x*y+cimag,z+1))));

In[9]: j_set = surface{[J(x,y,0)][x=-1.0:1.0][y=-1.2:1.2] \
                        [sample=100:100]};
#------------------------------------------------------

The Tube

There is a special kind of object called tube , it defines a tube around a curve. The definition syntax is 
   = tube {  }
where tube is the keyword, can either be the coordinate functions together with variable range, or a data file. The is a subset of sample and radius , (specifying the sample rate and the radius of the tube). Here are two complete examples: 
# ------------------------------------------------------
#  a torus knot
#
tx(x) = sin(2*x)*(10.0 + 6*cos(3*x));
ty(x) = cos(2*x)*(10.0 + 6*cos(3*x));
tz(x) = 6*sin(3*x);

tknot = tube{[tx(x),ty(x),tz(x)][x=0:2*pi][sample=100:10]
		[radius=0.5+ 0.1* sin(x)]}
# ------------------------------------------------------
#  The trifoil knot
#
set dummy t;

tref = tube{ [ -2*cos(t)- 1/2*cos(5*t)+ 3*sin(2*t),
               -3*cos(2*t)+ 2*sin(t)- 1/2*sin(5*t), 
                2*cos(3*t)]
              [ t=0: 2*pi][sample=100:20][radius=0.4]};
# ------------------------------------------------------

Other Objects

Xplot can iterate a map or solved a simple ODE. These objects are not very common so I'll just show you some examples. 
# ----- iterate a discrete map and plot its trajectory-----
In[3]: a=1.4; b=0.3; HX(x,y)=y+1-a*x**2; HY(x,y)=b*x;
In[4]: henonMap=map{[HX(x,y),HY(x,y)] 
                    [initial: 0.4,0.5][iterate: 5000]
                   };

# ----- solve ODEs and plot its trajectory         -----
# ----- notice here we group the relevent function -----
# ----- definitions in a single command            -----
In[5]: function definitions {
          RR = 28.0;
          LORdy1dt (x,y,z) = 10.0* (y - x);
          LORdy2dt (x,y,z) = RR* x - x*z - y;
          LORdy3dt (x,y,z) = x* y - 8.0* z /3.0;
         };

In[6]: LorenzAttractor=ode{[ LORdy1dt(x,y,z),
                             LORdy2dt(x,y,z),LORdy3dt(x,y,z)] 
                           [initials = 0.03: 0.12: 0.1]
                           [time = 0.0:70.0 ] [step = 0.002]
                           [skip 6] 
                          };

In[7]: lambda = 3.5; f(x) = lambda * x*(1-x);
In[8]: a = cur{[x,f(x),0][x=0:1][samples=300][color=red]}; 
In[9]: b = cur{[x,x,0] [x=0,1][sample=10][color=green]}; 
#
#      (x, y) -> (y, f(x))
# The z-component is not relevent (in plot2d) but it is
# helpful to get a depthcue shading.
#

In[10]: c = map{[y,f(x),0.002+z][initial=0.1,f(0.1),-1]      
	 	[iterates=400][color=blue][style=solid]};
In[11]  qmap= obj{ a,b,c };

#---------------------------------------------------------------

Data Files

So far all of our objects are defined from formulas, i.e, defined by their coordinate functions. In reality, most objects cannot be described by nice coordinate functions but by raw data points. In this situation, you can define the object from data files. We explain in this section what kind of data formats { xplot} accepts and how to use them to define your objects.
All data files are supposed to be plain text file.

Regular Grid Data (Mesh)

The simplest and the most common data format is a rectangular grid, that is, a M x N matrix. The matrix is saved as MN rows of x y z coordinates, row majored. Internally, { xplot} uses a regular grid to sample all of your surfaces defined by formulas.

Defining an object from a data file is similar to defining an object from coordinate functions, with the coordinate functions replaced by the file name (in quotes). For example, suppose you have a set of 30 by 50 grid data saved in a file called grid.data and you want to define an object from it. You may use the following command. 

In[1]: grid_surf=surface{[``grid.data''][sample: 30,50]};
We remark that a grid data of size N by 1, which is just N points, can be used to define a curve or a tube.

OFF Data Format

The only other data foram xolot accepts is the polygonal data in OFF format, i.e., first specify the number of vertices and the number of polygons. Then you list all the vertices, followed by the description of the polygons. Each vertex is a line of 3 float values, i.e, its coordinates. For each polygon, you first specify the number of vertices for it and then the index of the vertices. For example, the following data specifies the cube. 
#---------------------------------------------------------
#  cube.off
#           a cube in OFF format

8 6                # 8 vertices, 6 polygons.
0 0 0              # list of the 8 vertices.
1 0 0
1 1 0
0 1 0
0 0 1
1 0 1
1 1 1
0 1 1
4     0 1 2 3      # list of the 6 polygons.
4     7 6 4 5      # Note: you need to figure
4     2 3 7 6      #       out the orientation 
4     1 2 6 5      #       yourself. Indices 
4     0 1 5 4      #       starts at 0
4     3 0 4 8
And the following input 
In[20]: cube = sur{["cube.off"]}
defines the corresponding xplot object.

Other Features

Macro Expansion

Another interesting feature of xplot is the macro expansion facility. It is similar to the one in make . For example, 
In[1]: macro = ``f(x,y)=sin(x)*cos(y)''
defines a macro called macro which stands for the string on the right. Later reference of the string can be achieved by using $(macro) . For example, 
In[2]: $(macro);
has the same effect as 
In[3]: f(x,y)=sin(x)*cos(y);
One restriction for macro expansion is that macros and variables cannot have the same name. If this happens, xplot will interpret the macro as the value of the variable (the actural macro definition is not accessible). For example, 
In[4]: a = 100;
In[2]: a = ``f(x,y) = x+y'';
In[3]: $(a);
        (unknown command)
In[4]: print $(a);
       100

Start Up File

When a plot or plot2d command is issued, xplot reads a setup file called .xplot.init in the current directory or your home directory. You can save your favorite material and lighting setup in this file via the savesetup menu button under the misc menubar.

Appendex 1: Command Summary

Here is a list of xplot commands together with a short description of its usage.
set dummy args Set the dummy variables. For example: 
In[1]: set dummy u v;
The default dummy variables are x,y,z and w
show dummy Print the current dummy variables.
set title string Set the plot title, for example: 
In[1]: set title "The (3,4) Torus knot"
set notitle Disable the plot title.
reset Sometimes when errors occur, the command interpreter and the graphics driver cannot communicate well. If this happens, the reset command will clear the trouble.
plot objects Plot the specified objects.
plot2d objects Same as plot , but set the view point on the positive z axis.
replot Redo the last plot.
show arg Print the objects you defined so far. The arg can be f, g or a where f stands for functions, g for simple objects and a for everything.
save arg 'file' Save the specified objects into 'file', where arg is the same as in above.
load 'file' Execute all the commands in 'file' .
print variable Print the value of the variable.
! unix-command Shell escape.
exit (or quit) Exit from xplot.

Appendex 2: Syntax

Here is a brief summary of xplot object definition syntax.

Curve

 <identifier> = curve{ <geometry> <attributes>}

 <geometry> ::= 
                [ < 3 one variable functions>]
                [<dummy-var>=<expression>:<expression>]
              |
                ["data_file"]

 <attributes>  ::=
                [samp=<expression>]
                [color= <red>|<green>|<blue>|<magenta>|
                     <yellow>|<cyan>|<white>]
                [style = <-1>|<0>]

Surface

 <identifier> = surface { <geometry> <attributes> }

 <geometry> ::= 
               [<a 2 variable function>]
               | [<three 2 variable functions>]
               [<dummy-var1>=<expression>:<expression>]
               [<dummy-var2>=<expression>:<expression>]
             | 
               ["data_file"]

 <attributes> ::=
                 [samp=<expression>:]

Tube

 <identifier> = tube { <geometry> <attributes> }

 <geometry> ::= [< three 1 variable functions>]
               [<dummy-var1>=<expression>:<expression>]
             | 
               ["data_file"]
               [radius =<expression>]
 <attributes> ::=
                 [samp=<expression>:<expression>]

Trajectory of a Discrete Map

  <identifier> = map { <specification> <attributes>}	

  <specification> ::= 
                     [<map definition>]
                     [initials=<expressions separated by ,>]
                     [iterates=<integer expression>]

  <attributes> ::=
                     [ color = <red>|<green>...]
Note: xplot will only plot the first 3 coordinates.

Trajectory of an ODE


 <identifier> = ode{ <specification> <attributes>}

 <specification> ::=
                    [ <expression for dx/dt ...>]
                    [initials=<expression>|<expression> ...]
                    [time = <expr>:<expr>]

 <attributes> ::=
                   [step=<expr>]
                   [skip: <integer expression>]
                   [method: <RK> | <RKQC>]
                   [style: <dotted>|<solid>] 
                   [color: <red>|<green>| ...]

 if(method == RKQC) the following attributes may be specified:
                   [small= <expression>]
                   [scale: <expression>:<expression>...]
Again, xplot will only plot the first 3 coordinates.