# Class PlaneSurface

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

All Implemented Interfaces:
  `PlanarSurface, Surface`

public class PlaneSurface extends 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, Scale xscale, Scale yscale, boolean xflip, boolean yflip, Tick[] xticks, Tick[] yticks, Orientation xorient, Orientation yorient, String xlabel, String ylabel, Tick[] x2ticks, Tick[] y2ticks, Orientation x2orient, Orientation y2orient, String x2label, String y2label, Captioner captioner, SideFlags annotateflags, Color gridcolor, Color axlabelcolor, boolean islabelposition)`
Constructor.

## Method Summary

Modifier and Type
Method
Description
`static PlaneSurface`
`createSurface(Rectangle plotBounds, PlaneAspect aspect, Scale xscale, Scale yscale, boolean xflip, boolean yflip, String xlabel, String ylabel, DoubleUnaryOperator x2func, DoubleUnaryOperator y2func, String x2label, String y2label, Captioner captioner, SideFlags annotateflags, double xyfactor, double xcrowd, double ycrowd, OrientationPolicy orientpolicy, boolean minor, boolean shadow, Color gridcolor, Color axlabelcolor, boolean islabelposition)`
Utility method to create a PlaneSurface from available requirements.
`boolean`
`dataToGraphics(double[] dpos, boolean visibleOnly, Point2D.Double gp)`
Converts a data space position to a graphics position.
`boolean`
`dataToGraphicsOffset(double[] dpos0, Point2D.Double gpos0, double[] dpos1, boolean visibleOnly, Point2D.Double gpos1)`
Converts an offset data space position to a graphics position.
`boolean`
`equals(Object o)`
`String`
`formatPosition(double[] dpos)`
Formats the given data space position as a coordinate string.
`static 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.
`Rectangle`
`getPlotBounds()`
Returns the rectangle within which all of the plot data will appear.
`Scale[]`
`getScales()`
Indicates the scaling along the two axes.
`Surround`
`getSurround(boolean withScroll)`
Returns the surround that this surface would like to reserve outside the plot bounds.
`boolean[]`
`getTimeFlags()`
Indicates which axes represent time values.
`double[]`
`graphicsToData(Point2D gp, Supplier<CoordSequence> dposSupplier)`
Attempts to turn a graphics position into a data position.
`int`
`hashCode()`
`boolean`
`isContinuousLine(double[] dpos0, double[] dpos1)`
Indicates whether a line in graphics space between two given data space positions is continuous.
`void`
`paintBackground(Graphics g)`
Paints the plot surface background.
`void`
`paintForeground(Graphics g)`
Paints the plot surface foreground.

### Methods inherited from class Object

`clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait`

## Constructor Details

### PlaneSurface

public PlaneSurface(int gxlo, int gxhi, int gylo, int gyhi, double dxlo, double dxhi, double dylo, double dyhi, Scale xscale, Scale yscale, boolean xflip, boolean yflip, Tick[] xticks, Tick[] yticks, Orientation xorient, Orientation yorient, String xlabel, String ylabel, Tick[] x2ticks, Tick[] y2ticks, Orientation x2orient, Orientation y2orient, String x2label, String y2label, Captioner captioner, SideFlags annotateflags, Color gridcolor, Color axlabelcolor, boolean islabelposition)
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
  `xscale` - scaling on X axis
  `yscale` - 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
  `xorient` - tick label orientation on X axis
  `yorient` - tick label orientation on Y axis
  `xlabel` - text for labelling X axis
  `ylabel` - text for labelling Y axis
  `x2ticks` - array of tickmark objects for secondary X axis
  `y2ticks` - array of tickmark objects for secondary Y axis
  `x2orient` - tick label orientation on secondary X axis
  `y2orient` - tick label orientation on secondary Y axis
  `x2label` - text for labelling secondary X axis
  `y2label` - text for labelling secondary Y axis
  `captioner` - text renderer for axis labels etc, or null if absent
  `annotateflags` - indicates which sides to annotate
  `gridcolor` - colour of grid lines, or null if not plotted
  `axlabelcolor` - colour of axis labels
  `islabelposition` - whether formatted positions should include axis labels

## Method Details

### 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

### getSurround

public Surround getSurround(boolean withScroll)
Description copied from interface: `Surface`
Returns the surround 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 a surround 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:
  `getSurround` in interface `Surface`
Parameters:
  `withScroll` - true to reserve space for nicer scrolling
Returns:
  plot data area surround

### 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, 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, Point2D.Double gpos0, double[] dpos1, 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, 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(Point2D gp, Supplier<CoordSequence> dposSupplier)
Description copied from interface: `Surface`
Attempts 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
  `dposSupplier` - 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

### isContinuousLine

public boolean isContinuousLine(double[] dpos0, double[] dpos1)
Description copied from interface: `Surface`
Indicates whether a line in graphics space between two given data space positions is continuous.

This is not very well-defined, but if drawing a line in graphics coordinates between the graphics coordinates corresponding to the two data coordinates is likely to do something badly wrong, this method should return false. It is intended to deal with the case where a short offset in data coordinates would lead to a line going the wrong way round the sky when it crosses the longitude=+/-PI boundary in an Aitoff projection.

Specified by:
  `isContinuousLine` in interface `Surface`
Parameters:
  `dpos0` - first dataDimCount-element array containing data space coordinates
  `dpos1` - second dataDimCount-element array containing data space coordinates
Returns:
  true if drawing a graphics line between the two positions should be OK

### formatPosition

public 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(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

### 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}}`

### getScales

public Scale[] getScales()
Description copied from interface: `PlanarSurface`
Indicates the scaling along the two axes.

Specified by:
  `getScales` in interface `PlanarSurface`
Returns:
  2-element array giving horizontal, vertical axis scales

### 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(Object o)

Overrides:
  `equals` in class `Object`

### hashCode

public int hashCode()

Overrides:
  `hashCode` in class `Object`

### createSurface

public static PlaneSurface createSurface(Rectangle plotBounds, PlaneAspect aspect, Scale xscale, Scale yscale, boolean xflip, boolean yflip, String xlabel, String ylabel, DoubleUnaryOperator x2func, DoubleUnaryOperator y2func, String x2label, String y2label, Captioner captioner, SideFlags annotateflags, double xyfactor, double xcrowd, double ycrowd, OrientationPolicy orientpolicy, boolean minor, boolean shadow, Color gridcolor, Color axlabelcolor, boolean islabelposition)
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
  `xscale` - scaling on X axis
  `yscale` - 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
  `x2func` - function mapping primary to secondary X axis data coord, null for no secondary X axis
  `y2func` - function mapping primary to secondary Y axis data coord, null for no secondary Y axis
  `x2label` - secondary X axis label
  `y2label` - secondary Y axis label
  `captioner` - text renderer for axis labels etc
  `annotateflags` - which sides to annotate
  `xyfactor` - ratio (X axis unit length)/(Y axis unit length), or NaN to use whatever bounds shape and axis limits give you
  `xcrowd` - crowding factor for tick marks on X axis; 1 is normal
  `ycrowd` - crowding factor for tick marks on Y axis; 1 is normal
  `orientpolicy` - tick label orientation policy
  `minor` - whether to paint minor tick marks on axes
  `shadow` - whether to paint shadow ticks on opposite axes if no secondary axis
  `gridcolor` - colour of grid lines, or null for none
  `axlabelcolor` - colour of axis labels
  `islabelposition` - whether to include axis labels in formatted position text
Returns:
  new plot surface

### formatPosition

public static 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