%% Version 1.2.0 \documentclass[12pt]{book} \usepackage{amsmath,latexsym,epic,eepic,pstricks,xcolor,comment} \usepackage[dvips,hyperref]{hyperref} \usepackage{makeidx} \makeindex \renewcommand{\thefigure}{\arabic{chapter}.\arabic{figure}} \newcommand{\code}[1]{\texttt{#1}} \newcommand{\filename}[1]{\texttt{#1}} \newcommand{\Key}[1]{\texttt{#1}} \newcommand{\URL}[1]{\texttt{#1}} %% \setlength{\topmargin}{0.5in} \newcommand{\ePiX}{\code{ePiX}} \newcommand{\ext}{\code{ePiX\_ext}} \newcommand{\epix}{\code{epix}} \newcommand{\eepic}{\code{eepic}} \newcommand{\C}{\code{C}} \newcommand{\CXX}{\code{C++}} \newcommand{\pyepix}{\code{Pyepix}} \DeclareMathOperator{\clip}{clip} \newcommand{\Header}[1]{\smallskip\noindent\texttt{#1}% \index{Header file!{#1}@\texttt{#1}}\quad} %% Substitution commands easily removable by sed for texinfo: %% Remove recalcitrant chunks, \newcommand{\texicomment}{} \newcommand{\texicommentend}{} %% mark simple math, \newcommand{\teximath}[1]{$#1$} %% make function index entries, \newcommand{\findex}[1]{} %% top-level division (first argument for texinfo node name) \newcommand{\texinfochapter}[2]{\chapter{#2}} \newcommand{\texinfoappendix}[2]{\chapter{#2}} %%\renewcommand{\subsection*}[1]{\subsection{#1}} \title{ \ePiX\ Tutorial and \\ Reference Manual} \author{Andrew D. Hwang \\ Department\ of Math and CS \\ College of the Holy Cross} \date{Version 1.2, September, 2007} \begin{document} \maketitle \tableofcontents \texinfochapter{1}{Introduction} \ePiX, a collection of batch utilities, creates mathematically accurate figures, plots, and animations containing \LaTeX\ typography. The input syntax is easy to learn, and the user interface resembles that of \LaTeX\ itself: You prepare a scene description in a text editor, then ``compile'' the input file into a picture. \LaTeX- and web-compatible output types include a \LaTeX\ picture-like environment written with \code{PSTricks}, \code{tikz}, or \code{eepic} macros; vector images (\code{eps}, \code{ps}, and~\code{pdf}); and bitmapped images and movies (\code{png}, \code{mng}, and~\code{gif}). \ePiX's strengths include: \begin{itemize} \item Quality of output: \ePiX\ creates accurate, publication-quality figures whose appearance matches that of \LaTeX. Typography may be put in a figure as easily as in an ordinary \LaTeX\ document. \item Ease of use: Figure objects and their attributes are specified by simple, descriptive commands. \item Flexibility: Objects are described by attributes and Cartesian location; as in \LaTeX, printed appearance is determined when the figure is compiled. A well-designed figure can be altered dramatically, yet precisely, with command-line switches or minor changes to the input file. \item Power and extendibility: \ePiX\ inherits the power of \CXX\ as a programming language; variables, data structures, loops, and recursion can be used to draw complicated plots and figures with just a few lines of input. External code can be incorporated in a figure with a command line option or by using a Makefile. \item Economy of storage and transmission: For a document containing many figures, a compressed tar file of the \LaTeX\ sources and \ePiX\ files is typically a few percent the size of the compressed PostScript file. \item License: \ePiX\ is \emph{free software}.\index{Free software} You are granted the right to use the program for whatever purpose, and to inspect, modify, and re-distribute the source code, so long as you do not restrict the rights of others to do the same. In short, the license is similar to the terms under which theorems are published. \end{itemize} \ePiX\ facilitates logical, as opposed to visual, structuring of mathematical figures, analogous to the relationship between \LaTeX\ and a word processor. A few stylistic defaults streamline the creation of simple figures, but there are few internal restrictions on the contents or appearance of a figure; aesthetic and practical decisions are left to you. If you are a: \begin{itemize} \item Potential user, you may wish to skip immediately to ``Software Dependencies'' before investing additional time. \item New user, proceed from here until you have enough understanding to run the software, then experiment with the samples files while reading Chapter~\ref{chapter:started}, or return to the manual as needed. \item More advanced user, browse at will, probably starting with Chapter~\ref{chapter:ref-man}. \end{itemize} This manual is relatively conversational, and occasionally redundant, especially between portions meant for readers at different levels of familiarity. Throughout, you are assumed to be familiar with \LaTeX\ and basic linear algebra: the description of points, vectors, lines, and planes in three-dimensional space. Other material, such as \CXX\ syntax, is introduced as needed. \section{Changes in Version~1.2} \ePiX~1.2.x has been written almost entirely from scratch. The conceptual model is unchanged, but there are a few changes of syntax. If you're new to~\ePiX, please skip straight to Section~\ref{section:software_deps}. \subsection{Syntax Changes} Except as noted below, \ePiX~1.0 files will compile under Version~1.2. Generally, global variables have been deprecated or removed, and should be replaced by function calls in new files. The following changes are either required, or else strongly recommended (and may become mandatory). \begin{itemize} \item (Mandatory) The global variable \verb+tix+ in a \filename{flix} file must be manipulated through the function \verb+tix()+. \item (Mandatory) The command \code{use\_pstricks()} is obsolete. PSTricks output is obtained systematically as an output format. \item (Mandatory) Deprecated ``aliases'' no longer exist: \code{triple} (for the \code{P} class), \code{D}~(for \code{Deriv}), and \code{I}~(for \code{Integral}). Lowercase trig function names conflicted with the standard namespace and have been removed. \item (Mandatory) Geometric object commands (\code{circle}, \code{plane}, \code{segment}, and~\code{sphere}), which formerly created class objects, now perform drawing just as \code{ellipse}, \code{line}, \code{rect}, etc., do. The classes are available with capitalized names (\code{Circle}, etc.). \item (Mandatory) Camera orientation is controlled with functions named \code{tilt}, \code{pan}, and~\code{roll}; each rotates the camera about an axis through the viewpoint, not through the target. \item (Recommended) The global size variables \verb+x_min+, \verb+x_max+, \verb+y_min+, \verb+y_max+, \verb+x_size+, and \verb+y_size+ should be replaced by the function calls \verb+xmin()+, etc. (No underscores.) \item (Suggested) The camera may be accessed through the function \code{cam()}. \item (Suggested) The size and bounding box are given in one command, such as \code{picture(P(-1,0), P(1,1), "4x3in")}. The old syntax will be retained indefinitely. \end{itemize} \subsection{New Features} \begin{itemize} \item Output is cleanly separated from the internal representation. Figures may be written with a choice of macros---\code{PSTricks}, \code{tikz}, and \code{eepic} at present---and new output types are easily coded so long as the format supports arbitrary line segments, color, and the ability to place a \LaTeX\ box at a specified location. \item Colors are a manipulable data type, available in RGB, CMY, CMYK, and Gray models. \filename{xcolor}-style operations, such as color model conversion, blending, superposition, and inversion are provided. The camera has a filter which affects the colors of all scene elements. Filters performing CMYK separation are provided. \item Color filling is controlled with declarations, similarly to line colors in \ePiX~1.0. Arrows and markers of type spot, dot, ddot, and~circ are now colored like other markers. Parametric surfaces may be color-shaded. If a figure contains many shaded elements, a color-capable output format (e.g.\ \code{PSTricks}~or \code{tikz}) should be used for efficiency. Filled regions are implemented as fine hatching in \filename{eepic}. \item An \code{axis} class provides coordinate axes with labels in a variety of styles: decimals or scientific notation of specified precision, fractions, trig fractions, logarithmic labels in arbitrary (integer) base, and user-supplied styles. \item \ePiX~1.2.x performs page layout. Sub-figures may be manipulated flexibly. The sample files give several applications. \item Non-member intersection operators for circles, planes, spheres, and segments are provided. A ``non-generic'' intersection does not throw an exception, but instead returns an undrawable ``malformed'' object. \end{itemize} \section{Software Dependencies} \label{section:software_deps} \index{Installation|(} \index{Mac OS X} If you run GNU/Linux, a BSD, or Solaris, you probably have (and can surely install) all the external software needed to use \ePiX. On Mac~OS~X, you will need the Apple developer tools and an X~server (XCode and XDarwin on the Tiger disks), and the free~\code{fink} package manager to build a GNU environment. For Windows, you'll need to install Cygwin and several packages. Detailed instructions are given below. ``Under the hood'', an input file is successively converted to a \LaTeX\ picture; \code{dvi}; PostScript, \code{pdf}~or \code{eps}; and if desired, to a bitmapped image or movie. Four shell scripts---\epix, \code{laps}, \code{elaps}, and~\code{flix}---automate the various file format conversions. \ePiX\ consists of a \CXX\ library, header, and shell scripts, and requires GNU \code{bash} and a compiler \emph{for normal use}. For complete functionality, you need \code{g++} (Version~3.2 or later), \code{bash}, a text editor (\ePiX\ works particularly well with \code{emacs}), a \LaTeX\ distribution, \code{Ghostscript}, \code{gv} (or your favorite PS/PDF previewer), and \code{ImageMagick}. GNU \code{grep} and \code{sed} are good to have. You may need additional ``developer packages'' (\code{binutils}, \code{make}) in order to build \ePiX. The more up to date your software is, the better your experience is likely to be, but bleeding edge versions are not necessary, or even always desirable. Aside from their reliance on specific programs, \ePiX's shell scripts are written using Unix-style pathnames. Thus, the most straightforward way to use \ePiX\ is to install a GNU environment. Jay Belanger's \code{emacs} mode allows you to write, compile, and view \ePiX\ figures without leaving \code{emacs}. If you use another editor, you'll want to create template source files so you don't have to type boilerplate code each time you write a new figure. \index{Emacs@\code{emacs}} \subsection{Setting up an Environment Under Windows} \index{Windows operating system|(} \begin{comment} Version~1.0.4 of \ePiX\ has been implemented in Python~2.2 by Andrew Sterian, making \ePiX\ available on any platform that supports Python, and without requiring a \CXX~compiler or~\code{bash}. Python is a GPL-ed scripting language, and is available with a Windows installer and detailed instructions. The easiest alternative for Windows users is probably to install Python~2.2 or later (if necessary) and \code{Pyepix}. The \code{pyepix} project home page is: \URL{claymore.engineer.gvsu.edu/~steriana/Python/index.html} \end{comment} Cygwin can be used to run \ePiX\ under Windows. Download \filename{setup.exe} from \URL{www.cygwin.com}, then install the packages you need. The following are recommended, and sufficient for the actions described in this manual. \begin{verbatim} (Archive) bzip2, tar (Devel) binutils, coreutils, gcc, gcc-g++, make, sed (Editors) emacs, emacs-X11, vim (Graphics) ImageMagick, ghostscript-base, ghostscript-x11, gv (Publishing) tetex (all) (Shells) bash, bash-completion (X11) X-start-menu-icons, X-startup-scripts, XFree86-lib-compat, xorg-x11-fscl, xorg-x11-fsrv \end{verbatim} \index{Windows operating system|)} \section{Installation} \ePiX\ is distributed over the World-Wide Web as source code. Packages may be found at \URL{mathcs.holycross.edu/\~{}ahwang/epix/ePiX.html} The latest stable release is also on the CTAN mirrors, in the \code{graphics} directory. (Some users of Red Hat have reported file permission problems when unpacking the CTAN tarballs. If you encounter this difficulty, please try downloading the sources from the project main page.) Unpack the compressed tar file with the appropriate command: \begin{verbatim} tar -zxvf epix-x.y.z.tar.gz tar -jxvf epix-x.y.z.tar.bz2 \end{verbatim} (\code{x.y.z}~is the version number) or, if your \code{tar} doesn't do decompression, \begin{verbatim} gunzip -c epix-x.y.z.tar.gz | tar -xvf - bzcat epix-x.y.z.tar.bz2 | tar -xvf - \end{verbatim} \code{cd} to the source directory, \filename{epix-x.y.z}. The \filename{INSTALL} file contains detailed installation instructions. If you're impatient, the short of it is \code{./configure [--options]; make; make install}. Run \code{./configure --help} for a list of options. By default, \ePiX\ installs in subdirectories of \filename{/usr/local}; if you want to install elsewhere, supply \code{./configure} with the appropriate \code{--prefix}. You may also want to consult \filename{POST-INSTALL} for information on setting your \code{PATH} variable so your shell can find \ePiX. The manual and sample files are in \filename{/usr/local/share/doc/epix}. \index{Installation|)} \subsection{Development} There are two mailing lists, one for user questions, one for development discussion. Please visit \URL{savannah.nongnu.org/mail/?group=epix} to subscribe. \texinfochapter{2}{Getting Started} \label{chapter:started} This chapter describes the basics of creating figures in \ePiX\ for readers familiar with \LaTeX\ but completely new to~\CXX. No detailed knowledge of~\CXX\ is needed to use \ePiX, only a bit of grammar that is easily absorbed by example. Section~\ref{section:running} describes the commands (shell scripts) comprising \ePiX, and explains how to set up a graphical environment using standard *nix programs. Section~\ref{section:overview} briefly describes figure creation. Section~\ref{section:tutorial} presents a few files side-by-side with their output, and should be read at a computer so you can run the exercises. \section{Running \ePiX} \label{section:running} An ``input file'' is a human-written figure specification containing \ePiX\ commands. An ``output file'' is machine-created, and is included directly into a \LaTeX\ document with the appropriate packages. Conversion (``compiling'' a figure) is accomplished with four shell scripts, \code{laps}, \code{epix}, \code{elaps}, and \code{flix}. Each script has a preferred extension for its input files, and is invoked with a command of the form \begin{verbatim}