Class SkySurface

  • All Implemented Interfaces:
    Surface

    public class SkySurface
    extends java.lang.Object
    implements Surface
    Surface implementation for plotting on the celestial sphere. The data coordinates are direction cosines: 3-element arrays containing normalised X,Y,Z coordinates, where each coordinate is in the range -1..+1 and the sum of squares is 1.
    Since:
    20 Feb 2013
    Author:
    Mark Taylor
    • Constructor Summary

      Constructors 
      Constructor Description
      SkySurface​(java.awt.Rectangle plotBounds, Projection projection, double[] rotmat, double zoom, double xoff, double yoff, SkySys viewSystem, SkyAxisLabeller axLabeller, java.awt.Color gridColor, java.awt.Color axlabelColor, java.awt.Color scalebarColor, boolean sexagesimal, double crowd, Captioner captioner, boolean antialias)
      Constructor.
    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      GridLiner createGridder​(Rotation rotation, boolean sexagesimal, double loncrowd, double latcrowd)
      Attempts to construct a GridLiner object to draw grid lines on this plot.
      LabelledLine createLine​(java.awt.geom.Point2D gp1, java.awt.geom.Point2D gp2)
      Returns a labelled line corresponding to the (shorter) great circle arc between two graphics points.
      boolean dataToGraphics​(double[] dpos, boolean visibleOnly, java.awt.geom.Point2D.Double gpos)
      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)  
      SkyAspect flatPan​(java.awt.geom.Point2D pos0, java.awt.geom.Point2D pos1)
      Pan gesture which just translates the entire graphics plane.
      SkyAspect flatZoom​(java.awt.geom.Point2D pos, double factor)
      Zoom gesture which just magnifies the entire graphics plane.
      java.lang.String formatPosition​(double[] dpos)
      Formats the given data space position as a coordinate string.
      static java.lang.String formatPositionDec​(double lonRad, double latRad, double pixRad)
      Formats a lon/lat position as decimal given the approximate size of a screen pixel.
      static java.lang.String formatPositionSex​(double lonRad, double latRad, double pixRad)
      Formats a lon/lat position as sexagesimal given the approximate size of a screen pixel.
      Captioner getCaptioner()
      Returns a captioner suitable for drawing general purpose labels annotating the plot.
      int getDataDimCount()
      Returns 3.
      double getOffsetX()
      Returns the dimensionless X offset of the plot centre from the plot bounds centre.
      double getOffsetY()
      Returns the dimensionless Y offset of the plot centre from the plot bounds centre.
      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.
      Projection getProjection()
      Returns the projection used by this sky surface.
      double[] getRotation()
      Returns the rotation matrix corresponding to this view of the sky.
      java.awt.Point getSkyCenter()
      Returns the screen position corresponding to the center of the projection used by this surface.
      java.awt.Shape getSkyShape()
      Returns a shape that gives the boundary of the sky projection in graphics coordinates.
      SkySys getViewSystem()
      Returns the sky system into which coordinates are projected.
      double getZoom()
      Returns the zoom factor; 1 means the sky is approximately the same size as the plot bounds.
      double[] graphicsToData​(java.awt.geom.Point2D gpos)
      Attempts to turn a graphics position into a sky position.
      double[] graphicsToData​(java.awt.geom.Point2D gpos, 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​(java.awt.Graphics g)
      Paints the plot surface background.
      void paintForeground​(java.awt.Graphics g)
      Paints the plot surface foreground.
      double pixelAreaSteradians()
      Returns the approximate solid angle covered by a screen pixel in steradians.
      double pixelAreaSteradians​(java.awt.geom.Point2D gpos)
      Returns the solid angle covered by a given graphics pixel in steradians.
      SkyAspect projPan​(java.awt.geom.Point2D pos0, java.awt.geom.Point2D pos1)
      Pan gesture which attempts to rotate the sky while leaving the size and location of the graphics plane unchanged.
      SkyAspect projZoom​(java.awt.geom.Point2D pos, double factor)
      Zoom gesture which attempts to zoom the sky, with the cursor staying at the same sky position, while leaving the size and location of the graphics plane unchanged.
      SkyAspect reframe​(java.awt.geom.Point2D center, double factor)
      Returns a plot aspect giving the data region defined by a graphics position and zoom factor adjustment.
      double screenDistanceRadians​(java.awt.geom.Point2D gp1, java.awt.geom.Point2D gp2)
      Returns the distance along a great circle in radians between two graphics positions.
      • Methods inherited from class java.lang.Object

        clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait
    • Constructor Detail

      • SkySurface

        public SkySurface​(java.awt.Rectangle plotBounds,
                          Projection projection,
                          double[] rotmat,
                          double zoom,
                          double xoff,
                          double yoff,
                          SkySys viewSystem,
                          SkyAxisLabeller axLabeller,
                          java.awt.Color gridColor,
                          java.awt.Color axlabelColor,
                          java.awt.Color scalebarColor,
                          boolean sexagesimal,
                          double crowd,
                          Captioner captioner,
                          boolean antialias)
        Constructor.
        Parameters:
        plotBounds - graphics region within which the plot must fall
        projection - sky projection
        rotmat - 9-element rotation matrix
        zoom - zoom factor; 1 means the sky is approximately the same size as plot bounds
        xoff - x offset of plot centre from plot bounds centre in dimensionless units; 0 is centred
        yoff - y offset of plot centre from plot bounds centre in dimensionless units; 0 is centred
        viewSystem - sky system into which coordinates are projected
        axLabeller - sky axis labelling object
        gridColor - colour for grid drawing, or null if no grid
        axlabelColor - colour for axis labels, or null if no labels
        scalebarColor - colour for scale bar, or null if not drawn
        sexagesimal - whether to use sexagesimal coordinates
        crowd - tick mark crowding factor, 1 is normal
        captioner - text rendering object
        antialias - whether to antialias grid lines
    • Method Detail

      • getDataDimCount

        public int getDataDimCount()
        Returns 3.
        Specified by:
        getDataDimCount in interface Surface
        Returns:
        number of elements in data space coordinate array
      • 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
      • 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
      • 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
      • getProjection

        public Projection getProjection()
        Returns the projection used by this sky surface.
        Returns:
        projection
      • getRotation

        public double[] getRotation()
        Returns the rotation matrix corresponding to this view of the sky.
        Returns:
        9-element rotation matrix
      • getZoom

        public double getZoom()
        Returns the zoom factor; 1 means the sky is approximately the same size as the plot bounds.
        Returns:
        zoom factor
      • getOffsetX

        public double getOffsetX()
        Returns the dimensionless X offset of the plot centre from the plot bounds centre.
        Returns:
        dimensionless X offset
      • getOffsetY

        public double getOffsetY()
        Returns the dimensionless Y offset of the plot centre from the plot bounds centre.
        Returns:
        dimensionless Y offset
      • getViewSystem

        public SkySys getViewSystem()
        Returns the sky system into which coordinates are projected.
        Returns:
        view sky system
      • createGridder

        public GridLiner createGridder​(Rotation rotation,
                                       boolean sexagesimal,
                                       double loncrowd,
                                       double latcrowd)
        Attempts to construct a GridLiner object to draw grid lines on this plot.

        The work is done by classes from the SkyView package.

        Parameters:
        rotation - additional rotation to apply to sky system before grid lines are plotted; may be null for no additional rotation
        sexagesimal - true for sexagesimal labels, false for decimal
        loncrowd - longitude tick mark crowding factor, 1 is normal
        latcrowd - latitude tick mark crowding factor, 1 is normal
        Returns:
        gridliner, or null on failure
      • dataToGraphics

        public boolean dataToGraphics​(double[] dpos,
                                      boolean visibleOnly,
                                      java.awt.geom.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:
        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
        gpos - 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 gpos,
                                       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:
        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
      • graphicsToData

        public double[] graphicsToData​(java.awt.geom.Point2D gpos)
        Attempts to turn a graphics position into a sky position. This convenience function just calls graphicsToData(gpos,null), since the iterable argument is ignored for the SkySurface.
        Parameters:
        gpos - graphics position
        Returns:
        3-element unit vector representing data position, or null if gpos out of range
      • 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 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
      • pixelAreaSteradians

        public double pixelAreaSteradians()
        Returns the approximate solid angle covered by a screen pixel in steradians. It tries to return a representative value for the visible area.
        Returns:
        approximate linear size of a screen pixel in radians
      • pixelAreaSteradians

        public double pixelAreaSteradians​(java.awt.geom.Point2D gpos)
        Returns the solid angle covered by a given graphics pixel in steradians.
        Parameters:
        gpos - position of graphics pixel center
        Returns:
        approximate linear size of pixel in radians, or NaN if pixel is not (all) on the sky
      • screenDistanceRadians

        public double screenDistanceRadians​(java.awt.geom.Point2D gp1,
                                            java.awt.geom.Point2D gp2)
        Returns the distance along a great circle in radians between two graphics positions. The evaluation should be well-conditioned for small or large angles. The given coordinates do not need to be within the graphics bounds, but if they are outside the celestial sphere, NaN will be returned.
        Parameters:
        gp1 - first position
        gp2 - second position
        Returns:
        separation between positions in radians, or NaN if one of the positions is not on the sky
      • createLine

        public LabelledLine createLine​(java.awt.geom.Point2D gp1,
                                       java.awt.geom.Point2D gp2)
        Returns a labelled line corresponding to the (shorter) great circle arc between two graphics points.
        Parameters:
        gp1 - start point in graphics space
        gp2 - end point in graphics space
        Returns:
        labelled line, or null if it can't be done, for instance if not both points are on the sky
      • formatPositionSex

        public static java.lang.String formatPositionSex​(double lonRad,
                                                         double latRad,
                                                         double pixRad)
        Formats a lon/lat position as sexagesimal given the approximate size of a screen pixel. The pixel size is used to determine how much precision to give.
        Parameters:
        lonRad - longitude in radians
        latRad - latitude in radians
        pixRad - approximate size of a screen pixel in radians
      • formatPositionDec

        public static java.lang.String formatPositionDec​(double lonRad,
                                                         double latRad,
                                                         double pixRad)
        Formats a lon/lat position as decimal given the approximate size of a screen pixel. The pixel size is used to determine how much precision to give.
        Parameters:
        lonRad - longitude in radians
        latRad - latitude in radians
        pixRad - approximate size of a screen pixel in radians
      • flatPan

        public SkyAspect flatPan​(java.awt.geom.Point2D pos0,
                                 java.awt.geom.Point2D pos1)
        Pan gesture which just translates the entire graphics plane.
        Parameters:
        pos0 - source graphics position
        pos1 - destination graphics position
        Returns:
        panned sky aspect
      • flatZoom

        public SkyAspect flatZoom​(java.awt.geom.Point2D pos,
                                  double factor)
        Zoom gesture which just magnifies the entire graphics plane.
        Parameters:
        pos - reference graphics position
        factor - zoom factor
        Returns:
        zoomed sky aspect
      • projPan

        public SkyAspect projPan​(java.awt.geom.Point2D pos0,
                                 java.awt.geom.Point2D pos1)
        Pan gesture which attempts to rotate the sky while leaving the size and location of the graphics plane unchanged. If that functionality is not supported by the projection, it will fall back to flat panning.
        Parameters:
        pos0 - source graphics position
        pos1 - destination graphics position
        Returns:
        panned sky aspect
      • projZoom

        public SkyAspect projZoom​(java.awt.geom.Point2D pos,
                                  double factor)
        Zoom gesture which attempts to zoom the sky, with the cursor staying at the same sky position, while leaving the size and location of the graphics plane unchanged. If that functionality is not supported by the projection, it will fall back to flat zooming.
        Parameters:
        pos - reference graphics position
        factor - zoom factor
        Returns:
        zoomed sky aspect
      • reframe

        public SkyAspect reframe​(java.awt.geom.Point2D center,
                                 double factor)
        Returns a plot aspect giving the data region defined by a graphics position and zoom factor adjustment.
        Parameters:
        center - position in current graphics coordinates of the sky position requested as the new center
        factor - zoom factor (from current)
        Returns:
        reframed sky aspect
      • getSkyCenter

        public java.awt.Point getSkyCenter()
        Returns the screen position corresponding to the center of the projection used by this surface. That position will typically, but not necessarily, be the least distorted point. The returned position is not necessarily within the currently visible plot bounds.
        Returns:
        central position in graphics coordinates
      • getSkyShape

        public java.awt.Shape getSkyShape()
        Returns a shape that gives the boundary of the sky projection in graphics coordinates.
        Returns:
        sky boundary shape
      • 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