summaryrefslogtreecommitdiff
path: root/graphics/epix/doc/epix.info
diff options
context:
space:
mode:
Diffstat (limited to 'graphics/epix/doc/epix.info')
-rw-r--r--graphics/epix/doc/epix.info4696
1 files changed, 4696 insertions, 0 deletions
diff --git a/graphics/epix/doc/epix.info b/graphics/epix/doc/epix.info
new file mode 100644
index 0000000000..3b30c42c39
--- /dev/null
+++ b/graphics/epix/doc/epix.info
@@ -0,0 +1,4696 @@
+This is epix.info, produced by makeinfo version 4.9 from epix.texi.
+
+ This is the manual for ePiX, Version 1.2 Copyright (C) 2001, 2002,
+2003, 2004, 2005, 2006, 2007 Andrew D. Hwang
+
+
+File: epix.info, Node: Top, Next: Introduction, Prev: (dir), Up: (dir)
+
+ePiX manual
+***********
+
+This is the manual for ePiX, Version 1.2 Copyright (C) 2001, 2002,
+2003, 2004, 2005, 2006, 2007 Andrew D. Hwang
+
+* Menu:
+
+* Introduction ::
+* Getting Started ::
+* Reference Manual ::
+* Advanced Topics ::
+* Software Freedom::
+* Acknowledgments::
+* Function Index::
+* Concept Index::
+
+ --- The Detailed Node Listing ---
+
+Introduction
+
+* Changes in Version 1.2::
+* Software Dependencies::
+* Installation::
+
+Getting Started
+
+* Running `ePiX'::
+* The Drawing Model::
+* Tutorial::
+* `C++' Basics::
+* Animation::
+* Layout Tricks::
+
+Reference Manual
+
+* File Structure::
+* Picture Size and Aspect Ratio::
+* Color::
+* Scene Attributes::
+* Drawing Attributes::
+* Creating and Drawing Objects::
+* More About `C++'::
+* Attribute Quick Reference::
+
+Advanced Topics
+
+* Hidden Object Removal::
+* Extensions::
+* Programmer's Guide::
+
+
+File: epix.info, Node: Introduction, Next: Getting Started, Prev: Top, Up: Top
+
+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 `PSTricks', `tikz', or `eepic' macros; vector images
+(`eps', `ps', and `pdf'); and bitmapped images and movies (`png',
+`mng', and `gif').
+
+ `ePiX''s strengths include:
+
+ * 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.
+
+ * Ease of use: Figure objects and their attributes are specified
+ by simple, descriptive commands.
+
+ * 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.
+
+ * Power and extendibility: `ePiX' inherits the power of `C++' 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.
+
+ * 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.
+
+ * License: `ePiX' is _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.
+
+
+ `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:
+
+ * Potential user, you may wish to skip immediately to "Software
+ Dependencies" before investing additional time.
+
+ * New user, proceed from here until you have enough understanding
+ to run the software, then experiment with the samples files while
+ reading Chapter *Note chapter:started::, , or return to the
+ manual as needed.
+
+ * More advanced user, browse at will, probably starting with
+ Chapter *Note chapter:ref-man::, .
+
+
+ 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 `C++'
+syntax, is introduced as needed.
+
+* Menu:
+
+* Changes in Version 1.2::
+* Software Dependencies::
+* Installation::
+
+
+File: epix.info, Node: Changes in Version 1.2, Next: Software Dependencies, Prev: Introduction, Up: Introduction
+
+1.1 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 *Note
+section:software_deps::, .
+
+
+
+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).
+
+ * (Mandatory) The global variable tix in a `flix' file must be
+ manipulated through the function tix().
+
+ * (Mandatory) The command `use_pstricks()' is obsolete. PSTricks
+ output is obtained systematically as an output format.
+
+ * (Mandatory) Deprecated "aliases" no longer exist: `triple' (for
+ the `P' class), `D' (for `Deriv'), and `I' (for `Integral').
+ Lowercase trig function names conflicted with the standard
+ namespace and have been removed.
+
+ * (Mandatory) Geometric object commands (`circle', `plane',
+ `segment', and `sphere'), which formerly created class objects,
+ now perform drawing just as `ellipse', `line', `rect', etc., do.
+ The classes are available with capitalized names (`Circle',
+ etc.).
+
+ * (Mandatory) Camera orientation is controlled with functions
+ named `tilt', `pan', and `roll'; each rotates the camera about
+ an axis through the viewpoint, not through the target.
+
+ * (Recommended) The global size variables x_min, x_max, y_min,
+ y_max, x_size, and y_size should be replaced by the function
+ calls xmin(), etc. (No underscores.)
+
+ * (Suggested) The camera may be accessed through the function
+ `cam()'.
+
+ * (Suggested) The size and bounding box are given in one command,
+ such as `picture(P(-1,0), P(1,1), "4x3in")'. The old syntax will
+ be retained indefinitely.
+
+
+
+
+ * Output is cleanly separated from the internal representation.
+ Figures may be written with a choice of macros--`PSTricks',
+ `tikz', and `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.
+
+ * Colors are a manipulable data type, available in RGB, CMY, CMYK,
+ and Gray models. `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.
+
+ * 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.\ `PSTricks' or `tikz') should be used for
+ efficiency. Filled regions are implemented as fine hatching in
+ `eepic'.
+
+ * An `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.
+
+ * `ePiX' 1.2.x performs page layout. Sub-figures may be manipulated
+ flexibly. The sample files give several applications.
+
+ * 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.
+
+
+
+File: epix.info, Node: Software Dependencies, Next: Installation, Prev: Changes in Version 1.2, Up: Introduction
+
+1.2 Software Dependencies
+=========================
+
+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 `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; `dvi'; PostScript, `pdf' or `eps'; and if desired, to
+a bitmapped image or movie. Four shell scripts--`epix', `laps',
+`elaps', and `flix'--automate the various file format conversions.
+
+ `ePiX' consists of a `C++' library, header, and shell scripts, and
+requires GNU `bash' and a compiler _for normal use_. For complete
+functionality, you need `g++' (Version 3.2 or later), `bash', a text
+editor (`ePiX' works particularly well with `emacs'), a `LaTeX'
+distribution, `Ghostscript', `gv' (or your favorite PS/PDF previewer),
+and `ImageMagick'. GNU `grep' and `sed' are good to have. You may need
+additional "developer packages" (`binutils', `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 `emacs' mode allows you to write, compile, and view
+`ePiX' figures without leaving `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.
+
+
+
+Cygwin can be used to run `ePiX' under Windows. Download `setup.exe'
+from `http://www.cygwin.com', then install the packages you need. The
+following are recommended, and sufficient for the actions described in
+this manual.
+
+(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
+
+
+
+File: epix.info, Node: Installation, Prev: Software Dependencies, Up: Introduction
+
+1.3 Installation
+================
+
+`ePiX' is distributed over the World-Wide Web as source code. Packages
+may be found at `http://mathcs.holycross.edu/~ahwang/epix/ePiX.html'
+The latest stable release is also on the CTAN mirrors, in the
+`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:
+
+ tar -zxvf epix-x.y.z.tar.gz
+ tar -jxvf epix-x.y.z.tar.bz2
+ (`x.y.z' is the version number) or, if your `tar' doesn't do
+decompression,
+
+ gunzip -c epix-x.y.z.tar.gz | tar -xvf -
+ bzcat epix-x.y.z.tar.bz2 | tar -xvf -
+ `cd' to the source directory, `epix-x.y.z'. The `INSTALL' file
+contains detailed installation instructions. If you're impatient, the
+short of it is `./configure [--options]; make; make install'. Run
+`./configure --help' for a list of options.
+
+ By default, `ePiX' installs in subdirectories of `/usr/local'; if
+you want to install elsewhere, supply `./configure' with the
+appropriate `--prefix'. You may also want to consult `POST-INSTALL' for
+information on setting your `PATH' variable so your shell can find
+`ePiX'. The manual and sample files are in `/usr/local/share/doc/epix'.
+
+
+
+There are two mailing lists, one for user questions, one for
+development discussion. Please visit
+`http://savannah.nongnu.org/mail/?group=epix' to subscribe.
+
+
+File: epix.info, Node: Getting Started, Next: Reference Manual, Prev: Introduction, Up: Top
+
+2 Getting Started
+*****************
+
+This chapter describes the basics of creating figures in `ePiX' for
+readers familiar with `LaTeX' but completely new to `C++'. No detailed
+knowledge of `C++' is needed to use `ePiX', only a bit of grammar that
+is easily absorbed by example.
+
+ Section *Note section:running::, describes the commands (shell
+scripts) comprising `ePiX', and explains how to set up a graphical
+environment using standard *nix programs. Section *Note
+section:overview::, briefly describes figure creation. Section *Note
+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.
+
+* Menu:
+
+* Running `ePiX'::
+* The Drawing Model::
+* Tutorial::
+* `C++' Basics::
+* Animation::
+* Layout Tricks::
+
+
+File: epix.info, Node: Running `ePiX', Next: The Drawing Model, Prev: Getting Started, Up: Getting Started
+
+2.1 Running `ePiX'
+==================
+
+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, `laps', `epix', `elaps', and `flix'. Each script has a
+preferred extension for its input files, and is invoked with a command
+of the form
+
+ <script> [options] <input file(s)>
+ Often, no options are necessary. `<script> --help' describes
+`<script>''s options.
+
+ 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 <TAB> completion, under which a shell,
+based on what has been typed so far, automatically fills in a command
+when the <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
+`epix' <TAB> prints only names of `epix' input files. To use this
+feature, you must install Ian MacDonald's `bash completion' package.
+The `INSTALL' and `POST_INSTALL' files contain details.
+
+
+
+`laps' performs `LaTeX' to PostScript/PDF conversion, and is
+independent of the rest of `ePiX'. By default, `laps' invokes `LaTeX'
+and `dvips'. The option `--pdf' creates a PDF file by post-processing
+the PostScript with `ps2pdf'. Other `TeX'-family processors
+(`pslatex', `pdftex', etc.) may be used instead of `LaTeX' by invoking
+`laps' with an appropriate option.
+
+
+
+`epix' compiles an input file into a `LaTeX' picture. The input file
+should have extension `xp' (for eXtended Picture). Jay Belanger's
+`emacs' mode is Highly Recommended; the installation procedure can be
+found in the `POST_INSTALL' file. When this mode is active, `emacs'
+automatically inserts a preamble template when a new `xp' file is
+created. In addition, you can peruse `ePiX''s info file, or format,
+compile, and preview files, all from within `emacs'.
+
+ Output files from the script `epix' have extension `eepic', after
+Conrad Kwok's enhancements to the `LaTeX' picture environment. In
+Version 1.2, however, an output file need not contain `eepic' macros at
+all.
+
+ An output file is `input' directly into a `LaTeX' document whose
+preamble contains appropriate `usepackage' lines. Rotated text
+requires the `rotating' package.
+
+
+
+`elaps' creates stand-alone vector images (`eps' or `pdf') from `epix'
+input files or `eepic' figures, even those not produced with `epix'.
+`elaps' automatically loads the `LaTeX' packages needed for features
+described in this manual. Additional `LaTeX' packages and `dvips'
+options may be specified on the command line.
+
+
+
+`flix' creates bitmapped images and movies, Section *Note
+section:animation::, . Input files should have extension `flx', and
+must contain a valid `epix' header as well as additional code. Jay
+Belanger's `emacs' mode facilitates creation of `flix' files.
+
+
+File: epix.info, Node: The Drawing Model, Next: Tutorial, Prev: Running `ePiX', Up: Getting Started
+
+2.2 The Drawing Model
+=====================
+
+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.
+
+ `ePiX''s drawing model behaves similarly. A `picture' command sets
+the _canvas_ (or logical drawing area, a Cartesian rectangle) and the
+true size of the final figure. A `begin' command initializes the
+"virtual paper" for drawing. Subsequent _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 _style declaration_ which remain in
+effect until superseded. Finally, an `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 `len' argument is
+either a number (representing a length in `pt') or a double-quoted
+string containing a number and a two-letter `LaTeX' length unit, such
+as `"1.5pt"' or `"6cm"'. A `color' argument is a named primary
+(`Red()', `Cyan()', `White()', etc.), or a `Color' specified by
+densities (`RGB(r,g,b)', `CMY(c,m,y)', etc.)
+
+ * Fill color: `fill(color)', `nofill()'.
+
+ * Line color and width: `plain([color])', `bold([color])'.
+
+ * Text size: `font_size([size])', returns to `normalsize' if no
+ argument is given.
+
+
+ \noindent A complete list of style commands is found in Section
+*Note section:quickref::, , starting on page *Note section:quickref::.
+
+ To handle three-dimensional scenes, a `camera' performs point
+projection from a selected spatial location to the canvas. As a user,
+you'll need to control relatively few of the `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
+`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 z axis from a large distance, giving orthogonal projection on the
+(x,y) plane. When the `camera' is moved, the z axis points vertically
+up on the page.
+
+
+File: epix.info, Node: Tutorial, Next: `C++' Basics, Prev: The Drawing Model, Up: Getting Started
+
+2.3 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 `C'/`C++', should be mostly self-explanatory. One-line
+comments begin with the string "//".
+
+ To use the sample files interactively, you'll need working software:
+`bash', `emacs', `ePiX', `g++', `gv', and a running X server. To
+complete your "GUI", start `gv' and select "Watch file" from the "State"
+menu. The loaded file will update automatically when it changes.
+
+ Create a "scratch" directory, `cd' into it, and run the command
+
+ tar -zxf /usr/local/share/doc/epix/sample_src.tar.gz
+ (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 `README' file serves as a table
+of contents.
+
+ Open a sample file in `emacs', compile it from the drop-down menu
+(or with the keyboard command), then open the `EPS' file in `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.
+
+
+
+The first sample, `hello.xp', contains code needed to specify the
+figure's size, followed by the classic greeting. The `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.
+
+/* -*-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 ----
+}
+
+
+[Image]
+
+ * Change the color and width of the border. (`RGB(r,g,b);' creates
+ an RGB color, CMY colors are analogous. Named primaries are
+ available. The densities should be between 0 and 1 for
+ "expected" behavior.)
+
+ * Add `backing(Cyan());' after the `border' command.
+
+ * Put the command `crop_ellipse();' before the `border' command.
+ Permute the `crop_ellipse' command with the `border' and
+ `backing' lines, and note how the attribute (`crop') affects
+ objects (`border', `backing').
+
+
+
+
+Our next file uses simple objects to draw a 2-D house-and-sun scene.
+
+
+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();
+}
+
+
+[Image]
+
+ * Add declarations such as `bold(RGB(1,0.9,0.5))' or
+ `fill(Yellow())' to color the scene. (Color and filling are
+ orthogonal attributes.)
+
+ \noindent The sample file `house.flx' uses loops to draw gradient
+fills of the lawn, sky, and sun, and animates a sunset.
+
+
+
+Plotted functions must be defined in the "preamble", before `main'.
+"High-level" elements--coordinate axes and grids, axis labels, and
+graphs--are drawn with mnemonically-named commands.
+
+// 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();
+}
+
+
+[Image]
+
+ * Define and plot some different functions; adjust the bounding
+ box as necessary. (Use repeated multiplication for polynomials.
+ The `polarplot' command graphs r=f(\theta).)
+
+ * Change the arguments to `h_axis_labels'. The first specifies the
+ number of intervals to label; the second gives the label offset
+ in `pt'. The last puts each label below (`b') its Cartesian
+ location.
+
+
+
+
+Functions of two or three variables are defined just like functions of
+one variable, but for plotting the return type must be a point (`P'),
+not a real number (`double'). The `domain' class specifies the set of
+inputs to plot.
+
+
+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();
+}
+
+
+[Image]
+
+
+
+A function can be defined by an arbitrary algorithm, and a `domain' may
+be used to plot a family of functions for several values of one
+variable.
+
+
+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();
+}
+
+
+[Image]
+
+
+
+Page layout can be composed from sub-pages with `screen' objects. In
+the loop body below, objects are added to the "active" `screen', then
+`inset' into the "canvas", the screen representing the entire figure.
+
+
+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();
+}
+
+
+[Image]
+
+
+File: epix.info, Node: `C++' Basics, Next: Animation, Prev: Tutorial, Up: Getting Started
+
+2.4 `C++' Basics
+================
+
+An `ePiX' source file is a `C++' program. If you've successfully
+modified and compiled the sample files, you know enough `C++' to use
+`ePiX'. In the author's experience, `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 _The `C' Programming Language_, second edition
+`KnR'.
+
+
+
+Jay Belanger's `emacs' mode for `ePiX' inserts a file template when an
+empty buffer is opened with the extension `xp'. This section explains
+the purposes served by the template. A few additional remarks may help
+you avoid basic syntax pitfalls.
+
+ A `C++' file consists of "statements", analogous to ordinary
+sentences. Common types include _declarations_ (which "register" a
+function, variable, or type name with the compiler), _definitions_
+(which assign meaning to declared names), and _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
+
+#include "epix.h" // N.B. pre-processor directive, no semicolon
+using namespace ePiX;
+ The first line is analogous to a `LaTeX' `usepackage' command: It
+loads the contents of the "header" file `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 `label'
+command is actually known to the compiler as `ePiX::label'. The second
+line above tells the compiler to apply the prefix tacitly.
+
+
+
+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 `double' (double-precision floating
+point number), `P', and `int'. The name of a variable may consist
+(only) of letters (including the underscore character) and digits, and
+must begin with a letter:
+
+my_var, var2, MY_var, aLongVariableName; // valid
+my-var, 2var, \v@@riable, $x, ${MY_VARIABLE}; // not valid
+ 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 `const', `true', `double', `class', or `public') and names that
+begin with an underscore.
+
+ A function accepts "arguments" and "returns a value". To define a
+function in `C++', 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
+
+double f(double x)
+{
+ return sqrt(1-x*x);
+}
+ specifies the `double'-valued function f of one `double' variable
+defined by the formula f(x)=\sqrt1-x^2.
+
+
+
+`C++' has two types of comments. `C'-style comments, which may span
+several lines, are delimited by the strings `/*' and `*/'. One-line
+comments, analogous to the `LaTeX' `\%', are begun with `//'. A
+one-line comment may appear within a multi-line comment, but a
+`C'-style comment may not; the compiler will mistake the first `*/' it
+encounters as the end of the current multi-line comment.
+
+
+
+All the "action" in a `C++' program occurs inside the special function
+`main'. Running a compiled `C++' program is viewed by the operating
+system as calling the program's `main' function. The return value (an
+`int') is the program's exit status. The contents of the output file
+start with `begin()' and terminate with `end()'. Intervening
+statements constitute the _body_ of the file.
+
+ In `C++', a function may not be defined inside another function.
+Thus, variables may be defined inside `main', but functions cannot be.
+
+
+
+In `C++', a `string' is a sequence of characters. Most `string's in
+`ePiX' input files are _literals_, double-quoted `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 "\n" (newline) and "\t" (<TAB>). Unlike
+`LaTeX', `C++' does not require a space to separate an escape sequence
+from following text; the string "\\textwidth" literally represents a
+`LaTeX' command, while "\textwidth" is read "`TABextwidth'" by the
+compiler.
+
+ Though not commonly needed, raw text can be printed to the output
+file. The functions `write', `pre_write', and `post_write' accept
+`string' arguments. `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' `figure'
+environment (with caption and label) can be produced by an `ePiX' file,
+Figure *Note fig:captioned::, .
+
+
+#include "epix.h"
+using namespace ePiX;
+
+int main()
+{
+ picture(P(-1,-1), P(1,1), "10cm x 3in);
+ begin();
+ pre_write("\@float Figure[hbt]"); // comes before the picture
+
+ post_write("\@caption{A \@code{LaTeX}\ figure.}"); // and after
+ post_write("\@end float");
+
+ < ... other ePiX commands ... >
+ write("%% A comment near the end, but inside the picture.");
+ end();
+} // End of main()
+
+Figure: Generating a self-contained figure in `ePiX'.
+
+
+
+An algorithm's behavior usually depends on internal state. A
+_conditional statement_ causes blocks of code to be executed according
+to criteria. A _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.
+
+
+File: epix.info, Node: Animation, Next: Layout Tricks, Prev: `C++' Basics, Up: Getting Started
+
+2.5 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 `flix' automates the process of compiling a suitable input
+file into a collection of `png's and assembling these frames into a
+`mng' or `gif' animation. ImageMagick is the image-handling engine.
+
+ A `flix' file is an `epix' file with two restrictions:
+ * The `double' variable `tix()' is used as "clock".
+
+ * `main' accepts two command line arguments and sets `tix()'
+ accordingly.
+ Jay Belanger's `emacs' mode recognizes the file extension `.flx' and
+inserts template code if an empty buffer is opened. Creation of `flix'
+files is as easy as creation of `epix' files. The `samples' directory
+contains a handful of `flix' files that may be consulted for ideas.
+
+ By default, `flix' creates movies with 24 frames, in which `tix()'
+runs from 0 to 1, and animates at 0.08 sec/frame. These and other
+parameters can be changed with command-line options.
+
+ A "typical" `.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, `elaps' can be run on a `flix' file.
+`elaps' runs in a fraction of the time, and if `elaps' can't produce a
+viewable image, `flix' will surely fail. While running, `flix' prints
+a progress bar counting the number of `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 `convert' utility
+assembles the movie.
+
+
+File: epix.info, Node: Layout Tricks, Prev: Animation, Up: Getting Started
+
+2.6 Layout Tricks
+=================
+
+
+
+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.
+
+
+
+The sample files `lorenz.xp' and `twisted_cubic.xp' use page layout to
+draw crossed-eyes stereograms. For each frame, create and activate a
+`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.
+
+
+
+The sample files `cube.flx' and `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.
+
+
+
+Either form of stereogram can be animated in a `.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 `flix',
+debug the scene with `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.
+
+
+
+`ePiX' can place external images into a figure, similarly to Rolf
+Niepraschk's `overpic' package. You provide the Cartesian center point,
+the file name, and optionally the true height and/or width of the image:
+
+ label(P(a,b), "\\includegraphics[width=w,height=h]{file}");
+ This effect requires the `graphicx' package. When compiling a
+stand-alone graphic containing an external image, you must specify the
+`graphicx' package on the command line: `elaps -p graphicx <file>'
+
+
+File: epix.info, Node: Reference Manual, Next: Advanced Topics, Prev: Getting Started, Up: Top
+
+3 Reference Manual
+******************
+
+This chapter details `ePiX''s capabilities, discussing attributes and
+data types, and listing available commands in the form
+
+ label(P posn, [P offset], string text, [align]);
+ circle(P ctr, double rad=1, normal=P(0,0,1));
+ As in Chapter *Note chapter:started::, , function arguments are given
+by type (`P', `double', `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 `[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 `rad' argument of the `circle' command is omitted, the
+`normal' argument _must_ be omitted as well.
+
+ In an input file, only an argument's value is given, not the type:
+
+ label(P(0,0), P(0,-4), "Hello world", b);
+ circle(P(0,-0.25), sqrt(2)); // use default normal
+
+ Generally, `len' signifies either a number (representing a length in
+`pt') or a double-quoted string containing a number and a two-letter
+`LaTeX' length unit, such as `"1.5pt"' or `"6cm"'. `color' represents a
+`Color' object constructed from a named primary (`Blue()',
+`Magenta(0.7)', etc.), a color specification (`RGB(r,g,b)',
+`CMY(c,m,y)', etc.), or an operator applied to an existing `Color'.
+
+* Menu:
+
+* File Structure::
+* Picture Size and Aspect Ratio::
+* Color::
+* Scene Attributes::
+* Drawing Attributes::
+* Creating and Drawing Objects::
+* More About `C++'::
+* Attribute Quick Reference::
+
+
+File: epix.info, Node: File Structure, Next: Picture Size and Aspect Ratio, Prev: Reference Manual, Up: Reference Manual
+
+3.1 File Structure
+==================
+
+An `ePiX' input file constitutes a short `C++' program. When this
+program is compiled and run by one of the shell scripts, it creates a
+figure file suitable for inclusion in `LaTeX'.
+
+ Like a `LaTeX' document, an `ePiX' file contains a _preamble_, which
+sets up a drawing environment, and a _body_, which contains actual
+figure-generating commands. The minimal file has the form
+
+#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
+}
+ `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 `begin()' and `end()'. Function definitions
+must come in the preamble, before `main()'. Data definitions may appear
+in the preamble or body.
+
+
+
+The `end()' command writes the output file to `stdout', using `eepic'
+macros by default. The shell scripts redirect `stdout' to an
+appropriate disk file.
+
+ The attribute-setting command `pst_format()' causes the output file
+to be written using `PSTricks' macros when `end' is called. Similarly,
+`tikz_format()' causes the file to be written using `tikz' macros, and
+`eepic_format()' causes the file to be written using `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 `epix', `elaps', or
+`flix' with one of the options `--pst', `--tikz', or `--eepic' is
+tantamount to issuing a `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
+
+ print_eepic("file.tex");
+ writes the figure to the named file using `eepic' macros. Analogous
+commands exist for the formats `pst' and `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.
+
+
+File: epix.info, Node: Picture Size and Aspect Ratio, Next: Color, Prev: File Structure, Up: Reference Manual
+
+3.2 Picture Size and Aspect Ratio
+=================================
+
+The `picture' command specifies a figure's logical and true sizes. In
+the "minimal file" snippet above, the _canvas_ is the Cartesian
+rectangle [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 `picture''s third
+argument, a "size `string'" such as "4cm x 1in", containing a number
+and optional `LaTeX' length unit, an `x', another number, and a
+mandatory length unit. Spaces may be used for legibility. The
+mandatory length unit becomes the `LaTeX' `unitlength'. The argument
+"4cm x 1in" creates a picture 4 cm wide and 1 in high, but internally
+converts 4 cm to inches. Recognized length units are `pt' (points, the
+default), `cm' (centimeters), `in' (inches), `mm' (millimeters), `pc'
+(picas), and `bp' (big points). (`1in = 2.54cm = 72bp = 72.27pt', `1pc
+= 12pt'.)
+
+ The logical and true sizes may be defined separately with the
+commands
+
+ bounding_box(P(a1,b1), P(a2,b2));
+ picture(n1, n2);
+ unitlength(len); // len a length string, not a double
+ One way or another, the logical and true dimensions _must_ have
+positive values when the `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 `offset' command
+accepts two `double' arguments or a size `string' and shifts the page
+location accordingly. The command `offset("0.25 x -0.5cm")' shifts the
+picture right 0.25 cm and down 0.5 cm. If the `unitlength' is 1 cm,
+the command `offset(0.25, -0.5)' has the same effect.
+
+ A non-zero `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 `dvips' may crop according to rules of its own.
+
+ The canvas's corners are `(xmin(),ymin())' and `(xmax(),ymax())',
+while its width and height are `xsize()' and `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.
+[Image]
+
+ 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.
+
+
+File: epix.info, Node: Color, Next: Scene Attributes, Prev: Picture Size and Aspect Ratio, Up: Reference Manual
+
+3.3 Color
+=========
+
+`ePiX' provides a `Color' data type. Four models are implemented:
+`RGB', `CMY', `CMYK', and `Gray'. A `Color' holds primary color
+"channels", each carrying an intensity between 0 (no color) and 1 (full
+saturation). "No color" means black in `RGB' and `Gray', white in
+`CMY(K)'. `RGB', `CMY', and `CMYK' colors are written to the output
+file as commands in the corresponding model. `Gray' shades are written
+in `RGB'.
+
+ Operations on red-green-blue colors are described below.
+Functionally, colors are converted to `RGB', operated upon, then
+converted back to the original model. Conversions are as described in
+Uwe Kern's `xcolor' manual `xcolor'.
+
+
+
+Each color model has a "constructor" creating a color of specified
+densities. The `RGB' and `CMY' models have named "primary"
+constructors; the density argument is optional and defaults to 1.
+
+ // 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);
+
+
+ // 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)
+ Each `CMY' constructor has a corresponding `CMYK' function, e.g.\
+`CyanK()' or `CMYK_White()'.
+
+ Though color densities lie between 0 and 1, `ePiX''s primary color
+constructors take arguments mod 4, viewed as elements of [-2,2].
+Consider `Red(d)', "red with density d". For integer values of d, the
+constructor has the following meanings: `Red(0)' is black, `Red(1)' is
+red, `Red(2)'=`Red(-2)' is white, and `Red(-1)' is anti-red, or cyan.
+For non-integer d, the constructor interpolates between the bracketing
+integer values, Figure *Note fig:densities::, . Other primary
+constructors work analogously.
+
+
+[Image]
+
+Figure[hbt]
+
+ Let \delta:[-2,2]\to[0,1] be the piecewise-linear function that
+converts real numbers to primary color densities, \clip:R\to[0,1] the
+clipping function. The non-primary constructor `RGB(r, g, b)' computes
+the density of the red channel as
+\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".
+
+ Colors possess an "alpha-channel" for transparency. Except as
+supported by the output format, this feature is a stub.
+
+
+
+Colors can be scaled, inverted, blended, superposed, and filtered. In
+the code below, `tint' is a `Color'. The effect of each operation is
+described in the `rgb' model; the visual result is the same in all
+models.
+
+ 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
+ Except for `filter', these operators modify their object. `filter'
+simulates the effect of viewing `col' through a transparent sheet of
+`tint', and returns a new `Color' object having the same model as
+`tint' without modifying `tint' itself.
+
+
+File: epix.info, Node: Scene Attributes, Next: Drawing Attributes, Prev: Color, Up: Reference Manual
+
+3.4 Scene Attributes
+====================
+
+Objects in a scene sit in 3-dimensional space. A _camera_ maps objects
+to the _active screen_. The active `screen' may, in turn crop its
+contents. Each drawing command creates an object, "photographs" it, and
+adds the image to the active `screen'. This section describes the
+`Camera' and `screen' classes and a few associated concepts.
+
+
+
+By default, angles are measured in `radian's. Two other angular modes
+are available: `degrees' and `revolutions'. The angular mode is set
+with a named command, `radians()', `degrees()', or `revolutions()'. The
+current angular mode affects all trigonometric functions and operations.
+
+
+
+Three-dimensional scenes are drawn on flat paper by applying a
+mathematical transformation. By default, `ePiX' uses _point
+projection_, the technique used by art students when they trace on a
+window with grease pencil, Figure *Note fig:camera::, .
+
+
+[Image]
+
+Figure[hbt]
+
+ `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 _body_ (data that
+determines the position and orientation of the camera), a _lens_ (the
+actual mapping to the screen plane), and a _filter_ (a color through
+which the scene is viewed).
+
+
+
+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 _sea_, _sky_, and _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 _viewpoint_, the camera's
+spatial location. The _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 _range_.
+The _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.
+
+
+
+A _lens_ maps the world to the screen. `ePiX' comes with four lenses:
+_shadow_ (the default), _orthogonal_, _fisheye_, and _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.
+
+ An input file normally uses a single camera, so a global object named
+`camera' is defined automatically. At the start of a figure, the
+`camera' looks down on the (x_1,x_2)-plane from a distant point on the
+x_3-axis. The resulting view, essentially projection along the axis, is
+suitable for 2-dimensional figures.
+
+ The `camera' is manipulated similarly to a real camera:
+
+ 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
+ Explicitly setting the viewpoint or target makes the sky vector
+parallel to the projection of the x_3 axis when possible; otherwise the
+x_2-axis is used. Setting the range or focus moves the `camera'
+parallel along the eye line. Each command re-sizes the image; note that
+increasing the focus _enlarges_ the image. The three rotation
+operations fix the viewpoint, but only roll fixes the target.
+
+
+
+The `camera' has a _filter_ through which all scene `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 `Neutral' color, for which filtering has no effect at
+all. The `camera''s default filter is `Neutral'. In addition, each
+color model has a _neutral_ representative, `RGB_Neutral', etc. Passing
+`Color's through a neutral filter preserves their appearance but
+converts them to the neutral `Color''s model.
+
+ Filtering can be used to "split" a `Color' into primary
+constituents. For `RGB' channels, the primaries themselves are suitable
+filters. For `CMYK' channels, there are special _process_ filters,
+named C_Process, etc.
+
+ 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?
+
+
+
+
+Two operations handle elements lying far from the target. _Cropping_
+culls elements based on their screen location, and is described later.
+_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.
+
+ 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
+ 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.
+
+ 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
+ Like `clip_restore', the `clip_box' and `clip_to' commands remove all
+user-specified half spaces.
+
+
+
+By default, drawing occurs in the Cartesian coordinate system of the
+`canvas'. However, insets and subfigures are most naturally composed in
+"local" coordinates, then placed into their final location as a unit, a
+process called _layout_. `ePiX' implements layout with the `screen'
+class.
+
+
+
+A `screen' is a Cartesian plane containing a distinguished coordinate
+rectangle, its _bounding box_. The `canvas' of a figure is a `screen',
+as is the internal representation of the printed page. At any point of
+a file body, some `screen' is _active_, or "open for drawing". A new
+`screen' is created from a pair of opposite corners, but is not used
+until explicitly activated.
+
+ 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
+
+ The `canvas' is automatically drawn at the `end' of the input file.
+The contents of other `screen's must be incorporated into the `canvas'
+explicitly with an `import' or `inset' command. `import' affinely
+scales the bounding box of the "child" `screen' to the `canvas'. `inset'
+specifies corners in the "parent" where the child is placed.
+
+ 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
+
+
+
+The portion of a `screen' enclosed by a specified rectangle can be
+_extracted_. Each of the commands
+
+ subfig.extract(P sw, P ne);
+ canvas().extract(P sw, P ne);
+ returns the `screen' having stated corners and containing part of
+`subfig' or the `canvas', respectively. Elliptical and diamond-shaped
+portions of a `screen' may be extracted. The contents occupy the
+ellipse or diamond inscribed in the given rectangle.
+
+ subfig.extract_ellipse(sw, ne);
+ canvas().extract_diamond(sw, ne);
+ The `screen' returned by `extract' (or its variants) may be used just
+like a manually-constructed `screen', for example to construct a
+magnified inset.
+
+
+
+On occasion, it is necessary to draw at known page size, independently
+of the unit length. For 2-dimensional drawing in the (x_1,x_2)-plane
+with the `camera' in its default location, the coordinates (horizontal,
+vertical, or both) of a `screen' may be interpreted as true pt offsets
+relative to a specified point rather than as Cartesian coordinates.
+
+ inlay(subfig, P loc);
+ inlay_horizontal(subfig, loc);
+ inlay_vertical(subfig, loc);
+ Each command maps the origin of `subfig' to the specified location in
+the active `screen'. The first performs affine scaling so that one
+Cartesian unit in `subfig' maps to one true pt on the page. The second
+and third commands perform this scaling only in the named direction.
+
+ The `inlay' functions are suitable only for 2-dimensional effects.
+For 3-dimensional true-size drawing, the function `pt_to_screen'
+converts a true length of 1 pt into Cartesian coordinates in the active
+`screen'. For example, the command `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 `canvas', and _only_ when drawing in a `screen' imported to the
+`canvas' at "true Cartesian" size (one `screen' unit maps to one
+Cartesian unit in the `canvas'). In other situations, the true size
+coordinate(s) will be scaled by additional affine transformation(s).
+
+
+
+A `screen' has a _crop mask_: rectangular (default), elliptical, or
+diamond-shaped. If cropping is switched on in the active `screen',
+added elements are cropped to the crop mask. For example, cropping by
+the default crop mask in the `canvas' ensures the figure lies inside
+the printed region allocated by `LaTeX'.
+
+ The `crop' commands below affect the active `screen' only. Cropping
+is not a "global" attribute, but must be set or unset explicitly for
+each `screen'. By default, cropping is switched off.
+
+ 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
+ Normally the crop mask is inscribed in the `screen''s bounding box.
+The commands `crop_diamond' and `crop_ellipse' also accept a pair of
+`P' arguments, which are treated as corners of the crop box.
+
+ The active `screen' may be decorated with a `border' (outline of
+specified color and line width) and `backing' (solid fill color). The
+crop mask determines the shape of the `border' and `backing'.
+
+ border(color, len);
+ backing(color);
+ Identically-named member functions can be applied to an arbitrary
+`screen' whether or not it is active:
+
+ scr.crop_rectangle().backing(Blue(1.8));
+ canvas().crop();
+
+
+
+A _plane affine map_ has the form T(x) = Ax+b for some invertible
+2\times2 matrix A and a constant vector b. `ePiX''s `affine' class
+allows affine maps to be built and applied to `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 (1,0), (0,1), and (0,0) to `pt1', `pt2', and `pt0',
+respectively.
+
+ affine af(P pt1, P pt2, P pt0=P(0,0));
+ To emphasize, the arguments are locations, not displacements, and the
+image of the origin comes last. There is also a `void' constructor
+(taking no arguments) which returns the identity map.
+
+ To facilitate construction of affine maps, an existing `affine' may
+be post-composed with a variety of "elementary" affine transformations.
+In the commands below, `th' is an angle (in current units), `sc' is a
+non-zero `double', and `ctr' is a point fixed by the composing
+transformation. In each command, `ctr' defaults to (0,0).
+
+ 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
+ A non-invertible `affine' can be created _only_ by shearing or scaling
+with an extremely large or extremely small argument, or by supplying
+three collinear points to the constructor. Calling `invert' on a
+non-invertible map merely issues a warning and performs no action.
+
+ An `affine' may be applied to a `screen''s current contents. The
+`screen' class has eight member functions (`shift' through `shear')
+with syntax identical to the affine map functions. In addition, an
+arbitrary `affine' may be applied to a `screen':
+
+ scr.shift(arg); // shift scr's contents by arg; etc.
+ scr.apply(f); // apply f to scr's contents
+ To apply a composition of several maps to a `screen', it's best to
+build an `affine' map by composition, then `apply' the map. Composing
+`affine's is cheap; `apply'ing an `affine' is costly in proportion to
+the number of elements in the `screen'.
+
+ Applying an `affine' to a `screen' has no effect on the bounding
+box, `border', or `backing', and may move elements outside the bounding
+box even if cropping is active. To ensure a `screen''s contents lie
+inside the bounding box, `crop' the `screen' _after_ `apply'ing the
+`affine'(s).
+
+ The sample file `inverse.xp' uses `affine' maps to depict branches
+of inverse functions in one variable, `symmetry.xp' depicts the
+permutation group S_3 by its action on a regular hexagon.
+
+
+File: epix.info, Node: Drawing Attributes, Next: Creating and Drawing Objects, Prev: Scene Attributes, Up: Reference Manual
+
+3.5 Drawing Attributes
+======================
+
+`ePiX' maintains drawing states for filled regions, paths, and text
+objects.
+
+
+
+Filling is either on or off. When filling is active, closed paths are
+filled with the current _fill color_.
+
+ fill(); // turn filling on
+ fill(color); // turn filling on, specify color
+ nofill(); // turn filling off, same as fill(false);
+
+
+
+Paths and borders of filled regions are drawn with two _pen_s, each
+described by color and line width. The _line pen_ draws all path-like
+objects. The _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.
+
+ pen(len); // set line pen width
+ pen(color); // set line color, keep width
+ pen(color, len); // set color and width
+ As usual, `len' may be either a length string or a `double',
+interpreted as a width in `pt'. There are `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:
+
+ plain([color]); // 0.4pt
+ bold([color]); // 0.8pt
+ bbold([color]); // 1.6pt
+
+
+
+By default, path-like objects are drawn with solid lines. Dashed,
+dotted, and free-form path style patterns are also available. (The
+`base' underlayer is always solid.) The page length of a pattern
+defaults to 12 pt, but can be set.
+
+ line_style(string);
+ dash_size(len=12);
+ 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.
+[Image]
+
+ For brevity and uniformity, named commands are provided.
+
+ solid(); "-" dashed(); "- -" dotted(); " . "
+ A sequence of n dashes, spaces, and dots corresponds to a dash/dot
+pattern in an interval divided into n subintervals of equal length. If
+the ith character is a dash or space, the ith subinterval is drawn
+solid or empty, respectively. If the ith character is a period, a dot is
+placed at the midpoint of the ith subinterval.
+
+ This pattern is applied to a path-like object as follows. The page
+length of each edge is divided by the current `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 `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 *Note section:extensions::, for guidance.
+
+
+
+Two types of textual element may appear in a file: _labels_ (text
+boxes) and _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 _alignment point_ is attached to each label, and
+Cartesian coordinates position the alignment point.
+
+
+
+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:[Image]
+
+ The alignment point may be _offset_ manually by a specified number
+of `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.
+
+ label(P posn, P offset, string msg, [align]);
+ label(posn, msg);
+ The first two components of the `offset' argument are numbers of `pt'
+to shift the alignment point right and up. The optional `align'
+argument may be one--or an appropriate pair--of `t', `b', `r', or `l'
+(top, bottom, right, left), or `c' (center). These alignment options
+specify the position of the label _relative to the Cartesian location_
+`posn', namely they work _opposite_ to the way they work in `LaTeX'.
+[Image]\qquad [Image]
+
+ The `msg' argument is usually a snippet of `LaTeX' code enclosed in
+double quotes. `C++' treats "\" as an escape character, so a double
+backslash is needed in the source to get a single backslash in the
+output. For example,
+
+ label(P(0,0), P(2,-1), "$\\rho = \\sin\\theta$", br);
+ positions an alignment point `2pt' right and `1pt' below the
+(Cartesian) origin, and typesets the equation \rho=\sin\theta below and
+to the right.
+
+ Labels can be rotated; the (counterclockwise) angle is set in current
+angle units with the command `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
+`rotating' package. `elaps' automatically loads this package.
+
+ An `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 `screen' will have
+an `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 `inverse.xp' illustrates the effect of
+affine maps on labels.
+
+
+
+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
+
+font_size("Large");
+font_face("sc");
+ The argument of font_size is a valid `LaTeX' size. If no argument is
+given, `normalsize' is understood. font_face accepts a two-letter
+string, appended to the string "`text'" to give a `LaTeX' font
+declaration command ("`textsc'" above). Finer-grained control is
+accomplished by placing `LaTeX' commands into the label text.
+
+
+
+Each label command has a corresponding "mask" version (`masklabel')
+that draws an opaque rectangle under the label text. The mask size
+exceeds the label's size by an amount of _padding_, and the mask is
+itself surrounded by a rectangular _border_, of specified color and
+width.
+
+ 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
+
+
+
+`ePiX''s marker types, listed in Table *Note table:marker::, , are
+obtained with the command marker(P pt, <MARKER TYPE>); Several
+"dot-like" marker types are available by name: [Image]
+
+ spot(P pt); dot(P pt); ddot(P pt);
+ --- box(P pt); bbox(P pt);
+ ring(P pt); circ(P pt); ---
+ A `circ' is filled with the current `mask_color', and a `ring' is
+"hollow". Each dot-like marker can also be called with label syntax,
+generating a labeled marker with one command.
+
+ dot(P posn, offset=P(0,0), msg="", align=none); // etc.
+
+ By default, `spot' and `ring' are 4 pt in diameter; `dot', `box',
+and `circ' are 3 pt in diameter; `ddot' and `bbox' are 2 pt in
+diameter. At arbitrary diameter, a `spot' is 4/3 the diameter of a `dot'
+and a `ddot' is 2/3 the diameter. The command `dot_size(diam=3)' sets
+the diameter of a `dot', and hence the size of all dot-like markers.
+
+
+[Image]
+
+Table[tb]
+
+
+
+When constructing and placing a label,
+ * Offsets are specified in `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.
+
+ * The label text is enclosed in double quotes (the single
+ character `"'), and contains the `LaTeX' code to generate the
+ label. Backslashes are doubled.
+
+
+
+Old-style color declarations set the fill color, line color, and text
+color.
+
+ rgb(r, g, b); cmyk(c, m, y, k);
+ rgb(P); cmyk(P); // for function-controlled colors
+ red(d); // similarly for other primaries
+
+
+
+File: epix.info, Node: Creating and Drawing Objects, Next: More About `C++', Prev: Drawing Attributes, Up: Reference Manual
+
+3.6 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.
+
+
+
+The simplest object in the world, and by far the most common named data
+structure, is `P', an ordered triple of real numbers (double-precision
+floats). The function `P(x1,x2,x3)' creates the point (x_1,x_2,x_3). If
+only two arguments are provided, x_3=0 by default. This convention
+allows `ePiX' to treat 2- and 3-dimensional figures uniformly. The
+standard basis is available: `E_1=P(1,0,0)', etc.
+
+ Depending on context, a `P' may represent either a _location_
+(point) or a _displacement_ (vector). Almost all `ePiX' functions treat
+a `P' as a point. However, algebraic operators and commands that plot
+vector fields treat `P' arguments as displacements.
+
+ Polar, cylindrical, and spherical coordinate `P' constructors are
+sensitive to the current angular mode.
+
+ 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))
+
+ Algebraic operations--addition/subtraction, scalar multiplication;
+scalar, cross, and componentwise products; orthogonalization--can be
+performed on `P's. In compound expressions, the binary operators below
+should be enclosed in parentheses, and scalars must be collected at
+left, `P's at right.
+
+ 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)
+ Explicitly, `p\%q' is the unique vector `p+k*q' perpendicular to `q'.
+
+ `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 `P' operators.
+
+
+
+In addition to `P', objects of type `Circle', `Plane', `Segment', and
+`Sphere' can be used for Euclidean geometry constructions. Simple
+affine operations are supplied for each type, as is a `draw()'
+function, which represents the object as a path in the screen.
+
+ 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();
+ A `Segment''s "center" is its midpoint. A `Plane' has no center;
+`move_to' translates the `Plane' to pass through `arg', and `scale' has
+no effect.
+
+ A `Circle' data structure consists of a center, radius, and a
+perpendicular unit vector. Three constructors are provided:
+
+ Circle(center=P(0,0,0), double rad=1, normal=E_3);
+ Circle(P center, P point);
+ Circle(P p1, P p2, P p3);
+ The second constructor creates the `Circle' parallel to the (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 (x_1,x_2) plane.) The third returns the `Circle' passing through
+the given points; the points must not be collinear.
+
+ The data defining a `Circle' are recovered with member functions
+named `center()', `radius()', and `perp()'.
+
+ A `Plane' is specified by a point and normal vector, or by three
+non-collinear points. The `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.
+
+ A `Segment' is constructed from its endpoints. The member function
+`midpoint()' returns the center.
+
+ A `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 `center()' and `radius()' return the defining data.
+Capabilities specific to geography and spherical geometry are described
+below, pp. *Note non-eucl::ff.
+
+ The `draw()' function of a `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 `Sphere' and the center is not close to the
+`target'.
+
+
+
+To facilitate geometric computation, `ePiX''s `Circle', `Plane',
+`Segment', and `Sphere' classes can be intersected with the `*'
+operator.
+
+ A `Circle' has a center, radius, and unit normal; a `Plane' has a
+distinguished point and unit normal; a `Segment' has two endpoints; a
+`Sphere' has a center and radius. An object is _malformed_ if these
+conditions are not met. The constructors return well-formed objects
+with two exceptions: `Circle' and `Plane' create malformed objects if
+called with three collinear points. The operator `*' returns a
+malformed object if either argument is malformed, or if the operands
+are disjoint, tangent, or coincident. Malformedness is benign: Calling
+`draw()' on a malformed object does nothing.
+
+
+
+A `frame' comprises three mutually perpendicular unit vectors. The
+constructor takes three vectors. The `frame''s third vector e_3 is
+positively proportional to `v3', the second vector e_2 is positively
+proportional to `v2\%v3', and the first is the cross product,
+e_1=e_2\times e_3. Thus, a `frame' is right-handed, and does not depend
+on `v1'.
+
+ The elements of a `frame' are named `sea', `sky', and `eye', just as
+for the `camera'. A `frame' can be rotated through an arbitrary angle
+about any of its elements.
+
+ 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.
+
+
+
+Basic path-like objects are drawn with named commands. Arguments of
+polygon commands are endpoints/vertices. Except for `line' and `Line',
+the following are subject to filling.
+
+ 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);
+ The optional `line' argument is an expansion parameter:
+`line(p1,p2,t);' draws a segment centered at the midpoint of `p1' and
+`p2', with length scaled by 2^t/100. (Setting t=100 doubles the length,
+while t=-100 halves the length.) The arguments of `rect()' must lie in
+a plane parallel to a coordinate plane. The arguments to `circle'
+commands are the same as for `Circle' constructors.
+
+ Quadratic and cubic splines are described by their control points. A
+list of `P' is drawn as a "natural" spline (the 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.
+
+ 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]);
+ If parameter bounds are omitted in an `ellipse' command, the entire
+ellipse is drawn. When the angular range subtends one or more full
+turns in an `arc' or `ellipse' the curve is subject to filling.
+
+ Commands for planar (half-)ellipses remain from `ePiX''s early days:
+
+ 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);
+ If `radius' is `P(a,b)', these commands draw all or half of the
+ellipse with given center in the (x_1,x_2) plane, axes parallel to the
+coordinate axes, and axis lengths 2a and 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.
+
+ 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);
+ The `right_angle' command does not check its arguments for
+perpendicularity. The `arc_measure' commands mark the _small_ angle
+subtended by the directions; the label form places a label at the
+midpoint of the arc. The (optional) `scale' argument is the true size
+in `pt' of the marker.
+
+
+
+Consider a path made up of equal-length segments that can point at any
+angle of the form 2\pi k/n radians, for 0\leq k<n, like spokes on a
+wheel. A path is specified by a finite sequence of integers, taken
+modulo n. For example, if n=6, then the sequence 0, 1, -1, 0 corresponds
+to the ASCII path _/_. `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 *Note
+fig:fractal::, . The seed above generates the standard von Koch
+snowflake fractal. In code:
+
+ const int seed[] = {6, 4, 0, 1, -1, 0};
+ fractal(P(a,b), P(c,d), depth, seed);
+ The first entry of `seed[]' (here 6) is the number of "spokes" n, the
+second (4) is the number of terms in the seed, and the remaining
+entries are the seed proper. The final path joins (a,b) to (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.
+
+[Image]
+
+Figure[hbt]
+
+
+
+Line segments, splines, and arcs can be drawn with arrowheads at one
+end. In profile, an arrowhead's width is `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:
+
+ 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
+ [Image]\qquad [Image]\qquad [Image] \\ The `inset' must be between -1
+and 1. Each `arrow' command accepts an optional `scale' argument, which
+scales the arrowhead.
+
+ 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
+ A few "special-purpose" commands are supplied:
+
+ 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]);
+ If an `arc_arrow' is too short, nothing is drawn.
+
+
+
+`ePiX' provides an `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.
+
+
+
+An `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 `axis'.
+
+ The command
+
+ axis(P tail, P head, int n, P offset=P(0,0), [align = none]);
+ creates an axis joining `tail' to `head', divided into `n' segments of
+equal length, with a major tick mark and label at each division point
+and endpoint. The `offset' and `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:
+
+ 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
+ By default, major ticks are `6pt' long and twice the length of minor
+ticks. The global declaration `tick_size(len)' sets the major length,
+subject to "reasonable stylistic limits". For visual consistency, tick
+lengths should not be changed casually.
+
+ Labels on an `axis' may be drawn in several styles, selected with
+member functions:
+
+ 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
+ Arbitrary textual labels depending on one coordinate are obtained by
+writing a `string'-valued function of `double' and "registering" it:
+
+ // 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);
+ For example, textual tags can be printed instead of numeric labels.
+
+ By default, an `axis' is Cartesian. The member function `log(int
+b=10)' converts an `axis' to "log mode" with specified base; this
+affects both tick marks and labeling. If `b' is at least 3, minor tick
+marks appropriate for a logarithmic axis base `b' are drawn. Second,
+labels are written in decimal or scientific notation appropriately for
+a logarithmic axis; that is, "k\times b^N" (or its decimal value) is
+written at location N+\log_b k.
+
+ Minor ticks of a log `axis' may be labeled individually; again, this
+is controlled with member functions:
+
+ 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);
+
+ For convenience, an `axis' object along an edge of the active
+`screen' can be created with a named command:
+
+ top_axis(n, offset, align);
+ bottom_axis(n, offset, align);
+ left_axis(n, offset, align);
+ right_axis(n, offset, align);
+ The ticks automatically point into the bounding box.
+
+ The functions above create objects or set `axis' attributes, but
+write no output. Tick marks and labels can be printed separately, or at
+once:
+
+ Ax.draw(); // axis, tick marks, and labels
+ Ax.draw_ticks(); // axis and ticks only
+ Ax.draw_labels();
+
+
+
+`ePiX' formerly supplied commands for drawing simple axes and their
+labels. These commands have been kept for compatibility. Horizontal
+axes are generated with
+
+ h_axis(p1, p2, n, align=c); // n subintervals (n+1 ticks)
+ h_log_axis(p1, p2, n, align=c, base=10);
+ For vertical axes, use `v_axis'. The style of tick mark is
+appropriate for an axis of the given type. Horizontal axis tick marks
+may be aligned `t' (above the axis) or `b' (below). Similarly, vertical
+axis ticks may be aligned `r' or `l'.
+
+ The endpoint arguments of a coordinate axis may be omitted, in which
+case they default to p_1=(x_min,0) and p_2=(x_max,0) for a horizontal
+axis, or to p_1=(0,y_min) and p_2=(0,y_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
+
+ 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);
+ Labels for a vertical axis are generated with `v_axis_labels', etc.
+The labels are automatically generated to match their horizontal
+location. The first puts (n+1) evenly-spaced labels on the segment
+joining `p1' and `p2'. As with ordinary labels, the `offset' is in
+`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 `axis_[mask]labels' command, with the same defaults. The
+`offset' and number of labels must always be specified.
+
+
+
+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
+`inset' the screens so the axis pieces are nearly end to end. A zig-zag
+glyph signifies the break:
+
+ axis_break(P, P, scale=12);
+ The `P' arguments are the screen coordinates of the ends to be joined;
+the optional third argument is the true height and width in `pt' of the
+glyph. The sample file `coord_tricks.xp' uses layout and axis breaks.
+
+
+
+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.
+
+ grid(n1, n2); // fills the bounding box
+ grid(p1, p2, n1, n2); // fills the box with corners p1, p2
+ polar_grid(r, n1, n2);
+
+ Log and semi-log grids are drawn with analogous syntax:
+
+ 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
+ The 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.
+
+ Graph paper may be created by superimposing grids:
+
+ pen(0.25);
+ grid(10*xsize(), 10*ysize());
+ pen(0.5);
+ grid(2*xsize(), 2*ysize());
+ pen(1);
+ grid(xsize(), ysize());
+
+
+
+A `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 `P'-valued function `f'
+of one variable.
+
+ 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]);
+
+ The member function `pt()' accepts a `P' or three (or two) doubles
+and appends the specified point to a `path'. This snippet creates a
+regular n-gon:
+
+ path ngon; // declare new path
+ for (int i=0; i<=n; ++i)
+ ngon.pt(cis(i*full_turn()/n)); // works in all angle modes
+ Compound paths may be built by concatenation. If `path1' and `path2'
+share an endpoint, the commands
+
+ path1 += path2;
+ path1 -= path2;
+ replace `path1' with the result of traversing `path1' "forward", then
+following `path2' in the forward or reverse direction (respectively).
+For expected results, the first (or last) point on `path2' should be
+the last point of `path1'. The notation suggests 1-dimensional homology
+chains. The sample file `contour.xp' illustrates path creation and
+manipulation.
+
+ A `path' is a data structure, and must be drawn explicitly to create
+visible output. By default a `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 n-gon snippet
+above,
+
+ ngon.close(); // mark path as closed
+ ngon.fill(); // draw filled region if filling is active
+ ngon.draw(); // print to the screen
+ `path::close()' adds a closing edge if necessary. Once a `path' is
+closed, no more points can be added. A closed path clips and crops
+differently than an open `path' with the same data. `path::fill()' has
+no effect on an unclosed `path'.
+
+
+
+The noun "map" refers to a `C++' function that accepts one or more
+`double' arguments and returns a `double' or a `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 `double'-valued maps
+are graphed and `P'-valued maps are drawn parametrically. Either sort
+of depiction is called a "plot". `ePiX' plots are either "wire mesh",
+produced by a `plot' command, or "shaded", produced by a `surface'
+command.
+
+
+
+For the moment, "function" means "function of one variable" (precisely,
+a `double'-valued function of a `double' variable). A function graph
+depends on the domain and the number of points to use. Each of the
+commands
+
+ plot(f, t_min, t_max, n);
+ polarplot(f, t_min, t_max, n);
+ shadeplot(f, t_min, t_max, n);
+ graphs the function `f' on the interval `[t_min, t_max]' by dividing
+the interval into `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 `shadeplot', the region between
+their graphs is shaded.
+
+
+
+An `ePiX' `domain' is a coordinate box of dimension one, two, or three,
+specified by a pair of opposite corners and two _meshes_ ("coarse" and
+"fine", respectively) which specify the amount of data to be plotted.
+Plotting is explained in detail below.
+
+ // [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)]);
+ 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 m_i should be a (usually small) integer multiple of n_i for each i.
+
+ A `domain' may be _resized_ in any coordinate for which the
+thickness is positive, and can be _sliced_ by setting one variable to a
+constant. The result of slicing is a `domain' whose dimension is one
+smaller than the original. Finally, "`slices'" operators return the
+list of `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.
+
+ R2.resize2(a,b); // [a1,b1] x [a,b]
+ R2.slice1(t); // set x1 = t
+ R3.slices3([n]); // (n+1) domains with x3 = const
+[Image]
+
+ \smallskip When possible, resizing preserves grid square sizes.
+Generally, though, integer truncation occurs: If `R=domain(P(0,0),
+P(1,1), mesh(10,6))', then `R.resize1(0,0.25)' is the rectangle
+[0,0.25]\times[0,1] subdivided into 2\times6 subrectangles, since
+10\div4=2 in integer arithmetic. For expected behavior, choose mesh
+sizes to avoid integer truncation.
+
+ The arguments of a `plot' command are a map, followed by either a
+domain or its logical equivalent.
+
+ 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
+ By (compiler-enforced) convention, `plot' commands involving a
+`P'-valued map accept a `domain' argument, as in the second and third
+commands above. To plot a `double'-valued function, by contrast, supply
+the logical equivalent of a `domain', usually the endpoints and the
+number of intervals, as in the first `plot' command above.
+
+ Resizing and slicing allow a map `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 `plot' command:
+
+ plot(F, R2.resize1(0,0.5));
+ plot(F, R2.slices1());
+
+
+
+The `P' arguments of a `domain' are a pair of opposite corners. The
+first `mesh' argument, the _coarse_ mesh, specifies the number of
+subdivisions in each coordinate direction. The second `mesh', the
+_fine_ mesh, determines the number of points used in each direction
+when plotting.
+
+ 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 *Note fig:plot::, are drawn with a 6\times20 coarse
+mesh. In the first picture, the fine mesh is also 6\times20, while in
+the second, the fine mesh is 12\times60.
+
+
+[Image] [Image]
+
+Figure[hbt]
+
+ 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 _perpendicularly_ to a coordinate direction, while the
+fine mesh's size determines the number of segments used _along_ that
+direction. For predictable results, the fine mesh should be a small
+multiple of the coarse mesh.
+
+ Plotting works analogously for 3-dimensional `domain's and maps
+depending on three variables: The "one-dimensional skeleton" of the
+`domain''s image is drawn. A `P'-valued map of three variables can be
+plotted over a 1- or 2-dimensional `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 `domain'.
+
+
+
+`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 `surface' command is identical to a `plot' command
+when only a single surface is drawn. For example,
+
+ surface(F, R, cull=0);
+ plots the `P'-valued function `F' over the domain `R', the shaded
+equivalent of the corresponding `plot' command. The optional `cull'
+argument removes elements that point toward (`cull=-1') or away from
+(`cull=1') the camera. Naturally, orientation of mesh elements depends
+on the parametrization `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 `cull' argument.
+
+ 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);
+ The first revolves the graph of f about the x-axis, the second uses
+the parametric curve t\mapsto\bigl(f(t),g(t)\bigr) as profile. In each
+case, the parameter interval [t_min,t_max] is divided into n_lats
+equal-length subintervals, n_longs copies of the profile curve are
+drawn, and the complete surface (one full turn) is drawn.
+
+ The third form uses a `domain' to control the range of longitudes,
+and draws a surface of rotation in the Cartesian coordinate system
+defined by the orthonormal basis `coords', by default the standard
+basis. The arguments `f' and `g' define a parametric curve in the plane
+spanned by the first two elements of `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 _patch_ is drawn, not
+the visible edge of the mathematical surface. See
+`samples/artifacts.xp'.
+
+
+
+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 `domain's. In the code snippets below, `F' and `G' are
+`P'-valued functions of 3 variables, and `R' is a 3-dimensional
+`domain'.
+
+ To plot the images of several `domain's under a _single map_,
+assemble the `domain's into a list if necessary, then issue a `surface'
+command:
+
+ 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
+ For multiple maps, `ePiX' provides the `scenery' class. Conceptually,
+`scenery' is an agglomeration of shaded surfaces, built one surface at
+a time from maps and 2-dimensional `domain's. The `add' function
+accepts two arguments--a map, and either a `domain' or a list of
+`domain's--and contributes its data to the `scenery' rather than
+plotting immediately. Completed `scenery' is drawn manually.
+
+ 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);
+ Complete examples are included in the `samples' directory:
+`spherical.xp' and `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
+`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 `hugelatex'; your mileage
+may vary.
+
+
+
+By default, a `surface' or `scenery' is colored according to the
+current fill color. For finer control, each `surface', `surface_rev',
+and `scenery' command accepts an optional position-dependent `color'
+specification.
+
+ 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);
+ The `color' argument is a `P'-valued function of two or three
+`double's whose output is interpreted as a set of `RGB' densities. If
+`color' takes two arguments, they are `domain' coordinates, and the
+surface is colored according to parameter values. If `color' takes
+three arguments, they are Cartesian coordinates, and the surface is
+colored according to spatial location. Please see the sample files
+`surface_shade.xp' and `S2_harmonics.xp'.
+
+
+
+`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, `f' and `g' are `double'-valued functions of one
+variable.
+
+
+
+
+ sup(f, a, b); // max/min of f on [a,b]
+ inf(f, a, b);
+ newton(f, g, x0); // find approximate crossing point
+ 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 g defaults to the zero function if
+omitted.
+
+
+
+The classes `Deriv' and `Integral' are used to calculate values of
+derivatives and integrals, and to plot these functions.
+
+ 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
+ The lower limit on an integral is 0 by default. `Deriv's and
+`Integral's can be used directly in a `plot' command:
+
+ 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);
+ The second graphs the definite integral x\mapsto\int_x_0^x f(t)\,dt
+over [a,b]. As above, x_0 defaults to 0. The third draws rectangles or
+trapezoids whose area approximates the definite integral of f over
+[a,b]. The `TYPE' may be `UPPER', `LOWER', `LEFT', `RIGHT', `MIDPT', or
+`TRAP'.
+
+ Tangent lines and envelopes (families of tangent lines) are drawn
+with
+
+ 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
+ The sample files `conic.xp' and `lissajous.xp' illustrate these
+features.
+
+
+
+Let `F' be a `P'-valued function of two or three variables.
+
+ ode_plot(F, p_0, t_min, t_max, n);
+ flow(F, p_0, t_max, n);
+ The first plots the solution curve of the initial-value problem
+\dotx=F(x), x(0)=p_0, over the specified time interval. If t_min is
+omitted, its value is 0, so the curve starts at p_0. With manual
+calculation to rotate a planar field a quarter turn, `ode_plot' can be
+used to draw level curves (isobars) of a function of two variables; see
+the sample file `dipole.xp'. The `flow' function returns the result of
+starting at p_0 and flowing by F for time t_max, using Euler's method
+with 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
+`R' in three styles:
+
+ vector_field(F, R, [scale]); // true length
+ dart_field (F, R, [scale]); // const length
+ slope_field (F, R, [scale]); // const length
+ 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 x_3=const,
+starting at the height of the first corner of `R' and ending at the
+height of the second corner.
+
+ The optional final argument, which defaults to 1, scales the
+arrowheads in a vector field, and scales the (constant) length of field
+elements for slope and dart fields. The sample files `layout2.xp',
+`lorenz.xp', `slopefield.xp', and `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.
+
+
+
+`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.
+
+ hyperbolic_line(p, q);
+ disk_line(p, q);
+ For compatibility with 2-dimensional hyperbolic space, the half-space
+model is the set \(x_1,x_2,x_3)\mid x_2>0\.
+
+ A `frame' determines geographical coordinates on a `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
+`Sphere', a `frame', the numerical latitude, and a range of longitudes.
+A longitude line is described similarly.
+
+ latitude(lat, long_min, long_max, Sphere S, frame coords);
+ longitude(lngtd, lat_min, lat_max, Sphere S, frame coords);
+ By default, `coords' is the standard `frame' and `S' is the unit
+sphere. These commands draw only the portion of the curve that is
+visible from the current viewpoint. The function `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:
+
+ 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
+ Triangles and regular (Platonic) polyhedra are provided. The sample
+file `sample/polyhedra.xp' illustrates usage.
+
+ 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
+ Each function has a `back' version, which draws the hidden portion.
+The tetrahedron, cube, and octahedron are (up to scale) inscribed in
+the cube of side length 2 centered at the origin whose sides are
+parallel to `frame'. The point (1,1,1) is a vertex of the tetrahedron.
+
+ Up to scale, the icosahedron's vertices lie on the golden rectangle
+with vertices (\pm\gamma,0,\pm1) and its images under cyclic
+permutation of coordinates. The dodecahedron is dual to the icosahedron.
+
+
+
+Parametrized paths on a `Sphere S' (by default the unit sphere) can be
+specified either by radial projection of a `P'-valued curve, or by
+stereographic projection of a plane curve given as a pair of
+`double'-valued functions:
+
+ 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
+ Attempts to perform radial projection on a path through the origin
+will generate division-by-zero errors. Stereographic projection maps
+the equatorial plane \x_3=0\ to the unit sphere by projection from the
+corresponding pole: N=(0,0,1), S=(0,0,-1).
+
+ Each spherical plot command has a `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.
+
+
+
+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 `\%' is a comment.
+
+ `ePiX' provides two `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 `P'-valued function `F',
+and plot the resulting points:
+
+ plot("filename", STYLE, [i_1], [i_2], [i_3], [F]);
+ plot("filename", STYLE, F, [i_1], [i_2], [i_3]);
+ The first argument is the name of the data file. The `STYLE' may be
+`PATH', which joins the points in the order they appear, or any of the
+marker types in Table *Note table:marker::, . The integers 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" `F' is omitted in the first command, it defaults to
+the Cartesian point constructor. The function `F' is mandatory in the
+second form; useful choices include `log_log', `log_lin', and
+`lin_log', which plot the corresponding coordinate logarithmically.
+
+
+
+For more elaborate analysis, the `data_file' class presents an
+interface to a file as an ordered list of columns. There are two
+general ways to create a `data_file': read in an external file, or
+generate data (up to three columns) using specified `double'-valued
+functions. In the constructors below, each function `fi' is a
+`double'-valued function of one variable.
+
+ 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
+
+ Columns of a `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 `f' is a `double'-valued function of one variable
+and `F' is a `P'-valued function of two or three variables, whose
+components are written back to the selected columns.
+
+ DF.transform(f, i); // apply f to selected column(s)
+ DF.transform(F, i=1, j=2);
+ DF.transform(F, i, j, k);
+ Basic statistical operations on columns are provided.
+
+ 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
+ A `data_file' is scatter plotted using syntax as described above. %
+The output is cropped automatically to the bounding box.
+
+ DF.plot(STYLE, [i1], [i2], [i3], [F]);
+ DF.plot(STYLE, F, [i1], [i2], [i3]);
+ Histograms and bar charts are described below.
+
+ A `data_file' can be written to a disk file as raw data, or in
+specified format. Below, `fmt' denotes a `string'-valued formatting
+function of two variables and `myfile' is the name of the disk file to
+be written.
+
+ 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
+ A column can be extracted as a `C++' `vector' for use by another
+function.
+
+ DF.column(i); // i-th column
+ DF.column(f, i); // i-th column, transformed by f
+
+
+
+`ePiX' provides a `data_mask' class for culling data from a file
+according to the values in a specified column, and a `data_bins' class
+for sorting data by value.
+
+ A `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 `double'-valued function of
+`double', by default the identity, f(x)=x.
+
+ data_mask dm("[a, b]", [f]);
+ data_mask dm(a, b, [f]);
+ A `data_mask' "passes" inputs x if f(x) lies in the interval. The
+member function `reverse()' inverts this logical test.
+
+ The `data_file' class has `prune' functions to cull rows for which a
+specified column's entry satisfies a `data_mask''s criterion.
+
+ 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]
+
+ A `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 `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.
+
+ // [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
+
+ A `data_bins' object can be plotted as a histogram (rectangles'
+_area_ is proportional to the bin population), bar chart (rectangles'
+_height_ is proportional to the bin population), or spline
+interpolation of a bar chart.
+
+ db.histogram(c=1); // c = vertical scale factor
+ db.bar_chart(c=1);
+ db.plot(c=1);
+ By default (`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 [a,b] does not depend on how [a,b] has
+been subdivided. The sample files `dataplot.xp' and `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 x<a or x>b is a data value, it is counted as
+out-of-range and does not contribute to the histogram population. If
+x=a or 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.
+
+
+
+Simple horizontal and vertical error bars are provided. The final
+(optional) argument is the true height or width (respectively) in pt.
+
+ h_error_bar(P location, double error, <mark type>, ht=6);
+ v_error_bar(P location, double error, <mark type>, wd=6);
+
+ 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 *Note truesize::. For example, a fillable,
+labeled, asymmetric, vertical rectangular error bar can be implemented
+(entirely in `ePiX') like this:
+
+ 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);
+ }
+ For stylistic uniformity, functions such as this should be put into a
+library and used systematically. Section *Note section:extensions::,
+outlines the process of writing, compiling, and using a custom library.
+
+
+
+A `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 `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 `12pt' squares bordered in black, the label skip is `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 `double' represent lengths in `pt'.
+
+ 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);
+
+
+
+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.
+
+ L.fill_item(text);
+ L.path_item(text);
+ L.mark_item(<mark type>, text);
+ Keys in the printed legend appear in the same order they are created
+in the input file.
+
+
+
+Normally, a `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
+`legend' is placed into the figure with the `draw' function. The
+arguments have the same meaning as for ordinary `label's.
+
+ L.draw(P location, P offset, align);
+ All three arguments are mandatory. "Global" `legend' settings
+(border, backing, etc.) may be changed anywhere between the `legend''s
+creation and `draw' function. The sample file `legend.xp' revisits the
+example on page *Note taylor_poly::, including a trig-labeled axis and a
+legend. The file `shadeplot.xp' contains filled keys, and `dataplot.xp'
+contains a `legend' with items of mixed type.
+
+
+File: epix.info, Node: More About `C++', Next: Attribute Quick Reference, Prev: Creating and Drawing Objects, Up: Reference Manual
+
+3.7 More About `C++'
+====================
+
+A textbook or similarly detailed reference is essential for serious
+study of `C' or `C++'. _The `C' Programming Language_, second edition,
+by Kernighan and Ritchie `KnR', is an excellent, manageable resource
+for the basics of procedural programming. _C++ Primer Plus_, by Stephen
+Prata `Prata', clearly lays out the extensive details of `C++'.
+Marshall Cline's _`C++' FAQ Lite_ `Cline' engagingly discusses common
+points of confusion and furnishes tips on good design and programming.
+
+ `C++' 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 `C++' program that writes a
+`LaTeX' picture as output. `ePiX' may be viewed as an extension to
+`C++'; in the same way that `LaTeX' furnishes a high-level interface to
+`TeX', `ePiX' provides a high-level bridge between the computational
+power of `C++' and the `LaTeX' `picture' environment.
+
+ Like all high-level programming languages, `C++' 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.
+
+
+
+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.
+
+ Every variable in `C++' has a "type", such as integer (`int'),
+double-precision floating point (`double'), or Boolean (`bool', true or
+false). `ePiX' provides additional types, the most common of which is
+`P', for point. The construct `P(x,y,z)' creates (x,y,z), while
+`P(x,y)' gives (x,y,0), which is effectively the pair (x,y). A variable
+is defined by giving its type, its name, and an initializing expression.
+
+ In `C' and `C++', a _pointer_ variable holds the memory address of
+another variable. Pointers are useful for manipulating (possibly large)
+data structures through "handles" of fixed small size. `C++' also
+provides _references_, which bind an additional name to an existing
+object and allow the object to be manipulated through this alias. The
+statements
+
+ double x=1; // ordinary variable definition
+ double& rx=x; // bind a reference, signified by &
+ define a variable `x' having the value 1, and bind a reference
+variable `rx' to it. As long as `rx' exists, it refers to `x'. If the
+value of `x' changes, the value of `rx' does as well. Conversely, the
+value of `x' can be altered by assigning to `rx'. However, `rx' is the
+size of a pointer, regardless of the size of `x', so `rx' can be passed
+efficiently in a function call.
+
+
+
+In a programming language, the term "function" refers to a block of
+code that is executable by name. A `C++' 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:
+
+ int factorial(unsigned int n)
+ {
+ if (n == 0) return 1;
+ else return n*factorial(n-1);
+ }
+
+ The special type `void' represents a "null type". A function that
+performs an action but does not return a value has return type `void'.
+A function that takes no arguments may be viewed as taking a single
+`void' argument.
+
+ Every `C++' program has a special function `main()', which is called
+by the operating system when the program is run. The arguments of
+`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 `main()' or in a separately-compiled file.
+
+ Functions in `C++' 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 `functions.cc' contains
+simple functions defined by algorithms, and `functions.h' illustrates
+the use of `C++' templates. Other source files, such as `plots.cc', may
+be consulted for Simpson's rule, Euler's method, and the like.
+
+
+
+`C++' knows several familiar mathematical functions by name:
+
+ sqrt exp log log10 ceil floor fabs
+ (`fabs' is the absolute value for a floating-point argument.) `ePiX'
+provides trig and inverse trig functions sensitive to angular mode:
+
+ Cos Sin Tan
+ Sec Csc Cot
+ Acos Asin Atan
+ The inverse functions are principle branches.
+
+ The function `pow(x,y)' returns x^y when x>0, and `atan2(y,x)' (N.B.
+argument order) returns Arg(x+iy)\in(-\pi,\pi], the principle branch of
+arg. `C++' knows many constants to 20 decimal places, such as `M_PI',
+`M_PI_2', and `M_E' for \pi, \pi/2, and e respectively. `ePiX' defines
+a few additional functions:
+
+ sgn zero sinx cb
+ `sgn' is the signum function; `zero' is the constant function; `sinx'
+is the function x\mapsto \sin(x)/x with the discontinuity removed; `cb'
+(for "Charlie Brown") is the period-2 extension of the absolute value
+function on [-1,1].
+
+ The GNU `C++' library defines other functions, including inverse
+hyperbolic functions (`acosh', etc.), `log' and `exp' with base 2, 10,
+or arbitrary b (`log2', etc.), the error and gamma functions (`erf' and
+`tgamma' [sic], respectively), and Bessel functions of first and second
+kind: `j0', `j1', `y0', etc. Use, e.g., `jn(5, )' to get higher
+indices. The GNU `C' library reference manual `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:
+
+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); }
+
+
+
+
+Unlike `C', `C++' supports "object-oriented programming". In a
+nutshell, a _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 _interface_ (the set
+of meaningful operations) from its _implementation_ (the data
+structures and algorithms that realize the interface).
+
+ A class implementation consists of _members_ (named data elements)
+and _member functions_ (functions that belong to the class and have
+free access to members). `C++' 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:
+
+ Circle C1(P(1,0), 1.5); // circle of given center and radius
+ C1.draw(); // member function Circle::draw();
+ Naturally, this call draws the circle `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 `Prata' or Stroustrup `S', or Cline's
+on-line FAQ `Cline'.
+
+
+
+`C' and `C++' 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 `C++', 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 _needs_ to modify its arguments (e.g., a function `swap(x,y)'
+that exchanges the values of `x' and `y').
+
+ For the first situation, `C++' provides the `const' keyword, which
+ensures the function does not modify its arguments, but accepts a
+reference merely for efficiency. Any attempt to modify a `const'
+argument will be caught by the compiler. Most `ePiX' commands accept
+`const' reference arguments.
+
+ The ability to pass function arguments by reference is sometimes
+touted as a feature in `C++' 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.
+
+ 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
+ Unlike pointer arguments, reference arguments impose no syntactic
+burden on the user. If `A' is a `matrix', then `transpose(A);' and
+`trace(A);' will compile. You need not declare explicit reference
+variables and pass those to the function.
+
+
+
+`C++' provides "overloading": Multiple functions can be given the same
+name, so long as the number and/or type of their arguments differ. (It
+is _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.
+
+
+
+A `C++' 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
+_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.
+`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.
+
+
+
+A `C++' 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 `C++' than in `C'; the language
+itself supports safer and more featureful alternatives to macros, such
+as `const' variables and inline functions. File inclusion and
+conditional compilation are the chief uses of the pre-processor. Lines
+of the form
+
+ #include <iostream>
+ #include "epix.h"
+ cause the contents of a _header file_ to be read into the source file.
+A header file contains variable and function _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.
+
+ Conditional compilation is similar to conditional `LaTeX' code. For
+example, a file might produce either color or monochrome output as
+follows:
+
+#ifdef COLOR
+ ... // code for generating color figure
+#endif /* COLOR */
+#ifndef COLOR
+ ... // monochrome code
+#endif /* undef COLOR */
+ The "compiler symbol" `COLOR' is an ordinary `C++' name. To control
+compilation, either put a `\#define COLOR' line in the file, or
+(better) supply the flag on the command line: \\ epix -DCOLOR
+<file.xp> \\ Every `\#ifdef' must have a matching `\#endif'. Commenting
+the `\#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.
+
+
+
+As a programming language, `C++' 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 `C++'
+include:
+
+ 1. Every `C++' 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 `\#', do not end with a semicolon.
+
+ 2. Backslash is an escape character in `C++':
+ // 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
+
+ 3. Variable and function names may contain letters (including
+ underscore) and digits _only_, are case sensitive, and must
+ begin with a letter.
+
+ 4. Variables in `C++' must have a declared _type_, such as `int'
+ (integer) or `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 `main'. Local variables should be defined in the
+ smallest possible scope. Unlike `C', `C++' allows variables to be
+ defined where they first appear.
+
+ 5. `C++' requires explicit use of `*' to denote multiplication;
+ juxtaposition is not enough. `C++' does not support the use of ^
+ for exponentiation, e.g., t^2 is invalid. Instead, use `t*t' or
+ `pow(t,2)'.
+
+ 6. `C++' has single- and multi-line comments. Everything between a
+ double slash and the next newline is ignored, while the strings
+ /* and */ delimit multi-line comments. A single-line comment may
+ appear within a multi-line comment, but the compiler does not
+ nest multi-line comments.
+
+
+ Between them, `C' and `C++' have about 100 reserved keywords which
+cannot be used as function or variable names.
+
+
+File: epix.info, Node: Attribute Quick Reference, Prev: More About `C++', Up: Reference Manual
+
+3.8 Attribute Quick Reference
+=============================
+
+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 `len' argument is a double-quoted string containing a number and a
+two-letter `LaTeX' length unit, such as `"1.5pt"' or `"6cm"'. A `color'
+argument is a named primary (`Red()', `Cyan()', `White()', etc.), a
+`Color' specified by densities (`RGB(...)', `CMYK(...)', etc.), or a
+`Color' object. Using `Neutral()' as a `Color' argument generally turns
+off the corresponding attribute.
+
+ * Angular mode: `radians()', `degrees()', or `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., `Cos', `Tan'.
+
+ * Fill style: `fill(color)', `fill(bool)', `nofill()'.
+
+ * Path style:
+
+ * Width: `plain()', `bold()', `bbold()', `pen(len)'.
+
+ * Line style: `line_style(string)'. The argument is a
+ WYSIWYG sequence of dashes, spaces, and periods.
+ `dash_size(double)' and `dot_sep(double)' set the
+ (approximate) length in `pt' of the pattern. The commands
+ `solid()', `dashed()', `dotted()' define "standard"
+ defaults for brevity.
+
+ * Path color: Paths can be drawn using _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.
+
+ `pen(color,[len])', `base(color,[len])'
+
+ Standard widths: `plain(color)', `bold(color)',
+ `bbold(color)'
+
+
+ * Text attributes:
+
+ * Color: `label_color(color)'
+
+ * Mask: `label_mask(color)', `label_pad(len)'
+
+ * Border: `label_border(color, [len])',
+ `label_border(len)'. The command `no_label_border()'
+ turns off label borders.
+
+ * Font size: `font_size(LaTeX size)', no argument means
+ `normalsize'.
+
+ * Font face: `font_face(LaTeX font)', two-letter font
+ selection string, default is `rm'.
+
+ * Rotation: `label_angle(double)'
+
+
+
+ Do not confuse `Color' constructors with the similarly-named
+(deprecated) lowercase attribute-setting commands, `rgb(r,g,b)',
+`cmyk(c,m,y,k)', `red(d)', etc. These commands affect text, paths, and
+filled regions. For example, the single command `red()' has the same
+effect as the three commands `pen(Red())', `fill(Red())', and
+`label_color(Red())'.
+
+
+File: epix.info, Node: Advanced Topics, Next: Software Freedom, Prev: Reference Manual, Up: Top
+
+4 Advanced Topics
+*****************
+
+This chapter covers _ad hoc_ tricks and open-ended techniques that
+require relatively more programming sophistication. You will almost
+surely need an external `C++' reference if you do not speak the
+language.
+
+* Menu:
+
+* Hidden Object Removal::
+* Extensions::
+* Programmer's Guide::
+
+
+File: epix.info, Node: Hidden Object Removal, Next: Extensions, Prev: Advanced Topics, Up: Advanced Topics
+
+4.1 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 `surface.*'.
+
+ 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 `C++' 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 `saddle.xp'
+illustrates possible techniques.
+
+ Shaded surfaces can be decorated with a bit of hackery. For example,
+the `facet::draw' function in `facet.cc' can be modified easily to draw
+line elements, tangents, or normal vectors along with the facet itself.
+The sample file `decorate.xp' contains a couple of ideas. (The
+decorations are activated by compiler flags; please consult the file
+itself for information on compiling.)
+
+
+File: epix.info, Node: Extensions, Next: Programmer's Guide, Prev: Hidden Object Removal, Up: Advanced Topics
+
+4.2 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 `C++' to separately compiled libraries that add
+substantial new features. The structure of the source code is outlined
+in Section *Note section:programmers::, .
+
+
+
+A `C++' header file conventionally has suffix `.h', as in `myheader.h'.
+To use this custom header, put a line `\#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
+
+ 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 }
+ The keyword `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 _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:
+
+ Bold();
+ draw_square(cube(1.25));
+
+
+
+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 `std_F.cc' and `std_F.h'
+illustrate the techniques described below, and may be used for guidance
+and experimentation.
+
+ A small library is usually written as a _header_ file, which
+contains class and function declarations (also called "prototypes"),
+and a _source_ file, which contains the actual code. Conventionally
+(under *nix), these files have extension `.h' and `.cc' respectively.
+Header and source files may "include" other header files, to
+incorporate additional functionality.
+
+/* 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 */
+ This file exhibits two "safety features". The three `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.
+
+/* 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
+ 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.
+
+% g++ -c my_code.cc
+% ar -ru libcustom.a my_code.o
+% ranlib libcustom.a
+ 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 `.a'. Once these steps are
+successfully completed, put the library `libcustom.a' and header file
+`my_code.h' in your project directory. You're ready to use the code in
+an `ePiX' figure.
+
+
+
+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
+
+ -I<include> -L<libdir> -l<lib>
+ For example, to link `figure.xp' against `mylibs/libcustom.a', run the
+command
+
+ epix -Lmylibs -lcustom figure
+ The options `-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
+`\$HOME/.epixrc', with syntax as above. A line in the config file that
+contains a pound sign (`\#') is a comment, no matter where in the line
+the `\#' 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.
+
+
+
+The script `epix' links by default against the `C' math library
+`libm.a' and the `ePiX' library `libepix.a'. The command option
+`--no-defaults' clears the header and include paths and removes
+`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 `INSTALL' instructions, but _do not use the makefile to
+install_. Instead, manually install the header and library only, using
+their version number:
+
+# install -m 644 epix.h /usr/local/include/epix-1.0.h
+# install -m 644 libepix.a /usr/local/lib/libepix-1.0.a
+ A non-system directory may be used instead of `/usr/local'. To use
+the old version, a source file must `include' the appropriate header
+file (which is identified by its version number). To compile, issue a
+command such as
+
+epix --no-defaults -I/usr/local -L/usr/local -lepix-1.0 file.xp
+
+
+File: epix.info, Node: Programmer's Guide, Prev: Extensions, Up: Advanced Topics
+
+4.3 Programmer's Guide
+======================
+
+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 `Color.h', `path.h', and `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 *Note section:interface::, .
+
+ The user interface headers are assembled into a single file,
+`epix.h', and installed in `/usr/local/include' by default. In normal
+use, the shell scripts read only the user interface header. The
+individual headers, including the components of `epix.h', are installed
+in `/usr/local/include/epix'. These are provided for authors of
+external libraries, who may need access to implementation details.
+
+
+
+`ePiX' harnesses the computational power of `C++' 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 `GNUCoding'. At a minimum, an external package should build
+with the standard `./configure; make; make install' commands, and the
+`configure' script should accept an option `--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 "`epix-<...>'" is a good idea, but
+not essential. For example, a package providing textual nodes and
+diagram layout might be named `epix-nodes'. Input files would use the
+package with the lines
+
+ #include "epix-nodes.h"
+ using namespace ePiX-nodes;
+ and be compiled with
+
+ epix -lepix-nodes <file>
+
+ 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 `include' the user header file,
+and deal only with high-level objects and drawing attributes.
+
+
+
+These files (in order) comprise the global header `epix.h'.
+
+ `enums.h' Marker, alignment, Riemann integral, and vector field
+types.
+
+ `length.h' Physical lengths, conceptually a number and two-letter
+`LaTeX' length unit.
+
+ `interval.h' Closed, open, and half-open interval ranges for data
+culling.
+
+ `triples.h' The `P' class.
+
+ `functions.h' Angle-sensitive trig functions, miscellaneous utility
+functions, the `Deriv' and `Integral' classes.
+
+ `pairs.h' Screen locations and displacements, with complex
+arithmetic operations.
+
+ `Color.h' The Color class interface, named primaries and
+constructors.
+
+ `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.
+
+ `frame.h' Orthonormal bases.
+
+ `domain.h' Coordinate boxes for function plotting.
+
+ `camera.h' The camera.
+
+ `screen.h' The screen class.
+
+ `picture.h' Dimension-setting, offset, layout, decoration, verbatim
+text, and output format commands.
+
+ `markers.h' Point markers, axis labels, and coordinate axes.
+
+ `axis.h' Coordinate axes and labels in various styles.
+
+ `legend.h' Plot legends.
+
+ `path.h' The path class.
+
+ `curves.h' Polygons, arrows, ellipses, arcs, splines, coordinate
+grids, and recursive fractal curves.
+
+ `circle.h' The `Circle' shape object class.
+
+ `plane.h' The `Plane' shape object class.
+
+ `segment.h' The `Segment' shape object class.
+
+ `sphere.h' The `Sphere' shape object class.
+
+ `intersections.h' Shape object intersection operators.
+
+ `plots.h' Plotting commands.
+
+ `surface.h' Shaded surface plots.
+
+ `data_mask.h' Helper class for data pruning.
+
+ `data_file.h' Class for storing and representing data.
+
+ `data_bins.h' Class for sorting and counting data.
+
+ `geometry.h' Latitudes and longitudes; spherical plotting, arcs,
+polygons, and polyhedra; hyperbolic arcs.
+
+
+
+`Color_Base.h' The Color implementation interface.
+
+ `Color_CMY.h' The CMY color model.
+
+ `Color_CMYK.h' The CMYK color model.
+
+ `Color_Gray.h' The Gray color model.
+
+ `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.
+
+ `Color_RGB.h' The RGB color model.
+
+ `Color_Sep.h' Classes for CMYK separation.
+
+ `active_screen.h' Simple manipulator for the active screen.
+
+ `picture_data.h' Picture implementation: two `screen' s
+(representing the `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 `picture'
+environment in the output file. For simplicity, the `screen's and
+dimensions are public; encapsulation from the user results from
+"hiding" this header.
+
+
+
+Declaration-style attributes are maintained with functions returning
+static references: `the_angle_style()', `the_arrowhead_style()',
+`the_label_style()', `the_mark_size()', `the_paint_style()', and
+`the_path_style()'. Each function is declared in the analogously-named
+header.
+
+ `angle_units.h' Angular modes: `radians' , `revolutions', and
+`degrees'.
+
+ `arrow_style.h' Arrow head style data: width, ratio, and inset.
+
+ `label_style.h' Text object style: Label and mask colors, padding,
+border color and width, alignment, font size, font face, and angle.
+
+ `marker_style.h' Dot and tick sizes.
+
+ `paint_style.h' Line and base pens, fill color.
+
+ `path_style.h' Solid, dashed, dotted lines.
+
+ `pen_data.h' The pen class.
+
+
+
+`arrow_data.h' Arrow representation.
+
+ `facet.h' Shaded surface elements.
+
+ `label_data.h' Text (label and marker) objects.
+
+ `legend_item.h' Items for `legend' s.
+
+ `path_data.h' Path implementation.
+
+ `spline.h' The natural spline class.
+
+ `spline_data.h' Templates for quadratic and cubic splines.
+
+
+
+Elements in a `screen' are represented polymorphically as "`tile's", of
+which there are six types: `glyph' (textual elements), `pen_arrow'
+(arrows), `pen_fill' (filled regions), `pen_line' (path-like elements),
+`verbatim' (raw text), and `legend_tile' (legends).
+
+ Border and background shape are dictated by the `screen_mask' class.
+The cropping algorithm assumes the contour of a screen mask is convex.
+
+ `affine.h' Affine maps.
+
+ `cropping.h' Screen mask cropping.
+
+ `glyph.h' Markers and labels.
+
+ `legend_tile.h' Screen representation of a `legend' .
+
+ `mask_diamond.h' Screen diamond mask.
+
+ `mask_ellipse.h' Screen elliptical mask.
+
+ `mask_rectangle.h' Screen rectangular mask.
+
+ `pen_arrow.h' Arrows.
+
+ `pen_fill.h' Filled regions.
+
+ `pen_line.h' Paths.
+
+ `screen_data.h' Screen implementation class.
+
+ `screen_mask.h' Screen mask interface.
+
+ `tile.h' Screen element interface.
+
+ `verbatim.h' Text in output stream.
+
+
+
+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 `format' interface for the desired file type. Paths
+and filled regions may be implemented however the output type dictates.
+
+ `eepic.h' eepic macros.
+
+ `fmt_template.h' "skeleton" header for new output formats.
+
+ `format.h' The output interface.
+
+ `pst.h' PSTricks macros.
+
+ `tikz.h' tikz macros.
+
+
+
+`Color_Utils.h' Functions for setting color channel densities.
+
+ `clipping.h' The clip box.
+
+ `constants.h' Global constants: Line widths; dot, tick, and dash
+sizes; arrowhead parameters; miscellaneous numerical constants and
+internal parameters.
+
+ `crop_algorithms.h' Path and loop clipping templates.
+
+ `deriv.h' Finite difference template.
+
+ `edge_data.h' Path element representation template.
+
+ `errors.h' Warning and error messages.
+
+ `frac.h' Rational numbers and operators.
+
+ `halfspace.h' Halfspace cutting.
+
+ `hatching.h' Filling regions in eepic.
+
+ `lens.h' Camera lenses.
+
+ `map.h' Wrappers for templated plotting.
+
+ `plot_algorithms.h' Plotting templates.
+
+ `screen_crop.h' Crop paths and loops.
+
+ `utils.h' Truncation, date and time, line breaking.
+
+
+File: epix.info, Node: Software Freedom, Next: Acknowledgments, Prev: Advanced Topics, Up: Top
+
+Appendix A Software Freedom
+***************************
+
+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):
+
+ * (GPL 0) To run a program for any purpose.
+
+ * (GPL 1) To study how the program works, and adapt it to your
+ needs.
+
+ * (GPL 2) To redistribute copies of the program.
+
+ * (GPL 3) To improve the program, and release improvements to the
+ public, so that the whole community benefits.
+
+
+ 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.
+
+ 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.
+
+ 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 `http://www.fsf.org',
+to learn more about free software and how you can contribute to its
+development and adoption.
+
+
+File: epix.info, Node: Acknowledgments, Next: Function Index, Prev: Software Freedom, Up: Top
+
+Appendix 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:
+
+ *Infrastructure* Donald Knuth, Conrad Kwok, Leslie Lamport, Tim
+Morgan, Piet van Oostrum, Sunil Podar, Richard Stallman, Till Tantau,
+Herbert Voss, Timothy van Zandt
+
+ *Enhancements* Jay Belanger, Robin Blume-Kohout, Julian Gilbey,
+Marcus Hanwell, Yvon Henel, Svend Daugaard Pedersen, Andrew Sterian
+
+ *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)
+
+ *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
+
+
+File: epix.info, Node: Function Index, Next: Concept Index, Prev: Acknowledgments, Up: Top
+
+Function Index
+**************
+
+
+* Menu:
+
+* aarrow: Creating and Drawing Objects.
+ (line 248)
+* Acos: More About C++. (line 112)
+* activate: Scene Attributes. (line 161)
+* affine: Scene Attributes. (line 271)
+* apply: Scene Attributes. (line 307)
+* arc: Creating and Drawing Objects.
+ (line 167)
+* arc_arrow: Creating and Drawing Objects.
+ (line 248)
+* arc_measure: Creating and Drawing Objects.
+ (line 193)
+* arrow: Creating and Drawing Objects.
+ (line 242)
+* arrow_inset: Creating and Drawing Objects.
+ (line 235)
+* arrow_ratio: Creating and Drawing Objects.
+ (line 235)
+* arrow_width: Creating and Drawing Objects.
+ (line 235)
+* Asin: More About C++. (line 112)
+* Atan: More About C++. (line 112)
+* axis: Creating and Drawing Objects.
+ (line 275)
+* axis.align: Creating and Drawing Objects.
+ (line 284)
+* axis.align_labels: Creating and Drawing Objects.
+ (line 296)
+* axis.dec: Creating and Drawing Objects.
+ (line 296)
+* axis.draw: Creating and Drawing Objects.
+ (line 342)
+* axis.draw_labels: Creating and Drawing Objects.
+ (line 342)
+* axis.draw_ticks: Creating and Drawing Objects.
+ (line 342)
+* axis.frac: Creating and Drawing Objects.
+ (line 296)
+* axis.label_rep: Creating and Drawing Objects.
+ (line 307)
+* axis.precision: Creating and Drawing Objects.
+ (line 296)
+* axis.sci: Creating and Drawing Objects.
+ (line 296)
+* axis.subdivide: Creating and Drawing Objects.
+ (line 284)
+* axis.tag: Creating and Drawing Objects.
+ (line 323)
+* axis.tag235: Creating and Drawing Objects.
+ (line 323)
+* axis.tags: Creating and Drawing Objects.
+ (line 323)
+* axis.tick_ratio: Creating and Drawing Objects.
+ (line 284)
+* axis.trig: Creating and Drawing Objects.
+ (line 296)
+* axis.unmark: Creating and Drawing Objects.
+ (line 296)
+* axis.untag: Creating and Drawing Objects.
+ (line 323)
+* axis_break: Creating and Drawing Objects.
+ (line 394)
+* back_arc: Creating and Drawing Objects.
+ (line 851)
+* back_arc2: Creating and Drawing Objects.
+ (line 851)
+* back_cube: Creating and Drawing Objects.
+ (line 857)
+* back_dodeca: Creating and Drawing Objects.
+ (line 857)
+* back_icosa: Creating and Drawing Objects.
+ (line 857)
+* back_latitude: Creating and Drawing Objects.
+ (line 837)
+* back_line: Creating and Drawing Objects.
+ (line 851)
+* back_longitude: Creating and Drawing Objects.
+ (line 837)
+* back_octa: Creating and Drawing Objects.
+ (line 857)
+* back_tetra: Creating and Drawing Objects.
+ (line 857)
+* back_triangle: Creating and Drawing Objects.
+ (line 857)
+* backing: Scene Attributes. (line 252)
+* backplot_N: Creating and Drawing Objects.
+ (line 879)
+* backplot_R: Creating and Drawing Objects.
+ (line 879)
+* backplot_S: Creating and Drawing Objects.
+ (line 879)
+* bbold: Drawing Attributes. (line 33)
+* bbox: Drawing Attributes. (line 174)
+* begin: File Structure. (line 12)
+* Black: Color. (line 23)
+* Blue: Color. (line 23)
+* bold: Drawing Attributes. (line 33)
+* border: Scene Attributes. (line 252)
+* bottom_axis: Creating and Drawing Objects.
+ (line 332)
+* bounding_box: Picture Size and Aspect Ratio.
+ (line 24)
+* box: Drawing Attributes. (line 174)
+* Camera.at: Scene Attributes. (line 75)
+* Camera.clip_range: Scene Attributes. (line 75)
+* Camera.focus: Scene Attributes. (line 75)
+* Camera.look_at: Scene Attributes. (line 75)
+* Camera.pan: Scene Attributes. (line 75)
+* Camera.range: Scene Attributes. (line 75)
+* Camera.roll: Scene Attributes. (line 75)
+* Camera.tilt: Scene Attributes. (line 75)
+* canvas: Scene Attributes. (line 183)
+* cb: More About C++. (line 123)
+* circ: Drawing Attributes. (line 174)
+* circle: Creating and Drawing Objects.
+ (line 145)
+* Circle: Creating and Drawing Objects.
+ (line 70)
+* cis: Creating and Drawing Objects.
+ (line 27)
+* clip_box: Scene Attributes. (line 127)
+* clip_face: Scene Attributes. (line 137)
+* clip_restore: Scene Attributes. (line 137)
+* clip_slice: Scene Attributes. (line 137)
+* clip_to: Scene Attributes. (line 127)
+* CMY: Color. (line 29)
+* CMY_Black: Color. (line 29)
+* CMY_White: Color. (line 29)
+* cmyk: Drawing Attributes. (line 210)
+* CMYK: Color. (line 29)
+* Color.alpha: Color. (line 73)
+* Color.blend: Color. (line 73)
+* Color.filter: Color. (line 73)
+* Color.invert: Color. (line 73)
+* Color.superpose: Color. (line 73)
+* Cos: More About C++. (line 112)
+* Cot: More About C++. (line 112)
+* crop: Scene Attributes. (line 239)
+* crop_diamond: Scene Attributes. (line 239)
+* crop_ellipse: Scene Attributes. (line 239)
+* Csc: More About C++. (line 112)
+* Cyan: Color. (line 29)
+* cyl: Creating and Drawing Objects.
+ (line 27)
+* dart: Creating and Drawing Objects.
+ (line 248)
+* dart_field: Creating and Drawing Objects.
+ (line 793)
+* dash_size: Drawing Attributes. (line 44)
+* dashed: Drawing Attributes. (line 53)
+* data_bins: Creating and Drawing Objects.
+ (line 1006)
+* data_bins.bar_chart: Creating and Drawing Objects.
+ (line 1016)
+* data_bins.cut: Creating and Drawing Objects.
+ (line 1006)
+* data_bins.histogram: Creating and Drawing Objects.
+ (line 1016)
+* data_bins.plot: Creating and Drawing Objects.
+ (line 1016)
+* data_bins.read: Creating and Drawing Objects.
+ (line 1006)
+* data_file: Creating and Drawing Objects.
+ (line 931)
+* data_file.avg: Creating and Drawing Objects.
+ (line 950)
+* data_file.column: Creating and Drawing Objects.
+ (line 973)
+* data_file.covar: Creating and Drawing Objects.
+ (line 950)
+* data_file.dot: Creating and Drawing Objects.
+ (line 950)
+* data_file.plot: Creating and Drawing Objects.
+ (line 958)
+* data_file.precision: Creating and Drawing Objects.
+ (line 967)
+* data_file.read: Creating and Drawing Objects.
+ (line 931)
+* data_file.regression: Creating and Drawing Objects.
+ (line 950)
+* data_file.transform: Creating and Drawing Objects.
+ (line 945)
+* data_file.var: Creating and Drawing Objects.
+ (line 950)
+* data_file.write: Creating and Drawing Objects.
+ (line 967)
+* data_mask: Creating and Drawing Objects.
+ (line 988)
+* data_mask.prune: Creating and Drawing Objects.
+ (line 996)
+* ddot: Drawing Attributes. (line 174)
+* deactivate: Scene Attributes. (line 161)
+* Deriv: Creating and Drawing Objects.
+ (line 745)
+* Deriv.eval: Creating and Drawing Objects.
+ (line 745)
+* Deriv.left: Creating and Drawing Objects.
+ (line 745)
+* Deriv.right: Creating and Drawing Objects.
+ (line 745)
+* disk_line: Creating and Drawing Objects.
+ (line 826)
+* domain: Creating and Drawing Objects.
+ (line 512)
+* domain.resize: Creating and Drawing Objects.
+ (line 531)
+* domain.slice: Creating and Drawing Objects.
+ (line 531)
+* domain.slices: Creating and Drawing Objects.
+ (line 531)
+* domain_list: Creating and Drawing Objects.
+ (line 668)
+* domain_list.add: Creating and Drawing Objects.
+ (line 668)
+* dot: Drawing Attributes. (line 174)
+* dot_size: Drawing Attributes. (line 185)
+* dotted: Drawing Attributes. (line 53)
+* draw: Creating and Drawing Objects.
+ (line 59)
+* ellipse: Creating and Drawing Objects.
+ (line 167)
+* ellipse_bottom: Creating and Drawing Objects.
+ (line 180)
+* ellipse_left: Creating and Drawing Objects.
+ (line 180)
+* ellipse_right: Creating and Drawing Objects.
+ (line 180)
+* ellipse_top: Creating and Drawing Objects.
+ (line 180)
+* end: File Structure. (line 12)
+* envelope: Creating and Drawing Objects.
+ (line 768)
+* extract: Scene Attributes. (line 183)
+* extract_diamond: Scene Attributes. (line 190)
+* extract_ellipse: Scene Attributes. (line 190)
+* fill: Drawing Attributes. (line 12)
+* flow: Creating and Drawing Objects.
+ (line 778)
+* font_face: Drawing Attributes. (line 144)
+* font_size: Drawing Attributes. (line 144)
+* fractal: Creating and Drawing Objects.
+ (line 214)
+* frame: Creating and Drawing Objects.
+ (line 134)
+* front_arc: Creating and Drawing Objects.
+ (line 851)
+* front_arc2: Creating and Drawing Objects.
+ (line 851)
+* front_cube: Creating and Drawing Objects.
+ (line 857)
+* front_dodeca: Creating and Drawing Objects.
+ (line 857)
+* front_icosa: Creating and Drawing Objects.
+ (line 857)
+* front_line: Creating and Drawing Objects.
+ (line 851)
+* front_octa: Creating and Drawing Objects.
+ (line 857)
+* front_tetra: Creating and Drawing Objects.
+ (line 857)
+* front_triangle: Creating and Drawing Objects.
+ (line 857)
+* frontplot_N: Creating and Drawing Objects.
+ (line 879)
+* frontplot_R: Creating and Drawing Objects.
+ (line 879)
+* frontplot_S: Creating and Drawing Objects.
+ (line 879)
+* Gray: Color. (line 29)
+* Green: Color. (line 23)
+* grid: Creating and Drawing Objects.
+ (line 405)
+* h_axis: Creating and Drawing Objects.
+ (line 352)
+* h_axis_labels: Creating and Drawing Objects.
+ (line 368)
+* h_axis_log_labels: Creating and Drawing Objects.
+ (line 368)
+* h_axis_log_masklabels: Creating and Drawing Objects.
+ (line 368)
+* h_axis_masklabels: Creating and Drawing Objects.
+ (line 368)
+* h_error_bar: Creating and Drawing Objects.
+ (line 1047)
+* h_log_axis: Creating and Drawing Objects.
+ (line 352)
+* h_scale: Scene Attributes. (line 282)
+* h_shear: Scene Attributes. (line 282)
+* hyperbolic_line: Creating and Drawing Objects.
+ (line 826)
+* import: Scene Attributes. (line 172)
+* include: C++ Basics. (line 37)
+* inf: Creating and Drawing Objects.
+ (line 731)
+* inlay: Scene Attributes. (line 204)
+* inlay_horizontal: Scene Attributes. (line 204)
+* inlay_vertical: Scene Attributes. (line 204)
+* inset: Scene Attributes. (line 172)
+* Integral: Creating and Drawing Objects.
+ (line 745)
+* Integral.eval: Creating and Drawing Objects.
+ (line 745)
+* J: Creating and Drawing Objects.
+ (line 38)
+* label <1>: Drawing Attributes. (line 99)
+* label: Layout Tricks. (line 46)
+* label_border: Drawing Attributes. (line 160)
+* label_color: Drawing Attributes. (line 160)
+* label_mask: Drawing Attributes. (line 160)
+* label_pad: Drawing Attributes. (line 160)
+* latitude: Creating and Drawing Objects.
+ (line 837)
+* left_axis: Creating and Drawing Objects.
+ (line 332)
+* legend: Creating and Drawing Objects.
+ (line 1083)
+* legend.backing: Creating and Drawing Objects.
+ (line 1083)
+* legend.border: Creating and Drawing Objects.
+ (line 1083)
+* legend.draw: Creating and Drawing Objects.
+ (line 1115)
+* legend.fill_item: Creating and Drawing Objects.
+ (line 1101)
+* legend.item_border: Creating and Drawing Objects.
+ (line 1083)
+* legend.key_size: Creating and Drawing Objects.
+ (line 1083)
+* legend.label_skip: Creating and Drawing Objects.
+ (line 1083)
+* legend.mark_item: Creating and Drawing Objects.
+ (line 1101)
+* legend.path_item: Creating and Drawing Objects.
+ (line 1101)
+* Line: Creating and Drawing Objects.
+ (line 145)
+* line: Creating and Drawing Objects.
+ (line 145)
+* line_style: Drawing Attributes. (line 44)
+* log1_grid: Creating and Drawing Objects.
+ (line 411)
+* log2_grid: Creating and Drawing Objects.
+ (line 411)
+* log_grid: Creating and Drawing Objects.
+ (line 411)
+* longitude: Creating and Drawing Objects.
+ (line 837)
+* Magenta: Color. (line 29)
+* move_to: Creating and Drawing Objects.
+ (line 59)
+* newton: Creating and Drawing Objects.
+ (line 731)
+* no_label_border: Drawing Attributes. (line 160)
+* nofill: Drawing Attributes. (line 12)
+* ode_plot: Creating and Drawing Objects.
+ (line 778)
+* P: Creating and Drawing Objects.
+ (line 27)
+* P.x1: Creating and Drawing Objects.
+ (line 38)
+* P.x2: Creating and Drawing Objects.
+ (line 38)
+* P.x3: Creating and Drawing Objects.
+ (line 38)
+* path: Creating and Drawing Objects.
+ (line 437)
+* path.close: Creating and Drawing Objects.
+ (line 468)
+* path.draw: Creating and Drawing Objects.
+ (line 468)
+* path.fill: Creating and Drawing Objects.
+ (line 468)
+* pen <1>: Creating and Drawing Objects.
+ (line 422)
+* pen: Drawing Attributes. (line 23)
+* picture <1>: Picture Size and Aspect Ratio.
+ (line 24)
+* picture: File Structure. (line 12)
+* plain: Drawing Attributes. (line 33)
+* Plane: Creating and Drawing Objects.
+ (line 85)
+* plot: Creating and Drawing Objects.
+ (line 495)
+* polar: Creating and Drawing Objects.
+ (line 27)
+* polar_grid: Creating and Drawing Objects.
+ (line 405)
+* polarplot: Creating and Drawing Objects.
+ (line 495)
+* post_write: C++ Basics. (line 122)
+* postcomp: Scene Attributes. (line 282)
+* pre_write: C++ Basics. (line 122)
+* pt_to_screen: Scene Attributes. (line 214)
+* quad: Creating and Drawing Objects.
+ (line 145)
+* rect: Creating and Drawing Objects.
+ (line 145)
+* Red: Color. (line 23)
+* reflect: Scene Attributes. (line 282)
+* rgb: Drawing Attributes. (line 210)
+* RGB: Color. (line 23)
+* riemann_sum: Creating and Drawing Objects.
+ (line 756)
+* right_angle: Creating and Drawing Objects.
+ (line 193)
+* right_axis: Creating and Drawing Objects.
+ (line 332)
+* ring: Drawing Attributes. (line 174)
+* rotate: Scene Attributes. (line 282)
+* scale <1>: Creating and Drawing Objects.
+ (line 59)
+* scale: Scene Attributes. (line 282)
+* scenery: Creating and Drawing Objects.
+ (line 680)
+* scenery.add: Creating and Drawing Objects.
+ (line 680)
+* scenery.draw: Creating and Drawing Objects.
+ (line 680)
+* Sec: More About C++. (line 112)
+* Segment: Creating and Drawing Objects.
+ (line 90)
+* set_crop: Scene Attributes. (line 239)
+* sgn: More About C++. (line 123)
+* shadeplot: Creating and Drawing Objects.
+ (line 495)
+* shift <1>: Creating and Drawing Objects.
+ (line 59)
+* shift: Scene Attributes. (line 282)
+* Sin: More About C++. (line 112)
+* sinx: More About C++. (line 123)
+* slope_field: Creating and Drawing Objects.
+ (line 793)
+* solid: Drawing Attributes. (line 53)
+* sph: Creating and Drawing Objects.
+ (line 27)
+* Sphere: Creating and Drawing Objects.
+ (line 93)
+* spline: Creating and Drawing Objects.
+ (line 167)
+* spot: Drawing Attributes. (line 174)
+* sup: Creating and Drawing Objects.
+ (line 731)
+* surface: Creating and Drawing Objects.
+ (line 616)
+* surface_rev: Creating and Drawing Objects.
+ (line 627)
+* Tan: More About C++. (line 112)
+* tan_field: Creating and Drawing Objects.
+ (line 768)
+* tan_line: Creating and Drawing Objects.
+ (line 768)
+* top_axis: Creating and Drawing Objects.
+ (line 332)
+* triangle: Creating and Drawing Objects.
+ (line 145)
+* unitlength: Picture Size and Aspect Ratio.
+ (line 24)
+* v_axis: Creating and Drawing Objects.
+ (line 352)
+* v_axis_labels: Creating and Drawing Objects.
+ (line 368)
+* v_axis_log_labels: Creating and Drawing Objects.
+ (line 368)
+* v_axis_log_masklabels: Creating and Drawing Objects.
+ (line 368)
+* v_axis_masklabels: Creating and Drawing Objects.
+ (line 368)
+* v_error_bar: Creating and Drawing Objects.
+ (line 1047)
+* v_log_axis: Creating and Drawing Objects.
+ (line 352)
+* v_scale: Scene Attributes. (line 282)
+* v_shear: Scene Attributes. (line 282)
+* vector_field: Creating and Drawing Objects.
+ (line 793)
+* White: Color. (line 23)
+* write: C++ Basics. (line 122)
+* Yellow: Color. (line 29)
+* zero: More About C++. (line 123)
+
+
+File: epix.info, Node: Concept Index, Prev: Function Index, Up: Top
+
+Concept Index
+*************
+
+
+* Menu:
+
+* Affine map: Scene Attributes. (line 264)
+* Affine map!action on labels: Drawing Attributes. (line 130)
+* Angle units <1>: Drawing Attributes. (line 121)
+* Angle units: Scene Attributes. (line 14)
+* Angular mode <1>: More About C++. (line 112)
+* Angular mode: Creating and Drawing Objects.
+ (line 27)
+* Animation: Animation. (line 6)
+* Arrow: Creating and Drawing Objects.
+ (line 231)
+* Axes: Creating and Drawing Objects.
+ (line 257)
+* Axes!broken: Creating and Drawing Objects.
+ (line 390)
+* Axes!labeling: Creating and Drawing Objects.
+ (line 257)
+* Axes!logarithmic: Creating and Drawing Objects.
+ (line 350)
+* Bar Charts: Creating and Drawing Objects.
+ (line 1013)
+* Bounding box: Scene Attributes. (line 156)
+* Camera <1>: Hidden Object Removal.
+ (line 13)
+* Camera: Scene Attributes. (line 21)
+* Camera!color separation: Scene Attributes. (line 94)
+* Camera!lens: Scene Attributes. (line 57)
+* Camera!manipulation: Scene Attributes. (line 69)
+* Camera!manipulation of: Scene Attributes. (line 116)
+* Camera!viewpoint: Scene Attributes. (line 31)
+* canvas: The Drawing Model. (line 11)
+* Circle: Creating and Drawing Objects.
+ (line 69)
+* Classes: More About C++. (line 149)
+* Clipping: Scene Attributes. (line 120)
+* Color <1>: Drawing Attributes. (line 215)
+* Color: Color. (line 6)
+* Color!separation: Scene Attributes. (line 94)
+* Color!surface plotting: Creating and Drawing Objects.
+ (line 700)
+* Color!transparency: Color. (line 65)
+* Conditional statement: More About C++. (line 22)
+* Cplusplus@C++ <1>: More About C++. (line 6)
+* Cplusplus@C++: C++ Basics. (line 6)
+* Cropping: Scene Attributes. (line 231)
+* Data plotting: Creating and Drawing Objects.
+ (line 897)
+* Domain: Creating and Drawing Objects.
+ (line 509)
+* Emacs@emacs <1>: Animation. (line 19)
+* Emacs@emacs <2>: C++ Basics. (line 16)
+* Emacs@emacs <3>: Running ePiX. (line 50)
+* Emacs@emacs: Software Dependencies.
+ (line 36)
+* Error bars: Creating and Drawing Objects.
+ (line 1046)
+* Filling: Drawing Attributes. (line 11)
+* Fonts: Drawing Attributes. (line 142)
+* Free software <1>: Software Freedom. (line 6)
+* Free software: Introduction. (line 42)
+* Function: More About C++. (line 22)
+* Function!call syntax: More About C++. (line 186)
+* Function!class member: More About C++. (line 156)
+* Function!mathematical: More About C++. (line 108)
+* Function!overloaded: More About C++. (line 229)
+* Function!returning void: More About C++. (line 84)
+* Graph paper: Creating and Drawing Objects.
+ (line 422)
+* Graphical interface: Tutorial. (line 13)
+* Hidden object removal: Hidden Object Removal.
+ (line 6)
+* Histograms: Creating and Drawing Objects.
+ (line 1013)
+* Input file!comment in: More About C++. (line 337)
+* Input file!conditional compilation: More About C++. (line 281)
+* Installation <1>: Installation. (line 31)
+* Installation: Software Dependencies.
+ (line 6)
+* Intersection: Creating and Drawing Objects.
+ (line 109)
+* Labels <1>: More About C++. (line 310)
+* Labels: Drawing Attributes. (line 80)
+* Labels!alignment: Drawing Attributes. (line 80)
+* Labels!axis: Creating and Drawing Objects.
+ (line 257)
+* Labels!backslash in: Drawing Attributes. (line 205)
+* Labels!fonts in: Drawing Attributes. (line 142)
+* Labels!in double quotes: Drawing Attributes. (line 205)
+* Labels!rotated: Drawing Attributes. (line 121)
+* Layout <1>: Scene Attributes. (line 148)
+* Layout: Layout Tricks. (line 6)
+* Legends: Creating and Drawing Objects.
+ (line 1072)
+* Mac OS X: Software Dependencies.
+ (line 6)
+* Marker types: Drawing Attributes. (line 172)
+* Output format: File Structure. (line 31)
+* Path: Drawing Attributes. (line 11)
+* Path!class: Creating and Drawing Objects.
+ (line 433)
+* Path!filled: Drawing Attributes. (line 11)
+* Path!fractal: Creating and Drawing Objects.
+ (line 206)
+* Path!style: Drawing Attributes. (line 41)
+* Picture!aspect ratio: Picture Size and Aspect Ratio.
+ (line 44)
+* Picture!bounding box: Picture Size and Aspect Ratio.
+ (line 44)
+* Picture!offset: Picture Size and Aspect Ratio.
+ (line 6)
+* Picture!size: Picture Size and Aspect Ratio.
+ (line 6)
+* Plane: Creating and Drawing Objects.
+ (line 85)
+* Plotting: Creating and Drawing Objects.
+ (line 480)
+* Plotting!calculus: Creating and Drawing Objects.
+ (line 721)
+* Plotting!data: Creating and Drawing Objects.
+ (line 897)
+* Plotting!spherical: Creating and Drawing Objects.
+ (line 833)
+* Plotting!surface: Creating and Drawing Objects.
+ (line 605)
+* Point: Creating and Drawing Objects.
+ (line 14)
+* Pointer: More About C++. (line 52)
+* post_write: C++ Basics. (line 122)
+* pre_write: C++ Basics. (line 122)
+* Preamble: File Structure. (line 10)
+* Screen: Scene Attributes. (line 21)
+* Screen!active: Scene Attributes. (line 148)
+* Segment: Creating and Drawing Objects.
+ (line 90)
+* Sphere: Creating and Drawing Objects.
+ (line 93)
+* Stereograms: Layout Tricks. (line 8)
+* Variable!local: More About C++. (line 239)
+* Variable!names: More About C++. (line 34)
+* Variable!pointer: More About C++. (line 52)
+* Variable!reference: More About C++. (line 186)
+* Variable!type of: More About C++. (line 45)
+* Viewpoint: Scene Attributes. (line 31)
+* Windows operating system: Software Dependencies.
+ (line 40)
+* write: C++ Basics. (line 122)
+
+
+
+Tag Table:
+Node: Top185
+Node: Introduction1105
+Node: Changes in Version 1.24664
+Node: Software Dependencies8541
+Ref: section:software_deps8714
+Node: Installation11086
+Node: Getting Started12670
+Ref: chapter:started12806
+Node: Running `ePiX'13556
+Ref: section:running13709
+Node: The Drawing Model16861
+Ref: section:overview17013
+Node: Tutorial19428
+Ref: section:tutorial19560
+Ref: taylor_poly24927
+Node: `C++' Basics26756
+Ref: fig:captioned32767
+Node: Animation33131
+Ref: section:animation33262
+Node: Layout Tricks34998
+Ref: section:layout35116
+Node: Reference Manual37114
+Ref: chapter:ref-man37255
+Node: File Structure38952
+Node: Picture Size and Aspect Ratio41705
+Ref: page:scaling44202
+Node: Color44417
+Ref: section:color44557
+Ref: fig:densities46382
+Node: Scene Attributes47847
+Ref: fig:camera48882
+Ref: truesize56642
+Node: Drawing Attributes62495
+Ref: table:marker70626
+Node: Creating and Drawing Objects71285
+Ref: fig:fractal81596
+Ref: fig:plot96868
+Ref: non-eucl107182
+Node: More About `C++'121128
+Ref: references130049
+Node: Attribute Quick Reference137418
+Ref: section:quickref137580
+Node: Advanced Topics140341
+Ref: chapter:adv140481
+Node: Hidden Object Removal140765
+Ref: section:hidden140932
+Node: Extensions142805
+Ref: section:extensions142953
+Node: Programmer's Guide149302
+Ref: section:programmers149436
+Ref: section:interface152502
+Node: Software Freedom158743
+Node: Acknowledgments164009
+Node: Function Index165447
+Node: Concept Index200200
+
+End Tag Table