1Plotchart(n) Plotchart Plotchart(n)
2______________________________________________________________________________
6
8 Plotchart - Simple plotting and charting package
9
11 package require Tcl ?8.3?
12 package require Tk ?8.3?
14 package require Plotchart ?1.1?
16 ::Plotchart::createXYPlot w xaxis yaxis
18 ::Plotchart::createStripchart w xaxis yaxis
20 ::Plotchart::createPolarPlot w radius_data
22 ::Plotchart::createIsometricPlot w xaxis yaxis stepsize
24 ::Plotchart::create3DPlot w xaxis yaxis zaxis
26 ::Plotchart::createPiechart w
28 ::Plotchart::createBarchart w xlabels yaxis noseries
30 ::Plotchart::createHorizontalBarchart w xlabels yaxis noseries
32 ::Plotchart::createTimechart w time_begin time_end noitems
34 ::Plotchart::createGanttchart w time_begin time_end noitems
36 ?text_width?
37 $anyplot title text
39 $anyplot saveplot filename
41 $anyplot xtext text
43 $anyplot ytext text
45 $anyplot xconfig -option value ...
47 $anyplot yconfig -option value ...
49 $xyplot plot series xcrd ycrd
51 $xyplot contourlines xcrd ycrd values ?classes?
53 $xyplot contourfill xcrd ycrd values ?classes?
55 $xyplot contourbox xcrd ycrd values ?classes?
57 $xyplot colorMap colours
59 $xyplot grid xcrd ycrd
61 $polarplot plot series radius angle
63 $plot3d plotfunc function
65 $plot3d plotfuncont function contours
67 $plot3d gridsize nxcells nycells
69 $plot3d plotdata data
71 $plot3d colours fill border
73 $xyplot dataconfig series -option value ...
75 $pie plot data
77 $pie colours colour1 colour2 ...
79 $barchart plot series ydata colour
81 $barchart plot series xdata colour
83 $timechart period text time_begin time_end colour
85 $timechart milestone text time colour
87 $timechart vertline text time
89 $ganttchart task text time_begin time_end completed
91 $ganttchart milestone text time colour
93 $ganttchart vertline text time
95 $ganttchart connect from to
97 $ganttchart summary text args
99 $ganttchart color keyword newcolor
101 $ganttchart font keyword newfont
103 $isoplot plot rectangle x1 y1 x2 y2 colour
105 $isoplot plot filled-rectangle x1 y1 x2 y2 colour
107 $isoplot plot circle xc yc radius colour
109 $isoplot plot filled-circle xc yc radius colour
111 ::Plotchart::viewPort w pxmin pymin pxmax pymax
113 ::Plotchart::worldCoordinates w xmin ymin xmax ymax
115 ::Plotchart::world3DCoordinates w xmin ymin zmin xmax ymax zmax
117 ::Plotchart::coordsToPixel w x y
119 ::Plotchart::coords3DToPixel w x y z
121 ::Plotchart::polarCoordinates w radmax
123 ::Plotchart::polarToPixel w rad phi
125 ::Plotchart::pixelToCoords w x y
127 ::Plotchart::pixelToIndex w x y
129 ::Plotchart::determineScale xmin xmax
131_________________________________________________________________
133
135 Plotchart is a Tcl-only package that focuses on the easy creation of
136 xy-plots, barcharts and other common types of graphical presentations.
137 The emphasis is on ease of use, rather than flexibility. The procedures
138 that create a plot use the entire canvas window, making the layout of
139 the plot completely automatic.
140 This results in the creation of an xy-plot in, say, ten lines of code:
142 package require Plotchart
144 canvas .c -background white -width 400 -height 200
146 pack .c -fill both
147 #
149 # Create the plot with its x- and y-axes
150 #
151 set s [::Plotchart::createXYPlot .c {0.0 100.0 10.0} {0.0 100.0 20.0}]
152 foreach {x y} {0.0 32.0 10.0 50.0 25.0 60.0 78.0 11.0 } {
154 $s plot series1 $x $y
155 }
156 $s title "Data series"
158 A drawback of the package might be that it does not do any data manage‐
161 ment. So if the canvas that holds the plot is to be resized, the whole
162 plot must be redrawn. The advantage, though, is that it offers a num‐
163 ber of plot and chart types:
164 · XY-plots like the one shown above with any number of data
166 series.
167 · Stripcharts, a kind of XY-plots where the horizontal axis is
169 adjusted automatically. The result is a kind of sliding window
170 on the data series.
171 · Polar plots, where the coordinates are polar instead of carte‐
173 sian.
174 · Isometric plots, where the scale of the coordinates in the two
176 directions is always the same, i.e. a circle in world coordi‐
177 nates appears as a circle on the screen.
178 You can zoom in and out, as well as pan with these plots (Note:
180 this works best if no axes are drawn, the zooming and panning
181 routines do not distinguish the axes), using the mouse buttons
182 with the control key and the arrow keys with the control key.
183 · Piecharts, with automatic scaling to indicate the proportions.
185 · Barcharts, with either vertical or horizontal bars, stacked bars
187 or bars side by side.
188 · Timecharts, where bars indicate a time period and milestones or
190 other important moments in time are represented by triangles.
191 · 3D plots (both for displaying surfaces and 3D bars)
193
195 You create the plot or chart with one single command and then fill the
196 plot with data:
197 ::Plotchart::createXYPlot w xaxis yaxis
199 Create a new xy-plot.
200 w widget (in)
202 Name of the existing canvas widget to hold the plot.
203 xaxis list (in)
205 A 3-element list containing minimum, maximum and stepsize
206 for the x-axis, in this order.
207 yaxis list (in)
209 A 3-element list containing minimum, maximum and stepsize
210 for the y-axis, in this order.
211 ::Plotchart::createStripchart w xaxis yaxis
214 Create a new strip chart. The only difference to a regular XY
215 plot is that the x-axis will be automatically adjusted when the
216 x-coordinate of a new point exceeds the maximum.
217 w widget (in)
219 Name of the existing canvas widget to hold the plot.
220 xaxis list (in)
222 A 3-element list containing minimum, maximum and stepsize
223 for the x-axis, in this order.
224 yaxis list (in)
226 A 3-element list containing minimum, maximum and stepsize
227 for the y-axis, in this order.
228 ::Plotchart::createPolarPlot w radius_data
231 Create a new polar plot.
232 w widget (in)
234 Name of the existing canvas widget to hold the plot.
235 radius_data list (in)
237 A 2-element list containing maximum radius and stepsize
238 for the radial axis, in this order.
239 ::Plotchart::createIsometricPlot w xaxis yaxis stepsize
242 Create a new isometric plot, where the vertical and the horizon‐
243 tal coordinates are scaled so that a circle will truly appear as
244 a circle.
245 w widget (in)
247 Name of the existing canvas widget to hold the plot.
248 xaxis list (in)
250 A 2-element list containing minimum, and maximum for the
251 x-axis, in this order.
252 yaxis list (in)
254 A 2-element list containing minimum, and maximum for the
255 y-axis, in this order.
256 stepsize float|noaxes (in)
258 Either the stepsize used by both axes or the keyword
259 noaxes to signal the plot that it should use the full
260 area of the widget, to not draw any of the axes.
261 ::Plotchart::create3DPlot w xaxis yaxis zaxis
264 Create a new 3D plot.
265 w widget (in)
267 Name of the existing canvas widget to hold the plot.
268 xaxis list (in)
270 A 3-element list containing minimum, maximum and stepsize
271 for the x-axis, in this order.
272 yaxis list (in)
274 A 3-element list containing minimum, maximum and stepsize
275 for the y-axis, in this order.
276 zaxis list (in)
278 A 3-element list containing minimum, maximum and stepsize
279 for the z-axis, in this order.
280 ::Plotchart::createPiechart w
283 Create a new piechart.
284 w widget (in)
286 Name of the existing canvas widget to hold the plot.
287 ::Plotchart::createBarchart w xlabels yaxis noseries
290 Create a new barchart with vertical bars. The horizontal axis
291 will display the labels contained in the argument xlabels. The
292 number of series given by noseries determines both the width of
293 the bars, and the way the series will be drawn.
294 If the keyword stacked was specified the series will be drawn
296 stacked on top of each other. Otherwise each series that is
297 drawn will be drawn shifted to the right.
298 w widget (in)
300 Name of the existing canvas widget to hold the plot.
301 xlabels list (in)
303 List of labels for the x-axis. Its length also determines
304 the number of bars that will be plotted per series.
305 yaxis list (in)
307 A 3-element list containing minimum, maximum and stepsize
308 for the y-axis, in this order.
309 noseries int|stacked (in)
311 The number of data series that will be plotted. This has
312 to be an integer number greater than zero (if stacked is
313 not used).
314 ::Plotchart::createHorizontalBarchart w xlabels yaxis noseries
317 Create a new barchart with horizontal bars. The vertical axis
318 will display the labels contained in the argument ylabels. The
319 number of series given by noseries determines both the width of
320 the bars, and the way the series will be drawn.
321 If the keyword stacked was specified the series will be drawn
323 stacked from left to right. Otherwise each series that is drawn
324 will be drawn shifted upward.
325 w widget (in)
327 Name of the existing canvas widget to hold the plot.
328 ylabels list (in)
330 List of labels for the y-axis. Its length also determines
331 the number of bars that will be plotted per series.
332 yaxis list (in)
334 A 3-element list containing minimum, maximum and stepsize
335 for the x-axis, in this order.
336 noseries int|stacked (in)
338 The number of data series that will be plotted. This has
339 to be an integer number greater than zero (if stacked is
340 not used).
341 ::Plotchart::createTimechart w time_begin time_end noitems
344 Create a new timechart. The time axis (= x-axis) goes from
345 time_begin to time_end, and the vertical spacing is determined
346 by the number of items to plot.
347 w widget (in)
349 Name of the existing canvas widget to hold the plot.
350 time_begin string (in)
352 The start time given in a form that is recognised by the
353 clock scan command (e.g. "1 january 2004").
354 time_end string (in)
356 The end time given in a form that is recognised by the
357 clock scan command (e.g. "1 january 2004").
358 noitems int (in)
360 Expected/maximum number of items. This determines the
361 vertical spacing.
362 ::Plotchart::createGanttchart w time_begin time_end noitems
364 ?text_width?
365 Create a new Gantt chart. The time axis (= x-axis) goes from
366 time_begin to time_end, and the vertical spacing is determined
367 by the number of items to plot. Via the specific commands you
368 can then add tasks and connections between the tasks.
369 w widget (in)
371 Name of the existing canvas widget to hold the plot.
372 time_begin string (in)
374 The start time given in a form that is recognised by the
375 clock scan command (e.g. "1 january 2004").
376 time_end string (in)
378 The end time given in a form that is recognised by the
379 clock scan command (e.g. "1 january 2004").
380 noitems int (in)
382 Expected/maximum number of items. This determines the
383 vertical spacing.
384 text_width int
386 Expected/maximum width of the descriptive text (roughly
387 in characters, for the actual space reserved for the
388 text, it is assumed that a character is about ten pixels
389 wide). Defaults to 20.
390
392 Each of the creation commands explained in the last section returns the
393 name of a new object command that can be used to manipulate the plot or
394 chart. The subcommands available to a chart command depend on the type
395 of the chart.
396 General subcommands for all types of charts. $anyplot is the command
398 returned by the creation command:
399 $anyplot title text
401 Specify the title of the whole chart.
402 text string (in)
404 The text of the title to be drawn.
405 $anyplot saveplot filename
408 Draws the plot into a file, using PostScript.
409 filename string (in)
411 Contain the path name of the file to write the plot to.
412 $anyplot xtext text
415 Specify the title of the x-axis, for those plots that have a
416 straight x-axis.
417 text string (in)
419 The text of the x-axis label to be drawn.
420 $anyplot ytext text
423 Specify the title of the y-axis, for those plots that have a
424 straight y-axis.
425 text string (in)
427 The text of the y-axis label to be drawn.
428 $anyplot xconfig -option value ...
431 Set one or more configuration parameters for the x-axis. The
432 following options are supported:
433 format fmt
435 The format for the numbers along the axis.
436 ticklength length
438 The length of the tickmarks (in pixels).
439 ticklines boolean
441 Whether to draw ticklines (true) or not (false).
442 scale scale_data
444 New scale data for the axis, i.e. a 3-element list con‐
445 taining minimum, maximum and stepsize for the axis, in
446 this order.
447 Beware: Setting this option will clear all data from the
449 plot.
450 $anyplot yconfig -option value ...
453 Set one or more configuration parameters for the y-axis. This
454 method accepts the same options and values as the method xcon‐
455 fig.
456 Note: The commands xconfig and yconfig are currently implemented only
458 for XY-plots and only the option -format has any effect.
459 For xy plots and stripcharts:
461 $xyplot plot series xcrd ycrd
463 Add a data point to the plot.
464 series string (in)
466 Name of the data series the new point belongs to.
467 xcrd float (in)
469 X-coordinate of the new point.
470 ycrd float (in)
472 Y-coordinate of the new point.
473 For xy plots:
475 $xyplot contourlines xcrd ycrd values ?classes?
477 Draw contour lines for the values given on the grid. The grid is
478 defined by the xcrd and ycrd arguments (they give the x- and y-
479 coordinates of the grid cell corners). The values are given at
480 these corners. The classes determine which contour lines are
481 drawn. If a value on one of the corners is missing, the contour
482 lines in that cell will not be drawn.
483 xcrd list (in)
485 List of lists, each value is an x-coordinate for a grid
486 cell corner
487 ycrd list (in)
489 List of lists, each value is an y-coordinate for a grid
490 cell corner
491 values list (in)
493 List of lists, each value is the value at a grid cell
494 corner
495 classes list (in)
497 List of class values or a list of lists of two elements
498 (each inner list the class value and the colour to be
499 used). If empty or missing, the classes are determined
500 automatically.
501 Note: The class values must enclose the whole range of
503 values.
504 $xyplot contourfill xcrd ycrd values ?classes?
507 Draw filled contours for the values given on the grid. (The use
508 of this method is identical to the "contourlines" method).
509 $xyplot contourbox xcrd ycrd values ?classes?
511 Draw the cells as filled quadrangles. The colour is determined
512 from the average of the values on all four corners.
513 $xyplot colorMap colours
515 Set the colours to be used with the contour methods. The argu‐
516 ment is either a predefined colourmap (grey/gray, jet, hot or
517 cool) or a list of colours. When selecting the colours for actu‐
518 ally drawing the contours, the given colours will be interpo‐
519 lated (based on the HLS scheme).
520 colours list (in)
522 List of colour names or colour values or one of the pre‐
523 defined maps:
524 · grey or gray: gray colours from dark to light
526 · jet: rainbow colours
528 · hot: colours from yellow via red to darkred
530 · cool: colours from cyan via blue to magenta
532 $xyplot grid xcrd ycrd
534 Draw the grid cells as lines connecting the (valid) grid points.
535 xcrd list (in)
537 List of lists, each value is an x-coordinate for a grid
538 cell corner
539 ycrd list (in)
541 List of lists, each value is an y-coordinate for a grid
542 cell corner
543 For polar plots:
545 $polarplot plot series radius angle
547 Add a data point to the polar plot.
548 series string (in)
550 Name of the data series the new point belongs to.
551 radius float (in)
553 Radial coordinate of the new point.
554 angle float (in)
556 Angular coordinate of the new point (in degrees).
557 For 3D plots:
559 $plot3d plotfunc function
561 Plot a function defined over two variables x and y. The resolu‐
562 tion is determined by the set grid sizes (see the method grid‐
563 size for more information).
564 function string (in)
566 Name of the procedure that calculates the z-value for the
567 given x and y coordinates. The procedure has to accept
568 two float arguments (x is first argument, y is second)
569 and return a floating-point value.
570 $plot3d plotfuncont function contours
573 Plot a function defined over two variables x and y using the
574 contour levels in contours to colour the surface. The resolu‐
575 tion is determined by the set grid sizes (see the method grid‐
576 size for more information).
577 function string (in)
579 Name of the procedure that calculates the z-value for the
580 given x and y coordinates. The procedure has to accept
581 two float arguments (x is first argument, y is second)
582 and return a floating-point value.
583 contours list (in)
585 List of values in ascending order that represent the con‐
586 tour levels (the boundaries between the colours in the
587 contour map).
588 $plot3d gridsize nxcells nycells
591 Set the grid size in the two directions. Together they determine
592 how many polygons will be drawn for a function plot.
593 nxcells int (in)
595 Number of grid cells in x direction. Has to be an integer
596 number greater than zero.
597 nycells int (in)
599 Number of grid cells in y direction. Has to be an integer
600 number greater than zero.
601 $plot3d plotdata data
604 Plot a matrix of data.
605 data list (in)
607 The data to be plotted. The data has to be provided as a
608 nested list with 2 levels. The outer list contains rows,
609 drawn in y-direction, and each row is a list whose ele‐
610 ments are drawn in x-direction, for the columns. Example:
611 set data {
614 {1.0 2.0 3.0}
615 {4.0 5.0 6.0}
616 }
617 $plot3d colours fill border
621 Configure the colours to use for polygon borders and inner area.
622 fill color (in)
624 The colour to use for filling the polygons.
625 border color (in)
627 The colour to use for the border of the polygons.
628 For xy plots, stripcharts and polar plots:
630 $xyplot dataconfig series -option value ...
632 Set the value for one or more options regarding the drawing of
633 data of a specific series.
634 series string (in)
636 Name of the data series whose configuration we are chang‐
637 ing.
638 The following option are known:
640 colour c
642 color c
644 The colour to be used when drawing the data series.
645 type enum
647 The drawing mode chosen for the series. This can be one
648 of line, symbol, or both.
649 symbol enum
651 What kind of symbol to draw. The value of this option is
652 ignored when the drawing mode line was chosen. This can
653 be one of plus, cross, circle, up (triangle pointing up),
654 down (triangle pointing down), dot (filled circle),
655 upfilled or downfilled (filled triangles).
656 For piecharts:
658 $pie plot data
660 Fill a piechart.
661 data list (in)
663 A list of pairs (labels and values). The values determine
664 the relative size of the circle segments. The labels are
665 drawn beside the circle.
666 $pie colours colour1 colour2 ...
668 Set the colours to be used.
669 colour1 color (in)
671 The first colour.
672 colour2 color (in)
674 The second colour, and so on.
675 For vertical barcharts:
677 $barchart plot series ydata colour
679 Add a data series to a barchart.
680 series string (in)
682 Name of the series the values belong to.
683 ydata list (in)
685 A list of values, one for each x-axis label.
686 colour color (in)
688 The colour of the bars.
689 For horizontal barcharts:
691 $barchart plot series xdata colour
693 Add a data series to a barchart.
694 series string (in)
696 Name of the series the values belong to.
697 xdata list (in)
699 A list of values, one for each y-axis label.
700 colour color (in)
702 The colour of the bars.
703 For timecharts:
705 $timechart period text time_begin time_end colour
707 Add a time period to the chart.
708 text string (in)
710 The text describing the period.
711 time_begin string (in)
713 Start time of the period.
714 time_end string (in)
716 Stop time of the period.
717 colour color (in)
719 The colour of the bar (defaults to black).
720 $timechart milestone text time colour
723 Add a milestone (represented as an point-down triangle) to the
724 chart.
725 text string (in)
727 The text describing the milestone.
728 time string (in)
730 Time at which the milestone must be positioned.
731 colour color (in)
733 The colour of the triangle (defaults to black).
734 $timechart vertline text time
737 Add a vertical line (to indicate the start of the month for
738 instance) to the chart.
739 text string (in)
741 The text appearing at the top (an abbreviation of the
742 date/time for instance).
743 time string (in)
745 Time at which the line must be positioned.
746 For Gantt charts:
748 $ganttchart task text time_begin time_end completed
750 Add a task with its period and level of completion to the chart.
751 Returns a list of canvas items that can be used for further
752 manipulations, like connecting two tasks.
753 text string (in)
755 The text describing the task.
756 time_begin string (in)
758 Start time of the task.
759 time_end string (in)
761 Stop time of the task.
762 completed float (in)
764 The percentage of the task that is completed.
765 $ganttchart milestone text time colour
768 Add a milestone (represented as an point-down triangle) to the
769 chart.
770 text string (in)
772 The text describing the milestone.
773 time string (in)
775 Time at which the milestone must be positioned.
776 colour color (in)
778 The colour of the triangle (defaults to black).
779 $ganttchart vertline text time
782 Add a vertical line (to indicate the start of the month for
783 instance) to the chart.
784 text string (in)
786 The text appearing at the top (an abbreviation of the
787 date/time for instance).
788 time string (in)
790 Time at which the line must be positioned.
791 $ganttchart connect from to
794 Add an arrow that connects the from task with the to task.
795 from list (in)
797 The list of items returned by the "task" command that
798 represents the task from which the arrow starts.
799 text string (in)
801 The text summarising the tasks
802 args list (in)
804 One or more tasks (the lists returned by the "task" com‐
805 mand). They are shifted down to make room for the sum‐
806 mary.
807 to list (in)
809 The list of items returned by the "task" command that
810 represents the task at which the arrow ends.
811 $ganttchart summary text args
814 Add a summary item that spans all the tasks listed. The graphi‐
815 cal representation is a thick bar running from the leftmost task
816 to the rightmost.
817 Use this command before connecting the tasks, as the arrow would
819 not be shifted down!
820 text string (in)
822 The text summarising the tasks
823 args list (in)
825 One or more tasks (the lists returned by the "task" com‐
826 mand). They are shifted down to make room for the sum‐
827 mary.
828 $ganttchart color keyword newcolor
831 Set the colour of a part of the Gantt chart. These colours hold
832 for all items of that type.
833 keyword string (in)
835 The keyword indicates which part of the Gantt chart to
836 change:
837 · description - the colour of the descriptive text
839 · completed - the colour of the filled bar repre‐
841 senting the completed part of a task
842 · left - the colour for the part that is not yet
844 completed
845 · odd - the background colour for the odd entries
847 · even - the background colour for the even entries
849 · summary - the colour for the summary text
851 · summarybar - the colour for the bar for a summary
853 newcolor string (in)
855 The new colour for the chosen items.
856 $ganttchart font keyword newfont
859 Set the font of a part of the Gantt chart. These fonts hold for
860 all items of that type.
861 keyword string (in)
863 The keyword indicates which part of the Gantt chart to
864 change:
865 · description - the font used for descriptive text
867 · summary - the font used for summaries
869 · scale - the font used for the time scale
871 newfont string (in)
873 The new font for the chosen items.
874 For isometric plots (to be extended):
876 $isoplot plot rectangle x1 y1 x2 y2 colour
878 Plot the outlines of a rectangle.
879 x1 float (in)
881 Minimum x coordinate of the rectangle to be drawn.
882 y1 float (in)
884 Minimum y coordinate of the rectangle.
885 x2 float (in)
887 Maximum x coordinate of the rectangle to be drawn.
888 y2 float (in)
890 Maximum y coordinate of the rectangle.
891 colour color (in)
893 The colour of the rectangle.
894 $isoplot plot filled-rectangle x1 y1 x2 y2 colour
897 Plot a rectangle filled with the given colour.
898 x1 float (in)
900 Minimum x coordinate of the rectangle to be drawn.
901 y1 float (in)
903 Minimum y coordinate of the rectangle.
904 x2 float (in)
906 Maximum x coordinate of the rectangle to be drawn.
907 y2 float (in)
909 Maximum y coordinate of the rectangle.
910 colour color (in)
912 The colour of the rectangle.
913 $isoplot plot circle xc yc radius colour
916 Plot the outline of a circle.
917 xc float (in)
919 X coordinate of the circle's centre.
920 yc float (in)
922 Y coordinate of the circle's centre.
923 colour color (in)
925 The colour of the circle.
926 $isoplot plot filled-circle xc yc radius colour
929 Plot a circle filled with the given colour.
930 xc float (in)
932 X coordinate of the circle's centre.
933 yc float (in)
935 Y coordinate of the circle's centre.
936 colour color (in)
938 The colour of the circle.
939 There are a number of public procedures that may be useful in specific
941 situations: Pro memorie.
942
944 Besides the commands that deal with the plots and charts directly,
945 there are a number of commands that can be used to convert world coor‐
946 dinates to pixels and vice versa. These include:
947 ::Plotchart::viewPort w pxmin pymin pxmax pymax
949 Set the viewport for window w. Should be used in cooperation
950 with ::Plotchart::worldCoordinates.
951 w widget (in)
953 Name of the window (canvas widget) in question.
954 pxmin float (in)
956 Left-most pixel coordinate.
957 pymin float (in)
959 Top-most pixel coordinate (remember: the vertical pixel
960 coordinate starts with 0 at the top!).
961 pxmax float (in)
963 Right-most pixel coordinate.
964 pymax float (in)
966 Bottom-most pixel coordinate.
967 ::Plotchart::worldCoordinates w xmin ymin xmax ymax
970 Set the extreme world coordinates for window w. The world coor‐
971 dinates need not be in ascending order (i.e. xmin can be larger
972 than xmax, so that a reversal of the x-axis is achieved).
973 w widget (in)
975 Name of the window (canvas widget) in question.
976 xmin float (in)
978 X-coordinate to be mapped to left side of viewport.
979 ymin float (in)
981 Y-coordinate to be mapped to bottom of viewport.
982 xmax float (in)
984 X-coordinate to be mapped to right side of viewport.
985 ymax float (in)
987 Y-coordinate to be mapped to top side of viewport.
988 ::Plotchart::world3DCoordinates w xmin ymin zmin xmax ymax zmax
991 Set the extreme three-dimensional world coordinates for window
992 w. The world coordinates need not be in ascending order (i.e.
993 xmin can be larger than xmax, so that a reversal of the x-axis
994 is achieved).
995 w widget (in)
997 Name of the window (canvas widget) in question.
998 xmin float (in)
1000 X-coordinate to be mapped to front side of the 3D view‐
1001 port.
1002 ymin float (in)
1004 Y-coordinate to be mapped to left side of the viewport.
1005 zmin float (in)
1007 Z-coordinate to be mapped to bottom of viewport.
1008 xmax float (in)
1010 X-coordinate to be mapped to back side of viewport.
1011 ymax float (in)
1013 Y-coordinate to be mapped to right side of viewport.
1014 zmax float (in)
1016 Z-coordinate to be mapped to top side of viewport.
1017 ::Plotchart::coordsToPixel w x y
1020 Return a list of pixel coordinates valid for the given window.
1021 w widget (in)
1023 Name of the window (canvas widget) in question.
1024 x float (in)
1026 X-coordinate to be mapped.
1027 y float (in)
1029 Y-coordinate to be mapped.
1030 ::Plotchart::coords3DToPixel w x y z
1033 Return a list of pixel coordinates valid for the given window.
1034 w widget (in)
1036 Name of the window (canvas widget) in question.
1037 x float (in)
1039 X-coordinate to be mapped.
1040 y float (in)
1042 Y-coordinate to be mapped.
1043 y float (in)
1045 Z-coordinate to be mapped.
1046 ::Plotchart::polarCoordinates w radmax
1049 Set the extreme polar coordinates for window w. The angle always
1050 runs from 0 to 360 degrees and the radius starts at 0. Hence you
1051 only need to give the maximum radius. Note: If the viewport is
1052 not square, this procedure will not adjust the extremes, so that
1053 would result in an elliptical plot. The creation routine for a
1054 polar plot always determines a square viewport.
1055 w widget (in)
1057 Name of the window (canvas widget) in question.
1058 radmax float (in)
1060 Maximum radius.
1061 ::Plotchart::polarToPixel w rad phi
1064 Wrapper for a call to ::Plotchart::coordsToPixel, which assumes
1065 the world coordinates and viewport are set appropriately. Con‐
1066 verts polar coordinates to pixel coordinates. Note: To be use‐
1067 ful it should be accompanied by a matching ::Plotchart::worldCo‐
1068 ordinates procedure. This is automatically taken care of in the
1069 creation routine for polar plots.
1070 w widget (in)
1072 Name of the window (canvas widget) in question.
1073 rad float (in)
1075 Radius of the point.
1076 phi float (in)
1078 Angle to the positive x-axis.
1079 ::Plotchart::pixelToCoords w x y
1082 Return a list of world coordinates valid for the given window.
1083 w widget (in)
1085 Name of the window (canvas widget) in question.
1086 x float (in)
1088 X-pixel to be mapped.
1089 y float (in)
1091 Y-pixel to be mapped.
1092 ::Plotchart::pixelToIndex w x y
1094 Return the index of the pie segment containing the pixel coordi‐
1095 nates (x,y)
1096 w widget (in)
1098 Name of the window (canvas widget) in question, holding a
1099 piechart.
1100 x float (in)
1102 X-pixel to be mapped.
1103 y float (in)
1105 Y-pixel to be mapped.
1106 Furthermore there is a routine to determine "pretty" numbers for use
1108 with an axis:
1109 ::Plotchart::determineScale xmin xmax
1111 Determine "pretty" numbers from the given range and return a
1112 list containing the minimum, maximum and stepsize that can be
1113 used for a (linear) axis.
1114 xmin float (in)
1116 Rough minimum value for the scaling
1117 xmax float (in)
1119 Rough maximum value for the scaling.
1120
1122 Besides output to the canvas on screen, the module is capable, via can‐
1123 vas postscript, of producing PostScript files. One may wonder whether
1124 it is possible to extend this set of output formats and the answer is
1125 "yes". This section tries to sum up the aspects of using this module
1126 for another sort of output.
1127 One way you can create output files in a different format, is by exam‐
1129 ining the contents of the canvas after everything has been drawn and
1130 render that contents in the right form. This is probably the easiest
1131 way, as it involves nothing more than the re-creation of all the ele‐
1132 ments in the plot that are already there.
1133 The drawback of that method is that you need to have a display, which
1135 is not always the case if you run a CGI server or something like that.
1136 An alternative is to emulate the canvas command. For this to work, you
1138 need to know which canvas subcommands are used and what for. Obviously,
1139 the create subcommand is used to create the lines, texts and other
1140 items. But also the raise and lower subcommands are used, because with
1141 these the module can influence the drawing order - important to simu‐
1142 late a clipping rectangle around the axes. (The routine DrawMask is
1143 responsible for this - if the output format supports proper clipping
1144 areas, then a redefinition of this routine might just solve this).
1145 Furthermore, the module uses the cget subcommand to find out the sizes
1147 of the canvas. A more mundane aspect of this is that the module cur‐
1148 rently assumes that the text is 14 pixels high and that 80 pixels in
1149 width suffice for the axis' labels. No "hook" is provided to customise
1150 this.
1151 In summary:
1153 · Emulate the create subcommand to create all the items in the
1155 correct format
1156 · Emulate the cget subcommand for the options -width and -height
1158 to allow the correct calculation of the rectangle's position and
1159 size
1160 · Solve the problem of raising and lowering the items so that they
1162 are properly clipped, for instance by redefining the routine
1163 DrawMask.
1164 · Take care of the currently fixed text size properties
1166
1168 In this version there are a lot of things that still need to be imple‐
1169 mented:
1170 · General options like legends and text to the axes.
1172 · More robust handling of incorrect calls (right now the proce‐
1174 dures may fail when called incorrectly):
1175 · The axis drawing routines can not handle inverse axes
1177 right now.
1178 · If the user provides an invalid date/time string, the
1180 routines simply throw an error.
1181
1183 I have the following wishlist:
1184 · Isometric plots - allow new items to be implemented easily.
1186 · Add support for histograms where the independent axis is numeri‐
1188 cal.
1189 · A general 3D viewer - emphasis on geometry, not a ray-tracer.
1191
1193 3D bars, 3D surfaces, bar charts, charts, coordinate transformations,
1194 coordinates, graphical presentation, isometric plots, pie charts, plot‐
1195 ting, polar plots, strip charts, time charts, xy-plots
1196
1198 Copyright (c) 2004 Arjen Markus <arjenmarkus@users.sourceforge.net>
1199plotchart 1.1 Plotchart(n)