
% Copyright (c) 1991-2002, The Numerical ALgorithms Group Ltd.
% All rights reserved.
%
% Redistribution and use in source and binary forms, with or without
% modification, are permitted provided that the following conditions are
% met:
%
%     - Redistributions of source code must retain the above copyright
%       notice, this list of conditions and the following disclaimer.
%
%     - Redistributions in binary form must reproduce the above copyright
%       notice, this list of conditions and the following disclaimer in
%       the documentation and/or other materials provided with the
%       distribution.
%
%     - Neither the name of The Numerical ALgorithms Group Ltd. nor the
%       names of its contributors may be used to endorse or promote products
%       derived from this software without specific prior written permission.
%
% THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
% IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
% TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
% PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER
% OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
% EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
% PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES-- LOSS OF USE, DATA, OR
% PROFITS-- OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
% LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
% NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
% SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

% *********************************************************************
\head{chapter}{Graphics}{ugGraph}
% *********************************************************************

%
\begin{texonly}
\vspace*{-2cm}
\begin{figure}[htbp]
\begin{center}
  \includegraphics[height=.4\textheight]{knot3}
\end{center}
\vskip -.5\baselineskip
\caption{Torus knot of type (15,17).}
\vskip .5\baselineskip
\end{figure}
\end{texonly}

This chapter shows how to use the \Language{} graphics facilities
\index{graphics}
under the X Window System.
\Language{} has \twodim{} and \threedim{} drawing and rendering
packages that allow the drawing, coloring, transforming, mapping,
clipping, and combining of graphic output from \Language{}
computations.
This facility is particularly useful for investigating problems in
areas such as topology.
The graphics package is capable of plotting functions of one or
more variables or plotting parametric surfaces and curves.
Various coordinate systems are also available, such as polar and
spherical.

A graph is displayed in a viewport window and it has a
\index{viewport}
control-panel that uses interactive mouse commands.
PostScript and other output forms are available so that \Language{}
\index{PostScript}
images can be printed or used by other programs.\footnote{PostScript
is a trademark of Adobe Systems Incorporated, registered in the United
States.}

% *********************************************************************
\head{section}{Two-Dimensional Graphics}{ugGraphTwoD}
% *********************************************************************
%
The \Language{} \twodim{} graphics package provides the ability to
\index{graphics!two-dimensional}
display
%
\begin{itemize}
%
\item curves defined by functions of a single real variable
%
\item curves defined by parametric equations
%
\item implicit non-singular curves defined by polynomial equations
%
\item planar graphs generated from lists of point components.
\end{itemize}
These graphs
can be modified by specifying various options, such as
calculating points in the polar
coordinate system or changing the size of the graph viewport window.

% *********************************************************************
\head{subsection}{Plotting Two-Dimensional Functions of One Variable}{ugGraphTwoDPlot}
% *********************************************************************

\index{curve!one variable function}
The first kind of \twodim{} graph is that of a curve defined by a function
\spad{y = f(x)} over a finite interval of the \spad{x} axis.

%
\beginImportant
The general format for drawing a function defined by a formula
\spad{f(x)} is:
%
\begin{center}
{\tt draw(f(x), x = a..b, {\it options})}
\end{center}
where \spad{a..b} defines the range of \spad{x}, and where
{\it options} prescribes zero or more options as described in
\spadref{ugGraphTwoDOptions}.
An example of an option is \spad{curveColor == bright red().}
An alternative format involving functions \spad{f} and \spad{g}
is also available.
\endImportant

A simple way to plot a function is to use a formula.
The first argument is the formula.
For the second argument, write the name of the independent variable (here, \spad{x}),
followed by an \spadSyntax{=}, and the range of values.

\psXtc{
Display this formula over the range
\texht{$0 \leq x \leq 6$}{0 <= x <= 6}.
\Language{} converts your formula to a compiled
function so that the results can be computed
quickly and efficiently.
}{
\spadgraph{draw(sin(tan(x)) - tan(sin(x)),x = 0..6)}
}{
2D1VarA
}

Notice that \Language{} compiled the function before the graph was put
on the screen.

\psXtc{
Here is the same graph on a different interval.
This time we give the graph a title.
}{
\spadgraph{draw(sin(tan(x)) - tan(sin(x)), x = 10..16, title=="Shifted view")}
}{
2D1VarB
}
%
Once again the formula is converted to a compiled function before
any points were computed.
If you want to graph the same function on several intervals, it is
a good idea to define the function first so that the function has
to be compiled only once.
\xtc{
This time we first define the function.
}{
\spadcommand{f(x) == (x-1)*(x-2)*(x-3) \bound{f}}
}
\psXtc{
To draw the function, the first argument is its name
and the second is just the range with no independent variable.
}{
\spadgraph{draw(f, 0..4) \free{f}}
}{
2D1VarD
}

% *********************************************************************
\head{subsection}{Plotting Two-Dimensional Parametric Plane Curves}{ugGraphTwoDPar}
% *********************************************************************

The second kind of \twodim{} graph is that of
\index{parametric plane curve}
curves produced by parametric equations.
\index{curve!parametric plane}
Let \spad{x = f(t)} and \spad{y = g(t)} be formulas or two
functions \spad{f} and \spad{g} as the parameter \spad{t} ranges
over an interval \spad{[a,b]}.
The function \spadfun{curve} takes the two functions \spad{f} and
\spad{g} as its parameters.

\beginImportant
The general format for drawing a \twodim{} plane curve defined by
parametric formulas \spad{x = f(t)} and \spad{y = g(t)} is:
%
\begin{center}
{\tt draw(curve(f(t), g(t)), t = a..b, {\it options})}
\end{center}
where \spad{a..b} defines the range of the independent variable \spad{t},
and where {\it options} prescribes zero or more options as
described in \spadref{ugGraphThreeDOptions}.
An example of an option is \spad{curveColor == bright red().}
\endImportant

Here's an example:

\psXtc{
Define a parametric curve using a range involving
\spad{%pi}, \Language{}'s way of saying \texht{$\pi$}{``pi''}.
For parametric curves, \Language{} compiles two
functions, one for each of the functions \spad{f} and \spad{g}.
}{
\spadgraph{draw(curve(sin(t)*sin(2*t)*sin(3*t), sin(4*t)*sin(5*t)*sin(6*t)), t = 0..2*\%pi)}
}{
2DppcA
}
%
%
\psXtc{
The title may be an arbitrary string and is an
optional argument to the \spadfun{draw} command.
}{
\spadgraph{draw(curve(cos(t), sin(t)), t = 0..2*\%pi, title=="Circle")}
}{
2DppcB
}
%
If you plan on plotting \spad{x = f(t)}, \spad{y = g(t)} as \spad{t} ranges over
several intervals, you may want to define functions \spad{f} and \spad{g} first, so
that they need not be recompiled every time you create a new graph.
Here's an example:
\xtc{
As before, you can first define the functions you wish to draw.
}{
\spadcommand{f(t:DFLOAT):DFLOAT == sin(3*t/4) \bound{f}}
}
\xtc{
\Language{} compiles them to map \spadtype{DoubleFloat}
values to \spadtype{DoubleFloat} values.
}{
\spadcommand{g(t:DFLOAT):DFLOAT == sin(t) \bound{g}}
}

\psXtc{
Give to {\tt curve} the names of the functions,
then write the range without the name of the
independent variable.
}{
\spadgraph{draw(curve(f,g),0..\%pi) \free{f g}}
}{
2DppcC
}
%
%
\psXtc{
Here is another look at the same curve but over a different
range. Notice that \spad{f} and \spad{g} are not recompiled.
Also note that \Language{} provides a default title based on
the first function specified in \spadfun{curve}.
}{
\spadgraph{draw(curve(f,g),-4*\%pi..4*\%pi) \free{f g}}
}{
2DppcE
}

% *********************************************************************
\head{subsection}{Plotting Plane Algebraic Curves}{ugGraphTwoDPlane}
% *********************************************************************

A third kind of \twodim{} graph is a non-singular ``solution curve''
\index{curve!plane algebraic}
in a rectangular region of the plane.
A solution curve is a curve defined by a polynomial equation
\spad{p(x,y) = 0}.
\index{plane algebraic curve}
Non-singular means that the curve is ``smooth'' in that it does not
cross itself or come to a point (cusp).
Algebraically, this means that for any point \spad{(x,y)} on the curve,
that is, a point such that \spad{p(x,y) = 0}, the partial derivatives
\begin{texonly}
  $\frac{\partial p}{\partial x}(x,y)$ and
  $\frac{\partial p}{\partial y}(x,y)$
\end{texonly}
\begin{htonly}
\spad{dp/dx(x,y)} and \spad{dp/dy(a,b)}
\end{htonly}
are not both zero.
\index{curve!smooth}
\index{curve!non-singular}
\index{smooth curve}
\index{non-singular curve}

%
\beginImportant
The general format for drawing a non-singular solution curve
given by a polynomial of the form \spad{p(x,y) = 0} is:
%
\begin{center}
{\tt draw(p(x,y) = 0, x, y, range == [a..b, c..d], {\it options})}
\end{center}
where the second and third arguments name the first and second
independent variables of \spad{p}.
A {\tt range} option is always given to designate a bounding
rectangular region of the plane
\texht{$a \leq x \leq b, c \leq y\leq d$}{a <= x <= b, c <= y <= d}.
Zero or more additional options as described in
\spadref{ugGraphTwoDOptions} may be given.
\endImportant

\xtc{
We require that the polynomial has rational or integral coefficients.
Here is an algebraic curve example (``Cartesian ovals''):
\index{Cartesian!ovals}
}{
\spadcommand{p := ((x^2 + y^2 + 1) - 8*x)^2 - (8*(x^2 + y^2 + 1)-4*x-1) \bound{p}}
}

\psXtc{
The first argument is always expressed as an equation of the form \spad{p = 0}
where \spad{p} is a polynomial.
}{
\spadgraph{draw(p = 0, x, y, range == [-1..11, -7..7]) \free{p}}
}{
2DpacA
}

% *********************************************************************
\head{subsection}{Two-Dimensional Options}{ugGraphTwoDOptions}
% *********************************************************************

The \spadfun{draw} commands take an optional list of options,
such as {\tt title} shown above.
Each option is given by the syntax: {\it name} {\tt ==} {\it value}.
Here is a list of the available options in the order that they are
described below.

\begin{texonly}
\begin{tabular}{llll}
adaptive&clip&unit\\
clip&curveColor&range\\
toScale&pointColor&coordinates\\
\end{tabular}
\end{texonly}
\begin{htonly}
\table{ {adaptive} {clip} {unit} {clip} {curveColor} {range}
{toScale} {pointColor} {coordinates}}
\end{htonly}

The \spad{adaptive} option turns adaptive plotting on or off.
\index{adaptive plotting}
Adaptive plotting uses an algorithm that traverses a graph and computes
more points for those parts of the graph with high curvature.
The higher the curvature of a region is, the more points the algorithm
computes.
\index{graphics!2D options!adaptive}
%
%
\psXtc{
The {\tt adaptive} option is normally on.
Here we turn it off.
}{
\spadgraph{draw(sin(1/x),x=-2*\%pi..2*\%pi, adaptive == false)}
}{
2DOptAd
}
%
%
\psXtc{
The {\tt clip} option turns clipping on or off.
\index{graphics!2D options!clipping}
If on, large values are cut off according to
\spadfunFrom{clipPointsDefault}{GraphicsDefaults}.
}{
\spadgraph{draw(tan(x),x=-2*\%pi..2*\%pi, clip == true)}
}{
2DOptCp
}
%
%
\psXtc{
Option {\tt toScale} does plotting to scale if {\tt true} or uses
the entire viewport if {\tt false}.
The default can be determined using
\spadfunFrom{drawToScale}{GraphicsDefaults}.
\index{graphics!2D options!to scale}
}{
\spadgraph{draw(sin(x),x=-\%pi..\%pi, toScale == true, unit == [1.0,1.0])}
}{
2DOptSc
}
%
%
\psXtc{
Option {\tt clip} with a range sets point clipping of a graph within the
\index{graphics!2D options!clip in a range}
ranges specified in the list \spad{[x range,y range]}.
\index{clipping}
If only one range is specified, clipping applies to the y-axis.
}{
\spadgraph{draw(sec(x),x=-2*\%pi..2*\%pi, clip == [-2*\%pi..2*\%pi,-\%pi..\%pi], unit == [1.0,1.0])}
}{
2DOptCpR
}
%
\psXtc{
Option {\tt curveColor} sets the color of the graph curves or lines to be the
\index{graphics!2D options!curve color}
indicated palette color
\index{curve!color}
(see \spadref{ugGraphColor} and \spadref{ugGraphColorPalette}).
\index{color!curve}
}{
\spadgraph{draw(sin(x),x=-\%pi..\%pi, curveColor == bright red())}
}{
2DOptCvC
}
%
\psXtc{
Option {\tt pointColor}
sets the color of the graph points to the indicated
\index{graphics!2D options!point color}
palette color
(see \spadref{ugGraphColor} and \spadref{ugGraphColorPalette}).
\index{color!point}
}{
\spadgraph{draw(sin(x),x=-\%pi..\%pi, pointColor == pastel yellow())}
}{
2DOptPtC
}
%
\psXtc{
Option {\tt unit} sets the intervals at which the axis units are plotted
\index{graphics!2D options!set units}
according to the indicated steps [\spad{x} interval, \spad{y} interval].
}{
\spadgraph{draw(curve(9*sin(3*t/4),8*sin(t)), t = -4*\%pi..4*\%pi, unit == [2.0,1.0])}
}{
2DOptUt
}
%
%
\psXtc{
Option {\tt range} sets the range of variables in a graph to be
within the ranges
\index{graphics!2D options!range}
for solving plane algebraic curve plots.
}{
\spadgraph{draw(y^2 + y - (x^3 - x) = 0, x, y, range == [-2..2,-2..1], unit==[1.0,1.0])}
}{
2DOptRgA
}
%
%
\psXtc{
A second example of a solution plot.
}{
\spadgraph{draw(x^2 + y^2 = 1, x, y, range == [-3/2..3/2,-3/2..3/2], unit==[0.5,0.5])}
}{
2DOptRgB
}
%
%
\psXtc{
Option \spad{coordinates} indicates the coordinate system
in which the graph
\index{graphics!2D options!coordinates}
is plotted.
The default is to use the Cartesian coordinate system.
\index{Cartesian!coordinate system}
For more details, see \spadref{ugGraphCoord}%
\begin{htonly}
{ }or \spadtype{CoordinateSystems}%
\end{htonly}
.
\index{coordinate system!Cartesian}
}{
\spadgraph{draw(curve(sin(5*t),t),t=0..2*\%pi, coordinates == polar)}
}{
2DOptPlr
}

% *********************************************************************
\head{subsection}{Color}{ugGraphColor}
% *********************************************************************

The domain \spadtype{Color}
\exptypeindex{Color}
provides operations for manipulating
\index{graphics!color}
colors in \twodim{} graphs.
\index{color}
Colors are objects of \spadtype{Color}.
Each color has a {\it hue} and a {\it weight}.
\index{hue}
Hues are represented by integers that range from \spad{1} to the
\spadfunFrom{numberOfHues()}{Color}, normally
\index{graphics!color!number of hues}
\spad{27}.
%\footnote{Use \spadfun{colorDef} to
%change these values to any range you want for a given \threedim{} viewport}
\index{weight}
Weights are floats and  have the value \spad{1.0} by default.
%
\begin{description}
%
\item[\spadfun{color}]\funArgs{integer}
creates a color of hue {\it integer} and weight \spad{1.0}.
%
\item[\spadfun{hue}]\funArgs{color}
returns the hue of {\it color} as an integer.
\index{graphics!color!hue function}
%
\item[\spadfun{red}]\texttt{()}, \spadfun{blue}\texttt{()}
\spadfun{green}\texttt{()}, and \spadfun{yellow}\texttt{()}
\index{graphics!color!primary color functions}
\newline
create colors of that hue with weight \spad{1.0}.
%
\item[\subscriptIt{color}{1} {\tt +} \subscriptIt{color}{2}] returns the
color that results from additively combining the indicated
\subscriptIt{color}{1} and \subscriptIt{color}{2}.
Color addition is not commutative: changing the order of the arguments
produces different results.
%
\item[{\it integer} {\tt *} {\it color}]
changes the weight of {\it color} by {\it integer}
without affecting its hue.
\index{graphics!color!multiply function}
For example,
\spad{red() + 3*yellow()} produces a color closer to yellow than to red.
Color multiplication is not associative: changing the order of grouping
\index{color!multiplication}
produces different results.
\end{description}
%
\psXtc{
These functions can be used to change the point and curve colors
for two- and \threedim{} graphs.
Use the {\tt pointColor} option for points.
}{
\spadgraph{draw(x^2,x=-1..1,pointColor == green())}
}{
23DColA
}
%
\psXtc{
Use the {\tt curveColor} option for curves.
}{
\spadgraph{draw(x^2,x=-1..1,curveColor == color(13) + 2*blue())}
}{
23DColB
}

% *********************************************************************
\head{subsection}{Palette}{ugGraphColorPalette}
% *********************************************************************
\index{graphics!palette}

Domain \spadtype{Palette} is the domain of shades of colors:
\spadfun{dark}, \spadfun{dim}, \spadfun{bright}, \spadfun{pastel}, and \spadfun{light},
designated by the integers \spad{1} through \spad{5}, respectively.
\exptypeindex{Palette}
\xtc{
Colors are normally ``bright.''
}{
\spadcommand{shade red()}
}
\xtc{
To change the shade of a color, apply the name of a shade to it.
\index{color!shade}
\index{shade}
}{
\spadcommand{myFavoriteColor := dark blue() \bound{mfc}}
}
\xtc{
The expression \spad{shade(color)}
returns the value of a shade of \spad{color}.
}{
\spadcommand{shade myFavoriteColor \free{mfc}}
}
\xtc{
The expression \spad{hue(color)} returns its hue.
}{
\spadcommand{hue myFavoriteColor \free{mfc}}
}
\psXtc{
Palettes can be used in specifying colors in \twodim{} graphs.
}{
\spadgraph{draw(x^2,x=-1..1,curveColor == dark blue())}
}{
23DPal
}

% *********************************************************************
\head{subsection}{Two-Dimensional Control-Panel}{ugGraphTwoDControl}
% *********************************************************************
\index{graphics!2D control-panel}
Once you have created a viewport, move your mouse to the viewport and click
with your left mouse button to display a control-panel.
The panel is displayed on the side of the viewport closest to
where you clicked.  Each of the buttons which toggle on and off show the
current state of the graph.

\includehyperdoc{2Dctrl}{Two-dimensional control-panel.}

% *********************************************************************
\subsubsection{Transformations}
% *********************************************************************
\index{graphics!2D control-panel!transformations}

Object transformations are executed from the control-panel by mouse-activated
potentiometer windows.
%
\begin{description}
%
\item[Scale:] To scale a graph, click on a mouse button
\index{graphics!2D control-panel!scale}
within the {\bf Scale} window in the upper left corner of the control-panel.
The axes along which the scaling is to occur are indicated by setting the
toggles above the arrow.
With {\tt X On} and {\tt Y On} appearing, both axes are selected and scaling
is uniform.
If either is not selected, for example, if {\tt X Off} appears, scaling is
non-uniform.
%
\item[Translate:] To translate a graph, click the mouse in the
\index{graphics!2D control-panel!translate}
{\bf Translate} window in the direction you wish the graph to move.
This window is located in the upper right corner of the control-panel.
Along the top of the {\bf Translate} window are two buttons for selecting
the direction of translation.
Translation along both coordinate axes results when {\tt X On} and {\tt Y
On} appear or along one axis when one is on, for example, {\tt X On} and
{\tt Y Off} appear.
\end{description}

% *********************************************************************
\subsubsection{Messages}
% *********************************************************************
\index{graphics!2D control-panel!messages}

The window directly below the transformation potentiometer windows is
used to display system messages relating to the viewport and the control-panel.
The following format is displayed: \newline
%
\begin{center}
[scaleX, scaleY] \spad{>}graph\spad{<} [translateX, translateY] \newline
\end{center}
The two values to the left show the scale factor along the {\tt X} and
{\tt Y} coordinate axes.  The two values to the right show the distance of
translation from the center in the {\tt X} and {\tt Y} directions.  The number
in the center shows which graph in the viewport this data pertains to.
When multiple graphs exist in the same viewport,
the graph must be selected (see ``Multiple Graphs,'' below) in
order for its transformation data to be shown, otherwise the number
is 1.

% *********************************************************************
\subsubsection{Multiple Graphs}
% *********************************************************************

\index{graphics!2D control-panel!multiple graphs}
The {\bf Graphs} window contains buttons that allow the placement
of \twodim{} graphs into one of nine available slots in any other
\twodim{} viewport.
In the center of the window are numeral buttons from one to nine
that show whether a graph is displayed in the viewport.
Below each number button is a button showing whether a graph
that is present is selected for application of some
transformation.
When the caret symbol is displayed, then the graph in that slot
will be manipulated.
Initially, the graph for which the viewport is created occupies
the first slot, is displayed, and is selected.
%
%
\begin{description}
%
\item[Clear:]  The {\bf Clear} button deselects every viewport graph slot.
\index{graphics!2D control-panel!clear}
A graph slot is reselected by selecting the button below its number.
%
\item[Query:]  The {\bf Query} button is used to display the scale and
\index{graphics!2D control-panel!query}
translate data for the indicated graph.  When this button is selected the
message ``Click on the graph to query'' appears.  Select a slot
number button from the {\bf Graphs} window. The scaling factor and translation
offset of the graph are then displayed in the message window.
%
\item[Pick:]  The {\bf Pick} button is used to select a graph
\index{graphics!2D control-panel!pick}
to be placed or dropped into the indicated viewport.  When this button is
selected, the message ``Click on the graph to pick'' appears.
Click on the slot with the graph number of the desired
graph.  The graph information is held waiting for
you to execute a {\bf Drop} in some other graph.
%
\item[Drop:]  Once a graph has been picked up using the {\bf Pick} button,
\index{graphics!2D control-panel!drop}
the {\bf Drop} button places it into a new viewport slot.
The message ``Click on the graph to drop'' appears in the message
window when the {\bf Drop} button is selected.
By selecting one of the slot number buttons in the {\bf Graphs}
window, the graph currently being held is dropped into this slot
and displayed.
\end{description}

% *********************************************************************
\subsubsection{Buttons}
% *********************************************************************
\index{graphics!2D control-panel!buttons}

%
\begin{description}
%
\item[Axes] turns the coordinate axes on or off.
\index{graphics!2D control-panel!axes}
%
\item[Units] turns the units along the {\tt x}
and {\tt y} axis on or off.
\index{graphics!2D control-panel!units}
%
\item[Box] encloses the area of the viewport graph
in a bounding box, or removes the box if already enclosed.
\index{graphics!2D control-panel!box}
%
\item[Pts] turns on or off the display of points.
\index{graphics!2D control-panel!points}
%
\item[Lines] turns on or off the display
of lines connecting points.
\index{graphics!2D control-panel!lines}
%
\item[PS] writes the current viewport contents to
\index{graphics!2D control-panel!ps}
a file {\bf fricas2D.ps}.
The file is placed in the directory from which \Language{} or the {\bf
viewAlone} program was invoked.
\index{PostScript}
%
\item[Reset] resets the object transformation
characteristics and attributes back to their initial states.
\index{graphics!2D control-panel!reset}
%
\item[Hide] makes the control-panel disappear.
\index{graphics!2D control-panel!hide}
%
\item[Quit] queries whether the current viewport
\index{graphics!2D control-panel!quit}
session should be terminated.
\end{description}

% *********************************************************************
\head{subsection}{Operations for Two-Dimensional Graphics}{ugGraphTwoDops}
% *********************************************************************

Here is a summary of useful \Language{} operations for \twodim{}
graphics.
Each operation name is followed by a list of arguments.
Each argument is written as a variable informally named according
to the type of the argument (for example, {\it integer}).
If appropriate, a default value for an argument is given in
parentheses immediately following the name.

%
\texht{\bgroup\hbadness = 10001\sloppy}{}
\begin{description}
%
\item[\spadfun{adaptive}]\funArgs{\optArg{boolean\argDef{true}}}
\index{adaptive plotting}
sets or indicates whether graphs are plotted
\index{graphics!set 2D defaults!adaptive}
according to the adaptive refinement algorithm.
%
\item[\spadfun{axesColorDefault}]\funArgs{\optArg{color\argDef{dark blue()}}}
sets or indicates the default color of the
\index{graphics!set 2D defaults!axes color}
axes in a \twodim{} graph viewport.
%
\item[\spadfun{clipPointsDefault}]\funArgs{\optArg{boolean\argDef{false}}}
sets or
indicates whether point clipping is
\index{graphics!set 2D defaults!clip points}
to be applied as the default for graph plots.
%
\item[\spadfun{drawToScale}]\funArgs{\optArg{boolean\argDef{false}}}
sets or
indicates whether the plot of a graph
\index{graphics!set 2D defaults!to scale}
is ``to scale'' or uses the entire viewport space as the default.
%
\item[\spadfun{lineColorDefault}]\funArgs{\optArg{color\argDef{pastel yellow()}}}
sets or indicates the default color of the
\index{graphics!set 2D defaults!line color}
lines or curves in a \twodim{} graph viewport.
%
\item[\spadfun{maxPoints}]\funArgs{\optArg{integer\argDef{500}}}
sets or indicates
the default maximum number of
\index{graphics!set 2D defaults!max points}
possible points to be used when constructing a \twodim{} graph.
%
\item[\spadfun{minPoints}]\funArgs{\optArg{integer\argDef{21}}}
sets or indicates the default minimum number of
\index{graphics!set 2D defaults!min points}
possible points to be used when constructing a \twodim{} graph.
%
\item[\spadfun{pointColorDefault}]\funArgs{\optArg{color\argDef{bright red()}}}
sets or indicates the default color of the
\index{graphics!set 2D defaults!point color}
points in a \twodim{} graph viewport.
%
\item[\spadfun{pointSizeDefault}]\funArgs{\optArg{integer\argDef{5}}}
sets or indicates the default size of the
\index{graphics!set 2D defaults!point size}
dot used to plot points in a \twodim{} graph.
%
\item[\spadfun{screenResolution}]\funArgs{\optArg{integer\argDef{600}}}
sets or indicates the default screen
\index{graphics!set 2D defaults!screen resolution}
resolution constant used in setting the computation limit of adaptively
\index{adaptive plotting}
generated curve plots.
%
\item[\spadfun{unitsColorDefault}]\funArgs{\optArg{color\argDef{dim green()}}}
sets or indicates the default color of the
\index{graphics!set 2D defaults!units color}
unit labels in a \twodim{} graph viewport.
%
\item[\spadfun{viewDefaults}]\funArgs{}
resets the default settings for the following
\index{graphics!set 2D defaults!reset viewport}
attributes:  point color, line color, axes color, units color, point size,
viewport upper left-hand corner position, and the viewport size.
%
\item[\spadfun{viewPosDefault}]\funArgs{\optArg{list\argDef{[100,100]}}}
sets or indicates the default position of the
\index{graphics!set 2D defaults!viewport position}
upper left-hand corner of a \twodim{} viewport, relative to the
display root window.
The upper left-hand corner of the display is considered to be at the
(0, 0) position.
%
\item[\spadfun{viewSizeDefault}]\funArgs{\optArg{list\argDef{[200,200]}}}
sets or
indicates the default size in which two
\index{graphics!set 2D defaults!viewport size}
dimensional viewport windows are shown.
It is defined by a width and then a height.
%
\item[\spadfun{viewWriteAvailable}]\funArgs{\optArg{list\argDef{["pixmap",
"bitmap", "postscript", "image"}}}
indicates the possible file types
\index{graphics!2D defaults!available viewport writes}
that can be created with the \spadfunFrom{write}{TwoDimensionalViewport} function.
%
\item[\spadfun{viewWriteDefault}]
\funArgs{\optArg{list\argDef{[]}}}
sets or indicates the default types of files, in
\index{graphics!set 2D defaults!write viewport}
addition to the {\bf data} file, that are created when a
\spadfun{write} function is executed on a viewport.
%
\item[\spadfun{units}]\funArgs{viewport, integer\argDef{1}, string\argDef{"off"}}
turns the units on or off for the graph with index {\it integer}.
%
\item[\spadfun{axes}]\funArgs{viewport, integer\argDef{1}, string\argDef{"on"}}
turns the axes on
\index{graphics!2D commands!axes}
or off for the graph with index {\it integer}.
%
\item[\spadfun{close}]\funArgs{viewport}
closes {\it viewport}.
\index{graphics!2D commands!close}
%
\item[\spadfun{connect}]\funArgs{viewport, integer\argDef{1}, string\argDef{"on"}}
declares whether lines
\index{graphics!2D commands!connect}
connecting the points are displayed or not.
%
\item[\spadfun{controlPanel}]\funArgs{viewport, string\argDef{"off"}}
declares
whether the \twodim{} control-panel is automatically displayed
or not.
%
\item[\spadfun{graphs}]\funArgs{viewport}
returns a list
\index{graphics!2D commands!graphs}
describing the state of each graph.
If the graph state is not being used this is shown by {\tt "undefined"},
otherwise a description of the graph's contents is shown.
%
\item[\spadfun{graphStates}]\funArgs{viewport}
displays
\index{graphics!2D commands!state of graphs}
a list of all the graph states available for {\it viewport}, giving the
values for every property.
%
\item[\spadfun{key}]\funArgs{viewport}
returns the process
\index{graphics!2D commands!key}
ID number for {\it viewport}.
%
\item[\spadfun{move}]\funArgs{viewport,
\subscriptText{integer}{x}(viewPosDefault),
\subscriptText{integer}{y}(viewPosDefault)}
moves {\it viewport} on the screen so that the
\index{graphics!2D commands!move}
upper left-hand corner of {\it viewport} is at the position {\it (x,y)}.
%
\item[\spadfun{options}]\funArgs{\it viewport}
returns a list
\index{graphics!2D commands!options}
of all the \spadtype{DrawOption}s used by {\it viewport}.
%
\item[\spadfun{points}]\funArgs{viewport, integer\argDef{1}, string\argDef{"on"}}
specifies whether the graph points for graph {\it integer} are
\index{graphics!2D commands!points}
to be displayed or not.
%
\item[\spadfun{region}]\funArgs{viewport, integer\argDef{1}, string\argDef{"off"}}
declares whether graph {\it integer} is or is not to be displayed
with a bounding rectangle.
%
\item[\spadfun{reset}]\funArgs{viewport}
resets all the properties of {\it viewport}.
%
\item[\spadfun{resize}]\funArgs{viewport,
\subscriptText{integer}{width}, \subscriptText{integer}{height}}
\index{graphics!2D commands!resize}
resizes {\it viewport} with a new {\it width} and {\it height}.
%
\item[\spadfun{scale}]\funArgs{viewport, \subscriptText{integer}{n}\argDef{1},
\subscriptText{integer}{x}\argDef{0.9}, \subscriptText{integer}{y}\argDef{0.9}}
scales values for the
\index{graphics!2D commands!scale}
{\it x} and {\it y} coordinates of graph {\it n}.
%
\item[\spadfun{show}]\funArgs{viewport, \subscriptText{integer}{n}\argDef{1},
string\argDef{"on"}}
indicates if graph {\it n} is shown or not.
%
\item[\spadfun{title}]\funArgs{viewport, string\argDef{"FriCAS 2D"}}
designates the title for {\it viewport}.
%
\item[\spadfun{translate}]\funArgs{viewport,
\subscriptText{integer}{n}\argDef{1},
\subscriptText{float}{x}\argDef{0.0}, \subscriptText{float}{y}\argDef{0.0}}
\index{graphics!2D commands!translate}
causes graph {\it n} to be moved {\it x} and {\it y} units in the respective directions.
%
\item[\spadfun{write}]\funArgs{viewport, \subscriptText{string}{directory},
\optArg{strings}}
if no third argument is given, writes the {\bf data} file onto the directory
with extension {\bf data}.
The third argument can be a single string or a list of strings with some or
all the entries {\tt "pixmap"}, {\tt "bitmap"}, {\tt "postscript"}, and
{\tt "image"}.
\end{description}
\texht{\egroup}{}

% *********************************************************************
\head{subsection}{Addendum: Building Two-Dimensional Graphs}{ugGraphTwoDbuild}
% *********************************************************************

In this section we demonstrate how to create \twodim{} graphs from
lists of points and give an example showing how to read the lists
of points from a file.

% *********************************************************************
\subsubsection{Creating a Two-Dimensional Viewport from a List of Points}
% *********************************************************************

\Language{} creates lists of points in a \twodim{} viewport by utilizing
the \spadtype{GraphImage} and \spadtype{TwoDimensionalViewport} domains.
In this example, the \spadfunFrom{makeGraphImage}{GraphImage}
function takes a list of lists of points parameter, a list of colors for
each point in the graph, a list of colors for each line in the graph, and
a list of sizes for each point in the graph.
%
\xtc{
The following expressions create a list of lists of points which will be read
by \Language{} and made into a \twodim{} viewport.
}{
\spadcommand{p1 := point [1,1]\$(Point DFLOAT) \bound{p1}}
}
\xtc{
}{
\spadcommand{p2 := point [0,1]\$(Point DFLOAT) \bound{p2}}
}
\xtc{
}{
\spadcommand{p3 := point [0,0]\$(Point DFLOAT) \bound{p3}}
}
\xtc{
}{
\spadcommand{p4 := point [1,0]\$(Point DFLOAT) \bound{p4}}
}
\xtc{
}{
\spadcommand{p5 := point [1,.5]\$(Point DFLOAT) \bound{p5}}
}
\xtc{
}{
\spadcommand{p6 := point [.5,0]\$(Point DFLOAT) \bound{p6}}
}
\xtc{
}{
\spadcommand{p7 := point [0,0.5]\$(Point DFLOAT) \bound{p7}}
}
\xtc{
}{
\spadcommand{p8 := point [.5,1]\$(Point DFLOAT) \bound{p8}}
}
\xtc{
}{
\spadcommand{p9 := point [.25,.25]\$(Point DFLOAT) \bound{p9}}
}
\xtc{
}{
\spadcommand{p10 := point [.25,.75]\$(Point DFLOAT) \bound{p10}}
}
\xtc{
}{
\spadcommand{p11 := point [.75,.75]\$(Point DFLOAT) \bound{p11}}
}
\xtc{
}{
\spadcommand{p12 := point [.75,.25]\$(Point DFLOAT) \bound{p12}}
}
\xtc{
Finally, here is the list.
}{
\spadcommand{llp := [[p1,p2], [p2,p3], [p3,p4], [p4,p1], [p5,p6], [p6,p7], [p7,p8], [p8,p5], [p9,p10], [p10,p11], [p11,p12], [p12,p9]] \free{p1 p2 p3 p4 p5 p6 p7 p8 p9 p10 p11 p12} \bound{llp}}
}
\xtc{
Now we set the point sizes for all components of the graph.
}{
\spadcommand{size1 := 6::PositiveInteger \bound{size1}}
}
\xtc{
}{
\spadcommand{size2 := 8::PositiveInteger \bound{size2}}
}
\xtc{
}{
\spadcommand{size3 := 10::PositiveInteger \bound{size3}}
}
\xtc{
}{
\spadcommand{lsize := [size1, size1, size1, size1, size2, size2, size2, size2, size3, size3, size3, size3] \bound{lsize} \free{size1 size2 size3}}
}
\xtc{
Here are the colors for the points.
}{
\spadcommand{pc1 := pastel red() \bound{pc1}}
}
\xtc{
}{
\spadcommand{pc2 := dim green() \bound{pc2}}
}
\xtc{
}{
\spadcommand{pc3 := pastel yellow() \bound{pc3}}
}
\xtc{
}{
\spadcommand{lpc := [pc1, pc1, pc1, pc1, pc2, pc2, pc2, pc2, pc3, pc3, pc3, pc3] \free{pc1 pc2 pc3} \bound{lpc}}
}
\xtc{
Here are the colors for the lines.
}{
\spadcommand{lc := [pastel blue(), light yellow(), dim green(), bright red(), light green(), dim yellow(), bright blue(), dark red(), pastel red(), light blue(), dim green(), light yellow()] \bound{lc}}
}
\xtc{
Now the \spadtype{GraphImage} is created according to the component
specifications indicated above.
}{
\spadcommand{g := makeGraphImage(llp,lpc,lc,lsize)\$GRIMAGE \bound{g} \free{llp lpc lc lsize}}
}
\psXtc{
The \spadfunFrom{makeViewport2D}{TwoDimensionalViewport} function now
creates a \spadtype{TwoDimensionalViewport} for this graph according to the
list of options specified within the brackets.
}{
\spadgraph{makeViewport2D(g,[title("Lines")])\$VIEW2D \free{g}}
}{
lines
}

\xtc{
This example demonstrates the use of the \spadtype{GraphImage} functions
\spadfunFrom{component}{GraphImage} and \spadfunFrom{appendPoint}{GraphImage}
in adding points to an empty \spadtype{GraphImage}.
}{
\spadcommand{)clear all \bound{clearAll}}
}
\xtc{
}{
\spadcommand{g := graphImage()\$GRIMAGE \bound{Sg}\free{clearAll}}
}
\xtc{
}{
\spadcommand{p1 := point [0,0]\$(Point DFLOAT) \bound{Sp1}}
}
\xtc{
}{
\spadcommand{p2 := point [.25,.25]\$(Point DFLOAT) \bound{Sp2}}
}
\xtc{
}{
\spadcommand{p3 := point [.5,.5]\$(Point DFLOAT) \bound{Sp3}}
}
\xtc{
}{
\spadcommand{p4 := point [.75,.75]\$(Point DFLOAT) \bound{Sp4}}
}
\xtc{
}{
\spadcommand{p5 := point [1,1]\$(Point DFLOAT) \bound{Sp5}}
}
\xtc{
}{
\spadcommand{component(g,p1)\$GRIMAGE\free{Sg Sp1}\bound{gp1}}
}
\xtc{
}{
\spadcommand{component(g,p2)\$GRIMAGE\free{Sg Sp2}\bound{gp2}}
}
\xtc{
}{
\spadcommand{appendPoint(g,p3)\$GRIMAGE\free{gp1 gp2 Sp3}\bound{gp3}}
}
\xtc{
}{
\spadcommand{appendPoint(g,p4)\$GRIMAGE\free{gp3 Sp4}\bound{gp4}}
}
\xtc{
}{
\spadcommand{appendPoint(g,p5)\$GRIMAGE\free{gp4 Sp5}\bound{gp5}}
}
\psXtc{
Here is the graph.
}{
\spadgraph{makeViewport2D(g,[title("Graph Points")])\$VIEW2D \free{Sg gp5}}
}{
graphpoints
}
%

%
\xtc{
A list of points can also be made into a \spadtype{GraphImage} by using
the operation \spadfunFrom{coerce}{GraphImage}.  It is equivalent to adding
each point to \spad{g2} using \spadfunFrom{component}{GraphImage}.
}{
\spadcommand{g2 := coerce([[p1],[p2],[p3],[p4],[p5]])\$GRIMAGE  \free{Sp1 Sp2 Sp3 Sp4 Sp5} \bound{Sg2}}
}
\xtc{
Now, create an empty \spadtype{TwoDimensionalViewport}.
}{
\spadcommand{v := viewport2D()\$VIEW2D \bound{Sv}}
}
\xtc{
}{
\spadcommand{options(v,[title("Just Points")])\$VIEW2D \free{Sv}\bound{Svo}}
}
\xtc{
Place the graph into the viewport.
}{
\spadcommand{putGraph(v,g2,1)\$VIEW2D \free{Sg2 Svo}\bound{Svog2}}
}
\psXtc{
Take a look.
}{
\spadgraph{makeViewport2D(v)\$VIEW2D \free{Svog2}}
}{
justpoints
}


% *********************************************************************
\subsubsection{Creating a Two-Dimensional Viewport of a List of Points from a File}
% *********************************************************************

The following three functions read a list of points from a
file and then draw the points and the connecting lines. The
points are stored in the file in readable form as floating point numbers
(specifically, \spadtype{DoubleFloat} values) as an alternating
stream of \spad{x}- and \spad{y}-values. For example,
\begin{verbatim}
0.0 0.0     1.0 1.0     2.0 4.0
3.0 9.0     4.0 16.0    5.0 25.0
\end{verbatim}

\begin{xmpLines}
drawPoints(lp:List Point DoubleFloat):VIEW2D ==
  g := graphImage()$GRIMAGE
  for p in lp repeat
    component(g,p,pointColorDefault(),lineColorDefault(),
      pointSizeDefault())
  makeViewport2D(g,[title("Points")])$VIEW2D

drawLines(lp:List Point DoubleFloat):VIEW2D ==
  g := graphImage()$GRIMAGE
  component(g, lp, pointColorDefault(), lineColorDefault(),
    pointSizeDefault())$GRIMAGE
  makeViewport2D(g,[title("Points")])$VIEW2D

plotData2D(name, title) ==
  f:File(DFLOAT) := open(name,"input")
  lp:LIST(Point DFLOAT) := empty()
  while ((x := readIfCan!(f)) case DFLOAT) repeat
    y : DFLOAT := read!(f)
    lp := cons(point [x,y]$(Point DFLOAT), lp)
    lp
  close!(f)
  drawPoints(lp)
  drawLines(lp)
\end{xmpLines}
%
This command will actually create the viewport and the graph if
the point data is in the file \spad{"file.data"}.
\begin{xmpLines}
plotData2D("file.data", "2D Data Plot")
\end{xmpLines}

% *********************************************************************
\head{subsection}{Addendum: Appending a Graph to a Viewport Window Containing a Graph}{ugGraphTwoDappend}
% *********************************************************************

This section demonstrates how to append a \twodim{} graph to a viewport
already containing other graphs.
The default \spadfun{draw} command places a graph into the first
\spadtype{GraphImage} slot position of the \spadtype{TwoDimensionalViewport}.

\xtc{
This graph is in the first slot in its viewport.
}{
\spadcommand{v1 := draw(sin(x),x=0..2*\%pi) \bound{v1}}
}
\xtc{
So is this graph.
}{
\spadcommand{v2 := draw(cos(x),x=0..2*\%pi, curveColor==light red()) \bound{v2}}
}
\xtc{
The operation \spadfunFrom{getGraph}{TwoDimensionalViewport}
retrieves the \spadtype{GraphImage} \spad{g1} from the first slot position
in the viewport \spad{v1}.
}{
\spadcommand{g1 := getGraph(v1,1) \bound{g1}\free{v1}}
}
\xtc{
Now \spadfunFrom{putGraph}{TwoDimensionalViewport}
places \spad{g1} into the the second slot position of \spad{v2}.
}{
\spadcommand{putGraph(v2,g1,2) \bound{v22}\free{g1 v2}}
}
\psXtc{
Display the new \spadtype{TwoDimensionalViewport} containing both graphs.
}{
\spadgraph{makeViewport2D(v2) \free{v22}}
}{
twographs1
}
Instead of using \spadfun{draw} to draw a graph and then extract
graph data we can use \spadfun{makeObject}.
\xtc{
First graph.
}{
\spadcommand{g3 := makeObject(sin(x),x=-1..\%pi,[]) \bound{g3}}
}
\xtc{
This graph is in the first slot in its viewport.
}{
\spadcommand{v3 := draw(cos(x),x=-1..\%pi, curveColor==light red()) \bound{v3}}
}
\xtc{
Now \spadfunFrom{putGraph}{TwoDimensionalViewport}
places \spad{g3} into the the second slot position of \spad{v3}.
}{
\spadcommand{putGraph(v3,g3,2) \bound{v33}\free{g3 v3}}
}
\psXtc{
Display the new \spadtype{TwoDimensionalViewport} containing both graphs.
}{
\spadgraph{makeViewport2D(v3) \free{v33}}
}{
twographs2
}
\noOutputXtc{
The viewports \spad{v1}, \spad{v2} and \spad{v3} are no longer needed so
we close them.
}{
\spadcommand{close(v1); close(v2); close(v3) \free{v1 v2 v3}}
}

% *********************************************************************
\head{section}{Three-Dimensional Graphics}{ugGraphThreeD}
% *********************************************************************
%
The \Language{} \threedim{} graphics package provides the ability to
\index{graphics!three-dimensional}
%
\begin{itemize}
%
\item generate surfaces defined by a function of two real variables
%
\item generate space curves and tubes defined by parametric equations
%
\item generate surfaces defined by parametric equations
\end{itemize}
These graphs can be modified by using various options, such as calculating
points in the spherical coordinate system or changing the polygon grid size
of a surface.

% *********************************************************************
\head{subsection}{Plotting Three-Dimensional Functions of Two Variables}{ugGraphThreeDPlot}
% *********************************************************************

\index{surface!two variable function}
The simplest \threedim{} graph is that of a surface defined by a function
of two variables, \spad{z = f(x,y)}.

%
\beginImportant
The general format for drawing a surface defined by a formula \spad{f(x,y)}
of two variables \spad{x} and \spad{y} is:
%
\begin{center}
{\tt draw(f(x,y), x = a..b, y = c..d, {\it options})}
\end{center}
where \spad{a..b} and \spad{c..d} define the range of \spad{x}
and \spad{y}, and where {\it options} prescribes zero or more
options as described in \spadref{ugGraphThreeDOptions}.
An example of an option is \spad{title == "Title of Graph".}
An alternative format involving a function \spad{f} is also
available.
\endImportant

%
\psXtc{
The simplest way to plot a function of two variables is to use a formula.
With formulas you always precede the range specifications with
the variable name and an \spadSyntax{=} sign.
Notice that \Language{} uses the text of your function as a
default title.
}{
\spadgraph{draw(cos(x*y),x=-3..3,y=-3..3)}
}{
3D2VarA
}
%
\xtc{
If you intend to use a function more than once,
or it is long and complex, then first
give its definition to \Language{}.
}{
\spadcommand{f(x,y) == sin(x)*cos(y) \bound{f}}
}
%
%
\psXtc{
To draw the function, just give its name and drop the variables
from the range specifications.
\Language{} compiles your function for efficient computation
of data for the graph.
}{
\spadgraph{draw(f,-\%pi..\%pi,-\%pi..\%pi) \free{f}}
}{
3D2VarB
}

% *********************************************************************
\head{subsection}{Plotting Three-Dimensional Parametric Space Curves}{ugGraphThreeDParm}
% *********************************************************************

A second kind of \threedim{} graph is a \threedim{} space curve
\index{curve!parametric space}
defined by the parametric equations for \spad{x(t)}, \spad{y(t)},
\index{parametric space curve}
and \spad{z(t)} as a function of an independent variable \spad{t}.

%
\beginImportant
The general format for drawing a \threedim{} space curve defined by
parametric formulas \spad{x = f(t)}, \spad{y = g(t)}, and
\spad{z = h(t)} is:
%
\begin{center}
{\tt draw(curve(f(t),g(t),h(t)), t = a..b, {\it options})}
\end{center}
where \spad{a..b} defines the range of the independent variable
\spad{t}, and where {\it options} prescribes zero or more options
as described in \spadref{ugGraphThreeDOptions}.
An example of an option is \spad{title == "Title of Graph".}
An alternative format involving functions \spad{f}, \spad{g} and
\spad{h} is also available.
\endImportant

%
\psXtc{
If you use explicit formulas to draw a space curve, always precede
the range specification with the variable name and an
\spadSyntax{=} sign.
}{
\spadgraph{draw(curve(5*cos(t), 5*sin(t),t), t=-12..12)}
}{
3DpscA
}
%
\xtc{
Alternatively, you can draw space curves by referring to functions.
}{
\spadcommand{i1(t:DFLOAT):DFLOAT == sin(t)*cos(3*t/5) \bound{i1}}
}
\xtc{
This is useful if the functions are to be used more than once \ldots
}{
\spadcommand{i2(t:DFLOAT):DFLOAT == cos(t)*cos(3*t/5) \bound{i2}}
}
\xtc{
or if the functions are long and complex.
}{
\spadcommand{i3(t:DFLOAT):DFLOAT == cos(t)*sin(3*t/5) \bound{i3}}
}
%
%
\psXtc{
Give the names of the functions and
drop the variable name specification in the second argument.
Again, \Language{} supplies a default title.
}{
\spadgraph{draw(curve(i1,i2,i3),0..15*\%pi) \free{i1 i2 i3}}
}{
3DpscB
}

% *********************************************************************
\head{subsection}{Plotting Three-Dimensional Parametric Surfaces}{ugGraphThreeDPar}
% *********************************************************************

\index{surface!parametric}
A third kind of \threedim{} graph is a surface defined by
\index{parametric surface}
parametric equations for \spad{x(u,v)}, \spad{y(u,v)}, and
\spad{z(u,v)} of two independent variables \spad{u} and \spad{v}.

%
\beginImportant
The general format for drawing a \threedim{} graph defined by
parametric formulas \spad{x = f(u,v)}, \spad{y = g(u,v)},
and \spad{z = h(u,v)} is:
%
\begin{center}
{\tt draw(surface(f(u,v),g(u,v),h(u,v)), u = a..b, v = c..d, {\it options})}
\end{center}
where \spad{a..b} and \spad{c..d} define the range of the
independent variables \spad{u} and \spad{v}, and where
{\it options} prescribes zero or more options as described in
\spadref{ugGraphThreeDOptions}.
An example of an option is \spad{title == "Title of Graph".}
An alternative format involving functions \spad{f}, \spad{g} and
\spad{h} is also available.
\endImportant

%
\psXtc{
This example draws a graph of a surface plotted using the
parabolic cylindrical coordinate system option.
\index{coordinate system!parabolic cylindrical}
The values of the functions supplied to \spadfun{surface} are
\index{parabolic cylindrical coordinate system}
interpreted in coordinates as given by a {\tt coordinates} option,
here as parabolic cylindrical coordinates (see
\spadref{ugGraphCoord}).
}{
\spadgraph{draw(surface(u*cos(v), u*sin(v), v*cos(u)), u=-4..4, v=0..\%pi, coordinates== parabolicCylindrical)}
}{
3DpsA
}
%
Again, you can graph these parametric surfaces using functions,
if the functions are long and complex.
\xtc{
Here we declare the types of arguments and values to be of type
\spadtype{DoubleFloat}.
}{
\spadcommand{n1(u:DFLOAT,v:DFLOAT):DFLOAT == u*cos(v) \bound{n1}}
}
\xtc{
As shown by previous examples, these declarations are necessary.
}{
\spadcommand{n2(u:DFLOAT,v:DFLOAT):DFLOAT == u*sin(v) \bound{n2}}
}
\xtc{
In either case, \Language{} compiles the functions
when needed to graph a result.
}{
\spadcommand{n3(u:DFLOAT,v:DFLOAT):DFLOAT == u \bound{n3}}
}
\xtc{
Without these declarations, you have to suffix floats
with \spad{@DFLOAT} to get a \spadtype{DoubleFloat} result.
However, a call here with an unadorned float produces a \spadtype{DoubleFloat}.
}{
\spadcommand{n3(0.5,1.0)\free{n3}}
}
%
%
\psXtc{
Draw the surface by referencing the function names, this time
choosing the toroidal coordinate system.
\index{coordinate system!toroidal}
\index{toroidal coordinate system}
}{
\spadgraph{draw(surface(n1,n2,n3), 1..4, 1..2*\%pi, coordinates == toroidal(1\$DFLOAT)) \free{n1 n2 n3}}
}{
3DpsB
}

% *********************************************************************
\head{subsection}{Three-Dimensional Options}{ugGraphThreeDOptions}
% *********************************************************************

\index{graphics!3D options}
The \spadfun{draw} commands optionally take an optional list of options such
as {\tt coordinates} as shown in the last example.
Each option is given by the syntax: \spad{name} {\tt ==} \spad{value}.
Here is a list of the available options in the order that they are
described below:

\begin{texonly}
\begin{tabular}{llll}
title&coordinates&var1Steps\\
style&tubeRadius&var2Steps\\
colorFunction&tubePoints&space\\
\end{tabular}
\end{texonly}
\begin{htonly}
\table{ {title} {coordinates} {var1Steps} {style} {tubeRadius} {var2Steps}
{colorFunction} {tubePoints} {space}}
\end{htonly}

\psXtc{
The option \spad{title} gives your graph a title.
\index{graphics!3D options!title}
}{
\spadgraph{draw(cos(x*y),x=0..2*\%pi,y=0..\%pi,title == "Title of Graph") }
}{
3DOptTtl
}
%
\psXtc{
The \spad{style} determines which of four rendering algorithms is used for
\index{rendering}
the graph.
The choices are
{\tt "wireMesh"}, {\tt "solid"}, {\tt "shade"}, and {\tt "smooth"}.
}{
\spadgraph{draw(cos(x*y),x=-3..3,y=-3..3, style=="smooth", title=="Smooth Option")}
}{
3DOptSty
}
%

In all but the wire-mesh style, polygons in a surface or tube plot
are normally colored in a graph according to their
\spad{z}-coordinate value.  Space curves are colored according to their
parametric variable value.
\index{graphics!3D options!color function}
To change this, you can give a coloring function.
\index{function!coloring}
The coloring function is sampled across the range of its arguments, then
normalized onto the standard \Language{} colormap.

\xtc{
A function of one variable  makes the color depend on the
value of the parametric variable specified for a tube plot.
}{
\spadcommand{color1(t) == t \bound{colorFxn1}}
}
\psXtc{
}{
\spadgraph{draw(curve(sin(t), cos(t),0), t=0..2*\%pi, tubeRadius == .3, colorFunction == color1) \free{colorFxn1}}
}{
3DOptCf1
}
%
\xtc{
A function of two variables makes the color depend on the
values of the independent variables.
}{
\spadcommand{color2(u,v) == u^2 - v^2 \bound{colorFxn2}}
}
\psXtc{
Use the option {\tt colorFunction} for special coloring.
}{
\spadgraph{draw(cos(u*v), u=-3..3, v=-3..3, colorFunction == color2) \free{colorFxn2}}
}{
3DOptCf2
}
%
\xtc{
With a three variable function, the
color also depends on the value of the function.
}{
\spadcommand{color3(x,y,fxy) == sin(x*fxy) + cos(y*fxy) \bound{colorFxn3}}
}
\psXtc{
}{
\spadgraph{draw(cos(x*y), x=-3..3, y=-3..3, colorFunction == color3) \free{colorFxn3}}
}{
3DOptCf3
}
%
Normally the Cartesian coordinate system is used.
\index{Cartesian!coordinate system}
To change this, use the {\tt coordinates} option.
\index{coordinate system!Cartesian}
For details, see \spadref{ugGraphCoord}.
%
%
\xtc{
}{
\spadcommand{m(u:DFLOAT,v:DFLOAT):DFLOAT == 1 \bound{m}}
}
\psXtc{
Use the spherical
\index{spherical coordinate system}
coordinate system.
\index{coordinate system!spherical}
}{
\spadgraph{draw(m, 0..2*\%pi,0..\%pi, coordinates == spherical, style=="shade") \free{m}}
}{
3DOptCrd
}
%
Space curves may be displayed as tubes with polygonal cross sections.
\index{tube}
Two options, {\tt tubeRadius} and {\tt tubePoints},  control the size and
shape of this cross section.
%
\psXtc{
The {\tt tubeRadius} option specifies the radius of the tube that
\index{tube!radius}
encircles the specified space curve.
}{
\spadgraph{draw(curve(sin(t),cos(t),0),t=0..2*\%pi, style=="shade", tubeRadius == .3)}
}{
3DOptRad
}
%
%
\psXtc{
The {\tt tubePoints} option specifies the number of vertices
\index{tube!points in polygon}
defining the polygon that is used to create a tube around the
specified space curve.
The larger this number is, the more cylindrical the tube becomes.
}{
\spadgraph{draw(curve(sin(t), cos(t), 0), t=0..2*\%pi, style=="shade", tubeRadius == .25, tubePoints == 3)}
}{
3DOptPts
}
%
\index{graphics!3D options!variable steps}
%
%
\psXtc{
Options \spadfunFrom{var1Steps}{DrawOption} and
\spadfunFrom{var2Steps}{DrawOption} specify the number of intervals into
which the grid defining a surface plot is subdivided with respect to the
first and second parameters of the surface function(s).
}{
\spadgraph{draw(cos(x*y),x=-3..3,y=-3..3, style=="shade", var1Steps == 30, var2Steps == 30)}
}{
3DOptvB
}
%
The {\tt space} option
of a \spadfun{draw} command lets you build multiple graphs in three space.
To use this option, first create an empty three-space object,
then use the {\tt space} option thereafter.
There is no restriction as to the number or kinds
of graphs that can be combined this way.
\xtc{
Create an empty three-space object.
}{
\spadcommand{s := create3Space()\$(ThreeSpace DFLOAT) \bound{s}}
}
%
%
\xtc{
}{
\spadcommand{m(u:DFLOAT,v:DFLOAT):DFLOAT == 1 \bound{m}}
}
\psXtc{
Add a graph to this three-space object.
The new graph destructively inserts the graph
into \spad{s}.
}{
\spadgraph{draw(m,0..\%pi,0..2*\%pi, coordinates == spherical, space == s) \free{s m}}
}{
3Dmult1A
}
%
%
\psXtc{
Add a second graph to \spad{s}.
}{
\spadgraph{v := draw(curve(1.5*sin(t), 1.5*cos(t),0), t=0..2*\%pi, tubeRadius == .25, space == s) \free{s} \bound{v}}
}{
3Dmult1B
}
%
A three-space object can also be obtained from an existing \threedim{} viewport
using the \spadfunFrom{subspace}{ThreeSpace} command.
You can then use \spadfun{makeViewport3D} to create a viewport window.
\nullXtc{
Assign to \spad{subsp} the three-space object in viewport \spad{v}.
}{
\spadcommand{subsp := subspace v \free{v} \bound{su}}
}
\nullXtc{
Reset the space component of \spad{v} to the value of \spad{subsp}.
}{
\spadcommand{subspace(v, subsp) \bound{sp} \free{su}}
}
\nullXtc{
Create a viewport window from a three-space object.
}{
\spadgraph{makeViewport3D(subsp,"Graphs") \free{sp}}
}

% *********************************************************************
\head{subsection}{The makeObject Command}{ugGraphMakeObject}
% *********************************************************************

An alternate way to create multiple graphs is to use
\spadfun{makeObject}.
The \spadfun{makeObject} command is similar to the \spadfun{draw}
command, except that it returns a three-space object rather than a
\spadtype{ThreeDimensionalViewport}.
In fact, \spadfun{makeObject} is called by the \spadfun{draw}
command to create the \spadtype{ThreeSpace} then
\spadfunFrom{makeViewport3D}{ThreeDimensionalViewport} to create a
viewport window.

\xtc{
}{
\spadcommand{m(u:DFLOAT,v:DFLOAT):DFLOAT == 1 \bound{m}}
}
\xtc{
Do the last example a new way.
First use \spadfun{makeObject} to
create a three-space object \spad{sph}.
}{
\spadcommand{sph := makeObject(m, 0..\%pi, 0..2*\%pi, coordinates==spherical)\bound{sph}\free{m}}
}
\xtc{
Add a second object to \spad{sph}.
}{
\spadcommand{makeObject(curve(1.5*sin(t), 1.5*cos(t), 0), t=0..2*\%pi, space == sph, tubeRadius == .25) \free{sph}\bound{v1}}
}
\nullXtc{
Create and display a viewport
containing \spad{sph}.
}{
\spadgraph{makeViewport3D(sph,"Multiple Objects") \free{v1}}
}

Note that an undefined \spadtype{ThreeSpace} parameter declared in a
\spadfun{makeObject} or \spadfun{draw} command results in an error.
Use the \spadfunFrom{create3Space}{ThreeSpace} function to define a
\spadtype{ThreeSpace}, or obtain a \spadtype{ThreeSpace} that has been
previously generated before including it in a command line.

% *********************************************************************
\head{subsection}{Building Three-Dimensional Objects From Primitives}{ugGraphThreeDBuild}
% *********************************************************************

Rather than using the \spadfun{draw} and \spadfun{makeObject} commands,
\index{graphics!advanced!build 3D objects}
you can create \threedim{} graphs from primitives.
Operation \spadfunFrom{create3Space}{ThreeSpace} creates a
three-space object to which points, curves and polygons
can be added using the operations from the \spadtype{ThreeSpace}
domain.
The resulting object can then be displayed in a viewport using
\spadfunFrom{makeViewport3D}{ThreeDimensionalViewport}.

\xtc{
Create the empty three-space object \spad{space}.
}{
\spadcommand{space := create3Space()\$(ThreeSpace DFLOAT) \bound{space}}
}

Objects can be sent to this \spad{space} using the operations
exported by the \spadtype{ThreeSpace} domain.
\exptypeindex{ThreeSpace}
The following examples place curves into \spad{space}.

\xtc{
Add these eight curves to the space.
}{
\spadcommand{closedCurve(space,[[0,30,20], [0,30,30], [0,40,30], [0,40,100], [0,30,100],[0,30,110], [0,60,110], [0,60,100], [0,50,100], [0,50,30], [0,60,30], [0,60,20]]) \bound{curve1} \free{space}}
}
\xtc{
}{
\spadcommand{closedCurve(space,[[80,0,30], [80,0,100], [70,0,110], [40,0,110], [30,0,100], [30,0,90], [40,0,90], [40,0,95], [45,0,100], [65,0,100], [70,0,95], [70,0,35]]) \bound{curve2} \free{space}}
}
\xtc{
}{
\spadcommand{closedCurve(space,[[70,0,35], [65,0,30], [45,0,30], [40,0,35], [40,0,60], [50,0,60], [50,0,70], [30,0,70], [30,0,30], [40,0,20], [70,0,20], [80,0,30]]) \bound{curve3} \free{space}}
}
\xtc{
}{
\spadcommand{closedCurve(space,[[0,70,20], [0,70,110], [0,110,110], [0,120,100], [0,120,70], [0,115,65], [0,120,60], [0,120,30], [0,110,20], [0,80,20], [0,80,30], [0,80,20]]) \bound{curve4} \free{space}}
}
\xtc{
}{
\spadcommand{closedCurve(space,[[0,105,30], [0,110,35], [0,110,55], [0,105,60], [0,80,60], [0,80,70], [0,105,70], [0,110,75], [0,110,95], [0,105,100], [0,80,100], [0,80,20], [0,80,30]]) \bound{curve5} \free{space}}
}
\xtc{
}{
\spadcommand{closedCurve(space,[[140,0,20], [140,0,110], [130,0,110], [90,0,20], [101,0,20],[114,0,50], [130,0,50], [130,0,60], [119,0,60], [130,0,85], [130,0,20]]) \bound{curve6} \free{space}}
}
\xtc{
}{
\spadcommand{closedCurve(space,[[0,140,20], [0,140,110], [0,150,110], [0,170,50], [0,190,110], [0,200,110], [0,200,20], [0,190,20], [0,190,75], [0,175,35], [0,165,35],[0,150,75], [0,150,20]]) \bound{curve7} \free{space}}
}
\xtc{
}{
\spadcommand{closedCurve(space,[[200,0,20], [200,0,110], [189,0,110], [160,0,45], [160,0,110], [150,0,110], [150,0,20], [161,0,20], [190,0,85], [190,0,20]]) \bound{curve8} \free{space}}
}
\psXtc{
Create and display the viewport using \spadfun{makeViewport3D}.
Options may also be given but here are displayed as a list with values
enclosed in parentheses.
}{
\spadgraph{makeViewport3D(space, title == "Letters") \free{space curve1 curve2 curve3 curve4 curve5 curve6 curve7 curve8}}
}{
3DBuildA
}

% *********************************************************************
\subsubsection{Cube Example}
% *********************************************************************

As a second example of the use of primitives, we generate a cube using a
polygon mesh.
It is important to use a consistent orientation of the polygons for
correct generation of \threedim{} objects.

\xtc{
Again start with an empty three-space object.
}{
\spadcommand{spaceC := create3Space()\$(ThreeSpace DFLOAT) \bound{spaceC}}
}
\xtc{
For convenience,
give \spadtype{DoubleFloat} values \spad{+1} and \spad{-1} names.
}{
\spadcommand{x: DFLOAT := 1 \bound{x}}
}
\xtc{
}{
\spadcommand{y: DFLOAT := -1 \bound{y}}
}
\xtc{
Define the vertices of the cube.
}{
\spadcommand{a := point [x,x,y,1::DFLOAT]\$(Point DFLOAT) \bound{a} \free{x y}}
}
\xtc{
}{
\spadcommand{b := point [y,x,y,4::DFLOAT]\$(Point DFLOAT) \bound{b} \free{x y}}
}
\xtc{
}{
\spadcommand{c := point [y,x,x,8::DFLOAT]\$(Point DFLOAT) \bound{c} \free{x y}}
}
\xtc{
}{
\spadcommand{d := point [x,x,x,12::DFLOAT]\$(Point DFLOAT) \bound{d} \free{x y}}
}
\xtc{
}{
\spadcommand{e := point [x,y,y,16::DFLOAT]\$(Point DFLOAT) \bound{e} \free{x y}}
}
\xtc{
}{
\spadcommand{f := point [y,y,y,20::DFLOAT]\$(Point DFLOAT) \bound{f} \free{x y}}
}
\xtc{
}{
\spadcommand{g := point [y,y,x,24::DFLOAT]\$(Point DFLOAT) \bound{g} \free{x y}}
}
\xtc{
}{
\spadcommand{h := point [x,y,x,27::DFLOAT]\$(Point DFLOAT) \bound{h} \free{x y}}
}
\xtc{
Add the faces of the cube as polygons to the space using a
consistent orientation.
}{
\spadcommand{polygon(spaceC,[d,c,g,h]) \free{d c g h spaceC} \bound{pol1}}
}
\xtc{
}{
\spadcommand{polygon(spaceC,[d,h,e,a]) \free{d h e a spaceC} \bound{pol2}}
}
\xtc{
}{
\spadcommand{polygon(spaceC,[c,d,a,b]) \free{c d a b spaceC} \bound{pol3}}
}
\xtc{
}{
\spadcommand{polygon(spaceC,[g,c,b,f]) \free{g c b f spaceC} \bound{pol4}}
}
\xtc{
}{
\spadcommand{polygon(spaceC,[h,g,f,e]) \free{h g f e spaceC} \bound{pol5}}
}
\xtc{
}{
\spadcommand{polygon(spaceC,[e,f,b,a]) \free{e f b a spaceC} \bound{pol6}}
}
\psXtc{
Create and display the viewport.
}{
\spadgraph{makeViewport3D(spaceC, title == "Cube") \free{pol1 pol2 pol3 pol4 pol5 pol6}}
}{
3DBuildB
}

% *********************************************************************
\head{subsection}{Coordinate System Transformations}{ugGraphCoord}
% *********************************************************************
\index{graphics!advanced!coordinate systems}

The \spadtype{CoordinateSystems} package provides coordinate transformation
functions that map a given data point from the coordinate system specified
into the Cartesian coordinate system.
\exptypeindex{CoordinateSystems}
The default coordinate system, given a triplet \spad{(f(u,v), u, v)}, assumes
that \spad{z = f(u, v)}, \spad{x = u} and \spad{y = v},
that is, reads the coordinates in \spad{(z, x, y)} order.

\xtc{
}{
\spadcommand{m(u:DFLOAT,v:DFLOAT):DFLOAT == u^2 \bound{m}}
}
%
\psXtc{
Graph plotted in default coordinate system.
}{
\spadgraph{draw(m,0..3,0..5) \free{m}}
}{
defcoord
}

The \spad{z} coordinate comes first since the first argument of
the \spadfun{draw} command gives its values.
In general, the coordinate systems \Language{} provides, or any
that you make up, must provide a map to an \spad{(x, y, z)} triplet in
order to be compatible with the
\spadfunFrom{coordinates}{DrawOption} \spadtype{DrawOption}.
\exptypeindex{DrawOption}
Here is an example.

\xtc{
Define the identity function.
}{
\spadcommand{cartesian(point:Point DFLOAT):Point DFLOAT == point \bound{cart}}
}
\psXtc{
Pass \spad{cartesian} as the \spadfunFrom{coordinates}{DrawOption}
parameter to the \spadfun{draw} command.
}{
\spadgraph{draw(m,0..3,0..5,coordinates==cartesian) \free{m cart}}
}{
cartcoord
}
%

What happened?
The option {\tt coordinates == cartesian} directs \Language{} to
treat the dependent variable \spad{m} defined by
\texht{$m=u^2$}{m=u^2} as the \spad{x} coordinate.
Thus the triplet of values \spad{(m, u, v)} is transformed to
coordinates \spad{(x, y, z)} and so we get the graph of
\texht{$x=y^2$}{x=y^2}.

Here is another example.
The \spadfunFrom{cylindrical}{CoordinateSystems} transform takes
\index{coordinate system!cylindrical}
input of the form \spad{(w,u,v)}, interprets it in the order
\index{cylindrical coordinate system}
\texht{($r$,$\theta$,$z$)}{(\spad{r}, \spad{theta}, \spad{z})}
and maps it to the Cartesian coordinates
\begin{texonly}
$x=r\cos(\theta)$, $y=r\sin(\theta)$, $z=z$
\end{texonly}
\begin{htonly}
\spad{x = r * cos(theta)}, \spad{y = r * sin(theta)}, \spad{z = z}
\end{htonly}
in which
\texht{$r$}{\spad{r}} is the radius,
\texht{$\theta$}{\spad{theta}} is the angle and
\texht{$z$}{\spad{z}} is the z-coordinate.
\xtc{
An example using the \spadfunFrom{cylindrical}{CoordinateSystems}
coordinates for the constant \spad{r = 3}.
}{
\spadcommand{f(u:DFLOAT,v:DFLOAT):DFLOAT == 3 \bound{f}}
}
\psXtc{
Graph plotted in cylindrical coordinates.
}{
\spadgraph{draw(f,0..\%pi,0..6,coordinates==cylindrical) \free{f}}
}{
cylCoord
}

Suppose you would like to specify \smath{z} as a function of
\smath{r} and \texht{$\theta$}{\spad{theta}} instead of just
\smath{r}?
Well, you still can use the \spadfun{cylindrical} \Language{}
transformation but we have to reorder the triplet before
passing it to the transformation.

\xtc{
First, let's create a point to
work with and call it \spad{pt} with some color \spad{col}.
}{
\spadcommand{col := 5 \bound{c}}
}
\xtc{
}{
\spadcommand{pt := point[1,2,3,col]\$(Point DFLOAT) \free{c} \bound{pt}}
}
The reordering you want is
\texht{$(z,r, \theta)$}{\spad{(z,r,theta)}} to
\texht{$(r, \theta,z)$}{\spad{(r,theta,z)}}
so that the first element is moved to the third element, while the second
and third elements move forward and the color element does not change.
\xtc{
Define a function \userfun{reorder} to reorder the point elements.
}{
\spadcommand{reorder(p:Point DFLOAT):Point DFLOAT == point[p.2, p.3, p.1, p.4] \bound{freo}}
}
\xtc{
The function moves the second and third elements
forward but the color does not change.
}{
\spadcommand{reorder pt \free{pt freo}}
}
\xtc{
The function \userfun{newmap} converts our reordered version of
the cylindrical coordinate system to the standard
\texht{$(x,y,z)$}{\spad{(x,y,z)}} Cartesian system.
}{
\spadcommand{newmap(pt:Point DFLOAT):Point DFLOAT == cylindrical(reorder pt) \free{freo} \bound{fnewmap}}
}
\xtc{
}{
\spadcommand{newmap pt \free{fnewmap pt} \bound{new}}
}
%
\psXtc{
Graph the same function \spad{f} using the coordinate mapping of the function
\spad{newmap}, so it is now interpreted as
\texht{$z=3$}{\spad{z = 3}}:
}{
\spadgraph{draw(f,0..3,0..2*\%pi,coordinates==newmap) \free{f new}}
}{
newmap
}

% I think this is good to say here: it shows a lot of depth. RSS
{\texht{\sloppy}{}
The \spadtype{CoordinateSystems} package exports the following
\index{coordinate system}
operations:
\spadfun{bipolar},
\spadfun{bipolarCylindrical},
\spadfun{cartesian},
\spadfun{conical},
\spadfun{cylindrical},
\spadfun{elliptic},
\spadfun{ellipticCylindrical},
\spadfun{oblateSpheroidal},
\spadfun{parabolic},
\spadfun{parabolicCylindrical},
\spadfun{paraboloidal},
\spadfun{polar},
\spadfun{prolateSpheroidal},
\spadfun{spherical}, and
\spadfun{toroidal}.
Use \Browse{} or the \spadsys{)show} system command
\syscmdindex{show}
to get more information.

}

% *********************************************************************
\head{subsection}{Three-Dimensional Clipping}{ugGraphClip}
% *********************************************************************

A \threedim{} graph can be explicitly clipped within the \spadfun{draw}
\index{graphics!advanced!clip}
command by indicating a minimum and maximum threshold for the
\index{clipping}
given function definition.
These thresholds can be defined using the \Language{} \spadfun{min}
and \spadfun{max} functions.
\xtc{
}{
\begin{spadsrc}[\bound{g}]
gamma(x,y) ==
  g := Gamma complex(x,y)
  point [x, y, max( min(real g, 4), -4), argument g]
\end{spadsrc}
}
\psXtc{
Here is an example that clips
the gamma function in order to eliminate the extreme divergence it creates.
}{
\spadgraph{draw(gamma,-\%pi..\%pi,-\%pi..\%pi,var1Steps==50,var2Steps==50) \free{g}}
}{
clipGamma
}

% *********************************************************************
\head{subsection}{Three-Dimensional Control-Panel}{ugGraphThreeDControl}
% *********************************************************************
\index{graphics!3D control-panel}
Once you have created a viewport, move your mouse to the viewport
and click with your left mouse button.
This displays a control-panel on the side of the viewport
that is closest to where you clicked.

\includehyperdoc{3Dctrl}{Three-dimensional control-panel.}

% *********************************************************************
\subsubsection{Transformations}
% *********************************************************************

We recommend you first select the {\bf Bounds} button while
\index{graphics!3D control-panel!transformations}
executing transformations since the bounding box displayed
indicates the object's position as it changes.
%
\begin{description}
%
\item[Rotate:]  A rotation transformation occurs by clicking the mouse
\index{graphics!3D control-panel!rotate}
within the {\bf Rotate} window in the upper left corner of the
control-panel.
The rotation is computed in spherical coordinates, using the
horizontal mouse position to increment or decrement the value of
the longitudinal angle \texht{$\theta$}{\spad{theta}} within the
range of 0 to \texht{2$\pi$}{2*pi} and the vertical mouse position
to increment or decrement the value of the latitudinal angle
\spad{phi} within the range of \texht{-$\pi$}{pi}
to \texht{$\pi$}{pi}.
The active mode of rotation is displayed in green on a color
monitor or in clear text on a black and white monitor, while the
inactive mode is displayed in red for color display or a mottled
pattern for black and white.
%
\begin{description}
%
\item[origin:]  The {\bf origin} button indicates that the
rotation is to occur with respect to the origin of the viewing space, that is
indicated by the axes.
%
\item[object:]  The {\bf object} button indicates that the
rotation is to occur with respect to the center of volume of the object,
independent of the axes' origin position.
\end{description}
%
\item[Scale:]  A scaling transformation occurs by clicking the mouse
\index{graphics!3D control-panel!scale}
within the {\bf Scale} window in the upper center of the
control-panel, containing a zoom arrow.
The axes along which the scaling is to occur are indicated by
selecting the appropriate button above the zoom arrow window.
The selected axes are displayed in green on a color monitor or in
clear text on a black and white monitor, while the unselected axes
are displayed in red for a color display or a mottled pattern for
black and white.
%
\begin{description}
%
\item[uniform:]  Uniform scaling along the {\tt x}, {\tt y}
and {\tt z} axes occurs when all the axes buttons are selected.
%
\item[non-uniform:]  If any of the axes buttons are
not selected, non-uniform scaling occurs, that is, scaling occurs only in the
direction of the axes that are selected.
\end{description}
%
\item[Translate:]  Translation occurs by indicating with the mouse in the
\index{graphics!3D control-panel!translate}
{\bf Translate} window the direction you want the graph to move.
This window is located in the upper right corner of the
control-panel and contains a potentiometer with crossed arrows
pointing up, down, left and right.
Along the top of the {\bf Translate} window are three buttons
({\bf XY},
{\bf XZ}, and {\bf YZ}) indicating the three orthographic projection planes.
Each orientates the group as a view into that plane.
Any translation of the graph occurs only along this plane.
\end{description}

% *********************************************************************
\subsubsection{Messages}
% *********************************************************************
\index{graphics!3D control-panel!messages}

The window directly below the potentiometer windows for transformations is
used to display system messages relating to the viewport, the control-panel
and the current graph displaying status.

% *********************************************************************
\subsubsection{Colormap}
% *********************************************************************
\index{graphics!3D control-panel!color map}

Directly below the message window is the colormap range indicator
window.
\index{colormap}
The \Language{} Colormap shows a sampling of the spectrum from
which hues can be drawn to represent the colors of a surface.
The Colormap is composed of five shades for each of the hues along
this spectrum.
By moving the markers above and below the Colormap, the range of
hues that are used to color the existing surface are set.
The bottom marker shows the hue for the low end of the color range
and the top marker shows the hue for the upper end of the range.
Setting the bottom and top markers at the same hue results in
monochromatic smooth shading of the graph when {\bf Smooth} mode is selected.
At each end of the Colormap are {\bf +} and {\bf -} buttons.
When clicked on, these increment or decrement the top or bottom
marker.

% *********************************************************************
\subsubsection{Buttons}
% *********************************************************************
\index{graphics!3D control-panel!buttons}

Below the Colormap window and to the left are located various
buttons that determine the characteristics of a graph.
The buttons along the bottom and right hand side all have special
meanings; the remaining buttons in the first row indicate the mode
or style used to display the graph.
The second row are toggles that turn on or off a property of the
graph.
On a color monitor, the property is on if green (clear text, on a
monochrome monitor) and off if red (mottled pattern, on a
monochrome monitor).
Here is a list of their functions.
%
\begin{description}
%
\item[Wire] displays surface and tube plots as a
\index{graphics!3D control-panel!wire}
wireframe image in a single color (blue) with no hidden surfaces removed,
or displays space curve plots in colors based upon their parametric variables.
This is the fastest mode for displaying a graph.
This is very useful when you
want to find a good orientation of your graph.
%
\item[Solid] displays the graph with hidden
\index{graphics!3D control-panel!solid}
surfaces removed, drawing each polygon beginning with the furthest
from the viewer.
The edges of the polygons are displayed in the hues specified by
the range in the Colormap window.
%
\item[Shade] displays the graph with hidden
\index{graphics!3D control-panel!shade}
surfaces removed and with the polygons shaded, drawing each
polygon beginning with the furthest from the viewer.
Polygons are shaded in the hues specified by the range in the
Colormap window using the Phong illumination model.
\index{Phong!illumination model}
%
\item[Smooth] displays the graph using a
\index{graphics!3D control-panel!smooth}
renderer that computes the graph one line at a time.
The location and color of the graph at each visible point on the
screen are determined and displayed using the Phong illumination
\index{Phong!illumination model}
model.
Smooth shading is done in one of two ways, depending on the range
selected in the colormap window and the number of colors available
from the hardware and/or window manager.
When the top and bottom markers of the colormap range are set to
different hues, the graph is rendered by dithering between the
\index{dithering}
transitions in color hue.
When the top and bottom markers of the colormap range are set to
the same hue, the graph is rendered using the Phong smooth shading
model.
\index{Phong!smooth shading model}
However, if enough colors cannot be allocated for this purpose,
the renderer reverts to the color dithering method until a
sufficient color supply is available.
For this reason, it may not be possible to render multiple Phong
smooth shaded graphs at the same time on some systems.
%
\item[Bounds] encloses the entire volume of the
viewgraph within a bounding box, or removes the box if previously selected.
\index{graphics!3D control-panel!bounds}
The region that encloses the entire volume of the viewport graph is displayed.
%
\item[Axes] displays Cartesian
\index{graphics!3D control-panel!axes}
coordinate axes of the space, or turns them off if previously selected.
%
\item[Outline] causes
\index{graphics!3D control-panel!outline}
quadrilateral polygons forming the graph surface to be outlined in black when
the graph is displayed in {\bf Shade} mode.
%
\item[BW] converts a color viewport to black and white, or vice-versa.
\index{graphics!3D control-panel!bw}
When this button is selected the
control-panel and viewport switch to an immutable colormap composed of a range
of grey scale patterns or tiles that are used wherever shading is necessary.
%
\item[Light] takes you to a control-panel described below.
%
\item[ViewVolume] takes you to another control-panel as described below.
\index{graphics!3D control-panel!save}
%
\item[Save] creates a menu of the possible file types that can
be written using the control-panel.
The {\bf Exit} button leaves the save menu.
The {\bf Pixmap} button writes an \Language{} pixmap of
\index{graphics!3D control-panel!pixmap}
the current viewport contents.  The file is called {\bf fricas3D.pixmap} and is
located in the directory from which \Language{} or {\bf viewAlone} was
started.
The {\bf PS} button writes the current viewport contents to
\index{graphics!3D control-panel!ps}
PostScript output rather than to the viewport window.
By default the file is called {\bf fricas3D.ps}; however, if a file
\index{file!.Xdefaults @{\bf .Xdefaults}}
name is specified in the user's {\bf .Xdefaults} file it is
\index{graphics!.Xdefaults!PostScript file name}
used.
The file is placed in the directory from which the \Language{} or
{\bf viewAlone} session was begun.
See also the \spadfunFrom{write}{ThreeDimensionalViewport}
function.
\index{PostScript}
%
\item[Reset] returns the object transformation
\index{graphics!3D control-panel!reset}
characteristics back to their initial states.
%
\item[Hide] causes the control-panel for the
\index{graphics!3D control-panel!hide}
corresponding viewport to disappear from the screen.
%
\item[Quit]  queries whether the current viewport
\index{graphics!3D control-panel!quit}
session should be terminated.
\end{description}

% *********************************************************************
\subsubsection{Light}
% *********************************************************************
\index{graphics!3D control-panel!light}

%
%>>>\begin{texonly}
%
%>>>\begin{figure}[htbp]
%>>>\begin{picture}(183,252)(-125,0)
%>>>\special{psfile=3Dlight.ps}
%>>>\end{picture}
%>>>\caption{Three-Dimensional Lighting Panel.}
%>>>\end{figure}
%>>>\end{texonly}
%

The {\bf Light} button changes the control-panel into the
{\bf Lighting Control-Panel}.  At the top of this panel, the three axes
are shown with the same orientation as the object.  A light vector from
the origin of the axes shows the current position of the light source
relative to the object.  At the bottom of the panel is an {\bf Abort}
button that cancels any changes to the lighting that were made, and a
{\bf Return} button that carries out the current set of lighting changes
on the graph.
%
\begin{description}
%
\item[XY:]  The {\bf XY} lighting axes window is below the
\index{graphics!3D control-panel!move xy}
{\bf Lighting Control-Panel} title and to the left.
This changes the light vector within the {\bf XY} view plane.
%
\item[Z:]  The {\bf Z} lighting axis window is below the
\index{graphics!3D control-panel!move z}
{\bf Lighting Control-Panel} title and in the center.  This
changes the {\bf Z}
location of the light vector.
%
\item[Intensity:]
Below the {\bf Lighting Control-Panel} title
\index{graphics!3D control-panel!intensity}
and to the right is the light intensity meter.
Moving the intensity indicator down decreases the amount of
light emitted from the light source.
When the indicator is at the top of the meter the light source is
emitting at 100\% intensity.
At the bottom of the meter the light source is emitting at a level
slightly above ambient lighting.
\end{description}

% *********************************************************************
\subsubsection{View Volume}
% *********************************************************************
\index{graphics!3D control-panel!view volume}

The {\bf View Volume} button changes the control-panel into
the {\bf Viewing Volume Panel}.
At the bottom of the viewing panel is an {\bf Abort} button that
cancels any changes to the viewing volume that were made and a
{\it Return} button that carries out the current set of
viewing changes to the graph.
%
%>>>\begin{texonly}
%
%>>>\begin{figure}[htbp]
%>>>\begin{picture}(183,252)(-125,0)
%>>>\special{psfile=3Dvolume.ps}
%>>>\end{picture}
%>>>\caption{Three-Dimensional Volume Panel.}
%>>>\end{figure}
%>>>\end{texonly}
%
\begin{description}
%
\item[Eye Reference:]  At the top of this panel is the
\index{graphics!3D control-panel!eye reference}
{\bf Eye Reference} window.
It shows a planar projection of the viewing pyramid from the eye
of the viewer relative to the location of the object.
This has a bounding region represented by the rectangle on the
left.
Below the object rectangle is the {\bf Hither} window.
By moving the slider in this window the hither clipping plane sets
\index{hither clipping plane}
the front of the view volume.
As a result of this depth clipping all points of the object closer
to the eye than this hither plane are not shown.
The {\bf Eye Distance} slider to the right of the {\bf Hither}
slider is used to change the degree of perspective in the image.
%
\item[Clip Volume:]  The {\bf Clip Volume} window is at the
\index{graphics!3D control-panel!clip volume}
bottom of the {\bf Viewing Volume Panel}.
On the right is a {\bf Settings} menu.
In this menu are buttons to select viewing attributes.
Selecting the {\bf Perspective} button computes the image using
perspective projection.
\index{graphics!3D control-panel!perspective}
The {\bf Show Region} button indicates whether the clipping region
of the
\index{graphics!3D control-panel!show clip region}
volume is to be drawn in the viewport and the {\bf Clipping On}
button shows whether the view volume clipping is to be in effect
when the image
\index{graphics!3D control-panel!clipping on}
is drawn.
The left side of the {\bf Clip Volume} window shows the clipping
\index{graphics!3D control-panel!clip volume}
boundary of the graph.
Moving the knobs along the {\bf X}, {\bf Y}, and {\bf Z} sliders
adjusts the volume of the clipping region accordingly.
\end{description}

% *********************************************************************
\head{subsection}{Operations for Three-Dimensional Graphics}{ugGraphThreeDops}
% *********************************************************************

Here is a summary of useful \Language{} operations for \threedim{}
graphics.
Each operation name is followed by a list of arguments.
Each argument is written as a variable informally named according
to the type of the argument (for example, {\it integer}).
If appropriate, a default value for an argument is given in
parentheses immediately following the name.

%
\texht{\bgroup\hbadness = 10001\sloppy}{}
\begin{description}
%
\item[\spadfun{adaptive3D?}]\funArgs{}
tests whether space curves are to be plotted
\index{graphics!plot3d defaults!adaptive}
according to the
\index{adaptive plotting}
adaptive refinement algorithm.

%
\item[\spadfun{axes}]\funArgs{viewport, string\argDef{"on"}}
turns the axes on and off.
\index{graphics!3D commands!axes}

%
\item[\spadfun{close}]\funArgs{viewport}
closes the viewport.
\index{graphics!3D commands!close}

%
\item[\spadfun{colorDef}]\funArgs{viewport,
\subscriptIt{color}{1}\argDef{1}, \subscriptIt{color}{2}\argDef{27}}
sets the colormap
\index{graphics!3D commands!define color}
range to be from
\subscriptIt{color}{1} to \subscriptIt{color}{2}.

%
\item[\spadfun{controlPanel}]\funArgs{viewport, string\argDef{"off"}}
declares whether the
\index{graphics!3D commands!control-panel}
control-panel for the viewport is to be displayed or not.

%
\item[\spadfun{diagonals}]\funArgs{viewport, string\argDef{"off"}}
declares whether the
\index{graphics!3D commands!diagonals}
polygon outline includes the diagonals or not.

%
\item[\spadfun{drawStyle}]\funArgs{viewport, style}
selects which of four drawing styles
\index{graphics!3D commands!drawing style}
are used: {\tt "wireMesh", "solid", "shade",} or {\tt "smooth".}

%
\item[\spadfun{eyeDistance}]\funArgs{viewport,float\argDef{500}}
sets the distance of the eye from the origin of the object
\index{graphics!3D commands!eye distance}
for use in the \spadfunFrom{perspective}{ThreeDimensionalViewport}.

%
\item[\spadfun{key}]\funArgs{viewport}
returns the operating
\index{graphics!3D commands!key}
system process ID number for the viewport.

%
\item[\spadfun{lighting}]\funArgs{viewport,
\subscriptText{float}{x}\argDef{-0.5},
\subscriptText{float}{y}\argDef{0.5}, \subscriptText{float}{z}\argDef{0.5}}
sets the Cartesian
\index{graphics!3D commands!lighting}
coordinates of the light source.

%
\item[\spadfun{modifyPointData}]\funArgs{viewport,integer,point}
replaces the coordinates of the point with
\index{graphics!3D commands!modify point data}
the index {\it integer} with {\it point}.

%
\item[\spadfun{move}]\funArgs{viewport,
\subscriptText{integer}{x}\argDef{viewPosDefault},
\subscriptText{integer}{y}\argDef{viewPosDefault}}
moves the upper
\index{graphics!3D commands!move}
left-hand corner of the viewport to screen position
\allowbreak
({\small \subscriptText{integer}{x}, \subscriptText{integer}{y}}).

%
\item[\spadfun{options}]\funArgs{viewport}
returns a list of all current draw options.

%
\item[\spadfun{outlineRender}]\funArgs{viewport, string\argDef{"off"}}
turns polygon outlining
\index{graphics!3D commands!outline}
off or on when drawing in {\tt "shade"} mode.

%
\item[\spadfun{perspective}]\funArgs{viewport, string\argDef{"on"}}
turns perspective
\index{graphics!3D commands!perspective}
viewing on and off.

%
\item[\spadfun{reset}]\funArgs{viewport}
resets the attributes of a viewport to their
\index{graphics!3D commands!reset}
initial settings.

%
\item[\spadfun{resize}]\funArgs{viewport,
\subscriptText{integer}{width} \argDef{viewSizeDefault},
\subscriptText{integer}{height} \argDef{viewSizeDefault}}
resets the width and height
\index{graphics!3D commands!resize}
values for a viewport.

%
\item[\spadfun{rotate}]\funArgs{viewport,
\subscriptText{number}{\texht{$\theta$}{\spad{theta}}}\argDef{viewThetaDefault},
\subscriptText{number}{\texht{$\varphi$}{\spad{phi}}}\argDef{viewPhiDefault}}
rotates the viewport by rotation angles for longitude
({\it \texht{$\theta$}{\spad{theta}}}) and
latitude ({\it \texht{$\varphi$}{\spad{phi}}}).
Angles designate radians if given as floats, or degrees if given
\index{graphics!3D commands!rotate}
as integers.

%
\item[\spadfun{setAdaptive3D}]\funArgs{boolean\argDef{true}}
sets whether space curves are to be plotted
\index{graphics!plot3d defaults!set adaptive}
according to the adaptive
\index{adaptive plotting}
refinement algorithm.

%
\item[\spadfun{setMaxPoints3D}]\funArgs{integer\argDef{1000}}
 sets the default maximum number of possible
\index{graphics!plot3d defaults!set max points}
points to be used when constructing a \threedim{} space curve.

%
\item[\spadfun{setMinPoints3D}]\funArgs{integer\argDef{49}}
sets the default minimum number of possible
\index{graphics!plot3d defaults!set min points}
points to be used when constructing a \threedim{} space curve.

%
\item[\spadfun{setScreenResolution3D}]\funArgs{integer\argDef{500}}
sets the default screen resolution constant
\index{graphics!plot3d defaults!set screen resolution}
used in setting the computation limit of adaptively
\index{adaptive plotting}
generated \threedim{} space curve plots.

%
\item[\spadfun{showRegion}]\funArgs{viewport, string\argDef{"off"}}
declares whether the bounding
\index{graphics!3D commands!showRegion}
box of a graph is shown or not.
%
\item[\spadfun{subspace}]\funArgs{viewport}
returns the space component.
%
\item[\spadfun{subspace}]\funArgs{viewport, subspace}
resets the space component
\index{graphics!3D commands!subspace}
to {\it subspace}.

%
\item[\spadfun{title}]\funArgs{viewport, string}
gives the viewport the
\index{graphics!3D commands!title}
title {\it string}.

%
\item[\spadfun{translate}]\funArgs{viewport,
\subscriptText{float}{x}\argDef{viewDeltaXDefault},
\subscriptText{float}{y}\argDef{viewDeltaYDefault}}
translates
\index{graphics!3D commands!translate}
the object horizontally and vertically relative to the center of the viewport.

%
\item[\spadfun{intensity}]\funArgs{viewport,float\argDef{1.0}}
resets the intensity {\it I} of the light source,
\index{graphics!3D commands!intensity}
\texht{$0 \le I \le 1.$}{{\it 0 \le I \le 1}.}

%
\item[\spadfun{tubePointsDefault}]\funArgs{\optArg{integer\argDef{6}}}
sets or indicates the default number of
\index{graphics!3D defaults!tube points}
vertices defining the polygon that is used to create a tube around
a space curve.

%
\item[\spadfun{tubeRadiusDefault}]\funArgs{\optArg{float\argDef{0.5}}}
sets or indicates the default radius of
\index{graphics!3D defaults!tube radius}
the tube that encircles a space curve.

%
\item[\spadfun{var1StepsDefault}]\funArgs{\optArg{integer\argDef{27}}}
sets or indicates the default number of
\index{graphics!3D defaults!var1 steps}
increments into which the grid defining a surface plot is subdivided with
respect to the first parameter declared in the surface function.

%
\item[\spadfun{var2StepsDefault}]\funArgs{\optArg{integer\argDef{27}}}
sets or indicates the default number of
\index{graphics!3D defaults!var2 steps}
increments into which the grid defining a surface plot is subdivided with
respect to the second parameter declared in the surface function.

%
\item[\spadfun{viewDefaults}]\funArgs{{\tt [}\subscriptText{integer}{%
point}, \subscriptText{integer}{line}, \subscriptText{integer}{axes},
\subscriptText{integer}{units}, \subscriptText{float}{point},
\allowbreak\subscriptText{list}{position},
\subscriptText{list}{size}{\tt ]}}
resets the default settings for the
\index{graphics!3D defaults!reset viewport defaults}
point color, line color, axes color, units color, point size,
viewport upper left-hand corner position, and the viewport size.

%
\item[\spadfun{viewDeltaXDefault}]\funArgs{\optArg{float\argDef{0}}}
resets the default horizontal offset
\index{graphics!3D commands!deltaX default}
from the center of the viewport, or returns the current default offset if no argument is given.

%
\item[\spadfun{viewDeltaYDefault}]\funArgs{\optArg{float\argDef{0}}}
resets the default vertical offset
\index{graphics!3D commands!deltaY default}
from the center of the viewport, or returns the current default offset if no argument is given.

%
\item[\spadfun{viewPhiDefault}]\funArgs{\optArg{float\argDef{-\texht{$\pi$}{{\it pi}}/4}}}
resets the default latitudinal view angle,
or returns the current default angle if no argument is given.
\index{graphics!3D commands!phi default}
\texht{$\varphi$}{{\it phi}} is set to this value.

%
\item[\spadfun{viewpoint}]\funArgs{viewport, \subscriptText{float}{x},
\subscriptText{float}{y}, \subscriptText{float}{z}}
sets the viewing position in Cartesian coordinates.

%
\item[\spadfun{viewpoint}]\funArgs{viewport,
\subscriptText{float}{\texht{$\theta$}{\spad{theta}}},
\subscriptText{Float}{\texht{$\varphi$}{\spad{phi}}}}
sets the viewing position in spherical coordinates.

%
\item[\spadfun{viewpoint}]\funArgs{viewport,
\subscriptText{Float}{\texht{$\theta$}{\spad{theta}}},
\subscriptText{Float}{\texht{$\varphi$}{\spad{phi}}},
\subscriptText{Float}{scaleFactor},
\subscriptText{Float}{xOffset}, \subscriptText{Float}{yOffset}}
sets the viewing position in spherical coordinates,
the scale factor, and offsets.
\index{graphics!3D commands!viewpoint}
\texht{$\theta$}{{\it theta}} (longitude) and
\texht{$\varphi$}{{\it phi}} (latitude) are in radians.

%
\item[\spadfun{viewPosDefault}]\funArgs{\optArg{list\argDef{[0,0]}}}
sets or indicates the position of the upper
\index{graphics!3D defaults!viewport position}
left-hand corner of a \twodim{} viewport, relative to the display root
window (the upper left-hand corner of the display is \spad{[0, 0]}).

%
\item[\spadfun{viewSizeDefault}]\funArgs{\optArg{list\argDef{[400,400]}}}
sets or indicates the width and height dimensions
\index{graphics!3D defaults!viewport size}
of a viewport.

%
\item[\spadfun{viewThetaDefault}]\funArgs{\optArg{float\argDef{\texht{$\pi$}{{\it pi}}/4}}}
resets the default longitudinal view angle,
or returns the current default angle if no argument is given.
\index{graphics!3D commands!theta default}
When a parameter is specified, the default longitudinal view angle
\texht{$\theta$}{{\it theta}} is set to this value.

%
\item[\spadfun{viewWriteAvailable}]\funArgs{\optArg{list\argDef{["pixmap",
"bitmap", "postscript", "image"}}}
indicates the possible file types
\index{graphics!3D defaults!available viewport writes}
that can be created with the \spadfunFrom{write}{ThreeDimensionalViewport} function.

%
\item[\spadfun{viewWriteDefault}]\funArgs{\optArg{list\argDef{[]}}}
sets or indicates the default types of files
that are created in addition to the {\bf data} file when a
\spadfunFrom{write}{ThreeDimensionalViewport} command
\index{graphics!3D defaults!viewport writes}
is executed on a viewport.

%
\item[\spadfun{write}]\funArgs{viewport, directory, \optArg{option}}
writes the file {\bf data} for {\it viewport}
in the directory {\it directory}.
An optional third argument specifies a file type (one of {\tt
pixmap}, {\tt bitmap}, {\tt postscript}, or {\tt image}), or a
list of file types.
An additional file is written for each file type listed.

%
\item[\spadfun{zoom}]\funArgs{viewport, float\argDef{2.5}}
specifies the scaling factor.
\index{graphics!3D commands!zoom}
\index{scaling graphs}
\end{description}
\texht{\egroup}{}

% *********************************************************************
\head{subsection}{Customization using .Xdefaults}{ugXdefaults}
% *********************************************************************
\index{graphics!.Xdefaults}

Both the \twodim{} and \threedim{} drawing facilities consult
the {\bf .Xdefaults} file for various defaults.
\index{file!.Xdefaults @{\bf .Xdefaults}}
The list of defaults that are recognized by the graphing routines
is discussed in this section.
These defaults are preceded by {\tt FriCAS.3D.}
for \threedim{} viewport defaults, {\tt FriCAS.2D.}
for \twodim{} viewport defaults, or {\tt FriCAS*} (no dot) for
those defaults that are acceptable to either viewport type.

%
\begin{description}
%
\item[{\tt FriCAS*buttonFont:\ \it font}] \ \newline
This indicates which
\index{graphics!.Xdefaults!button font}
font type is used for the button text on the control-panel.
\xdefault{Rom11}
%
\item[{\tt FriCAS.2D.graphFont:\ \it font}] \ (2D only) \newline
This indicates
\index{graphics!.Xdefaults!graph number font}
which font type is used for displaying the graph numbers and
slots in the {\bf Graphs} section of the \twodim{} control-panel.
\xdefault{Rom22}
%
\item[{\tt FriCAS.3D.headerFont:\ \it font}] \ \newline
This indicates which
\index{graphics!.Xdefaults!graph label font}
font type is used for the axes labels and potentiometer
header names on \threedim{} viewport windows.
This is also used for \twodim{} control-panels for indicating
which font type is used for potentionmeter header names and
multiple graph title headers.
%for example, {\tt FriCAS.2D.headerFont: 8x13}.
\xdefault{Itl14}
%
\item[{\tt FriCAS*inverse:\ \it switch}] \ \newline
This indicates whether the
\index{graphics!.Xdefaults!inverting background}
background color is to be inverted from white to black.
If {\tt on}, the graph viewports use black as the background
color.
If {\tt off} or no declaration is made, the graph viewports use a
white background.
\xdefault{off}
%
\item[{\tt FriCAS.3D.lightingFont:\ \it font}] \ (3D only) \newline
This indicates which font type is used for the {\bf x},
\index{graphics!.Xdefaults!lighting font}
{\bf y}, and {\bf z} labels of the two lighting axes potentiometers, and for
the {\bf Intensity} title on the lighting control-panel.
\xdefault{Rom10}
%
\item[{\tt FriCAS.2D.messageFont, FriCAS.3D.messageFont:\ \it font}] \ \newline
These indicate the font type
\index{graphics!.Xdefaults!message font}
to be used for the text in the control-panel message window.
\xdefault{Rom14}
%
\item[{\tt FriCAS*monochrome:\ \it switch}] \ \newline
This indicates whether the
\index{graphics!.Xdefaults!monochrome}
graph viewports are to be displayed as if the monitor is black and
white, that is, a 1 bit plane.
If {\tt on} is specified, the viewport display is black and white.
If {\tt off} is specified, or no declaration for this default is
given, the viewports are displayed in the normal fashion for the
monitor in use.
\xdefault{off}
%
\item[{\tt FriCAS*titleFont \it font}] \ \newline
This
\index{graphics!.Xdefaults!title font}
indicates which font type is used
for the title text and, for \threedim{} graphs,
in the lighting and viewing-volume control-panel windows.
\index{graphics!Xdefaults!2d}
\xdefault{Rom14}
%
\item[{\tt FriCAS.2D.unitFont:\ \it font}] \ (2D only) \newline
This indicates
\index{graphics!.Xdefaults!unit label font}
which font type is used for displaying the unit labels on
\twodim{} viewport graphs.
\xdefault{6x10}
%
\item[{\tt FriCAS.3D.volumeFont:\ \it font}] \ (3D only) \newline
This indicates which font type is used for the {\bf x},
\index{graphics!.Xdefaults!volume label font}
{\bf y}, and {\bf z} labels of the clipping region sliders; for the
{\bf Perspective}, {\bf Show Region}, and {\bf Clipping On} buttons under
{\bf Settings}, and above the windows for the {\bf Hither} and
{\bf Eye Distance} sliders in the {\bf Viewing Volume Panel} of the
\threedim{} control-panel.
\xdefault{Rom8}
\end{description}
