next up previous
Next: Plotting Functions Up: Getting Started Previous: Coordinates and Dimensions


A Simple Figure and C Tutorial

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, $ [-1,1]\times[0,1]$ 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 $ (a,b)$. Finally, variables in C must have a declared type, such as int (integer), double (double-precision float), or char (character).

Figure 1: The source file for Figure 2.
\begin{figure}
\begin{footnotesize}
\begin{verbatim}/* semicirc.c -- A rectang...
...0), x_size, P(-12, -12));end();
}\end{verbatim}\end{footnotesize}\end{figure}

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.

Figure 2: A rectangle inscribed in the upper half disk.
\begin{figure}
\begin{center}
\input{semicirc.eepic}
\end{center}\end{figure}

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_unit
Other 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 $ (0,0)$, with radius $ (1,1)$. Remember that the construct P(a,b) creates the ordered pair $ (a,b)$. 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  $ (\frac{1}{2},\frac{\sqrt{3}}{\ 2})$, offset right by 2pt and up by 4pt. In the final figure, the label reads `` $ y=\sqrt{1-x^2}$'', 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 $ (-1,0)$, the last is at $ (1,0)$, and there are $ 2+1$ 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.

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.



Subsections
next up previous
Next: Plotting Functions Up: Getting Started Previous: Coordinates and Dimensions
hwang
2002-06-06