The PLplot Plotting Library: Programmer's Reference Manual
Prev | Chapter 3. Advanced Use of PLplot | Next

# Contour and Shade Plots

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.

## Contour Plots from C

`plcont` is the routine callable from C for plotting contours. This routine has the form:

`plcont` (z, nx, ny, kx, lx, ky, ly, clevel, nlevel, pltr, pltr_data);

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.

## Shade Plots from C

NEEDS DOCUMENTATION. Follow the plshade and plshades usage in `examples/c/x??c.c`.

## Contour Plots from the Fortran 95 interface

NEEDS DOCUMENTATION. Follow the plcont usage (with a variety of overloaded forms available with different arguments) in `examples/f95/x??f.f90`.

## Shade Plots from the Fortran 95 interface

NEEDS DOCUMENTATION. Follow the plshade and plshades usage (with a variety of overloaded forms available with different arguments) in `examples/f95/x??f.f90`.

## Contour Plots from the Fortran 77 interface

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:

`call plcont` (z, nx, ny, kx, lx, ky, ly, clevel, nlevel);

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

`call plcon0` (z, nx, ny, kx, lx, ky, ly, clevel, nlevel);

`call plcon1` (z, nx, ny, kx, lx, ky, ly, clevel, nlevel, xg1, yg1);

`call plcon2` (z, nx, ny, kx, lx, ky, ly, clevel, nlevel, xg2, yg2);

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

## Shade Plots from the Fortran 77 interface

NEEDS DOCUMENTATION. Follow the plshade* and plshades* usage in `examples/f77/x??f.f`.

Prev | Home | Next
Three Dimensional Surface Plots | Up | Deploying programs that use PLplot