diff options
Diffstat (limited to 'graphics/epix/doc/manual.tex')
-rw-r--r-- | graphics/epix/doc/manual.tex | 5030 |
1 files changed, 5030 insertions, 0 deletions
diff --git a/graphics/epix/doc/manual.tex b/graphics/epix/doc/manual.tex new file mode 100644 index 0000000000..71aa59aa97 --- /dev/null +++ b/graphics/epix/doc/manual.tex @@ -0,0 +1,5030 @@ +%% Version 1.2.0 +\documentclass[12pt]{book} +\usepackage{amsmath,latexsym,epic,eepic,pstricks,xcolor,comment} +\usepackage[dvips,hyperref]{hyperref} + +\usepackage{makeidx} +\makeindex + +\renewcommand{\thefigure}{\arabic{chapter}.\arabic{figure}} + +\newcommand{\code}[1]{\texttt{#1}} +\newcommand{\filename}[1]{\texttt{#1}} +\newcommand{\Key}[1]{\texttt{#1}} +\newcommand{\URL}[1]{\texttt{#1}} + +%% \setlength{\topmargin}{0.5in} +\newcommand{\ePiX}{\code{ePiX}} +\newcommand{\ext}{\code{ePiX\_ext}} +\newcommand{\epix}{\code{epix}} +\newcommand{\eepic}{\code{eepic}} +\newcommand{\C}{\code{C}} +\newcommand{\CXX}{\code{C++}} +\newcommand{\pyepix}{\code{Pyepix}} + +\DeclareMathOperator{\clip}{clip} + +\newcommand{\Header}[1]{\smallskip\noindent\texttt{#1}% + \index{Header file!{#1}@\texttt{#1}}\quad} + +%% Substitution commands easily removable by sed for texinfo: +%% Remove recalcitrant chunks, +\newcommand{\texicomment}{} +\newcommand{\texicommentend}{} + +%% mark simple math, +\newcommand{\teximath}[1]{$#1$} +%% make function index entries, +\newcommand{\findex}[1]{} + +%% top-level division (first argument for texinfo node name) +\newcommand{\texinfochapter}[2]{\chapter{#2}} +\newcommand{\texinfoappendix}[2]{\chapter{#2}} + +%%\renewcommand{\subsection*}[1]{\subsection{#1}} + +\title{ \ePiX\ Tutorial and \\ Reference Manual} +\author{Andrew D. Hwang \\ + Department\ of Math and CS \\ + College of the Holy Cross} +\date{Version 1.2, September, 2007} + +\begin{document} + +\maketitle + +\tableofcontents + +\texinfochapter{1}{Introduction} + +\ePiX, a collection of batch utilities, creates mathematically +accurate figures, plots, and animations containing \LaTeX\ typography. +The input syntax is easy to learn, and the user interface resembles +that of \LaTeX\ itself: You prepare a scene description in a text +editor, then ``compile'' the input file into a picture. \LaTeX- and +web-compatible output types include a \LaTeX\ picture-like environment +written with \code{PSTricks}, \code{tikz}, or \code{eepic} macros; +vector images (\code{eps}, \code{ps}, and~\code{pdf}); and bitmapped +images and movies (\code{png}, \code{mng}, and~\code{gif}). + +\ePiX's strengths include: + +\begin{itemize} +\item Quality of output: \ePiX\ creates accurate, publication-quality + figures whose appearance matches that of \LaTeX. Typography may be + put in a figure as easily as in an ordinary \LaTeX\ document. + +\item Ease of use: Figure objects and their attributes are specified + by simple, descriptive commands. + +\item Flexibility: Objects are described by attributes and Cartesian + location; as in \LaTeX, printed appearance is determined when the + figure is compiled. A well-designed figure can be altered + dramatically, yet precisely, with command-line switches or minor + changes to the input file. + +\item Power and extendibility: \ePiX\ inherits the power of \CXX\ as a + programming language; variables, data structures, loops, and + recursion can be used to draw complicated plots and figures with + just a few lines of input. External code can be incorporated in a + figure with a command line option or by using a Makefile. + +\item Economy of storage and transmission: For a document containing + many figures, a compressed tar file of the \LaTeX\ sources and + \ePiX\ files is typically a few percent the size of the compressed + PostScript file. + +\item License: \ePiX\ is \emph{free software}.\index{Free software} + You are granted the right to use the program for whatever purpose, + and to inspect, modify, and re-distribute the source code, so long + as you do not restrict the rights of others to do the same. In + short, the license is similar to the terms under which theorems are + published. + +\end{itemize} + + +\ePiX\ facilitates logical, as opposed to visual, structuring of +mathematical figures, analogous to the relationship between \LaTeX\ +and a word processor. A few stylistic defaults streamline the creation +of simple figures, but there are few internal restrictions on the +contents or appearance of a figure; aesthetic and practical decisions +are left to you. + +If you are a: + +\begin{itemize} + +\item Potential user, you may wish to skip immediately to ``Software + Dependencies'' before investing additional time. + +\item New user, proceed from here until you have enough understanding + to run the software, then experiment with the samples files while + reading Chapter~\ref{chapter:started}, or return to the manual as + needed. + +\item More advanced user, browse at will, probably starting with + Chapter~\ref{chapter:ref-man}. + +\end{itemize} + +This manual is relatively conversational, and occasionally redundant, +especially between portions meant for readers at different levels of +familiarity. Throughout, you are assumed to be familiar with \LaTeX\ +and basic linear algebra: the description of points, vectors, lines, +and planes in three-dimensional space. Other material, such as \CXX\ +syntax, is introduced as needed. + + +\section{Changes in Version~1.2} + +\ePiX~1.2.x has been written almost entirely from scratch. The +conceptual model is unchanged, but there are a few changes of +syntax. If you're new to~\ePiX, please skip straight to +Section~\ref{section:software_deps}. + + +\subsection{Syntax Changes} + +Except as noted below, \ePiX~1.0 files will compile under +Version~1.2. Generally, global variables have been deprecated or +removed, and should be replaced by function calls in new files. The +following changes are either required, or else strongly recommended +(and may become mandatory). + +\begin{itemize} + +\item (Mandatory) The global variable \verb+tix+ in a \filename{flix} + file must be manipulated through the function \verb+tix()+. + +\item (Mandatory) The command \code{use\_pstricks()} is obsolete. + PSTricks output is obtained systematically as an output format. + +\item (Mandatory) Deprecated ``aliases'' no longer exist: + \code{triple} (for the \code{P} class), \code{D}~(for \code{Deriv}), + and \code{I}~(for \code{Integral}). Lowercase trig function names + conflicted with the standard namespace and have been removed. + +\item (Mandatory) Geometric object commands (\code{circle}, + \code{plane}, \code{segment}, and~\code{sphere}), which formerly + created class objects, now perform drawing just as \code{ellipse}, + \code{line}, \code{rect}, etc., do. The classes are available with + capitalized names (\code{Circle}, etc.). + +\item (Mandatory) Camera orientation is controlled with functions + named \code{tilt}, \code{pan}, and~\code{roll}; each rotates + the camera about an axis through the viewpoint, not through the + target. + +\item (Recommended) The global size variables \verb+x_min+, + \verb+x_max+, \verb+y_min+, \verb+y_max+, \verb+x_size+, and + \verb+y_size+ should be replaced by the function calls + \verb+xmin()+, etc. (No underscores.) + +\item (Suggested) The camera may be accessed through the function + \code{cam()}. + +\item (Suggested) The size and bounding box are given in one command, + such as \code{picture(P(-1,0), P(1,1), "4x3in")}. The old syntax + will be retained indefinitely. + +\end{itemize} + + +\subsection{New Features} + +\begin{itemize} + +\item Output is cleanly separated from the internal representation. + Figures may be written with a choice of macros---\code{PSTricks}, + \code{tikz}, and \code{eepic} at present---and new output types + are easily coded so long as the format supports arbitrary line + segments, color, and the ability to place a \LaTeX\ box at a + specified location. + +\item Colors are a manipulable data type, available in RGB, CMY, CMYK, + and Gray models. \filename{xcolor}-style operations, such as color + model conversion, blending, superposition, and inversion are + provided. + + The camera has a filter which affects the colors of all scene + elements. Filters performing CMYK separation are provided. + +\item Color filling is controlled with declarations, similarly to line + colors in \ePiX~1.0. Arrows and markers of type spot, dot, ddot, + and~circ are now colored like other markers. Parametric surfaces + may be color-shaded. + + If a figure contains many shaded elements, a color-capable output + format (e.g.\ \code{PSTricks}~or \code{tikz}) should be used for + efficiency. Filled regions are implemented as fine hatching in + \filename{eepic}. + +\item An \code{axis} class provides coordinate axes with labels in a + variety of styles: decimals or scientific notation of specified + precision, fractions, trig fractions, logarithmic labels in + arbitrary (integer) base, and user-supplied styles. + +\item \ePiX~1.2.x performs page layout. Sub-figures may be manipulated + flexibly. The sample files give several applications. + +\item Non-member intersection operators for circles, planes, spheres, + and segments are provided. A ``non-generic'' intersection does not + throw an exception, but instead returns an undrawable ``malformed'' + object. + +\end{itemize} + + +\section{Software Dependencies} +\label{section:software_deps} + +\index{Installation|(} +\index{Mac OS X} + +If you run GNU/Linux, a BSD, or Solaris, you probably have (and can +surely install) all the external software needed to use \ePiX. On +Mac~OS~X, you will need the Apple developer tools and an X~server +(XCode and XDarwin on the Tiger disks), and the free~\code{fink} +package manager to build a GNU environment. For Windows, you'll need +to install Cygwin and several packages. Detailed instructions are +given below. + +``Under the hood'', an input file is successively converted to a +\LaTeX\ picture; \code{dvi}; PostScript, \code{pdf}~or \code{eps}; and +if desired, to a bitmapped image or movie. Four shell +scripts---\epix, \code{laps}, \code{elaps}, and~\code{flix}---automate +the various file format conversions. + +\ePiX\ consists of a \CXX\ library, header, and shell scripts, and +requires GNU \code{bash} and a compiler \emph{for normal use}. For +complete functionality, you need \code{g++} (Version~3.2 or later), +\code{bash}, a text editor (\ePiX\ works particularly well with +\code{emacs}), a \LaTeX\ distribution, \code{Ghostscript}, \code{gv} +(or your favorite PS/PDF previewer), and \code{ImageMagick}. GNU +\code{grep} and \code{sed} are good to have. You may need additional +``developer packages'' (\code{binutils}, \code{make}) in order to +build \ePiX. The more up to date your software is, the better your +experience is likely to be, but bleeding edge versions are not +necessary, or even always desirable. + +Aside from their reliance on specific programs, \ePiX's shell scripts +are written using Unix-style pathnames. Thus, the most straightforward +way to use \ePiX\ is to install a GNU environment. + +Jay Belanger's \code{emacs} mode allows you to write, compile, and +view \ePiX\ figures without leaving \code{emacs}. If you use another +editor, you'll want to create template source files so you don't have +to type boilerplate code each time you write a new figure. +\index{Emacs@\code{emacs}} + + +\subsection{Setting up an Environment Under Windows} + +\index{Windows operating system|(} +\begin{comment} +Version~1.0.4 of \ePiX\ has been implemented in Python~2.2 by Andrew +Sterian, making \ePiX\ available on any platform that supports Python, +and without requiring a \CXX~compiler or~\code{bash}. Python is a +GPL-ed scripting language, and is available with a Windows installer +and detailed instructions. The easiest alternative for Windows users +is probably to install Python~2.2 or later (if necessary) and +\code{Pyepix}. The \code{pyepix} project home page is: +\URL{claymore.engineer.gvsu.edu/~steriana/Python/index.html} +\end{comment} + +Cygwin can be used to run \ePiX\ under Windows. Download +\filename{setup.exe} from \URL{www.cygwin.com}, then install the +packages you need. The following are recommended, and sufficient for +the actions described in this manual. +\begin{verbatim} +(Archive) bzip2, tar +(Devel) binutils, coreutils, gcc, gcc-g++, make, sed +(Editors) emacs, emacs-X11, vim +(Graphics) ImageMagick, ghostscript-base, ghostscript-x11, gv +(Publishing) tetex (all) +(Shells) bash, bash-completion +(X11) X-start-menu-icons, X-startup-scripts, + XFree86-lib-compat, xorg-x11-fscl, xorg-x11-fsrv +\end{verbatim} +\index{Windows operating system|)} + + +\section{Installation} + +\ePiX\ is distributed over the World-Wide Web as source code. Packages +may be found at \URL{mathcs.holycross.edu/\~{}ahwang/epix/ePiX.html} +The latest stable release is also on the CTAN mirrors, in the +\code{graphics} directory. (Some users of Red Hat have reported file +permission problems when unpacking the CTAN tarballs. If you encounter +this difficulty, please try downloading the sources from the project +main page.) Unpack the compressed tar file with the appropriate +command: +\begin{verbatim} + tar -zxvf epix-x.y.z.tar.gz + tar -jxvf epix-x.y.z.tar.bz2 +\end{verbatim} +(\code{x.y.z}~is the version number) or, if your \code{tar} +doesn't do decompression, +\begin{verbatim} + gunzip -c epix-x.y.z.tar.gz | tar -xvf - + bzcat epix-x.y.z.tar.bz2 | tar -xvf - +\end{verbatim} +\code{cd} to the source directory, \filename{epix-x.y.z}. The +\filename{INSTALL} file contains detailed installation instructions. +If you're impatient, the short of it is \code{./configure [--options]; + make; make install}. Run \code{./configure --help} for a list of +options. + +By default, \ePiX\ installs in subdirectories of +\filename{/usr/local}; if you want to install elsewhere, supply +\code{./configure} with the appropriate \code{--prefix}. You may also +want to consult \filename{POST-INSTALL} for information on setting +your \code{PATH} variable so your shell can find \ePiX. The manual +and sample files are in \filename{/usr/local/share/doc/epix}. +\index{Installation|)} + + +\subsection{Development} + +There are two mailing lists, one for user questions, one for +development discussion. Please visit +\URL{savannah.nongnu.org/mail/?group=epix} to subscribe. + + +\texinfochapter{2}{Getting Started} +\label{chapter:started} + +This chapter describes the basics of creating figures in \ePiX\ for +readers familiar with \LaTeX\ but completely new to~\CXX. No detailed +knowledge of~\CXX\ is needed to use \ePiX, only a bit of grammar that +is easily absorbed by example. + +Section~\ref{section:running} describes the commands (shell scripts) +comprising \ePiX, and explains how to set up a graphical environment +using standard *nix programs. Section~\ref{section:overview} briefly +describes figure creation. Section~\ref{section:tutorial} presents a +few files side-by-side with their output, and should be read at a +computer so you can run the exercises. + + +\section{Running \ePiX} +\label{section:running} + +An ``input file'' is a human-written figure specification containing +\ePiX\ commands. An ``output file'' is machine-created, and is +included directly into a \LaTeX\ document with the appropriate +packages. + +Conversion (``compiling'' a figure) is accomplished with four shell +scripts, \code{laps}, \code{epix}, \code{elaps}, and \code{flix}. +Each script has a preferred extension for its input files, and is +invoked with a command of the form +\begin{verbatim} + <script> [options] <input file(s)> +\end{verbatim} +Often, no options are necessary. \code{<script> --help} +describes \code{<script>}'s options. +\texicomment +Figure~\ref{fig:programs} (page~\pageref{fig:programs}) diagrams the +shell scripts and the file types they process. +\texicommentend + +By default, output file names are constructed by replacing the input +extension with the (preferred) output extension. For brevity, +extensions may be omitted. If the script has doubts about your intent, +it proceeds with default behavior and prints a warning message. + +The author is a great fan of \Key{TAB} completion, under which a +shell, based on what has been typed so far, automatically fills in a +command when the \Key{TAB} key is pressed. \ePiX\ comes with code +snippets that complete intelligently when the first part of a command +is one of the shell scripts. For example, if command completion is +active, typing \code{epix} \Key{TAB} prints only names of \code{epix} +input files. To use this feature, you must install Ian MacDonald's +\code{bash completion} package. The \filename{INSTALL} and +\filename{POST\_INSTALL} files contain details. + + +\subsubsection*{\code{laps}} + +\code{laps} performs \LaTeX\ to PostScript/PDF conversion, and is +independent of the rest of \ePiX. By default, \code{laps} invokes +\LaTeX~and \code{dvips}. The option \code{--pdf} creates a PDF~file by +post-processing the PostScript with~\code{ps2pdf}. Other \TeX-family +processors (\code{pslatex}, \code{pdftex}, etc.) may be used instead +of~\LaTeX\ by invoking \code{laps} with an appropriate option. + + +\subsubsection*{\code{epix}} + +\code{epix} compiles an input file into a \LaTeX\ picture. The input +file should have extension \filename{xp} (for eXtended Picture). Jay +Belanger's \code{emacs} mode is Highly Recommended; the installation +procedure can be found in the \filename{POST\_INSTALL} file. When this +mode is active, \code{emacs} automatically inserts a preamble template +when a new \filename{xp} file is created. In addition, you can peruse +\ePiX's info file, or format, compile, and preview files, all from +within \code{emacs}. +\index{Emacs@\code{emacs}} + +Output files from the script \code{epix} have extension +\filename{eepic}, after Conrad Kwok's enhancements to the \LaTeX\ +picture environment. In Version~1.2, however, an output file need not +contain \code{eepic} macros at all. + +An output file is \code{input} directly into a \LaTeX\ document whose +preamble contains appropriate \code{usepackage} lines. +\texicomment +\begin{center} + \begin{tabular}{cc} + Format & Required Package(s) \\ + \hline + \code{eepic} & \code{epic,eepic,xcolor} \\ + \code{pst} & \code{pstricks} \\ + \code{tikz} & \code{tikz} + \end{tabular} +\end{center} +\texicommentend +Rotated text requires the \code{rotating} package. + + +\subsubsection*{\code{elaps}} + +\code{elaps} creates stand-alone vector images (\filename{eps}~or +\filename{pdf}) from \code{epix} input files or \filename{eepic} +figures, even those not produced with \code{epix}. \code{elaps} +automatically loads the \LaTeX\ packages needed for features described +in this manual. Additional \LaTeX\ packages and \code{dvips} options +may be specified on the command line. + + +\subsubsection*{\code{flix}} + +\code{flix} creates bitmapped images and movies, +Section~\ref{section:animation}. Input files should have extension +\filename{flx}, and must contain a valid \code{epix} header as well as +additional code. Jay Belanger's \code{emacs} mode facilitates creation +of \code{flix} files. + + +\section{The Drawing Model} +\label{section:overview} + +To draw a figure manually, you select a sheet of paper of appropriate +size and add paths, markers, and labels. These scene elements have +attributes (line color, line width, fill color, font size, etc.) +affecting their appearance. + +\index{canvas} +\ePiX's drawing model behaves similarly. A \code{picture} command +sets the \emph{canvas} (or logical drawing area, a Cartesian +rectangle) and the true size of the final figure. A \code{begin} +command initializes the ``virtual paper'' for drawing. Subsequent +\emph{drawing commands} add objects to the scene: lines, curves, +function plots, labels, and the like. The printed appearance of scene +elements is determined by the current ``attribute state'' and +controlled by \emph{style declaration} which remain in effect until +superseded. Finally, an \code{end} command closes the figure and +prints it to the output file. + +In this manual, command descriptions follow a few +conventions. Optional arguments are enclosed in square brackets. A +\code{len} argument is either a number (representing a length in +\code{pt}) or a double-quoted string containing a number and a +two-letter \LaTeX\ length unit, such as \code{"1.5pt"} or +\code{"6cm"}. A \code{color} argument is a named primary +(\code{Red()}, \code{Cyan()}, \code{White()}, etc.), or a \code{Color} +specified by densities (\code{RGB(r,g,b)}, \code{CMY(c,m,y)}, etc.) + +\begin{itemize} + +\item Fill color: \code{fill(color)}, \code{nofill()}. + +\item Line color and width: \code{plain([color])}, + \code{bold([color])}. + +\item Text size: \code{font\_size([size])}, returns to + \code{normalsize} if no argument is given. + +\end{itemize} + +\noindent A complete list of style commands is found in +Section~\ref{section:quickref}, starting on +page~\pageref{section:quickref}. + +To handle three-dimensional scenes, a \code{camera} performs point +projection from a selected spatial location to the canvas. As a user, +you'll need to control relatively few of the \code{camera}'s +parameters. Keep in mind, however, that elements are added to a scene +in the same order their commands appear in the output file, and that +later elements generally cover earlier ones. Some three-dimensional +scenes require manual ordering of the input file; such ordering is +dependent on the \code{camera}'s location. + +By default, \ePiX\ draws thin, solid, black lines, performs no filling +of regions, prints text in a 12~pt Roman font, and looks down the +\teximath{z}~axis from a large distance, giving orthogonal projection +on the \teximath{(x,y)}~plane. When the \code{camera} is moved, the +\teximath{z}~axis points vertically up on the page. + + +\section{Tutorial} +\label{section:tutorial} + +This section presents sample input files side-by-side with their +output so you can compare what you write with what you'll see on the +screen or page. \ePiX\ provides standard drawing capabilities, but +like all software has its own idioms and personality. The basic +syntax, which comes from \code{C}/\CXX, should be mostly +self-explanatory. One-line comments begin with the +string~``\verb+//+''. + + +%%\index{Emacs@\code{emacs}} +\index{Graphical interface} +To use the sample files interactively, you'll need working software: +\filename{bash}, \filename{emacs}, \ePiX, \filename{g++}, +\filename{gv}, and a running X~server. To complete your ``GUI'', +start~\filename{gv} and select ``Watch file'' from the ``State'' +menu. The loaded file will update automatically when it changes. + +Create a ``scratch'' directory, \code{cd} into it, and run the command +\begin{verbatim} + tar -zxf /usr/local/share/doc/epix/sample_src.tar.gz +\end{verbatim} +(Change the path as appropriate for your installation.) This unpacks +copies of the sample files into your scratch directory, including all +the files mentioned in this manual. The \filename{README} file serves +as a table of contents. + +Open a sample file in \filename{emacs}, compile it from the drop-down +menu (or with the keyboard command), then open the \filename{EPS} file +in~\filename{gv}. Now you're ready to follow the tutorial +interactively. A few suggested exercises are included with each +file. Naturally, as you study more files, you'll be able to make more +interesting changes on your own. + + +\subsubsection*{Basic Drawing} + +The first sample, \filename{hello.xp}, contains code needed to specify +the figure's size, followed by the classic greeting. The \code{border} +command draws a box around the figure in the specified color and +width, and serves here merely to delimit the output from the +surrounding page. +\begin{verbatim} +/* -*-ePiX-*- */ +#include "epix.h" // These lines are analogous +using namespace ePiX; // to a usepackage command. + +int main() +{ + picture(P(-1,-1), P(1,1), "2 x 1in"); // corners, true size + + begin(); // ---- Figure body starts here ---- + + border(Black(), "1pt"); // color, line width + + font_size("Huge"); // May be any font size, e.g. "scriptsize" + label(P(0,0), "Hello, world!"); + + end(); // ---- End figure; write output file ---- +} +\end{verbatim} + +\begin{center} + \input{hello.eepic} +\end{center} + +\begin{itemize} + +\item Change the color and width of the + border. (\code{RGB(r,g,b);} creates an RGB color, CMY colors are + analogous. Named primaries are available. The densities should be + between \teximath{0}~and \teximath{1} for ``expected'' behavior.) + +\item Add \code{backing(Cyan());} after the \code{border} command. + +\item Put the command \code{crop\_ellipse();} before the \code{border} + command. Permute the \code{crop\_ellipse} command with the + \code{border} and \code{backing} lines, and note how the attribute + (\code{crop}) affects objects (\code{border}, \code{backing}). + +\end{itemize} + + +\subsubsection*{Geometric Objects} + +Our next file uses simple objects to draw a 2-D house-and-sun scene. + +\begin{verbatim} +int main() +{ + picture(P(0,0), P(5,2), "3.75 x 1.5in"); + + begin(); + + triangle(P(0.9, 1), P(3.1, 1), P(2, 1.5)); // vertices + circle(P(4,1.5), 0.25); // center and radius + + rect(P(1,0), P(3,1)); // opposite corners + + fill(Black(0.1)); // light gray + rect(P(2.3,0), P(2.7,0.8)); // the door + nofill(); + + bold(); // draw thicker lines + grid(P(1.4, 0.2), P(2, 0.6), 2, 2); // corners, number of squares + + line(P(xmin(), 0), P(xmax(), 0)); // endpoints + + end(); +} +\end{verbatim} + +\begin{center} + \input{objects.eepic} +\end{center} + +\begin{itemize} + +\item Add declarations such as \code{bold(RGB(1,0.9,0.5))} or + \code{fill(Yellow())} to color the scene. (Color and filling are + orthogonal attributes.) +\end{itemize} + +\noindent The sample file \filename{house.flx} uses loops to draw +gradient fills of the lawn, sky, and sun, and animates a sunset. + + +\subsubsection*{Function Plotting} + +Plotted functions must be defined in the ``preamble'', before +\code{main}. ``High-level'' elements---coordinate axes and grids, axis +labels, and graphs---are drawn with mnemonically-named commands. +\begin{verbatim} +// double = double-precision floating point +double f(double x) { return 0.75*Sin(x) - 0.25*Sin(2*x); } + +int main() +{ + picture(P(-2,-1), P(2,1), "5 x 1in"); // [-2,2] x [-1,1] + + begin(); + revolutions(); // set angle units, [0,1] = one turn + + h_axis(16); // axes w/default endpts + v_axis(4); + h_axis_labels(4, P(0,-4), b); // shift down 4pt, align below + + plain(Red()); + plot(f, xmin(), xmax(), 120); // use 120 intervals + + end(); +} +\end{verbatim} + +\begin{center} + \input{plotting.eepic} +\end{center} + +\begin{itemize} + +\item Define and plot some different functions; adjust the bounding + box as necessary. (Use repeated multiplication for polynomials. + The \code{polarplot} command graphs \teximath{r=f(\theta)}.) + +\item Change the arguments to \code{h\_axis\_labels}. The first + specifies the number of intervals to label; the second gives the + label offset in~\code{pt}. The last puts each label below~(\code{b}) + its Cartesian location. + +\end{itemize} + + +\subsubsection*{Multivariable Plotting} + +Functions of two or three variables are defined just like functions of +one variable, but for plotting the return type must be a +point~(\code{P}), not a real number~(\code{double}). The \code{domain} +class specifies the set of inputs to plot. + +\begin{verbatim} +P f(double r, double th) +{ + return P(r*Cos(th), r*Sin(th), pow(r, 3)*Cos(3*th)); +} + +int main() +{ + picture(P(-1,-1), P(1, 1), "2 x 1in"); + begin(); + pst_format(); // use PSTricks macros for output + + // corners ([0,1] x [0,2\pi]) and fineness + // (8x40 rectangles, plotted at 16x120 resolution) + domain R(P(0,0), P(1, 2*M_PI), mesh(8,40), mesh(16,120)); + + camera.at(P(3,1,2)); // set the viewpoint + arrow(P(0,0,0), P(1.25,0,0)); // coordinate axes + arrow(P(0,0,0), P(0,1.25,0)); + + plain(Blue(1.2)); // line color and width + fill(Yellow()); // shading color + surface(f, R); + + end(); +} +\end{verbatim} + +\begin{center} + \input{plotting2.eepic} +\end{center} + + +\subsubsection*{Loops and Control Structures} +\label{taylor_poly} + +A function can be defined by an arbitrary algorithm, and a +\code{domain} may be used to plot a family of functions for several +values of one variable. + +\begin{footnotesize} +\begin{verbatim} +P sin_n(double x, double n) // Taylor polynomial of sin x +{ + const int N((int) floor(n)); // convert n to an index bound + const double sqx(-pow(x, 2)); // -x^2 + double val(x), summand(x); + + for (int i=1; i <= 2*N+1; i += 2) + { + summand *= (sqx/((i+1)*(i+2))); // (-1)^i x^{2i+1}/(2i+1)! + val += summand; + } + + return P(x, val); // return (x, y) +} + +int main() +{ + picture(P(0, -1), P(6*M_PI, 1), "5 x 1in"); + + begin(); + + set_crop(); + bold(Green()); + plot(Sin, 0, xmax(), 120); + + domain R(P(0,1), P(6*M_PI, 41), mesh(60, 40), mesh(120, 40)); + for (int i=3; 0 <= i; --i) // print in descending degree + { + bold(RGB(0.25*i, 0, 1-0.25*i)); // degree-dependent color + plot(sin_n, R.slice2(5*i+1)); // plot for n = 5i+1 + } + end(); +} +\end{verbatim} +\end{footnotesize} + +\begin{center} + \input{plotting3.eepic} +\end{center} + + +\subsubsection*{Page Layout} + +Page layout can be composed from sub-pages with \code{screen} objects. +In the loop body below, objects are added to the ``active'' +\code{screen}, then \code{inset} into the ``canvas'', the screen +representing the entire figure. + +\begin{verbatim} +P f(double u, double v) +{ + return P((u-v)*(u+v), 2*u*v, u); +} + +int main() +{ + picture(P(0,0), P(2,3), "5x7.5in"); // overall size + + begin(); + + domain R(P(-1,-1), P(1,1), mesh(12,12), mesh(24,24)); + + for (int i=0; i<2; ++i) + for (int j=0; j<3; ++j) + { + screen my(P(-3,-3), P(3,3)); + activate(my); + border(Red(0.6), "1pt"); + // frame-dependent viewpoint + camera.at(sph(10, (2*j+i+1)*M_PI/8, M_PI/6)); + + plot(f, R); + arrow(P(0,0,0), 2*E_1); + arrow(P(0,0,0), 2*E_2); + // SW corner at (i, 2-j), padded by 0.05 on all sides + inset(P(i+0.05,2.05-j), P(i+0.95,2.95-j)); + } + + end(); +} +\end{verbatim} + +\begin{center} + \input{layout.eepic} +\end{center} + + +\section{\CXX\ Basics} + +\index{Cplusplus@\CXX|(} +An \ePiX\ source file is a \CXX~program. If you've successfully +modified and compiled the sample files, you know enough~\CXX\ to use +\ePiX. In the author's experience, \code{C}~grammar suffices for most +applications. An excellent introduction to definitions of functions +and variables, control statements, and overall program structure is +Kernighan~and Ritchie's \emph{The \code{C} Programming Language}, +second edition~\cite{KnR}. + + +\subsection{File Format} + +\index{Emacs@\code{emacs}} +Jay Belanger's \code{emacs} mode for \code{ePiX} inserts a file +template when an empty buffer is opened with the extension~\code{xp}. +This section explains the purposes served by the template. A few +additional remarks may help you avoid basic syntax pitfalls. + +A \CXX\ file consists of ``statements'', analogous to ordinary +sentences. Common types include \emph{declarations} (which +``register'' a function, variable, or type name with the compiler), +\emph{definitions} (which assign meaning to declared names), and +\emph{function calls} (which cause a named function to execute). Most +statements in an \ePiX\ input file are function calls (``commands''). +Plain declarations are relatively rare in user files, since a +definition serves to declare any new names that it contains. + +Every statement ends with a semicolon, and conventionally a file +contains at most one statement per line. The compiler ignores +nearly all whitespace (spaces, tabs, and newlines), which should be +used freely to make files easy to read. Other punctuation +(periods, commas, (semi)colons, parentheses, braces, and quotes) +dictates file parsing, and must adhere stringently to grammar. + +An \ePiX\ file always begins with the lines +\findex{include} +\begin{verbatim} +#include "epix.h" // N.B. pre-processor directive, no semicolon +using namespace ePiX; +\end{verbatim} +The first line is analogous to a \LaTeX\ \code{usepackage} command: It +loads the contents of the ``header'' file \filename{epix.h}, importing +the names of commands provided by~\ePiX. To avoid name conflicts, +\ePiX's commands are enclosed in a ``namespace''. For example, the +\code{label} command is actually known to the compiler as +\code{ePiX::label}. The second line above tells the compiler to apply +the prefix tacitly. + + +\subsection{Variables and Functions} +%% \index{Variable}\index{Variable!names} +%% \index{Function}\index{Function!names} + +Definitions of variables and functions play the same role in a figure +that macro definitions play in a \LaTeX\ document: gathering and +organizing information on which the figure depends. A variable is +defined by supplying its type, name, and initial value. By far the +most common data types in~\ePiX\ are \code{double} (double-precision +floating point number), \code{P}, and \code{int}. The name of a +variable may consist (only) of letters (including the underscore +character) and digits, and must begin with a letter: +\begin{verbatim} +my_var, var2, MY_var, aLongVariableName; // valid +my-var, 2var, \v@riable, $x, ${MY_VARIABLE}; // not valid +\end{verbatim} +Variable names are case-sensitive, and numerous (non-universal) +conventions govern the significance of capitalization. Generally, make +names descriptive but not unwieldy, and avoid language keywords (such +as \code{const}, \code{true}, \code{double}, \code{class}, or +\code{public}) and names that begin with an underscore. + +A function accepts ``arguments'' and ``returns a value''. To define a +function in~\CXX, you must specify the return type, the name of the +function, the types of the arguments, and the algorithm by which the +value is computed from the inputs. The code block +\begin{verbatim} +double f(double x) +{ + return sqrt(1-x*x); +} +\end{verbatim} +specifies the \code{double}-valued function~\teximath{f} of one \code{double} +variable defined by the formula \teximath{f(x)=\sqrt{1-x^2}}. + + +\subsection{Comments} + +\CXX\ has two types of comments. \code{C}-style comments, which may +span several lines, are delimited by the strings \code{/*}~and +\code{*/}. One-line comments, analogous to the \LaTeX~\code{\%}, are +begun with \code{//}. A one-line comment may appear within a multi-line +comment, but a \code{C}-style comment may not; the compiler will +mistake the first~\code{*/} it encounters as the end of the current +multi-line comment. + + +\subsection{Program Execution} + +All the ``action'' in a \CXX\ program occurs inside the special +function~\code{main}. Running a compiled \CXX~program is viewed by the +operating system as calling the program's \code{main} function. The +return value (an \code{int}) is the program's exit status. The +contents of the output file start with \code{begin()} and terminate +with \code{end()}. Intervening statements constitute the \emph{body} +of the file. + +In \CXX, a function may not be defined inside another function. Thus, +variables may be defined inside \code{main}, but functions cannot be. + + +\subsection{Strings and Raw Output} + +In \CXX, a \code{string} is a sequence of characters. Most +\code{string}s in \ePiX\ input files are \emph{literals}, +double-quoted \code{string}s whose value is read from the input. In a +string literal, backslash is an escape character; a single backslash +is produced by a double backslash in the input file. Certain letters +have special meanings when backslash-escaped, including ``\verb+\n+'' +(newline) and ``\verb+\t+'' (\Key{TAB}). Unlike~\LaTeX, \CXX~does not +require a space to separate an escape sequence from following text; +the string ``\verb+\\textwidth+'' literally represents a \LaTeX\ +command, while ``\verb+\textwidth+'' is read ``\code{TABextwidth}'' by +the compiler. + +Though not commonly needed, raw text can be printed to the output +file. The functions \code{write}, \code{pre\_write}, and +\code{post\_write} accept \code{string} arguments. \code{write} prints +its argument where the call appears in the input file. The other +functions print their arguments before or after the completed picture, +respectively. These commands must be in the file body. As an +application, a complete \LaTeX\ \code{figure} environment (with +caption and label) can be produced by an \ePiX\ file, +Figure~\ref{fig:captioned}. + +\index{pre\_write} +\index{post\_write} +\index{write} +\findex{pre\_write} +\findex{post\_write} +\findex{write} +\begin{figure} +\begin{footnotesize} +\begin{verbatim} +#include "epix.h" +using namespace ePiX; + +int main() +{ + picture(P(-1,-1), P(1,1), "10cm x 3in); + begin(); + pre_write("\\begin{figure}[hbt]"); // comes before the picture + + post_write("\\caption{A \\LaTeX\\ figure.}"); // and after + post_write("\\end{figure}"); + + < ... other ePiX commands ... > + write("%% A comment near the end, but inside the picture."); + end(); +} // End of main() +\end{verbatim} +\end{footnotesize} +\caption{Generating a self-contained figure in \ePiX.} +\label{fig:captioned} +\end{figure} + + +\subsection{Conditionals and Loops} + +An algorithm's behavior usually depends on internal state. A +\emph{conditional statement} causes blocks of code to be executed +according to criteria. A \emph{loop} repeatedly executes a code +block, usually changing the values of variables in a predictable way, +so that the loop exits after finitely many traversals. + +\texicomment +Figure~\ref{fig:gcd} illustrates conditionals and loops with +Euclid's algorithm for the greatest common divisor. Three pieces of +notation require explanation: \code{j\%i} means~``\teximath{j\pmod i}'', +\code{||} is logical~``or'', and \code{==} is ``test for equality''. +(A single~``\code{=}'' is the assignment operator.) + +\index{Function!Euclidean algorithm} +\begin{figure}[hbt] +\begin{footnotesize} +\begin{verbatim} +int gcd (int i, int j) +{ + int temp(i); // initialization syntax + if (i==0 || j==0) + return i+j; // define gcd(k,0) = k + + else { + if (j < i) // swap them + { + temp = j; + j = i; + i = temp; + } + // the work is done here... + while (0 != (temp = j%i)) // assign temp, test for zero + { + j = i; + i = temp; + } + return i; + } +} +\end{verbatim} +\end{footnotesize} +\caption{Euclid's division algorithm in~\CXX.} +\label{fig:gcd} +\end{figure} +\texicommentend + +%% \noindent For details on conditionals, or for more advanced techniques +%% of \CXX\ programming, please consult a textbook or online tutorial. +\index{Cplusplus@\CXX|)} + +%% Force previous two figures onto the same page +%%\clearpage + +\section{Animation} +\label{section:animation} + +\index{Animation|(} +\ePiX\ is well-suited to the creation of mathematically accurate +animations: If a figure depends suitably upon a ``time'' parameter, +then a loop can be used to draw the entire figure for multiple time +values, yielding successive ``snapshots'' of the figure as time +progresses. The shell script~\code{flix} automates the process of +compiling a suitable input file into a collection of \filename{png}s +and assembling these frames into a \filename{mng}~or \filename{gif} +animation. ImageMagick is the image-handling engine. + +A \code{flix} file is an \code{epix} file with two restrictions: +\begin{itemize} + \item The \code{double} variable \code{tix()} is used as + ``clock''. + + \item \code{main} accepts two command line arguments and sets + \code{tix()} accordingly. +\end{itemize} +\index{Emacs@\code{emacs}} +Jay Belanger's \code{emacs} mode recognizes the file +extension~\filename{.flx} and inserts template code if an empty buffer +is opened. Creation of \code{flix} files is as easy as creation of +\code{epix} files. The \filename{samples} directory contains a +handful of \code{flix} files that may be consulted for ideas. + +By default, \code{flix} creates movies with 24~frames, in which +\code{tix()} runs from~0 to~1, and animates at +\teximath{0.08}~sec/frame. These and other parameters can be changed +with command-line options. + +A ``typical'' \code{.flx} file may take 30~seconds to a few minutes to +compile, depending on the number of frames and the complexity of each +frame. To facilitate debugging, \code{elaps} can be run on a +\code{flix} file. \code{elaps} runs in a fraction of the time, and if +\code{elaps} can't produce a viewable image, \code{flix} will surely +fail. While running, \code{flix} prints a progress bar counting the +number of \filename{eps} files that have been created. There will be +a delay of a few seconds (or more) after the last frame is produced, +during which ImageMagick's \code{convert} utility assembles the movie. +\index{Animation|)} + + +\section{Layout Tricks} +\label{section:layout} +\index{Layout} + +\subsection{Stereograms} +\index{Stereograms} +Stereograms are created by drawing a single scene twice from slightly +different points of view. To create a stereogram with \ePiX, write a +``scene'' function containing the necessary drawing commands, then set +the camera appropriately and call the scene function twice, once for +each frame. + +\subsubsection*{Crossed-Eyes Stereograms} + +The sample files \filename{lorenz.xp}~and \filename{twisted\_cubic.xp} +use page layout to draw crossed-eyes stereograms. For each frame, +create and activate a \code{screen}, set the camera, and call the +scene function. The frames are inset side by side in the final +picture. For a crossed-eyes stereogram, the frame from the +``rightmost'' camera position is placed on the left. + +\subsubsection*{Bi-Color Stereograms} + +The sample files \filename{cube.flx}~and \filename{mirrorball.flx} +contain animated red-cyan stereograms, suitable for viewing with 3-D +glasses. The technique works best with black-and-white line drawings, +but the basic approach is the same as for crossed-eyes stereograms: +Create a scene function and call it twice, setting the camera +appropriately. Layout is unnecessary since the frames are superposed. +Pen colors should be close to red and cyan, but ``optimal'' choices +depend on one's eyes and 3-D glasses. + +\subsubsection*{Stereographic Movies} + +Either form of stereogram can be animated in a \code{.flx} file, but +keeping one's eyes properly crossed requires practice while most +people can instantly see depth with 3-D glasses. As always when using +\code{flix}, debug the scene with \code{elaps} before compiling a +movie. If a stereoscopic effect is difficult to see in a still image, +it will be even harder to perceive in a movie. + + +\subsection{Inset Images} + +\ePiX\ can place external images into a figure, similarly to +Rolf Niepraschk's \code{overpic} package. You provide the Cartesian +center point, the file name, and optionally the true height and/or +width of the image: +\findex{label} +\begin{verbatim} + label(P(a,b), "\\includegraphics[width=w,height=h]{file}"); +\end{verbatim} +This effect requires the \filename{graphicx} package. When compiling a +stand-alone graphic containing an external image, you must specify the +\filename{graphicx} package on the command line: \code{elaps -p +graphicx <file>} + +\texicomment +\begin{figure}[hbt] + \begin{center} + \input{ePiX.eepic} + \end{center} + \caption{Visual guide to \ePiX's shell scripts} + \label{fig:programs} +\end{figure} +\texicommentend + + +\texinfochapter{3}{Reference Manual} +\label{chapter:ref-man} + +This chapter details \ePiX's capabilities, discussing attributes and +data types, and listing available commands in the form +\begin{verbatim} + label(P posn, [P offset], string text, [align]); + circle(P ctr, double rad=1, normal=P(0,0,1)); +\end{verbatim} +As in Chapter~\ref{chapter:started}, function arguments are given by +type (\code{P}, \code{double}, \code{string}, etc.)\ and name, or by +name alone if the type is clear. Optional arguments are enclosed in +square brackets. A few argument types, such as \code{[align]} above, +admit only a small number of values; these cases are explained when +the corresponding command is first introduced. + +A name followed by an equals sign and a value indicates a default +argument; if omitted in an input file, the compiler substitutes the +default value. Only trailing arguments may be specified this way. For +example, if the \code{rad} argument of the \code{circle} command is +omitted, the \code{normal} argument \emph{must} be omitted as well. + +In an input file, only an argument's value is given, not the type: +\begin{verbatim} + label(P(0,0), P(0,-4), "Hello world", b); + circle(P(0,-0.25), sqrt(2)); // use default normal +\end{verbatim} + +Generally, \code{len} signifies either a number (representing a length +in \code{pt}) or a double-quoted string containing a number and a +two-letter \LaTeX\ length unit, such as \code{"1.5pt"} or +\code{"6cm"}. \code{color} represents a \code{Color} object +constructed from a named primary (\code{Blue()}, \code{Magenta(0.7)}, +etc.), a color specification (\code{RGB(r,g,b)}, \code{CMY(c,m,y)}, +etc.), or an operator applied to an existing \code{Color}. + + +\section{File Structure} + +An \ePiX\ input file constitutes a short \CXX\ program. When this +program is compiled and run by one of the shell scripts, it creates a +figure file suitable for inclusion in \LaTeX. + +\index{Preamble} +Like a \LaTeX\ document, an \ePiX\ file contains a \emph{preamble}, +which sets up a drawing environment, and a \emph{body}, which contains +actual figure-generating commands. The minimal file has the form +\findex{picture} +\findex{begin} +\findex{end} +\begin{verbatim} +#include "epix.h" // N.B. no semicolon +using namespace ePiX; + +int main() { + picture(P(a1,b1), P(a2,b2), "n1 [unit1] x n2 unit2"); + begin(); // end of preamble, start of body + end(); // end of body +} +\end{verbatim} +\ePiX\ commands are of four general types: drawing, attribute setting, +definitions (of data and functions), and operations on existing +objects. Except as noted below, drawing and attribute commands must +appear in the body, between \code{begin()}~and \code{end()}. Function +definitions must come in the preamble, before \code{main()}. Data +definitions may appear in the preamble or body. + + +\subsubsection*{Output Format} +\index{Output format} + +The \code{end()} command writes the output file to \code{stdout}, +using \code{eepic} macros by default. The shell scripts redirect +\code{stdout} to an appropriate disk file. + +The attribute-setting command \code{pst\_format()} causes the output +file to be written using \code{PSTricks} macros when \code{end} is +called. Similarly, \code{tikz\_format()} causes the file to be written +using \code{tikz} macros, and \code{eepic\_format()} causes the file +to be written using \code{eepic} macros. These commands may appear +anywhere in the figure body. There is no reason for a file to contain +more than one such command. + +The output format may be selected on the command line, overriding any +explicit request in the input file. Supplying \code{epix}, +\code{elaps}, or \code{flix} with one of the options \code{--pst}, +\code{--tikz}, or \code{--eepic} is tantamount to issuing a +\code{pst\_format()} (etc.)\ command just before the end of the +file. These options are listed in decreasing precedence. If more than +one is given, the ``strongest'' applies, regardless of the command +line order. + +A figure may be written directly to a specified disk file, in a format +unaffected by the command line flags above. The command +\begin{verbatim} + print_eepic("file.tex"); +\end{verbatim} +writes the figure to the named file using \code{eepic} +macros. Analogous commands exist for the formats \code{pst}~and +\code{tikz}. These commands perform an immediate action. Consequently, +the command's location in the input file is significant, and multiple +commands may appear in a single file, so long as distinct file name +arguments are provided. Applications include writing the same figure +in multiple formats, or creating successive ``snapshots'' of a lengthy +computation. + + +\section{Picture Size and Aspect Ratio} + +\index{Picture!size} +\index{Picture!offset} +The \code{picture} command specifies a figure's logical and true +sizes. In the ``minimal file'' snippet above, the \emph{canvas} is the +Cartesian rectangle \teximath{[a_1,a_2]\times[b_1,b_2]} whose corners +are given. Either pair of opposite corners is acceptable, but +confusion is less likely when the SW~and NE corners are given, in this +order. + +The true (printed) width and height are read from \code{picture}'s +third argument, a ``size \code{string}'' such as \verb+"4cm x 1in"+, +containing a number and optional \LaTeX\ length unit, an~\code{x}, +another number, and a mandatory length unit. Spaces may be used for +legibility. The mandatory length unit becomes the \LaTeX\ +\code{unitlength}. The argument \verb+"4cm x 1in"+ creates a picture +4~cm wide and 1~in high, but internally converts 4~cm to inches. +Recognized length units are \code{pt} (points, the default), \code{cm} +(centimeters), \code{in} (inches), \code{mm} (millimeters), \code{pc} +(picas), and \code{bp} (big points). +(\code{1in = 2.54cm = 72bp = 72.27pt}, \code{1pc = 12pt}.) + +The logical and true sizes may be defined separately with the commands +\findex{bounding\_box} +\findex{picture} +\findex{unitlength} +\begin{verbatim} + bounding_box(P(a1,b1), P(a2,b2)); + picture(n1, n2); + unitlength(len); // len a length string, not a double +\end{verbatim} +One way or another, the logical and true dimensions \emph{must} have +positive values when the \code{begin()} command is issued. + +\LaTeX\ treats the contents of a picture environment as a single box, +aligned by default on its lower left corner. An \code{offset} command +accepts two \code{double} arguments or a size \code{string} and shifts +the page location accordingly. The command +\code{offset("0.25 x -0.5cm")} shifts the picture right +\teximath{0.25}~cm and down \teximath{0.5}~cm. If the +\code{unitlength} is 1~cm, the command \code{offset(0.25, -0.5)} has +the same effect. + +A non-zero \code{offset} causes a picture's contents to appear in a +location where \LaTeX\ does not expect them. This can be useful in a +\LaTeX\ document, but should be avoided when compiling a stand-alone +image, since \code{dvips} may crop according to rules of its own. + + +\index{Picture!aspect ratio} +\index{Picture!bounding box} +The canvas's corners are \code{(xmin(),ymin())} and +\code{(xmax(),ymax())}, while its width and height are +\code{xsize()}~and \code{ysize()}. The canvas is a virtual, advisory +data structure; its dimensions are not directly related to the +figure's printed size, and picture elements may lie outside the +canvas. Affine scaling maps the canvas to the page when the output +file is written. +\begin{center} +\input{scaling.eepic} +\end{center} +\label{page:scaling} +The figure's aspect ratio is controlled by sizing the canvas. The +aspect ratio is ``true'' if the canvas and page rectangles are +geometrically similar, e.g., if both boxes are 1.5~times as wide as +they are tall. + + +\section{Color} +\label{section:color} + +\index{Color|(} +\ePiX\ provides a \code{Color} data type. Four models are implemented: +\code{RGB}, \code{CMY}, \code{CMYK}, and \code{Gray}. A \code{Color} +holds primary color ``channels'', each carrying an intensity between +0~(no color) and~1 (full saturation). ``No color'' means black in +\code{RGB} and \code{Gray}, white in \code{CMY(K)}. \code{RGB}, +\code{CMY}, and~\code{CMYK} colors are written to the output file as +commands in the corresponding model. \code{Gray} shades are written +in~\code{RGB}. + +Operations on red-green-blue colors are described below. Functionally, +colors are converted to~\code{RGB}, operated upon, then converted back +to the original model. Conversions are as described in Uwe Kern's +\filename{xcolor} manual~\cite{xcolor}. + + +\subsection{Constructors} + +Each color model has a ``constructor'' creating a color of specified +densities. The \code{RGB}~and \code{CMY} models have named ``primary'' +constructors; the density argument is optional and defaults to~1. +\findex{RGB} +\findex{Red} +\findex{Green} +\findex{Blue} +\findex{White} +\findex{Black} +\begin{verbatim} + // red-green-blue colors + RGB(double r=0, double g=0, double b=0); + Red(d=1); Green(d=1); Blue(d=1); + White(d=1); Black(d=1); +\end{verbatim} +\findex{CMY} +\findex{Cyan} +\findex{Magenta} +\findex{Yellow} +\findex{CMY\_White} +\findex{CMY\_Black} +\findex{CMYK} +\findex{Gray} +\begin{verbatim} + // cyan-magenta-yellow colors + CMY(double c=0, double m=0, double y=0); + Cyan(d=1); Magenta(d=1); Yellow(d=1); + CMY_White(d=1); CMY_Black(d=1); + + // gray + Gray(double d=0); // equivalent to RGB(d, d, d) +\end{verbatim} +Each \code{CMY} constructor has a corresponding \code{CMYK} function, +e.g.\ \code{CyanK()}~or \code{CMYK\_White()}. + +Though color densities lie between 0~and 1, \ePiX's primary color +constructors take arguments mod~4, viewed as elements +of~\teximath{[-2,2]}. Consider \code{Red(d)}, ``red with +density~\teximath{d}''. For integer values of~\teximath{d}, the +constructor has the following meanings: \code{Red(0)}~is black, +\code{Red(1)}~is red, \code{Red(2)}=\code{Red(-2)}~is white, and +\code{Red(-1)}~is anti-red, or cyan. For non-integer~\teximath{d}, the +constructor interpolates between the bracketing integer values, +Figure~\ref{fig:densities}. Other primary constructors work +analogously. + +\begin{figure}[hbt] + \begin{center} + \input{color_density.eepic} + \end{center} + \caption{The red primary constructor.} +\label{fig:densities} +\end{figure} + +Let \teximath{\delta:[-2,2]\to[0,1]} be the piecewise-linear function +that converts real numbers to primary color densities, +\teximath{\clip:\mathbf{R}\to[0,1]} the clipping function. The +non-primary constructor \code{RGB(r, g, b)} computes the density of +the red channel as +\teximath{\clip\bigl(\delta(r)+\delta(-g)+\delta(-b)\bigr)}; the green +and blue channel densities are computed similarly. Every color can be +created with arguments between 0~and 1, but the constructor accepts +arbitrary real arguments and returns colors varying ``continuously and +periodically''. + +\index{Color!transparency} +Colors possess an ``alpha-channel'' for transparency. Except as +supported by the output format, this feature is a stub. + + +\subsection{Color Operations} + +Colors can be scaled, inverted, blended, superposed, and filtered. In +the code below, \code{tint}~is a \code{Color}. The effect of each +operation is described in the \code{rgb} model; the visual result is +the same in all models. +\findex{Color.invert} +\findex{Color.blend} +\findex{Color.superpose} +\findex{Color.alpha} +\findex{Color.filter} +\begin{verbatim} + tint *= double c; // multiply channels by c, rebuild + tint.invert(); // (r, g, b) -> (1-r, 1-g, 1-b) + tint.blend(Color col, double t); // (1-t)*tint + t*col + tint.superpose(col); // add channels, then clip to [0,1] + tint.alpha(double d); // set alpha channel to clip(d) + + tint.filter(col); // return min density in each channel +\end{verbatim} +Except for \code{filter}, these operators modify their object. +\code{filter} simulates the effect of viewing \code{col} +through a transparent sheet of \code{tint}, and returns a new +\code{Color} object having the same model as \code{tint} without +modifying \code{tint} itself. + + +\section{Scene Attributes} + +Objects in a scene sit in 3-dimensional space. A \emph{camera} +maps objects to the \emph{active screen}. The active \code{screen} +may, in turn crop its contents. Each drawing command creates an +object, ``photographs'' it, and adds the image to the active +\code{screen}. This section describes the \code{Camera} and +\code{screen} classes and a few associated concepts. + + +\subsection{Angular Mode} +\index{Angle units} + +By default, angles are measured in \code{radian}s. Two other angular +modes are available: \code{degrees}~and \code{revolutions}. The +angular mode is set with a named command, \code{radians()}, +\code{degrees()}, or \code{revolutions()}. The current angular mode +affects all trigonometric functions and operations. + + +\subsection{The Camera} +\index{Camera|(emph} +\index{Screen|(} + +Three-dimensional scenes are drawn on flat paper by applying a +mathematical transformation. By default, \ePiX\ uses \emph{point +projection}, the technique used by art students when they trace on a +window with grease pencil, Figure~\ref{fig:camera}. + +\begin{figure}[hbt] + \begin{center} + \input{camera.eepic} + \end{center} + \vspace*{-0.25in} + \caption{Point projection.} + \label{fig:camera} +\end{figure} + +\index{Camera!viewpoint} +\index{Viewpoint} +\ePiX\ depicts a Cartesian world by projecting mathematically to a +screen plane, then affinely scaling to a printed page. The camera, +which maps the world to the screen, consists of a \emph{body} (data +that determines the position and orientation of the camera), a +\emph{lens} (the actual mapping to the screen plane), and a +\emph{filter} (a color through which the scene is viewed). + + +\subsubsection*{Body} + +The camera's spatial orientation is described by a triple of mutually +perpendicular unit vectors. In memory of happy days at the beach, +these vectors are called \emph{sea}, \emph{sky}, and~\emph{eye}. The +screen plane is parallel to the sea-sky plane; the sea vector points +horizontally to the right, sky points vertically upward. The eye is +their cross product, which points directly at the viewer. + +The sea-sky-eye basis is located at the \emph{viewpoint}, the camera's +spatial location. The \emph{target}, the origin of the screen plane, +lies on the line through the viewpoint in the direction opposite the +eye vector. The distance from the viewpoint to the target is the +\emph{range}. The \emph{camera sphere} is centered at the viewpoint +and passes through the target. The orientation, viewpoint, target, +and range completely (and redundantly) determine the camera's +geometric situation in the world. + + +\subsubsection*{The Lens} +\index{Camera!lens} + +A \emph{lens} maps the world to the screen. \ePiX\ comes with four +lenses: \emph{shadow} (the default), \emph{orthogonal}, +\emph{fisheye}, and \emph{bubble}. Each lens simulates the appearance +of world objects as seen by an observer at the viewpoint. The shadow +lens is point projection from the viewpoint to the screen plane. The +orthogonal lens projects from infinite distance. Each of the other +lenses performs radial projection to the camera sphere, then maps the +sphere to the screen plane; the fisheye lens does orthogonal +projection (so the entire image lies inside the disk centered at the +target whose radius is the range) while the bubble lens does +stereographic projection from the target's antipode. +\index{Screen|)} + + +\index{Camera!manipulation|(} +An input file normally uses a single camera, so a global object named +\code{camera} is defined automatically. At the start of a figure, the +\code{camera} looks down on the \teximath{(x_1,x_2)}-plane from a +distant point on the \teximath{x_3}-axis. The resulting view, +essentially projection along the axis, is suitable for 2-dimensional +figures. + +The \code{camera} is manipulated similarly to a real camera: +\findex{Camera.at} +\findex{Camera.look\_at} +\findex{Camera.range} +\findex{Camera.focus} +\findex{Camera.tilt} +\findex{Camera.pan} +\findex{Camera.roll} +\findex{Camera.clip\_range} +\begin{verbatim} + camera.at(P posn); // set viewpoint to posn + camera.look_at(P targ); // set target to targ + camera.range(double dist); // fix target, move viewpoint + camera.focus(double dist); // fix viewpoint, move target + camera.tilt(double angle); // rotate about the sea axis + camera.pan(double angle); // rotate about the sky axis + camera.roll(double angle); // rotate about the eye axis + camera.clip_range(dist); // cull scenery closer than dist +\end{verbatim} +Explicitly setting the viewpoint or target makes the sky vector +parallel to the projection of the \teximath{x_3}~axis when possible; +otherwise the \teximath{x_2}-axis is used. Setting the range or focus +moves the \code{camera} parallel along the eye line. Each command +re-sizes the image; note that increasing the focus \emph{enlarges} the +image. The three rotation operations fix the viewpoint, but only roll +fixes the target. + + +\subsubsection*{Filtering and Color Separation} +\index{Color!separation} +\index{Camera!color separation} + +The \code{camera} has a \emph{filter} through which all scene +\code{Color}s pass. For uniformity, the filter should only be set at +the start of the file body, before any visible elements have been +placed in the scene. The filter has two primary uses---model +conversion and color separation---but can also be used for special +effects. + +There is a \code{Neutral} color, for which filtering has no effect at +all. The \code{camera}'s default filter is \code{Neutral}. In +addition, each color model has a \emph{neutral} representative, +\code{RGB\_Neutral}, etc. Passing \code{Color}s through a neutral +filter preserves their appearance but converts them to the neutral +\code{Color}'s model. + +Filtering can be used to ``split'' a \code{Color} into primary +constituents. For \code{RGB} channels, the primaries themselves are +suitable filters. For \code{CMYK} channels, there are special +\emph{process} filters, named \verb+C_Process+, etc. +\begin{verbatim} + camera.filter(CMY_Neutral()); // convert all colors to CMY + camera.filter(Gray_Neutral()); // black and white photography + camera.filter(Green()); // the green channel + camera.filter(M_Process()); // the magenta channel + camera.filter(Red(1.4)); // la vie en rose? +\end{verbatim} +\index{Camera!manipulation of|)} +\index{Camera|)} + + +\subsection{Clipping} + +\index{Clipping|(} + +Two operations handle elements lying far from the target. +\emph{Cropping} culls elements based on their screen location, and is +described later. \emph{Clipping} removes objects whose spatial +location lies outside the ``clip region''. + +Initially, the clip region is a very large box centered at the +origin. Commands are provided to resize this box, keeping the faces +parallel to coordinate planes. +\findex{clip\_box} +\findex{clip\_to} +\begin{verbatim} + clip_box(P pt1, P pt2); // opposite corners + clip_box(P pt); // opposite corners pt and -pt + clip_to (P pt); // pt and P(0,0,0) + clip_box(); // very large box +\end{verbatim} +Additional ``clippers'' may be added manually. Individual clipping +planes are specified by a point and inward-pointing normal vector. +Parallel planes cutting a ``slice'' or ``slab'' are described by a +location, direction, and a distance. The location lies halfway between +the clipping planes, and the planes' normals point toward the location. +\findex{clip\_face} +\findex{clip\_slice} +\findex{clip\_restore} +\begin{verbatim} + clip_face(P loc, P perp); // perp points inward + clip_slice(loc, perp); // very close parallel planes + clip_slice(loc, perp, dist); // planes separated by dist + clip_restore(); // remove manually-added clip planes +\end{verbatim} +Like \code{clip\_restore}, the \code{clip\_box} and \code{clip\_to} +commands remove all user-specified half spaces. +\index{Clipping|)} + + +\subsection{Screens and Page Layout} +\index{Screen|(} +\index{Screen!active} +\index{Layout} + +By default, drawing occurs in the Cartesian coordinate system of the +\code{canvas}. However, insets and subfigures are most naturally +composed in ``local'' coordinates, then placed into their final +location as a unit, a process called \emph{layout}. \ePiX\ implements +layout with the \code{screen} class. + + +\subsubsection*{Screens} +\index{Bounding box} + +A \code{screen} is a Cartesian plane containing a distinguished +coordinate rectangle, its \emph{bounding box}. The \code{canvas} of a +figure is a \code{screen}, as is the internal representation of the +printed page. At any point of a file body, some \code{screen} is +\emph{active}, or ``open for drawing''. A new \code{screen} is created +from a pair of opposite corners, but is not used until explicitly +activated. +\findex{activate} +\findex{deactivate} +\begin{verbatim} + screen subfig(P(a1,b1), P(a2,b2)); // [a1, a2] x [b1, b2] + activate(subfig); // open subfig for drawing + // commands to draw in subfig + deactivate(subfig); // re-activate the previous screen +\end{verbatim} + +The \code{canvas} is automatically drawn at the \code{end} of the +input file. The contents of other \code{screen}s must be incorporated +into the \code{canvas} explicitly with an \code{import}~or +\code{inset} command. \code{import} affinely scales the bounding box +of the ``child'' \code{screen} to the \code{canvas}. \code{inset} +specifies corners in the ``parent'' where the child is +placed. +\findex{import} +\findex{inset} +\begin{verbatim} + import(); // active screen to canvas + import(subfig); // subfig to canvas + inset(P sw, P ne); // active screen to specified rectangle + inset(subfig, sw, ne); // subfig to specified rectangle + inset(subfig); // inset to subfig's corners +\end{verbatim} + + +\subsubsection*{Extracting} + +The portion of a \code{screen} enclosed by a specified rectangle can +be \emph{extracted}. Each of the commands +\findex{extract} +\findex{canvas} +\begin{verbatim} + subfig.extract(P sw, P ne); + canvas().extract(P sw, P ne); +\end{verbatim} +returns the \code{screen} having stated corners and containing part of +\code{subfig} or the \code{canvas}, respectively. Elliptical and +diamond-shaped portions of a \code{screen} may be extracted. The +contents occupy the ellipse or diamond inscribed in the given +rectangle. +\findex{extract\_diamond} +\findex{extract\_ellipse} +\begin{verbatim} + subfig.extract_ellipse(sw, ne); + canvas().extract_diamond(sw, ne); +\end{verbatim} +The \code{screen} returned by \code{extract} (or its variants) may be +used just like a manually-constructed \code{screen}, for example to +construct a magnified inset. + + +\subsubsection*{True-Size Drawing} +\label{truesize} + +On occasion, it is necessary to draw at known page size, independently +of the unit length. For 2-dimensional drawing in the +\teximath{(x_1,x_2)}-plane with the \code{camera} in its default +location, the coordinates (horizontal, vertical, or both) of a +\code{screen} may be interpreted as true~pt offsets relative to a +specified point rather than as Cartesian coordinates. +\findex{inlay} +\findex{inlay\_horizontal} +\findex{inlay\_vertical} +\begin{verbatim} + inlay(subfig, P loc); + inlay_horizontal(subfig, loc); + inlay_vertical(subfig, loc); +\end{verbatim} +Each command maps the origin of \code{subfig} to the specified +location in the active \code{screen}. The first performs affine +scaling so that one Cartesian unit in \code{subfig} maps to one +true~pt on the page. The second and third commands perform this +scaling only in the named direction. + +\findex{pt\_to\_screen} +The \code{inlay} functions are suitable only for 2-dimensional +effects. For 3-dimensional true-size drawing, the function +\code{pt\_to\_screen} converts a true length of 1~pt into Cartesian +coordinates in the active \code{screen}. For example, the command +\code{line(P(0,0), P(pt\_to\_screen(12),0))} draws a line segment +12~pt long with its left endpoint at the Cartesian origin. True size +drawing is unusual in an input file, but has definite uses in library +code; \ePiX's right angle marker is a typical application. + +Either type of true-size drawing works as described when drawing in +the \code{canvas}, and \emph{only} when drawing in a \code{screen} +imported to the \code{canvas} at ``true Cartesian'' size (one +\code{screen} unit maps to one Cartesian unit in the \code{canvas}). +In other situations, the true size coordinate(s) will be scaled by +additional affine transformation(s). + + +\subsubsection*{Cropping and Decorations} + +\index{Cropping} +A \code{screen} has a \emph{crop mask}: rectangular (default), +elliptical, or diamond-shaped. If cropping is switched on in the +active \code{screen}, added elements are cropped to the crop mask. +For example, cropping by the default crop mask in the \code{canvas} +ensures the figure lies inside the printed region allocated by +\LaTeX. + +The \code{crop} commands below affect the active \code{screen} +only. Cropping is not a ``global'' attribute, but must be set or unset +explicitly for each \code{screen}. By default, cropping is switched +off. +\findex{crop} +\findex{crop\_ellipse} +\findex{crop\_diamond} +\findex{set\_crop} +\begin{verbatim} + set_crop(); // activate cropping + set_crop(false); // deactivate cropping + crop_diamond(); // <>-shaped mask, set crop state + crop_ellipse(); // etc... + crop(); // crop active screen's contents +\end{verbatim} +Normally the crop mask is inscribed in the \code{screen}'s bounding +box. The commands \code{crop\_diamond} and \code{crop\_ellipse} also +accept a pair of \code{P}~arguments, which are treated as corners of +the crop box. + +The active \code{screen} may be decorated with a \code{border} +(outline of specified color and line width) and \code{backing} (solid +fill color). The crop mask determines the shape of the \code{border} +and \code{backing}. +\findex{border} +\findex{backing} +\begin{verbatim} + border(color, len); + backing(color); +\end{verbatim} +Identically-named member functions can be applied to an arbitrary +\code{screen} whether or not it is active: +\begin{verbatim} + scr.crop_rectangle().backing(Blue(1.8)); + canvas().crop(); +\end{verbatim} + + +\subsubsection*{Affine Maps} +\index{Affine map} + +A \emph{plane affine map} has the form \teximath{T(x) = Ax+b} for some +invertible \teximath{2\times2} matrix~\teximath{A} and a constant +vector~\teximath{b}. \ePiX's \code{affine} class allows affine maps to +be built and applied to \code{screen}s' contents. + +An affine map is uniquely determined by the images of three +non-collinear points. The constructor returns the affine map sending +the points \teximath{(1,0)}, \teximath{(0,1)}, and~\teximath{(0,0)} to +\code{pt1}, \code{pt2}, and~\code{pt0}, respectively. +\findex{affine} +\begin{verbatim} + affine af(P pt1, P pt2, P pt0=P(0,0)); +\end{verbatim} +To emphasize, the arguments are locations, not displacements, and the +image of the origin comes last. There is also a \code{void} +constructor (taking no arguments) which returns the identity map. + +To facilitate construction of affine maps, an existing \code{affine} +may be post-composed with a variety of ``elementary'' affine +transformations. In the commands below, \code{th} is an angle (in +current units), \code{sc} is a non-zero \code{double}, and \code{ctr} +is a point fixed by the composing transformation. In each command, +\code{ctr} defaults to \teximath{(0,0)}. +\findex{shift} +\findex{rotate} +\findex{reflect} +\findex{h\_scale} +\findex{v\_scale} +\findex{scale} +\findex{h\_shear} +\findex{v\_shear} +\findex{postcomp} +\begin{verbatim} + affine af; // the identity map + af.shift(P arg); // translate by arg + af.rotate(th, [ctr]); // counterclockwise rotation about ctr + af.reflect(th, [ctr]); // reflect across line through ctr + + af.h_scale(sc, [ctr]); // horizontal scaling + af.v_scale(sc, [ctr]); // vertical scaling + af.scale(sc, [ctr]); // dilatation + + af.h_shear(sc, [ctr]); // shear preserving horizontals + af.v_shear(sc, [ctr]); // shear preserving verticals + + af.invert(); // the inverse + af.postcomp(affine f); // post-compose with f + af(f); // pre-compose, af not modified +\end{verbatim} +A non-invertible \code{affine} can be created \emph{only} by shearing +or scaling with an extremely large or extremely small argument, or by +supplying three collinear points to the constructor. Calling +\code{invert} on a non-invertible map merely issues a warning and +performs no action. + +An \code{affine} may be applied to a \code{screen}'s current contents. +The \code{screen} class has eight member functions (\code{shift} +through \code{shear}) with syntax identical to the affine map +functions. In addition, an arbitrary \code{affine} may be applied to a +\code{screen}: +\findex{apply} +\begin{verbatim} + scr.shift(arg); // shift scr's contents by arg; etc. + scr.apply(f); // apply f to scr's contents +\end{verbatim} +To apply a composition of several maps to a \code{screen}, it's best +to build an \code{affine} map by composition, then \code{apply} the +map. Composing \code{affine}s is cheap; \code{apply}ing an +\code{affine} is costly in proportion to the number of elements in the +\code{screen}. + +Applying an \code{affine} to a \code{screen} has no effect on the +bounding box, \code{border}, or \code{backing}, and may move elements +outside the bounding box even if cropping is active. To ensure a +\code{screen}'s contents lie inside the bounding box, \code{crop} the +\code{screen} \emph{after} \code{apply}ing the \code{affine}(s). + +The sample file \filename{inverse.xp} uses \code{affine} maps to +depict branches of inverse functions in one variable, +\filename{symmetry.xp} depicts the permutation group~\teximath{S_3} +by its action on a regular hexagon. +\index{Screen|)} + + +\section{Drawing Attributes} + +\ePiX\ maintains drawing states for filled regions, paths, and text +objects. + + +\subsection{Filled Regions} + +\index{Filling} +\index{Path|(} +\index{Path!filled} +Filling is either on or off. When filling is active, closed paths are +filled with the current \emph{fill color}. +\findex{fill} +\findex{nofill} +\begin{verbatim} + fill(); // turn filling on + fill(color); // turn filling on, specify color + nofill(); // turn filling off, same as fill(false); +\end{verbatim} + + +\subsection{Paths} + +Paths and borders of filled regions are drawn with two \emph{pen}s, +each described by color and line width. The \emph{line pen} draws +all path-like objects. The \emph{base pen} does nothing unless it is +wider then the line pen, in which case it draws an ``underlayer'' or +``border'' on the line pen. +\findex{pen} +\begin{verbatim} + pen(len); // set line pen width + pen(color); // set line color, keep width + pen(color, len); // set color and width +\end{verbatim} +As usual, \code{len} may be either a length string or a \code{double}, +interpreted as a width in~\code{pt}. There are \code{base} functions +with the same signatures and analogous meanings for the base pen. + +The line width can be set with named declarations; the optional +argument sets the line color: +\findex{plain} +\findex{bold} +\findex{bbold} +\begin{verbatim} + plain([color]); // 0.4pt + bold([color]); // 0.8pt + bbold([color]); // 1.6pt +\end{verbatim} + + +\subsubsection*{Path Style} + +\index{Path!style} +By default, path-like objects are drawn with solid lines. Dashed, +dotted, and free-form path style patterns are also available. (The +\code{base} underlayer is always solid.) The page length of a pattern +defaults to 12~pt, but can be set. +\findex{line\_style} +\findex{dash\_size} +\begin{verbatim} + line_style(string); + dash_size(len=12); +\end{verbatim} +The path style is set with a WYSIWYG string of dashes, spaces, and +periods, representing a pattern of dashes, gaps, and dots. In the +sample styles below, the repeating units have the same page size, +12~pt. +\begin{center} + \input{pathstyle.eepic} +\end{center} +For brevity and uniformity, named commands are provided. +\findex{solid} +\findex{dashed} +\findex{dotted} +\begin{verbatim} + solid(); "-" dashed(); "- -" dotted(); " . " +\end{verbatim} +A sequence of \teximath{n}~dashes, spaces, and dots corresponds to a +dash/dot pattern in an interval divided into \teximath{n}~subintervals +of equal length. If the \teximath{i}th character is a dash or space, +the \teximath{i}th~subinterval is drawn solid or empty, +respectively. If the \teximath{i}th~character is a period, a dot is +placed at the midpoint of the \teximath{i}th~subinterval. + +This pattern is applied to a path-like object as follows. The page +length of each edge is divided by the current \code{dash\_size} and +the ceiling (next largest integer) taken. This many copies of the +current path style are scaled onto the edge. The first and last +characters are adjacent in repeated units. + +There are three inequivalent ways to adjust the dash length/dot +spacing in a non-line path: Change the \code{dash\_length}, create a +path with a different number of points, or use a longer, repetitive +pattern. For best results, the style string should not be longer than +about a dozen characters. + +If you need several dashed/dotted line styles in multiple figures, +it's best to define a custom header instead of hard-coding line +styles. See Section~\ref{section:extensions} for guidance. +\index{Path|)} + + +\subsection{Text Objects} + +\index{Labels|(emph} +\index{Labels!alignment} + +Two types of textual element may appear in a file: \emph{labels} (text +boxes) and \emph{markers} (\LaTeX\ symbols). A marker occupies a box +of zero size, and is placed at a specified Cartesian location. A label +has typographical size, and is usually offset from its Cartesian +location. For placement, an \emph{alignment point} is attached to each +label, and Cartesian coordinates position the alignment point. + +\subsubsection*{Labels} + +A label is printed as a \LaTeX\ box. By default, the alignment point +is its reference point, the intersection of the left edge and the +baseline, which is used by \LaTeX\ to position the box on the +page:\input{basepoint.eepic} + +\index{Labels!alignment|(} +The alignment point may be \emph{offset} manually by a specified +number of \code{pt}. Additionally, a label's location with respect to +the alignment point can be chosen with an optional \LaTeX-style +alignment option. This scheme allows labels to be placed easily where +they will not overlap other parts of the figure, and ensures labels +stay properly positioned when the size or aspect ratio of a figure +changes. +\findex{label} +\begin{verbatim} + label(P posn, P offset, string msg, [align]); + label(posn, msg); +\end{verbatim} +The first two components of the \code{offset} argument are numbers +of~\code{pt} to shift the alignment point right and up. The optional +\code{align} argument may be one---or an appropriate pair---of +\code{t}, \code{b}, \code{r}, or~\code{l} (top, bottom, right, left), +or~\code{c} (center). These alignment options specify the position of +the label \emph{relative to the Cartesian location}~\code{posn}, +namely they work \emph{opposite} to the way they work in \LaTeX. +\begin{center} + \input{alignment_lr.eepic}\qquad + \input{alignment.eepic} +\end{center} +\index{Labels!alignment|)} + +The \code{msg} argument is usually a snippet of \LaTeX\ code enclosed +in double quotes. \CXX~treats ``\verb+\+'' as an escape character, so +a double backslash is needed in the source to get a single backslash +in the output. For example, +\begin{verbatim} + label(P(0,0), P(2,-1), "$\\rho = \\sin\\theta$", br); +\end{verbatim} +positions an alignment point \code{2pt}~right and \code{1pt}~below the +(Cartesian) origin, and typesets the equation +\teximath{\rho=\sin\theta} below and to the right. + +\index{Labels!rotated} +\index{Angle units} +Labels can be rotated; the (counterclockwise) angle is set in current +angle units with the command \code{label\_angle(theta)}. For example, +a rotation angle of~90 degrees prints labels along a vertical +axis. Though label rotation has legitimate uses, it can make labels +more difficult to read, defeating their purpose. Do not use rotated +labels merely because they are available. As a practical matter, if an +output file contains rotated labels, the enclosing document must use +the \code{rotating} package. \code{elaps} automatically loads this +package. + +\index{Affine map!action on labels} +An \code{affine} behaves moderately intelligently when acting on a +marker or label. The mapping is applied to the label's location, and +the ``linear part'' is used to adjust the offset and label angle. No +attempt is made to treat alignment. For best results, if a +\code{screen} will have an \code{affine} applied to it, label +positions should be fine-tuned only with offsets, not alignment +arguments. In all situations, the font itself is unchanged; no +attempt is made to print sheared, scaled, or reflected text. The +sample file \filename{inverse.xp} illustrates the effect of affine +maps on labels. + + +\subsubsection*{Fonts and Type Size} + +\index{Fonts} +\index{Labels!fonts in} +By default, the font in an \ePiX\ figure is that of the enclosing +document. The font size and face are changed with +``declaration-style'' commands such as +\findex{font\_size} +\findex{font\_face} +\begin{verbatim} +font_size("Large"); +font_face("sc"); +\end{verbatim} +The argument of \verb+font_size+ is a valid \LaTeX\ size. If no +argument is given, \code{normalsize} is understood. \verb+font_face+ +accepts a two-letter string, appended to the string ``\code{text}'' to +give a \LaTeX\ font declaration command (``\code{textsc}'' above). +Finer-grained control is accomplished by placing \LaTeX\ commands +into the label text. + + +\subsubsection*{Label Attributes and Masked Labels} + +Each label command has a corresponding ``mask'' version +(\code{masklabel}) that draws an opaque rectangle under the label +text. The mask size exceeds the label's size by an amount of +\emph{padding}, and the mask is itself surrounded by a rectangular +\emph{border}, of specified color and width. +\findex{label\_color} +\findex{label\_mask} +\findex{label\_pad} +\findex{label\_border} +\findex{no\_label\_border} +\begin{verbatim} + label_color(color); // set label text color + label_mask(color=White()); // set mask color + label_pad(string len); + + label_border(color, [len]); // set color (and line width) + label_border(len); // set line width only + no_label_border(); // turn off label borders +\end{verbatim} + + +\subsubsection*{Markers} + +\index{Marker types|(} +\ePiX's marker types, listed in Table~\ref{table:marker}, are obtained +with the command \verb+marker(P pt, <MARKER TYPE>);+ Several +``dot-like'' marker types are available by name: \input{dots.eepic} +\findex{spot} +\findex{dot} +\findex{ddot} +\findex{box} +\findex{bbox} +\findex{ring} +\findex{circ} +\begin{verbatim} + spot(P pt); dot(P pt); ddot(P pt); + --- box(P pt); bbox(P pt); + ring(P pt); circ(P pt); --- +\end{verbatim} +A \code{circ} is filled with the current \code{mask\_color}, and a +\code{ring} is ``hollow''. Each dot-like marker can also be called +with label syntax, generating a labeled marker with one command. +\begin{verbatim} + dot(P posn, offset=P(0,0), msg="", align=none); // etc. +\end{verbatim} + +\findex{dot\_size} +By default, \code{spot}~and \code{ring} are 4~pt in diameter; +\code{dot}, \code{box}, and~\code{circ} are 3~pt in diameter; +\code{ddot}~and \code{bbox} are 2~pt in diameter. At arbitrary +diameter, a \code{spot} is \teximath{4/3}~the diameter of a~\code{dot} +and a~\code{ddot} is \teximath{2/3}~the diameter. The command +\code{dot\_size(diam=3)} sets the diameter of a \code{dot}, and hence +the size of all dot-like markers. + +\begin{table}[tb] + \begin{center} + \input{marker.eepic} + \end{center} + \caption{\ePiX's \code{marker} types.} + \label{table:marker} +\end{table} +\index{Marker types|)} + + + +\subsubsection*{Reminders} + +When constructing and placing a label, +\begin{itemize} +\item Offsets are specified in \code{pt} (true length), not Cartesian + units: A label's location relative to its alignment point should not + depend on the logical or printed size of the figure. + +\item The label text is enclosed in double quotes (the single + character~\code{"}), and contains the \LaTeX\ code to generate the + label. Backslashes are doubled. + \index{Labels!backslash in} + \index{Labels!in double quotes} +\end{itemize} +\index{Labels|)} + + +\subsection{Color Declarations} + +Old-style color declarations set the fill color, line color, and +text color. +\findex{rgb} +\findex{cmyk} +\begin{verbatim} + rgb(r, g, b); cmyk(c, m, y, k); + rgb(P); cmyk(P); // for function-controlled colors + red(d); // similarly for other primaries +\end{verbatim} +\index{Color|)} + + +\section{Creating and Drawing Objects} + +Scene elements include geometric objects, coordinate grids, axis +labels, and function plots. A few commands create an object (a point, +line segment, circle, sphere, or plane) that can be used in subsequent +computations, but most drawing commands automatically create, draw, +and discard objects. + + +\subsection{Geometric Data Structures} + +\index{Point|(} +The simplest object in the world, and by far the most common named +data structure, is~\code{P}, an ordered triple of real numbers +(double-precision floats). The function~\code{P(x1,x2,x3)} creates the +point~\teximath{(x_1,x_2,x_3)}. If only two arguments are provided, +\teximath{x_3=0} by default. This convention allows \ePiX\ to treat +2-~and 3-dimensional figures uniformly. The standard basis is +available: \code{E\_1=P(1,0,0)}, etc. + +Depending on context, a \code{P} may represent either a +\emph{location} (point) or a \emph{displacement} (vector). Almost all +\ePiX\ functions treat a~\code{P} as a point. However, algebraic +operators and commands that plot vector fields treat \code{P} +arguments as displacements. + +Polar, cylindrical, and spherical coordinate \code{P}~constructors are +sensitive to the current angular mode. +\index{Angular mode} +\findex{P} +\findex{polar} +\findex{cis} +\findex{cyl} +\findex{sph} +\begin{verbatim} + P pt=polar(r,t); // (r*Cos(t), r*Sin(t), 0) + P pt=cis(t); // (Cos(t), Sin(t), 0) = polar(1, t) + P pt=cyl(r,t,z); // (r*Cos(t), r*Sin(t), z) + P pt=sph(r,t,phi); // polar(r,t)*Cos(phi) + (0,0,r*Sin(phi)) +\end{verbatim} + +Algebraic operations---addition/subtraction, scalar multiplication; +scalar, cross, and componentwise products; orthogonalization---can +be performed on~\code{P}s. In compound expressions, the binary +operators below should be enclosed in parentheses, and scalars must be +collected at left, \code{P}s at right. +\findex{P.x1} +\findex{P.x2} +\findex{P.x3} +\findex{J} +\begin{verbatim} + double u=pt.x1(); // first coordinate of pt, etc. + P(a,b,c)|P(x,y,z); // scalar product, ax+by+cz + P(a,b,c)&P(x,y,z); // componentwise product (ax, by, cz) + P(a,b,c)*P(x,y,z); // cross product (bz-cy, cx-az, ay-bx) + J(p); // quarter turn about the x3-axis + p%q; // orthogonalization, p (mod q) +\end{verbatim} +Explicitly, \code{p\%q}~is the unique vector \code{p+k*q} +perpendicular to~\code{q}. + +\code{P}~operations express mathematical relationships, and therefore +imbue a figure with logical structure, making the input file easier to +read, modify, and maintain. Commonly, a file preamble will define a +few named points with hard-coded coordinates, then define additional +points of interest using \code{P}~operators. +\index{Point|)} + + +\subsubsection*{Other Geometric Classes} + +In addition to~\code{P}, objects of type \code{Circle}, \code{Plane}, +\code{Segment}, and \code{Sphere} can be used for Euclidean geometry +constructions. Simple affine operations are supplied for each type, as +is a \code{draw()} function, which represents the object as a path in +the screen. +\findex{shift} +\findex{move\_to} +\findex{scale} +\findex{draw} +\begin{verbatim} + obj.shift(P arg); // translate by arg + obj.move_to(P arg); // move center to arg + obj.scale(double c); // scale about center by c + obj.draw(); +\end{verbatim} +A \code{Segment}'s ``center'' is its midpoint. A \code{Plane} has no +center; \code{move\_to} translates the \code{Plane} to pass through +\code{arg}, and \code{scale} has no effect. + +\index{Circle} +A \code{Circle} data structure consists of a center, radius, and a +perpendicular unit vector. Three constructors are provided: +\findex{Circle} +\begin{verbatim} + Circle(center=P(0,0,0), double rad=1, normal=E_3); + Circle(P center, P point); + Circle(P p1, P p2, P p3); +\end{verbatim} +The second constructor creates the \code{Circle} parallel to the +\teximath{(x_1,x_2)}~plane, with given center, and radius equal to the distance +between the arguments. (A warning is printed if the second argument +does not lie on the circle, namely, if the arguments do not lie in a +plane parallel to the \teximath{(x_1,x_2)}~plane.) The third returns the +\code{Circle} passing through the given points; the points must not be +collinear. + +The data defining a \code{Circle} are recovered with member functions +named \code{center()}, \code{radius()}, and \code{perp()}. + +\index{Plane} +\findex{Plane} +A \code{Plane} is specified by a point and normal vector, or by three +non-collinear points. The \code{draw()} function clips the plane and +draws the resulting polygon. Unless the clip box has been set +manually, the clipped polygon's vertices will have large coordinates. + +\index{Segment} +\findex{Segment} +A \code{Segment} is constructed from its endpoints. The member +function \code{midpoint()} returns the center. + +\index{Sphere} +\findex{Sphere} +A \code{Sphere} is specified by a point and a radius---by default the +origin and unity, or by the center and a point on the sphere. Member +functions \code{center()}~and \code{radius()} return the defining +data. Capabilities specific to geography and spherical geometry are +described below, pp.~\pageref{non-eucl}ff. + +The \code{draw()} function of a \code{Sphere} draws the horizon +visible from the current viewpoint. While this horizon is a circle in +object space, its image in the screen is generally an ellipse. +Antipodal points are not generally mapped to points symmetrically +placed with respect to the center of this ellipse. These effects are +most pronounced when the viewpoint is close to the \code{Sphere} and +the center is not close to the \code{target}. + + +\subsubsection*{Intersection} + +\index{Intersection} + +To facilitate geometric computation, \ePiX's \code{Circle}, +\code{Plane}, \code{Segment}, and \code{Sphere} classes can be +intersected with the \code{*}~operator. +\texicomment +Table~\ref{table:intersect} +lists the return types for each pair of arguments. Intersection is +commutative, so only the top half of the table is shown. For purposes +of intersection, a \code{Segment} is extended into a line. +The sample file \filename{pascal.xp} gives typical applications of +objects and intersection. +\findex{intersection} +\begin{table}[hbt] +\begin{center} + \begin{tabular}{c|cccc} + \code{*} & + \code{Segment} & \code{Circle} & \code{Plane} & \code{Sphere} \\ + \hline + \code{Segment} & \code{P} & \code{Segment} & \code{P} & \code{Segment} \\ + \code{Circle} & & \code{Segment} & \code{Segment} & \code{Segment} \\ + \code{Plane} & & & \code{Segment} & \code{Circle} \\ + \code{Sphere} & & & & \code{Circle} + \end{tabular} + \caption{Object intersection types.} + \label{table:intersect} +\end{center} +\end{table} +\texicommentend + +A \code{Circle} has a center, radius, and unit normal; a \code{Plane} +has a distinguished point and unit normal; a \code{Segment} has two +endpoints; a \code{Sphere} has a center and radius. An object is +\emph{malformed} if these conditions are not met. The constructors +return well-formed objects with two exceptions: \code{Circle} and +\code{Plane} create malformed objects if called with three collinear +points. The operator~\code{*} returns a malformed object if either +argument is malformed, or if the operands are disjoint, tangent, or +coincident. Malformedness is benign: Calling \code{draw()} on a +malformed object does nothing. + + +\subsubsection*{Orthonormal Frames} + +A \code{frame} comprises three mutually perpendicular unit +vectors. The constructor takes three vectors. The \code{frame}'s third +vector~\teximath{e_3} is positively proportional to~\code{v3}, the +second vector~\teximath{e_2} is positively proportional to +\code{v2\%v3}, and the first is the cross product, +\teximath{e_1=e_2\times e_3}. Thus, a \code{frame} is right-handed, +and does not depend on~\code{v1}. + +The elements of a \code{frame} are named \code{sea}, \code{sky}, and +\code{eye}, just as for the \code{camera}. A \code{frame} can be +rotated through an arbitrary angle about any of its elements. +\findex{frame} +\begin{verbatim} + frame(); // the standard basis {E_1, E_2, E_3} + frame fr(v1, v2, v3); // orthonormalize {v1, v2, v3} + fr.sea(); // the first element of fr, etc. + fr.rot1(theta); // rotate fr through theta about sea, etc. +\end{verbatim} + + +\subsection{Path-Like Elements} + +Basic path-like objects are drawn with named commands. Arguments of +polygon commands are endpoints/vertices. Except for \code{line}~and +\code{Line}, the following are subject to filling. +\findex{line} +\findex{Line} +\findex{triangle} +\findex{rect} +\findex{quad} +\findex{circle} +\begin{verbatim} + line(P p1, P p2, [double expand]); + Line(p1, p2); // draw line through p1, p2 (crop required) + triangle(P p1, P p2, P p3); + rect(P p1, P p2); + quad(P p1, P p2, P p3, P p4); // quadrilateral + circle(ctr=P(0,0,0), rad=1, normal=E_3); + circle(ctr, pt); + circle(pt1, pt2, pt3); +\end{verbatim} +The optional \code{line} argument is an expansion parameter: +\code{line(p1,p2,t);} draws a segment centered at the midpoint of +\code{p1}~and \code{p2}, with length scaled +by~\teximath{2^{t/100}}. (Setting \teximath{t=100} doubles the length, +while \teximath{t=-100} halves the length.) The arguments of +\code{rect()} must lie in a plane parallel to a coordinate plane. The +arguments to \code{circle} commands are the same as for \code{Circle} +constructors. + +Quadratic and cubic splines are described by their control points. A +list of~\code{P} is drawn as a ``natural'' spline (the \teximath{C^2} +piecewise cubic curve with vanishing second derivatives at the +endpoints); the number of points per cubic segment must be specified. +Circular and elliptical arcs are given by center, a basis, angular +range, and an optional number of intervals. +\findex{spline} +\findex{arc} +\findex{ellipse} +\begin{verbatim} + spline(P p1, P p2, P p3, [int n]); // quadratic + spline(P p1, P p2, P p3, P p4, [int n]); // cubic + spline(vector<P>, int n); // natural spline + + arc(P ctr, rad, t_min, t_max); // parallel to (x1,x2)-plane + ellipse(P ctr, P v1, P v2); // in plane spanned by v1, v2 + ellipse(P ctr, P v1, P v2, t_min, t_max, [int n]); +\end{verbatim} +\texicomment +Mathematically, these commands draw parametric paths +\begin{align*} + \text{Spline:}\quad&(1-t)^2 p_1 + 2(1-t)t p_2 + t^2 p_3, + && t\in[0,1] \\ + \text{Spline:}\quad&(1-t)^3 p_1 + 3(1-t)^2t p_2 + 3(1-t)t^2 p_3 + t^3p_4, + && t\in[0,1] \\ + \text{Arc:}\quad&\mathrm{ctr} + (\cos t)(\mathrm{rad},0,0) + + (\sin t)(0,\mathrm{rad},0), + && t\in[t_\mathrm{min}, t_\mathrm{max}] \\ + \text{Ellipse:}\quad&\mathrm{ctr} + (\cos t)v_1 + (\sin t)v_2, + && t\in[t_\mathrm{min}, t_\mathrm{max}]. +\end{align*} +\texicommentend +If parameter bounds are omitted in an \code{ellipse} command, the +entire ellipse is drawn. When the angular range subtends one or more +full turns in an \code{arc}~or \code{ellipse} the curve is subject to +filling. + +Commands for planar (half-)ellipses remain from \ePiX's early days: +\findex{ellipse} +\findex{ellipse\_left} +\findex{ellipse\_right} +\findex{ellipse\_top} +\findex{ellipse\_bottom} +\begin{verbatim} + ellipse(P ctr, P radius); + ellipse_left(P ctr, P radius); + ellipse_right(P ctr, P radius); + ellipse_top(P ctr, P radius); + ellipse_bottom(P ctr, P radius); +\end{verbatim} +If \code{radius} is \code{P(a,b)}, these commands draw all or half of +the ellipse with given center in the \teximath{(x_1,x_2)} plane, axes +parallel to the coordinate axes, and axis lengths \teximath{2a}~and +\teximath{2b}. + +Two commands are available to mark off right angles or a subtended +angle. Each accepts a spatial location and two non-zero directions, +and draws a scene element in the plane spanned by the vectors. +\findex{right\_angle} +\findex{arc\_measure} +\begin{verbatim} + right_angle(P loc, P v1, P v2, scale=8); + arc_measure(P loc, P v1, P v2, scale=8); + arc_measure(P loc, P v1, P v2, offset, text, align, scale=8); +\end{verbatim} +The \code{right\_angle} command does not check its arguments for +perpendicularity. The \code{arc\_measure} commands mark the +\emph{small} angle subtended by the directions; the label form places +a label at the midpoint of the arc. The (optional) \code{scale} +argument is the true size in~\code{pt} of the marker. + + +\subsubsection*{Recursive Fractal Curves} + +\index{Path!fractal} +Consider a path made up of equal-length segments that can point at any +angle of the form~\teximath{2\pi k/n} radians, for \teximath{0\leq +k<n}, like spokes on a wheel. A path is specified by a finite sequence +of integers, taken modulo~\teximath{n}. For example, if +\teximath{n=6}, then the sequence \teximath{0, 1, -1, 0} corresponds +to the ASCII path \verb+_/\_+. \ePiX's fractal approximation starts +with such a ``seed'' then recursively (up to a specified depth) +replaces each segment with a scaled and rotated copy of the seed, +Figure~\ref{fig:fractal}. The seed above generates the standard +von~Koch snowflake fractal. In code: +\findex{fractal} +\begin{verbatim} + const int seed[] = {6, 4, 0, 1, -1, 0}; + fractal(P(a,b), P(c,d), depth, seed); +\end{verbatim} +The first entry of \code{seed[]} (here~6) is the number of +``spokes''~\teximath{n}, the second~(4) is the number of terms in the +seed, and the remaining entries are the seed proper. The final path +joins \teximath{(a,b)}~to \teximath{(c,d)}. The number of segments in +the final path grows exponentially in the depth, so depths larger than +5~or 6 are likely to exceed the capabilities of \LaTeX\ and/or +PostScript. +\begin{figure}[hbt] + \begin{center} + \input{koch.eepic} + \end{center} + \caption{Successive iterations of \{\code{4,8,0,1,0,3,3,0,1,0}\}} + \label{fig:fractal} +\end{figure} + + +\subsubsection*{Arrows} + +\index{Arrow} +Line segments, splines, and arcs can be drawn with arrowheads at one +end. In profile, an arrowhead's width is \code{3pt}, and its height +is 5.5~times the width. The actual printed height depends on the +head's orientation with respect to the camera. By default, an +arrowhead is a filled triangle. The shape and size are adjusted with +declarations: +\findex{arrow\_width} +\findex{arrow\_ratio} +\findex{arrow\_inset} +\begin{verbatim} + arrow_width(w=3); // width in pt + arrow_ratio(r=5.5); // height-to-width + arrow_inset(c=0); // base indent as frac of ht +\end{verbatim} +\input{arrow.eepic} Inset\teximath{=0}\qquad +\input{arrow25.eepic} Inset\teximath{=0.25}\qquad +\input{arrow50.eepic} Inset\teximath{=0.5} \\ +The \code{inset} must be between \teximath{-1}~and \teximath{1}. Each +\code{arrow} command accepts an optional \code{scale} argument, which +scales the arrowhead. +\findex{arrow} +\begin{verbatim} + arrow(P tail, P tip, [scale]); + arrow(P p1, P p2, P p3, [scale]); // spline arrows + arrow(P p1, P p2, P p3, P p4, [scale]); + arrow(P ctr, P v1, P v2, t_min, t_max, [scale]); // ellipse +\end{verbatim} +A few ``special-purpose'' commands are supplied: +\findex{dart} +\findex{aarrow} +\findex{arc\_arrow} +\begin{verbatim} + dart (P p1, P p2); // same as arrow(p1, p2, 0.5); + aarrow(P p1, P p2); // double-headed arrow <---> + arc_arrow(ctr, rad, t_min, t_max, [scale]); +\end{verbatim} +If an \code{arc\_arrow} is too short, nothing is drawn. + + +\subsection{Coordinate Axes and Labels} + +\index{Labels!axis|(} +\index{Axes!labeling} +\index{Axes|(} +\ePiX\ provides an \code{axis} class for coordinate axes. Labels are +generated automatically in a variety of styles: decimal, scientific +notation, fraction, and trigonometric fraction. Logarithmic axes and +labels are available. Axis and labeling commands from Version~1.0 have +been retained. + + +\subsubsection*{The \code{axis} Class} + +An \code{axis} consists of a line segment divided into a specified +number of equal-length subintervals by ``major'' (long) tick marks. +Each subinterval may be divided further by ``minor'' (short) tick +marks. Minor ticks may be equally-spaced (``Cartesian'') or +logarithmically placed. Finally, a label is written at each major tick +mark with specified offset and alignment. Labels are generated +automatically from the endpoints, so the line should be parallel to a +coordinate axis. Label attributes (masking, borders, font size and +face, rotation angle) are determined by the current label style, not +by the \code{axis}. + +The command +\findex{axis} +\begin{verbatim} + axis(P tail, P head, int n, P offset=P(0,0), [align = none]); +\end{verbatim} +creates an axis joining \code{tail} to \code{head}, divided into +\code{n}~segments of equal length, with a major tick mark and label at +each division point and endpoint. The \code{offset} and \code{align} +arguments have the same meaning as for ordinary labels. + +The number and length of minor ticks, and the alignment of ticks, are +controlled with member functions: +\findex{axis.subdivide} +\findex{axis.tick\_ratio} +\findex{axis.align} +\begin{verbatim} + axis Ax(P(a,c), P(b,c), n); + Ax.subdivide(n); // put n-1 minor ticks in each axis segment + Ax.tick_ratio(r); // minor length = r*major length + Ax.align(AL=c); // align all ticks; AL = t, b, l, r, or c +\end{verbatim} +By default, major ticks are \code{6pt}~long and twice the length of +minor ticks. The global declaration \code{tick\_size(len)} sets the +major length, subject to ``reasonable stylistic limits''. For visual +consistency, tick lengths should not be changed casually. + +\index{Axes!labeling} +Labels on an \code{axis} may be drawn in several styles, selected with +member functions: +\findex{axis.dec} +\findex{axis.frac} +\findex{axis.trig} +\findex{axis.sci} +\findex{axis.unmark} +\findex{axis.precision} +\findex{axis.align\_labels} +\begin{verbatim} + Ax.dec(); // decimals (default) + Ax.frac(); // fractions, e.g. 0.5 -> \frac{1}{2} + Ax.trig(); // fractional multiples of \pi + Ax.sci(); // scientific notation, k\times base^N + + Ax.unmark(double); // remove label at selected location + Ax.precision(p); // set number of digits for decimal labels + Ax.align_labels(AL); // re-align labels +\end{verbatim} +Arbitrary textual labels depending on one coordinate are obtained by +writing a \code{string}-valued function of~\code{double} and +``registering'' it: +\findex{axis.label\_rep} +\begin{verbatim} + // f represents x as a string in given precision and base + std::string f(double x, unsigned int prec, unsigned int base); + Ax.label_rep(f); +\end{verbatim} +For example, textual tags can be printed instead of numeric labels. + +By default, an \code{axis} is Cartesian. The member function +\code{log(int b=10)} converts an \code{axis} to ``log mode'' with +specified base; this affects both tick marks and labeling. If \code{b} +is at least~3, minor tick marks appropriate for a logarithmic axis +base~\code{b} are drawn. Second, labels are written in decimal or +scientific notation appropriately for a logarithmic axis; that is, +``\teximath{k\times b^N}'' (or its decimal value) is written at +location \teximath{N+\log_b k}. + +Minor ticks of a log \code{axis} may be labeled individually; again, +this is controlled with member functions: +\findex{axis.tag} +\findex{axis.tag235} +\findex{axis.tags} +\findex{axis.untag} +\begin{verbatim} + Ax.tag(d); // labels at N+log_b(d) + Ax.tag235(); // tag 2, 3, and 5 if b=10 + Ax.tags(); // tag 1, ..., b-1 + Ax.untag(); // remove all tags, including 1 + Ax.untag(double); // remove one tag, e.g. Ax.untag(9); +\end{verbatim} + +For convenience, an \code{axis} object along an edge of the active +\code{screen} can be created with a named command: +\findex{top\_axis} +\findex{bottom\_axis} +\findex{left\_axis} +\findex{right\_axis} +\begin{verbatim} + top_axis(n, offset, align); + bottom_axis(n, offset, align); + left_axis(n, offset, align); + right_axis(n, offset, align); +\end{verbatim} +The ticks automatically point into the bounding box. + +The functions above create objects or set \code{axis} attributes, but +write no output. Tick marks and labels can be printed separately, or +at once: +\findex{axis.draw} +\findex{axis.draw\_ticks} +\findex{axis.draw\_labels} +\begin{verbatim} + Ax.draw(); // axis, tick marks, and labels + Ax.draw_ticks(); // axis and ticks only + Ax.draw_labels(); +\end{verbatim} + + +\subsubsection*{Other Axis-Drawing Commands} + +\index{Axes!logarithmic} +\ePiX\ formerly supplied commands for drawing simple axes and their +labels. These commands have been kept for compatibility. Horizontal +axes are generated with +\findex{h\_axis} +\findex{h\_log\_axis} +\findex{v\_axis} +\findex{v\_log\_axis} +\begin{verbatim} + h_axis(p1, p2, n, align=c); // n subintervals (n+1 ticks) + h_log_axis(p1, p2, n, align=c, base=10); +\end{verbatim} +For vertical axes, use \code{v\_axis}. The style of tick mark is +appropriate for an axis of the given type. Horizontal axis tick marks +may be aligned \code{t}~(above the axis) or~\code{b} +(below). Similarly, vertical axis ticks may be aligned \code{r}~or +\code{l}. + +The endpoint arguments of a coordinate axis may be omitted, in which +case they default to \teximath{p_1=(x_\mathrm{min},0)} and +\teximath{p_2=(x_\mathrm{max},0)} for a horizontal axis, or to +\teximath{p_1=(0,y_\mathrm{min})} and +\teximath{p_2=(0,y_\mathrm{max})} for a vertical axis. If the bounding +box has integer width and/or height, omitting the number of points +draws tick marks one unit apart. + +Labels for a horizontal Cartesian or logarithmic axis are generated +with the commands +\findex{h\_axis\_labels} +\findex{h\_axis\_masklabels} +\findex{h\_axis\_log\_labels} +\findex{h\_axis\_log\_masklabels} +\findex{v\_axis\_labels} +\findex{v\_axis\_masklabels} +\findex{v\_axis\_log\_labels} +\findex{v\_axis\_log\_masklabels} +\begin{verbatim} + h_axis_labels(P p1, P p2, int n, P offset, [align]); + h_axis_masklabels(p1, p2, n, offset, [align]); + h_axis_log_labels(p1, p2, [n], offset, [align], base=10); + h_axis_log_masklabels(p1, p2, [n], offset, [align], base=10); +\end{verbatim} +Labels for a vertical axis are generated with \code{v\_axis\_labels}, +etc. The labels are automatically generated to match their horizontal +location. The first puts \teximath{(n+1)}~evenly-spaced labels on the segment +joining \code{p1}~and \code{p2}. As with ordinary labels, the +\code{offset} is in~\code{pt}, and the optional \LaTeX-style alignment +option positions the labels using their corners. The second command +draws masked labels according to the current label masking +attributes. The third writes labels in exponential notation, using the +Cartesian coordinate as exponent. + +As for coordinate axes, the initial and final points may be omitted in +an \code{axis\_[mask]labels} command, with the same defaults. The +\code{offset} and number of labels must always be specified. + + +\subsubsection*{Broken Axes} +\index{Axes!broken} + +Broken axes are best drawn using page layout, especially if axis +labels are to be drawn. To accomplish the task, create a screen for +each piece of axis, using appropriate Cartesian coordinates for the +corners, then \code{inset} the screens so the axis pieces are nearly +end to end. A zig-zag glyph signifies the break: +\findex{axis\_break} +\begin{verbatim} + axis_break(P, P, scale=12); +\end{verbatim} +The \code{P} arguments are the screen coordinates of the ends to be +joined; the optional third argument is the true height and width +in~\code{pt} of the glyph. The sample file \filename{coord\_tricks.xp} +uses layout and axis breaks. + + +\subsubsection*{Coordinate Grids} + +Cartesian grids fill a coordinate rectangle, and have a specified +number of lines in each direction. A polar grid has specified radius, +and numbers of rings and sectors. +\findex{grid} +\findex{polar\_grid} +\begin{verbatim} + grid(n1, n2); // fills the bounding box + grid(p1, p2, n1, n2); // fills the box with corners p1, p2 + polar_grid(r, n1, n2); +\end{verbatim} + +Log and semi-log grids are drawn with analogous syntax: +\findex{log\_grid} +\findex{log1\_grid} +\findex{log2\_grid} +\begin{verbatim} + log_grid (p1, p2, n1, n2, [base1], [base2]); // log-log + log1_grid(p1, p2, n1, n2, [base]); // log-lin + log2_grid(p1, p2, n1, n2, [base]); // lin-log +\end{verbatim} +The~\teximath{n_i} arguments dictate the number of squares, namely the number +of orders of magnitude spanned in the logarithmic direction(s). The +(optional) base arguments default to~10, and control the number of +lines drawn per order of magnitude. As with Cartesian grids, the +corners are optional; if omitted, the grid fills the bounding box. + +\index{Graph paper} +Graph paper may be created by superimposing grids: +\texicomment +\begin{center} + \begin{minipage}[b]{2.5in} + \begin{footnotesize} +\texicommentend +\findex{pen} +\findex{grid} +\begin{verbatim} + pen(0.25); + grid(10*xsize(), 10*ysize()); + pen(0.5); + grid(2*xsize(), 2*ysize()); + pen(1); + grid(xsize(), ysize()); +\end{verbatim} +\texicomment + \end{footnotesize} + \end{minipage} + \qquad + \input{graphpaper.eepic} +\end{center} +\index{Axes|)} +\texicommentend + +\subsection{The Path Class} + +\index{Path!class} +A \code{path} data structure is an ordered list of points that can be +cropped, clipped, mapped, concatenated, and drawn. The first four +constructors mirror polygon-drawing commands above. Function graphs +and parametric paths are built from a real- or \code{P}-valued +function~\code{f} of one variable. +\findex{path} +\begin{verbatim} + path(p1, p2, expand=0); // line (endpoints) + path(p1, p2, p3, [n]); // quadratic spline + path(p1, p2, p3, p4, [n]); // cubic spline + path(p1, v1, v2, t_min, t_max, [n]); // ellipse + path(f, t_min, t_max, [n]); +\end{verbatim} + +The member function \code{pt()} accepts a~\code{P} or three (or two) +doubles and appends the specified point to a \code{path}. This +snippet creates a regular \teximath{n}-gon: +\begin{verbatim} + path ngon; // declare new path + for (int i=0; i<=n; ++i) + ngon.pt(cis(i*full_turn()/n)); // works in all angle modes +\end{verbatim} +Compound paths may be built by concatenation. If \code{path1}~and +\code{path2} share an endpoint, the commands +\begin{verbatim} + path1 += path2; + path1 -= path2; +\end{verbatim} +replace \code{path1} with the result of traversing \code{path1} +``forward'', then following \code{path2} in the forward or reverse +direction (respectively). For expected results, the first +(or last) point on~\code{path2} should be the last point +of~\code{path1}. The notation suggests 1-dimensional homology +chains. The sample file \filename{contour.xp} illustrates path +creation and manipulation. + +A \code{path} is a data structure, and must be drawn explicitly to +create visible output. By default a \code{path} is not a closed loop +(even if the first and last points are the same), and is not filled +when drawn. Member functions perform these tasks. Continuing the +\teximath{n}-gon snippet above, +\findex{path.close} +\findex{path.fill} +\findex{path.draw} +\begin{verbatim} + ngon.close(); // mark path as closed + ngon.fill(); // draw filled region if filling is active + ngon.draw(); // print to the screen +\end{verbatim} +\code{path::close()} adds a closing edge if necessary. Once a +\code{path} is closed, no more points can be added. A closed path +clips and crops differently than an open \code{path} with the same +data. \code{path::fill()} has no effect on an unclosed \code{path}. + + +\subsection{Function Plotting} + +\index{Plotting|(} +The noun ``map'' refers to a \CXX\ function that accepts one or +more \code{double} arguments and returns a \code{double}~or +a~\code{P}. Mathematically, a map can be depicted in two ways: as a +graph (which retains information about the domain), or as a +parametrized curve or surface (which discards domain +information). \ePiX\ assumes that \code{double}-valued maps are +graphed and \code{P}-valued maps are drawn parametrically. Either sort +of depiction is called a ``plot''. \ePiX\ plots are either ``wire +mesh'', produced by a \code{plot} command, or ``shaded'', produced by +a \code{surface} command. + + +\subsubsection*{Basic Plotting} + +For the moment, ``function'' means ``function of one variable'' +(precisely, a \code{double}-valued function of a \code{double} +variable). A function graph depends on the domain and the number of +points to use. Each of the commands +\findex{plot} +\findex{polarplot} +\findex{shadeplot} +\begin{verbatim} + plot(f, t_min, t_max, n); + polarplot(f, t_min, t_max, n); + shadeplot(f, t_min, t_max, n); +\end{verbatim} +graphs the function~\code{f} on the interval \code{[t\_min, t\_max]} +by dividing the interval into \code{n}~subintervals of equal length. +The first gives a Cartesian plot, the second a polar plot with bounds +in current angular units, the third shades the region between the +graph and the horizontal axis. If two functions are given to +\code{shadeplot}, the region between their graphs is shaded. + + +\subsubsection*{Domains and Wiremesh Plots} + +\index{Domain|(} +An \ePiX\ \code{domain} is a coordinate box of dimension one, two, or +three, specified by a pair of opposite corners and two \emph{meshes} +(``coarse'' and ``fine'', respectively) which specify the amount of +data to be plotted. Plotting is explained in detail below. +\findex{domain} +\begin{verbatim} + // [a1,a2] x [b1,b2]: n1 x n2 rectangles, m1 x m2 intervals + domain R2(P(a1,b1), P(a2,b2), mesh(n1,n2), [mesh(m1,m2)]); + + // [a1,a2] x [b1,b2] x [c1,c2] divided analogously + domain R3(P(a1,b1,c1), P(a2,b2,c2), + mesh(n1,n2,n3), [mesh(m1,m2,m3)]); +\end{verbatim} +If unspecified, the fine mesh is the same as the coarse mesh. For +expected behavior, the coarse mesh should ``divide'' the fine mesh, in +that \teximath{m_i}~should be a (usually small) integer multiple +of~\teximath{n_i} for each~\teximath{i}. + +A \code{domain} may be \emph{resized} in any coordinate for which the +thickness is positive, and can be \emph{sliced} by setting one +variable to a constant. The result of slicing is a \code{domain} whose +dimension is one smaller than the original. Finally, +``\code{slices}'' operators return the list of \code{domain}s obtained +by setting one variable to evenly-spaced constants. By default, the +number of slices is specified by the coarse mesh. An optional argument +specifies the number of slices. This argument need not be related to +the coarse mesh. +\findex{domain.resize} +\findex{domain.slice} +\findex{domain.slices} +\begin{verbatim} + R2.resize2(a,b); // [a1,b1] x [a,b] + R2.slice1(t); // set x1 = t + R3.slices3([n]); // (n+1) domains with x3 = const +\end{verbatim} +\begin{center} + \input{slices.eepic} +\end{center} +\smallskip +When possible, resizing preserves grid square sizes. Generally, +though, integer truncation occurs: If \code{R=domain(P(0,0), P(1,1), +mesh(10,6))}, then \code{R.resize1(0,0.25)} is the rectangle +\teximath{[0,0.25]\times[0,1]} subdivided into \teximath{2\times6} +subrectangles, since \teximath{10\div4=2} in integer arithmetic. For +expected behavior, choose mesh sizes to avoid integer truncation. + + +The arguments of a \code{plot} command are a map, followed by either a +domain or its logical equivalent. +\findex{plot} +\begin{verbatim} + double f(double t) { return t*t; } + P F(double u, double v) { return P(u, v, exp(u)*Sin(v)); } + P G(double u, double v, double w) { return P(v*w, u*w, u*v); } + + plot(f, a, b, n); // f:[a,b] -> R, using n intervals + plot(F, R2); // graph of exp(u)*Sin(v) + plot(G, R3.slice2(0.5); // G: R^3 -> R^3 restricted to y=0.5 +\end{verbatim} +By (compiler-enforced) convention, \code{plot} commands involving a +\code{P}-valued map accept a \code{domain} argument, as in the second +and third commands above. To plot a \code{double}-valued function, by +contrast, supply the logical equivalent of a \code{domain}, usually +the endpoints and the number of intervals, as in the first \code{plot} +command above. + +Resizing and slicing allow a map~\code{F} to be plotted selectively +over parts of its domain. This can be used to emphasize parts of the +image, layer scene elements, patch surfaces together, and so forth. +Resize and slice(s) commands may be used directly in a \code{plot} +command: +\findex{plot} +\begin{verbatim} + plot(F, R2.resize1(0,0.5)); + plot(F, R2.slices1()); +\end{verbatim} + + +\subsubsection*{Meshes and Plotting} + +The \code{P}~arguments of a \code{domain} are a pair of opposite +corners. The first \code{mesh} argument, the \emph{coarse} mesh, +specifies the number of subdivisions in each coordinate direction. +The second \code{mesh}, the \emph{fine} mesh, determines the number of +points used in each direction when plotting. + +\begin{comment} +Suppose the \code{domain}~\code{R2} is, as above, the rectangle +\teximath{[0,3]\times[-1,2]}. The argument \code{mesh(12,6)} divides the +rectangle a \teximath{12\times6}~array of subrectangles known as the +\emph{coarse mesh}. A \code{P}-valued map~\code{F} of two variables is +plotted over the edges of the coarse mesh. Rather than drawing +quadrilaterals, however, \ePiX\ draws the image curves at the +resolution specified by the argument \code{mesh(60,60)}, the +\emph{fine mesh}. In this example, the curves in each direction are +drawn using 60~line segments. +\end{comment} + +Separating the roles of coarse and fine meshes allows a plot to +conform closely to a surface without using a fine grid of curves. +Both parts of Figure~\ref{fig:plot} are drawn with a +\teximath{6\times20} coarse mesh. In the first picture, the fine mesh +is also \teximath{6\times20}, while in the second, the fine mesh is +\teximath{12\times60}. + +\begin{figure}[hbt] + \begin{center} + \input{plot_a.eepic}\hspace*{0.5in} + \input{plot_b.eepic} + \caption{Coarse and fine meshes.} + \label{fig:plot} + \end{center} +\end{figure} + +The coarse mesh is significant only for domains of dimension at +least~2. The coarse mesh's size determines the number of curves or +surfaces plotted \emph{perpendicularly} to a coordinate direction, +while the fine mesh's size determines the number of segments used +\emph{along} that direction. For predictable results, the fine mesh +should be a small multiple of the coarse mesh. + +Plotting works analogously for 3-dimensional \code{domain}s and maps +depending on three variables: The ``one-dimensional skeleton'' of the +\code{domain}'s image is drawn. A \code{P}-valued map of +three variables can be plotted over a 1-~or 2-dimensional +\code{domain}. (The effect may be unexpected unless the domain arises +by slicing, however.) A map depending on one or two variables cannot +be plotted over a 3-dimensional \code{domain}. +\index{Domain|)} + + +\subsubsection*{Shaded Surfaces} + +\index{Plotting!surface|(} + +\ePiX's shaded surface plotting implements a degree of hidden surface +removal. The algorithm breaks a surface into mesh fragments, sorts +them in decreasing (approximate) distance to the camera, and prints +them. If filling is active, a mesh fragment is shaded according to +the angle between the normal vector and the direction to the camera, +simulating constant ambient lighting; otherwise, the current fill +color is used. This technique works fairly well for surfaces without +intersection, and even acceptably handles intersecting surfaces for +which mesh elements intersect only along boundaries. + +The syntax of a \code{surface} command is identical to a \code{plot} +command when only a single surface is drawn. For example, +\findex{surface} +\begin{verbatim} + surface(F, R, cull=0); +\end{verbatim} +plots the \code{P}-valued function~\code{F} over the domain~\code{R}, +the shaded equivalent of the corresponding \code{plot} command. The +optional \code{cull} argument removes elements that point toward +(\code{cull=-1}) or away from (\code{cull=1}) the camera. Naturally, +orientation of mesh elements depends on the parametrization~\code{F}, +not merely on the surface. Culling reduces the output file size, but +is useful mostly for closed, convex surfaces. + +There are special commands for surfaces of rotation; each accepts a +final \code{cull} argument. +\findex{surface\_rev} +\begin{verbatim} + surface_rev(f, t_min, t_max, n_lats, n_longs); + surface_rev(f, g, t_min, t_max, n_lats, n_longs=24); + surface_rev(f, g, R, frame coords); +\end{verbatim} +The first revolves the graph of~\teximath{f} about the +\teximath{x}-axis, the second uses the parametric curve +\teximath{t\mapsto\bigl(f(t),g(t)\bigr)} as profile. In each case, the +parameter interval \verb+[t_min,t_max]+ is divided into \verb+n_lats+ +equal-length subintervals, \verb+n_longs+ copies of the profile curve +are drawn, and the complete surface (one full turn) is drawn. + +The third form uses a \code{domain} to control the range of +longitudes, and draws a surface of rotation in the Cartesian +coordinate system defined by the orthonormal basis \code{coords}, by +default the standard basis. The arguments \code{f}~and \code{g} define +a parametric curve in the plane spanned by the first two elements +of~\code{coords}, and the first element is the axis of rotation. + +As in wire mesh plotting, the fine mesh is used to draw the boundaries +of surface patches; this tends to make surfaces look smoother for +modest-sized coarse meshes. If the coarse mesh is too coarse, however, +two visually undesirable effects can occur. First, adjacent regions of +the surface may be shaded very differently, since shading is constant +over patches defined by the coarse mesh. Second, a patch nearly +tangent to a line of sight may be drawn badly if the patch bends back +on itself, since the boundary of the \emph{patch} is drawn, not the +visible edge of the mathematical surface. See +\filename{samples/artifacts.xp}. + + +\subsubsection*{Multiple Domains and/or Maps} + +A scene containing two or more shaded surfaces cannot generally be +built up one surface at a time. Instead, multiple surfaces must be +assembled into a single data structure before they can be drawn. +Multiple surfaces are built from one or more maps and one or more +2-dimensional \code{domain}s. In the code snippets below, \code{F}~and +\code{G} are \code{P}-valued functions of 3~variables, and~\code{R} is +a 3-dimensional \code{domain}. + +To plot the images of several \code{domain}s under a \emph{single +map}, assemble the \code{domain}s into a list if necessary, then issue +a \code{surface} command: +\findex{surface} +\findex{domain\_list} +\findex{domain\_list.add} +\begin{verbatim} + surface(F, R.slices3(), cull=0); + + domain_list DL(R.slice1(0)); // build domain list + DL.add(R.slice2(0.5)); // add a domain, etc. + surface(G, DL, cull=0); // draw +\end{verbatim} +For multiple maps, \ePiX\ provides the \code{scenery} +class. Conceptually, \code{scenery} is an agglomeration of shaded +surfaces, built one surface at a time from maps and 2-dimensional +\code{domain}s. The \code{add} function accepts two arguments---a map, +and either a \code{domain} or a list of \code{domain}s---and +contributes its data to the \code{scenery} rather than plotting +immediately. Completed \code{scenery} is drawn manually. +\findex{scenery} +\findex{scenery.add} +\findex{scenery.draw} +\begin{verbatim} + scenery S(F, R.slice3(0.25)); // S contains one surface + S.add(F, R.slice2(0)); // S contains two surfaces + S.add(G, R.slices1(3)); // S contains six surfaces + S.draw(cull=0); +\end{verbatim} +Complete examples are included in the \filename{samples} directory: +\filename{spherical.xp}~and \filename{minkowski.xp}. + +In principle, a scene may contain arbitrarily many surfaces. However, +figures that contain many objects tend to tax \LaTeX's internal +stacks. Frequent color changes exacerbate the problem. Even if you +use \filename{hugelatex} (or increase \LaTeX's memory), a figure +containing more than a few thousand mesh elements is unlikely to +compile. At moderate resolution, a surface can easily contain +1000~patches. Each shell script has a command-line option to invoke +\filename{hugelatex}; your mileage may vary. + + +\subsubsection*{User-Specified Color Shading} + +\index{Color!surface plotting} +By default, a \code{surface} or \code{scenery} is colored according to +the current fill color. For finer control, each \code{surface}, +\code{surface\_rev}, and \code{scenery} command accepts an optional +position-dependent \code{color} specification. +\findex{surface} +\findex{surface\_rev} +\findex{scenery} +\findex{scenery.add} +\begin{verbatim} + surface(F, R, color, cull=0); + surface_rev(f, [g], t_min, t_max, n_lats, n_longs, color); + surface_rev(f, g, R, color, [coords]); + + scenery S(F, R, color); + S.add(F, R, color); +\end{verbatim} +The \code{color} argument is a \code{P}-valued function of two or +three \code{double}s whose output is interpreted as a set of +\code{RGB}~densities. If \code{color} takes two arguments, they are +\code{domain} coordinates, and the surface is colored according to +parameter values. If \code{color} takes three arguments, they are +Cartesian coordinates, and the surface is colored according to spatial +location. Please see the sample files +\filename{surface\_shade.xp}~and \filename{S2\_harmonics.xp}. +\index{Plotting!surface|)} + + +\subsection{Calculus Plotting} +\index{Plotting!calculus|(} + +\ePiX\ provides high-level commands for plotting derivatives and +definite integrals, Riemann sums, tangent lines, slope- and vector +fields, and solutions of planar and spatial systems of differential +equations. + +In this section, \code{f}~and \code{g} are \code{double}-valued +functions of one variable. + +\subsubsection*{Utility Functions} + +\findex{sup} +\findex{inf} +\findex{newton} +\begin{verbatim} + sup(f, a, b); // max/min of f on [a,b] + inf(f, a, b); + newton(f, g, x0); // find approximate crossing point +\end{verbatim} +Newton's method returns the crossing point of the given functions, +starting from the specified seed, which should be reasonably close to +the expected solution. If a critical point is hit or 5~iterations +pass, a warning is issued and the current result (probably incorrect) +is returned. The second function~\teximath{g} defaults to the zero function if +omitted. + +\subsubsection*{Derivatives and Integrals} + +The classes \code{Deriv}~and \code{Integral} are used to calculate +values of derivatives and integrals, and to plot these functions. +\findex{Deriv} +\findex{Deriv.eval} +\findex{Deriv.left} +\findex{Deriv.right} +\findex{Integral} +\findex{Integral.eval} +\begin{verbatim} + Deriv df(f); // function object: df(x) = f'(x) + df.eval(t); // return f'(t) + df.left(t); // deriv from left at t: (f(t)-f(t-dt))/dt + df.right(t); // deriv from right at t: (f(t+dt)-f(t))/dt + + Integral prim(f,a); // function object: prim(x) = int_a^x f + prim.eval(b); // numerical integral of f over [a,b] + double val(Integral(f).eval(1)); // val = \int_0^1 f +\end{verbatim} +The lower limit on an integral is~0 by default. \code{Deriv}s and +\code{Integral}s can be used directly in a \code{plot} command: +\findex{plot} +\findex{riemann\_sum} +\begin{verbatim} + plot(Deriv(f), a, b, n); // plot f' over [a,b] + plot(Integral(f, x0), a, b, n); + riemann_sum(f, a, b, n, TYPE); +\end{verbatim} +The second graphs the definite integral \teximath{x\mapsto\int_{x_0}^x +f(t)\,dt} over~\teximath{[a,b]}. As above, \teximath{x_0}~defaults +to~0. The third draws rectangles or trapezoids whose area approximates +the definite integral of~\teximath{f} over~\teximath{[a,b]}. The +\code{TYPE} may be \code{UPPER}, \code{LOWER}, \code{LEFT}, +\code{RIGHT}, \code{MIDPT}, or~\code{TRAP}. + +Tangent lines and envelopes (families of tangent lines) are drawn with +\findex{tan\_line} +\findex{envelope} +\findex{tan\_field} +\begin{verbatim} + tan_line(f, t); // f real- or vector-valued + envelope(f, t_min, t_max, n); // family of tangent lines + tan_field(f, g, t_min, t_max, n); // field of tangents +\end{verbatim} +The sample files \filename{conic.xp}~and \filename{lissajous.xp} +illustrate these features. + + +\subsubsection*{Systems of Differential Equations} + +Let \code{F}~be a \code{P}-valued function of two or three variables. +\findex{ode\_plot} +\findex{flow} +\begin{verbatim} + ode_plot(F, p_0, t_min, t_max, n); + flow(F, p_0, t_max, n); +\end{verbatim} +The first plots the solution curve of the initial-value problem +\teximath{\dot{x}=F(x)}, \teximath{x(0)=p_0}, over the specified time +interval. If \teximath{t_\mathrm{min}} is omitted, its value is~0, so +the curve starts at~\teximath{p_0}. With manual calculation to rotate +a planar field a quarter turn, \code{ode\_plot} can be used to draw +level curves (isobars) of a function of two variables; see the sample +file \filename{dipole.xp}. The \code{flow} function returns the +result of starting at~\teximath{p_0} and flowing by~\teximath{F} for +time~\teximath{t_\mathrm{max}}, using Euler's method with~\teximath{n} +time steps. This is useful for placing markers or arrowheads precisely +along a flow line. + +A planar or spatial vector field itself may be plotted over a +domain~\code{R} in three styles: +\findex{vector\_field} +\findex{dart\_field} +\findex{slope\_field} +\begin{verbatim} + vector_field(F, R, [scale]); // true length + dart_field (F, R, [scale]); // const length + slope_field (F, R, [scale]); // const length +\end{verbatim} +The field is sampled at the grid points of the coarse mesh. If the +domain is 2-dimensional, the plot is a planar slice of the field, even +if the field depends on three variables. If the domain is +3-dimensional, the field is drawn in successive slices +\teximath{x_3=\mathrm{const}}, starting at the height of the first +corner of~\code{R} and ending at the height of the second corner. + +The optional final argument, which defaults to~\teximath{1}, scales the +arrowheads in a vector field, and scales the (constant) length of +field elements for slope and dart fields. The sample files +\filename{layout2.xp}, \filename{lorenz.xp}, \filename{slopefield.xp}, +and \filename{vfield.xp} illustrate usage. + +In each field-plotting command, the domain argument may be replaced by +two points, representing corners of a coordinate rectangle, and two +integers, the number of grid intervals in the selected coordinate +directions. Only planar slices of a vector field can be plotted using +the alternative syntax. +\index{Plotting|)} + + +\subsection{Non-Euclidean Geometry} +\label{non-eucl} + +\ePiX\ provides limited features for spherical and hyperbolic +geometry: the ability to draw lines in the half-plane and Poincar\'e +disk models of the hyperbolic plane, and to draw latitudes, +longitudes, great circle arcs, spherical triangles, regular polyhedra, +and parametrized curves on a sphere. + +Hyperbolic line segments are specified by their endpoints in the upper +half space or ball (Poincar\'e) models. In each case there is no +output if either endpoint lies outside the model. +\findex{hyperbolic\_line} +\findex{disk\_line} +\begin{verbatim} + hyperbolic_line(p, q); + disk_line(p, q); +\end{verbatim} +For compatibility with 2-dimensional hyperbolic space, the half-space +model is the set \teximath{\{(x_1,x_2,x_3)\mid x_2>0\}}. + +\index{Plotting!spherical|(} +A \code{frame} determines geographical coordinates on a \code{Sphere}: +the first element points toward longitude~0 on the equator, the third +element points to the north pole. A latitude line depends on a +\code{Sphere}, a \code{frame}, the numerical latitude, and a range of +longitudes. A longitude line is described similarly. +\findex{latitude} +\findex{longitude} +\findex{back\_latitude} +\findex{back\_longitude} +\begin{verbatim} + latitude(lat, long_min, long_max, Sphere S, frame coords); + longitude(lngtd, lat_min, lat_max, Sphere S, frame coords); +\end{verbatim} +By default, \code{coords} is the standard \code{frame} and \code{S} is +the unit sphere. These commands draw only the portion of the curve +that is visible from the current viewpoint. The function +\code{back\_latitude} draws the invisible portion of a latitude line. + +Spherical arcs and triangles are described by their endpoints. Only +the direction vector from the center of the sphere to an endpoint is +significant; if a sphere is scaled or moved, the same function call +will draw the corresponding object on the new sphere. + +The following draw the visible (front) portions of great circle arcs: +\findex{front\_arc} +\findex{front\_arc2} +\findex{front\_line} +\findex{back\_arc} +\findex{back\_arc2} +\findex{back\_line} +\begin{verbatim} + front_arc(p1, p2, S); // short arc on S from p1 to p2 + front_arc2(p1, p2, S); // arc from p1 to -p1 through p2 + front_line(p1, p2, S); // great circle through p1 and p2 +\end{verbatim} +Triangles and regular (Platonic) polyhedra are provided. The sample +file \filename{sample/polyhedra.xp} illustrates usage. +\findex{front\_triangle} +\findex{front\_tetra} +\findex{front\_cube} +\findex{front\_octa} +\findex{front\_dodeca} +\findex{front\_icosa} +\findex{back\_triangle} +\findex{back\_tetra} +\findex{back\_cube} +\findex{back\_octa} +\findex{back\_dodeca} +\findex{back\_icosa} +\begin{verbatim} + front_triangle(p1, p2, p3, S); // spherical triangle + front_tetra(S, coords); // regular tetrahedron + front_cube(S, coords); // hexahedron + front_octa(S, coords); // octahedron + front_dodeca(S, coords); // dodecahedron + front_icosa(S, coords); // icosahedron +\end{verbatim} +Each function has a \code{back} version, which draws the hidden +portion. The tetrahedron, cube, and octahedron are (up to scale) +inscribed in the cube of side length~\teximath{2} centered at the origin whose +sides are parallel to~\code{frame}. The point \teximath{(1,1,1)} is a vertex of +the tetrahedron. + +Up to scale, the icosahedron's vertices lie on the golden rectangle +with vertices \teximath{(\pm\gamma,0,\pm1)} and its images under cyclic +permutation of coordinates. The dodecahedron is dual to the +icosahedron. + +\subsubsection*{Spherical Plotting} + +Parametrized paths on a \code{Sphere~S} (by default the unit sphere) +can be specified either by radial projection of a \code{P}-valued +curve, or by stereographic projection of a plane curve given as a pair +of \code{double}-valued functions: +\findex{frontplot\_R} +\findex{frontplot\_N} +\findex{frontplot\_S} +\findex{backplot\_R} +\findex{backplot\_N} +\findex{backplot\_S} +\begin{verbatim} + frontplot_R(phi, t_min, t_max, n, [S]); // radial + frontplot_N(f1, f2, t_min, t_max, n, [S]); // from north pole + frontplot_S(f1, f2, t_min, t_max, n, [S]); // from south pole +\end{verbatim} +Attempts to perform radial projection on a path through the origin +will generate division-by-zero errors. Stereographic projection maps +the equatorial plane \teximath{\{x_3=0\}} to the unit sphere by +projection from the corresponding pole: \teximath{N=(0,0,1)}, +\teximath{S=(0,0,-1)}. + +Each spherical plot command has a \code{back} version that prints only +the portion of the path invisible from the current viewpoint. +Because of the way \ePiX\ layers output, it is generally best to put +hidden portions of the input before visible portions, with line width +and/or style that suggests hidden lines. + + +\subsection{Data Plotting} +\index{Plotting!data|(} +\index{Data plotting|(} + +Files of numerical data can be created, manipulated, analyzed, +plotted (paths, scatter plots, and histograms), read, and written. +The format for a data file is one or more floating-point +numbers per line, with the same number of entries per line. Anything +that appears on a line after the \LaTeX\ comment character~\code{\%} +is a comment. + +\ePiX\ provides two \code{plot} commands for file data. The first +facilitates plotting selected columns; the second simplifies plotting +the first two columns with one or both scales logarithmic. Either form +can be used to plot selected columns logarithmically. + +The general commands read numbers from two or three columns of a +specified file, pass them as arguments to a \code{P}-valued +function~\code{F}, and plot the resulting points: +\findex{plot} +\begin{verbatim} + plot("filename", STYLE, [i_1], [i_2], [i_3], [F]); + plot("filename", STYLE, F, [i_1], [i_2], [i_3]); +\end{verbatim} +The first argument is the name of the data file. The \code{STYLE} may +be \code{PATH}, which joins the points in the order they appear, or +any of the marker types in Table~\ref{table:marker}. The +integers~\teximath{i_k} specify columns from which to extract data; these +default, respectively, to the first column, second column, and null (a +column of zeroes). If the ``coordinate system''~\code{F} is omitted in +the first command, it defaults to the Cartesian point constructor. The +function~\code{F} is mandatory in the second form; useful choices +include \code{log\_log}, \code{log\_lin}, and~\code{lin\_log}, which +plot the corresponding coordinate logarithmically. + + +\subsubsection*{Data Files} + +For more elaborate analysis, the \code{data\_file} class presents an +interface to a file as an ordered list of columns. There are two +general ways to create a \code{data\_file}: read in an external file, +or generate data (up to three columns) using specified +\code{double}-valued functions. In the constructors below, each +function~\code{fi} is a \code{double}-valued function of one variable. +\findex{data\_file} +\findex{data\_file.read} +\begin{verbatim} + data_file DF("my_data"); // read data from disk file + data_file DF(f1, t_min, t_max, num_pts); // values of f1 + data_file DF(f1, f2, t_min, t_max, num_pts); + data_file DF(f1, f2, f3, t_min, t_max, num_pts); + data_file DF(3); // create empty data_file with 3 columns + DF.read("file1"); // read a disk file +\end{verbatim} + +Columns of a \code{data\_file} can be transformed by a user-specified +function, averaged, correlated, extracted (for use by other code), +scatter plotted, and written to a disk file at specified +precision. Below, the function~\code{f} is a \code{double}-valued +function of one variable and~\code{F} is a \code{P}-valued function of +two or three variables, whose components are written back to the +selected columns. +\findex{data\_file.transform} +\begin{verbatim} + DF.transform(f, i); // apply f to selected column(s) + DF.transform(F, i=1, j=2); + DF.transform(F, i, j, k); +\end{verbatim} +Basic statistical operations on columns are provided. +\findex{data\_file.dot} +\findex{data\_file.avg} +\findex{data\_file.var} +\findex{data\_file.covar} +\findex{data\_file.regression} +\begin{verbatim} + DF.dot(i,j); // dot product of columns i, j + DF.avg(i); // mean of column i + DF.var(i); // population variance + DF.covar(i,j); // covariance + DF.regression(i,j); // plot regression line +\end{verbatim} +A \code{data\_file} is scatter plotted using syntax as described above. +% The output is cropped automatically to the bounding box. +\findex{data\_file.plot} +\begin{verbatim} + DF.plot(STYLE, [i1], [i2], [i3], [F]); + DF.plot(STYLE, F, [i1], [i2], [i3]); +\end{verbatim} +Histograms and bar charts are described below. + +A \code{data\_file} can be written to a disk file as raw data, or in +specified format. Below, \code{fmt} denotes a \code{string}-valued +formatting function of two variables and \filename{myfile} is the +name of the disk file to be written. +\findex{data\_file.precision} +\findex{data\_file.write} +\begin{verbatim} + DF.precision(4); // set to 4 significant figures + DF.write("myfile"); // write as tab-separated columns + DF.write("myfile", fmt, [i1], [i2]); // apply fmt to cols +\end{verbatim} +A column can be extracted as a \code{C++}~\code{vector} for use by +another function. +\findex{data\_file.column} +\begin{verbatim} + DF.column(i); // i-th column + DF.column(f, i); // i-th column, transformed by f +\end{verbatim} + + +\subsubsection*{Data Containers} + +\ePiX\ provides a \code{data\_mask} class for culling data from a file +according to the values in a specified column, and a \code{data\_bins} +class for sorting data by value. + +A \code{data\_mask} consists of an interval of numbers and a +``filter'' function. The (closed, open, or half-open) interval is +given as a string in standard mathematical notation, or by its +endpoints (for a closed interval). The filter is a +\code{double}-valued function of \code{double}, by default the +identity, \teximath{f(x)=x}. +\findex{data\_mask} +\begin{verbatim} + data_mask dm("[a, b]", [f]); + data_mask dm(a, b, [f]); +\end{verbatim} +A \code{data\_mask} ``passes'' inputs~\teximath{x} if~\teximath{f(x)} +lies in the interval. The member function \code{reverse()} inverts +this logical test. + +The \code{data\_file} class has \code{prune} functions to cull +rows for which a specified column's entry satisfies a +\code{data\_mask}'s criterion. +\findex{data\_mask.prune} +\begin{verbatim} + DF.prune(dm, i); // remove row if i-th column entry fails + DF.prune(a, b, i); // remove row if i-th column outside [a,b] +\end{verbatim} + +A \code{data\_bins} object models an interval divided at specified +locations into ``bins'', not necessarily of equal length. Numerical +data is read in and the number of points in each bin counted. The +lifetime of a \code{data\_bins} object has two stages. First, ``cuts'' +(endpoints of subintervals) are added. Then, once data is read, the +cuts are ``locked'' and cannot subsequently be changed. +\findex{data\_bins} +\findex{data\_bins.cut} +\findex{data\_bins.read} +\begin{verbatim} + // [xmin, xmax] divided into n equal intervals, 1 by default + data_bins db(xmin, xmax, [n]); + db.cut(x); // add a cut at x (if x is in bounds) + db.read(vector<double>); // read data, lock bins +\end{verbatim} + +\index{Histograms} +\index{Bar Charts} +A \code{data\_bins} object can be plotted as a histogram (rectangles' +\emph{area} is proportional to the bin population), bar chart +(rectangles' \emph{height} is proportional to the bin population), or +spline interpolation of a bar chart. +\findex{data\_bins.histogram} +\findex{data\_bins.bar\_chart} +\findex{data\_bins.plot} +\begin{verbatim} + db.histogram(c=1); // c = vertical scale factor + db.bar_chart(c=1); + db.plot(c=1); +\end{verbatim} +By default (\code{c=1}), the height of a bar chart rectangle is the +fraction of the total population contained in the bin; thus, the +height is always between 0~and 1. For a histogram, the height of a +rectangle is the fraction of the population per horizontal unit in the +bin; thus, the total area over an interval~\teximath{[a,b]} does not +depend on how~\teximath{[a,b]} has been subdivided. The sample files +\filename{dataplot.xp}~and \filename{histogram.xp} illustrate use. + +Statistical convention dictates cuts be chosen distinctly from data +values; that is, values should all fall strictly within a bin, not at +a boundary point. With large, unknown data sets, this convention may +be difficult to uphold. \ePiX\ attempts to handle anomalous data +intelligently, by keeping counts of values ``out-of-range'' or +``on-cut''. + +In detail, if \teximath{x<a} or \teximath{x>b} is a data value, it is +counted as out-of-range and does not contribute to the histogram +population. If \teximath{x=a} or \teximath{x=b}, the value counts as +both out-of-range and on-cut but is added to the population of the +lowest or highest bin, respectively. Any other cut appearing as a data +input is flagged as on-cut, and increments the population of each +adjacent bin by one-half. When a histogram or bar chart is written, +\ePiX\ prints a warning message summarizing the number of anomalous +data seen. + + +\subsubsection*{Error Bars} +\index{Error bars} + +Simple horizontal and vertical error bars are provided. The final +(optional) argument is the true height or width (respectively) in pt. +\findex{h\_error\_bar} +\findex{v\_error\_bar} +\begin{verbatim} + h_error_bar(P location, double error, <mark type>, ht=6); + v_error_bar(P location, double error, <mark type>, wd=6); +\end{verbatim} + +To create more complex elements, such as asymmetric bars, whisker +plots, labeled error bars, and the like, write a custom function using +true-size drawing, see page~\pageref{truesize}. For example, a +fillable, labeled, asymmetric, vertical rectangular error bar can be +implemented (entirely in \ePiX) like this: +\begin{verbatim} + void error_bar(P loc, double lo, double hi, P offset, + std::string text, align, double wd=6) + { + const double width(pt_to_screen(0.5*wd)); // converts to 3pt + rect(loc - P(width, lo), loc + P(width, hi)); + line(loc - P(width, 0), loc + P(width, 0)); + label(loc + P(width, 0), offset, text, align); + } +\end{verbatim} +For stylistic uniformity, functions such as this should be put into a +library and used systematically. Section~\ref{section:extensions} +outlines the process of writing, compiling, and using a custom +library. +\index{Plotting!data|)} +\index{Data plotting|)} + + +\subsection{Legends} +\index{Legends} + +A \code{legend} systematically labels different parts of a plot by +associating visual ``keys'' with explanatory text. This tends to be +most useful for plots containing several distinct but conceptually +related graphs requiring contrast. + +Visually, a \code{legend} is represented as an aligned list of rows, +each containing a box (the key), a gap (the label skip), and some +text. These rows are printed in a (usually large) masked label. By +default, keys are \code{12pt}~squares bordered in black, the label +skip is~\code{6pt}, the background is white, and the border is plain +black. These attributes are controlled (simultaneously for all items) +with member functions. Parameters of type \code{double} represent +lengths in~\code{pt}. +\findex{legend} +\findex{legend.backing} +\findex{legend.border} +\findex{legend.item\_border} +\findex{legend.label\_skip} +\findex{legend.key\_size} +\begin{verbatim} + legend L; + L.backing(color); // set background + L.border(color, [double]); // set border color [and width] + L.border(double); // border width + + L.item_border(color, [double]); + L.item_border(double); // same, for item borders + + L.label_skip(double); + L.key_size(double); +\end{verbatim} + + +\subsubsection*{Legend Keys} + +There are three types of legend key, representing filled regions, +paths, and markers. Fill and path keys get their visual attributes +from the current drawing state. A mark key must be told the marker +type. Each is created by specifying the item text. +\findex{legend.fill\_item} +\findex{legend.path\_item} +\findex{legend.mark\_item} +\begin{verbatim} + L.fill_item(text); + L.path_item(text); + L.mark_item(<mark type>, text); +\end{verbatim} +Keys in the printed legend appear in the same order they are created +in the input file. + + +\subsubsection*{Creating a Legend} + +Normally, a \code{legend} is defined near the start of a file, and an +item is added at the point in the file where the corresponding object +or plot is drawn, so that the item receives the correct attributes. A +\code{legend} is placed into the figure with the \code{draw} +function. The arguments have the same meaning as for ordinary +\code{label}s. +\findex{legend.draw} +\begin{verbatim} + L.draw(P location, P offset, align); +\end{verbatim} +All three arguments are mandatory. ``Global'' \code{legend} settings +(border, backing, etc.) may be changed anywhere between the +\code{legend}'s creation and \code{draw} function. The sample file +\filename{legend.xp} revisits the example on +page~\pageref{taylor_poly}, including a trig-labeled axis and a +legend. The file \filename{shadeplot.xp} contains filled keys, and +\filename{dataplot.xp} contains a \code{legend} with items of mixed +type. + + +\section{More About \CXX} +\index{Cplusplus@\CXX|(emph} + +A textbook or similarly detailed reference is essential for serious +study of~\code{C} or~\CXX. \emph{The \code{C} Programming Language}, +second edition, by Kernighan~and Ritchie~\cite{KnR}, is an excellent, +manageable resource for the basics of procedural +programming. \emph{C++ Primer Plus}, by Stephen Prata~\cite{Prata}, +clearly lays out the extensive details of~\CXX. Marshall Cline's +\emph{\CXX\ FAQ Lite}~\cite{Cline} engagingly discusses common points +of confusion and furnishes tips on good design and programming. + +\CXX\ is a powerful, complex language whose syntax is similar to that +of~\C, or to the scripting languages of Maple~and Mathematica. An +\ePiX\ input file is source code for a \CXX~program that writes a +\LaTeX\ picture as output. \ePiX\ may be viewed as an extension +to~\CXX; in the same way that \LaTeX\ furnishes a high-level interface +to~\TeX, \ePiX\ provides a high-level bridge between the computational +power of~\CXX\ and the \LaTeX\ \code{picture} environment. + +\index{Function} +\index{Conditional statement} +Like all high-level programming languages, \CXX\ provides variables, +functions, and control structures. Variables hold pieces of data such +as numerical values and geometric locations, while functions operate +on data. A control structure, such as a loop or conditional statement, +affects the program's course according to the program's current state. +A source file is composed primarily of ``statements'', which perform +actions ranging from defining variables and functions to setting +figure attributes, performing calculations, and writing objects to the +output file. + +\subsection{Names and Types} + +\index{Variable!names|(} +Names of variables and functions may consist (only) of letters, +digits, and the underscore character. The first character of a name +must not be a digit, and the language standard reserves names starting +with underscore for library authors. Names are case-sensitive, but +it's usually a bad idea to use a single name capitalized and +uncapitalized in a single file. Numerous capitalization conventions +are used informally; this document uses uncapitalized words separated +by underscores for variables and functions, and occasionally uses all +capitals for constants. As with names of \LaTeX\ macros, primary +considerations are clarity (of meaning), readability, and consistency. +\index{Variable!names|)} + +\index{Variable!type of} +Every variable in \CXX\ has a ``type'', +such as integer (\code{int}), double-precision floating point +(\code{double}), or Boolean (\code{bool}, true~or false). \ePiX\ +provides additional types, the most common of which is~\code{P}, for +point. The construct \code{P(x,y,z)} creates~\teximath{(x,y,z)}, while +\code{P(x,y)} gives~\teximath{(x,y,0)}, which is effectively the +pair~\teximath{(x,y)}. A variable is defined by giving its type, its +name, and an initializing expression. + +\index{Variable!pointer} +\index{Pointer} +In~\code{C} and~\CXX, a \emph{pointer} variable holds the memory +address of another variable. Pointers are useful for manipulating +(possibly large) data structures through ``handles'' of fixed small +size. \CXX\ also provides \emph{references}, which bind an additional +name to an existing object and allow the object to be manipulated +through this alias. The statements +\begin{verbatim} + double x=1; // ordinary variable definition + double& rx=x; // bind a reference, signified by & +\end{verbatim} +define a variable~\code{x} having the value~1, and bind a reference +variable~\code{rx} to it. As long as~\code{rx} exists, it refers +to~\code{x}. If the value of~\code{x} changes, the value of~\code{rx} +does as well. Conversely, the value of~\code{x} can be altered by +assigning to~\code{rx}. However,~\code{rx} is the size of a pointer, +regardless of the size of~\code{x}, so~\code{rx} can be passed +efficiently in a function call. +\texicomment +Some applications are discussed on page~\pageref{references}. +\texicommentend + + +\subsection{Functions} + +\index{Function|(} +In a programming language, the term ``function'' refers to a block of +code that is executable by name. A \CXX\ function takes a list of +``arguments'', and has a ``return value''. This information, together +with the function's name, must be provided when a function is defined. +A function may not be defined inside another function. However, a +function may call other functions (including itself) as part of its +execution: +\begin{verbatim} + int factorial(unsigned int n) + { + if (n == 0) return 1; + else return n*factorial(n-1); + } +\end{verbatim} + +\index{Function!returning \code{void}} +The special type~\code{void} represents a ``null type''. A function +that performs an action but does not return a value has return type +\code{void}. A function that takes no arguments may be viewed as +taking a single \code{void} argument. + +Every \CXX\ program has a special function~\code{main()}, which is +called by the operating system when the program is run. The arguments +of~\code{main()} are command-line arguments, and the return type is an +integer that signals success or failure. User-specified functions must +be defined before the call to \code{main()} or in a +separately-compiled file. + +Functions in~\CXX\ may be as simple as an algebraic formula or as +complex as an arbitrary algorithm. Greatest common divisors, finite +sums, numerical derivatives and integrals, solutions of differential +equations, recursively generated fractal curves, and curves of best +fit are a few applications in \ePiX. Several sample files contain +user-level algorithms, which do not require knowledge of \ePiX's +internal data structures. The source file \filename{functions.cc} +contains simple functions defined by algorithms, and +\filename{functions.h} illustrates the use of \CXX\ templates. Other +source files, such as \filename{plots.cc}, may be consulted for +Simpson's rule, Euler's method, and the like. + + +\subsection{Mathematical Functions} + +\index{Function!mathematical|(} +\CXX~knows several familiar mathematical functions by name: +\begin{verbatim} + sqrt exp log log10 ceil floor fabs +\end{verbatim} +(\code{fabs} is the absolute value for a floating-point argument.) +\ePiX\ provides trig and inverse trig functions sensitive to angular +mode: +\index{Angular mode} +\findex{Cos} +\findex{Sin} +\findex{Tan} +\findex{Sec} +\findex{Csc} +\findex{Cot} +\findex{Acos} +\findex{Asin} +\findex{Atan} +\begin{verbatim} + Cos Sin Tan + Sec Csc Cot + Acos Asin Atan +\end{verbatim} +The inverse functions are principle branches. + +The function \code{pow(x,y)} returns~\teximath{x^y} when +\teximath{x>0}, and \code{atan2(y,x)} (N.B. argument order) returns +\teximath{\mathrm{Arg}(x+iy)\in(-\pi,\pi]}, the principle branch of +arg. \CXX~knows many constants to 20~decimal places, such as +\code{M\_PI}, \code{M\_PI\_2}, and \code{M\_E} for~\teximath{\pi}, +\teximath{\pi/2}, and~\teximath{e} respectively. \ePiX\ defines a few +additional functions: +\findex{sgn} +\findex{zero} +\findex{sinx} +\findex{cb} +\begin{verbatim} + sgn zero sinx cb +\end{verbatim} +\texicomment +\begin{center} + \input{sgn.eepic}\qquad + \input{sinx.eepic}\qquad + \input{cb.eepic} +\end{center} +\medskip +\texicommentend +\code{sgn} is the signum function; \code{zero} is the constant +function; \code{sinx} is the function \teximath{x\mapsto \sin(x)/x} +with the discontinuity removed; \code{cb} (for ``Charlie Brown'') is +the period-2 extension of the absolute value function +on~\teximath{[-1,1]}. + +The GNU \CXX\ library defines other functions, including inverse +hyperbolic functions (\code{acosh}, etc.), \code{log}~and \code{exp} +with base~2, 10, or arbitrary~\teximath{b} (\code{log2}, etc.), the +error and gamma functions (\code{erf}~and \code{tgamma} [sic], +respectively), and Bessel functions of first and second kind: +\code{j0}, \code{j1}, \code{y0}, etc. Use, e.g., \code{jn(5,~)} to get +higher indices. The GNU \C~library reference manual~\cite{GNUC} +describes these and other functions in detail. + +Functions may be used in subsequent definitions, and functions of two +(or more) variables are defined in direct analogy to functions of one +variable: +\begin{verbatim} +double f(double t) { return t*t*log(t*t); } // t^2 \ln(t^2) +double g(double s, double t) { return exp(2*s)*Sin(t); } +\end{verbatim} +\index{Function!mathematical|)} + + +\subsection{Basics of Classes} + +\index{Classes|(} +Unlike~\code{C}, \CXX\ supports ``object-oriented programming''. In a +nutshell, a \emph{class} is an abstraction in computer code of some +concept, such as a point, a sphere, a mapping that can be plotted, or +a camera. Classes allow a programmer to separate an object's +\emph{interface} (the set of meaningful operations) from its +\emph{implementation} (the data structures and algorithms that realize +the interface). + +\index{Function!class member} +A class implementation consists of \emph{members} (named data +elements) and \emph{member functions} (functions that belong to the +class and have free access to members). \CXX\ classes enforce access +permissions on their members, protecting data from being manipulated +except as promised by the interface. + +An ideal interface looks like a black box: It hides the implementation +completely. In order to cooperate, two classes need only know each +other's interfaces. This separation of form and function modularizes a +program, and facilitates debugging, code reuse, and overall +maintainability, particularly in large programs. + +In simple programming, classes may be treated like built-in types. +Each class object has its own member functions, whose call syntax +differs from standard function calls: +\begin{verbatim} + Circle C1(P(1,0), 1.5); // circle of given center and radius + C1.draw(); // member function Circle::draw(); +\end{verbatim} +Naturally, this call draws the circle~\code{C1}. Generally, a member +function call consists of a class object's name, a period, and the +name of the member function. Arguments, if any, go in the parentheses +after the member function name, just as in a regular function call. + +A few short paragraphs cannot do more than scratch the surface of +classes and object-oriented programming. For more details, please +consult a book, such as Prata~\cite{Prata} or Stroustrup~\cite{S}, or +Cline's on-line FAQ~\cite{Cline}. +\index{Classes|)} + + +\subsection{References and Function Arguments} + +\index{Function!call syntax} +\index{Variable!reference} +\label{references} +\code{C}~and \CXX\ are ``call by value'' languages. Variables are not +passed to a function; instead a copy of the value is made, and the +function operates only on the copy. Though this feature causes +occasional inconvenience, it prevents an object from being altered +unexpectedly by a function call in a different part of the program. +Calling by value helps localize the logic of a program, and +circumvents easy-to-write but extremely hard-to-find bugs. + +In \CXX, a function may accept reference arguments. Passing an object +by reference grants the calling function access to the object itself, +not to a copy. There are two common applications: The object is a +large data structure for which copying is ``expensive'', or the +function \emph{needs} to modify its arguments (e.g., a function +\code{swap(x,y)} that exchanges the values of \code{x}~and +\code{y}). + +For the first situation, \CXX\ provides the \code{const} keyword, +which ensures the function does not modify its arguments, but accepts +a reference merely for efficiency. Any attempt to modify a +\code{const} argument will be caught by the compiler. Most \ePiX\ +commands accept \code{const} reference arguments. + +The ability to pass function arguments by reference is sometimes +touted as a feature in \CXX\ texts. However, the technique circumvents +the data encapsulation of calling by value, and should be avoided +unless absolutely necessary. If a function merely ``updates'' the +value of a variable, probably the variable should be of class type, +and the update should be performed by a member function. + +A function declaration must indicate that its arguments are +references. The declarations below have the indicated idiomatic +meanings. +\begin{verbatim} + class matrix; + double det(matrix); // call by value, perhaps inefficient + matrix& transpose(matrix&); // probably changes its argument + double trace(const matrix&); // does not change its argument +\end{verbatim} +Unlike pointer arguments, reference arguments impose no syntactic +burden on the user. If~\code{A} is a~\code{matrix}, then +\code{transpose(A);} and \code{trace(A);} will compile. You need not +declare explicit reference variables and pass those to the function. + + +\subsection{Overloading} + +\index{Function!overloaded} +\CXX\ provides ``overloading'': Multiple functions can be given the +same name, so long as the number and/or type of their arguments +differ. (It is \emph{not} enough for the return types alone to differ. +The compiler must be able to select a function from its calling +syntax.) To the user, the appearance is that a single function +intelligently handles multiple argument lists. Naturally, overloaded +names should refer to functions that are conceptually related. +\index{Function|)} + + +\subsection{Scope} + +\index{Variable!local} +A \CXX\ statement ends with a semicolon. A collection of statements +enclosed by curly braces is a ``code block'', and may be viewed as a +single logical statement. Curly braces determine a ``scope'', inside +which variable names may be re-used without ambiguity. Function +bodies are code blocks, as are the alternatives associated to control +statements. A variable defined between curly braces is said to be +\emph{local} to the scope in which it is defined; its value cannot +be used out of scope. Variables should be declared in the smallest +scope possible. + +The compiler is not picky about spaces, tabs, and newlines, so an +input file should be formatted to make local scopes visually +apparent. \code{emacs} automatically indents code to reflect scope, +though the default behavior does not please all users. As with +variable naming, clarity and consistency are paramount. + + +\subsection{Headers and Pre-Processing} + +A \CXX\ source file is compiled in multiple stages that occur +transparently to the user. The first step, pre-processing, involves +simple text replacement for file inclusion, macro expansion and +conditional compilation. Next, the source is compiled and assembled: +Human-readable language instructions are parsed, then represented in +assembly language. Finally, the object files are linked: Function +calls are resolved to hard-coded file offsets, possibly involving +external library files, and the program instructions are packaged into +an executable binary that the operating system can run. + +Pre-processing is used much less in~\CXX\ than in~\code{C}; the +language itself supports safer and more featureful alternatives to +macros, such as \code{const} variables and inline functions. File +inclusion and conditional compilation are the chief uses of the +pre-processor. Lines of the form +\begin{verbatim} + #include <iostream> + #include "epix.h" +\end{verbatim} +cause the contents of a \emph{header file} to be read into the source +file. A header file contains variable and function +\emph{declarations}, statements that specify types and names but do +not define actual data. Declarations tell the compiler just enough +to resolve expressions and function calls without knowing specific +values or function definitions. + +\index{Input file!conditional compilation} +Conditional compilation is similar to conditional \LaTeX\ code. For +example, a file might produce either color or monochrome output as +follows: +\begin{verbatim} +#ifdef COLOR + ... // code for generating color figure +#endif /* COLOR */ +#ifndef COLOR + ... // monochrome code +#endif /* undef COLOR */ +\end{verbatim} +The ``compiler symbol'' \code{COLOR} is an ordinary \CXX\ name. To +control compilation, either put a \code{\#define COLOR} line in the +file, or (better) supply the flag on the command line: \\ +\verb+ epix -DCOLOR <file.xp>+ \\ +Every \code{\#ifdef} must have a matching \code{\#endif}. Commenting +the \code{\#endif} is a good habit; in a realistic file, the start and +end of a conditional block may be separated by more than one screen. + + +\subsection{Comparison with \LaTeX\ Syntax} + +As a programming language, \CXX\ provides certain features common to +all languages (such as \LaTeX, MetaPost, Perl, Lisp\ldots) and adheres +to rules of grammar. Salient differences between \LaTeX\ and \CXX\ +include: + +\begin{enumerate} +\item Every \CXX\ statement and function call must end with a + semicolon. An omitted semicolon may result in a cryptic error + message from the compiler. Pre-processor directives, which start + with a~\code{\#}, do not end with a semicolon. + +\item Backslash is an escape character in \CXX: + \index{Labels} +\begin{verbatim} + // Put label $y=\sin x$ at (2,1) + // Note single ^ backslash in output + label(P(2,1), P(0,0), "$y=\\sin x$"); + // Double backslash ^^ in source +\end{verbatim} + +\item Variable and function names may contain letters (including + underscore) and digits \emph{only}, are case sensitive, and must + begin with a letter. + +\item Variables in \CXX\ must have a declared \emph{type}, such as + \code{int} (integer) or \code{double} (double-precision floating + point). If a variable has global scope and its value does not + change, the definition should probably come in the preamble or at + the beginning of \code{main}. Local variables should be defined in + the smallest possible scope. Unlike~\C, \CXX\ allows variables to be + defined where they first appear. + +\item \CXX~requires explicit use of~\code{*} to denote multiplication; + juxtaposition is not enough. \CXX~does not support the use of + \verb+^+ for exponentiation, e.g., \verb+t^2+ is invalid. Instead, + use \code{t*t}~or \code{pow(t,2)}. + +\item \CXX\ has single- and multi-line comments. Everything between a + double slash and the next newline is ignored, while the strings + \verb+/*+~and \verb+*/+ delimit multi-line comments. A single-line + comment may appear within a multi-line comment, but the compiler + does not nest multi-line comments. + \index{Input file!comment in} + +\end{enumerate} + +Between them, \C~and \CXX~have about 100~reserved keywords which +cannot be used as function or variable names. +\index{Cplusplus@\CXX|)} + + +\section{Attribute Quick Reference} +\label{section:quickref} + +In the body of an input file, the ``drawing state'' determines the +figure's appearance. Attributes are declarations, set by commands that +accept arguments of the stated type. + +A \code{len} argument is a double-quoted string containing a number +and a two-letter \LaTeX\ length unit, such as \code{"1.5pt"} or +\code{"6cm"}. A \code{color} argument is a named primary +(\code{Red()}, \code{Cyan()}, \code{White()}, etc.), a \code{Color} +specified by densities (\code{RGB(...)}, \code{CMYK(...)}, etc.), or a +\code{Color} object. Using \code{Neutral()} as a \code{Color} argument +generally turns off the corresponding attribute. + +\begin{itemize} + +\item Angular mode: \code{radians()}, \code{degrees()}, or + \code{revolutions()}. + + The angular mode affects all trigonometric operations, including + camera rotations, the drawing of arcs and ellipses, polar plotting, + label angle, and the trig functions themselves. Angle-sensitive trig + functions are capitalized, e.g., \code{Cos}, \code{Tan}. + +\item Fill style: \code{fill(color)}, \code{fill(bool)}, + \code{nofill()}. + +\item Path style: + + \begin{itemize} + + \item Width: \code{plain()}, \code{bold()}, \code{bbold()}, + \code{pen(len)}. + + \item Line style: \code{line\_style(string)}. The argument is a + WYSIWYG sequence of dashes, spaces, and periods. + \code{dash\_size(double)} and \code{dot\_sep(double)} set the + (approximate) length in~\code{pt} of the pattern. The commands + \code{solid()}, \code{dashed()}, \code{dotted()} define + ``standard'' defaults for brevity. + + \item Path color: + Paths can be drawn using \emph{two} pens, one atop the other. When + the ``base'' pen is white (or the background color) and wider than + the ``line'' pen, a path masks parts of the figure it crosses. A + 3-D effect may be obtained by making the base pen a darker shade + than the ``line'' pen. + + \code{pen(color,[len])}, \code{base(color,[len])} + + Standard widths: \code{plain(color)}, \code{bold(color)}, + \code{bbold(color)} + + \end{itemize} + +\item Text attributes: + + \begin{itemize} + + \item Color: \code{label\_color(color)} + + \item Mask: \code{label\_mask(color)}, \code{label\_pad(len)} + + \item Border: \code{label\_border(color, [len])}, + \code{label\_border(len)}. The command \code{no\_label\_border()} + turns off label borders. + + \item Font size: \code{font\_size(LaTeX size)}, no argument means + \code{normalsize}. + + \item Font face: \code{font\_face(LaTeX font)}, two-letter font + selection string, default is \code{rm}. + + \item Rotation: \code{label\_angle(double)} + + \end{itemize} + +\end{itemize} + +Do not confuse \code{Color} constructors with the similarly-named +(deprecated) lowercase attribute-setting commands, \code{rgb(r,g,b)}, +\code{cmyk(c,m,y,k)}, \code{red(d)}, etc. These commands affect text, +paths, and filled regions. For example, the single command +\code{red()} has the same effect as the three commands +\code{pen(Red())}, \code{fill(Red())}, and \code{label\_color(Red())}. + + +\texinfochapter{4}{Advanced Topics} +\label{chapter:adv} + +This chapter covers \emph{ad hoc} tricks and open-ended techniques +that require relatively more programming sophistication. You will +almost surely need an external \CXX\ reference if you do not speak the +language. + + +\section{Hidden Object Removal} +\label{section:hidden} + +\index{Hidden object removal|(} +\ePiX\ writes the output file in the same order that objects appear in +the input. The order is significant because PostScript builds a figure +in layers: Objects are drawn over objects that come earlier in the +file. Shaded polygons can be used to obtain surprisingly effective +hidden object removal in surface meshes. This section describes the +data structures defined in the source files \code{surface.*}. + +\index{Camera} +The basic idea is to create a shaded polygon class that knows its +approximate distance to the camera. For computational simplicity, a +mesh ``facet'' is treated as a quadrilateral, located at the +arithmetic mean of its vertices. A facet's boundary is created from a +map and a domain by tracing a fine mesh rectangle counterclockwise. + +To draw a parametrized surface, facets are stored in a \CXX\ vector, +sorted in decreasing order of distance to the camera, and printed to +the output file. If filling is active, the gray density of a facet +depends on the cosine of the angle between the normal vector and the +vector from the camera to the element. + +This simple algorithm works surprisingly well when mesh elements +intersect at most along complete edges. To incorporate line-like +elements (e.g., coordinate axes, wire-mesh plots) with shaded +surfaces, the best technique is often to order high-level scene +elements manually, breaking up shaded surfaces (for example, with +domain resizing or clipping) as necessary. The sample file +\filename{saddle.xp} illustrates possible techniques. + +Shaded surfaces can be decorated with a bit of hackery. For example, +the \code{facet::draw} function in \filename{facet.cc} can be +modified easily to draw line elements, tangents, or normal vectors +along with the facet itself. The sample file +\filename{decorate.xp} contains a couple of ideas. (The +decorations are activated by compiler flags; please consult the file +itself for information on compiling.) +\index{Hidden object removal|)} + + +\section{Extensions} +\label{section:extensions} + +Thanks to a suggestion of Andrew Sterian, \ePiX\ is extensible. User +extensions span a spectrum, from header files that require only basic +knowledge of~\CXX\ to separately compiled libraries that add +substantial new features. The structure of the source code is +outlined in Section~\ref{section:programmers}. + + +\subsection{Header Files} + +A \CXX~header file conventionally has suffix~\filename{.h}, as in +\filename{myheader.h}. To use this custom header, put a line +\code{\#include "myheader.h"} in your source file. + +User definitions can be easily and robustly implemented with ``inline +functions''. Inline functions are superficially similar to macros, but +are far more safe and featureful (since they are handled by the +compiler rather than by the pre-processor). Examples are +\begin{verbatim} + inline void Bold() { pen(1.6); } + inline void purple() { rgb(0.5, 0, 0.7); } + inline void draw_square(double s) { rect(P(-s,-s),P(s,s)); } + inline double cube(double x) { return pow(x,3); // x^3 } +\end{verbatim} +The keyword \code{void} signifies a function that does not return a +value, or (when used as an implicit parameter) a function that does +not accept arguments. Inline function definitions are syntactically +identical to ordinary function definitions, but \emph{must} occur in a +header file or in the source file where they are used. The examples +above might be used in an input file as follows: +\begin{verbatim} + Bold(); + draw_square(cube(1.25)); +\end{verbatim} + + +\subsection{Compiling} + +The next few sections outline the creation of a ``static library'' on +GNU/Linux, and explain how to incorporate custom features at runtime. +The extensively-commented sample files \filename{std\_F.cc}~and +\filename{std\_F.h} illustrate the techniques described below, and may +be used for guidance and experimentation. + +A small library is usually written as a \emph{header} file, which +contains class and function declarations (also called ``prototypes''), +and a \emph{source} file, which contains the actual +code. Conventionally (under *nix), these files have extension +\filename{.h}~and \filename{.cc} respectively. Header and source files +may ``include'' other header files, to incorporate additional +functionality. +\begin{verbatim} +/* my_code.h */ +#ifndef MY_CODE +#define MY_CODE +#include <cmath> // standard library math header +#include "epix.h" // ePiX header +using ePiX::P; + +namespace Mine { // to avoid name conflicts + // functions for special relativity + double lorentz_norm(const P&); + bool spacelike(const P&); +} // end of namespace +#endif /* MY_CODE */ +\end{verbatim} +This file exhibits two ``safety features''. The three \code{MY\_CODE} +lines prevent the file from being included multiple times. In a file +of this size, inclusion protection is overkill, but as your code base +grows and the number of header files increases, this protection is +essential. Second, the header introduces a ``Mine'' namespace. Inside +this namespace, two functions are declared as prototypes, giving the +function's return type, name, and argument type(s). A header file +should be commented fairly liberally, so that a year or two from now +you'll be able to decipher the file's contents. For a longer file, +version and contact information, an overall comment describing the +file's features, and license information are appropriate. + +Next, the corresponding source file; definitions are also placed into +the namespace, and must match their prototypes from the header file +exactly. +\begin{verbatim} +/* my_code.cc */ +#include "my_code.h" +using namespace ePiX; + +namespace Mine { + double lorentz_norm(const P& arg) + { + double x(arg.x1()), y(arg.x2()), z(arg.x3()); // extract coords + return (y-x)*(y+x) + z*z; // -x^2 + y^2 + z^2 + } + bool spacelike(const P& arg) + { + return (lorentz_norm(arg) > 0); // true if inequality is + } +} // end of namespace +\end{verbatim} +Copies of these files are included with the source code so you can +experiment with them. Next, the source file must be ``compiled'', +``archived'', and ``indexed''. In the commands below, the percent sign +is the prompt. +\begin{verbatim} +% g++ -c my_code.cc +% ar -ru libcustom.a my_code.o +% ranlib libcustom.a +\end{verbatim} +Please see your system documentation for details on command options +and what each step does. For linking (below), the name of the library +file must begin ``lib'' and have the extension~\filename{.a}. Once these +steps are successfully completed, put the library \filename{libcustom.a} +and header file \filename{my\_code.h} in your project directory. You're +ready to use the code in an \ePiX\ figure. + + +\subsection{Runtime Linking} + +The script~\epix\ allows input files to be linked with external +libraries at run time, when the input file is compiled into a +temporary executable. + +\epix\ recognizes command line options and passes them verbatim to the +compiler. The most commonly used options are those of the form +\begin{verbatim} + -I<include> -L<libdir> -l<lib> +\end{verbatim} +For example, to link \filename{figure.xp} against +\filename{mylibs/libcustom.a}, run the command +\begin{verbatim} + epix -Lmylibs -lcustom figure +\end{verbatim} +The options \code{-I. -L.} tell the compiler to look in the current +directory for header and library files. Compiler options may appear +in any order, but must come before the name of the input file(s). + +Compiler options may be placed in the configuration file +\filename{\$HOME/.epixrc}, with syntax as above. A line in the config +file that contains a pound sign~(\code{\#}) is a comment, no matter +where in the line the~\code{\#} appears. If any non-comment line +fails to start with a dash, the rest of the file is silently +discarded. Command-line options are read before the config file. + + +\subsection{Using Multiple Versions} + +The script \filename{epix}~links by default against the \code{C}~math +library \code{libm.a}~and the \ePiX\ library \code{libepix.a}. The +command option \code{--no-defaults} clears the header and include +paths and removes \code{libepix.a} from the link list. The script may +therefore be used with multiple versions of \ePiX, a potentially +useful feature if you regularly need to compile old source files, or +simply prefer the syntax of an older version. + +To install and use (say) Version~1.0.0, build the package according to +its \filename{INSTALL} instructions, but \emph{do not use the makefile + to install}. Instead, manually install the header and library only, +using their version number: +\begin{verbatim} +# install -m 644 epix.h /usr/local/include/epix-1.0.h +# install -m 644 libepix.a /usr/local/lib/libepix-1.0.a +\end{verbatim} +A non-system directory may be used instead of \filename{/usr/local}. +To use the old version, a source file must \code{include} the +appropriate header file (which is identified by its version number). +To compile, issue a command such as +\begin{verbatim} +epix --no-defaults -I/usr/local -L/usr/local -lepix-1.0 file.xp +\end{verbatim} + + +\section{Programmer's Guide} +\label{section:programmers} + +This section briefly surveys \ePiX's implementation, and is intended +for (potential) programmers. The source code is divided into modules +with small, well-defined responsibilities, but the user interface is +mostly compatible with the syntax of Version~1.0. These constraints +demanded a degree of implementation hiding. For example, the +user-visible classes defined in \filename{Color.h}, \filename{path.h}, +and~\filename{screen.h} contain only a pointer to the implementation +class, and style data is hidden behind global commands. + +Functionally, the code consists of the user interface; implementation +class\-es comprising drawing attributes, spatial objects, screens and +representations of their elements, and output; and miscellaneous +utility functions. The headers in each group, and their contents, are +described in Section~\ref{section:interface}. + +The user interface headers are assembled into a single file, +\filename{epix.h}, and installed in \filename{/usr/local/include} by +default. In normal use, the shell scripts read only the user interface +header. The individual headers, including the components of +\filename{epix.h}, are installed in +\filename{/usr/local/include/epix}. These are provided for authors of +external libraries, who may need access to implementation details. + + +\subsection{External Packages} + +\ePiX\ harnesses the computational power of~\CXX\ to the typographical +capabilities of \LaTeX. Consequently, \ePiX\ should be viewed in part +as a framework for expressing numerical data visually. + +In the course of your work, you may develop specialized code filling a +gap in \ePiX's functionality. If your code seems likely to be of +interest to other users, please consider bundling it as an external +package and notifying the \ePiX\ community so your work can be linked +from the project pages and distributed to interested users. + +There are no formal requirements for external packages, but in the +interest of uniformity contributed code should follow the GNU Coding +Standards~\cite{GNUCoding}. At a minimum, an external package should +build with the standard \code{./configure; make; make install} +commands, and the \code{configure} script should accept an option +\code{--with-epix} for the user to specify a non-default \ePiX\ +install directory. + +If an external package builds a static library, it should provide a +single header containing all the package's entry points, and enclose +its interface in a namespace. Entry points should not collide with +\ePiX\ functions. Naming the package ``\filename{epix-<...>}'' is a +good idea, but not essential. For example, a package providing textual +nodes and diagram layout might be named \filename{epix-nodes}. Input +files would use the package with the lines +\begin{verbatim} + #include "epix-nodes.h" + using namespace ePiX-nodes; +\end{verbatim} +and be compiled with +\begin{verbatim} + epix -lepix-nodes <file> +\end{verbatim} + +The user and internal interfaces of \ePiX-1.2 are not likely to +change. Still, it's prudent to rely only on the user interface in +contributed code whenever possible. Doing so also simplifies your work +as an author; your library can simply \code{include} the user header +file, and deal only with high-level objects and drawing attributes. + + +\subsection{User Interface} +\label{section:interface} + +These files (in order) comprise the global header \filename{epix.h}. + +\Header{enums.h} Marker, alignment, Riemann integral, and vector field +types. + +\Header{length.h} Physical lengths, conceptually a number and +two-letter \LaTeX\ length unit. + +\Header{interval.h} Closed, open, and half-open interval ranges for +data culling. + +\Header{triples.h} The \code{P} class. + +\Header{functions.h} Angle-sensitive trig functions, miscellaneous +utility functions, the \code{Deriv}~and \code{Integral} classes. + +\Header{pairs.h} Screen locations and displacements, with complex +arithmetic operations. + +\Header{Color.h} The Color class interface, named +primaries and constructors. + +\Header{state.h} Angle mode; clipping and cropping; label styles; +filling; arrow head style; dot and tick sizes, dash length; line +style; line and base pen attributes; color-setting commands. + +\Header{frame.h} Orthonormal bases. + +\Header{domain.h} Coordinate boxes for function plotting. + +\Header{camera.h} The camera. + +\Header{screen.h} The screen class. + +\Header{picture.h} Dimension-setting, offset, layout, decoration, +verbatim text, and output format commands. + +\Header{markers.h} Point markers, axis labels, and coordinate axes. + +\Header{axis.h} Coordinate axes and labels in various styles. + +\Header{legend.h} Plot legends. + +\Header{path.h} The path class. + +\Header{curves.h} Polygons, arrows, ellipses, arcs, splines, +coordinate grids, and recursive fractal curves. + +\Header{circle.h} The \code{Circle} shape object class. + +\Header{plane.h} The \code{Plane} shape object class. + +\Header{segment.h} The \code{Segment} shape object class. + +\Header{sphere.h} The \code{Sphere} shape object class. + +\Header{intersections.h} Shape object intersection operators. + +\Header{plots.h} Plotting commands. + +\Header{surface.h} Shaded surface plots. + +\Header{data\_mask.h} Helper class for data pruning. + +\Header{data\_file.h} Class for storing and representing data. + +\Header{data\_bins.h} Class for sorting and counting data. + +\Header{geometry.h} Latitudes and longitudes; spherical plotting, +arcs, polygons, and polyhedra; hyperbolic arcs. + + +\subsection{Implementation Classes} + +\Header{Color\_Base.h} The Color implementation interface. + +\Header{Color\_CMY.h} The CMY color model. + +\Header{Color\_CMYK.h} The CMYK color model. + +\Header{Color\_Gray.h} The Gray color model. + +\Header{Color\_Neutral.h} Each color class has a ``Neutral'' member +that converts colors to that model by filtering. This file defines the +unique ``model-less'' Neutral color for which filtering performs no +action. + +\Header{Color\_RGB.h} The RGB color model. + +\Header{Color\_Sep.h} Classes for CMYK separation. + +\Header{active\_screen.h} Simple manipulator for the active screen. + +\Header{picture\_data.h} Picture implementation: two \code{screen}s +(representing the \code{canvas}~and the output page), true dimensions +and offsets, pointer to output format, list of colors, and lists of +verbatim text to write before and after printing the \code{picture} +environment in the output file. For simplicity, the \code{screen}s and +dimensions are public; encapsulation from the user results from +``hiding'' this header. + + +\subsubsection*{Style Attributes} + +Declaration-style attributes are maintained with functions returning +static references: \code{the\_angle\_style()}, +\code{the\_arrowhead\_style()}, \code{the\_label\_style()}, +\code{the\_mark\_size()}, \code{the\_paint\_style()}, and +\code{the\_path\_style()}. Each function is declared in the +analogously-named header. + +\Header{angle\_units.h} Angular modes: \code{radians}, +\code{revolutions}, and \code{degrees}. + +\Header{arrow\_style.h} Arrow head style data: width, ratio, and +inset. + +\Header{label\_style.h} Text object style: Label and mask colors, +padding, border color and width, alignment, font size, font face, and +angle. + +\Header{marker\_style.h} Dot and tick sizes. + +\Header{paint\_style.h} Line and base pens, fill color. + +\Header{path\_style.h} Solid, dashed, dotted lines. + +\Header{pen\_data.h} The pen class. + + +\subsubsection*{Objects} + +\Header{arrow\_data.h} Arrow representation. + +\Header{facet.h} Shaded surface elements. + +\Header{label\_data.h} Text (label and marker) objects. + +\Header{legend\_item.h} Items for \code{legend}s. + +\Header{path\_data.h} Path implementation. + +\Header{spline.h} The natural spline class. + +\Header{spline\_data.h} Templates for quadratic and cubic splines. + + +\subsubsection*{Screen Representation} + +Elements in a \code{screen} are represented polymorphically as +``\code{tile}s'', of which there are six types: \code{glyph} (textual +elements), \code{pen\_arrow} (arrows), \code{pen\_fill} (filled +regions), \code{pen\_line} (path-like elements), \code{verbatim} +(raw text), and \code{legend\_tile} (legends). + +Border and background shape are dictated by the \code{screen\_mask} +class. The cropping algorithm assumes the contour of a screen mask is +convex. + +\Header{affine.h} Affine maps. + +\Header{cropping.h} Screen mask cropping. + +\Header{glyph.h} Markers and labels. + +\Header{legend\_tile.h} Screen representation of a \code{legend}. + +\Header{mask\_diamond.h} Screen diamond mask. + +\Header{mask\_ellipse.h} Screen elliptical mask. + +\Header{mask\_rectangle.h} Screen rectangular mask. + +\Header{pen\_arrow.h} Arrows. + +\Header{pen\_fill.h} Filled regions. + +\Header{pen\_line.h} Paths. + +\Header{screen\_data.h} Screen implementation class. + +\Header{screen\_mask.h} Screen mask interface. + +\Header{tile.h} Screen element interface. + +\Header{verbatim.h} Text in output stream. + + +\subsubsection*{Output} + +Output is divided into a couple of high-level operations and several +``atomic'' low-level operations. To create a new output +format, one need only implement the \code{format} interface for the +desired file type. Paths and filled regions may be implemented however +the output type dictates. + +\Header{eepic.h} eepic macros. + +\Header{fmt\_template.h} ``skeleton'' header for new output formats. + +\Header{format.h} The output interface. + +\Header{pst.h} PSTricks macros. + +\Header{tikz.h} tikz macros. + + +\subsubsection*{Utilities} + +\Header{Color\_Utils.h} Functions for setting color channel densities. + +\Header{clipping.h} The clip box. + +\Header{constants.h} Global constants: Line widths; dot, tick, and +dash sizes; arrowhead parameters; miscellaneous numerical constants +and internal parameters. + +\Header{crop\_algorithms.h} Path and loop clipping templates. + +\Header{deriv.h} Finite difference template. + +\Header{edge\_data.h} Path element representation template. + +\Header{errors.h} Warning and error messages. + +\Header{frac.h} Rational numbers and operators. + +\Header{halfspace.h} Halfspace cutting. + +\Header{hatching.h} Filling regions in eepic. + +\Header{lens.h} Camera lenses. + +\Header{map.h} Wrappers for templated plotting. + +\Header{plot\_algorithms.h} Plotting templates. + +\Header{screen\_crop.h} Crop paths and loops. + +\Header{utils.h} Truncation, date and time, line breaking. + + +\appendix +\texinfoappendix{A}{Software Freedom} +\index{Free software|(} + +Academics in general, and mathematicians in particular, depend on free +exchange of information. We prove theorems or establish experimental +results, write up formal accounts, place preprints on public file +servers, and submit papers to peer-reviewed journals. If accepted, the +results---data, techniques, methods of reasoning, citations, and +conclusions---are published in print and become part of the public +record, governed by copyright law. Libraries purchase journal +subscriptions, but researchers and scholars may use ideas from the +literature merely by giving appropriate citations in their own +work. ``Theft'' arises from false claims of authorship. + +Carried over to software, the academic process would guarantee rights +similar to those provided by the GNU General Public License (GPL): + +\begin{itemize} + +\item (GPL~0) To run a program for any purpose. + +\item (GPL~1) To study how the program works, and adapt it to your + needs. + +\item (GPL~2) To redistribute copies of the program. + +\item (GPL~3) To improve the program, and release improvements to the + public, so that the whole community benefits. + +\end{itemize} + +In reality, attitudes toward software differ markedly. Most academics +work on a proprietary platform, use proprietary software for research +and teaching, and share information with colleagues and students in +proprietary, even obfuscated, data formats. Contrary to the academic +ethic, proprietary software licenses restrict access to information: +preventing users from learning how a program works internally +(``reverse engineering''), limiting the number of users who may run a +piece of software, and forbidding users from running (or sometimes +even installing) a purchased copy on multiple machines. + +Restrictions on use aside, if one cannot examine a program's source +code, one cannot fully trust the output, any more than one can trust +(for purposes of scientific publication) results of a commercial +testing lab. + +\texicomment +\noindent$\phantom{.}$\hfil\vbox{\hrule width 4in}\hfil +\texicommentend + +Consider a hypothetical future world in which scholarly results are +disseminated like software. Instead of subscriptions, journals +sell licenses granting readership to a specified number of +individuals. Photocopying an article for a class or research seminar +constitutes ``piracy'', though if the institution has purchased a +sufficiently large site license the teacher or speaker may bring the +physical volume to class and project the pages onto a screen. + +Of course, reading an article is scarcely enlightening. Mathematics +papers contain only the statements of theorems. Merely opening the +journal binds the reader to a lengthy legal agreement, stating that +theorems be used only for specific purposes and threatening serious +legal consequences for attempting to discover the author's proofs. + +The actions of a single student, employee, or faculty member can +expose an institution to a costly ``journal audit'' from the +Mathematical Society of America (MSA), with the institution +responsible for legal costs if the audit reveals license violations +anywhere in the organization. + +Mathematicians who long for the Old Days when papers contained +proofs and were shared freely are dismissed as idealistic cranks +or labeled anti-business communists. Common knowledge asserts the +obvious superiority of proprietary journals, and the necessity of +licenses for keeping mathematicians gainfully employed. + +\texicomment +\noindent$\phantom{.}$\hfil\vbox{\hrule width 4in}\hfil +\texicommentend + +Back in our world, some vendors have attempted to placate opponents of +closed source with ``shared source'' licenses, under which one may +sign a non-disclosure agreement and subsequently examine source +code. In the future world analogy, a shared source agreement would +allow journal licensees to sign an NDA, then see the proofs of +theorems. Readers could thereby correct errors in proofs (benefitting +the publisher by improving the reliability of the journal), but would +be legally forbidden from using the ideas elsewhere (denying benefit +to other mathematicians). + +Legally and conceptually codifying software as a commodity ignores a +fundamental reality: Like an idea or recipe, software can be copied +without loss of the original. The perception of ``theft'' by copying +arises from an artificial belief that software has an owner who must +be monetarily compensated each time a person acquires a copy. The +nature of software does not enforce the ``sale'' model in the way +services and physical commodities do. It therefore seems +philosophically inappropriate to treat software as a commodity, and +perilous to conform the legal system to the enforcement of such a +model. + +At its best, software enhances our productivity and +creativity. Sharing software, like sharing ideas, benefits a larger +number of people without detriment to existing users. I hope this +modest program is, in conjunction with the much larger efforts of +others (especially Donald Knuth, Richard Stallman, and the many people +who have contributed to the authorship of \LaTeX\ and its packages), +useful to you in your mathematical work. + +Please visit the Free Software Foundation, at +\URL{www.fsf.org}, to learn more about free software and how +you can contribute to its development and adoption. +\index{Free software|)} + +\texinfoappendix{B}{Acknowledgments} + +\ePiX\ is built on the work of many people (unfortunately, most of +whom I am unaware). The following people have contributed, sometimes +unknowingly but always generously: + +\paragraph{Infrastructure} Donald Knuth, Conrad Kwok, Leslie Lamport, +Tim Morgan, Piet van~Oostrum, Sunil Podar, Richard Stallman, Till +Tantau, Herbert Voss, Timothy van~Zandt + +\paragraph{Enhancements} Jay Belanger, Robin Blume-Kohout, Julian +Gilbey, Marcus Hanwell, Yvon Henel, Svend Daug{\aa}rd Pedersen, Andrew +Sterian + +\paragraph{Porting and packaging} Julian Gilbey (Debian); Tsuguru Kato +(FreeBSD); Markus Dittrich, Danny van Dyk, Christian Faulhammer, +Olivier Fisette, Chris Gianelloni, Michael Hanselmann, Marcus Hanwell, +David Holm, Peter Johanson, Patrick Kursawe, Tobias Scherbaum, Markus +Ullmann (Gentoo); Guido Gonzato (RPM); Rene Rebe (T2) + +\paragraph{Debugging, advice, and other assistance} Jay Belanger, +Felipe Paulo Guazzi Bergo, Karl Berry, Robin Blume-Kohout, Patrick +Cousot, Stephen Gibson, Julian Gilbey, Dov Grobgeld, Bob Grover, Jim +Hefferon, Jacques L'helgoual, Yvon Henel, Hartmut Henkel, Herng-Jeng +Jou, Walter Kehowski, Kevin McCormick, Ross Moore, Thorsten Riess, +Alan Sill, Neel Smith, Michael Somos, Andrew Sterian, Ryszard Tanas, +Kai Trukenmueller, Torbjorn Vik, Wenguang Wang, Gabe Weaver, Mariusz +Wodzicki + +\texicomment +\begin{thebibliography}{9} +% +\bibitem{Cline} Marshall Cline, \emph{\CXX\ FAQ Lite}, \\ + \URL{http://www.parashift.com/c++-faq-lite/} +% +\bibitem{xcolor} Uwe Kern, \emph{Extending \LaTeX's color facilities: + the \code{xcolor} package}, white paper, Jan.~21, 2007 +% +\bibitem{KnR} Brian Kernighan and Dennis Ritchie, \emph{The \code{C} + Programming Language}, Second Ed., Prentice-Hall Software Series, + 1988 +% +\bibitem{GNUC} Sandra Loosemore, Richard M. Stallman, et.\ al., + \emph{The GNU \code{C}~Library Reference Manual}, GNU Press, + 2004 +% +\bibitem{Prata} Stephen Prata, \emph{\CXX\ Primer Plus}, Sams, 2002 +% +\bibitem{R} Keith Reckdahl, \emph{Using Imported Graphics in + \LaTeX2e}, Version~2.0, white paper, Dec.~15, 1997 +% +\bibitem{GNUCoding} Richard M. Stallman, et.\ al., \emph{The GNU + Coding Standards}, \\ + \URL{http://www.gnu.org/prep/standards/} +% +\bibitem{S} Bjarne Stroustrup, \emph{The \CXX\ Programming Language}, + Special Ed., Addison-Wesley, 1997 +% +\bibitem{Z} Timothy van~Zandt, \emph{PSTricks: PostScript Macros for + Generic \TeX}, Version~0.93a, white paper, Mar.~12, 1993 +% +\end{thebibliography} + +\clearpage + +\printindex + +\end{document} + +\texicommentend |