|
ActiveTcl User Guide
|
|
|
[ Main table Of Contents | Tklib Table Of Contents | Tklib Index ]
Plotchart(n) 0.9 "Plotchart"
Plotchart - Simple plotting and charting package
TABLE OF
CONTENTS
SYNOPSIS
DESCRIPTION
PLOT
CREATION COMMANDS
PLOT METHODS
COORDINATE TRANSFORMATIONS
OTHER OUTPUT
FORMATS
ROOM FOR
IMPROVEMENT
TODO - SOME
PRIVATE NOTES
KEYWORDS
COPYRIGHT
package require Tcl ?8.3?
package require Plotchart ?0.9?
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:
- XY-plots like the one shown above with any number of data
series.
- Stripcharts, a kind of XY-plots where the horizontal axis is
adjusted automatically. The result is a kind of sliding window on
the data series.
- Polar plots, where the coordinates are polar instead of
cartesian.
- Isometric plots, where the scale of the coordinates in the two
directions is always the same, i.e. a circle in world coordinates
appears as a circle on the screen.
You can zoom in and out, as well as pan with these plots
(Note: this works best if no axes are drawn, the zooming
and panning routines do not distinguish the axes), using the mouse
buttons with the control key and the arrow keys with the control
key.
- Piecharts, with automatic scaling to indicate the
proportions.
- Barcharts, with either vertical or horizontal bars, stacked
bars or bars side by side.
- Timecharts, where bars indicate a time period and milestones or
other important moments in time are represented by triangles.
- 3D plots (both for displaying surfaces and 3D bars)
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.
- widget w (in)
- Name of the existing canvas widget to hold the
plot.
- list xaxis (in)
- A 3-element list containing minimum, maximum and stepsize for
the x-axis, in this order.
- list yaxis (in)
- 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.
- widget w (in)
- Name of the existing canvas widget to hold the
plot.
- list xaxis (in)
- A 3-element list containing minimum, maximum and stepsize for
the x-axis, in this order.
- list yaxis (in)
- 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.
- widget w (in)
- Name of the existing canvas widget to hold the
plot.
- list radius_data (in)
- 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.
- widget w (in)
- Name of the existing canvas widget to hold the
plot.
- list xaxis (in)
- A 2-element list containing minimum, and maximum for the
x-axis, in this order.
- list yaxis (in)
- A 2-element list containing minimum, and maximum for the
y-axis, in this order.
- float|noaxes stepsize
(in)
- 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.
- widget w (in)
- Name of the existing canvas widget to hold the
plot.
- list xaxis (in)
- A 3-element list containing minimum, maximum and stepsize for
the x-axis, in this order.
- list yaxis (in)
- A 3-element list containing minimum, maximum and stepsize for
the y-axis, in this order.
- list zaxis (in)
- A 3-element list containing minimum, maximum and stepsize for
the z-axis, in this order.
- ::Plotchart::createPiechart w
- Create a new piechart.
- widget w (in)
- 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.
- widget w (in)
- Name of the existing canvas widget to hold the
plot.
- list xlabels (in)
- List of labels for the x-axis. Its length also determines the
number of bars that will be plotted per series.
- list yaxis (in)
- A 3-element list containing minimum, maximum and stepsize for
the y-axis, in this order.
- int|stacked noseries
(in)
- 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.
- widget w (in)
- Name of the existing canvas widget to hold the
plot.
- list ylabels (in)
- List of labels for the y-axis. Its length also determines the
number of bars that will be plotted per series.
- list yaxis (in)
- A 3-element list containing minimum, maximum and stepsize for
the x-axis, in this order.
- int|stacked noseries
(in)
- 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.
- widget w (in)
- Name of the existing canvas widget to hold the
plot.
- string time_begin (in)
- The start time given in a form that is recognised by the clock scan command (e.g. "1 january 2004").
- string time_end (in)
- The end time given in a form that is recognised by the clock scan command (e.g. "1 january 2004").
- int noitems (in)
- Expected/maximum number of items. This determines the vertical
spacing.
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.
- string text (in)
- The text of the title to be drawn.
- $anyplot saveplot filename
- Draws the plot into a file, using PostScript.
- string filename (in)
- 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.
- string text (in)
- 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.
- string text (in)
- 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.
- string series (in)
- Name of the data series the new point belongs to.
- float xcrd (in)
- X-coordinate of the new point.
- float ycrd (in)
- Y-coordinate of the new point.
For polar plots:
- $polarplot plot series radius angle
- Add a data point to the polar plot.
- string series (in)
- Name of the data series the new point belongs to.
- float radius (in)
- Radial coordinate of the new point.
- float angle (in)
- 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).
- string function (in)
- 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.
- int nxcells (in)
- Number of grid cells in x direction. Has to be an integer
number greater than zero.
- int nycells (in)
- Number of grid cells in y direction. Has to be an integer
number greater than zero.
- $plot3d plotdata data
- Plot a matrix of data.
- list data (in)
- 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.
- color fill (in)
- The colour to use for filling the polygons.
- color border (in)
- 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.
- string series (in)
- 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.
- list data (in)
- 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.
- color colour1 (in)
- The first colour.
- color colour2 (in)
- The second colour, and so on.
For vertical barcharts:
- $barchart plot series ydata colour
- Add a data series to a barchart.
- string series (in)
- Name of the series the values belong to.
- list ydata (in)
- A list of values, one for each x-axis label.
- color colour (in)
- The colour of the bars.
For horizontal barcharts:
- $barchart plot series xdata colour
- Add a data series to a barchart.
- string series (in)
- Name of the series the values belong to.
- list xdata (in)
- A list of values, one for each y-axis label.
- color colour (in)
- The colour of the bars.
For timecharts:
- $timechart period text time_begin time_end colour
- Add a time period to the chart.
- string text (in)
- The text describing the period.
- string time_begin (in)
- Start time of the period.
- string time_end (in)
- Stop time of the period.
- color colour (in)
- 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.
- string text (in)
- The text describing the milestone.
- string time (in)
- Time at which the milestone must be positioned.
- color colour (in)
- 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.
- string text (in)
- The text appearing at the top (an abbreviation of the date/time
for instance).
- string time (in)
- 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.
- float x1 (in)
- Minimum x coordinate of the rectangle to be drawn.
- float y1 (in)
- Minimum y coordinate of the rectangle.
- float x2 (in)
- Maximum x coordinate of the rectangle to be drawn.
- float y2 (in)
- Maximum y coordinate of the rectangle.
- color colour (in)
- The colour of the rectangle.
- $isoplot plot filled-rectangle
x1 y1 x2
y2 colour
- Plot a rectangle filled with the given colour.
- float x1 (in)
- Minimum x coordinate of the rectangle to be drawn.
- float y1 (in)
- Minimum y coordinate of the rectangle.
- float x2 (in)
- Maximum x coordinate of the rectangle to be drawn.
- float y2 (in)
- Maximum y coordinate of the rectangle.
- color colour (in)
- The colour of the rectangle.
- $isoplot plot circle xc yc radius colour
- Plot the outline of a circle.
- float xc (in)
- X coordinate of the circle's centre.
- float yc (in)
- Y coordinate of the circle's centre.
- color colour (in)
- The colour of the circle.
- $isoplot plot filled-circle xc yc radius
colour
- Plot a circle filled with the given colour.
- float xc (in)
- X coordinate of the circle's centre.
- float yc (in)
- Y coordinate of the circle's centre.
- color colour (in)
- The colour of the circle.
There are a number of public procedures that may be useful in
specific situations: Pro memorie.
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.
- widget w (in)
- Name of the window (canvas widget) in question.
- float pxmin (in)
- Left-most pixel coordinate.
- float pymin (in)
- Top-most pixel coordinate (remember: the vertical pixel
coordinate starts with 0 at the top!).
- float pxmax (in)
- Right-most pixel coordinate.
- float pymax (in)
- 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).
- widget w (in)
- Name of the window (canvas widget) in question.
- float xmin (in)
- X-coordinate to be mapped to left side of viewport.
- float ymin (in)
- Y-coordinate to be mapped to bottom of viewport.
- float xmax (in)
- X-coordinate to be mapped to right side of viewport.
- float ymax (in)
- 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).
- widget w (in)
- Name of the window (canvas widget) in question.
- float xmin (in)
- X-coordinate to be mapped to front side of the 3D viewport.
- float ymin (in)
- Y-coordinate to be mapped to left side of the viewport.
- float zmin (in)
- Z-coordinate to be mapped to bottom of viewport.
- float xmax (in)
- X-coordinate to be mapped to back side of viewport.
- float ymax (in)
- Y-coordinate to be mapped to right side of viewport.
- float zmax (in)
- 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.
- widget w (in)
- Name of the window (canvas widget) in question.
- float x (in)
- X-coordinate to be mapped.
- float y (in)
- Y-coordinate to be mapped.
- ::Plotchart::coords3DToPixel w x y z
- Return a list of pixel coordinates valid for the given
window.
- widget w (in)
- Name of the window (canvas widget) in question.
- float x (in)
- X-coordinate to be mapped.
- float y (in)
- Y-coordinate to be mapped.
- float y (in)
- 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.
- widget w (in)
- Name of the window (canvas widget) in question.
- float radmax (in)
- 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.
- widget w (in)
- Name of the window (canvas widget) in question.
- float rad (in)
- Radius of the point.
- float phi (in)
- Angle to the positive x-axis.
- ::Plotchart::pixelToCoords w x y
- Return a list of world coordinates valid for the given
window.
- widget w (in)
- Name of the window (canvas widget) in question.
- float x (in)
- X-pixel to be mapped.
- float y (in)
- Y-pixel to be mapped.
- ::Plotchart::pixelToIndex w x y
- Return the index of the pie segment containing the pixel
coordinates (x,y)
- widget w (in)
- Name of the window (canvas widget) in question, holding a
piechart.
- float x (in)
- X-pixel to be mapped.
- float y (in)
- 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.
- float xmin (in)
- Rough minimum value for the scaling
- float xmax (in)
- Rough maximum value for the scaling.
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:
- Emulate the create subcommand to create all the items
in the correct format
- Emulate the cget subcommand for the options -width and
-height to allow the correct calculation of the rectangle's
position and size
- Solve the problem of raising and lowering the
items so that they are properly clipped, for instance by redefining
the routine DrawMask.
- Take care of the currently fixed text size properties
In this version there are a lot of things that still need to be
implemented:
- General options like legends and text to the axes.
- More robust handling of incorrect calls (right now the
procedures may fail when called incorrectly):
- The axis drawing routines can not handle inverse axes right
now.
- If the user provides an invalid date/time string, the routines
simply throw an error.
I have the following wishlist:
- Isometric plots - allow new items to be implemented easily.
- Add support for histograms where the independent axis is
numerical.
- A general 3D viewer - emphasis on geometry, not a
ray-tracer.
3D bars , 3D surfaces , bar charts , charts , coordinate transformations , coordinates , graphical presentation , isometric plots , pie charts , plotting , polar plots , strip charts , time charts , xy-plots
Copyright © 2004 Arjen Markus
<arjenmarkus@users.sourceforge.net>