”
at the right point.)
This section describes the pgfbaseplot package.
This package provides a set of commands that are intended to make it reasonably easy to plot functions using PGF. It is loaded automatically by pgf, but you can load it manually if you have only included pgfcore.
There exist many powerful programs that produce plots, examples are GNUPLOT or MATHEMATICA. These programs can produce two different kinds of output: First, they can output a complete plot picture in a certain format (like PDF) that includes all low-level commands necessary for drawing the complete plot (including axes and labels). Second, they can usually also produce “just plain data” in the form of a long list of coordinates. Most of the powerful programs consider it a to be “a bit boring” to just output tabled data and very much prefer to produce fancy pictures. Nevertheless, when coaxed, they can also provide the plain data.
The plotting mechanism described in the following deals only with plotting data given in the form of a list of coordinates. Thus, this section is about using PGF to turn lists of coordinates into plots.
Note that is often not necessary to use PGF for this. Programs like GNUPLOT can produce very sophisticated plots and it is usually much easier to simply include these plots as a finished PDF or PostScript graphics.
However, there are a number of reasons why you may wish to invest time and energy into mastering the PGF commands for creating plots:
”
at the right point.)
The above list is not exhaustive, unfortunately.
PGF (conceptually) uses a two-stage process for generating plots. First, a plot stream must be produced. This stream consists (more or less) of a large number of coordinates. Second a plot handler is applied to the stream. A plot handler “does something” with the stream. The standard handler will issue line-to operations to the coordinates in the stream. However, a handler might also try to issue appropriate curve-to operations in order to smooth the curve. A handler may even do something else entirely, like writing each coordinate to another stream, thereby duplicating the original stream.
Both for the creation of streams and the handling of streams different sets of commands exist. The commands for creating streams start with \pgfplotstream, the commands for setting the handler start with \pgfplothandler.
A plot stream is a (long) sequence of the following three commands:
Between calls of these commands arbitrary other code may be called. Obviously, the stream should start with the first command and end with the last command. Here is an example of a plot stream:
|
This command signals that a plot stream starts. The effect of this command is to call the internal command \pgf@plotstreamstart, which is set by the current plot handler to do whatever needs to be done at the beginning of the plot.
This command adds a <point> to the current plot stream. The effect of this command is to call the internal command \pgf@plotstreampoint, which is also set by the current plot handler. This command should now “handle” the point in some sensible way. For example, a line-to command might be issued for the point.
This command signals that a plot stream ends. It calls \pgf@plotstreamend, which should now do any necessary “cleanup.”
Note that plot streams are not buffered, that is, the different points are handled immediately. However, using the recording handler, it is possible to record a stream.
Plot streams can be created “by hand” as in the earlier example. However, most of the time the coordinates will be produced internally by some command. For example, the \pgfplotxyfile reads a file and converts it into a plot stream.
This command will try to open the file <filename>. If this succeeds, it will convert the file contents into a plot stream as follows: A \pgfplotstreamstart is issued. Then, each nonempty line of the file should start with two numbers separated by a space, such as 0.1 1 or 100 -.3. Anything following the numbers is ignored.
Each pair <x> and <y> of numbers is converted into one plot stream point in the xy-coordinate system. Thus, a line like
|
is turned into
|
The two characters % and # are also allowed in a file and they are both treated as comment characters. Thus, a line starting with either of them is empty and, hence, ignored.
When the file has been read completely, \pgfplotstreamend is called.
This command works like \pgfplotxyfile, only three numbers are expected on each non-empty line. They are converted into points in the xyz-coordinate system. Consider, the following file:
|
It is turned into the following stream:
|
Currently, there is no command that can decide automatically whether the xy-coordinate system should be used or whether the xyz-system should be used. However, it would not be terribly difficult to write a “smart file reader” that parses coordinate files a bit more intelligently.
This command will “try” to call the GNUPLOT program to generate the coordinates of the <function>. In detail, the following happens:
This command works with two files: <prefix>.gnuplot and <prefix>.table. If the optional argument <prefix> is not given, it is set to \jobname.
Let us start with the situation where none of these files exists. Then PGF will first generate the file <prefix>.gnuplot. In this file it writes
|
where #1 is replaced by <prefix>. Then, in a second line, it writes the text <function>.
Next, PGF will try to invoke the program gnuplot with the argument <prefix>.gnuplot. This call may or may not succeed, depending on whether the \write18 mechanism (also known as shell escape) is switched on and whether the gnuplot program is available.
Assuming that the call succeeded, the next step is to invoke \pgfplotxyfile on the file <prefix>.table; which is exactly the file that has just been created by gnuplot.
|
The more difficult situation arises when the .gnuplot file exists, which will be the case on the second run of TEX on the TEX file. In this case PGF will read this file and check whether it contains exactly what PGF “would have written” into this file. If this is not the case, the file contents is overwritten with what “should be there” and, as above, gnuplot is invoked to generate a new .table file. However, if the file contents is “as expected,” the external gnuplot program is not called. Instead, the <prefix>.table file is immediately read.
As explained in Section 9.12.3, the net effect of the above mechanism is that gnuplot is called as little as possible and that when you pass along the .gnuplot and .table files with your .tex file to someone else, that person can TEX the .tex file without having gnuplot installed and without having the \write18 mechanism switched on.
A plot handler prescribes what “should be done” with a plot stream. You must set the plot handler before the stream starts. The following commands install the most basic plot handlers; more plot handlers are defined in the file pgflibraryplothandlers, which is documented in Section 14.3.
All plot handlers work by setting redefining the following three macros: \pgf@plotstreamstart, \pgf@plotstreampoint, and \pgf@plotstreamend.
This handler will issue a \pgfpathlineto command for each point of the plot, except possibly for the first. What happens with the first point can be specified using the two commands described below.
|
Specifies that the line-to plot handler (and also some other plot handlers) should issue a move-to command for the first point of the plot instead of a line-to. This will start a new part of the current path, which is not always, but often, desirable. This is the default.
Specifies that plot handlers should issue a line-to command for the first point of the plot.
|
This handler will simply throw away the stream.
When this handler is installed, each time a plot stream command is called, this command will be appended to <macros>. Thus, at the end of the stream, <macro> will contain all the commands that were issued on the stream. You can then install another handler and invoke <macro> to “replay” the stream (possibly many times).
|