PlaneSurface (Starjava TTOOLS API)

java.lang.Object
- uk.ac.starlink.ttools.plot2.geom.PlaneSurface

All Implemented Interfaces:

PlanarSurface, Surface
```
public class PlaneSurface
extends java.lang.Object
implements Surface, PlanarSurface
```
Surface implementation for flat 2-d plotting.

Since:

19 Feb 2013

Author:

Mark Taylor

Constructor Summary

Constructors
Constructor	Description
`PlaneSurface(int gxlo, int gxhi, int gylo, int gyhi, double dxlo, double dxhi, double dylo, double dyhi, boolean xlog, boolean ylog, boolean xflip, boolean yflip, Tick[] xticks, Tick[] yticks, java.lang.String xlabel, java.lang.String ylabel, Captioner captioner, java.awt.Color gridcolor, java.awt.Color axlabelcolor)`	Constructor.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method	Description
`static PlaneSurface`	`createSurface(java.awt.Rectangle plotBounds, PlaneAspect aspect, boolean xlog, boolean ylog, boolean xflip, boolean yflip, java.lang.String xlabel, java.lang.String ylabel, Captioner captioner, double xyfactor, boolean grid, double xcrowd, double ycrowd, boolean minor, java.awt.Color gridcolor, java.awt.Color axlabelcolor)`	Utility method to create a PlaneSurface from available requirements.
`boolean`	`dataToGraphics(double[] dpos, boolean visibleOnly, java.awt.geom.Point2D.Double gp)`	Converts a data space position to a graphics position.
`boolean`	`dataToGraphicsOffset(double[] dpos0, java.awt.geom.Point2D.Double gpos0, double[] dpos1, boolean visibleOnly, java.awt.geom.Point2D.Double gpos1)`	Converts an offset data space position to a graphics position.
`boolean`	`equals(java.lang.Object o)`
`java.lang.String`	`formatPosition(double[] dpos)`	Formats the given data space position as a coordinate string.
`static java.lang.String`	`formatPosition(Axis axis, double dpos)`	Formats a coordinate value for presentation to the user.
`Axis[]`	`getAxes()`	Returns the axis objects used by this surface.
`Captioner`	`getCaptioner()`	Returns a captioner suitable for drawing general purpose labels annotating the plot.
`int`	`getDataDimCount()`	Returns 2.
`double[][]`	`getDataLimits()`	Returns the limits in data coordinates of the plot region.
`boolean[]`	`getFlipFlags()`	Indicates which axes are reversed.
`boolean[]`	`getLogFlags()`	Indicates the scaling along the two axes.
`java.awt.Rectangle`	`getPlotBounds()`	Returns the rectangle within which all of the plot data will appear.
`java.awt.Insets`	`getPlotInsets(boolean withScroll)`	Returns the insets that this surface would like to reserve outside the plot bounds.
`boolean[]`	`getTimeFlags()`	Indicates which axes represent time values.
`double[]`	`graphicsToData(java.awt.geom.Point2D gp, java.lang.Iterable<double[]> dposIt)`	Attempst to turn a graphics position into a data position.
`int`	`hashCode()`
`void`	`paintBackground(java.awt.Graphics g)`	Paints the plot surface background.
`void`	`paintForeground(java.awt.Graphics g)`	Paints the plot surface foreground.

Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait

- Constructor Detail
  - PlaneSurface
```
public PlaneSurface(int gxlo,
                    int gxhi,
                    int gylo,
                    int gyhi,
                    double dxlo,
                    double dxhi,
                    double dylo,
                    double dyhi,
                    boolean xlog,
                    boolean ylog,
                    boolean xflip,
                    boolean yflip,
                    Tick[] xticks,
                    Tick[] yticks,
                    java.lang.String xlabel,
                    java.lang.String ylabel,
                    Captioner captioner,
                    java.awt.Color gridcolor,
                    java.awt.Color axlabelcolor)
```
    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
    
    dxlo - data X coordinate lower bound
    
    dxhi - data X coordinate upper bound
    
    dylo - data Y coordinate lower bound
    
    dyhi - data Y coordinate upper bound
    
    xlog - whether to use logarithmic scaling on X axis
    
    ylog - whether to use logarithmic scaling on Y axis
    
    xflip - whether to invert direction of X axis
    
    yflip - whether to invert direction of Y axis
    
    xticks - array of tickmark objects for X axis
    
    yticks - array of tickmark objects for Y axis
    
    xlabel - text for labelling X axis
    
    ylabel - text for labelling Y axis
    
    captioner - text renderer for axis labels etc, or null if absent
    
    gridcolor - colour of grid lines, or null if not plotted
    
    axlabelcolor - colour of axis labels
- Method Detail
  - getPlotBounds
```
public java.awt.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 java.awt.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.
    This method is supposed to return only the space that may actually be touched by the plot. The calling code may wish to apply additional padding on top of this for cosmetic reasons.
    
    Specified by:
    
    getPlotInsets in interface Surface
    
    Parameters:
    
    withScroll - true to reserve space for nicer scrolling
    
    Returns:
    
    plot data area insets
  - getDataDimCount
```
public int getDataDimCount()
```
    Returns 2.
    
    Specified by:
    
    getDataDimCount in interface Surface
    
    Returns:
    
    number of elements in data space coordinate array
  - dataToGraphics
```
public boolean dataToGraphics(double[] dpos,
                              boolean visibleOnly,
                              java.awt.geom.Point2D.Double gp)
```
    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:
    
    dpos - 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
    
    gp - point object into which the graphics position will be written on success
    
    Returns:
    
    true iff the conversion succeeds
  - dataToGraphicsOffset
```
public boolean dataToGraphicsOffset(double[] dpos0,
                                    java.awt.geom.Point2D.Double gpos0,
                                    double[] dpos1,
                                    boolean visibleOnly,
                                    java.awt.geom.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:
    
    dpos0 - context position in data space
    
    gpos0 - context position in graphics space (result of calling dataToGraphics on dpos0)
    
    dpos1 - 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
  - graphicsToData
```
public double[] graphicsToData(java.awt.geom.Point2D gp,
                               java.lang.Iterable<double[]> dposIt)
```
    Description copied from interface: Surface
    
    Attempst to turn a graphics position into a data position. This is not always trivial, for instance in a 3D plot one graphics position maps to a line of data positions. The dposIt argument can optionally be supplied to cope with such instances. If a data pos cannot be determined, null is returned. If dposIt is absent, the method will run quickly. If it's present, it may or may not run slowly.
    
    Specified by:
    
    graphicsToData in interface Surface
    
    Parameters:
    
    gp - 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
  - formatPosition
```
public java.lang.String formatPosition(double[] dpos)
```
    Description copied from interface: Surface
    
    Formats the given data space position as a coordinate string. If possible the returned string should have the same length and formatting over the whole visible plot surface, so that the representation doesn't jump around when the cursor is moved.
    
    Specified by:
    
    formatPosition in interface Surface
    
    Parameters:
    
    dpos - dataDimCount-element array giving data space position
    
    Returns:
    
    human-readable string representing position
  - 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
  - paintBackground
```
public void paintBackground(java.awt.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(java.awt.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
  - getDataLimits
```
public double[][] getDataLimits()
```
    Description copied from interface: PlanarSurface
    
    Returns the limits in data coordinates of the plot region.
    
    Specified by:
    
    getDataLimits in interface PlanarSurface
    
    Returns:
    
    2x2 array {{xlo, xhi}, {ylo, yhi}}
  - getLogFlags
```
public boolean[] getLogFlags()
```
    Description copied from interface: PlanarSurface
    
    Indicates the scaling along the two axes.
    
    Specified by:
    
    getLogFlags in interface PlanarSurface
    
    Returns:
    
    2-element array giving horizontal, vertical scaling flags: false for linear, true for logarithmic
  - getFlipFlags
```
public boolean[] getFlipFlags()
```
    Description copied from interface: PlanarSurface
    
    Indicates which axes are reversed.
    
    Specified by:
    
    getFlipFlags in interface PlanarSurface
    
    Returns:
    
    2-element array giving horizontal, vertical flip flags; true to invert normal plot direction
  - getTimeFlags
```
public boolean[] getTimeFlags()
```
    Description copied from interface: PlanarSurface
    
    Indicates which axes represent time values.
    
    Specified by:
    
    getTimeFlags in interface PlanarSurface
    
    Returns:
    
    2-element array giving horizontal, vertical time flags; true for time axis with data units of seconds, false for normal numeric axis
  - getAxes
```
public Axis[] getAxes()
```
    Description copied from interface: PlanarSurface
    
    Returns the axis objects used by this surface.
    
    Specified by:
    
    getAxes in interface PlanarSurface
    
    Returns:
    
    2-element array giving horizontal, vertical axis instances
  - equals
```
public boolean equals(java.lang.Object o)
```
    Overrides:
    
    equals in class java.lang.Object
  - hashCode
```
public int hashCode()
```
    Overrides:
    
    hashCode in class java.lang.Object
  - createSurface
```
public static PlaneSurface createSurface(java.awt.Rectangle plotBounds,
                                         PlaneAspect aspect,
                                         boolean xlog,
                                         boolean ylog,
                                         boolean xflip,
                                         boolean yflip,
                                         java.lang.String xlabel,
                                         java.lang.String ylabel,
                                         Captioner captioner,
                                         double xyfactor,
                                         boolean grid,
                                         double xcrowd,
                                         double ycrowd,
                                         boolean minor,
                                         java.awt.Color gridcolor,
                                         java.awt.Color axlabelcolor)
```
    Utility method to create a PlaneSurface from available requirements. It works out actual data coordinate bounds and tickmarks, and then invokes the constructor.
    
    Parameters:
    
    plotBounds - rectangle which the plot data should occupy
    
    aspect - surface view configuration
    
    xlog - whether to use logarithmic scaling on X axis
    
    ylog - whether to use logarithmic scaling on Y axis
    
    xflip - whether to invert direction of X axis
    
    yflip - whether to invert direction of Y axis
    
    xlabel - text for labelling X axis
    
    ylabel - text for labelling Y axis
    
    captioner - text renderer for axis labels etc
    
    xyfactor - ratio (X axis unit length)/(Y axis unit length), or NaN to use whatever bounds shape and axis limits give you
    
    grid - whether to draw grid lines
    
    xcrowd - crowding factor for tick marks on X axis; 1 is normal
    
    ycrowd - crowding factor for tick marks on Y axis; 1 is normal
    
    minor - whether to paint minor tick marks on axes
    
    gridcolor - colour of grid lines, if plotted
    
    axlabelcolor - colour of axis labels
    
    Returns:
    
    new plot surface
  - formatPosition
```
public static java.lang.String formatPosition(Axis axis,
                                              double dpos)
```
    Formats a coordinate value for presentation to the user.
    
    Parameters:
    
    axis - axis on which value appears
    
    dpos - data coordinate value
    
    Returns:
    
    formatted data coordinate string

Class PlaneSurface

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

PlaneSurface

Method Detail

getPlotBounds

getPlotInsets

getDataDimCount

dataToGraphics

dataToGraphicsOffset

graphicsToData

formatPosition

getCaptioner

paintBackground

paintForeground

getDataLimits

getLogFlags

getFlipFlags

getTimeFlags

getAxes

equals

hashCode

createSurface

formatPosition