A flexible signal plotter. The plot can be configured and data can be provided either through a file with commands or through direct invocation of the public methods of the class.
When calling the public methods, in most cases the changes will not be visible until paintComponent() is called. To request that this be done, call repaint(). One exception is addPoint(), which makes the new point visible immediately if the plot is visible on the screen and addPoint() is called from the event dispatching thread.
This base class supports a simple file syntax that has largely been replaced by the XML-based PlotML syntax. To read a file or a URL in this older syntax, use the read() method. This older syntax contains any number commands, one per line. Unrecognized commands and commands with syntax errors are ignored. Comments are denoted by a line starting with a pound sign "#". The recognized commands include those supported by the base class, plus a few more. The commands are case insensitive, but are usually capitalized. The number of data sets to be plotted does not need to be specified. Data sets are added as needed. Each dataset can be optionally identified with color (see the base class) or with unique marks. The style of marks used to denote a data point is defined by one of the following commands:
Marks: none Marks: points Marks: dots Marks: various Marks: pixels
Here, "points" are small dots, while "dots" are larger. If "various" is specified, then unique marks are used for the first ten data sets, and then recycled. If "pixels" are specified, then each point is drawn as one pixel. Using no marks is useful when lines connect the points in a plot, which is done by default. However, if persistence is set, then you may want to choose "pixels" because the lines may overlap, resulting in annoying gaps in the drawn line. If the above directive appears before any DataSet directive, then it specifies the default for all data sets. If it appears after a DataSet directive, then it applies only to that data set.
To disable connecting lines, use:
Lines: off
To reenable them, use
Lines: on
You can also specify "impulses", which are lines drawn from a plotted point down to the x axis. Plots with impulses are often called "stem plots." These are off by default, but can be turned on with the command:
Impulses: on
or back off with the command
Impulses: off
If that command appears before any DataSet directive, then the command applies to all data sets. Otherwise, it applies only to the current data set. To create a bar graph, turn off lines and use any of the following commands:
Bars: on Bars: width Bars: width, offset
The
width is a real number specifying the width of the bars in the units of the x axis. The
offset is a real number specifying how much the bar of the
ith data set is offset from the previous one. This allows bars to "peek out" from behind the ones in front. Note that the frontmost data set will be the first one. To turn off bars, use
Bars: off
To specify data to be plotted, start a data set with the following command:
DataSet: string
Here,
string is a label that will appear in the legend. It is not necessary to enclose the string in quotation marks. To start a new dataset without giving it a name, use:
DataSet:
In this case, no item will appear in the legend. New datasets are plotted
behind the previous ones. If the following directive occurs:
ReuseDataSets: on
Then datasets with the same name will be merged. This makes it easier to combine multiple datafiles that contain the same datasets into one file. By default, this capability is turned off, so datasets with the same name are not merged. The data itself is given by a sequence of commands with one of the following forms:
x, y draw: x, y move: x, y x, y, yLowErrorBar, yHighErrorBar draw: x, y, yLowErrorBar, yHighErrorBar move: x, y, yLowErrorBar, yHighErrorBar
The "draw" command is optional, so the first two forms are equivalent. The "move" command causes a break in connected points, if lines are being drawn between points. The numbers
x and
y are arbitrary numbers as supported by the Double parser in Java. If there are four numbers, then the last two numbers are assumed to be the lower and upper values for error bars. The numbers can be separated by commas, spaces or tabs.
Some of the methods, such as those that add points a plot, are executed in the event thread, possibly some time after they are called. If they are called from a thread different from the event thread, then the order in which changes to the plot take effect may be surprising. We recommend that any code you write that changes the plot in visible ways be executed in the event thread. You can accomplish this using the following template:
Runnable doAction = new Runnable() { public void run() { ... make changes here (e.g. setMarksStyle()) ... } }; plot.deferIfNecessary(doAction); This plotter has some limitations:
- If you zoom in far enough, the plot becomes unreliable. In particular, if the total extent of the plot is more than 232 times extent of the visible area, quantization errors can result in displaying points or lines. Note that 232 is over 4 billion.
- The limitations of the log axis facility are listed in the
_gridInit() method in the PlotBox class.
@author Edward A. Lee, Christopher Brooks
@version $Id: Plot.java,v 1.248 2007/12/16 07:29:47 cxh Exp $
@since Ptolemy II 0.2
@Pt.ProposedRating Yellow (cxh)
@Pt.AcceptedRating Yellow (cxh)