Class Graph

java.lang.Object
org.bzdev.graphs.Graph

public class Graph extends Object
Class for representing and creating graphs. Java's graphics use two coordinate systems:
  • an integer-valued coordinate system in which each point corresponds to a pixel for the device rendering graphics. This coordinate system is referred to as "device space" in Java documentation.
  • a real-valued coordinate system in units of points, where there are 72 points per inch. This coordinate system is referred to as "user space" in Java documentation.
For some common cases (e.g., a BufferedImage) a distance of length 1.0 in user space corresponds to a distance of 1 in device space, but for hardware-based devices (e.g., printers), this may not be the case. Typical computer monitors have 72 pixels per inch, so for this case device space and user space are identical. Both spaces use a convention where increasing x coordinates point right and increasing y coordinates point down.

The Graph class introduces a third space called graph coordinate space in which the coordinates are in the units being plotted, and in which increasing values are oriented as specified by the user (generally 'left' for the x direction 'up' for the 'y' direction). (the normal convention when drawing graphs) rather than down. The use of graph coordinate space simplifies drawing graphs as scaling and translations are handled automatically.

A graph is assumed to be drawn on a rectangle with a height and width specified in user space.


                            width       
        _|____________________________________________|_
         |                                            |
         |                                            | upper
         |        __________________________          |_y-offset
         |        |                         |         |
  height |        |                         |         |
         |        |                         |         |
         |        |                         |         |
         |        |                         |         |
         |        |                         |         |
         |        |_________________________|         |_
         |                                            | lower
        _|____________________________________________|_y-offset
         |  lower |                          | upper  |
          x-offset                            x-offset
     
 
A portion of this rectangle—the inner rectangle in the figure above—is area in which objects in the graph are usually drawn. The axes, however, will typically be outside this inner rectangle. Various offsets determine how much space is left for such axes, labels, and other decorations surrounding the graph. The method setOffsets sets these offsets. The height, width,and four offsets are specified in user space. The method setRanges provides the upper and lower x and y coordinates in graph coordinate space of the inner rectangle. When a graph is created, the constructor will call set all the offsets to 0 and then call setRanges(0.0, getWidth(), 0.0, getHeight()), thus causing user space and graph coordinate space to have the same scale, with the point (0,0) at the lower left corner of the figure and with x and y increasing to reach other points within the graph.

The method createGraphics returns a graphics context for user space and createGraphicsGCS returns a graphics context for graph coordinate space. While one can use the graphics context returned by createGraphicsGCS directly for drawing, strokes would also be scaled, making it difficult to draw lines and other shapes with a desired outline width in user space, the usual case when drawing curves on a graph. To handle the usual case conveniently, the Graph class provides several drawing methods that allow fonts and strokes to be specified in user space, with shapes and some other objects that can be drawn specified in graph-coordinate space. The other objects are instances of Drawable and Graphic described below The drawing methods are

  • drawImage. There are several variants, some of which allow the image to be rotated, scaled, or flipped. Arguments common to all are a graphics context, an image, and the x and y coordinate in graph-coordinate space. Optional arguments (those that are present appear in the order shown below) include the following:
    • refpoint or refpointName - A Point2D in the image's coordinate system that represents a point on the image that will be placed at the location denoted by the common x and y arguments. The image's coordinate system uses real-valued values in which 1.0 corresponds to the size of a pixel, with increase x values moving right and increasing y values moving down from the upper-left corner of the image (i.e, the coordinates are standard Java user-space coordinates). A reference point name is a symbolic name representing common cases (corners, the image's center, and the centers of image's edges). The image's coordinate system is independent of the scaleX and scaleY parameters defined below.
    • angle - the angle by which the image should be rotated, measured counterclockwise from a right-pointing horizontal axis. The default is 0.0. For graph coordinate space, "right pointing" refers to the direction of increasing X and counterclockwise refers to a rotation towards the direction for increasing Y.
    • scaleX - the scaling factor in the X direction. The default is 1.0. Larger scaling factors make the image larger.
    • scaleY - the scaling factor in the Y direction. The default is 1.0. Larger scaling factors make the image larger.
    • flipX - true if the image should be reflected about the x axis. The default is false. A reflected image will overlay the original image, with the reflection applied before any other transformation. If an image is reflected, the reference point refers to the reflected image.
    • flipY - true if the image should be reflected about the y axis. The default is false. A reflected image will overlay the original image, with the reflection applied before any other transformation. If an image is reflected, the reference point refers to the reflected image.
    • imageInGCS - true if, before any scaling, the width and height of a pixel corresponds to 1 unit length in graph coordinate space; false if the width and height of a pixel corresponds to 1 unit length in user space. The default is true.
    The default for imageInGCS of true is the most convenient value for the anim2d package, where images would tend to represent objects in an animation and should adjust size as a view of an animation is zoomed. By contrast, a value of false is appropriate when the image represents some sort of fixed-sized icon or label, but those are often positioned at fixed locations on the fame, in which case a Graphics2D for the frame would be used directly.
  • drawString. There are two variants. One uses font parameters associated with the graph and the other uses a set of font parameters configured independently. The class FontParms specifies the font color, the font to use, the position relative to the string of a reference point whose position on the graph is specified when the string is drawn, and the angle at which the string should be printed.
  • draw. This method takes a graphics context as its first argument and either a Graph.Drawable or a Shape as its second argument. The outline of a shape will be drawn. For a Drawable, its toShape method will be called and the resulting shape will be drawn.
  • fill. This method takes a graphics context as its first argument and either a Graph.Drawable or a Shape as its second argument. The shape will be filled. For a Drawable, its toShape method will be called and the resulting shape will be filled.
  • add. This method takes as its argument an instance of the class Graph.Graphic and adds that object to the graph by calling the object's addTo method.

The interface Graph.Drawable indicates that an object has an associated shape that can be drawn or filled by a graph. The interface Graph.Graphic indicates that an object has a graphical representation that can appear on a graph. This representation is typically more complex than ones associated with a Shape or a Drawable. The interfaces Graph.UserDrawable and Graph.UserGraphic are similar, but represent objects that should be drawn in user space and then placed at specified locations in graph coordinate space. Graph.UserDrawable and Graph.UserGraphic are useful for drawing symbols that should have a fixed size on an image. Symbols to represent data points are a good example of cases where these classes are useful.

Graph axis are described by the class Graph.Axis, with tick marks along the axis specified by the class Graph.TickSpec. Finally, for some uses of the graph class (e.g., its use in animations provided by the org.bzdev.anim2d package), it is useful to be able to draw lines with a width specified in graph coordinate space. In these cases, the method createGraphicsGCS can be used to obtain a graphics context where stroke widths are defined in graph coordinate space units. Typically one will first create a graph. One can specify the image dimensions explicitly or initialize the graph with an instance of OutputStreamGraphics. For example,


   Graph graph = new Graph(800, 600);
 
or

   OutputStream os = new FileOutputStream("output.png");
   OutputStreamGraphics =
      OutputStreamGraphics.newInstance(800, 600, "png");
   Graph graph = new Graph(osg);
 
The documentation for PrinterGraphics shows how to set up a graph so that the image will go directly to a printer.

The next step is to set the offsets and ranges. The method setOffsets(int,int) or setOffsets(int,int,int,int) will reserve space around the edges of a graph for labels and axes (specifically, the tick marks). Values of 50 are reasonable, with a value of 75 or 100 useful if there is a label for an axis. If the offsets are too small, a label or tick mark might not be visible. One then sets the ranges for the graph (the range in the X direction and the range in the Y direction) by calling setRanges(double,double,double,double). For example, if the X values on a graph vary from 0.0 to 1000.0 and the Y values vary from 0.0 to 100.0, the following statements could be used to configure the graph:


     graph.setOffsets(75, 50, 75, 50);
     graph.setRanges(0.0, 1000.0, 0.0, 100.0);
 
An alternate method setRanges(double,double,double,double,double,double) is useful when the Graph class is used to create a 'canvas' on which to draw objects.

Once the graph is configured, one can draw objects on it. The first step it to create a graphics context. Aside from setting the drawing color, font size, strokes, etc., this graphics context will not be used directly in most cases as the graphics context has user-space coordinates. Instead, the graphics context will be passed to one of the graph's "draw" methods. For example,


     Graphics2D g2d = graph.createGraphics();
     double x1 = 10.0;
     double y1 = 1.0;
     double x2 = 900.0;
     double y1 = 90.0;
     Line2D line = new Line2D.Double(x1, y1, x2, y2);
     g2d.setColor(Color.BLUE);
     g2d.setStroke(new BasicStroke(1.5F));
     graph.draw(g2d, line);
 
will draw a blue line whose end points in graph coordinate space are (10.0, 1.0) and (900.0, 90.0) and whose width is 1.5 pts (in user-space units). If Graphics2D.setPaint(Paint) is used, The paint is specified in user space. The method createGraphicsGCS() will create a graphics context that uses graph coordinate space and the method Graphics2D.setPaint(Paint) will specify a paint using graph coordinate space, but in this case the graphics context must be used directly to draw or fill shapes: the draw and fill methods provided by Graph specify the shape to be drawn in graph coordinate space using a graphics context that draws in user apsce.

To draw a symbol on the graph, one can create an instance of the class Graph.SymbolFactory, configure it, and then create a symbol. A 'draw' method will then draw the symbol. For example,


     Graph.SymbolFactory sf = new Graph.SymbolFactory();
     sf.setColor(Color.BLACK);
     Graph.Symbol circ = sf.newSymbol("SolidCircle");
     graph.draw(circ, 200.0, 30.0);
     graph.drawEY(circ, 400.0, 40.0, 25.0);
 
will draw a symbol (a solid, black circle) at the point (200.0, 30.0) in graph coordinate space. It will also draw the same symbol at (400.0, 40.0) in graph coordinate space, but with error bars in the Y direction.

The easiest way to add axes to a graph is to use one of the subclasses of AxisBuilder to create an axis. One can then call a "draw" method to add the axis to the graph. For example


     AxisBuilder.Linear ab =
        new AxisBuilder.Linear(graph, 0.0, 0.0, 1000.0, true, "X Axis");
     ab.setMaximumExponent(3);
     ab.addTickSpec(0, 0, true, "%4.0f");
     ab.addTickSpec(2, 1, false, null);
     graph.draw(ab.createAxis());
 
will draw an X axis. How the axis is configured is described in the documentation for each of subclasses of AxisBuilder.

To draw or output an image, call a 'write' method:


     graph.write();
 
when the graph's constructor used an instance of OutputStreamGraphics or other classes that implement the OSGraphicsOps interface. Otherwise use a 'write' method with multiple arguments:

     graph.write("png", "output.png");
 
See Also:
  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static class 
    Class to specify a graph axis.
    static enum 
    Vertical text positioning for strings.
    static interface 
    Interface for objects that have a corresponding shape.
    static class 
    Class specifying a graph's font parameters.
    static interface 
    Interface for objects that can be drawn on a graph.
    static enum 
    Enumeration specifying the image type for a graph.
    static enum 
    Enumeration specifying text justification for strings.
    static class 
    Class to provide a logarithmic axis.
    static class 
    Class for symbols used in plotting.
    static class 
    Factory class for creating graph symbols.
    static class 
    Class specifying graph tick marks along an axis.
    static interface 
    Interface for user-space objects that have a corresponding shape.
    static interface 
    Interface for user-space objects that can be drawn on a graph.
  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final int
    The default height for a graph.
    static final int
    The default width for a graph.
  • Constructor Summary

    Constructors
    Constructor
    Description
    Constructor.
    Graph(int width, int height)
    Constructor specifying an image width and height.
    Graph(int width, int height, boolean requestAlpha, ISWriterOps isw)
    Constructor specifying an image-sequence-writer object.
    Graph(int width, int height, int type, IndexColorModel cm)
    Constructor specifying an image width, height, type, and color model.
    Graph(int width, int height, Graph.ImageType type)
    Constructor specifying an image width, height, and type.
    Constructor specifying an image.
    Constructor specifying an output-stream-graphics object.
    Graph(Graph graph, boolean shared)
    Constructor based on another instance of Graph.
  • Method Summary

    Modifier and Type
    Method
    Description
    void
    add(Graphics2D g, Graph.UserGraphic graphic, double x, double y)
    Add a UserGraphic at specified coordinates.
    void
    Add a Graphic to a graph.
    void
    add(Graph.Graphic g, double x, double y)
    Add a graphic to a graph at a specified location.
    void
    add(Graph.UserGraphic g, double x, double y)
    Add a graphic defined in user space to a graph.
    boundingBox(boolean gcs)
    Get a bounding box for the visible area of a graph.
    void
    Clear an image.
    void
    clear(Paint paint)
    Clear an image using a specified background
    void
    Clip a graphics context based on a shape The shape will be converted to user space before the clip method is called on the graphics context.
    coordTransform(double x, double y)
    Convert x-y coordinates as doubles from graph coordinate space to user space.
    coordTransform(float x, float y)
    Convert x-y coordinates as floats from graph coordinate space to user space.
    Convert a point in graph coordinate space to user space.
    coordTransform(Point2D srcPoint, Point2D destPoint)
    Convert a point in graph coordinate space to user space and store it.
    Returns a shape in an image's or graphic context's user space given a shape in graph coordinate space.
    Returns a shape in an image's or graphic context's user space given a shape in graph coordinate space, preferentially making the shape a {java.awt.Rectangle} when the shape is already an instance of {java.awt.geom.RectangularShape}.
    Create a graphics context.
    Create a Graphics context using graph coordinate space.
    void
    Draw a shape.
    void
    Draw a Drawable.
    void
    draw(Graphics2D g, Graph.UserDrawable drawable, double x, double y)
    Draw a UserDrawable.
    void
    Draw an axis.
    void
    draw(Graph.Symbol symbol, double x, double y)
    Draw a symbol.
    void
    drawEX(Graph.Symbol symbol, double x, double y, double error)
    Draw a symbol with symmetric error bars in the X direction.
    void
    drawEX(Graph.Symbol symbol, double x, double y, double elow, double ehigh)
    Draw a symbol with asymmetric error bars in the X direction.
    void
    drawEXY(Graph.Symbol symbol, double x, double y, double errorX, double errorY)
    Draw a symbol with symmetric error bars in the X and Y direction.
    void
    drawEXY(Graph.Symbol symbol, double x, double y, double elowX, double ehighX, double elowY, double ehighY)
    Draw a symbol with asymmetric error bars in the X and Y directions.
    void
    drawEY(Graph.Symbol symbol, double x, double y, double error)
    Draw a symbol with symmetric error bars in the Y direction.
    void
    drawEY(Graph.Symbol symbol, double x, double y, double elow, double ehigh)
    Draw a symbol with asymmetric error bars in the Y direction.
    void
    drawImage(Graphics2D g2d, Image img, double x, double y)
    Draw an image.
    void
    drawImage(Graphics2D g2d, Image img, double x, double y, boolean imageInGCS)
    Draw an image with each pixel representing a unit in either user space or graph coordinate space.
    void
    drawImage(Graphics2D g2d, Image img, double x, double y, Point2D refpoint)
    Draw an image given a reference point.
    void
    drawImage(Graphics2D g2d, Image img, double x, double y, Point2D refpoint, boolean imageInGCS)
    Draw an image given a reference point with each pixel representing a unit in either user space or graph coordinate space.
    void
    drawImage(Graphics2D g2d, Image img, double x, double y, Point2D refpoint, double angle)
    Draw an image given a reference point and angle.
    void
    drawImage(Graphics2D g2d, Image img, double x, double y, Point2D refpoint, double angle, boolean imageInGCS)
    Draw an image given a reference point and angle with each pixel representing a unit in either user space or graph coordinate space.
    void
    drawImage(Graphics2D g2d, Image img, double x, double y, Point2D refpoint, double angle, double scaleX, double scaleY)
    Draw an image given a reference point, angle and scale factors.
    void
    drawImage(Graphics2D g2d, Image img, double x, double y, Point2D refpoint, double angle, double scaleX, double scaleY, boolean imageInGCS)
    Draw an image given a reference point, angle and scale factors, with a pixel's height and width before scaling being a unit length in either user space or graph coordinate space.
    void
    drawImage(Graphics2D g2d, Image img, double x, double y, Point2D refpoint, double angle, double scaleX, double scaleY, boolean flipX, boolean flipY)
    Draw an image given a reference point, angle, scale factors, reflection flags.
    void
    drawImage(Graphics2D g2d, Image img, double x, double y, Point2D refpoint, double angle, double scaleX, double scaleY, boolean flipX, boolean flipY, boolean imageInGCS)
    Draw an image given a reference point, angle, scale factors, and reflection flags, with a pixel's height and width before scaling being a unit length in either user space or graph coordinate space.
    void
    drawImage(Graphics2D g2d, Image img, double x, double y, RefPointName refpointName)
    Draw an image given a named reference point.
    void
    drawImage(Graphics2D g2d, Image img, double x, double y, RefPointName refpointName, boolean imageInGCS)
    Draw an image given a named reference point with each pixel representing a unit in either user space or graph coordinate space.
    void
    drawImage(Graphics2D g2d, Image img, double x, double y, RefPointName refpointName, double angle)
    Draw an image given a named reference point and an angle.
    void
    drawImage(Graphics2D g2d, Image img, double x, double y, RefPointName refpointName, double angle, boolean imageInGCS)
    Draw an image given a named reference point and an angle with each pixel representing a unit in either user space or graph coordinate space.
    void
    drawImage(Graphics2D g2d, Image img, double x, double y, RefPointName refpointName, double angle, double scaleX, double scaleY)
    Draw an image given a named reference point, an angle, and scale factors.
    void
    drawImage(Graphics2D g2d, Image img, double x, double y, RefPointName refpointName, double angle, double scaleX, double scaleY, boolean imageInGCS)
    Draw an image given a named reference point, an angle, and scale factors, with a pixel's height and width before scaling being a unit length in either user space or graph coordinate space.
    void
    drawImage(Graphics2D g2d, Image img, double x, double y, RefPointName refpointName, double angle, double scaleX, double scaleY, boolean flipX, boolean flipY)
    Draw an image given a named reference point, an angle, scale factors, and reflection flags.
    void
    drawImage(Graphics2D g2d, Image img, double x, double y, RefPointName refpointName, double angle, double scaleX, double scaleY, boolean flipX, boolean flipY, boolean imageInGCS)
    Draw an image given a named reference point, an angle, scale factors, reflection flags, with each pixel representing a unit in either user space or graph coordinate space.
    void
    drawString(String string, double x, double y)
    Draw a string using the graph's font parameters.
    void
    drawString(String string, double x, double y, Graph.FontParms fp)
    Draw a string.
    void
    Fill a shape.
    void
    Fill a Drawable.
    void
    fill(Graphics2D g, Graph.UserDrawable drawable, double x, double y)
    Fill a UserDrawable.
    void
    Flush the graphics to an instance of OSGraphicsOps, if configured by a constructor.
    Get the color to use when clearing a graph.
    boolean
    Get the mode that determines if clearing a graph should add the background color to each pixel in a graph or replace the pixels.
    Get the color model associated with the graph's image.
    Get a coordinate transformation to go from graph coordinate space to user space.
    static Color
    Get the default color to use when clearing a graph.
    Get the font for this graph.
    double
    Get the font angle for this graph.
    Get the font vertical alignment for this graph.
    Get the font color for this graph.
    Get the font justification for this graph.
    Get the font parameters for this graph.
    getFontToFit(String string, Point2D p1, Point2D p2)
    Get a font with the same font family and style as the default font, sized based on two points.
    getFontToFit(String string, Point2D p1, Point2D p2, String fontName, int fontStyle)
    Get a font with a given font family and style, sized based on two points.
    double
    Get the height of a graph.
    int
    Get the height of a graph as an integer.
    Get the image used to display a graph.
    Get the image type.
    Get the output-stream graphics or OSGraphicsOps used to display a graph.
    int
    Get the parity for this graph.
    double
    getUserSpaceAngle(double gcsAngle, boolean ccw)
    Get the angle in user space corresponding to an angle in graph coordinate space.
    double
    Get the width of a graph.
    int
    Get the width of a graph as an integer.
    double
    Get the x coordinate for the lower end of the graph's range.
    double
    getXLower(double xgcs, double xf, double scaleFactorX)
    Get the x coordinate for the lower end of the graph's range given specific parameters.
    static double
    getXLower(double width, double xgcs, double xf, double scaleFactorX, int xLowerOffset, int xUpperOffset)
    Get the x coordinate for the lower end of the graph's range given specific parameters and graph dimensions.
    int
    Get the lower X offset for this graph.
    double
    Get the scale factor in the x direction.
    double
    Get the x coordinate for the upper end of the graph's range.
    double
    getXUpper(double xgcs, double xf, double scaleFactorX)
    Get the x coordinate for the upper end of the graph's range given specific parameters.
    static double
    getXUpper(double width, double xgcs, double xf, double scaleFactorX, int xLowerOffset, int xUpperOffset)
    Get the x coordinate for the upper end of the graph's range given specific parameters and graph dimensions.
    int
    Get the upper X offset for this graph.
    double
    Get the y coordinate for the lower end of the graph's range.
    double
    getYLower(double ygcs, double yf, double scaleFactorY)
    Get the y coordinate for the lower end of the graph's range given specific parameters.
    static double
    getYLower(double height, double ygcs, double yf, double scaleFactorY, int yLowerOffset, int yUpperOffset)
    Get the y coordinate for the lower end of the graph's range given specific parameters and graph dimensions.
    int
    Get the lower Y offset for this graph.
    double
    Get the scale factor in the y direction.
    double
    Get the y coordinate for the upper end of the graph's range.
    double
    getYUpper(double ygcs, double yf, double scaleFactorY)
    Get the y coordinate for the upper end of the graph's range given specific parameters.
    static double
    getYUpper(double height, double ygcs, double yf, double scaleFactorY, int yLowerOffset, int yUpperOffset)
    Get the y coordinate for the upper end of the graph's range given specific parameters and graph dimensions.
    int
    Get the upper Y offset for this graph.
    imageBoundingBox(Image img, double x, double y, Point2D refpoint, double angle, double scaleX, double scaleY, boolean imageInGCS)
    Get the bounding box in graph coordinate space for an image given a reference point, angle, and scale factors, with a pixel's height and width before scaling being a unit length in either user space or graph coordinate space.
    imageBoundingBox(Image img, double x, double y, RefPointName refpointName, double angle, double scaleX, double scaleY, boolean imageInGCS)
    Get the bounding box in graph coordinate space for an image given a reference point name, angle, and scale factors, with a pixel's height and width before scaling being a unit length in either user space or graph coordinate space.
    invCoordTransform(double x, double y)
    Convert the x-y coordinates, as doubles, in user space to a point in graph coordinate space.
    invCoordTransform(float x, float y)
    Convert the x-y coordinates, as floats, in user space to a point in graph coordinate space.
    Convert a point in user space to a point in graph coordinate space.
    invCoordTransform(Point2D srcPoint, Point2D destPoint)
    Convert a point in user space to a point in graph coordinate space and store it.
    Returns a shape in graph coordinate space given a shape in user space.
    boolean
    maybeVisible(Shape s, boolean gcs)
    Determine if a shape might be inside the portion of graph coordinate space that can be displayed.
    void
    Set the color to use when clearing a graph.
    void
    setClearByFillMode(boolean mode)
    Set whether or clearing a graph should add the background color to each pixel in a graph or replace the pixels.
    static void
    Set the default color to use when clearing a graph.
    void
    Set the font to use for this graph.
    void
    setFontAngle(double angle)
    Set the font angle for this graph.
    void
    Set the font vertical alignment for this graph.
    void
    Set the font color for this graph.
    void
    Set the font justification for this graph.
    void
    Set the font parameters for this graph.
    void
    setOffsets(int x, int y)
    Set the graph offsets symmetrically.
    void
    setOffsets(int xL, int xU, int yL, int yU)
    Set the graph offsets.
    void
    Set this graph's OutputStreamGraphics field.
    void
    setRanges(double xLower, double xUpper, double yLower, double yUpper)
    Set the x and y ranges.
    void
    setRanges(double xgcs, double ygcs, double xf, double yf, double scaleFactorX, double scaleFactorY)
    Set ranges based on scale factors.
    void
    setRotation(double theta, double xAnchor, double yAnchor)
    Specify how to rotate a graph about an anchor point expressed in graph coordinate space.
    void
    Write graphics to an instance of OSGraphicsOps, if configured by a constructor.
    void
    write(String type, File file)
    Write the graph to a file.
    void
    Write the graph to an outputStream.
    void
    write(String type, String name)
    Write the graph to a file given a file name.
    void
    Write the graph to a file provided by a file accessor.
    boolean
    Determine direction of positive X axis in graph coordinate space.
    boolean
    Determine direction of positive Y axis in graph coordinate space.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
  • Field Details

    • DEFAULT_WIDTH

      public static final int DEFAULT_WIDTH
      The default width for a graph.
      See Also:
    • DEFAULT_HEIGHT

      public static final int DEFAULT_HEIGHT
      The default height for a graph.
      See Also:
  • Constructor Details

    • Graph

      public Graph()
      Constructor. The image will be cleared.
    • Graph

      public Graph(Graph graph, boolean shared) throws IllegalArgumentException
      Constructor based on another instance of Graph. When shared, the two graphs share the same image or other object on which a graph is to be drawn. The original graph's size, image type, offsets, ranges and background color are copied. When not shared, a new image will be created with the same image type and dimensions 1as the original image. The image will be cleared (so it will be filled with the background color) if it is not shared.

      A shared graph is particularly useful for graphs in which the left and right vertical axes have different scales (for example a graph showing two functions of temperature, where one function's range is a pressure and the other function's range is a volume).

      Parameters:
      graph - a graph on which to base this instance
      shared - True if the graph is shared; false otherwise
      Throws:
      IllegalArgumentException - the graph argument uses output stream graphics or an image sequence writer but the graph being constructed is not shared
      See Also:
    • Graph

      public Graph(int width, int height)
      Constructor specifying an image width and height. The image will be cleared.
      Parameters:
      width - the image width
      height - the image height
      See Also:
    • Graph

      public Graph(int width, int height, Graph.ImageType type)
      Constructor specifying an image width, height, and type. The image will be cleared.
      Parameters:
      width - the image width
      height - the image height
      type - the image type (an enum constant corresponding to integer constants defined by BufferedImage that must not be null)
      See Also:
    • Graph

      public Graph(BufferedImage image)
      Constructor specifying an image. The image will not be cleared. The image may not be null.
      Parameters:
      image - the image used to display the graph
    • Graph

      public Graph(OSGraphicsOps osg)
      Constructor specifying an output-stream-graphics object. The graphics will not be cleared.
      Parameters:
      osg - the instance of OSGraphicsOps to be used to create the graph
    • Graph

      public Graph(int width, int height, boolean requestAlpha, ISWriterOps isw)
      Constructor specifying an image-sequence-writer object. The graphics will not be cleared.
      Parameters:
      width - the width of the drawing area
      height - the height of the drawing area
      requestAlpha - true if the drawing area should be configured with an alpha channel; false otherwise
      isw - the instance of ISWriterOps used to create the graph
    • Graph

      public Graph(int width, int height, int type, IndexColorModel cm)
      Constructor specifying an image width, height, type, and color model. A color model should be provided only when the image type is BufferedImage.TYPE_BYTE_BINARY or BufferedImage.TYPE_BYTE_INDEXED. The image will be cleared.
      Parameters:
      width - the image width
      height - the image height
      type - the image type (constants from BufferedImage
      cm - the color model
  • Method Details

    • getImage

      public BufferedImage getImage()
      Get the image used to display a graph.
      Returns:
      the image for this graph; null if there is none
    • getOutputStreamGraphics

      public OSGraphicsOps getOutputStreamGraphics()
      Get the output-stream graphics or OSGraphicsOps used to display a graph.
      Returns:
      the output-stream graphics instance; null if there is none
    • getColorModel

      public ColorModel getColorModel()
      Get the color model associated with the graph's image.
      Returns:
      the color model
    • getHeightAsInt

      public int getHeightAsInt()
      Get the height of a graph as an integer.
      Returns:
      the height
    • getWidthAsInt

      public int getWidthAsInt()
      Get the width of a graph as an integer.
      Returns:
      the width
    • getHeight

      public double getHeight()
      Get the height of a graph.
      Returns:
      the height in user-space units
    • getWidth

      public double getWidth()
      Get the width of a graph.
      Returns:
      the width in user-space units
    • getImageType

      public Graph.ImageType getImageType()
      Get the image type.
      Returns:
      the image type; null there is no image.
    • setOSGraphics

      public void setOSGraphics(OSGraphicsOps osg)
      Set this graph's OutputStreamGraphics field. This method is used only when a graph is configured to use an image sequence writer. The argument should have been created with one of that image sequence writer's nextOutputStreamGraphics methods. If not, some methods such as getImageType() may not work as expected (the image type returned by getImageType() is not changed by this method).

      Offsets, ranges, and graph rotations are preserved, as are fonts, font color, the background color, etc., but previously created graphics contexts are no longer valid, and previous drawing operations are not copied to the new output stream graphics.

      This method is used by Animation2D. It should rarely be used directly as it is intended for use by animation classes or other classes that manage sequences of images.

      Parameters:
      osg - the output stream graphics to use
      Throws:
      IllegalStateException - this graph was not constructed with an output stream graphics object.
      IllegalArgumentException - the width and height for the argument does not match the ones required for this graph
      See Also:
    • setDefaultBackgroundColor

      public static void setDefaultBackgroundColor(Color color)
      Set the default color to use when clearing a graph. Unless set by the user, the default is black with an alpha value of 0 making 'black' transparent. This is the color that will be used initially when a graph is created. Existing graphs will not have their background color modified.
      Parameters:
      color - the color
    • getDefaultBackgroundColor

      public static Color getDefaultBackgroundColor()
      Get the default color to use when clearing a graph.
      Returns:
      the default color
    • setBackgroundColor

      public void setBackgroundColor(Color color)
      Set the color to use when clearing a graph.
      Parameters:
      color - the background color
    • getBackgroundColor

      public Color getBackgroundColor()
      Get the color to use when clearing a graph.
      Returns:
      the color to use when clearing a graph
    • setClearByFillMode

      public void setClearByFillMode(boolean mode)
      Set whether or clearing a graph should add the background color to each pixel in a graph or replace the pixels. For an alpha of 255, the appearance does not depend on the mode. For other values of alpha, when the mode is true, the background color, which is transparent or translucent, will be added to each pixel; when the mode is false, each pixel will be replaced with one having the background color.
      Parameters:
      mode - true for adding; false for replacing
    • getClearByFillMode

      public boolean getClearByFillMode()
      Get the mode that determines if clearing a graph should add the background color to each pixel in a graph or replace the pixels.
      Returns:
      true for adding; false for replacing
    • clear

      public void clear()
      Clear an image. The effect depends on the background color and whether clear-by-fill mode is active. In clear-by-fill mode, the graph's image is filled with the background color. If the background color has a value of alpha less than 255, the previous image will be covered by a transparent or partially transparent pixels. If not in clear-by-fill mode, the existing image will be replaced with the background color (this is the default mode when a graph is created). Clear-by-fill mode is useful for some types of animation, where an indication of the previous positions of objects in the animation is useful, for instance by creating a 'blurred motion' effect.
      See Also:
    • clear

      public void clear(Paint paint)
      Clear an image using a specified background
      Parameters:
      paint - the background
    • drawImage

      public void drawImage(Graphics2D g2d, Image img, double x, double y) throws IOException
      Draw an image. The image's reference point is at the image's upper left corner. An image's reference point is the point in the image's coordinate system that will be placed at the point (x, y) on the graph. Each pixel's width and height are a single unit in graph coordinate space.

      There are of number of methods named drawImage. Details for the arguments of these methods, include default values for optional ones, can be found in the overview for drawImage.

      A pixel in the image will take up one unit in graph coordinate space. The upper edge of the image (from left to right in the image's coordinate system) will lie along a line passing through (x, y) in graph coordinate space and parallel to the positive X axis. Note that if the positive X axis in graph coordinate space points right to left in user space, the image will appear to have been rotated 180 degrees relative to the positive X axis in user space.

      Parameters:
      g2d - a graphics context on which to draw
      img - the image to draw
      x - the x coordinate in graph coordinate space for the image's reference point
      y - the coordinate in graph coordinate space for the image's reference point
      Throws:
      IOException - the image could not be loaded
    • drawImage

      public void drawImage(Graphics2D g2d, Image img, double x, double y, boolean imageInGCS) throws IOException
      Draw an image with each pixel representing a unit in either user space or graph coordinate space. The image's reference point is at the image's upper left corner. An image's reference point is the point in the image's coordinate system that will be placed at the point (x, y) on the graph.

      There are of number of methods named drawImage. Details for the arguments of these methods, include default values for optional ones, can be found in the overview for drawImage.

      When the argument imageInCGS is true, a pixel in the image will take up 1 unit in graph coordinate space. The upper edge of the image (from left to right in the image's coordinate system) will lie along a line passing through (x, y) in graph coordinate space and parallel to the positive X axis. Note that if the positive X axis in graph coordinate space points right to left in user space, the image will appear to have been rotated 180 degrees relative to the positive X axis in user space.

      When the argument imageInCGS is false, a pixel in the image will take up one unit in user space. The lower and upper edges of the image will be parallel to the X axis in user space.

      Parameters:
      g2d - a graphics context on which to draw
      img - the image to draw
      x - the x coordinate in graph coordinate space for the image's reference point
      y - the coordinate in graph coordinate space for the image's reference point
      imageInGCS - true if the image pixel size is a unit in graph coordinate space; false if the image pixel size is a unit in user space
      Throws:
      IOException - the image could not be loaded
    • drawImage

      public void drawImage(Graphics2D g2d, Image img, double x, double y, RefPointName refpointName) throws IOException
      Draw an image given a named reference point. An image's reference point is the point in the image's coordinate system that will be placed at the point (x, y) on the graph. Each pixel's width and height are a single unit in graph coordinate space.

      There are of number of methods named drawImage. Details for the arguments of these methods, include default values for optional ones, can be found in the overview for drawImage.

      A pixel in the image will take up one unit in graph coordinate space. The upper edge of the image (from left to right in the image's coordinate system) will be parallel to a line passing through (x, y) in graph coordinate space and parallel to the positive X axis. The image will be placed so that its reference point is at (x, y). Note that if the positive X axis in graph coordinate space points right to left in user space, the image will appear to have been rotated 180 degrees relative to the positive X axis in user space.

      Parameters:
      g2d - a graphics context on which to draw
      img - the image to draw
      x - the image's x coordinate in graph coordinate space
      y - the image's y coordinate in graph coordinate space
      refpointName - the name of the reference point of the image
      Throws:
      IOException - the image could not be loaded
    • drawImage

      public void drawImage(Graphics2D g2d, Image img, double x, double y, RefPointName refpointName, boolean imageInGCS) throws IOException
      Draw an image given a named reference point with each pixel representing a unit in either user space or graph coordinate space. An image's reference point is the point in the image's coordinate system that will be placed at the point (x, y) on the graph.

      There are of number of methods named drawImage. Details for the arguments of these methods, include default values for optional ones, can be found in the overview for drawImage.

      When the argument imageInCGS is true, a pixel in the image will take up one unit in graph coordinate space. The upper edge of the image (from left to right in the image's coordinate system) will be parallel to a line passing through (x, y) in graph coordinate space and parallel to the positive X axis. The image will be placed so that its reference point is at (x, y). Note that if the positive X axis in graph coordinate space points right to left in user space, the image will appear to have been rotated 180 degrees relative to the positive X axis in user space.

      When the argument imageInCGS is false, a pixel in the image will take up one unit in user space. The lower and upper edges of the image will be parallel to the X axis in user space.

      Parameters:
      g2d - a graphics context on which to draw
      img - the image to draw
      x - the image's x coordinate in graph coordinate space
      y - the image's y coordinate in graph coordinate space
      refpointName - the name of the reference point of the image
      imageInGCS - true if the image pixel size is a unit in graph coordinate space; false if the image pixel size is a unit in user space
      Throws:
      IOException - the image could not be loaded
    • drawImage

      public void drawImage(Graphics2D g2d, Image img, double x, double y, RefPointName refpointName, double angle) throws IOException
      Draw an image given a named reference point and an angle. An image's reference point is the point in the image's coordinate system that will be placed at the point (x, y) on the graph. Each pixel's width and height are a single unit in graph coordinate space.

      There are of number of methods named drawImage. Details for the arguments of these methods, include default values for optional ones, can be found in the overview for drawImage.

      A pixel in the image will take up one unit in graph coordinate space. The lower edge of the image (from left to right in the image's coordinate system) will be parallel to a line in user space whose direction is set by its angle from the positive X direction when rotated towards the positive Y direction, both in graph coordinate space. The image will be placed so that the reference point is at the coordinates (x, y) in graph coordinate space. The mapping from graph-coordinate-space angles to user-space angles is not linear if the scale factors in the X and Y directions differ.

      Parameters:
      g2d - a graphics context on which to draw
      img - the image to draw
      x - the image's x coordinate in graph coordinate space
      y - the image's y coordinate in graph coordinate space
      refpointName - the name of the reference point of the image
      angle - an angle, in radians and in graph coordinate space, by which the image will be rotated in the counter clockwise direction from its normal orientation about the reference point
      Throws:
      IOException - the image could not be loaded
    • drawImage

      public void drawImage(Graphics2D g2d, Image img, double x, double y, RefPointName refpointName, double angle, boolean imageInGCS) throws IOException
      Draw an image given a named reference point and an angle with each pixel representing a unit in either user space or graph coordinate space. An image's reference point is the point in the image's coordinate system that will be placed at the point (x, y) on the graph.

      There are of number of methods named drawImage. Details for the arguments of these methods, include default values for optional ones, can be found in the overview for drawImage.

      When the argument imageInCGS is true, a pixel in the image will take up 1 unit in graph coordinate space. The lower edge of the image (from left to right in the image's coordinate system) will be parallel to a line in user space whose direction is set by its angle from the positive X direction when rotated towards the positive Y direction, both in graph coordinate space. The image will be placed so that the reference point is at the coordinates (x, y) in graph coordinate space. The mapping from graph-coordinate-space angles to user-space angles is not linear if the scale factors in the X and Y directions differ.

      When the argument imageInCGS is false, a pixel in the image will take up one unit in user space. The lower and upper edges of the image will be parallel to a line obtained by rotating counter clockwise by the specified angle from the positive X axis in user space.

      Parameters:
      g2d - a graphics context on which to draw
      img - the image to draw
      x - the image's x coordinate in graph coordinate space
      y - the image's y coordinate in graph coordinate space
      refpointName - the name of the reference point of the image
      angle - an angle, in radians and in user space, by which the image will be rotated in the counter clockwise direction, from its normal orientation, about the reference point
      imageInGCS - true if the image pixel size is a unit in graph coordinate space; false if the image pixel size is a unit in user space
      Throws:
      IOException - the image could not be loaded
    • drawImage

      public void drawImage(Graphics2D g2d, Image img, double x, double y, RefPointName refpointName, double angle, double scaleX, double scaleY) throws IOException
      Draw an image given a named reference point, an angle, and scale factors. An image's reference point is the point in the image's coordinate system that will be placed at the point (x, y) on the graph. Each pixel's width and height are a single unit in graph coordinate space.

      There are of number of methods named drawImage. Details for the arguments of these methods, include default values for optional ones, can be found in the overview for drawImage.

      A pixel in the scaled image will take up one unit in graph coordinate space. The lower edge of the image (from left to right in the image's coordinate system) will be parallel to a line in user space whose direction is set by its angle from the positive X direction when rotated towards the positive Y direction, both in graph coordinate space. The image will be placed so that the reference point is at the coordinates (x, y) in graph coordinate space. The mapping from graph-coordinate-space angles to user-space angles is not linear if the scale factors in the X and Y directions differ.

      Parameters:
      g2d - a graphics context on which to draw
      img - the image to draw
      x - the image's x coordinate in graph coordinate space
      y - the image's y coordinate in graph coordinate space
      refpointName - the name of the reference point of the image
      angle - an angle, in radians and in graph coordinate space, by which the image will be rotated in the counter clockwise direction from its normal orientation and about the reference point
      scaleX - the scaling factor, in the X direction of the image, by which to change the size of the image
      scaleY - the scaling factor, in the Y direction of the image, by which to change the size of the image
      Throws:
      IOException - the image could not be loaded
    • drawImage

      public void drawImage(Graphics2D g2d, Image img, double x, double y, RefPointName refpointName, double angle, double scaleX, double scaleY, boolean imageInGCS) throws IOException
      Draw an image given a named reference point, an angle, and scale factors, with a pixel's height and width before scaling being a unit length in either user space or graph coordinate space. An image's reference point is the point in the image's coordinate system that will be placed at the point (x, y) on the graph.

      There are of number of methods named drawImage. Details for the arguments of these methods, include default values for optional ones, can be found in the overview for drawImage.

      When the argument imageInCGS is true, a pixel in the scaled image will take up one unit in graph coordinate space. The lower edge of the image (from left to right in the image's coordinate system) will be parallel to a line in user space whose direction is set by its angle from the positive X direction when rotated towards the positive Y direction, both in graph coordinate space. The image will be placed so that the reference point is at the coordinates (x, y) in graph coordinate space. The mapping from graph-coordinate-space angles to user-space angles is not linear if the scale factors in the X and Y directions differ.

      When the argument imageInCGS is false, a pixel in the scaled image will take up one unit in user space. The lower and upper edges of the image will be parallel to a line obtained by rotating counter clockwise by the specified angle from the positive X axis in user space.

      Parameters:
      g2d - a graphics context on which to draw
      img - the image to draw
      x - the image's x coordinate in graph coordinate space
      y - the image's y coordinate in graph coordinate space
      refpointName - the name of the reference point of the image
      angle - an angle, in radians and in user space, by which the image will be rotated in the counter clockwise direction, from its normal orientation, about the reference point
      scaleX - the scaling factor, in the X direction of the image, by which to change the size of the image
      scaleY - the scaling factor, in the Y direction of the image, by which to change the size of the image
      imageInGCS - true if a pixel's height and width before scaling represents a unit length in graph coordinate space; false if it represents a unit length in user space
      Throws:
      IOException - the image could not be loaded
    • drawImage

      public void drawImage(Graphics2D g2d, Image img, double x, double y, RefPointName refpointName, double angle, double scaleX, double scaleY, boolean flipX, boolean flipY) throws IOException
      Draw an image given a named reference point, an angle, scale factors, and reflection flags. An image's reference point is the point in the image's coordinate system that will be placed at the point (x, y) on the graph. When an image is flipped in either the X or Y direction (or both), it is flipped about the center of the image, and the reference point remains at the same location relative to the image's upper left corner. That is, the flipped image in effect overlays the original one and replaces it. The angle is the angle in user space, but reversed from the usual clockwise direction used in most Java graphics operations (to be consistent with the common case for graph coordinate space where increasing X moves right and increasing Y moves up). Each pixel's width and height are a single unit in graph coordinate space.

      There are of number of methods named drawImage. Details for the arguments of these methods, include default values for optional ones, can be found in the overview for drawImage.

      A pixel in the scaled image will take up one unit in graph coordinate space. The lower edge of the image (from left to right in the image's coordinate system) will be parallel to a line in user space whose direction is set by its angle from the positive X direction when rotated towards the positive Y direction, both in graph coordinate space. The image will be placed so that the reference point is at the coordinates (x, y) in graph coordinate space. The mapping from graph-coordinate-space angles to user-space angles is not linear if the scale factors in the X and Y directions differ.

      Parameters:
      g2d - a graphics context on which to draw
      img - the image to draw
      x - the image's x coordinate in graph coordinate space
      y - the image's y coordinate in graph coordinate space
      refpointName - the name of the reference point of the image
      angle - an angle, in radians and in user space, by which the image will be rotated in the counter clockwise direction, from its normal orientation, about the reference point
      scaleX - the scaling factor, in the X direction of the image, by which to change the size of the image
      scaleY - the scaling factor, in the Y direction of the image, by which to change the size of the image
      flipX - true of the image should be reflected about the Y axis in the image's coordinate system
      flipY - true of the image should be reflected about the X axis in the image's coordinate system.
      Throws:
      IOException - the image could not be loaded
    • drawImage

      public void drawImage(Graphics2D g2d, Image img, double x, double y, RefPointName refpointName, double angle, double scaleX, double scaleY, boolean flipX, boolean flipY, boolean imageInGCS) throws IOException
      Draw an image given a named reference point, an angle, scale factors, reflection flags, with each pixel representing a unit in either user space or graph coordinate space. An image's reference point is the point in the image's coordinate system that will be placed at the point (x, y) on the graph. When an image is flipped in either the X or Y direction (or both), it is flipped about the center of the image, and the reference point remains at the same location relative to the image's upper left corner. That is, the flipped image in effect overlays the original one and replaces it. The angle is the angle in user space, but reversed from the usual clockwise direction used in most Java graphics operations (to be consistent with the common case for graph coordinate space where increasing X moves right and increasing Y moves up).

      There are of number of methods named drawImage. Details for the arguments of these methods, include default values for optional ones, can be found in the overview for drawImage.

      When the argument imageInCGS is true, a pixel in the scaled image will take up one unit in graph coordinate space. The lower edge of the image (from left to right in the image's coordinate system) will be parallel to a line in user space whose direction is set by its angle from the positive X direction when rotated towards the positive Y direction, both in graph coordinate space. The image will be placed so that the reference point is at the coordinates (x, y) in graph coordinate space. The mapping from graph-coordinate-space angles to user-space angles is not linear if the scale factors in the X and Y directions differ.

      When the argument imageInCGS is false, a pixel in the scaled image will take up one unit in user space. The lower and upper edges of the image will be parallel to the X axis in user space.

      Parameters:
      g2d - a graphics context on which to draw
      img - the image to draw
      x - the image's x coordinate in graph coordinate space
      y - the image's y coordinate in graph coordinate space
      refpointName - the name of the reference point of the image
      angle - an angle, in radians and in user space, by which the image will be rotated in the counter clockwise direction, from its normal orientation, about the reference point
      scaleX - the scaling factor, in the X direction of the image, by which to change the size of the image
      scaleY - the scaling factor, in the Y direction of the image, by which to change the size of the image
      flipX - true of the image should be reflected about the Y axis in the image's coordinate system
      flipY - true of the image should be reflected about the X axis in the image's coordinate system.
      imageInGCS - true if a pixel's height and width before scaling represents a unit length in graph coordinate space; false if it represents a unit length in user space
      Throws:
      IOException - the image could not be loaded
    • imageBoundingBox

      public Rectangle2D imageBoundingBox(Image img, double x, double y, RefPointName refpointName, double angle, double scaleX, double scaleY, boolean imageInGCS) throws IOException
      Get the bounding box in graph coordinate space for an image given a reference point name, angle, and scale factors, with a pixel's height and width before scaling being a unit length in either user space or graph coordinate space.

      An image's reference point is the point in the image's coordinate system that will be placed at the point (x, y) on the graph. For this method, the reference point is determined by name, not by its coordinates.

      For images that are never translated or rotated, this method can be used to compute a bounding box in graph coordinate space. One can use that bounding box to determine if an attempt to draw the image will be certain to fail. The bounding box is not necessarily the smallest one possible.

      When the argument imageInCGS is true, a pixel in the scaled image will take up one unit in graph coordinate space. The lower edge of the image (from left to right in the image's coordinate system) will be parallel to a line in user space whose direction is set by its angle from the positive X direction when rotated towards the positive Y direction, both in graph coordinate space. The image will be placed so that the reference point is at the coordinates (x, y) in graph coordinate space. The mapping from graph-coordinate-space angles to user-space angles is not linear if the scale factors in the X and Y directions differ.

      When the argument imageInCGS is false, a pixel in the scaled image will take up one unit in user space. The lower and upper edges of the image will be parallel to the X axis in user space.

      Parameters:
      img - the image to draw
      x - the image's x coordinate in graph coordinate space
      y - the image's y coordinate in graph coordinate space
      refpointName - the name of the reference point of the image
      angle - an angle, in radians and in user space, by which the image will be rotated in the counter clockwise direction, from its normal orientation, about the reference point
      scaleX - the scaling factor, in the X direction of the image, by which to change the size of the image
      scaleY - the scaling factor, in the Y direction of the image, by which to change the size of the image
      imageInGCS - true if a pixel's height and width before scaling represents a unit length in graph coordinate space; false if it represents a unit length in user space
      Returns:
      a bounding box in graph coordinate space
      Throws:
      IOException - the image could not be loaded
    • drawImage

      public void drawImage(Graphics2D g2d, Image img, double x, double y, Point2D refpoint) throws IOException
      Draw an image given a reference point. Each pixel's width and height are a single unit in graph coordinate space.

      There are of number of methods named drawImage. Details for the arguments of these methods, include default values for optional ones, can be found in the overview for drawImage.

      A pixel in the image will take up one unit in graph coordinate space. The upper edge of the image (from left to right in the image's coordinate system) will be parallel to a line passing through (x, y) in graph coordinate space and parallel to the positive X axis. The image will be placed so that its reference point is at (x, y). Note that if the positive X axis in graph coordinate space points right to left in user space, the image will appear to have been rotated 180 degrees relative to the positive X axis in user space.

      Parameters:
      g2d - a graphics context on which to draw
      img - the image to draw
      x - the image's x coordinate in graph coordinate space
      y - the image's y coordinate in graph coordinate space
      refpoint - a reference point in the image's coordinate system that indicates the point on the image that will be placed at the point (x, y) in graph coordinate space
      Throws:
      IOException - the image could not be loaded
    • drawImage

      public void drawImage(Graphics2D g2d, Image img, double x, double y, Point2D refpoint, boolean imageInGCS) throws IOException
      Draw an image given a reference point with each pixel representing a unit in either user space or graph coordinate space.

      There are of number of methods named drawImage. Details for the arguments of these methods, include default values for optional ones, can be found in the overview for drawImage.

      When the argument imageInCGS is true, a pixel in the image will take up one unit in graph coordinate space. The upper edge of the image (from left to right in the image's coordinate system) will be parallel to a line passing through (x, y) in graph coordinate space and parallel to the positive X axis. The image will be placed so that its reference point is at (x, y). Note that if the positive X axis in graph coordinate space points right to left in user space, the image will appear to have been rotated 180 degrees relative to the positive X axis in user space.

      When the argument imageInCGS is false, a pixel in the scaled image will take up one unit in user space. The lower and upper edges of the image will be parallel to the X axis in user space.

      Parameters:
      g2d - a graphics context on which to draw
      img - the image to draw
      x - the image's x coordinate in graph coordinate space
      y - the image's y coordinate in graph coordinate space
      refpoint - a reference point in the image's coordinate system that indicates the point on the image that will be placed at the point (x, y) in graph coordinate space
      imageInGCS - true if the image pixel size is a unit in graph coordinate space; false if the image pixel size is a unit in user space
      Throws:
      IOException - the image could not be loaded
    • drawImage

      public void drawImage(Graphics2D g2d, Image img, double x, double y, Point2D refpoint, double angle) throws IOException
      Draw an image given a reference point and angle. Each pixel's width and height are a single unit in graph coordinate space.

      There are of number of methods named drawImage. Details for the arguments of these methods, include default values for optional ones, can be found in the overview for drawImage.

      A pixel in the image will take up one unit in graph coordinate space. The lower edge of the image (from left to right in the image's coordinate system) will be parallel to a line in user space whose direction is set by its angle from the positive X direction when rotated towards the positive Y direction, both in graph coordinate space. The image will be placed so that the reference point is at the coordinates (x, y) in graph coordinate space. The mapping from graph-coordinate-space angles to user-space angles is not linear if the scale factors in the X and Y directions differ.

      Parameters:
      g2d - a graphics context on which to draw
      img - the image to draw
      x - the image's x coordinate in graph coordinate space
      y - the image's y coordinate in graph coordinate space
      refpoint - a reference point in the image's coordinate system that indicates the point on the image that will be placed at the point (x, y) in graph coordinate space
      angle - an angle, in radians and in user space, by which the image will be rotated in the counter clockwise direction, from its normal orientation, about the reference point
      Throws:
      IOException - the image could not be loaded
    • drawImage

      public void drawImage(Graphics2D g2d, Image img, double x, double y, Point2D refpoint, double angle, boolean imageInGCS) throws IOException
      Draw an image given a reference point and angle with each pixel representing a unit in either user space or graph coordinate space.

      There are of number of methods named drawImage. Details for the arguments of these methods, include default values for optional ones, can be found in the overview for drawImage.

      When the argument imageInCGS is true, a pixel in the image will take up one unit in graph coordinate space. The lower edge of the image (from left to right in the image's coordinate system) will be parallel to a line in user space whose direction is set by its angle from the positive X direction when rotated towards the positive Y direction, both in graph coordinate space. The image will be placed so that the reference point is at the coordinates (x, y) in graph coordinate space. The mapping from graph-coordinate-space angles to user-space angles is not linear if the scale factors in the X and Y directions differ.

      When the argument imageInCGS is false, a pixel in the image will take up one unit in user space. The lower and upper edges of the image will be parallel to a line obtained by rotating counter clockwise by the specified angle from the positive X axis in user space.

      Parameters:
      g2d - a graphics context on which to draw
      img - the image to draw
      x - the image's x coordinate in graph coordinate space
      y - the image's y coordinate in graph coordinate space
      refpoint - a reference point in the image's coordinate system that indicates the point on the image that will be placed at the point (x, y) in graph coordinate space
      angle - an angle, in radians and in user space, by which the image will be rotated in the counter clockwise direction, from its normal orientation, about the reference point
      imageInGCS - true if the image pixel size is a unit in graph coordinate space; false if the image pixel size is a unit in user space
      Throws:
      IOException - the image could not be loaded
    • drawImage

      public void drawImage(Graphics2D g2d, Image img, double x, double y, Point2D refpoint, double angle, double scaleX, double scaleY) throws IOException
      Draw an image given a reference point, angle and scale factors. Each pixel's width and height are a single unit in graph coordinate space.

      There are of number of methods named drawImage. Details for the arguments of these methods, include default values for optional ones, can be found in the overview for drawImage.

      A pixel in the scaled image will take up one unit in graph coordinate space. The lower edge of the image (from left to right in the image's coordinate system) will be parallel to a line in user space whose direction is set by its angle from the positive X direction when rotated towards the positive Y direction, both in graph coordinate space. The image will be placed so that the reference point is at the coordinates (x, y) in graph coordinate space. The mapping from graph-coordinate-space angles to user-space angles is not linear if the scale factors in the X and Y directions differ.

      Parameters:
      g2d - a graphics context on which to draw
      img - the image to draw
      x - the image's x coordinate in graph coordinate space
      y - the image's y coordinate in graph coordinate space
      refpoint - a reference point in the image's coordinate system that indicates the point on the image that will be placed at the point (x, y) in graph coordinate space
      angle - an angle, in radians and in user space, by which the image will be rotated in the counter clockwise direction, from its normal orientation, about the reference point
      scaleX - the scaling factor, in the X direction of the image, by which to change the size of the image
      scaleY - the scaling factor, in the Y direction of the image, by which to change the size of the image
      Throws:
      IOException - the image could not be loaded
    • drawImage

      public void drawImage(Graphics2D g2d, Image img, double x, double y, Point2D refpoint, double angle, double scaleX, double scaleY, boolean imageInGCS) throws IOException
      Draw an image given a reference point, angle and scale factors, with a pixel's height and width before scaling being a unit length in either user space or graph coordinate space.

      There are of number of methods named drawImage. Details for the arguments of these methods, include default values for optional ones, can be found in the overview for drawImage.

      When the argument imageInCGS is true, a pixel in the scaled image will take up one unit in graph coordinate space. The lower edge of the image (from left to right in the image's coordinate system) will be parallel to a line in user space whose direction is set by its angle from the positive X direction when rotated towards the positive Y direction, both in graph coordinate space. The image will be placed so that the reference point is at the coordinates (x, y) in graph coordinate space. The mapping from graph-coordinate-space angles to user-space angles is not linear if the scale factors in the X and Y directions differ.

      When the argument imageInCGS is false, a pixel in the scaled image will take up one unit in user space. The lower and upper edges of the image will be parallel to a line obtained by rotating counter clockwise by the specified angle from the positive X axis in user space.

      Parameters:
      g2d - a graphics context on which to draw
      img - the image to draw
      x - the image's x coordinate in graph coordinate space
      y - the image's y coordinate in graph coordinate space
      refpoint - a reference point in the image's coordinate system that indicates the point on the image that will be placed at the point (x, y) in graph coordinate space
      angle - an angle, in radians and in user space, by which the image will be rotated in the counter clockwise direction, from its normal orientation, about the reference point
      scaleX - the scaling factor, in the X direction of the image, by which to change the size of the image
      scaleY - the scaling factor, in the Y direction of the image, by which to change the size of the image
      imageInGCS - true if a pixel's height and width before scaling represents a unit length in graph coordinate space; false if it represents a unit length in user space
      Throws:
      IOException - the image could not be loaded
    • drawImage

      public void drawImage(Graphics2D g2d, Image img, double x, double y, Point2D refpoint, double angle, double scaleX, double scaleY, boolean flipX, boolean flipY) throws IOException
      Draw an image given a reference point, angle, scale factors, reflection flags. When an image is flipped in either the X or Y direction (or both), it is flipped about the center of the image, and the reference point remains at the same location relative to the image's upper left corner. That is, the flipped image in effect overlays the original one and replaces it. The angle is the angle in user space, but reversed from the usual clockwise direction used in most Java graphics operations (to be consistent with the common case for graph coordinate space where increasing X moves right and increasing Y moves up). Each pixel's width and height are a single unit in graph coordinate space.

      There are of number of methods named drawImage. Details for the arguments of these methods, include default values for optional ones, can be found in the overview for drawImage.

      A pixel in the scaled image will take up one unit in graph coordinate space. The lower edge of the image (from left to right in the image's coordinate system) will be parallel to a line in user space whose direction is set by its angle from the positive X direction when rotated towards the positive Y direction, both in graph coordinate space. The image will be placed so that the reference point is at the coordinates (x, y) in graph coordinate space. The mapping from graph-coordinate-space angles to user-space angles is not linear if the scale factors in the X and Y directions differ.

      Parameters:
      g2d - a graphics context on which to draw
      img - the image to draw
      x - the image's x coordinate in graph coordinate space
      y - the image's y coordinate in graph coordinate space
      refpoint - a reference point in the image's coordinate system that indicates the point on the image that will be placed at the point (x, y) in graph coordinate space
      angle - an angle, in radians and in user space, by which the image will be rotated in the counter clockwise direction, from its normal orientation, about the reference point
      scaleX - the scaling factor, in the X direction of the image, by which to change the size of the image
      scaleY - the scaling factor, in the Y direction of the image, by which to change the size of the image
      flipX - true of the image should be reflected about the Y axis in the image's coordinate system
      flipY - true of the image should be reflected about the X axis in the image's coordinate system.
      Throws:
      IOException - the image could not be loaded
    • drawImage

      public void drawImage(Graphics2D g2d, Image img, double x, double y, Point2D refpoint, double angle, double scaleX, double scaleY, boolean flipX, boolean flipY, boolean imageInGCS) throws IOException
      Draw an image given a reference point, angle, scale factors, and reflection flags, with a pixel's height and width before scaling being a unit length in either user space or graph coordinate space. When an image is flipped in either the X or Y direction (or both), it is flipped about the center of the image, and the reference point remains at the same location relative to the image's upper left corner. That is, the flipped image in effect overlays the original one and replaces it. The angle is the angle in user space, but reversed from the usual clockwise direction used in most Java graphics operations (to be consistent with the common case for graph coordinate space where increasing X moves right and increasing Y moves up).

      There are of number of methods named drawImage. Details for the arguments of these methods, include default values for optional ones, can be found in the overview for drawImage.

      When the argument imageInCGS is true, a pixel in the scaled image will take up one unit in graph coordinate space. The lower edge of the image (from left to right in the image's coordinate system) will be parallel to a line in user space whose direction is set by its angle from the positive X direction when rotated towards the positive Y direction, both in graph coordinate space. The image will be placed so that the reference point is at the coordinates (x, y) in graph coordinate space. The mapping from graph-coordinate-space angles to user-space angles is not linear if the scale factors in the X and Y directions differ.

      When the argument imageInCGS is false, a pixel in the scaled image will take up one unit in user space. The lower and upper edges of the image will be parallel to a line obtained by rotating counter clockwise by the specified angle from the positive X axis in user space.

      Parameters:
      g2d - a graphics context on which to draw
      img - the image to draw
      x - the image's x coordinate in graph coordinate space
      y - the image's y coordinate in graph coordinate space
      refpoint - a reference point in the image's coordinate system that indicates the point on the image that will be placed at the point (x, y) in graph coordinate space
      angle - an angle, in radians and in user space, by which the image will be rotated in the counter clockwise direction, from its normal orientation, about the reference point
      scaleX - the scaling factor, in the X direction of the image, by which to change the size of the image
      scaleY - the scaling factor, in the Y direction of the image, by which to change the size of the image
      flipX - true of the image should be reflected about the Y axis in the image's coordinate system
      flipY - true of the image should be reflected about the X axis in the image's coordinate system.
      imageInGCS - true if a pixel's height and width before scaling represents a unit length in graph coordinate space; false if it represents a unit length in user space
      Throws:
      IOException - the image could not be loaded
    • imageBoundingBox

      public Rectangle2D imageBoundingBox(Image img, double x, double y, Point2D refpoint, double angle, double scaleX, double scaleY, boolean imageInGCS) throws IOException
      Get the bounding box in graph coordinate space for an image given a reference point, angle, and scale factors, with a pixel's height and width before scaling being a unit length in either user space or graph coordinate space.

      For images that are never translated or rotated, this method can be used to compute a bounding box in graph coordinate space. One can use that bounding box to determine if an attempt to draw the image will be certain to fail. The bounding box is not necessarily the smallest one possible.

      The method getUserSpaceAngle(double,boolean) can be used to translate an angle in graph coordinate space into the appropriate angle to use in user space, allowing for differences in scale factors between the X and Y directions and any graph rotation that might have been configured.

      Parameters:
      img - the image
      x - the image's x coordinate in graph coordinate space
      y - the image's y coordinate in graph coordinate space
      refpoint - a reference point in the image's coordinate system that indicates the point on the image that will be placed at the point (x, y) in graph coordinate space
      angle - an angle, in radians and in user space, by which the image will be rotated in the counter clockwise direction, from its normal orientation, about the reference point
      scaleX - the scaling factor, in the X direction of the image, by which to change the size of the image
      scaleY - the scaling factor, in the Y direction of the image, by which to change the size of the image
      imageInGCS - true if a pixel's height and width before scaling represents a unit length in graph coordinate space; false if it represents a unit length in user space
      Returns:
      a bounding box in graph coordinate space
      Throws:
      IOException - the image could not be loaded
    • setFontParms

      public void setFontParms(Graph.FontParms parms)
      Set the font parameters for this graph.
      Parameters:
      parms - a FontParams instance whose parameters should be copied; null to restore the default
    • getFontParms

      public Graph.FontParms getFontParms()
      Get the font parameters for this graph. This method returns a copy of the current font parameters for this graph.
      Returns:
      the font parameters for this graph.
    • setFont

      public void setFont(Font f)
      Set the font to use for this graph.
      Parameters:
      f - the font to use
    • getFont

      public Font getFont()
      Get the font for this graph.
      Returns:
      the font
    • setFontColor

      public void setFontColor(Color c)
      Set the font color for this graph.
      Parameters:
      c - the color; null if the default color should be used
    • getFontColor

      public Color getFontColor()
      Get the font color for this graph.
      Returns:
      the font color
    • setFontJustification

      public void setFontJustification(Graph.Just j)
      Set the font justification for this graph.
      Parameters:
      j - the font justification
    • getFontJustification

      public Graph.Just getFontJustification()
      Get the font justification for this graph.
      Returns:
      the justification
    • setFontBaseline

      public void setFontBaseline(Graph.BLineP blp)
      Set the font vertical alignment for this graph.
      Parameters:
      blp - the vertical alignment
    • getFontBaseline

      public Graph.BLineP getFontBaseline()
      Get the font vertical alignment for this graph.
      Returns:
      the alignment
    • setFontAngle

      public void setFontAngle(double angle)
      Set the font angle for this graph.
      Parameters:
      angle - the angle in degrees
    • getFontAngle

      public double getFontAngle()
      Get the font angle for this graph.
      Returns:
      the angle in degrees
    • getFontToFit

      public Font getFontToFit(String string, Point2D p1, Point2D p2)
      Get a font with the same font family and style as the default font, sized based on two points. The font size will be as large as possible with the constraint that the first argument, string, will have a length no larger than the distance between p1 and p2 measured in user space.
      Parameters:
      string - the string
      p1 - the first point in graph coordinate space
      p2 - the second point in graph coordinate space
      Returns:
      the font
    • getFontToFit

      public Font getFontToFit(String string, Point2D p1, Point2D p2, String fontName, int fontStyle)
      Get a font with a given font family and style, sized based on two points. The font size will be as large as possible with the constraint that the first argument, string, will have a length no larger than the distance between p1 and p2 in user space. The size returned is based on the assumption that the string will be drawn so that its baseline is parallel to a line from p1 to p2: the length of a string for a given font varies slightly depending on the string's orientation.
      Parameters:
      string - the string
      p1 - the first point in graph coordinate space
      p2 - the second point in graph coordinate space
      fontName - the name of a font face or font family
      fontStyle - the style of the font (a logical 'or' of Font.PLAIN, Font.BOLD, and/or Font.ITALIC)
      Returns:
      the font
      See Also:
    • drawString

      public void drawString(String string, double x, double y)
      Draw a string using the graph's font parameters.
      Parameters:
      string - the string to draw
      x - the x position in graph coordinates
      y - the y position in graph coordinates
    • drawString

      public void drawString(String string, double x, double y, Graph.FontParms fp)
      Draw a string.
      Parameters:
      string - the string to draw
      x - the x position in graph coordinates
      y - the y position in graph coordinates
      fp - the font parameters to use
    • createGraphics

      public Graphics2D createGraphics()
      Create a graphics context.
      Returns:
      a new graphics context
    • createGraphicsGCS

      public Graphics2D createGraphicsGCS()
      Create a Graphics context using graph coordinate space. This is useful when one wishes to draw using a stroke whose width is defined in graph coordinate space. A graphics context returned by this method should be used directly, with all operations using units in graph coordinate space, including the width of strokes. This is useful for instances of Graph used by the org.bzdev.anim2d package.
      Returns:
      a graphics context using graph coordinate space
    • add

      public void add(Graph.Graphic g)
      Add a Graphic to a graph. Adding refers to a sequence of graphic operations needed to insert a complex object into a graph - something that might require multiple calls to draw or fill methods. The graphic will have its origin at (0.0, 0.0) in graph coordinate space.
      Parameters:
      g - the graphic to add to this graph
    • add

      public void add(Graph.Graphic g, double x, double y)
      Add a graphic to a graph at a specified location. Adding refers to a sequence of graphic operations needed to insert a complex object into a graph - something that might require multiple calls to draw or fill methods. Graphic g's reference point at (0.0, 0.0) in graph coordinate space will be moved to (x, y) in graph coordinate space and everything drawn will be translated by the same amount as well.
      Parameters:
      g - the graphic to add to this graph
      x - the x coordinate in graph-coordinate space at which the object should be placed
      y - the y coordinate in graph-coordinate space at which the object should be placed
    • add

      public void add(Graph.UserGraphic g, double x, double y)
      Add a graphic defined in user space to a graph. Adding refers to a sequence of graphic operations needed to insert a complex object into a graph - something that might require multiple calls to draw or fill methods. The object is assumed to have a reference point at location (0.0, 0.0) in user space.
      Parameters:
      g - the graphic to add to this graph
      x - the x coordinate in graph-coordinate space at which the object should be placed
      y - the y coordinate in graph-coordinate space at which the object should be placed
    • add

      public void add(Graphics2D g, Graph.UserGraphic graphic, double x, double y)
      Add a UserGraphic at specified coordinates. The UserGraphic is specified in user space with a reference point at (0.0, 0.0) in user space. If the graphics context's affine transformation differs from the affine transform of a graphics context returned by createGraphics(), that additional transformation will be applied before a translation to the user space coordinates corresponding to (x, y) is applied. This allows the graphics context to provide its own transformation (e.g., for scaling or a rotation).
      Parameters:
      g - a graphics context that was obtained by calling the graph's createGraphics() method
      graphic - the UserGraphic to draw
      x - the x coordinate in graph-coordinate space at which the object's reference point should be placed
      y - the y coordinate in graph-coordinate space at which the object's reference point should be placed
    • draw

      public void draw(Graphics2D g, Graph.Drawable drawable)
      Draw a Drawable. The drawable must be specified in graph coordinate space. That is, its Graph.Drawable.toShape() method must return a shape whose control points or dimensions are specified in graph coordinate space units.
      Parameters:
      g - a graphics context that was obtained by calling the graph's createGraphics() method
      drawable - the Drawable to draw
    • fill

      public void fill(Graphics2D g, Graph.Drawable drawable)
      Fill a Drawable. The drawable must be specified in graph coordinate space. That is, its Graph.Drawable.toShape() method must return a shape whose control points or dimensions are specified in graph coordinate space units.
      Parameters:
      g - a graphics context that was obtained by calling the graph's createGraphics() method
      drawable - the Drawable to fill
    • draw

      public void draw(Graphics2D g, Graph.UserDrawable drawable, double x, double y)
      Draw a UserDrawable. The Drawable is specified in user space with a reference point at (0.0, 0.0) in user space. Any modifications to the graphics context's affine transform will be applied to the drawable, possibly moving the drawable with respect to the reference point, rotating the drawable, or shearing it. After any such transform is applied, the point (0.0, 0.0) will be translated to the location in user space corresponding to (x, y) in graph coordinate space.
      Parameters:
      g - a graphics context that was obtained by calling the graph's createGraphics() method
      drawable - the UserDrawable to draw
      x - the x coordinate in graph-coordinate space at which the object's reference point should be placed
      y - the y coordinate in graph-coordinate space at which the object's reference point should be placed
    • fill

      public void fill(Graphics2D g, Graph.UserDrawable drawable, double x, double y)
      Fill a UserDrawable. The Drawable is specified in user space with a reference point at (0.0, 0.0) in user space. Any modifications to the graphics context's affine transform will be applied to the drawable, possibly moving the drawable with respect to the reference point, rotating the drawable, or shearing it. After any such transform is applied, the point (0.0, 0.0) will be translated to the location in user space corresponding to (x, y) in graph coordinate space.
      Parameters:
      g - a graphics context that was obtained by calling the graph's createGraphics() method
      drawable - the UserDrawable to fill
      x - the x coordinate in graph-coordinate space at which the object's reference point should be placed
      y - the y coordinate in graph-coordinate space at which the object's reference point should be placed
    • coordTransform

      public Shape coordTransform(Shape s)
      Returns a shape in an image's or graphic context's user space given a shape in graph coordinate space.
      Parameters:
      s - the original shape
      Returns:
      the new shape
    • coordTransformForClip

      public Shape coordTransformForClip(Shape s)
      Returns a shape in an image's or graphic context's user space given a shape in graph coordinate space, preferentially making the shape a {java.awt.Rectangle} when the shape is already an instance of {java.awt.geom.RectangularShape}.

      The method Graphics.setClip(Shape) supports shapes that are returned by Graphics.getClip() or that are instances of Rectangle. This method will convert a rectangular shape into a Rectangle, providing the smallest Rectangle that contains the shape.

      Parameters:
      s - the original shape
      Returns:
      the new shape
    • invCoordTransform

      public Shape invCoordTransform(Shape s)
      Returns a shape in graph coordinate space given a shape in user space.
      Parameters:
      s - the original shape
      Returns:
      the new shape
    • draw

      public void draw(Graphics2D g, Shape s)
      Draw a shape.
      Parameters:
      g - a graphics context that was obtained by calling the graph's createGraphics() method
      s - a shape in graph coordinate space
    • fill

      public void fill(Graphics2D g, Shape s)
      Fill a shape.
      Parameters:
      g - a graphics context that was obtained by calling the graph's createGraphics() method
      s - a shape in graph coordinate space
    • clip

      public void clip(Graphics2D g, Shape s)
      Clip a graphics context based on a shape The shape will be converted to user space before the clip method is called on the graphics context. When the argument s is an instance of RectangularShape, the converted shape will be the smallest instance of Rectangle that fully contains s.
      Parameters:
      g - a graphics context that was obtained by calling the graph's createGraphics() method
      s - a shape in graph coordinate space
      See Also:
    • coordTransform

      public Point2D coordTransform(float x, float y)
      Convert x-y coordinates as floats from graph coordinate space to user space.
      Parameters:
      x - the x coordinate in graph coordinate space
      y - the y coordinate in graph coordinate space
      Returns:
      the corresponding point in user space
    • coordTransform

      public Point2D coordTransform(double x, double y)
      Convert x-y coordinates as doubles from graph coordinate space to user space.
      Parameters:
      x - the x coordinate in graph coordinate space
      y - the y coordinate in graph coordinate space
      Returns:
      the corresponding point in user space
    • coordTransform

      public Point2D coordTransform(Point2D point)
      Convert a point in graph coordinate space to user space.
      Parameters:
      point - the point in graph coordinate space
      Returns:
      the corresponding point in user space
    • coordTransform

      public Point2D coordTransform(Point2D srcPoint, Point2D destPoint)
      Convert a point in graph coordinate space to user space and store it.
      Parameters:
      srcPoint - the point in graph coordinate space
      destPoint - a point used to store the coordinates in user space; null if a new point should be created to store the results
      Returns:
      the corresponding point in user space
    • invCoordTransform

      public Point2D invCoordTransform(double x, double y) throws IllegalStateException
      Convert the x-y coordinates, as doubles, in user space to a point in graph coordinate space.
      Parameters:
      x - the x coordinate
      y - the y coordinate
      Returns:
      the corresponding point in graph-coordinate space
      Throws:
      IllegalStateException
    • invCoordTransform

      public Point2D invCoordTransform(float x, float y) throws IllegalStateException
      Convert the x-y coordinates, as floats, in user space to a point in graph coordinate space.
      Parameters:
      x - the x coordinate
      y - the y coordinate
      Returns:
      the corresponding point in graph-coordinate space
      Throws:
      IllegalStateException
    • invCoordTransform

      public Point2D invCoordTransform(Point2D point) throws IllegalStateException
      Convert a point in user space to a point in graph coordinate space.
      Parameters:
      point - a point in user space
      Returns:
      the corresponding point in graph-coordinate space
      Throws:
      IllegalStateException
    • invCoordTransform

      public Point2D invCoordTransform(Point2D srcPoint, Point2D destPoint) throws IllegalStateException
      Convert a point in user space to a point in graph coordinate space and store it.
      Parameters:
      srcPoint - the point in graph coordinate space
      destPoint - a point used to store the coordinates in user space; null if a new point should be created to store the results
      Returns:
      the corresponding point in graph coordinate space
      Throws:
      IllegalStateException
    • draw

      public void draw(Graph.Axis axis)
      Draw an axis.
      Parameters:
      axis - the axis to draw
    • getXLower

      public double getXLower()
      Get the x coordinate for the lower end of the graph's range.
      Returns:
      the x coordinate lower end of the graph's range in graph coordinate space
    • getYLower

      public double getYLower()
      Get the y coordinate for the lower end of the graph's range.
      Returns:
      the y coordinate lower end of the graph's range in graph coordinate space
    • getXUpper

      public double getXUpper()
      Get the x coordinate for the upper end of the graph's range.
      Returns:
      the x coordinate upper end of the graph's range in graph coordinate space
    • getYUpper

      public double getYUpper()
      Get the y coordinate for the upper end of the graph's range.
      Returns:
      the y coordinate upper end of the graph's range in graph coordinate space
    • setOffsets

      public void setOffsets(int x, int y)
      Set the graph offsets symmetrically.
      Parameters:
      x - the x offset in user space
      y - the y offset in user space
    • setOffsets

      public void setOffsets(int xL, int xU, int yL, int yU)
      Set the graph offsets.
      Parameters:
      xL - the lower x offset in user space
      yL - the lower y offset in user space
      xU - the upper x offset in user space
      yU - the upper y offset in user space
    • getXLowerOffset

      public int getXLowerOffset()
      Get the lower X offset for this graph. Lower and upper refer to the left and right offsets respectively.
      Returns:
      the lower X offset in user-space units
    • getXUpperOffset

      public int getXUpperOffset()
      Get the upper X offset for this graph. Lower and Upper refer to the left and right offsets respectively.
      Returns:
      the upper X offset in user-space units
    • getYLowerOffset

      public int getYLowerOffset()
      Get the lower Y offset for this graph. Lower and upper refer to the top and bottom offsets respectively.
      Returns:
      the lower X offset in user-space units
    • getYUpperOffset

      public int getYUpperOffset()
      Get the upper Y offset for this graph. Lower and upper refer to the top and bottom offsets respectively.
      Returns:
      the upper Y offset in user-space units
    • setRanges

      public void setRanges(double xLower, double xUpper, double yLower, double yUpper)
      Set the x and y ranges. All values are in graph coordinate space.
      Parameters:
      xLower - the lower value of the range in the x direction
      xUpper - the upper value of the range in the x direction
      yLower - the lower value of the range in the y direction
      yUpper - the upper value of the range in the y direction
    • setRanges

      public void setRanges(double xgcs, double ygcs, double xf, double yf, double scaleFactorX, double scaleFactorY)
      Set ranges based on scale factors. A scale factor is the ratio of a distance in user space to a distance in graph coordinate space. If angles are to be preserved, the scale factors for the X and Y directions must be equal. The scale factors are the numbers by which a coordinate difference in graph coordinate space along the X or Y directions respectively must be multiplied to obtain the corresponding difference in user space.

      Note: if setOffsets(int,int) or setOffsets(int,int,int,int) will be called, these methods should be called before this method is called.

      Parameters:
      xgcs - the x coordinate of a point in graph coordinate space that will be positioned at a specified location on the graph
      ygcs - the y coordinate of a point in graph coordinate space that will be positioned at a specified location on the graph
      xf - the fractional distance from the graph's left offset to its right offset at which the point xgcs in graph coordinate space appears
      yf - the fractional distance from the graph's lower offset to its upper offset at which the point ygcs in graph coordinate space appears
      scaleFactorX - the scale factor for the X direction
      scaleFactorY - the scale factor for the Y direction
    • getXLower

      public double getXLower(double xgcs, double xf, double scaleFactorX)
      Get the x coordinate for the lower end of the graph's range given specific parameters.
      Parameters:
      xgcs - the x coordinate of a point in graph coordinate space that will be positioned at a specified location on the graph
      xf - the fractional distance from the graph's left offset to its right offset at which the point xgcs in graph coordinate space appears
      scaleFactorX - the scale factor for the X direction (multiplying a distance in graph coordinate space by a scale factor yields the corresponding distance in user space)
      Returns:
      the lower value of the x coordinate in graph coordinate space of the graph's range
    • getXUpper

      public double getXUpper(double xgcs, double xf, double scaleFactorX)
      Get the x coordinate for the upper end of the graph's range given specific parameters.
      Parameters:
      xgcs - the x coordinate of a point in graph coordinate space that will be positioned at a specified location on the graph
      xf - the fractional distance from the graph's left offset to its right offset at which the point xgcs in graph coordinate space appears
      scaleFactorX - the scale factor for the X direction (multiplying a distance in graph coordinate space by a scale factor yields the corresponding distance in user space)
      Returns:
      the upper value of the x coordinate in graph coordinate space of the graph's range
    • getYLower

      public double getYLower(double ygcs, double yf, double scaleFactorY)
      Get the y coordinate for the lower end of the graph's range given specific parameters.
      Parameters:
      ygcs - the y coordinate of a point in graph coordinate space that will be positioned at a specified location on the graph
      yf - the fractional distance from the graph's lower offset to its upper offset at which the point ygcs in graph coordinate space appears
      scaleFactorY - the scale factor for the Y direction (multiplying a distance in graph coordinate space by a scale factor yields the corresponding distance in user space)
      Returns:
      the lower value of the y coordinate in graph coordinate space of the graph's range
    • getYUpper

      public double getYUpper(double ygcs, double yf, double scaleFactorY)
      Get the y coordinate for the upper end of the graph's range given specific parameters.
      Parameters:
      ygcs - the y coordinate of a point in graph coordinate space that will be positioned at a specified location on the graph
      yf - the fractional distance from the graph's lower offset to its upper offset at which the point ygcs in graph coordinate space appears
      scaleFactorY - the scale factor for the Y direction (multiplying a distance in graph coordinate space by a scale factor yields the corresponding distance in user space)
      Returns:
      the upper value of the y coordinate in graph coordinate space of the graph's range
    • getXLower

      public static double getXLower(double width, double xgcs, double xf, double scaleFactorX, int xLowerOffset, int xUpperOffset)
      Get the x coordinate for the lower end of the graph's range given specific parameters and graph dimensions. This method is useful for applications that have to determine the lower X value before the graph is actually created.
      Parameters:
      width - the width of the graph
      xgcs - the x coordinate of a point in graph coordinate space that will be positioned at a specified location on the graph
      xf - the fractional distance from the graph's left offset to its right offset at which the point xgcs in graph coordinate space appears
      scaleFactorX - the scale factor for the X direction (multiplying a distance in graph coordinate space by a scale factor yields the corresponding distance in user space)
      xLowerOffset - the X offset for the left edge of the graph
      xUpperOffset - the X offset for the right edge of the graph
      Returns:
      the lower value of the x coordinate in graph coordinate space of the graph's range
    • getXUpper

      public static double getXUpper(double width, double xgcs, double xf, double scaleFactorX, int xLowerOffset, int xUpperOffset)
      Get the x coordinate for the upper end of the graph's range given specific parameters and graph dimensions. This method is useful for applications that have to determine the upper X value before the graph is actually created.
      Parameters:
      width - the width of the graph
      xgcs - the x coordinate of a point in graph coordinate space that will be positioned at a specified location on the graph
      xf - the fractional distance from the graph's left offset to its right offset at which the point xgcs in graph coordinate space appears
      scaleFactorX - the scale factor for the X direction (multiplying a distance in graph coordinate space by a scale factor yields the corresponding distance in user space)
      xLowerOffset - the X offset for the left edge of the graph
      xUpperOffset - the X offset for the right edge of the graph
      Returns:
      the upper value of the x coordinate in graph coordinate space of the graph's range
    • getYLower

      public static double getYLower(double height, double ygcs, double yf, double scaleFactorY, int yLowerOffset, int yUpperOffset)
      Get the y coordinate for the lower end of the graph's range given specific parameters and graph dimensions. This method is useful for applications that have to determine the lower Y value before the graph is actually created.
      Parameters:
      height - the height of the graph
      ygcs - the y coordinate of a point in graph coordinate space that will be positioned at a specified location on the graph
      yf - the fractional distance from the graph's lower offset to its upper offset at which the point ygcs in graph coordinate space appears
      scaleFactorY - the scale factor for the Y direction (multiplying a distance in graph coordinate space by a scale factor yields the corresponding distance in user space)
      yLowerOffset - the Y offset for the lower edge of the graph
      yUpperOffset - the Y offset for the upper edge of the graph
      Returns:
      the lower value of the y coordinate in graph coordinate space of the graph's range
    • getYUpper

      public static double getYUpper(double height, double ygcs, double yf, double scaleFactorY, int yLowerOffset, int yUpperOffset)
      Get the y coordinate for the upper end of the graph's range given specific parameters and graph dimensions. This method is useful for applications that have to determine the upper Y value before the graph is actually created.
      Parameters:
      height - the height of the graph
      ygcs - the y coordinate of a point in graph coordinate space that will be positioned at a specified location on the graph
      yf - the fractional distance from the graph's lower offset to its upper offset at which the point ygcs in graph coordinate space appears
      scaleFactorY - the scale factor for the Y direction (multiplying a distance in graph coordinate space by a scale factor yields the corresponding distance in user space)
      yLowerOffset - the Y offset for the lower edge of the graph
      yUpperOffset - the Y offset for the upper edge of the graph
      Returns:
      the upper value of the y coordinate in graph coordinate space of the graph's range
    • setRotation

      public void setRotation(double theta, double xAnchor, double yAnchor)
      Specify how to rotate a graph about an anchor point expressed in graph coordinate space. This method sets parameters for a rotation. After scaling in the x and y directions, the rotation will keep the anchor point at the same position and rotate the graph about that point. Typically the anchor point will be a point that is visible on the graph. A positive value of the angle theta will rotate the graph frame counterclockwise, so objects displayed will appear to have been rotated clockwise.

      This method will rarely be used directly as it was added to allow the GraphView class to support rotations.

      Parameters:
      theta - the rotation angle in radians
      xAnchor - the X coordinate in graph coordinate space of the anchor point
      yAnchor - the Y coordinate in graph coordinate space of the anchor anchor point
    • getXScale

      public double getXScale()
      Get the scale factor in the x direction. The scale factor is multiplied by a difference of x coordinates in graph coordinate space to obtain the difference in user space. The value returned is unsigned (i.e., always non-negative). To determine the sign, use the method xAxisPointsRight(), which returns true when the positive X axis points right in graph coordinate space (the normal orientation)..
      Returns:
      the scale factor
    • getYScale

      public double getYScale()
      Get the scale factor in the y direction. The scale factor is multiplied by a difference of y coordinates in graph coordinate space to obtain the difference in user space. The value returned is unsigned (i.e., always non-negative). To determine the sign, use the method yAxisPointsDown(), which returns false when the positive Y axis points up in graph coordinate space (the normal orientation).
      Returns:
      the scale factor
    • xAxisPointsRight

      public boolean xAxisPointsRight()
      Determine direction of positive X axis in graph coordinate space.
      Returns:
      true if the positive X axis points right in user space; false otherwise
    • yAxisPointsDown

      public boolean yAxisPointsDown()
      Determine direction of positive Y axis in graph coordinate space.
      Returns:
      true if the positive Y axis points down in user space; false otherwise
    • getParity

      public int getParity()
      Get the parity for this graph. A parity of zero indicates that the parity cannot yet be determined because setRanges was not yet called or was configured so upper and lower values in either the X or Y direction are identical. Otherwise a parity of 1.0 depends on the direction in which the positive X and positive Y axes in graph coordinate space point in user space:
      • If the X axis points right and the Y axis points up, the parity is 1.
      • If the X axis points left and the Y axis points down, the parity is 1.
      • If the X axis points right and the Y axis points down, the parity is -1.
      • If the X axis points left and the Y axis points up, the parity is -1.
      A parity of 1 indicates that images rotated counterclockwise in user space are also rotated counterclockwise in graph coordinate space. A parity of -1 indicates that these rotations are in opposite directions.
      Returns:
      the current parity
    • getUserSpaceAngle

      public double getUserSpaceAngle(double gcsAngle, boolean ccw)
      Get the angle in user space corresponding to an angle in graph coordinate space. "Counterclockwise in graph coordinate space" refers to the angular direction a vector parallel to the positive X axis in graph coordinate space would turn to point parallel to the positive Y axis in graph coordinate space.

      The angle returned when ccw is true is the angle that this class's drawImage methods would use to make an image's horizontal axis parallel to a line with a given angle from the X axis in graph coordinate space.

      Parameters:
      gcsAngle - the angle in radians in graph coordinate space, measured counterclockwise
      ccw - true if the angle in user space should be measured counterclockwise; false if the angle in user space should be measured clockwise.
      Returns:
      the angle in user space.
    • getCoordTransform

      public AffineTransform getCoordTransform()
      Get a coordinate transformation to go from graph coordinate space to user space. The value returned will be a copy of the transform for this graph.
      Returns:
      the transformation
    • boundingBox

      public Rectangle2D boundingBox(boolean gcs)
      Get a bounding box for the visible area of a graph. This method is intended for cases were a graph contains a large number of objects with easily computed bounding boxes or bounding boxes that have been cached. If a large fraction of these objects are outside the visible area of the graph, one use this method to avoid an attempt to draw them.

      The box is such that areas outside the bounding box will be outside the region that is visible. For the graph coordinate space case when rotations are used, a significant fraction of the bounding box will not be visible. Rotations are primarily used for animations that use an instance of GraphView where the view changes angle.

      When gcs is true, the bounding box will be larger than the bounding box implied by the range when offsets are used.

      Parameters:
      gcs - true if the bounding box's coordinates are in graph coordinate space; false if the bounding box's units are in user space
      Returns:
      the bounding box
    • maybeVisible

      public boolean maybeVisible(Shape s, boolean gcs)
      Determine if a shape might be inside the portion of graph coordinate space that can be displayed. When this method returns true, a shape may be, but not necessarily is, within the visible area for a graph.

      The main use for this class occurs when a large number of objects may be drawn, with many of them outside the visible portion of graph coordinate space or user space. This method can be used to determine which objects are worth printing. It will run the fastest if the shape given to it is a rectangle representing a bounding box (ideally precomputed).

      Parameters:
      s - the shape to test
      gcs - true if the control points provided by a shape's path iterator are points in graph coordinate space; false if they are points in user space
      Returns:
      true if a shape might be visible; false if it is definitely not visible
    • write

      public void write(String type, String name) throws IOException
      Write the graph to a file given a file name. The type parameters are strings naming the file format as used by the class javax.imageio.ImageIO
      Parameters:
      type - the file type
      name - the file name
      Throws:
      IOException - an error occurred during writing
    • write

      public void write(String type, File file) throws IOException
      Write the graph to a file. The type parameters are strings naming the file format as used by the class javax.imageio.ImageIO
      Parameters:
      type - the file type
      file - the file to write
      Throws:
      IOException - an error occurred during writing
    • write

      public void write(String type, FileAccessor fa) throws IOException
      Write the graph to a file provided by a file accessor. The type parameters are strings naming the file format as used by the class javax.imageio.ImageIO
      Parameters:
      type - the file type
      fa - the file accessor to use
      Throws:
      IOException - an error occurred during writing
    • write

      public void write(String type, OutputStream os) throws IOException
      Write the graph to an outputStream. The type parameters are strings naming the file format as used by the class javax.imageio.ImageIO
      Parameters:
      type - the file type
      os - the output stream to which to write the image
      Throws:
      IOException - an error occurred during writing
    • flush

      public void flush() throws IOException
      Flush the graphics to an instance of OSGraphicsOps, if configured by a constructor. The behavior depends on the OSGraphicsOps subclass: some will update and object where others may do nothing. The documentation for classes implementing OSGraphicsOps should specify the behavior for that class.
      Throws:
      IOException - an IO error occurred.
    • write

      public void write() throws IOException
      Write graphics to an instance of OSGraphicsOps, if configured by a constructor.
      Throws:
      IOException - an IO error occurred.
    • draw

      public void draw(Graph.Symbol symbol, double x, double y)
      Draw a symbol.
      Parameters:
      symbol - the symbol
      x - the x coordinate in graph coordinate space
      y - the y coordinate in graph coordinate space
    • drawEX

      public void drawEX(Graph.Symbol symbol, double x, double y, double error)
      Draw a symbol with symmetric error bars in the X direction. An error bar will not be displayed if it does not extend past the symbol.
      Parameters:
      symbol - the symbol
      x - the x coordinate in graph coordinate space
      y - the y coordinate in graph coordinate space
      error - distance in graph coordinate space from the point (x, y) to the edge of an error bar
    • drawEX

      public void drawEX(Graph.Symbol symbol, double x, double y, double elow, double ehigh)
      Draw a symbol with asymmetric error bars in the X direction. An error bar will not be displayed if it does not extend past the symbol.
      Parameters:
      symbol - the symbol
      x - the x coordinate in graph coordinate space
      y - the y coordinate in graph coordinate space
      elow - distance in graph coordinate space from the point (x, y) to the edge of an error bar with the lowest value of x
      ehigh - distance in graph coordinate space from the point (x, y) to the edge of an error bar with the highest value of x
    • drawEY

      public void drawEY(Graph.Symbol symbol, double x, double y, double error)
      Draw a symbol with symmetric error bars in the Y direction. An error bar will not be displayed if it does not extend past the symbol.
      Parameters:
      symbol - the symbol
      x - the x coordinate in graph coordinate space
      y - the y coordinate in graph coordinate space
      error - distance in graph coordinate space from the point (x, y) to the edge of an error bar
    • drawEY

      public void drawEY(Graph.Symbol symbol, double x, double y, double elow, double ehigh)
      Draw a symbol with asymmetric error bars in the Y direction. An error bar will not be displayed if it does not extend past the symbol.
      Parameters:
      symbol - the symbol
      x - the x coordinate in graph coordinate space
      y - the y coordinate in graph coordinate space
      elow - distance in graph coordinate space from the point (x, y) to the edge of an error bar with the lowest value of y
      ehigh - distance in graph coordinate space from the point (x, y) to the edge of an error bar with the highest value of y
    • drawEXY

      public void drawEXY(Graph.Symbol symbol, double x, double y, double errorX, double errorY)
      Draw a symbol with symmetric error bars in the X and Y direction. An error bar will not be displayed if it does not extend past the symbol.
      Parameters:
      symbol - the symbol
      x - the x coordinate in graph coordinate space
      y - the y coordinate in graph coordinate space
      errorX - distance in the X direction in graph coordinate space from the point (x, y) to the edge of an error bar
      errorY - distance in the Y direction in graph coordinate space from the point (x, y) to the edge of an error bar
    • drawEXY

      public void drawEXY(Graph.Symbol symbol, double x, double y, double elowX, double ehighX, double elowY, double ehighY)
      Draw a symbol with asymmetric error bars in the X and Y directions. An error bar will not be displayed if it does not extend past the symbol.
      Parameters:
      symbol - the symbol
      x - the x coordinate in graph coordinate space
      y - the y coordinate in graph coordinate space
      elowX - distance in graph coordinate space from the point (x, y) to the edge of an error bar with the lowest value of x
      ehighX - distance in graph coordinate space from the point (x, y) to the edge of an error bar with the highest value of x
      elowY - distance in graph coordinate space from the point (x, y) to the edge of an error bar with the lowest value of y
      ehighY - distance in graph coordinate space from the point (x, y) to the edge of an error bar with the highest value of y