uk.ac.starlink.ttools.plot2.geom

Class TimeSurface

java.lang.Object

uk.ac.starlink.ttools.plot2.geom.TimeSurface

All Implemented Interfaces:

PlanarSurface, Surface

public class TimeSurface
extends Object
implements Surface, PlanarSurface

Surface implementation for time-series plotting.

Since:

17 Jul 2013

Author:

Mark Taylor

Constructor Summary

Constructors

Constructor and Description
TimeSurface(int gxlo, int gxhi, int gylo, int gyhi, double dtlo, double dthi, double dylo, double dyhi, boolean ylog, boolean yflip, Tick[] tticks, Tick[] yticks, String tlabel, String ylabel, Tick[] t2ticks, Tick[] y2ticks, String t2label, String y2label, Captioner captioner, Color gridcolor, TimeFormat tformat, SideFlags annotateflags) Constructor.

Method Summary

Modifier and Type	Method and Description
static TimeSurface	createSurface(Rectangle plotBounds, TimeAspect aspect, boolean ylog, boolean yflip, String tlabel, String ylabel, java.util.function.DoubleUnaryOperator t2func, java.util.function.DoubleUnaryOperator y2func, String t2label, String y2label, Captioner captioner, Color gridcolor, TimeFormat tformat, double tcrowd, double ycrowd, boolean minor, boolean shadow, SideFlags annotateflags) Utility method to create a TimeSurface 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.
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.
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.
boolean[]	getTimeFlags() Indicates which axes represent time values.
double[]	graphicsToData(Point2D gp, java.util.function.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 java.lang.Object

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

Constructor Detail

TimeSurface

public TimeSurface(int gxlo,
                   int gxhi,
                   int gylo,
                   int gyhi,
                   double dtlo,
                   double dthi,
                   double dylo,
                   double dyhi,
                   boolean ylog,
                   boolean yflip,
                   Tick[] tticks,
                   Tick[] yticks,
                   String tlabel,
                   String ylabel,
                   Tick[] t2ticks,
                   Tick[] y2ticks,
                   String t2label,
                   String y2label,
                   Captioner captioner,
                   Color gridcolor,
                   TimeFormat tformat,
                   SideFlags annotateflags)

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

dtlo - data time coordinate lower bound in unix seconds

dthi - data time coordinate upper bound in unix seconds

dylo - data Y coordinate lower bound

dyhi - data Y coordinate upper bound

ylog - whether to use logarithmic scaling on Y axis

yflip - whether to invert direction of Y axis

tticks - array of tickmark objects for time axis

yticks - array of tickmark objects for Y axis

tlabel - text for labelling time axis

ylabel - text for labelling Y axis

t2ticks - array of tickmark objects for secondary time axis

y2ticks - array of tickmark objects for secondary Y axis

t2label - text for labelling secondary time axis

y2label - text for labelling secondary Y axis

captioner - text renderer for axis labels etc

gridcolor - grid line colour, or null for none

tformat - time labelling format

annotateflags - which sides to annotate

Method Detail

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, 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(Point2D gp,
                               java.util.function.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

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

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

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

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

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

hashCode

public int hashCode()

Overrides:

hashCode in class Object

equals

public boolean equals(Object o)

Overrides:

equals in class Object

createSurface

public static TimeSurface createSurface(Rectangle plotBounds,
                                        TimeAspect aspect,
                                        boolean ylog,
                                        boolean yflip,
                                        String tlabel,
                                        String ylabel,
                                        java.util.function.DoubleUnaryOperator t2func,
                                        java.util.function.DoubleUnaryOperator y2func,
                                        String t2label,
                                        String y2label,
                                        Captioner captioner,
                                        Color gridcolor,
                                        TimeFormat tformat,
                                        double tcrowd,
                                        double ycrowd,
                                        boolean minor,
                                        boolean shadow,
                                        SideFlags annotateflags)

Utility method to create a TimeSurface 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

ylog - whether to use logarithmic scaling on Y axis

yflip - whether to invert direction of Y axis

tlabel - text for labelling time axis

ylabel - text for labelling Y axis

t2func - function mapping unix seconds to secondary time axis data coord, null for no secondary time axis

y2func - function mapping primary to secondary Y axis data coord, null for no secondary Y axis

t2label - secondary time axis label

y2label - secondary Y axis label

captioner - text renderer for axis labels etc

gridcolor - colour of grid lines, or null for none

tformat - time labelling format

tcrowd - crowding factor for tick marks on time 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

shadow - whether to paint shadow ticks on opposite axes if no secondary axis

annotateflags - which axes to annotate

Returns:

new plot surface