Package gov.nasa.worldwindx.examples.analytics

Class AnalyticSurface

  • All Implemented Interfaces:
    PreRenderable, Renderable
    Direct Known Subclasses:
    ExportableAnalyticSurface
    public class AnalyticSurface
extends java.lang.Object
implements Renderable, PreRenderable
    AnalyticSurface represents a connected grid of geographic locations, covering a specified Sector at a specified base altitude in meters. The number of grid locations is defined by the AnalyticSurface's dimensions. The default dimensions are (10, 10). Callers specify the dimensions by using one of the constructors accepting width and height, or by invoking setDimensions(int, int). Each grid point has the following set of attributes:
    • Scalar value : the grid point's height relative to the surface's base altitude, both in meters
    • Color : the grid point's RGBA color components
    Callers specify the attributes at each grid point by invoking setValues(Iterable) with an Iterable of AnalyticSurface.GridPointAttributes. Grid points are assigned attributes from this iterable staring at the upper left hand corner, and proceeding in row-first order across the grid. The iterable should contain at least width * height values, where width and height are the AnalyticSurface's grid dimensions. If the caller does not specify any GridPointAttributes, or the caller specified iterable contains too few values, the unassigned grid points are given default attributes: the default scalar value is 0, and the default color is Color.BLACK.

    Surface Altitude

    AnalyticSurface's altitude can vary at each grid point. The altitude of each grid point depends on four properties: the altitude mode, the surface altitude, the vertical scale, and the scalar value from GridPointAttributes. The following table outlines how the altitude at each grid point is computed for each altitude mode:

    Altitude Computation
    Altitude ModeGrid Point Altitude
    WorldWind.ABSOLUTE (default)surface altitude + (vertical scale * scalar value from GridPointAttributes)
    WorldWind.RELATIVE_TO_GROUNDterrain height at grid point + surface altitude + (vertical scale * scalar value from GridPointAttributes)
    WorldWind.CLAMP_TO_GROUNDterrain height at grid point

    Note that when the altitude mode is WorldWind.CLAMP_TO_GROUND the surface altitude, vertical scale, and the scalar value from GridPointAttributes are ignored. In this altitude mode only the Sector, dimensions, and color from GridPointAttributes are used.

    • Field Detail

      • DEFAULT_ALTITUDE_MODE

        protected static final int DEFAULT_ALTITUDE_MODE
        The default altitude mode.
        See Also:
        Constant Field Values

      • DEFAULT_COLOR

        protected static final java.awt.Color DEFAULT_COLOR

      • RELATIVE_TO_GROUND_REGEN_PERIOD

        protected static final long RELATIVE_TO_GROUND_REGEN_PERIOD
        The time period between surface regeneration when altitude mode is relative-to-ground.
        See Also:
        Constant Field Values

      • visible

        protected boolean visible

      • sector

        protected Sector sector

      • altitude

        protected double altitude

      • altitudeMode

        protected int altitudeMode

      • width

        protected int width

      • height

        protected int height

      • verticalScale

        protected double verticalScale

      • pickObject

        protected java.lang.Object pickObject

      • clientLayer

        protected Layer clientLayer

      • extremeValues

        protected double[] extremeValues

      • expired

        protected boolean expired

      • updateFailed

        protected boolean updateFailed

      • globeStateKey

        protected java.lang.Object globeStateKey

      • regenTime

        protected long regenTime

      • referencePos

        protected Position referencePos

      • referencePoint

        protected Vec4 referencePoint

    • Constructor Detail

      • AnalyticSurface

        public AnalyticSurface​(Sector sector,
                       double altitude,
                       int width,
                       int height,
                       java.lang.Iterable<? extends AnalyticSurface.GridPointAttributes> iterable)
        Constructs a new AnalyticSurface with the specified Sector, base altitude in meters, grid dimensions, and iterable of GridPointAttributes. The iterable should contain at least with * height non-null GridPointAttributes.
        Parameters:
        sector - the Sector which defines the surface's geographic region.
        altitude - the base altitude to place the surface at, in meters.
        width - the surface grid width, in number of grid points.
        height - the surface grid height, in number of grid points.
        iterable - the attributes associated with each grid point.
        Throws:
        java.lang.IllegalArgumentException - if the sector is null, if the width is less than 1, if the height is less than 1, or if the iterable is null.

      • AnalyticSurface

        public AnalyticSurface​(Sector sector,
                       double altitude,
                       int width,
                       int height)
        Constructs a new AnalyticSurface with the specified Sector, base altitude in meters, and grid dimensions. The new AnalyticSurface has the default AnalyticSurface.GridPointAttributes.
        Parameters:
        sector - the Sector which defines the surface's geographic region.
        altitude - the base altitude to place the surface at, in meters.
        width - the surface grid width, in number of grid points.
        height - the surface grid height, in number of grid points.
        Throws:
        java.lang.IllegalArgumentException - if the sector is null, if the width is less than 1, or if the height is less than 1.

      • AnalyticSurface

        public AnalyticSurface​(Sector sector,
                       double altitude)
        Constructs a new AnalyticSurface with the specified Sector and base altitude in meters. The new AnalyticSurface has default dimensions of (10, 10), and default AnalyticSurface.GridPointAttributes.
        Parameters:
        sector - the Sector which defines the surface's geographic region.
        altitude - the base altitude to place the surface at, in meters.
        Throws:
        java.lang.IllegalArgumentException - if the sector is null.

      • AnalyticSurface

        public AnalyticSurface​(int width,
                       int height)
        Constructs a new AnalyticSurface with the specified grid dimensions. The new AnalyticSurface is has the default Sector Sector.EMPTY_SECTOR, the default altitude of 0 meters, and default AnalyticSurface.GridPointAttributes.
        Parameters:
        width - the surface grid width, in number of grid points.
        height - the surface grid height, in number of grid points.
        Throws:
        java.lang.IllegalArgumentException - if the sector is null.

    • Method Detail

      • isVisible

        public boolean isVisible()
        Returns true if the surface is visible in the scene, and false otherwise.
        Returns:
        true if the surface is visible in the scene, and false otherwise

      • setVisible

        public void setVisible​(boolean visible)
        Sets whether or not the surface is visible in the scene.
        Parameters:
        visible - true to make the surface visible, and false to make it hidden.

      • getSector

        public Sector getSector()
        Returns the Sector defining the geographic boundary of this surface.
        Returns:
        this surface's geographic boundary, as a Sector.

      • setSector

        public void setSector​(Sector sector)
        Sets this surface's geographic boundary, as a Sector.
        Parameters:
        sector - this surface's new geographic boundary, as a Sector.
        Throws:
        java.lang.IllegalArgumentException - if the sector is null.

      • getAltitude

        public double getAltitude()
        Returns this surface's base altitude, in meters.
        Returns:
        this surface's base altitude, in meters.
        See Also:
        setAltitude(double)

      • setAltitude

        public void setAltitude​(double altitude)
        Sets this surface's base altitude, in meters. See the AnalyticSurface class documentation for information on how the altitude is interpreted.
        Parameters:
        altitude - the new base altitude, in meters.

      • getDimensions

        public int[] getDimensions()
        Returns the number of horizontal and vertical points composing this surface as an array with two values. The value at index 0 indicates the grid width, and the value at index 1 indicates the grid height.
        Returns:
        the dimensions of this surface's grid.

      • setDimensions

        public void setDimensions​(int width,
                          int height)
        Sets the number of horizontal and vertical points composing this surface.
        Parameters:
        width - the new grid width.
        height - the new grid height.
        Throws:
        java.lang.IllegalArgumentException - if either width or heigth are less than 1.

      • setValues

        public void setValues​(java.lang.Iterable<? extends AnalyticSurface.GridPointAttributes> iterable)
        Sets this surface's iterable of AnalyticSurface.GridPointAttributes. Grid points are assigned attributes from this iterable staring at the upper left hand corner, and proceeding in row-first order across the grid. The iterable should contain at least width * height values, where width and height are the AnalyticSurface's grid dimensions. If the iterable contains too few values, the unassigned grid points are given default attributes: the default scalar value is 0, and the default color is Color.BLACK.
        Parameters:
        iterable - the new grid point attributes.
        Throws:
        java.lang.IllegalArgumentException - if the iterable is null.

      • getVerticalScale

        public double getVerticalScale()
        Returns the scale applied to the value at each grid point.
        Returns:
        the surface's vertical scale coefficient.

      • setVerticalScale

        public void setVerticalScale​(double scale)
        Sets the scale applied to the value at each grid point. Before rendering, this value is applied to each grid points scalar value, thus increasing or decreasing it's height relative to the surface's base altitude, both in meters.
        Parameters:
        scale - the surface's vertical scale coefficient.

      • getSurfaceAttributes

        public AnalyticSurfaceAttributes getSurfaceAttributes()
        Returns a copy of the rendering attributes associated with this surface. Modifying the contents of the returned reference has no effect on this surface. In order to make an attribute change take effect, invoke setSurfaceAttributes(AnalyticSurfaceAttributes) with the modified attributes.
        Returns:
        a copy of this surface's rendering attributes.

      • setSurfaceAttributes

        public void setSurfaceAttributes​(AnalyticSurfaceAttributes attributes)
        Sets the rendering attributes associated with this surface. The caller cannot assume that modifying the attribute reference after calling setSurfaceAttributes() will have any effect, as the implementation may defensively copy the attribute reference. In order to make an attribute change take effect, invoke setSurfaceAttributes(AnalyticSurfaceAttributes) again with the modified attributes.
        Parameters:
        attributes - this surface's new rendering attributes.
        Throws:
        java.lang.IllegalArgumentException - if attributes is null.

      • getPickObject

        public java.lang.Object getPickObject()
        Returns the object which is associated with this surface during picking. A null value is permitted and indicates that the surface itself will be the object returned during picking.
        Returns:
        this surface's pick object.

      • setPickObject

        public void setPickObject​(java.lang.Object pickObject)
        Sets the object associated with this surface during picking. A null value is permitted and indicates that the surface itself will be the object returned during picking.
        Parameters:
        pickObject - the object to associated with this surface during picking. A null value is permitted and indicates that the surface itself will be the object returned during picking.

      • getClientLayer

        public Layer getClientLayer()
        Returns the layer associated with this surface during picking.
        Returns:
        this surface's pick layer.

      • setClientLayer

        public void setClientLayer​(Layer layer)
        Sets the layer associated with this surface during picking. A null value is permitted, and indicates that no layer is associated with this surface.
        Parameters:
        layer - this surface's pick layer.

      • render

        public void render​(DrawContext dc)
        Causes this Renderable to render itself using the provided draw context.
        Specified by:
        render in interface Renderable
        Parameters:
        dc - the DrawContext to be used
        See Also:
        DrawContext

      • getExtent

        public Extent getExtent​(DrawContext dc)
        Returns this surface's extent in model coordinates.
        Parameters:
        dc - the current DrawContext.
        Returns:
        this surface's extent in the specified DrawContext.
        Throws:
        java.lang.IllegalArgumentException - if the DrawContext is null.

      • intersectsFrustum

        protected boolean intersectsFrustum​(DrawContext dc)
        Test if this AnalyticSurface intersects the specified draw context's frustum. During picking mode, this tests intersection against all of the draw context's pick frustums. During rendering mode, this tests intersection against the draw context's viewing frustum.
        Parameters:
        dc - the current draw context.
        Returns:
        true if this AnalyticSurface intersects the draw context's frustum; false otherwise.

      • computeExtremeValues

        public static double[] computeExtremeValues​(java.lang.Iterable<? extends AnalyticSurface.GridPointAttributes> iterable,
                                            double missingDataSignal)
        Returns the minimum and maximum values in the specified iterable of AnalyticSurface.GridPointAttributes. Values equivalent to the specified missingDataSignal are ignored. This returns null if the iterable is empty or contains only missing values.
        Parameters:
        iterable - the GridPointAttributes to search for the minimum and maximum value.
        missingDataSignal - the number indicating a specific value to ignore.
        Returns:
        an array containing the minimum value in index 0 and the maximum value in index 1, or null if the iterable is empty or contains only missing values.
        Throws:
        java.lang.IllegalArgumentException - if the iterable is null.

      • computeExtremeValues

        public static double[] computeExtremeValues​(java.lang.Iterable<? extends AnalyticSurface.GridPointAttributes> iterable)
        Returns the minimum and maximum values in the specified iterable of AnalyticSurface.GridPointAttributes. Values equivalent to Double.NaN are ignored. This returns null if the buffer is empty or contains only NaN values.
        Parameters:
        iterable - the GridPointAttributes to search for the minimum and maximum value.
        Returns:
        an array containing the minimum value in index 0 and the maximum value in index 1, or null if the iterable is empty or contains only NaN values.
        Throws:
        java.lang.IllegalArgumentException - if the iterable is null.

      • createGridPointAttributes

        public static AnalyticSurface.GridPointAttributes createGridPointAttributes​(double value,
                                                                            java.awt.Color color)
        Returns a new instance of AnalyticSurface.GridPointAttributes with the specified value and color.
        Parameters:
        value - the new GridPointAttributes' value.
        color - the new GridPointAttributes' color.
        Returns:
        a new GridPointAttributes defined by the specified value and color.

      • createColorGradientAttributes

        public static AnalyticSurface.GridPointAttributes createColorGradientAttributes​(double value,
                                                                                double minValue,
                                                                                double maxValue,
                                                                                double minHue,
                                                                                double maxHue)
        Returns a new instance of AnalyticSurface.GridPointAttributes with a Color computed from the specified value and value range. The color's RGB components are computed by mapping value's relative position in the range [minValue, maxValue] to the range of color hues [minHue, maxHue]. The color's Alpha component is computed by mapping the values's relative position in the range [minValue, minValue + (maxValue - minValue) / 10] to the range [0, 1]. This has the effect of interpolating hue and alpha based on the grid point value.
        Parameters:
        value - the new GridPointAttributes' value.
        minValue - the minimum value.
        maxValue - the maximum value.
        minHue - the mimimum color hue, corresponding to the minimum value.
        maxHue - the maximum color hue, corresponding to the maximum value.
        Returns:
        a new GridPointAttributes defined by the specified value, value range, and color hue range.

      • createDefaultValues

        public static java.lang.Iterable<? extends AnalyticSurface.GridPointAttributes> createDefaultValues​(int count)
        Returns a new iterable populated with the default AnalyticSurface.GridPointAttributes. The default GridPointAttributes have a value of 0, and the color Color.BLACK.
        Parameters:
        count - the desired number of GridPointAttributes to return.
        Returns:
        an iterable containing count default GridPointAttributes.

      • createColorGradientValues

        public static java.lang.Iterable<? extends AnalyticSurface.GridPointAttributes> createColorGradientValues​(BufferWrapper values,
                                                                                                          double missingDataSignal,
                                                                                                          double minValue,
                                                                                                          double maxValue,
                                                                                                          double minHue,
                                                                                                          double maxHue)
        Returns a new iterable populated with AnalyticSurface.GridPointAttributes computed by invoking createColorGradientAttributes(double, double, double, double, double) for each double value in the speicfied BufferWrapper. Values equivalent to the specified missingDataSignal are replaced with the specified minValue.
        Parameters:
        values - the buffer of values.
        missingDataSignal - the number indicating a specific value to ignore.
        minValue - the minimum value.
        maxValue - the maximum value.
        minHue - the mimimum color hue, corresponding to the minimum value.
        maxHue - the maximum color hue, corresponding to the maximum value.
        Returns:
        an iiterable GridPointAttributes defined by the specified buffer of values.

      • makeOrderedRenderable

        protected void makeOrderedRenderable​(DrawContext dc)

      • drawOrderedRenderable

        protected void drawOrderedRenderable​(DrawContext dc)

      • doDrawOrderedRenderable

        protected void doDrawOrderedRenderable​(DrawContext dc)

      • drawInterior

        protected void drawInterior​(DrawContext dc)

      • drawOutline

        protected void drawOutline​(DrawContext dc)

      • beginDrawing

        protected void beginDrawing​(DrawContext dc)

      • endDrawing

        protected void endDrawing​(DrawContext dc)

      • isExpired

        protected boolean isExpired​(DrawContext dc)

      • setExpired

        protected void setExpired​(boolean expired)

      • doUpdate

        protected void doUpdate​(DrawContext dc)

      • preRenderSurfaceObjects

        protected void preRenderSurfaceObjects​(DrawContext dc)

      • drawSurfaceObjects

        protected void drawSurfaceObjects​(DrawContext dc)