Ptplot Frequently Asked Questions

Below are some answers to frequently asked questions about ptplot. This page contains links to documents about Ptplot internals and infrastructure.

Contents

  • 1. General
  • 1.1 What Is Ptplot?
  • 1.2 How do I pronounce 'ptplot'?
  • 1.3 What is the copyright?
  • 1.4 How do I contact the authors?
  • 1.5 Is there a mailing list?
  • 1.6 What is the relationship between xgraph and ptplot?
  • 1.7 What is the relationship between ptplot and Ptolemy II?
  • 1.8 Does Ptplot contain encryption?
  • 1.9 Does Ptplot have a US Export Control Classification Number?
  • 2. Installation questions
  • 2.1 How do I download ptplot?
  • 2.2 What platforms does ptplot run under?
  • 2.3 What do I need to Install Ptplot?
  • 2.4 Troubleshooting
  • 2.5 Is there a bug list?
  • 2.6 What features might you someday implement?
  • 3. How do I . . .
  • 3.1 Plot my own data?
  • 3.2 How do I plot binary data?
  • 3.3 How do I handle endian issues in binary data?
  • 3.4 How do I print a plot from a Plot applet or application?
  • 3.5 How do I plot two datafiles in an applet?
  • 3.6 How do I have two separate plots?
  • 3.7 How do I create a simple standalone Plot application?
  • 3.8 Why is the HTML so complex for the applets?
  • 3.9 How do I create a simple standalone Plot applet?
  • 3.10 How do I set the ranges for a plot that is using log axes?
  • 3.11 Does Ptplot support 3-D plots?

  • 1. General

    1.1 What Is Ptplot?
    Ptplot is a Java 2-D graphing component. Ptplot can be used in applets and applications. The top-level Ptplot page describes Ptplot further.
    1.2 How do I pronounce 'ptplot'?
    pee-tee-plot. Unlike with Ptolemy, the initial p in the pt is pronounced.
    1.3 What is the copyright?
    Ptplot is released under the fairly liberal UC Berkeley copyright, see copyright.txt. Most files have the copyright at the top, for example, see Plot.java.

    Ptplot is free for academic and commercial use. You an incorporate it into products, but you need to include follow the instructions in the copyright notice.

    This copyright is based on the Tcl copyright that was used when Prof. Ousterhout was developing Tcl here at UC Berkeley. This copyright was also used in Ptolemy Classic, which has been used in commercial products.

    If you use Ptplot in a product, and you would like us to include a pointer to your use in our Third Party uses of Ptplot page, then send email to ptplot at ptolemy eecs berkeley edu.

    This style of copyright is often referred to the community as a "BSD" copyright because it was used for the "Berkeley Standard Distribution" of Unix. It is much more liberal that the commonly used "GPL" or "GNU Public License," which encumbers the software and derivative works with the requirement that they carry the source code and the same copyright agreement. The BSD copyright requires that the software and derivative work carry the identity of the copyright owner, as embodied in the lines:

    Copyright (c) 1999-2010 The Regents of the University of California.
    All rights reserved.
    

    The copyright also requires that copies and derivative works include the disclaimer of liability in BOLD. It specifically does not require that copies of the software or derivative works carry the middle paragraph, so such copies and derivative works need not grant similarly liberal rights to users of the software.

    The intent of the BSD copyright is to maximize the potential impact of the software by enabling uses of the software that are inconsistent with disclosing the source code or granting free redistribution rights. For example, a commercial enterprise can extend the software, adding value, and sell the original software embodied with the extensions. Economic principles indicate that granting free redistribution rights may render the enterprise business model untenable, so many business enterprises avoid software with GPL licenses. Economic principles also indicate that, in theory, fair pricing of derivative works must be based on the value of the extensions, the packaging, or the associated services provided by the enterprise. The pricing cannot reflect the value of the free software, since an informed consumer will, in theory, obtain that free software from another source.

    Software with a BSD license can also be more easily included in defense or national-security related applications, where free redistribution of source code and licenses may be inconsistent with the mission of the software. Ptolemy II can include other software with copyrights that are different from the BSD copyright. In general, we do not include software with the GNU General Public License (GPL) license, because provisions of the GPL license require that software with which GLP'd code is integrated also be encumbered by the GPL license. In the past, we have made an exception for GPL'd code that is aggregated with Ptolemy II but not directly combined with Ptolemy II. For example cvs2cl.pl was shipped with Ptolemy II. This file is a GPL'd Perl script that access the CVS database and generates a ChangeLog file. This script is not directly called by Ptolemy II, and bwe include it as a ``mere aggregation'' and thus Ptolemy II does not fall under the GPL. Note that we do not include GPL'd Java files that are compiled and then called from Ptolemy II because this would combine Ptolemy II with the GPL'd code and thus encumber Ptolemy II with the GPL.

    Another GNU license is the GNU Library General Public License now known as the GNU Lesser General Public License (LGPL). We try to avoid packages that have this license, but we on occasion we have included them with Ptolemy II. The LGPL license is less strict than the GPL - the LGPL permits linking with other packages without encumbering the other package. In general, it is best if you avoid GNU code. If you are considering using code with the GPL or LGPL, we encourage you to carefully read the license and to also consult the GNU GPL FAQ at http://www.gnu.org/licenses/gpl-faq.html.

    We also avoid including software with proprietary copyrights that do not permit redistribution of the software.

    1.4 How do I contact the authors?
    The primary author of Ptplot is Professor Edward A. Lee. Christopher Brooks is a coauthor. William Wu and Lukito Muliadi contributed code. You can contact the authors via ptplot at ptolemy eecs berkeley edu.
    1.5 Is there a mailing list?
    We maintain the ptplot-announce alias for announcing new ptplot releases. This alias is for Ptplot announcements only. Thus, you cannot post to this group. To subscribe to this group, See https://lists.eecs.berkeley.edu/sympa/subscribe/ptplot-announce.
    1.6 What is the relationship between xgraph and ptplot?
    The introduction contains a description of the relationship between xgraph and ptplot.
    Note that you can download sources and binaries for pxgraph, an extension to xgraph from http://ptolemy.eecs.berkeley.edu/other/pxgraph.htm
    1.7 What is the relationship between ptplot and Ptolemy II?
    Ptolemy II is a set of Java packages supporting heterogeneous, concurrent modeling and design. One of the packages that is shipped with Ptolemy II is Ptplot. For more information about Ptolemy II, see http://ptolemy.eecs.berkeley.edu/ptolemyII/. We usually do a release of Ptolemy II once a year. As part of the Ptolemy II release process, we usually do a standalone Ptplot release.
    1.8 Does Ptplot contain encryption?
    PtPlot does not include encryption. (We sometimes get asked this question by overseas PtPlot users)
    1.9 Does Ptplot have a US Export Control Classification Number?
    We do not have a Export Control Classification Number (ECCN).

    2. Installation questions

    2.1 How do I download Ptplot?
    http://ptolemy.eecs.berkeley.edu/java/ptplot.htm has links to the tar and zip files.
    2.2 What platforms does Ptplot run under?
    Ptplot was developed under JDK 1.4, which requires the Java Plug-in.

    Java 1.4 or later is required, the PlotFrame class uses

    import javax.print.attribute.PrintRequestAttributeSet;
    import javax.print.attribute.HashPrintRequestAttributeSet;
    
    These are part of the java.print package which does not exist in Java 1.3.1 or 1.3.2.

    Ptplot will also work under Java 1.4.0, but note that Java 1.4.0 has a bug that prevents some applets from working well if Ptplot is installed in a directory that has spaces in the path name, see the troubleshooting page for details.

    If you don't want to require your users to install the JDK plug-in, then try using Ptplot 3.1 or earlier.

    A small standalone example that uses Ptplot 3.1 can be found at http://ptolemy.eecs.berkeley.edu/java/ptplot/standalone/

    Note that Ptplot 3.1 and later wll not compile with JDK1.1, the Plot class uses the clear() method from the Vector class, which is not present in JDK1.1.

    Ptplot 2.0 supported JDK1.1, and Ptplot 1.3 and earlier supported JDK1.0.2, you can find those releases in http://ptolemy.eecs.berkeley.edu/java/old.

    2.3 What do I need to Install Ptplot?
    To use Ptplot, you will need the Java Runtime Environment, (JRE) which can be downloaded from http://www.javasoft.com.

    See the Installing Ptplot page for more information

    You can also run Ptplot as an applet in your local browser by downloading the Java Plug-in.

    2.4 Troubleshooting
    The Ptplot Troubleshooting guide has a few hints.

    You might find useful information on the Ptplot homepage at http://ptolemy.eecs.berkeley.edu/java/ptplot.

    If you are really stumped, you can send mail to ptplot at ptolemy eecs berkeley edu. Your mail should include:

    1. What version of Ptplot you are running.
    2. What platform you are running under (Solaris, Windows etc.)
    3. The version of Java that you are running
    4. If the problem is with an applet, then include the type of browser and the version.
    5. Exactly how to reproduce the bug.
    2.5 Is there a bug list?
  • Most of the known bugs and limitations are listed in the javadoc Plot documentation
  • The Todo list is at the top of the Plot.java file.
  • Note that PlotLive works best under Windows and may not work at all under Solaris.
  • 2.6 What features might you some day implement?
    Below is a list of frequently requested features that we might some day implement. At this point, we have no plans to implement these features, but since the source code is available, anyone can go ahead and implement these features on their own
    Handling Dates
    It would be nice if Ptplot could properly display dates on the axes. It turns out that the code that labels the axes is fairly tricky to get right and have it look good.
    One way to handle dates is to convert a date such as 2003/03/20 to the integeter day of the year since January 1 and then use the XTicks facility to label the starts of the month:
    XTicks: Jan 0, Feb 31, Mar 59, Apr 90, May 120
    
    To handle time, once can convert to the number of minutes or seconds since midnight and adjust the ticks accordingly.
    Making the datapoints more interactive
    It would be nice if the user could mouse on the data points in the graph and various things would happen:
  • The values for the point would pop up as a tooltip
  • The user could jump to a URL
  • It would be nice if the points could have labels that are displayed in the graph.
    The way to implement these sorts of features would be to look at the zoom code and to add a point type that included a url field.
    Selecting data sets
    It would be nice if the user could select which datasets were displayed.

    3. How do I . . .

    3.1 How do I plot my own data?
    There are several ways to plot data using ptplot. You can read data from a file on the local filesystem, or from a file on the internet via a URL. You can sketch your own data and then save the file. Or you can create Java applications or applets that directly call methods of the Plot classes to create the plot.

    The preferred file format is called PlotML, and is described fully in the Plot chapter. It is a textual format in XML, the popular extensible markup language used widely on the internet. An older (and more compact) textual format is also supported. Binary data files are also supported, see 3.2 How do I plot binary data? All three formats are demonstrated in the demos.

    If you write Java code, the key method for adding data points is the addPoint() method of the Plot class. The Fourier Series demo uses this method.

    You can also plot data dynamically as shown in the live plot demo.

    3.2 How do I plot binary data?
    Ptplot can plot binary datafiles in an older file format originally created by Joe Buck for the X11 pxgraph program. For details on the format see the javadoc Pxgraph documentation for the PxgraphParser class.

    The Java program below shows how to generate a raw binary data file with two data points in it.

    cxh@tycho 25% cat BinaryData.java
    import java.io.*;
    
    class BinaryData {
        public static void main(String args[]) {
            try {
                FileOutputStream fileOutput = new FileOutputStream("binary.plt");
                DataOutputStream dataOutput = new DataOutputStream(fileOutput);
                // First pair
                dataOutput.writeFloat(1);
                dataOutput.writeFloat(1);
                // Second pair
                dataOutput.writeFloat(2);
                dataOutput.writeFloat(3);
                dataOutput.close();
                fileOutput.close();
            } catch (IOException e) {
            System.out.println("Failed to open a file: " + e);
            }
        }
    }
    cxh@tycho 26% javac BinaryData.java
    cxh@tycho 27% setenv CLASSPATH .
    cxh@tycho 28% java BinaryData
    cxh@tycho 29% od -c binary.plt
    0000000   ? 200  \0  \0   ? 200  \0  \0   @  \0  \0  \0   @   @  \0  \0
    0000020
    cxh@tycho 30% pxgraph -binary binary.plt
    
    
    3.3 How do I handle endian issues in binary data?
    Traditional C/C++ programs encode binary data in different formats on different platforms.
  • Big-endian - SPARCs and the network in general use this format.
  • Little-endian - Intel x86 chips use this format.
  • Problems can occur when you try to read a binary format file on a machine other than the machine it was created on. Java always reads binary data in big-endian format, so the pxgraph script and the pxgraphargs applet parameter take the following arguments:
  • -binary - use the endian format of the machine that the Java virtual machine is running on.
  • -bigendian - the file is in big-endian format, convert it if the Java virtual machine is running on a little-endian machine.
  • -littleendian - the file is in little-endian format, convert it if the Java virtual machine is running on a big-endian machine.
  • See the Endian Examples for example that use the above flags. The Java Programmer's FAQ has more information about endian issues.
    3.4 How do I print a plot from a Plot applet or application?
    The JDK1.4 plug-in makes printing applets easier. Most applets should have a print icon on the upper right corner that will bring up a printer dialog.

    In an applet, you can copy the plot to the clipboard in Encapsulated PostScript (EPS) format by typing Control-C. You can export the plot to standard out in EPS by typing an E.

    Note that printing is supported from standalone applications (ptplot, pxgraph, and histogram). These applications can also export encapsulated postscript files.

    To generate a GIF image, you might try first generating PostScript by printing to a file or exporting EPS, and then using pstogif, which is part of Ghostview, available at http://www.cs.wisc.edu/~ghost/. Below is an example:

    pxgraph -print -o /tmp/data.ps demo/data.plt
    pstogif /tmp/data.ps
    
    Under Windows, you can use Print Screen to capture a screen shot, the help system says:
    To copy the window or screen contents
  • To make a copy of only the active window, press ALT+PRINT SCREEN.
  • To copy the entire screen as it appears on your monitor, press PRINT SCREEN.
  • Note
    To paste the image into a document, click the Edit menu in the document window, and then click Paste.
    You can paste into Paint, which can be started using Start->Programs->Accessories->Paint From Paint, you can save a gif You can open the gif with Start->Programs->Accessories->Imaging and save a jpg.

    Under Windows, you may want to try using Snagit, which is a commercially available program. http://ptolemy.eecs.berkeley.edu/java/ptplot/exportPNG-0.0.1.patch.gz is a gzipped patch to Ptplot 5.2 by Bernard Guillot that "allows Easy Export to PNG. This in turn becomes an easy path to export to GIF and JPG.". Portions of the patch are under the GNU Lesser General Public License 2.1, see http://www.gnu.org/copyleft/lesser.html for details. This patch has _not_ been tested by the Ptplot pteam at UC Berkeley.

    To generate gifs, the servlet code at http://ptolemy.eecs.berkeley.edu/java/ptplot/ptolemy-plot-servlet.tar.gz might be of use. This is a gzipped tar file that contains sample code to use Ptplot as a servlet. The code was written by Alberto Gobbi, and has _not_ been tested by the Ptplot pteam at UC Berkeley.

    3.5 How do I plot two datafiles in an applet?
    In applications (ptplot, pxgraph, and histogram), this is easy: just specify the two files on the command line. In applets, only PxgraphApplet supports this. The pxgraphargs applet parameter can be used to pass more than one file to the plotter. The pxgraphargs parameter can also pass pxgraph command line arguments. For example, the HTML below would plot two datafiles at once. The title of the plot would be Two datafiles.
    <APPLET name="twofiles" CODE="ptolemy.plot.PlotApplet" Height=400 Width=400
        codebase="../../.."
        archive="ptolemy/plot/plotapplet.jar"
        alt="If you had a java-enabled browser, you would see an applet here."
    >
    <param name="pxgraphargs" value="-t 'Two datafiles' file1.plt file2.plt">
       <hr>If your browser recognized the applet tag,
        you would see an applet here.<hr>
    </APPLET>
    
    An alternative is to use ptplot to merge the two files into one plot, then save as a single file.
    3.6 How do I have two separate plots?
    See LogAxes.htm for an applet that has two separate plots side by side.

    See TwoPlotExample.java for a standalone application that has two separate plots side by side.

    3.7 How do I create a simple standalone Plot application?
    PlotApplication.java is a standalone application with a menu interface. It has derived classes PlotMLApplication, which adds the ability to read PlotML files, and EditablePlotMLApplication, which adds the ability to edit the data being plotted. EditablePlotMLApplication is started by the $PTII/bin/ptplot startup script.

    You can start up the standalone application by hand with:

    java -classpath plotapplication.jar ptolemy.plot.plotml.EditablePlotMLApplication demo/sinusoids.xml
    

    ptolemy/plot/demo/TwoPlotExample.java is a simple standalone Java application that uses the Plot class. The comment towards the top of the file contains instructions about how to compile it.

    3.8 Why is the HTML so complex for the applets?
    The demonstration applets that we ship use JavaScript so that the applets will work on the widest variety of platforms, browsers and versions of the Java Plug-in.

    However, if you are using a recent version of the Java Plug-in, then you can use the simpler <applet> . . . </applet> style.
    Note that this style will not work under Netscape 4.7x.

    $PTII/ptolemy/plot/demo/MarksSimple.htm uses this simpler style.

    For more information about how to write applets that use the Java Plug-in, see http://java.sun.com/products/plugin/versions.html

    3.9 How do I create a simple standalone Plot applet?
    The applet codebase parameter controls where and applet may look for data files. See http://java.sun.com/docs/books/tutorial/applet/appletsonly/data.html for details.

    For example, to move the ../demo/MarksSimple.html file out of the Ptplot tree, follow these steps below:

    1. Copy the necessary files to the directory where your web server serves files:
      mkdir ~/public_html/ptplot
      cd ptplot5.2/ptolemy/plot
      cp plotmlapplet.jar ~/public_html/ptplot
      cp demo/MarksSimple.htm ~/public_html/ptplot
      cp demo/plotmlSample.txt ~/public_html/ptplot
      cp plotml/PlotML_1.dtd ~/public_html/ptplot
      
      1) Edit ~/public_html/ptplot/Marks.htm and change
      the codebase from "../../.." to "."
      and change the archive from ptolemy/plot/plotmlapplet.jar to plotmlapplet.jar
      <APPLET
       code = "ptolemy.plot.plotml.PlotMLApplet"
       codebase = "."
       archive = "plotmlapplet.jar"
       width = "600"
       height = "400"
       >
      <PARAM NAME = "background" VALUE = "#ffffff" >
      <PARAM NAME = "dataurl" VALUE = "plotmlSample.txt" >
        No Java Plug-in support for applet, see
       <a href="http://java.sun.com/products/plugin/"><code>http://java.sun.com/products/plugin/</code></a>
      </APPLET>
      
    2. Edit ~/public_html/ptplot/plotmlSample.txt and change the dtd from ../plotml/plotml.dtd to PlotML_1.dtd:
      2c2
      < <!DOCTYPE plot SYSTEM "PlotML_1.dtd">
      ---
      > <!DOCTYPE plot SYSTEM "../plotml/plotml.dtd">
      
    If you have problems, then be sure to enable the Java plug-in console and look for messages there.
    3.10 How do I set the ranges for a plot that is using log axes?
    The implementation of Log Axes is complex and some what difficult to use.
    The grid labels represent powers of 10. Note that if a logarithmic scale is used, then the values must be positive. Non-positive values will be silently dropped. Note further that when using logarithmic axes that the log of input data is taken as the data is added to the plot. This means that
    XLog: on
    or
    YLog: on
    should appear before any data. Also, the value of the XTicks, YTicks or XRange or YRange directives should be in log units. So,
    XTicks: 1K 3
    will display the string
    1K
    at the 1000 mark.
  • 3.11 Does Ptplot support 3-D plots? Ptplot does not support 3D charts. Extending Ptplot to do 3D plots would be tricky, and we have no plans to include 3D plots at this time.

    You could write code that would do a projection of 3D data onto a 2D space, but Ptplot has no z axis, so that would not be that useful.

    You could also modify Ptplot so that it would do a waterfall style plot, where each successive z value was offsite slightly Figure 5.4 at http://ptolemy.eecs.berkeley.edu/ptolemyclassic/almagest/docs/user/html/sdf.doc2.html#5.2.2 Sink stars has an icon of a waterfall plot, which is described as:

    Waterfall Plot a series of traces in the style of a waterfall plot. This is a type of three-dimensional plot used to show the evolution of signals or spectra. Optionally, each plot can be made opaque, so that lines that would appear behind the plot are eliminated.
  • Last Updated: $Date: 2010-10-20 11:25:01 -0700 (Wed, 20 Oct 2010) $