# Class CubeSurface

java.lang.Object
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

Constructors
Constructor
Description
`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, Orientation[] orients, String[] labels, Captioner captioner, boolean frame, boolean antialias)`
Constructor.

## Method Summary

Modifier and Type
Method
Description
`static CubeSurface`
`createSurface(Rectangle plotBounds, CubeAspect aspect, boolean forceIso, boolean[] logFlags, boolean[] flipFlags, String[] labels, double[] crowdFactors, OrientationPolicy orientpolicy, 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, GPoint3D gPos)`
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.
`double[]`
`getDataLimits(int idim)`
Returns the data range boundaries in a specified dimension.
`boolean[]`
`getFlipFlags()`
Indicates which axes are reversed.
`boolean[]`
`getLogFlags()`
Indicates the scaling along the three axes.
`Rectangle`
`getPlotBounds()`
Returns the rectangle within which all of the plot data will appear.
`int[]`
`getScreenDirections()`
Identifies which data space axes are closest to the screen horizontal, vertical and normal directions in the current state of rotation.
`Surround`
`getSurround(boolean withScroll)`
Returns the surround that this surface would like to reserve outside the plot bounds.
`double[]`
`graphicsToData(Point2D gpos0, Supplier<CoordSequence> dposSupplier)`
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.
`boolean`
`isContinuousLine(double[] dpos0, double[] dpos1)`
Indicates whether a line in graphics space between two given data space positions is continuous.
`static boolean`
`isIsometricPossible(boolean[] logFlags)`
Determines whether forced isometric scaling makes sense for a given set of axis logarithmic flags.
`double`
`normalise(double[] dataPos, int idim)`
Maps a data space coordinate to a normalised space coordinate.
`void`
`normalisedToGraphicZ(double sx, double sy, double sz, GPoint3D gPos)`
Converts normalised 3d coordinates to a graphics position plus Z coordinate.
`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 Object

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

## Constructor Details

### 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, Orientation[] orients, 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
  `orients` - 3-element array X,Y,Z tick caption orientations
  `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 Details

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

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

### 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, 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, GPoint3D gPos)
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 3-d graphics position will be written into this point on success
Returns:
  true iff the conversion was successful
See Also:
  - `dataToGraphics(double[], boolean, Point2D.Double)`

### normalisedToGraphicZ

public void normalisedToGraphicZ(double sx, double sy, double sz, GPoint3D gPos)
Converts normalised 3d coordinates to a graphics position plus Z coordinate. The normalised positions are as returned by `normalise`. If coordinates outside of the normalised range (-1,1) are submitted, the output position will be outside the visible cube.

Parameters:
  `sx` - normalised X coordinate
  `sy` - normalised Y coordinate
  `sz` - normalised Z coordinate
  `gPos` - the graphics position will be written into this point

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

### getDataLimits

public double[] getDataLimits(int idim)
Returns the data range boundaries in a specified dimension.

Parameters:
  `idim` - dimension index (0..2)
Returns:
  2-element array giving (lower,upper) limits in data coords in the specified dimension

### getLogFlags

public boolean[] getLogFlags()
Indicates the scaling along the three axes.

Returns:
  3-element array giving X, Y, Z scaling flags: false for linear, true for logarithmic

### getFlipFlags

public boolean[] getFlipFlags()
Indicates which axes are reversed.

Returns:
  3-element array giving X, Y, Z flip flags; true to invert normal plot direction

### normalise

public double normalise(double[] dataPos, int idim)
Maps a data space coordinate to a normalised space coordinate. Normalised coordinates are in the range -1..+1.

Parameters:
  `dataPos` - 3-element data space coordinate array
  `idim` - index of dimension to convert (0, 1 or 2)
Returns:
  normalised coordinate

### 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, Supplier<CoordSequence> dposSupplier)
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
  `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

### 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 forceIso, boolean[] logFlags, boolean[] flipFlags, String[] labels, double[] crowdFactors, OrientationPolicy orientpolicy, 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
  `forceIso` - if true, scaling is forced the same on all axes
  `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
  `orientpolicy` - axis label orientation policy
  `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

### isIsometricPossible

public static boolean isIsometricPossible(boolean[] logFlags)
Determines whether forced isometric scaling makes sense for a given set of axis logarithmic flags.

Parameters:
  `logFlags` - 3-element array indicating logarithmic status for X, Y, Z axes
Returns:
  true iff forced isometric scaling is a possibility