uk.ac.starlink.ttools.plot2.geom
Class CubeSurface

java.lang.Object
  extended by uk.ac.starlink.ttools.plot2.geom.CubeSurface
All Implemented Interfaces:
Surface

public class CubeSurface
extends Object
implements Surface

Surface implementation for 3-d plotting.

Part of the surface definition involves a rotation matrix by which the data positions are rotated before being plotted to the screen. If the rotation matrix is a unit matrix, the data X coord is screen X increasing left to right (graphics positive), the data Z coord is screen Y increasing bottom to top (graphics negative), and the data Y coord is into the screen increasing front to back.

Since:
20 Feb 2013
Author:
Mark Taylor

Constructor Summary
CubeSurface(int gxlo, int gxhi, int gylo, int gyhi, double[] dlos, double[] dhis, boolean[] logFlags, boolean[] flipFlags, double[] rotmat, double zoom, double xoff, double yoff, Tick[][] ticks, String[] labels, Captioner captioner, boolean frame, boolean antialias)
          Constructor.
 
Method Summary
static CubeSurface createSurface(Rectangle plotBounds, CubeAspect aspect, boolean[] logFlags, boolean[] flipFlags, String[] labels, double[] crowdFactors, Captioner captioner, boolean frame, boolean minor, boolean antialias)
          Utility method to create a CubeSurface from available requirements.
 boolean dataToGraphics(double[] dataPos, boolean visibleOnly, Point2D.Double gPos)
          Converts a data space position to a graphics position.
 boolean dataToGraphicsOffset(double[] dataPos0, Point2D.Double gPos0, double[] dataPos1, boolean visibleOnly, Point2D.Double gpos1)
          Converts an offset data space position to a graphics position.
 boolean dataToGraphicZ(double[] dataPos, boolean visibleOnly, Point2D.Double gPos, double[] zloc)
          Returns graphics position plus Z coordinate for a data point.
 boolean equals(Object o)
           
 String formatPosition(double[] dataPos)
          Returns null.
 Captioner getCaptioner()
          Returns a captioner suitable for drawing general purpose labels annotating the plot.
 int getDataDimCount()
          Returns 3.
 Rectangle getPlotBounds()
          Returns the rectangle within which all of the plot data will appear.
 Insets getPlotInsets(boolean withScroll)
          Returns the insets that this surface would like to reserve outside the plot bounds.
 int[] getScreenDirections()
          Identifies which data space axes are closest to the screen horizontal, vertical and normal directions in the current state of rotation.
 double[] graphicsToData(Point2D gpos0, Iterable<double[]> dposIt)
          Only works if a point iterator is supplied, because of degeneracy in mapping a cube to a plane.
 int hashCode()
           
 boolean inRange(double[] dataPos)
          Determines whether a given data position is within the data space cube represented by this surface.
 void paintBackground(Graphics g)
          Paints the plot surface background.
 void paintForeground(Graphics g)
          Paints the plot surface foreground.
 Point2D.Double projectNormalisedPos(double[] nPos)
          Determines the graphics position to which a normalised space point will map.
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

CubeSurface

public CubeSurface(int gxlo,
                   int gxhi,
                   int gylo,
                   int gyhi,
                   double[] dlos,
                   double[] dhis,
                   boolean[] logFlags,
                   boolean[] flipFlags,
                   double[] rotmat,
                   double zoom,
                   double xoff,
                   double yoff,
                   Tick[][] ticks,
                   String[] labels,
                   Captioner captioner,
                   boolean frame,
                   boolean antialias)
Constructor.

Parameters:
gxlo - graphics X coordinate lower bound
gxhi - graphics X coordinate upper bound
gylo - graphics Y coordinate lower bound
gyhi - graphics Y coordinate upper bound
dlos - 3-element array giving X,Y,Z data coordinate lower bounds
dhis - 3-element array giving X,Y,Z data coordinate upper bounds
logFlags - 3-element array flagging log scaling on X,Y,Z axis
flipFlags - 3-element array flagging axis inversion for X,Y,Z
rotmat - 9-element array giving graphics space rotation matrix
zoom - zoom factor, 1 means cube roughly fills plot bounds
xoff - graphics X offset in pixels, 0 means centred in plot bounds
yoff - graphics Y offset in pixels, 0 means centred in plot bounds
ticks - 3-element array X,Y,Z tickmark arrays
labels - 3-element array of X,Y,Z axis label strings
captioner - text renderer
frame - whether to draw wire frame
antialias - whether to antialias grid lines
Method Detail

getDataDimCount

public int getDataDimCount()
Returns 3.

Specified by:
getDataDimCount in interface Surface
Returns:
number of elements in data space coordinate array

getPlotBounds

public Rectangle getPlotBounds()
Description copied from interface: Surface
Returns the rectangle within which all of the plot data will appear. This includes anything that might get drawn by a plot layer, but does not necessarily include axis labels etc.

Specified by:
getPlotBounds in interface Surface
Returns:
plot data area bounds

getPlotInsets

public Insets getPlotInsets(boolean withScroll)
Description copied from interface: Surface
Returns the insets that this surface would like to reserve outside the plot bounds. This is space outside the rectangle returned by Surface.getPlotBounds() to be used for axis labels etc.

If the withScroll parameter is set, then an attempt will be made to return insets that will not alter if the current plot is scrolled around a moderate amount. For a one-time plot that's not important, but for an interactive plot it prevents the actual plot position jumping around to accommodate more or less space on the axes according to exactly where ticks happen to fall on the axes.

Specified by:
getPlotInsets in interface Surface
Parameters:
withScroll - true to reserve space for nicer scrolling
Returns:
plot data area insets

getCaptioner

public Captioner getCaptioner()
Description copied from interface: Surface
Returns a captioner suitable for drawing general purpose labels annotating the plot.

Specified by:
getCaptioner in interface Surface
Returns:
captioner

dataToGraphics

public boolean dataToGraphics(double[] dataPos,
                              boolean visibleOnly,
                              Point2D.Double gPos)
Description copied from interface: Surface
Converts a data space position to a graphics position. If visibleOnly is true, then if the return value is true, the exit value of gPos is guaranteed to be within the plot bounds of this surface.

If visibleOnly is false, there are no guarantees about the exit value of gPos, and its coordinates could be infinite or NaN. In this case you might want to perform additional checking, for instance with the utility methods PlotUtil.isPointFinite or isPointReal.

Specified by:
dataToGraphics in interface Surface
Parameters:
dataPos - dataDimCount-element array containing data space coordinates
visibleOnly - if true, then the conversion will only succeed when the result falls within the plot bounds of this surface
gPos - point object into which the graphics position will be written on success
Returns:
true iff the conversion succeeds

dataToGraphicsOffset

public boolean dataToGraphicsOffset(double[] dataPos0,
                                    Point2D.Double gPos0,
                                    double[] dataPos1,
                                    boolean visibleOnly,
                                    Point2D.Double gpos1)
Description copied from interface: Surface
Converts an offset data space position to a graphics position. Context is given in the form of an existing converted nearby point (both data and graphics positions).

This (somewhat hacky) method is required for surfaces in which a data position may map to more than one position in graphics space, for instance sky surfaces with discontinuous longitude. The result does not need to be the same as the result of calling Surface.dataToGraphics(double[], boolean, java.awt.geom.Point2D.Double), and is not required to be a legal graphics position, but it must make visual sense, for instance when plotting error bars. The semantics of a "nearby point" is not very well defined. There are probably situations in which calling this will not give the result that's wanted, but they will probably be rare.

Specified by:
dataToGraphicsOffset in interface Surface
Parameters:
dataPos0 - context position in data space
gPos0 - context position in graphics space (result of calling dataToGraphics on dpos0)
dataPos1 - query position in data space
visibleOnly - if true, the call only succeeds if the result is within the plot bounds of this surface
gpos1 - point object to which the graphics position of dpos1 will be written on success
Returns:
true for success, false for no result

dataToGraphicZ

public boolean dataToGraphicZ(double[] dataPos,
                              boolean visibleOnly,
                              Point2D.Double gPos,
                              double[] zloc)
Returns graphics position plus Z coordinate for a data point.

Parameters:
dataPos - 3-element X,Y,Z position in data coordinates
visibleOnly - true if only data points that will be visible on this surface are of interest
gPos - the graphics position will be written into this point on success
zloc - the Z coordinate of the result will be written into the first element of this array on success
Returns:
true iff the conversion was successful
See Also:
dataToGraphics(double[], boolean, java.awt.geom.Point2D.Double)

inRange

public boolean inRange(double[] dataPos)
Determines whether a given data position is within the data space cube represented by this surface.

Parameters:
dataPos - 3-element array of non-normalised data coordinates
Returns:
true if it falls within this surface's data bounds

projectNormalisedPos

public Point2D.Double projectNormalisedPos(double[] nPos)
Determines the graphics position to which a normalised space point will map. This method is not maximally fast (it creates a Point object) so should not be used in a tight loop.

Parameters:
nPos - 3-element coordinate array in normalised space
Returns:
graphics position

formatPosition

public String formatPosition(double[] dataPos)
Returns null. At time of writing this method is not called for CubeSurface.

Specified by:
formatPosition in interface Surface
Parameters:
dataPos - dataDimCount-element array giving data space position
Returns:
human-readable string representing position

graphicsToData

public double[] graphicsToData(Point2D gpos0,
                               Iterable<double[]> dposIt)
Only works if a point iterator is supplied, because of degeneracy in mapping a cube to a plane. If we have a point iterator, then the Z coordinate is determined as the average Z coordinate of all data points that fall near to the indicated graphics position.

Specified by:
graphicsToData in interface Surface
Parameters:
gpos0 - graphics point
dposIt - iterable over dataDimCount-element arrays representing all the data space positions plotted, or null
Returns:
dataDimCount-element array giving data space position for gPos, or null if it cannot be determined

paintBackground

public void paintBackground(Graphics g)
Description copied from interface: Surface
Paints the plot surface background. Anything that appears within the plot bounds underneath the data markings must go here.

Specified by:
paintBackground in interface Surface
Parameters:
g - graphics context

paintForeground

public void paintForeground(Graphics g)
Description copied from interface: Surface
Paints the plot surface foreground. Anything that appears on top of the data markings or outside the plot bounds must go here. This may include axes.

Specified by:
paintForeground in interface Surface
Parameters:
g - graphics context

getScreenDirections

public int[] getScreenDirections()
Identifies which data space axes are closest to the screen horizontal, vertical and normal directions in the current state of rotation.

Returns:
3-element array, a permutation of the values 0,1,2; elements are indices of screen {horizontal, vertical, normal} axes respectively

equals

public boolean equals(Object o)
Overrides:
equals in class Object

hashCode

public int hashCode()
Overrides:
hashCode in class Object

createSurface

public static CubeSurface createSurface(Rectangle plotBounds,
                                        CubeAspect aspect,
                                        boolean[] logFlags,
                                        boolean[] flipFlags,
                                        String[] labels,
                                        double[] crowdFactors,
                                        Captioner captioner,
                                        boolean frame,
                                        boolean minor,
                                        boolean antialias)
Utility method to create a CubeSurface from available requirements. It works out the tickmarks and then invokes the constructor.

Parameters:
plotBounds - rectangle within which the plot should be drawn
aspect - surface view configuration
logFlags - 3-element array flagging log scaling on X,Y,Z axis
flipFlags - 3-element array flagging axis inversion for X,Y,Z
labels - 3-element array of X,Y,Z axis label strings
crowdFactors - 3-element array giving tick mark crowding factors for X,Y,Z axes; 1 is normal
captioner - text renderer
frame - whether to draw wire frame
minor - whether to draw minor tickmarks
antialias - whether to antialias grid lines
Returns:
new plot surface


Copyright © 2015 Central Laboratory of the Research Councils. All Rights Reserved.