% --------- LaTeX -----------
%
%     xplot Manual
%
% ---------------------------
\documentstyle[12pt]{article}


\title{\makebox[1.5in][r]{ }\\
\makebox[1.5in][r]{ } \\
\makebox[1.5in][r]{ } \\
\makebox[1.5in][r]{ } \\XPLOT Tutorial }
\author{Maorong Zou}
\date{February 9, 1994}

\begin{document}
\maketitle
%---------------------------------------------------------------------%
\newpage

\tableofcontents
\newpage
\section{ Introduction }

\subsection{What Is Xplot}
{\bf 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.


\subsection{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.

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

\subsection{Comments}
Comments are welcome. Please direct them to 
\verb+mzou@ma.utexas.edu+.


\section{Getting Started With Xplot}
To invoke  xplot, just type \verb+xplot+ in an
{\it xterm} window.
After you have done this, you will see the following message:
\begin{verbatim}

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

In[1]:

\end{verbatim}
This means xplot has been succesfully loaded and it is
ready for your inputs.

\subsection{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.
\begin{verbatim}
In[1]: ex1 =surface{[sin(x)*cos(y)][x: -pi,pi][y: -pi,pi]};
\end{verbatim}
After the above line has been entered, an object called 
{\it ex1} is defined (assuming there are no syntax errors).
To plot it, just enter the following command.
\begin{verbatim}
In[2]: plot ex1;
\end{verbatim}
In just a few seconds, a window will pop out and the object 
{\it ex1 } is displayed in it with the default graphics 
attributes. 
 
\subsection{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 \verb+C Slider+
button is probably the most useful one, it resets all sliders
to their center position. 
Initially, the sliders are binded to {\it rotations}
about the {\it 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 \verb+Fast+ button once. 

In case you lose your object, there is a button in the
lower right corner called \verb+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.


\subsection{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
\verb+Filled Polygon +, \verb+Wire over Poly+,
\verb+Wireframe Only+, \verb+Zbuffered Wire+
and \verb+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.


\subsection{Change the Color of the Object}

On the top menubar, there is a menu called \verb+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 \verb+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 \verb+Light+ menu button and modifying the
corresponding gadgets in the gadget panel.

\subsection{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 \verb+SaveImage+ menu button and the \verb+ OK+
button on the gadget window.



\subsection{Plot Multiple Objects}

Xplot is capable of displaying multiple objects. Objects are
either surfaces of lines or points. Here is an example:

\begin{verbatim}
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;
\end{verbatim}

\subsection{A Curve Example}
The objects in our first two examples are all surfaces, now
let us plot a curve defined by
\begin{displaymath}
(sin(x)(5+cos(20x)),cos(x)(5+cos(20x)),sin(20x))\hspace{4mm} x\in
[0,2\pi],
\end{displaymath}
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 \verb+curve_example+) and plot it.

\begin{verbatim}
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;
\end{verbatim}

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 \verb+Depthcue+ button on the
gadget panel. If you cannot find this button there, press
the \verb+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 \verb+Lighted Line+ button on the gadget
panel. Of course, you have to disable the depthcueing by check
the \verb+Fixed light src+ box once or twice.

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


\section{Functions, Variables}

\subsection{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 \verb+set dummy+ command. For example, if you
want to use \verb+s+ and \verb+t+ as you function
arguments, you can use the following command.
\begin{verbatim}
In[1]: set dummy t s;
\end{verbatim}
To see what the current dummy variables are, use
the \verb+show dummy+ command.

\subsection{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.
\begin{verbatim}
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);
\end{verbatim}

Xplot accepts most of the standard math functions and
math operators. 

\noindent{\bf Important Note:}
xplot only accepts functions of at most 4 variables.
\vspace{5mm}

\section{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.
\subsection{Curves, Surfaces}
The general definition syntax is:
\begin{verbatim}
  <id> = keyword { <geometry> <attributes>}
\end{verbatim}
where \verb+<id>+ is the name you given to the object,
\verb+keyword+ is either {\bf surface} or {\bf curve},
\verb+<geometry>+ can either be the coordinate functions
together with variable range, or a data file. For curves,
\verb+<attributes>+ is a subset of {\bf sample}, {\bf color}, {\bf style},
with each attribute enclosed in square brackets.
Color can be only be one of {\it red,green,blue,yellow,
cyan,magenta, white}(red is the default). 
Style can be either {\it solid} (the default)
or {\it points}.


For example, 
\begin{verbatim}
In[1]: curve_example=curve{[``curve_data''][sample: 2345]\
                           [color: cyan][style: points]};
\end{verbatim}

For surfaces, \verb+<attributes>+ is {\bf sample}. 
For example.
\begin{verbatim}
#------------------------------------------------------
# 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]}

\end{verbatim}

\begin{verbatim}
#------------------------------------------------------
# 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]};
#------------------------------------------------------
\end{verbatim}


\subsection{The Tube}
There is a special kind of object called \verb+tube+,
it defines a tube around a curve. The definition syntax
is
\begin{verbatim}
  <id> = tube { <geometry> <attributes>}
\end{verbatim}
where \verb+tube+ is the keyword, 
\verb+<geometry>+ can either be the coordinate functions
together with variable range, or a data file. The
\verb+<attributes>+ is a subset of
 {\bf sample} and {\bf radius}, (specifying the sample rate and
the radius of the tube). Here are two complete examples:
\begin{verbatim}
# ------------------------------------------------------
#  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]};
# ------------------------------------------------------
	

\end{verbatim}

\subsection{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.
\begin{verbatim}
# ----- 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 };

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

\end{verbatim}

\section{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. 

\vspace{6mm}
{\bf All data files are supposed to be plain text file.}

\subsection{Regular Grid Data (Mesh)}
The simplest and the most common data format is a 
rectangular grid, that is, a $M\times 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 \verb+grid.data+ and you
want to define an object from it. You may use the
following command.
\begin{verbatim}
In[1]: grid_surf=surface{[``grid.data''][sample: 30,50]};
\end{verbatim}

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.

\subsection{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.
\begin{verbatim}
#---------------------------------------------------------
#  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
\end{verbatim}
And the following input
\begin{verbatim}
In[20]: cube = sur{["cube.off"]}
\end{verbatim}
defines the corresponding xplot object.
 

\section{Other Features}

\subsection{Macro Expansion}
Another interesting feature of xplot is the 
macro expansion facility. It is similar to the
one in {\bf make}. For example,
\begin{verbatim}
In[1]: macro = ``f(x,y)=sin(x)*cos(y)''
\end{verbatim}
defines a macro called \verb+macro+ which stands
for the string on the right. Later reference
of the string can be achieved by using 
\verb+$(macro)+. For example,
\begin{verbatim}
In[2]: $(macro);
\end{verbatim}
has the same effect as 
\begin{verbatim}
In[3]: f(x,y)=sin(x)*cos(y);
\end{verbatim}

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,
\begin{verbatim}
In[4]: a = 100;
In[2]: a = ``f(x,y) = x+y'';
In[3]: $(a);
        (unknown command)
In[4]: print $(a);
       100
\end{verbatim}


\subsection{Start Up File}
When a {\it plot} or {\it plot2d} command is 
issued, xplot reads a setup file
called \verb+.xplot.init+
in the current directory or your home directory.
You can save your favorite material and lighting
setup in this file via the \verb+savesetup+ menu
button under the \verb+misc+ menubar.

\section{Appendex 1: Command Summary}

Here is a list of xplot commands together with a
short description of its usage.

\vspace{8mm}
\noindent {\bf set dummy} {\it args }

Set the dummy variables. For example:
\begin{verbatim}
In[1]: set dummy u v;
\end{verbatim}
The default dummy variables are $x,y,z$ and $w$

\vspace{8mm}
\noindent {\bf show dummy}

Print the current dummy variables.

\vspace{8mm}
\noindent {\bf set title} {\it string}

Set the plot title, for example:

\begin{verbatim}
In[1]: set title "The (3,4) Torus knot"
\end{verbatim}


\vspace{8mm}
\noindent {\bf set notitle} 

Disable the plot title.



\vspace{8mm}
\noindent{\bf reset}

Sometimes when errors occur, the command interpreter and the
graphics driver cannot communicate well. If this happens, the
{\bf reset} command will clear the trouble.


\vspace{8mm}
\noindent{\bf plot} {\it objects}

Plot the specified objects.

\vspace{8mm}
\noindent{\bf plot2d} {\it objects}

Same as {\bf plot}, but set the view point on the positive $z$ axis.

	
\vspace{8mm}
\noindent{\bf replot}

Redo the last plot.

\vspace{8mm}
\noindent{\bf show } {\it arg}

Print the objects you defined so far. The arg can be
{\bf f, g} or {\bf a} where {\bf f} stands for functions,
{\bf g} for simple objects and
{\bf a} for everything. 

\vspace{8mm}
\noindent{\bf save} {\it arg 'file'}

Save the specified objects into {\it 'file'}, where {\it arg}
is the same as in above.

\vspace{8mm}
\noindent{\bf load } {\it 'file'}

Execute all the commands in {\it 'file'}.

\vspace{8mm}
\noindent{\bf print} {\it variable}

Print the value of the variable.

\vspace{8mm}
\noindent{\bf !}  {\it unix-command}

Shell escape.

\vspace{8mm}
\noindent{\bf exit} ( or {\bf quit})

Exit from xplot.

\section{Appendex 2: Syntax}
Here is a brief summary of xplot object definition
syntax.

\subsection*{Curve}
\begin{verbatim}
 <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>]

\end{verbatim}
\subsection*{Surface}
\begin{verbatim}
 <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>:<expression>]
\end{verbatim}

\subsection*{Tube}
\begin{verbatim}
 <identifier> = tube { <geometry> <attributes> }

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


\subsection*{Trajectory of a Discrete Map}
\begin{verbatim}
  <identifier> = map { <specification> <attributes>}	

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

  <attributes> ::=
                     [ color = <red>|<green>...]
\end{verbatim}
Note: xplot will only plot the first 3 coordinates.
\subsection*{Trajectory of an ODE}
\begin{verbatim}

 <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>...]
\end{verbatim}
Again, xplot will only plot the first 3 coordinates.

\end{document}



