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:

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.