The emu_graph Widget

emu_graph widget is a tcl-only 2D graphing package. It isn't a widget as such, rather it is a structure which can be rendered on any canvas. To use it, you create a graph with the emu_graph command, supplying options to configure the graph. This then creates a new command to manipulate the graph. Manipulations include adding one or more sets of data and configuring the appearance of the data and the graph.

You can see a demostration of the graph package if you have the Tcl plugin.

The emu_graph package is available via http://www.ics.mq.edu.au/~cassidy/tcl/emu_graph.html or you can download it directly via CANTCL http://purl.org/tcl/cantcl/package/emu-graph.zip. Please contact Steve Cassidy with any bug reports, enhancements or other queries.

Command Syntax

The emu_graph command is documented here:

emu_graph name ?options?

Options are (defaults in parentheses):

• -width The width of the plotting region -- inside the axes (300).
• -height The height of the plotting region (200).
• -xref The x coordinate of the top left corner of the plotting region (50).
• -yref The y coordinate of the top left corner of the plotting region (30).
• -ticklen The length of axis ticks (5).
• -axistextoffset The offset between the axes and tick labels (5).
• -nticks_x The number of ticks on the x axis (5).
• -nticks_y The number of ticks on the y axis (5).
• -font The font for text in the graph (fixed).
• -autorange If 1, the graph axes will autorange to the data, set to 0 if you want to set xmin etc yourself (1).
• -canvas The canvas on which the graph will be rendered.
• -xmin The minimum for the x axis.
• -xmax The maximum for the x axis.
• -ymin The minimum for the y axis.
• -ymax The maximum for the y axis.

-canvas is the only required option, all others will default to sensible values. Note that if you want to set the axis limits yourself you will need to either set all limits for both axes or let the graph autorange first and then set one or more of the limits in a later call to configure.

Widget Commands

The emu_graph command creates a new command of the given name to manipulate the graph. The subcommands available are:

• graph configure ?options? modifies configuration information for the graph. Options are the same as those to the emu_graph command.
• graph canvas2x N converts a canvas x-coordinate to a graph coordinate.
• graph canvas2y N converts a canvas y-coordinate to a graph coordinate.
• graph x2canvas N converts a graph x-coordinate to a canvas coordinate.
• graph y2canvas N converts a graph y-coordinate to a canvas coordinate.
• graph bbox returns the bounding box of the graph, including any axis labels.
• graph vmark x tag {color red} puts a vertical mark at the given x position on the graph. Tags it with the given tag.
• graph hmark y tag {color red} puts a horizontal mark at the given y position on the graph. Tags it with the given tag.
• graph movevmark tag x moves an existing vertical mark with tag tag to the new x position
• graph movehmark tag y moves an existing horizontal mark with tag tag to the new y position
• graph cget option returns the value of the configuration option option (the leading - on the option may be omitted).
• graph clearmark tag Clears all marks with the given tag.
• graph data tag ?options? adds a data set to the graph. Details below.
• graph image image xmin xmax ymin ymax Adds an image to the plot and snaps the axes around it, the axis limits are set to the specified values and autoranging is turned off.
• graph redraw forces a redraw of the plot.

More about graph data

Each set of data points can be configured seperately, changing the way it will be rendered in the graph. Data is supplied as a set of coordinates, the same as the format for canvas lines. More options for supplying data may be added later. An optional mask vector can be supplied which is used along with a mask threshold to blank out parts of the plot -- at the moment this only works with point plots, not lines. Each data set has a tag and all canvas items belonging to that data set will have that tag. The options for graph data are:

• -coords list supplies the coordinates of the data as a list of x y pairs, eg: {1 10 2 9 3 8} represents the points (1, 10), (2, 9) and (3, 8)
• -mask list supplies a mask vector which must have the same length as the coords list.
• -maskthresh N supplies a mask threshold, data will only be drawn if the corresponding element of the mask vector exceeds this threshold.
• trackdata name suppiles line coordinates via a trackdata object name. This requires the C level facilities of the emu system
• -points 1/0 toggle drawing of points (0).
• -lines 1/0 toggle drawing of lines (1).
• -colour col define the colour of the line/points (red).

The trackdata mechanism is used in the Emu system for generating plots of speech data extracted from a database, it is intended for use when there are lots of points for a line.

A Note on Coding Style

The way I've implemented this code is to have every procedure prefixed with emu_graph. Those procedures which are intended as user subcommands of a graph instance have two periods following this, eg. emu_graph..redraw, other procedures for internal use have one colon, eg emu_graph:axes.

All configuration data is stored in the global array emu_graph.