Package gov.nasa.worldwind.ogc.kml

Class KMLRegion

  • All Implemented Interfaces:
    MessageListener, XMLEventParser
    public class KMLRegion
extends KMLAbstractObject
    Represents the KML Region element and provides access to its contents. Regions define an area of interest described by a geographic bounding box and an optional minimum and maximum altitude.

    Bounding Box
    A Region's bounding box controls when the Region is active by defining a volume that must intersect the viewing frustum. The bounding box is computed according to the altitudeMode attribute of a Region's geographic LatLonAltBox as follows:

    • clampToGround (default): The bounding box encloses the terrain surface in the sector defined by the north, south, east, and west limits of this Region's LatLonAltBox.
    • relativeToGround: The bounding box encloses the volume in the sector defined by the north, south, east, and west limits of the Region's LatLonAltBox, and who's upper and lower altitude are specified by its minAltitude and maxAltitude, relative to ground level.
    • absolute: The bounding box encloses the volume in the sector defined by the north, south, east, and west limits of the Region's LatLonAltBox, and who's upper and lower altitude are specified by its minAltitude and maxAltitude, relative to mean sea level.

    Level of Detail
    A Region's level of detail determines when it is active by defining an upper and lower boundary on the Region's screen area or the Region's distance to the view. The level of detail is computed according to the altitudeMode attribute of a Region's geographic LatLonAltBox as follows:

    • clampToGround (default): The level of detail is determined by computing the distance from the eye point and Region sector, scaling the distance by the KMLTraversalContext's detail hint, then comparing that scaled distance to the Region's min and max pixel sizes in meters (the Region sector's area divided by minLodPixels and maxLodPixels, respectively). The Region is active when the scaled distance is less than or equal to the min pixel size in meters and greater than the max pixel size in meters. The detail hint may be specified by calling setDetailHint on the top level KMLRoot (the KMLRoot loaded by the application).
    • relativeToGround: The level of detail is determined by computing the number of pixels the Region occupies on screen, and comparing that pixel count to the Region's minLodPixels and maxLodPixels. The Region is active when the pixel count is greater or equal to minLodPixels and less than maxLodPixels.
    • absolute: The level of detail is determined by computing the number of pixels the Region occupies on screen, and comparing that pixel count to the Region's minLodPixels and maxLodPixels. The Region is active when the pixel count is greater or equal to minLodPixels and less than maxLodPixels.

    In order to prevent Regions with adjacent level of detail ranges from activating at the same time, Region gives priority to higher level of detail ranges. For example, suppose that two KML features representing different detail levels of a Collada model have Regions with LOD range 100-200 and 200-300. Region avoids activating both features in the event that both their level of detail criteria are met by giving priority to the second range: 200-300.

    KML Feature Hierarchies
    When a Region is attached to a KML feature, the feature and its descendants are displayed only when the Region is active. A Region is active when its bounding box is in view and its level of detail criteria are met. Region provides the isActive method for determining if a Region is active for a specified DrawContext.

    Regions do not apply directly to KML containers, because a descendant feature can override the container's Region with its own Region. If a feature does not specify a Region it inherits the Region of its nearest ancestor. Since a child feature's Region may be larger or have a less restrictive level of detail range than its ancestor's Region, the visibility of an entire KML feature tree cannot be determined based on a container's Region. Instead, visibility must be determined at each leaf feature.

    Limitations
    The Region bounding box must lie between -90 to 90 degrees latitude, and -180 to 180 degrees longitude. Regions that span the date line are currently not supported.

    • Field Detail

      • DEFAULT_DATA_GENERATION_INTERVAL

        protected static final int DEFAULT_DATA_GENERATION_INTERVAL
        The default time in milliseconds a RegionData element may exist in this Region's regionDataCache before it must be regenerated: 6 seconds.
        See Also:
        Constant Field Values

      • DEFAULT_UNUSED_DATA_LIFETIME

        protected static final int DEFAULT_UNUSED_DATA_LIFETIME
        The default time in milliseconds a RegionData element may exist in this Region's regionDataCache without being used before it is evicted: 1 minute.
        See Also:
        Constant Field Values

      • DEFAULT_DETAIL_HINT_ORIGIN

        protected static final double DEFAULT_DETAIL_HINT_ORIGIN
        The default value that configures KML scene resolution to screen resolution as the viewing distance changes: 2.8.
        See Also:
        Constant Field Values

      • maxExpiryTime

        protected long maxExpiryTime
        The maximum lifespan of this Region's computed data, in milliseconds. Initialized to DEFAULT_DATA_GENERATION_INTERVAL.

      • minExpiryTime

        protected long minExpiryTime
        The minimum lifespan of this Region's computed data, in milliseconds. Initialized to DEFAULT_DATA_GENERATION_INTERVAL - 1000.

      • regionDataCache

        protected ShapeDataCache regionDataCache
        Holds globe-dependent computed Region data. One entry per globe encountered during isActive. Initialized to a new ShapeDataCache with maxTimeSinceLastUsed set to DEFAULT_UNUSED_DATA_LIFETIME.

      • currentData

        protected KMLRegion.RegionData currentData
        Identifies the active globe-dependent data for the current invocation of isActive. The active data is drawn from the regionDataCache at the beginning of the isActive method.

      • detailHintOrigin

        protected double detailHintOrigin
        The default value that configures KML scene resolution to screen resolution as the viewing distance changes. The KMLRoot's detail hint specifies deviations from this default. Initially DEFAULT_DETAIL_HINT_ORIGIN.

    • Constructor Detail

      • KMLRegion

        public KMLRegion​(java.lang.String namespaceURI)
        Creates a new KMLRegion with the specified namespace URI, but otherwise does nothing. The new Region has no bounding box and no level of detail range.
        Parameters:
        namespaceURI - the qualifying namespace URI. May be null to indicate no namespace qualification.

    • Method Detail

      • getLatLonAltBox

        public KMLLatLonAltBox getLatLonAltBox()
        Indicates the bounding box that must be in view for this this Region to be considered active. May be null.
        Returns:
        this Region's geographic bounding box, or null indicating that this Region has no bounding box restriction.

      • getLod

        public KMLLod getLod()
        Indicates the level of detail criteria that must be satisfied for this Region to be considered active. May be null.
        Returns:
        this Region's level of detail range, or null indicating that this Region has no level of detail restriction.

      • isActive

        public boolean isActive​(KMLTraversalContext tc,
                        DrawContext dc)
        Indicates whether this Region is active on the specified DrawContext. A Region is active if its bounding box intersects the viewing frustum, and its level of detail criteria are met for the specified traversal context and draw context.

        This always returns true if this Region has no bounding box, or if its bounding box is in the viewing frustum and this Region has no lod criteria.

        Parameters:
        tc - the current KML traversal context.
        dc - the DrawContext used to determine whether this Region is active.
        Returns:
        true if this Region is active; otherwise false.
        Throws:
        java.lang.IllegalArgumentException - if either the KMLTraversalContext or the DrawContext is null.

      • makeRegionData

        protected void makeRegionData​(DrawContext dc)
        Produces the data used to determine whether this Region is active for the specified DrawContext. This attempts to re-use RegionData already been calculated this frame, or previously calculated RegionData that is still valid and has not expired. This method is called by isActive prior to determining if this Region is actually active.
        Parameters:
        dc - the current draw context.
        See Also:
        isActive(gov.nasa.worldwind.ogc.kml.impl.KMLTraversalContext, gov.nasa.worldwind.render.DrawContext)

      • getCurrentData

        protected KMLRegion.RegionData getCurrentData()
        Returns the data cache entry for the current invocation of isActive.
        Returns:
        the data cache entry for the current invocation of isActive.

      • createCacheEntry

        protected KMLRegion.RegionData createCacheEntry​(DrawContext dc)
        Creates and returns a new RegionData instance specific to this Region instance.
        Parameters:
        dc - the current draw context.
        Returns:
        data cache entry for the state in the specified draw context.

      • mustRegenerateData

        protected boolean mustRegenerateData​(DrawContext dc)
        Indicates whether this Region's data must be recomputed, either as a result of a change in the Globe's state or the expiration of the geometry regeneration interval.

        A KMLRegion.RegionData must be current when this method is called.

        Parameters:
        dc - the current draw context.
        Returns:
        true if this Region's data must be regenerated, otherwise false.

      • doMakeRegionData

        protected void doMakeRegionData​(DrawContext dc)
        Produces the data used to determine whether this Region is active for the specified DrawContext. This method is called by makeRegionData upon determining that the current RegionData must be recomputed, either as a result of a change in the Globe's state or the expiration of the geometry regeneration interval. A KMLRegion.RegionData must be current when this method is called.
        Parameters:
        dc - the current draw context.
        See Also:
        makeRegionData(gov.nasa.worldwind.render.DrawContext)

      • doMakeClampToGroundRegionData

        protected void doMakeClampToGroundRegionData​(DrawContext dc,
                                             KMLLatLonAltBox box)
        Produces the Extent and the Sector for this Region. Assumes this region's altitude mode is clampToGround. A KMLRegion.RegionData must be current when this method is called.
        Parameters:
        dc - the current draw context.
        box - the Region's geographic bounding box.

      • doMakeRelativeToGroundRegionData

        protected void doMakeRelativeToGroundRegionData​(DrawContext dc,
                                                KMLLatLonAltBox box)
        Produces the Extent and the Sector for this Region. Assumes this region's altitude mode is relativeToGround. A KMLRegion.RegionData must be current when this method is called.
        Parameters:
        dc - the current draw context.
        box - the Region's geographic bounding box.

      • doMakeAbsoluteRegionData

        protected void doMakeAbsoluteRegionData​(DrawContext dc,
                                        KMLLatLonAltBox box)
        Produces the Extent and the Sector for this Region. Assumes this region's altitude mode is absolute. A KMLRegion.RegionData must be current when this method is called.
        Parameters:
        dc - the current draw context.
        box - the Region's geographic bounding box.

      • isSectorSupported

        protected boolean isSectorSupported​(Sector sector)
        Determines if a Sector is supported by this Region implementation. This implementation does not support sectors with latitude values outside of [-90, 90], or longitude values outside of [-180, 180].
        Parameters:
        sector - Sector to test.
        Returns:
        true if sector is with [-90, 90] latitude and [-180, 180] longitude.

      • isRegionActive

        protected boolean isRegionActive​(KMLTraversalContext tc,
                                 DrawContext dc)
        Indicates whether this Region is active on the specified DrawContext. A Region is active if its bounding box intersects the viewing frustum, and its level of detail criteria are met for the specified traversal context and draw context. This is called by isActive and its return value may be cached during a single frame.
        Parameters:
        tc - the current KML traversal context.
        dc - the DrawContext used to determine whether this Region is active.
        Returns:
        true if this Region is active; otherwise false.

      • isRegionVisible

        protected boolean isRegionVisible​(DrawContext dc)
        Indicates whether this Region is visible for the specified DrawContext. If this Region's altitudeMode is clampToGround, this Region is considered visible if its sector intersects the DrawContext's visible sector and its frustum intersects the DrawContext's viewing frustum. Otherwise, this Region is considered visible its frustum intersects the DrawContext's viewing frustum.
        Parameters:
        dc - the DrawContext used to test this Region for visibility.
        Returns:
        true if this Region is visible, otherwise false.

      • intersectsFrustum

        protected boolean intersectsFrustum​(DrawContext dc)
        Indicates whether this Region intersects the viewing frustum for the specified DrawContext. A KMLRegion.RegionData must be current when this method is called.

        This returns true if this Region has no bounding box, or if its bounding box cannot be computed for any reason.

        Parameters:
        dc - the DrawContext who's frustum is tested against this Region's bounding box.
        Returns:
        true if this Region's bounding box intersects the DrawContext's frustum, otherwise false.

      • meetsLodCriteria

        protected boolean meetsLodCriteria​(KMLTraversalContext tc,
                                   DrawContext dc)
        Indicates whether the specified DrawContext meets this Region's level of detail criteria. A KMLRegion.RegionData must be current when this method is called.

        This returns true if this Region has no level of criteria, or if its level of detail cannot be compared against the bounding box for any reason.

        Parameters:
        tc - the current KML traversal context.
        dc - the DrawContext to test.
        Returns:
        true if the DrawContext's meets this Region's level of detail criteria, otherwise false.

      • meetsClampToGroundLodCriteria

        protected boolean meetsClampToGroundLodCriteria​(KMLTraversalContext tc,
                                                DrawContext dc,
                                                KMLLod lod)
        Indicates whether the specified DrawContext meets this Region's level of detail criteria. Assumes this region's altitude mode is clampToGround. A KMLRegion.RegionData must be current when this method is called.
        Parameters:
        tc - the current KML traversal context.
        dc - the DrawContext to test.
        lod - the level of detail criteria that must be met.
        Returns:
        true if the DrawContext's meets this Region's level of detail criteria, otherwise false.

      • meetsRelativeToGroundLodCriteria

        protected boolean meetsRelativeToGroundLodCriteria​(KMLTraversalContext tc,
                                                   DrawContext dc,
                                                   KMLLod lod)
        Indicates whether the specified DrawContext meets this Region's level of detail criteria. Assumes this region's altitude mode is relativeToGround. A KMLRegion.RegionData must be current when this method is called.
        Parameters:
        tc - the current KML traversal context.
        dc - the DrawContext to test.
        lod - the level of detail criteria that must be met.
        Returns:
        true if the DrawContext's meets this Region's level of detail criteria, otherwise false.

      • meetsAbsoluteLodCriteria

        protected boolean meetsAbsoluteLodCriteria​(KMLTraversalContext tc,
                                           DrawContext dc,
                                           KMLLod lod)
        Indicates whether the specified DrawContext meets this Region's level of detail criteria. Assumes this region's altitude mode is absolute. A KMLRegion.RegionData must be current when this method is called.
        Parameters:
        tc - the current KML traversal context.
        dc - the DrawContext to test.
        lod - the level of detail criteria that must be met.
        Returns:
        true if the DrawContext's meets this Region's level of detail criteria, otherwise false.

      • meetsScreenAreaCriteria

        protected boolean meetsScreenAreaCriteria​(DrawContext dc,
                                          KMLLod lod)
        Indicates whether this Region's projected screen area on the specified DrawContext is in the range specified by lod.
        Parameters:
        dc - the DrawContext to test.
        lod - the level of detail criteria that must be met.
        Returns:
        true if this Region's screen area meets the level of detail criteria, otherwise false.

      • getDetailFactor

        protected double getDetailFactor​(KMLTraversalContext tc)
        Indicates the detail factor that configures KML scene resolution to screen resolution as the viewing distance changes. This returns the Region's detailHintOrigin plus the KMLTraversalContext's detail hint.
        Parameters:
        tc - the KML traversal context that specifies the detail hint.
        Returns:
        this Region's detailHintOrigin plus the traversal context's detailHintOrigin.

      • reset

        protected void reset()