Contouring and shading has traditionally been one of the messier things to do in PLplot. The C API has many parameters, with complex setup and tear down properties. Of special concern is that some of the parameters do not have a natural representation in script languages like Tcl. In this section we describe how the Tcl interface to these facilities is provided, and how to use it.
By way of reference, the primary C function call for contouring is:
void plcont( PLFLT **f, PLINT nx, PLINT ny, PLINT kx, PLINT lx, PLINT ky, PLINT ly, PLFLT *clevel, PLINT nlevel, void (*pltr) (PLFLT, PLFLT, PLFLT *, PLFLT *, PLPointer), PLPointer pltr_data);
This is a fairly complex argument list, and so for this function (and
for plshade, described below) we dispense with trying to exactly
mirror the C API, and just concentrate on capturing the functionality
within a Tcl context. To begin with, the data is provided through a
2-d Tcl matrix. The Tcl matrix carries along its size information
with it, so nx
and ny
are no longer needed. The
kx
, lx
, ky
and
ly
variables are
potentially still useful for plotting a subdomain of the full data
set, so they may be specified in the natural way, but we make this
optional since they are frequently not used to convey anything more
than what could be inferred from nx
and
ny
. However, to
simplify processing, they must be supplied or omitted as a set (all of
them, or none of them). clevel
is supplied as a 1-d Tcl
matrix, and so nlevel
can be omitted.
Finally, we have no way to support function pointers from Tcl, so instead we provide token based support for accessing the three coordinate transformation routines which are provided by PLplot, and which many PLplot users use. There are thus three courses of action:
Provide no pltr specification. In this case, pltr0
is
used by default.
Specify pltr1 x y
where x and y are 1-d Tcl matrices.
In this case pltr1
will be used, and the 1-d arrays which it
needs will be supplied from the Tcl matrices x
and
y
.
Specify pltr2 x y
where x and y are 2-d Tcl matrices.
In this case pltr2
will be used, and the 2-d arrays which it
needs will be supplied from the Tcl matrices x
and
y
.
Now, there can be no question that this is both more concise and less
powerful than what you could get in C. The loss of the ability to
provide a user specified transformation function is regrettable. If
you really do need that functionality, you will have to implement your
own Tcl extension command to do pretty much the same thing as the
provided Tcl extension command plcont
(which is in
tclAPI.c
in function plcontCmd()
), except specify the C
transformation function of your choice.
However, that having been said, we recognize that one common use for
this capability is to provide a special version of pltr2
which
knows how to implement a periodic boundary condition, so that polar
plots, for example, can be implemented cleanly. That is, if you want
to draw contours of a polar data set defined on a 64 x 64 grid,
ensuring that contour lines would actually go all the way around the
origin rather than breaking off like a silly pacman figure, then you
had basically two choices in C. You could copy the data to a 65 x 64
grid, and replicate one row of data into the spare slot, and then plot
the larger data set (taking care to replicate the coordinate arrays
you passed to pltr2 in the same way), or you could make a
special version of pltr2
which would understand that one of the
coordinates was wrapped, and perform transformations accordingly
without actually making you replicate the data.
Since the former option is ugly in general, and hard to do in Tcl in
particular, and since the second option is even more difficult to do
in Tcl (requiring you do make a special Tcl extension command as
described above), we provide special, explicit support for this common
activity. This is provided through the use of a new, optional
parameter wrap
which may be specified as the last parameter to
the Tcl command, only if you are using pltr2
. Supplying
1
will wrap in the first coordinate, 2
will wrap in the
second coordinate.
The resultant Tcl command is:
plcont f [kx lx ky ly] clev [pltr x y] [wrap]
Note that the brackets here are used to signify optional arguments, not to represent Tcl command substitution!
The Tcl demo x09.tcl
provides examples of all the capabilities
of this interface to contouring from Tcl. Note in particular,
x09_polar
which does a polar contour without doing anything
complicated in the way of setup, and without getting a pacman as the
output.
The Tcl interface to shading works very much like the one for contouring. The command is:
plshade z xmin xmax ymin ymax \ sh_min sh_max sh_cmap sh_color sh_width \ min_col min_wid max_col max_wid \ rect [pltr x y] [wrap]
where nx
and ny
were dropped since they are inferred
from the Tcl matrix z
, defined
was dropped since it
isn't supported anyway, and plfill
was dropped since it was the
only valid choice anyway. The pltr
spec and
wrap
work
exactly as described for the Tcl plcont
described above.
The Tcl demo x16.tcl
contains extensive demonstrations of use,
including a shaded polar plot which connects in the desirable way
without requiring special data preparation, again just like for
plcont
described previously.