Using The Plot3D Extension Widget

1 Introduction

The Plot3D widget draws one or more lines of data in a 3-dimensional space and then renders the results on a canvas widget. Figure 1.1 displayed is a typical Plot3D graph with addition annotation to show its coordinate axes and axis planes.

As shown in figure 1.1, the Plot3D widget uses a right-handed coordinate system. The Y axis is always pointing up. Each line of data is drawn in its own plane which is parallel to the XY-axis plane.

Figure 1.1: A Typical Plot3D Widget With Extra Annotation Showing The Coordinate Axes and Axis Planes

Lines of data are numbered beginning with 0. Line 0 has the largest Z coordinate and higher numbered lines are drawn closer to the XY-Plane. This is illustrated in figures 1.2 and 1.3 which show the same graph as figure 1.1 but with labels on both graph lines.

Figure 1.2: The Previous Figure With Additional Annotation To Show The Graph Line Numbers

Figure 1.3: The Previous Graph Viewed From A Different Angle

A simple Plot3D graph can be created using the following 4 lines of Tcl code:

   plot3d gr -canvas .c
   gr data 0   100 120 140 140 130 150 140 140 \
               120 100  90 130 150 180 170 130
   gr data 1    50  40  10 100 120 140 200 130 \
               150  90 140 140 120 100  90 100
   pack [canvas .c]

The second and third lines of the above example create two lines of data in the Plot3D widget. Each of these commands consists of the name of the widget, the ``data'' subcommand word, the line number (0 and 1 in the example) and one or more data points. The example shows two lines of data each with 16 points (exactly the same data used to generate figure 1.1, by the way) but these are not hard limits. You can create up to 50 lines of data with up to 50 data points each. You can create even more if you change the MAX_PLANES and MAX_POINTS macros in the Plot3D source code and recompile.

It is not necessary to give each data line the same number of data points. The Plot3D widget will automatically scale its X-axis to accomodate the longest data line. Also, there is no limit to the Y values for any data point other than the fact that they must be non-negative. Each Y value can be any non-negative floating point number. The Y axis of the graph will automatically scale to accomodate the largest Y value.

2 Common Configuration Options

If you put the four Tcl/Tk commands shown in the example above into a file, then run a Plot3D enabled ``wish'' on that file, you'll get a graph that looks like figure 2.1. As you can see, this graph is correct, but visually uninspiring. This section will describe options to the Plot3D widget that will make the graph more eye-catching and easier to read.

Figure 2.1: An Unadorned Graph

2.1 Changing The Color Of Graph Lines

The first thing we can do is give some color and width to the two graph lines. This is accomplished by using a variation on the config widget command where the first argument is the number of the graph line we want to configure. Like this:

   gr config 0 -options {-fill blue -width 4}
   gr config 1 -options {-fill yellow -width 4}

Figure 2.2: The Graph After Setting Line Colors And Widths

The ``-options'' option can be applied only to a specific line. If you want to specify additional arguments to be appended to all graph lines, you should use the ``-lineoptions'' option. For example, the three commands that follow have exactly the same effect as the two command above:

   gr config 0 -options {-fill blue}
   gr config 1 -options {-fill yellow}
   gr config -lineoptions {-width 4}

In general, you should use the ``-options'' option for graph line attributes that apply only to a single graph line (such as color), and use ``-lineoptions'' for all attributes that apply to all lines (such as width). A common argument to ``-lineoptions'' is the following:

   gr config -lineoptions {-width 4 -capstyle round -smooth 1}

Figure 2.3: The Example Graph With Smooth Lines

2.2 Changing Attributes Of The Axis Planes

The Plot3D widget also allows extra attributes to be specified for the axis planes. Just as the ``-lineoptions'' option will cause extra text to be appended to the canvas widget commands that create graph lines, the ``-xyplane'' option will cause extra text to be appended to the canvas widget command that draws the XY Axis Plane. By default, the value of the ``-xyplane'' option is ``-fill honeydew3 -outline black'' which works well for most people. But if you want to change it you can.

There are similar options ``-xzplane'' and ``-yzplane'' for controlling the appearance of the XZ and YZ axis planes, respectively. Both have reasonable defaults, but you are free to change them if you want something different.

2.3 Scaling The Graph

The Plot3D widget supports two configurations that control the amount of space the graph takes up on the canvas: ``-bbox'' and ``-magnification''. There is a third option ``-size'' that controls the relative sizes of the three coordinate axes of the graph.

The argument to the ``-bbox'' option is a list of four integers that specify the X and Y canvas coordinates for the upper left-hand corner of the graph, and the width and height of the graph in pixels. The default setup is equivalent to the following:

   gr config -bbox {0 0 300 200}

The size of the graph as it is drawn on the canvas can also be adjusted using the ``-magnification'' option. The argument to ``-magnification'' is a single integer that is the amount by which the graph should be scaled before it is displayed. Useful values for the magnification normally are in the range of 500 to 2000, though you will doubtless want experiment to find a value suitable for each particular use. If no ``-magnification'' option is used, or if the value is set to the empty string, then graph will scale to fit the bounding box specified by the ``-bbox'' option.

The ``-size'' option does not change how big the graph is drawn, as its name might imply, but rather the relative sizes of the X, Y and Z axes. The argument to ``-size'' is a list of 3 real numbers that specify the relative size of the X, Y and Z axis, respectively. The default value is the equivalent of:

   gr config -size {2 1 1}

Figure 2.4: Changing The Relative Sizes Of The Coordinate Axes

2.4 Labeling The Axes

The tic-marks on the X and Y axes of the graph will be automatically labeled if you just specify a font to use for the labelling with the ``-font'' option. Like this:

   gr config -font fixed

Labels for the tic-marks along the Z axis are specified individually for each data line using a line specific configuration. Like this:

   gr config 0 -label {Line 0}
   gr config 1 -label {Line 1}

The combined effect of specifying a font and putting labels on the data lines is a graph that looks something like figure 2.5.

Figure 2.5: Labels On The Graph

3 Making The Graph Rotate

One of the more interesting features of the Plot3D widget is its ability to view a graph from many different angles. The ability to change the viewing angle dynamically heightens the 3-D effect and make the graph easier to understand. It also increases the visual appeal of an application using the Plot3D widget.

3.1 Manually Positioning The Observer

The viewing angle of the graph is controlled by the position of an imaginary observer looking directly at the center of the graph. The position of the observer can be set or queried at any time using the ``-observer'' configuration option. Like this:

   gr config -observer {0.8 0.23 10}

3.2 Connecting The Graph To Scrollbars

A Plot3D widget is connected to scrollbars just like any other scrollable Tk widget such as a canvas, or text widget or listbox. The ``-xscrollcommand'' and ``-yscrollcommand'' configuration options on the Plot3D widget are configured to invoke the ``set'' widget command of the appropriate scrollbars, and the ``-command'' configuration options of the scrollbars are set to invoke the ``xview'' or ``yview'' commands of the Plot3D widget. The following code illustrates:

   canvas .c
   scrollbar .xs -orient horizontal -command {gr xview}
   scrollbar .ys -orient vertical -command {gr yview}
   plot3d gr -canvas .c -xscrollcommand {.xs set} -yscrollcommand {.ys set} \
   grid .c -column 0 -row 0
   grid .ys -column 1 -row 0 -sticky ns
   grid .xs -column 0 -row 1 -sticky ew

3.3 Rotating The Graph By Dragging

The position of the observer can be varied by clicking and dragging on the surface of the canvas in addition to moving the scrollbars. The following bindings induce this behavior:

   bind .c <ButtonPress-1> {gr drag from %x %y}
   bind .c <B1-Motion> {gr drag to %x %y}

It works to connect a Plot3D widget to scrollbars and to allow drag rotations at the same time. If you do both, then the scrollbars will automatically move when you rotate the graph by dragging.

3.4 Making The Graph Rotate By Itself

To heighten the 3-D effect, you can cause the graph in a Plot3D widget to continuously change the position of the observer relative to the center of the graph. This gives the graph the appearance of constantly rotating in three dimensions. We call the effect ``motoring''.

There are two configuration options that control the automatic rotation motor. The ``-motorframedelay'' option specifies the amount of time between frames in the rotation animation, in milliseconds. Thus if you set ``-motorframedelay'' to 100, the graph will redraw itself with at different viewing angle about 10 times per second. You can turn the motor off by setting ``-motorframedelay'' to 0.

To obtain a pleasing animation effect for our example graph above, we can add the following line of code:

  gr config -motorframedelay 150

  button .b -command MotorOnOff
  pack .b
  proc MotorOnOff {} {
    if {[gr cget -motorframedelay]==0} {
       .b config -text {Stop the Motor}
       gr config -motorframedelay 150
    } else {
       .b config -text {Start the Motor}
       gr config -motorframedelay 0
    }
  }

The other configuration option associated with the motor is called ``-motorcontrol''. This option allows you to specify the minimum and maximum azimuth and elevation that the motor will traverse and the rate at which the motor moves in each direction. You can change any or all of these values to give different rotation angles and speed. But the default values usually give a satisfactory appearance, and so these parameters rarely need to be changed.

The argument to the ``-motorcontrol'' option is a list of 6 floating point numbers in this order: minimum azimuth, maximum azimuth, rate of change in azimuth, minimum elevation, maximum elevation and rate of change of elevation. The defaults values are -0.15, 1.5, 0.1, 0.0, 0.8 and 0.071, respectively.

3.5 Speed And Efficiency Considerations

Every time the position of the observer to a Plot3D graph widget changes, the entire graph must be completely redrawn. This can involve issuing hundreds of canvas widget commands, and for complex graphs or slow computers, can take a substantial fraction of a second. But in order to achieve a responsive display, the graph needs to be updated in less than a tenth of a second.

In order to help the graph redisplay itself quickly enough, the amount of detail shown by the graph can be reduced while it is being rotated. Reducing the amount of detail displayed reduces the number of canvas widget commands that must be issued, and thus makes the graph seem more responsive.

The amount of detail shown by the Plot3D widget is controlled by the ``-detail'' configuration option. The normal setting for this option is ``full'' which means that all graph details are displayed. The other two possible values for the -detail option are ``partial'' and ``outline''. When -detail is set ot ``partial'', the graph lines and background planes are shown as normal, but the tic marks and text markings around the edge of the graph are omitted. In ``outline'' mode, most of the graph drawing is omitted, and only a box outline of the graph is displayed. Figure 3.1 shows the same graph at each of the three levels of detail selectable using the -detail option.

Figure 3.1: The Same Graph At Three Levels Of Detail: ``full'', ``partial'' and ``outline''

The code fragment below shows a typical application of the -detail configuration option in reducing the amount of redisplaying necessary while a graph is being rotated by dragging.

   bind .c <ButtonPress-1> {gr drag from %x %y}
   bind .c <B1-Motion> {gr config -detail partial; gr drag to %x %y}
   bind .c <ButtonRelease-1> {gr config -detail full}

With these bindings, the amount of detail drawn on the graph is reduced as soon as the you begin to drag the graph, and remains reduced as long as the mouse button is held down. But when the mouse button is released, indicating that the drag has completed, the -detail option is restored to ``full'' so that all graph details are once again displayed.

In this example, the level of detail is reduced to ``partial'' which is adequate for a responsive display on most systems. On a slow computer, or with an unusually complex graph, you may get better results by reducing the level of detail to ``outline''.

Bindings similar to the above can reduce the level of detail when the graph is rotated using scrollbars. We have:

  bind .xs <B1-Motion> {gr config -detail partial}
  bind .xs <ButtonRelease-1> {gr config -detail full}
  bind .ys <B1-Motion> {gr config -detail partial}
  bind .ys <ButtonRelease-1> {gr config -detail full}

4 Viewing Slices Of The Graph

Sometimes it is helpful to be able to see a cross-section or slice of a graph in order to better compare the Y values of the various lines in the graph at a fixed X. An example of this is shown in figure 4.1. This figure shows three images of the same graph sliced at different points along the X axis. To the right of each graph is a two-dimensional image of the slice.

Figure 4.1: Three Slices Of The Same Graph

The rectangular red box that defines the plane of the slices in figure 4.1 is called the ``slice cursor''. You can position the slice cursor at any point along the X axis using the cursor subcommand to the Plot3D widget. Like this:

  gr cursor 4.17934

  set x [gr cursor]

The default appearance of the slice cursor is a black line 1 pixel wide. Usually you will want something different that the default. Fortunately, it is easy to change the appearance of the slice cursor using the ``-cursoroptions'' configuration option. The -cursoroptions option works much like the ``-lineoptions'' option. Its argument is one or more options that are passed to the canvas widget commands that actually draw the cursor. In figure 4.1, the cursor is configured as follows:

  gr config -cursoroptions {-fill red -width 2}

Once a cursor is visible, the user can change the position of the cursor by dragging it with the mouse. No special action is required to enable this feature -- it occurs automatically as part of the drag from and drag to subcommands. If the user presses the mouse button directly on top of the slice cursor and moves the mouse, the slice cursor will move but the graph will stay stationary. If the user presses the mouse button anywhere on the graph other than directly over the slice cursor, then moves the mouse, the slice cursor will stay in the same spot and the graph will rotate. This sounds complex when expressed in words, but it is very intuitive when viewed graphically.

In addition to configuring and positioning the slice cursor, we must have some means of extracting information about a particular slice from the Plot3D widget, so that the slice can be displayed. This is accomplished using the slice subcommands.

The slice subcommand returns a list which contains the value of every line in the graph for a given X coordinate. The X coordinate need not be an integer -- adjacent integral values of the line are interpolated to find the values at intermediate points.

As an example, consider figure 4.1, and especially the middle graph in that figure. The 2-D plot to the right of the 3-D plot is a slice of the 3-D plot taken at an X coordinate of 6.62276. The values for the 2-D plot were extracted from the 3-D plot using the command:

  gr slice 6.62276

  {140 130 180 98.862 192.455}

The 2-D graph of the slice must be handled separately from the Plot3D widget. (One of the 2-D barchart widgets in the BLT extension might be good for this, or you can grow your own from a canvas.) But the Plot3D widget does provide a means to notify the 2-D graph to change its display whenever the slice cursor moves. The ``-cursormovecallback'' configuration option on the Plot3D widget defines a Tcl/Tk command that is executed whenever the slice cursor is moved. In the example, the argument to -cursormovecallback is a Tcl procedure named ``PlotSlice''. The PlotSlice procedure finds the value of the current slice and then updates the 2-D plot accordingly. The following code illustrates the idea:

  proc PlotSlice {} {
    set data [gr slice [gr cursor]]
    # Update the 2-D plot with the information in $data
  }
  gr config -cursormovecallback PlotSlice

5 Adding You Own Annotations

Look back at figures 1.2 and 1.3 above. Both of these images are screen shots of an ordinary Plot3D widget. The Plot3D widget drew everything in these figures, including the extra annotation of the axis and labels and arrows pointing to the two graph lines. You too can add additional annotation like this to your graphs, and this section will tell you how.

There are two features of the Plot3D widget that allow you to add your own annotations: the ``-redrawcallback'' configuration option and the translate subcommand. The -redrawcallback configuration option allows you to specify a Tcl procedure that is invoked every time the graph is redrawn (because the position of the observer changes). Thus, you use the -redrawcallback to specify a routine that actually draws your annotations on the canvas. The translate subcommand converts 3-D coordinate in the space of the graph into the 2-D coordinates space of the canvas widget on which the graph is drawn. This allows your annotation drawing routine, the one called by the -redrawcallback, to figure out where on the canvas widget it needs to draw.

These ideas are best illustrated by an example. The code that puts the ``Graph Line 0'' annotation on figures 1.2 and 1.3 looks something like the following:

  proc DrawLabel {} {
    eval .c create line \
      [gr translate 0.625 1.0 1.2] \
      [gr translate 0.625 0.68 0.75] \
      -arrow last -tags gr
    eval .c create text \
      [gr translate 0.625 1.0 1.25] \
      -text {{Graph Line 0}} -anchor e -tags gr
  }
  gr config -redrawcallback DrawLabel

The procedure DrawLabel does the actual work of drawing the annotation. This procedure contains two commands. The first adds an arrow to the canvas between the points (0.625,1.0,1.2) and (0.625,0.68,0.75). This is the arrow that points from the label to the graph line. The second statement in the DrawLabel procedure adds the text of the label to the canvas.

Notice in both statements how the gr translate subcommand is used to convert 3-D graph coordinates into 2-D canvas coordinates. This translation takes into account the current magnification and rotation of the graph, so your annotation rotates with your graph image automatically.

The return value from gr translate is a list of two floating point numbers. However, the canvas create command requires coordinates that are separate arguments, not elements of a list. For that reason, we have to preface each canvas create command with the eval command that will expand the list of coordinates returned by gr translate into separate arguments. The fact the eval is used means that the argument to the ``-text'' option on the second statement must be enclosed in two sets of curly braces.

One final detail that is important to note is the ``-tags gr'' argument which is added to every canvas item created as part of the annotation. Whenever the graph is redrawn, the Plot3D widget must first remove the prior version of the graph. It does this by executing the command

  .c delete gr

6 Compiling And Installing The Plot3D Widget

All source code to the Plot3D widget is contained in a single file named plot3d.c. Compile this file as any other Tcl/Tk source file.

  cc -O -c plot3d.o

  if (Plot3D_Init(interp) == TCL_ERROR) {
     return TCL_ERROR;
  }

You can also compile the Plot3D widget as a loadable module so that it can be used with an existing wish interpreter or from the Tcl/Tk plugin for Netscape. Under Linux, the command sequence to compile Plot3D into a loadable modules is the following:

  gcc -fPIC -O -c plot3d.c
  gcc -shared -o plot3d.so plot3d.o

  load ./plot3d.so Plot3d

7 Summary

The Plot3D widget is useful on its own as a means for generating interactive 3-D plots of numerical data. But more than that, the design of the Plot3D widget illustrates a promising new technique for developing highly graphical super-widgets on top of the very versatile canvas widget that is a stardard part of Tcl/Tk. By leveraging the existing functionality of the canvas widget, the Plot3D widget was constructed with only a modest amount of additional code (less than 2000 lines) and in only a few weeks of programmer time. We hope that others will join us in generating new graphical super-widgets built on top of the Tk canvas.

8 Copyright Information

The copyright for the source code to the Plot3D widget, and this documentation, is the exclusive property of

Conservation Through Innovation, Ltd
1040 Whipple Street, Suite 225
Prescott, AZ 86301
520.776.7107
http://www.cti-ltd.com