NAME

Plotchart -
Simple plotting and charting package

SYNOPSIS

package require Tcl  ? 8.3 ?
package require Plotchart  ? 0.9 ?
::Plotchart::createXYPlot w xaxis yaxis
::Plotchart::createStripchart w xaxis yaxis
::Plotchart::createPolarPlot w radius_data
::Plotchart::createIsometricPlot w xaxis yaxis stepsize
::Plotchart::create3DPlot w xaxis yaxis zaxis
::Plotchart::createPiechart w
::Plotchart::createBarchart w xlabels yaxis noseries
::Plotchart::createHorizontalBarchart w xlabels yaxis noseries
::Plotchart::createTimechart w time_begin time_end noitems
$anyplot title text
$anyplot saveplot filename
$anyplot xtext text
$anyplot ytext text
$anyplot xconfig -option value ...
$anyplot yconfig -option value ...
$xyplot plot series xcrd ycrd
$polarplot plot series radius angle
$plot3d plotfunc function
$plot3d gridsize nxcells nycells
$plot3d plotdata data
$plot3d colours fill border
$xyplot dataconfig series -option value ...
$pie plot data
$pie colours colour1 colour2 ...
$barchart plot series ydata colour
$barchart plot series xdata colour
$timechart period text time_begin time_end colour
$timechart milestone text time colour
$timechart vertline text time
$isoplot plot rectangle x1 y1 x2 y2 colour
$isoplot plot filled-rectangle x1 y1 x2 y2 colour
$isoplot plot circle xc yc radius colour
$isoplot plot filled-circle xc yc radius colour
::Plotchart::viewPort w pxmin pymin pxmax pymax
::Plotchart::worldCoordinates w xmin ymin xmax ymax
::Plotchart::world3DCoordinates w xmin ymin zmin xmax ymax zmax
::Plotchart::coordsToPixel w x y
::Plotchart::coords3DToPixel w x y z
::Plotchart::polarCoordinates w radmax
::Plotchart::polarToPixel w rad phi
::Plotchart::pixelToCoords w x y
::Plotchart::determineScale xmin xmax

DESCRIPTION

Plotchart is a Tcl-only package that focuses on the easy creation of xy-plots, barcharts and other common types of graphical presentations. The emphasis is on ease of use, rather than flexibility. The procedures that create a plot use the entire canvas window, making the layout of the plot completely automatic.

This results in the creation of an xy-plot in, say, ten lines of code:

    package require Plotchart

    canvas .c -background white -width 400 -height 200
    pack   .c -fill both

    #
    # Create the plot with its x- and y-axes
    #
    set s [::Plotchart::createXYPlot .c {0.0 100.0 10.0} {0.0 100.0 20.0}]

    foreach {x y} {0.0 32.0 10.0 50.0 25.0 60.0 78.0 11.0 } {
        $s plot series1 $x $y
    }

    $s title "Data series"

A drawback of the package might be that it does not do any data management. So if the canvas that holds the plot is to be resized, the whole plot must be redrawn. The advantage, though, is that it offers a number of plot and chart types:

PLOT CREATION COMMANDS

You create the plot or chart with one single command and then fill the plot with data:
::Plotchart::createXYPlot w xaxis yaxis
Create a new xy-plot.
TypeNameMode
widgetwin
  Name of the existing canvas widget to hold the plot.
listxaxisin
  A 3-element list containing minimum, maximum and stepsize for the x-axis, in this order.
listyaxisin
  A 3-element list containing minimum, maximum and stepsize for the y-axis, in this order.

::Plotchart::createStripchart w xaxis yaxis
Create a new strip chart. The only difference to a regular XY plot is that the x-axis will be automatically adjusted when the x-coordinate of a new point exceeds the maximum.
TypeNameMode
widgetwin
  Name of the existing canvas widget to hold the plot.
listxaxisin
  A 3-element list containing minimum, maximum and stepsize for the x-axis, in this order.
listyaxisin
  A 3-element list containing minimum, maximum and stepsize for the y-axis, in this order.

::Plotchart::createPolarPlot w radius_data
Create a new polar plot.
TypeNameMode
widgetwin
  Name of the existing canvas widget to hold the plot.
listradius_datain
  A 2-element list containing maximum radius and stepsize for the radial axis, in this order.

::Plotchart::createIsometricPlot w xaxis yaxis stepsize
Create a new isometric plot, where the vertical and the horizontal coordinates are scaled so that a circle will truly appear as a circle.
TypeNameMode
widgetwin
  Name of the existing canvas widget to hold the plot.
listxaxisin
  A 2-element list containing minimum, and maximum for the x-axis, in this order.
listyaxisin
  A 2-element list containing minimum, and maximum for the y-axis, in this order.
float|noaxes stepsizein
  Either the stepsize used by both axes or the keyword noaxes to signal the plot that it should use the full area of the widget, to not draw any of the axes.

::Plotchart::create3DPlot w xaxis yaxis zaxis
Create a new 3D plot.
TypeNameMode
widgetwin
  Name of the existing canvas widget to hold the plot.
listxaxisin
  A 3-element list containing minimum, maximum and stepsize for the x-axis, in this order.
listyaxisin
  A 3-element list containing minimum, maximum and stepsize for the y-axis, in this order.
listzaxisin
  A 3-element list containing minimum, maximum and stepsize for the z-axis, in this order.

::Plotchart::createPiechart w
Create a new piechart.
TypeNameMode
widgetwin
  Name of the existing canvas widget to hold the plot.

::Plotchart::createBarchart w xlabels yaxis noseries
Create a new barchart with vertical bars. The horizontal axis will display the labels contained in the argument xlabels. The number of series given by noseries determines both the width of the bars, and the way the series will be drawn.
If the keyword stacked was specified the series will be drawn stacked on top of each other. Otherwise each series that is drawn will be drawn shifted to the right.
TypeNameMode
widgetwin
  Name of the existing canvas widget to hold the plot.
listxlabelsin
  List of labels for the x-axis. Its length also determines the number of bars that will be plotted per series.
listyaxisin
  A 3-element list containing minimum, maximum and stepsize for the y-axis, in this order.
int|stacked noseriesin
  The number of data series that will be plotted. This has to be an integer number greater than zero (if stacked is not used).

::Plotchart::createHorizontalBarchart w xlabels yaxis noseries
Create a new barchart with horizontal bars. The vertical axis will display the labels contained in the argument ylabels. The number of series given by noseries determines both the width of the bars, and the way the series will be drawn.
If the keyword stacked was specified the series will be drawn stacked from left to right. Otherwise each series that is drawn will be drawn shifted upward.
TypeNameMode
widgetwin
  Name of the existing canvas widget to hold the plot.
listylabelsin
  List of labels for the y-axis. Its length also determines the number of bars that will be plotted per series.
listyaxisin
  A 3-element list containing minimum, maximum and stepsize for the x-axis, in this order.
int|stacked noseriesin
  The number of data series that will be plotted. This has to be an integer number greater than zero (if stacked is not used).

::Plotchart::createTimechart w time_begin time_end noitems
Create a new timechart. The time axis (= x-axis) goes from time_begin to time_end, and the vertical spacing is determined by the number of items to plot.
TypeNameMode
widgetwin
  Name of the existing canvas widget to hold the plot.
stringtime_beginin
  The start time given in a form that is recognised by the clock scan command (e.g. "1 january 2004").
stringtime_endin
  The end time given in a form that is recognised by the clock scan command (e.g. "1 january 2004").
intnoitemsin
  Expected/maximum number of items. This determines the vertical spacing.

PLOT METHODS

Each of the creation commands explained in the last section returns the name of a new object command that can be used to manipulate the plot or chart. The subcommands available to a chart command depend on the type of the chart.

General subcommands for all types of charts. $anyplot is the command returned by the creation command:

$anyplot title text
Specify the title of the whole chart.
TypeNameMode
stringtextin
  The text of the title to be drawn.

$anyplot saveplot filename
Draws the plot into a file, using PostScript.
TypeNameMode
stringfilenamein
  Contain the path name of the file to write the plot to.

$anyplot xtext text
Specify the title of the x-axis, for those plots that have a straight x-axis.
TypeNameMode
stringtextin
  The text of the x-axis label to be drawn.

$anyplot ytext text
Specify the title of the y-axis, for those plots that have a straight y-axis.
TypeNameMode
stringtextin
  The text of the y-axis label to be drawn.

$anyplot xconfig -option value ...
Set one or more configuration parameters for the x-axis. The following options are known:
format fmt
The format for the numbers along the axis.
ticklength length
The length of the tickmarks (in pixels).
ticklines boolean
Whether to draw ticklines (true) or not (false).
scale scale_data
New scale data for the axis, i.e. a 3-element list containing minimum, maximum and stepsize for the axis, in this order.
Beware: Setting this option will clear all data from the plot.

$anyplot yconfig -option value ...
Set one or more configuration parameters for the y-axis. This method accepts the same options and values as the method xconfig.

Note: The commands xconfig and yconfig are currently implemented only for XY-plots and only the option -format has any effect.

For xy plots and stripcharts:

$xyplot plot series xcrd ycrd
Add a data point to the plot.
TypeNameMode
stringseriesin
  Name of the data series the new point belongs to.
floatxcrdin
  X-coordinate of the new point.
floatycrdin
  Y-coordinate of the new point.

For polar plots:

$polarplot plot series radius angle
Add a data point to the polar plot.
TypeNameMode
stringseriesin
  Name of the data series the new point belongs to.
floatradiusin
  Radial coordinate of the new point.
floatanglein
  Angular coordinate of the new point (in degrees).

For 3D plots:

$plot3d plotfunc function
Plot a function defined over two variables x and y. The resolution is determined by the set grid sizes (see the method gridsize for more information).
TypeNameMode
stringfunctionin
  Name of the procedure that calculates the z-value for the given x and y coordinates. The procedure has to accept two float arguments (x is first argument, y is second) and return a floating-point value.

$plot3d gridsize nxcells nycells
Set the grid size in the two directions. Together they determine how many polygons will be drawn for a function plot.
TypeNameMode
intnxcellsin
  Number of grid cells in x direction. Has to be an integer number greater than zero.
intnycellsin
  Number of grid cells in y direction. Has to be an integer number greater than zero.

$plot3d plotdata data
Plot a matrix of data.
TypeNameMode
listdatain
  The data to be plotted. The data has to be provided as a nested list with 2 levels. The outer list contains rows, drawn in y-direction, and each row is a list whose elements are drawn in x-direction, for the columns. Example:
    set data {
    {1.0 2.0 3.0}
    {4.0 5.0 6.0}
    }


$plot3d colours fill border
Configure the colours to use for polygon borders and inner area.
TypeNameMode
colorfillin
  The colour to use for filling the polygons.
colorborderin
  The colour to use for the border of the polygons.

For xy plots, stripcharts and polar plots:

$xyplot dataconfig series -option value ...
Set the value for one or more options regarding the drawing of data of a specific series.
TypeNameMode
stringseriesin
  Name of the data series whose configuration we are changing.

The following option are known:
colour c
color c
The colour to be used when drawing the data series.
type enum
The drawing mode chosen for the series. This can be one of line, symbol, or both.
symbol enum
What kind of symbol to draw. The value of this option is ignored when the drawing mode line was chosen. This can be one of plus, cross, circle, up (triangle pointing up), down (triangle pointing down), dot (filled circle), upfilled or downfilled (filled triangles).

For piecharts:

$pie plot data
Fill a piechart.
TypeNameMode
listdatain
  A list of pairs (labels and values). The values determine the relative size of the circle segments. The labels are drawn beside the circle.
$pie colours colour1 colour2 ...
Set the colours to be used.
TypeNameMode
colorcolour1in
  The first colour.
colorcolour2in
  The second colour, and so on.

For vertical barcharts:

$barchart plot series ydata colour
Add a data series to a barchart.
TypeNameMode
stringseriesin
  Name of the series the values belong to.
listydatain
  A list of values, one for each x-axis label.
colorcolourin
  The colour of the bars.

For horizontal barcharts:

$barchart plot series xdata colour
Add a data series to a barchart.
TypeNameMode
stringseriesin
  Name of the series the values belong to.
listxdatain
  A list of values, one for each y-axis label.
colorcolourin
  The colour of the bars.

For timecharts:

$timechart period text time_begin time_end colour
Add a time period to the chart.
TypeNameMode
stringtextin
  The text describing the period.
stringtime_beginin
  Start time of the period.
stringtime_endin
  Stop time of the period.
colorcolourin
  The colour of the bar (defaults to black).

$timechart milestone text time colour
Add a milestone (represented as an point-down triangle) to the chart.
TypeNameMode
stringtextin
  The text describing the milestone.
stringtimein
  Time at which the milestone must be positioned.
colorcolourin
  The colour of the triangle (defaults to black).

$timechart vertline text time
Add a vertical line (to indicate the start of the month for instance) to the chart.
TypeNameMode
stringtextin
  The text appearing at the top (an abbreviation of the date/time for instance).
stringtimein
  Time at which the line must be positioned.

For isometric plots (to be extended):

$isoplot plot rectangle x1 y1 x2 y2 colour
Plot the outlines of a rectangle.
TypeNameMode
floatx1in
  Minimum x coordinate of the rectangle to be drawn.
floaty1in
  Minimum y coordinate of the rectangle.
floatx2in
  Maximum x coordinate of the rectangle to be drawn.
floaty2in
  Maximum y coordinate of the rectangle.
colorcolourin
  The colour of the rectangle.

$isoplot plot filled-rectangle x1 y1 x2 y2 colour
Plot a rectangle filled with the given colour.
TypeNameMode
floatx1in
  Minimum x coordinate of the rectangle to be drawn.
floaty1in
  Minimum y coordinate of the rectangle.
floatx2in
  Maximum x coordinate of the rectangle to be drawn.
floaty2in
  Maximum y coordinate of the rectangle.
colorcolourin
  The colour of the rectangle.

$isoplot plot circle xc yc radius colour
Plot the outline of a circle.
TypeNameMode
floatxcin
  X coordinate of the circle's centre.
floatycin
  Y coordinate of the circle's centre.
colorcolourin
  The colour of the circle.

$isoplot plot filled-circle xc yc radius colour
Plot a circle filled with the given colour.
TypeNameMode
floatxcin
  X coordinate of the circle's centre.
floatycin
  Y coordinate of the circle's centre.
colorcolourin
  The colour of the circle.

There are a number of public procedures that may be useful in specific situations: Pro memorie.

COORDINATE TRANSFORMATIONS

Besides the commands that deal with the plots and charts directly, there are a number of commands that can be used to convert world coordinates to pixels and vice versa. These include:
::Plotchart::viewPort w pxmin pymin pxmax pymax
Set the viewport for window w. Should be used in cooperation with ::Plotchart::worldCoordinates.
TypeNameMode
widgetwin
  Name of the window (canvas widget) in question.
floatpxminin
  Left-most pixel coordinate.
floatpyminin
  Top-most pixel coordinate (remember: the vertical pixel coordinate starts with 0 at the top!).
floatpxmaxin
  Right-most pixel coordinate.
floatpymaxin
  Bottom-most pixel coordinate.

::Plotchart::worldCoordinates w xmin ymin xmax ymax
Set the extreme world coordinates for window w. The world coordinates need not be in ascending order (i.e. xmin can be larger than xmax, so that a reversal of the x-axis is achieved).
TypeNameMode
widgetwin
  Name of the window (canvas widget) in question.
floatxminin
  X-coordinate to be mapped to left side of viewport.
floatyminin
  Y-coordinate to be mapped to bottom of viewport.
floatxmaxin
  X-coordinate to be mapped to right side of viewport.
floatymaxin
  Y-coordinate to be mapped to top side of viewport.

::Plotchart::world3DCoordinates w xmin ymin zmin xmax ymax zmax
Set the extreme three-dimensional world coordinates for window w. The world coordinates need not be in ascending order (i.e. xmin can be larger than xmax, so that a reversal of the x-axis is achieved).
TypeNameMode
widgetwin
  Name of the window (canvas widget) in question.
floatxminin
  X-coordinate to be mapped to front side of the 3D viewport.
floatyminin
  Y-coordinate to be mapped to left side of the viewport.
floatzminin
  Z-coordinate to be mapped to bottom of viewport.
floatxmaxin
  X-coordinate to be mapped to back side of viewport.
floatymaxin
  Y-coordinate to be mapped to right side of viewport.
floatzmaxin
  Z-coordinate to be mapped to top side of viewport.

::Plotchart::coordsToPixel w x y
Return a list of pixel coordinates valid for the given window.
TypeNameMode
widgetwin
  Name of the window (canvas widget) in question.
floatxin
  X-coordinate to be mapped.
floatyin
  Y-coordinate to be mapped.

::Plotchart::coords3DToPixel w x y z
Return a list of pixel coordinates valid for the given window.
TypeNameMode
widgetwin
  Name of the window (canvas widget) in question.
floatxin
  X-coordinate to be mapped.
floatyin
  Y-coordinate to be mapped.
floatyin
  Z-coordinate to be mapped.

::Plotchart::polarCoordinates w radmax
Set the extreme polar coordinates for window w. The angle always runs from 0 to 360 degrees and the radius starts at 0. Hence you only need to give the maximum radius. Note: If the viewport is not square, this procedure will not adjust the extremes, so that would result in an elliptical plot. The creation routine for a polar plot always determines a square viewport.
TypeNameMode
widgetwin
  Name of the window (canvas widget) in question.
floatradmaxin
  Maximum radius.

::Plotchart::polarToPixel w rad phi
Wrapper for a call to ::Plotchart::coordsToPixel, which assumes the world coordinates and viewport are set appropriately. Converts polar coordinates to pixel coordinates. Note: To be useful it should be accompanied by a matching ::Plotchart::worldCoordinates procedure. This is automatically taken care of in the creation routine for polar plots.
TypeNameMode
widgetwin
  Name of the window (canvas widget) in question.
floatradin
  Radius of the point.
floatphiin
  Angle to the positive x-axis.

::Plotchart::pixelToCoords w x y
Return a list of world coordinates valid for the given window.
TypeNameMode
widgetwin
  Name of the window (canvas widget) in question.
floatxin
  X-pixel to be mapped.
floatyin
  Y-pixel to be mapped.

Furthermore there is a routine to determine "pretty" numbers for use with an axis:

::Plotchart::determineScale xmin xmax
Determine "pretty" numbers from the given range and return a list containing the minimum, maximum and stepsize that can be used for a (linear) axis.
TypeNameMode
floatxminin
  Rough minimum value for the scaling
floatxmaxin
  Rough maximum value for the scaling.

OTHER OUTPUT FORMATS

Besides output to the canvas on screen, the module is capable, via canvas postscript, of producing PostScript files. One may wonder whether it is possible to extend this set of output formats and the answer is "yes". This section tries to sum up the aspects of using this module for another sort of output.

One way you can create output files in a different format, is by examining the contents of the canvas after everything has been drawn and render that contents in the right form. This is probably the easiest way, as it involves nothing more than the re-creation of all the elements in the plot that are already there.

The drawback of that method is that you need to have a display, which is not always the case if you run a CGI server or something like that.

An alternative is to emulate the canvas command. For this to work, you need to know which canvas subcommands are used and what for. Obviously, the create subcommand is used to create the lines, texts and other items. But also the raise and lower subcommands are used, because with these the module can influence the drawing order - important to simulate a clipping rectangle around the axes. (The routine DrawMask is responsible for this - if the output format supports proper clipping areas, then a redefinition of this routine might just solve this).

Furthermore, the module uses the cget subcommand to find out the sizes of the canvas. A more mundane aspect of this is that the module currently assumes that the text is 14 pixels high and that 80 pixels in width suffice for the axis' labels. No "hook" is provided to customise this.

In summary:

ROOM FOR IMPROVEMENT

In this version there are a lot of things that still need to be implemented:

TODO - SOME PRIVATE NOTES

I have the following wishlist:

KEYWORDS

graphical presentation, plotting, charts, xy-plots, bar charts, strip charts, polar plots, isometric plots, pie charts, time charts, 3D surfaces, 3D bars, coordinates, coordinate transformations