Several routines are available in PLplot which perform a contour or shade plot of data stored in a two-dimensional array. The contourer uses a contour following algorithm so that it is possible to use non-continuous line styles. Further, one may specify arbitrary coordinate mappings from array indices to world coordinates, such as for contours in a polar coordinate system. In this case it is best to draw the distinction between the C, Fortran 95, and Fortran 77 interfaces so these are handled in turn.
plcont is the routine callable from C for plotting contours.
This routine has the form:
where z is the two-dimensional array of size nx by ny containing samples of the function to be contoured. (z is a vectored two-dimensional array as described in the previous section. It is not a fixed-size two-dimensional array.) The parameters kx, lx, ky and ly specify the portion of z that is to be considered. The array clevel of length nlevel is a list of the desired contour levels.
The path of each contour is initially computed in terms of the
values of the array indices which range from 0
to nx-1 in the first index and from
0 to ny-1 in the second
index. Before these can be drawn in the current window (see the Section called Defining the Window), it is necessary to convert from these array
indices into world coordinates. This is done by passing a pointer
pltr to a user-defined transformation function
to plcont. For C use of plcont (and plshade, see next subsection)
we have included directly in
the PLplot library the following transformation routines:
pltr0 (identity transformation or you can
enter a NULL argument to get the same effect); pltr1
(linear interpolation in singly dimensioned coordinate arrays);
and pltr2 (linear interpolation in doubly dimensioned coordinate
arrays). Examples of the use of these transformation
routines are given in examples/c/x09c.c,
examples/c/x14c.c, and
examples/c/x16c.c. These same three examples
also demonstrate a user-defined transformation function
mypltr which is capable of
arbitrary translation, rotation, and/or shear. By defining other
transformation subroutines, it is possible to draw contours wrapped
around polar grids etc.
NEEDS DOCUMENTATION. Follow the plshade and plshades usage in examples/c/x??c.c.
NEEDS DOCUMENTATION. Follow the plcont usage (with a variety of overloaded forms available with different arguments) in examples/f95/x??f.f90.
NEEDS DOCUMENTATION. Follow the plshade and plshades usage (with a variety of overloaded forms available with different arguments) in examples/f95/x??f.f90.
The routines mentioned above are not recommended for use directly
from Fortran 77 due to the need to pass a function pointer. That is,
the transformation function is written in C and can not generally
be changed by the user. The call for routine plcontfortran77 from
Fortran 77 is then:
When called from Fortran 77, this routine has the same effect as when invoked
from C. The interpretation of all parameters (see plcont) is also the
same except there is no transformation function supplied as the last
parameter. Instead, a 6-element array specifying coefficients to use in the
transformation is supplied via the named common block
plplot (see code).
Since this approach is somewhat
inflexible, the user is recommended to call either of plcon0, plcon1, or
plcon2 instead for Fortran 77.
The three routines recommended for use from Fortran 77 are plcon0,
plcon1, and plcon2. These routines are similar to existing
commercial plot package contour plotters in that they offer
successively higher complexity, with plcon0 utilizing no
transformation arrays, while those used by plcon1 and plcon2
are one and two dimensional, respectively. The call syntax for
each is
The plcon0 routine is implemented via a call to plcont with a
very simple (identity) transformation function, while plcon1 and
plcon2 use interpolating transformation functions as well as
a call to
plcont.
The transformation arrays are used by these routines to specify a mapping between the computational coordinate system and the physical one. For example, the transformation to polar coordinates might look like:
do i = 1, NX do j = 1, NY xg(i, j) = r(i) * cos( theta(j) ) yg(i, j) = r(i) * sin( theta(j) ) enddo enddo |
assuming the user had already set up arrays r and theta to specify the (r, θ) values at the gridpoints in his system. For this example, it is recommended that the user add an additional cell in theta such that xg(i, NY+1) = xg(i, 1) and yg(i, NY+1) = yg(i, 1) so that the contours show the proper periodic behavior in θ (see also example program 9).
The transformation function not only specifies the transformation
at grid points, but also at intermediate locations, via linear
interpolation. For example, in the pltr1
transformation function used by plcon1, the 1-d interpolation to
get tx as a function of x
looks like (in C):
ul = (PLINT)x; ur = ul + 1; du = x - ul; xl = *(xg+ul); xr = *(xg+ur); *tx = xl * (1-du) + xr * du; |
while in Fortran 77 this might look like:
lxl = x lxr = lxl + 1 dx = x - lxl xl = xg(lxl) xr = xg(lxr) tx = xl * (1-dx) + xr * dx |
NEEDS DOCUMENTATION. Follow the plshade* and plshades* usage in examples/f77/x??f.f.