Surface (Starlink-UK API)

All Known Subinterfaces:

PlanarSurface

All Known Implementing Classes:

CubeSurface, PlaneSurface, SkySurface, TimeSurface
```
public interface Surface
```
Defines the graphical area on which plots are painted. It maps data space coordinates to graphics coordinates (and possibly vice versa) and paints axes.

Since:

11 Feb 2013

Author:

Mark Taylor

See Also:

SurfaceFactory

Method Summary

All Methods Instance Methods Abstract Methods
Modifier and Type	Method and Description
`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.
`String`	`formatPosition(double[] dataPos)` Formats the given data space position as a coordinate string.
`Captioner`	`getCaptioner()` Returns a captioner suitable for drawing general purpose labels annotating the plot.
`int`	`getDataDimCount()` Returns the dimensionality of the data space used by this plot surface.
`Rectangle`	`getPlotBounds()` Returns the rectangle within which all of the plot data will appear.
`Surround`	`getSurround(boolean withScroll)` Returns the surround that this surface would like to reserve outside the plot bounds.
`double[]`	`graphicsToData(Point2D gPos, java.util.function.Supplier<CoordSequence> dposSupplier)` Attempts to turn a graphics position into a data position.
`boolean`	`isContinuousLine(double[] dataPos0, double[] dataPos1)` 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.

- Method Detail
  - getPlotBounds
```
Rectangle getPlotBounds()
```
    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.
    
    Returns:
    
    plot data area bounds
  - getSurround
```
Surround getSurround(boolean withScroll)
```
    Returns the surround that this surface would like to reserve outside the plot bounds. This is space outside the rectangle returned by 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.
    
    Parameters:
    
    withScroll - true to reserve space for nicer scrolling
    
    Returns:
    
    plot data area surround
  - paintBackground
```
void paintBackground(Graphics g)
```
    Paints the plot surface background. Anything that appears within the plot bounds underneath the data markings must go here.
    
    Parameters:
    
    g - graphics context
  - paintForeground
```
void paintForeground(Graphics g)
```
    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.
    
    Parameters:
    
    g - graphics context
  - getDataDimCount
```
int getDataDimCount()
```
    Returns the dimensionality of the data space used by this plot surface.
    
    Returns:
    
    number of elements in data space coordinate array
  - dataToGraphics
```
boolean dataToGraphics(double[] dataPos,
                       boolean visibleOnly,
                       Point2D.Double gPos)
```
    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.
    
    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
```
boolean dataToGraphicsOffset(double[] dataPos0,
                             Point2D.Double gpos0,
                             double[] dataPos1,
                             boolean visibleOnly,
                             Point2D.Double gPos1)
```
    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 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.
    
    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
  - graphicsToData
```
double[] graphicsToData(Point2D gPos,
                        java.util.function.Supplier<CoordSequence> dposSupplier)
```
    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.
    
    Parameters:
    
    gPos - 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
```
boolean isContinuousLine(double[] dataPos0,
                         double[] dataPos1)
```
    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.
    
    Parameters:
    
    dataPos0 - first dataDimCount-element array containing data space coordinates
    
    dataPos1 - second dataDimCount-element array containing data space coordinates
    
    Returns:
    
    true if drawing a graphics line between the two positions should be OK
  - formatPosition
```
String formatPosition(double[] dataPos)
```
    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.
    
    Parameters:
    
    dataPos - dataDimCount-element array giving data space position
    
    Returns:
    
    human-readable string representing position
  - getCaptioner
```
Captioner getCaptioner()
```
    Returns a captioner suitable for drawing general purpose labels annotating the plot.
    
    Returns:
    
    captioner

Interface Surface

Method Summary

Method Detail

getPlotBounds

getSurround

paintBackground

paintForeground

getDataDimCount

dataToGraphics

dataToGraphicsOffset

graphicsToData

isContinuousLine

formatPosition

getCaptioner