Class PlotVolume

  • Direct Known Subclasses:
    BitmapSortPlotVolume, VectorSortPlotVolume, ZBufferPlotVolume

    public abstract class PlotVolume
    extends java.lang.Object
    Plots 3D points on a 2D graphics context. This is an abstract class which does much of the common work but stops short of actually drawing the points. The main problem to be solved by concrete subclasses is that of ensuring that pixels 'in front' (ones with larger Z coordinates) obscure those 'behind'.

    To enable strategies which may require some kind of sorting on a full set of points prior to doing any plotting, clients of this class must first submit all the points to be plotted using the plot3D methods, and finally call flush() to ensure that the plotting has taken place.

    Since:
    22 Nov 2005
    Author:
    Mark Taylor
    • Constructor Summary

      Constructors 
      Modifier Constructor Description
      protected PlotVolume​(java.awt.Component c, java.awt.Graphics g, MarkStyle[] styles, double padFactor, int[] padBorders, double fogginess)
      Constructor.
    • Method Summary

      All Methods Static Methods Instance Methods Abstract Methods Concrete Methods 
      Modifier and Type Method Description
      DataColorTweaker createFoggingTweaker​(DataColorTweaker tweaker)  
      abstract void flush()
      Ensures that all points submitted through the plot method have been painted on the graphics context.
      Fogger getFogger()
      Returns the fogger used for rendering depth effects.
      java.awt.Graphics getGraphics()
      Returns this object's graphics context.
      int getScale()
      Returns the scaling constant for this volume.
      MarkStyle[] getStyles()
      Returns the array of styles whose markers can be plotted on this volume.
      static int packRgba​(float[] rgba)
      Utility method to convert an RGBA float[] array into an integer.
      protected abstract void plot2d​(int px, int py, double z, double[] coords, int istyle, boolean showPoint, java.lang.String label, int nerr, int[] xoffs, int[] yoffs, double[] zerrs)
      Plots an marker and optional associated error values at a given point in graphics coordinates with given additional Z coordinates.
      boolean plot3d​(double[] centre, int istyle, boolean showPoint, java.lang.String label, int nerr, double[] xerrs, double[] yerrs, double[] zerrs)
      Submits a point with associated errors for plotting.
      int projectX​(double x)
      Determines the integer X value in graphics space from an X value in normalised 3d space.
      int projectY​(double y)
      Determines the integer Y value in graphics space from a Y value in normalised 3d space.
      static void unpackRgba​(int rgba, float[] buf)
      Utility method to convert an RGBA integer into a float[] array.
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Constructor Detail

      • PlotVolume

        protected PlotVolume​(java.awt.Component c,
                             java.awt.Graphics g,
                             MarkStyle[] styles,
                             double padFactor,
                             int[] padBorders,
                             double fogginess)
        Constructor.
        Parameters:
        c - component on which points will be plotted
        g - graphics context on which points will be plotted
        styles - array of marker styles which may be used to plot
        padFactor - minimum amount of space outside the unit cube in both dimensions - 1 means no extra space
        padBorders - space, additional to padFactor, to be left around the edges of the plot; order is (left,right,bottom,top)
        fogginess - thickness of fog for depth shading
    • Method Detail

      • getStyles

        public MarkStyle[] getStyles()
        Returns the array of styles whose markers can be plotted on this volume.
        Returns:
        mark style array
      • getScale

        public int getScale()
        Returns the scaling constant for this volume. This is the value by which the normalised coordinates are multiplied to give the length on the screen in pixels of a line if it is being plotted normal to the viewer. It is approximately the linear dimension of the component in pixels.
        Returns:
        scale length
      • getFogger

        public Fogger getFogger()
        Returns the fogger used for rendering depth effects.
        Returns:
        fogger
      • plot3d

        public boolean plot3d​(double[] centre,
                              int istyle,
                              boolean showPoint,
                              java.lang.String label,
                              int nerr,
                              double[] xerrs,
                              double[] yerrs,
                              double[] zerrs)
        Submits a point with associated errors for plotting. The graphical effect is not guaranteed to occur until a subsequent call to flush(). The 3D point coordinates (one central point in centre and nerr additional points in xerrs, yerrs, zerrs) are in normalised coordinates, in which points inside the unit cube centred at (.5,.5,.5) are intended to be visible under normal circumstances. The ordering of the error points is that required by the ErrorRenderer class.

        Note that the centre array is not guaranteed to retain its contents after this call returns; this method must make copies of the values if it needs to retain them.

        The return value indicates whether the point was actually plotted; it may be false if the point was known to be off screen. This isn't guaranteed to be exact; there may be false positives or false negatives near the edge of the plotting area.

        Parameters:
        centre - normalised (x,y,z) coordinates of main point
        istyle - index into the array of styles set up for this volume which will define how the marker is plotted
        showPoint - whether the central point is to be plotted
        label - label for point, or null
        nerr - the number of error points, or zero for no errors
        xerrs - nerr-element array of X coordinates of error points
        yerrs - nerr-element array of Y coordinates of error points
        zerrs - nerr-element array of Z coordinates of error points
        Returns:
        true iff the point was actually plotted
      • projectX

        public int projectX​(double x)
        Determines the integer X value in graphics space from an X value in normalised 3d space.
        Parameters:
        x - normalised space X coordinate
        Returns:
        graphics space X coordinate
      • projectY

        public int projectY​(double y)
        Determines the integer Y value in graphics space from a Y value in normalised 3d space.
        Parameters:
        y - normalised space Y coordinate
        Returns:
        graphics space Y coordinate
      • plot2d

        protected abstract void plot2d​(int px,
                                       int py,
                                       double z,
                                       double[] coords,
                                       int istyle,
                                       boolean showPoint,
                                       java.lang.String label,
                                       int nerr,
                                       int[] xoffs,
                                       int[] yoffs,
                                       double[] zerrs)
        Plots an marker and optional associated error values at a given point in graphics coordinates with given additional Z coordinates. Points with greater Z values should obscure points with lesser ones. The ordering of the error points is that required by the ErrorRenderer class.

        Most implementations currently ignore the Z values associated with the error points, and put everything at the depth of the central point, because it's too hard to do otherwise. Does this produce seriously confusing visualisation?

        Parameters:
        px - graphics space X coordinate of the central point
        py - graphics space Y coordinate of the central point
        z - depth of point; a point with a greater z should obscure a point with a lesser one
        coords - original coordinate array; as well as (redundant) x,y,z values it may contain auxiliary axis coordinates
        istyle - index of the style used to plot the point
        showPoint - whether the central point is to be plotted
        label - label for point, or null
        nerr - number of error points, or zero for no errors
        xoffs - nerr-element array of graphics space X coordinates for error points
        yoffs - nerr-element array of graphics space Y coordinates for error points
        zerrs - nerr-element array of depths for error points
      • flush

        public abstract void flush()
        Ensures that all points submitted through the plot method have been painted on the graphics context.
      • getGraphics

        public java.awt.Graphics getGraphics()
        Returns this object's graphics context.
        Returns:
        graphics context
      • packRgba

        public static int packRgba​(float[] rgba)
        Utility method to convert an RGBA float[] array into an integer.
        Parameters:
        rgba - float array
        Returns:
        integer
      • unpackRgba

        public static void unpackRgba​(int rgba,
                                      float[] buf)
        Utility method to convert an RGBA integer into a float[] array.
        Parameters:
        rgba - integer
        buf - 4-element float array to receive result