Suppose we want to depict a rectangle inscribed in the upper unit
half-disk, say for an area maximization problem. The figure will
contain coordinate axes, the semi-circle, the inscribed rectangle, and
labels. The first step is to decide on the bounding box. In this
example,
is a reasonable choice. If
the figure is to have true aspect ratio, the width will be twice the
height. Next we decide the true size of the figure (as mentioned
already, it is easy to change this later). A width of 2.5 in is
reasonable, and the aspect ratio forces the height to be 1.25 in.
The input file is shown in Figure 1. The
format should be partially self-explanatory, but a line-by-line
explanation is given below. A few things may not be self-explanatory:
The first line of input, delimited by ``/*
'' and ``*/
'',
is a comment. (A comment begun with /*
may span several lines,
but ends at the next occurrance of */
. You should take
care when commenting a large portion of an existing file, lest the new
comment be terminated prematurely by an existing comment.) A
single-line comment, analogous to a LATEX line beginning
with %
, begins with ``//
''. ePiX manipulates points
and vectors using an ordered pair data structure; the construct
P(a,b) creates the ordered pair . Finally, variables in C must have a declared type, such as int (integer), double
(double-precision float), or char (character).
When ePiX is run on this source file and the output is included in a LATEX document, the result is as depicted in Figure 2.
The include line ensures that standard commands will be available to ePiX when the file is compiled. Every ePiX file must contain this line. The double quotes are single characters, not pairs of single quotes. For the most part, C is not picky about spaces and blank lines in a file, but it is very sensitive to punctuation. Most lines in a C program end with a semicolon. The include line is a rare exception.
The next non-blank line is an assignment statement. In this example, w denotes the half-width of the inscribed rectangle. The final appearance of the figure can be adjusted by changing w. Using variables highlights the logical structure of the figure, which is especially valuable when the figure contains many objects whose positions are mathematically related. Generally, variables are similar to LATEX macros; if a constant appears repeatedly in a single figure, it should probably be a variable. Multiple variable assignments may be placed on a single line, separated by commas, or may be put on separate lines. It is a good idea to group together logically related assignment statements, and to use blank lines and spaces as needed to make the file easy to read.
The include line, variable assignments, and function definitions (none in this example) constitute the preamble. The action begins with the function call to main. The rest of the input file, the body, consists of ePiX commands.
The first four lines of the body assign values to several variables that determine the size and positioning of the figure. You are discouraged from accessing these variables directly, but their names are:
x_min x_max y_min y_max h_size v_size h_offset v_offset pic_size pic_unitOther than
pic_unit
, which is of type char,2 all of these variables
are doubles.
The begin(); line prints some commentary and a LATEX picture head in the output file; everything between begin(); and end(); generates a picture object.
Picture object commands are mnemonic. The line commands draw the
horizontal and vertical axes. The endpoints of the axes are specified
in terms of the Cartesian bounding box of the figure; if the bounding
box is changed, the axes will adjust automatically. The
ellipse_top
command draws the top half of an ellipse, centered
at , with radius
. Remember that the construct
P(a,b) creates the ordered pair
. The boldrect command
draws a boldface rectangle, with opposite corners given in terms of
the variable w.
Finally, there are two commands that print labels in the figure. The
first causes output of a LATEX command to be placed at the Cartesian
location
, offset right by 2pt
and up by 4pt. In
the final figure, the label reads ``
'', and is placed
using the LATEX basepoint of the entire formula. In ePiX, the
correct way to position a label is to specify the ``coarse'' location
in Cartesian coordinates, then to fine tune the location visually with
the label offset. Label offsets are always specified in true points,
because font sizes are given in points and do not change with scaling.
The label command
h_axis_labels(P(x_min,0), P(x_max,0), x_size, P(-12, -12));
generates horizontal-axis labels. The first label is at , the
last is at
, and there are
labels, namely one at each
integer point. The final pair is the label offset; the labels will be
shifted left by 12pt (which roughly centers them) and down
12pt (which prints them below the horizontal axis). ePiX generates
the label values automatically.
There are a few important features (of both C and ePiX) illustrated by this input file.
4*x_size
) must be defined inside
main.3
*
to denote multiplication, and does not
recognize the caret as notation for exponentiation. To get powers of a
variable, you must either specify explicit multiplication, as
in w*w
, or must use C's exponentiation function, as
in pow(w,2)
. The latter sensibly handles arbitrary
floating-point bases and exponents.
ePiX provides about two dozen graphics primitives, including lines, arrows, triangles and rectangles, whole and half ellipses, circular arcs and arrows, quadratic and cubic splines, Cartesian and polar coordinate grids, axes with tick marks, and various types of point marker. These are descriptively named, and are invoked as in the example above. A detailed list and description is given in Section 3.
If you have the pstcol (or color) package for LATEX , you
can create basic color figures by delimiting portions of the input
file with (say) red();
and end_red();
Colors available
in this way are red, blue, green, magenta, cyan, and yellow. ePiX allows generation of essentially arbitrary colors. Detailed
instructions on creating and previewing color files are given in
Section 2.2.