gov.nasa.worldwind.ogc.kml
Class KMLRegion

java.lang.Object
  gov.nasa.worldwind.util.xml.AbstractXMLEventParser
      gov.nasa.worldwind.ogc.kml.KMLAbstractObject
          gov.nasa.worldwind.ogc.kml.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.

Nested Class Summary

protected static class

KMLRegion.RegionData RegionData holds a Region's computed data used during a single call to Region.isActive, and is unique to a particular Globe.

Field Summary

protected KMLRegion.RegionData	currentData Identifies the active globe-dependent data for the current invocation of isActive.
protected static 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.
protected static double	DEFAULT_DETAIL_HINT_ORIGIN The default value that configures KML scene resolution to screen resolution as the viewing distance changes: 2.8.
protected static 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.
protected double	detailHintOrigin The default value that configures KML scene resolution to screen resolution as the viewing distance changes.
protected long	maxExpiryTime The maximum lifespan of this Region's computed data, in milliseconds.
protected long	minExpiryTime The minimum lifespan of this Region's computed data, in milliseconds.
protected ShapeDataCache	regionDataCache Holds globe-dependent computed Region data.

Fields inherited from class gov.nasa.worldwind.ogc.kml.KMLAbstractObject

MSG_BOX_CHANGED, MSG_GEOMETRY_CHANGED, MSG_LINK_CHANGED, MSG_STYLE_CHANGED, MSG_TIME_CHANGED, MSG_VIEW_CHANGED

Fields inherited from class gov.nasa.worldwind.util.xml.AbstractXMLEventParser

CHARACTERS_CONTENT, fields, namespaceURI, parent

Constructor Summary

KMLRegion(String namespaceURI)
Creates a new KMLRegion with the specified namespace URI, but otherwise does nothing.

Method Summary

void	applyChange(KMLAbstractObject sourceValues)
protected KMLRegion.RegionData	createCacheEntry(DrawContext dc) Creates and returns a new RegionData instance specific to this Region instance.
protected void	doMakeAbsoluteRegionData(DrawContext dc, KMLLatLonAltBox box) Produces the Extent and the Sector for this Region.
protected void	doMakeClampToGroundRegionData(DrawContext dc, KMLLatLonAltBox box) Produces the Extent and the Sector for this Region.
protected void	doMakeRegionData(DrawContext dc) Produces the data used to determine whether this Region is active for the specified DrawContext.
protected void	doMakeRelativeToGroundRegionData(DrawContext dc, KMLLatLonAltBox box) Produces the Extent and the Sector for this Region.
protected KMLRegion.RegionData	getCurrentData() Returns the data cache entry for the current invocation of isActive.
protected double	getDetailFactor(KMLTraversalContext tc) Indicates the detail factor that configures KML scene resolution to screen resolution as the viewing distance changes.
KMLLatLonAltBox	getLatLonAltBox() Indicates the bounding box that must be in view for this this Region to be considered active.
KMLLod	getLod() Indicates the level of detail criteria that must be satisfied for this Region to be considered active.
protected boolean	intersectsFrustum(DrawContext dc) Indicates whether this Region intersects viewing frustum for the specified DrawContext.
boolean	isActive(KMLTraversalContext tc, DrawContext dc) Indicates whether this Region is active on the specified DrawContext.
protected boolean	isRegionActive(KMLTraversalContext tc, DrawContext dc) Indicates whether this Region is active on the specified DrawContext.
protected boolean	isRegionVisible(DrawContext dc) Indicates whether this Region is visible for the specified DrawContext.
protected boolean	isSectorSupported(Sector sector) Determines if a Sector is supported by this Region implementation.
protected void	makeRegionData(DrawContext dc) Produces the data used to determine whether this Region is active for the specified DrawContext.
protected boolean	meetsAbsoluteLodCriteria(KMLTraversalContext tc, DrawContext dc, KMLLod lod) Indicates whether the specified DrawContext meets this Region's level of detail criteria.
protected boolean	meetsClampToGroundLodCriteria(KMLTraversalContext tc, DrawContext dc, KMLLod lod) Indicates whether the specified DrawContext meets this Region's level of detail criteria.
protected boolean	meetsLodCriteria(KMLTraversalContext tc, DrawContext dc) Indicates whether the specified DrawContext meets this Region's level of detail criteria.
protected boolean	meetsRelativeToGroundLodCriteria(KMLTraversalContext tc, DrawContext dc, KMLLod lod) Indicates whether the specified DrawContext meets this Region's level of detail criteria.
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.
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.
void	onChange(Message msg)
protected void	reset()

Methods inherited from class gov.nasa.worldwind.ogc.kml.KMLAbstractObject

getId, getRoot, getTargetId, onMessage

Methods inherited from class gov.nasa.worldwind.util.xml.AbstractXMLEventParser

allocate, doAddCharacters, doAddEventAttribute, doAddEventContent, doParseEventAttributes, doParseEventContent, freeResources, getAConstructor, getCharacters, getField, getField, getFields, getNamespaceURI, getParent, hasField, hasField, hasFields, mergeFields, newInstance, overrideFields, parse, parseCharacterContent, removeField, setField, setField, setFields, setParent

Methods inherited from class java.lang.Object

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

Field Detail

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.

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

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

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.

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.

Constructor Detail

KMLRegion

public KMLRegion(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

applyChange

public void applyChange(KMLAbstractObject sourceValues)

Overrides:

applyChange in class KMLAbstractObject

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.

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.

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.

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)

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.

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.

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.

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.

intersectsFrustum

protected boolean intersectsFrustum(DrawContext dc)

Indicates whether this Region intersects viewing frustum for the specified DrawContext. If the DrawContext is in picking mode, this indicates whether this Region's bounding box intersects any of the pick frustums. Otherwise, this this indicates whether this Region's bounding box intersects the viewing frustum. 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.

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:

IllegalArgumentException - if either the KMLTraversalContext or the DrawContext is null.

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.

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.

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)

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.

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.

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.

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.

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.

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.

onChange

public void onChange(Message msg)

Overrides:

onChange in class KMLAbstractObject

reset

protected void reset()