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`.