gov.nasa.worldwindx.examples.util

Class ExtentVisibilitySupport

java.lang.Object

gov.nasa.worldwindx.examples.util.ExtentVisibilitySupport

public class ExtentVisibilitySupport
extends java.lang.Object

ExtentVisibilitySupport provides visibility tests and computations on objects with 3D extents in model coordinates, and on objects with 2D extents in screen coordinates. The caller configures ExtentVisibilitySupport with an Iterable of Extent instances and ExtentVisibilitySupport.ScreenExtent instances by invoking setExtents(Iterable) and setScreenExtents(Iterable), respectively. These Iterables defines ExtentVisibilitySupport's scene elements. ExtentVisibilitySupport keeps a direct reference to these Iterables; it does not attempt to copy or modify them in any way. Any null elements in these Iterables are ignored. The static convenience method extentsFromExtentHolders(Iterable, gov.nasa.worldwind.globes.Globe, double) makes it easy to for callers to convert an Iterable of Extents references to an Iterable of ExtentHolder references.

The method areExtentsContained(gov.nasa.worldwind.View) provides a mechanism for callers to test whether or not the currently configured scene is entirely contained within a certain View. This method tests containment on both the model coordinate extents and screen coordinate extents.

The method computeViewLookAtContainingExtents(gov.nasa.worldwind.globes.Globe, double, gov.nasa.worldwind.View) returns a viewing coordinate system which contains the currently configured scene, while preserving the current view's orientation to the globe (heading and pitch). This has the effect of computing the pan and zoom parameters necessary for a View to contain the current scene. Depending on the current scene, the computed view may represent a best-estimate, and not the final parameters necessary to contain the scene. If the scene contains model coordinate extents which depend on the view, or screen coordinate extents, the caller should invoke this method iteratively (after applying view changes from the previous call) until the returned view coordinate system converges on values which contain the scene.

See Also:

Extent, ExtentHolder, ExtentVisibilitySupport.ScreenExtent

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	ExtentVisibilitySupport.ScreenExtent ScreenExtent represents a screen object's enclosing bounding box in screen coordinates, and that object's reference point in model coordinates.

Field Summary

Fields

Modifier and Type	Field and Description
protected static double	EPSILON
protected java.lang.Iterable<? extends Extent>	extentIterable
protected static double	SCREEN_POINT_PADDING_PIXELS
protected java.lang.Iterable<? extends ExtentVisibilitySupport.ScreenExtent>	screenExtentIterable

Constructor Summary

Constructors

Constructor and Description
ExtentVisibilitySupport() Constructs a new ExtentVisibilitySupport, but otherwise does nothing.

Method Summary

Modifier and Type	Method and Description
boolean	areExtentsContained(Frustum frustum, java.awt.Rectangle viewport) Returns true if the model coordinates scene elements are completely inside the space enclosed by the specified Frustum in model coordinates, and the screen coordinate scene elements are completely inside the viewport rectangle.
boolean	areExtentsContained(View view) Returns true if the model coordinates scene elements are completely inside the space enclosed by the specified View in model coordinates, and the screen coordinate scene elements are completely inside the View's viewport rectangle.
protected Vec4	computeCenterPoint(Globe globe, double verticalExaggeration, java.lang.Iterable<? extends Extent> modelExtents, java.lang.Iterable<? extends ExtentVisibilitySupport.ScreenExtent> screenExtents)
protected Vec4	computeEyePoint(Vec4 eye, Vec4 center, Vec4 up, Angle fieldOfView, java.awt.Rectangle viewport, double nearClipDistance, double farClipDistance, java.lang.Iterable<? extends Extent> modelExtents, java.lang.Iterable<? extends ExtentVisibilitySupport.ScreenExtent> screenExtents)
protected Vec4	computeEyePointForModelExtents(Vec4 eye, Vec4 center, Vec4 up, Angle fieldOfView, java.awt.Rectangle viewport, java.lang.Iterable<? extends Extent> modelExtents)
protected Vec4	computeEyePointForScreenBounds(Vec4 eye, Vec4 center, Vec4 up, Angle fieldOfView, java.awt.Rectangle viewport, double nearClipDistance, double farClipDistance, java.lang.Iterable<? extends ExtentVisibilitySupport.ScreenExtent> screenExtents)
protected Vec4	computeEyePointForScreenExtents(Vec4 eye, Vec4 center, Vec4 up, Angle fieldOfView, java.awt.Rectangle viewport, double nearClipDistance, double farClipDistance, java.lang.Iterable<? extends ExtentVisibilitySupport.ScreenExtent> screenExtents)
protected Vec4	computeEyePointForScreenReferencePoints(Vec4 eye, Vec4 center, Vec4 up, Angle fieldOfView, java.awt.Rectangle viewport, java.lang.Iterable<? extends ExtentVisibilitySupport.ScreenExtent> screenExtents)
Vec4[]	computeViewLookAtContainingExtents(Globe globe, double verticalExaggeration, Vec4 eyePoint, Vec4 centerPoint, Vec4 upVector, Angle fieldOfView, java.awt.Rectangle viewport, double nearClipDistance, double farClipDistance) Returns an array of View look-at vectors optimal for viewing the the scene elements, or null if this has no scene elements.
Vec4[]	computeViewLookAtContainingExtents(Globe globe, double verticalExaggeration, View view) Returns an array of View look-at vectors optimal for viewing the the scene elements, or null if this has no scene elements.
static java.lang.Iterable<Extent>	extentsFromExtentHolders(java.lang.Iterable<? extends ExtentHolder> extentHolders, Globe globe, double verticalExaggeration) Converts the specified Iterable of ExtentHolder references to a new Iterable of Extent references.
java.lang.Iterable<? extends Extent>	getExtents() Returns this ExtentVisibilitySupport's Iterable of Extents.
java.lang.Iterable<? extends ExtentVisibilitySupport.ScreenExtent>	getScreenExtents() Returns this ExtentVisibilitySupport's Iterable of ScreenExtents.
void	setExtents(java.lang.Iterable<? extends Extent> extents) Sets this ExtentVisibilitySupport's Iterable of Extents.
void	setScreenExtents(java.lang.Iterable<? extends ExtentVisibilitySupport.ScreenExtent> screenExtents) Sets this ExtentVisibilitySupport's Iterable of ScreenExtents.
protected java.lang.Iterable<ExtentVisibilitySupport.ScreenExtent>	translateScreenExtents(java.lang.Iterable<? extends ExtentVisibilitySupport.ScreenExtent> screenExtents, Matrix oldModelview, Matrix newModelview, Matrix projection, java.awt.Rectangle viewport)
protected java.lang.String	validate(Vec4 eye, Vec4 center, Vec4 up, Angle fieldOfView, java.awt.Rectangle viewport, double nearClipDistance, double farClipDistance)

Methods inherited from class java.lang.Object

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

Field Detail

EPSILON

protected static final double EPSILON

See Also:

Constant Field Values

extentIterable

protected java.lang.Iterable<? extends Extent> extentIterable

SCREEN_POINT_PADDING_PIXELS

protected static final double SCREEN_POINT_PADDING_PIXELS

See Also:

Constant Field Values

screenExtentIterable

protected java.lang.Iterable<? extends ExtentVisibilitySupport.ScreenExtent> screenExtentIterable

Constructor Detail

ExtentVisibilitySupport

public ExtentVisibilitySupport()

Constructs a new ExtentVisibilitySupport, but otherwise does nothing.

Method Detail

areExtentsContained

public boolean areExtentsContained(Frustum frustum,
                                   java.awt.Rectangle viewport)

Returns true if the model coordinates scene elements are completely inside the space enclosed by the specified Frustum in model coordinates, and the screen coordinate scene elements are completely inside the viewport rectangle. Otherwise, this returns false. If this ExtentVisibilitySupport has no scene elements, this returns true.

Parameters:

frustum - the Frustum with which to test for containment, in model coordinates.

viewport - the viewport rectangle with which to test for containment, in screen coordinates.

Returns:

true if the scene elements are completely inside the Frustum and viewport rectangle, or if this has no scene elements. false if any scene element is partially or completely outside the Frustum or viewport rectangle.

Throws:

java.lang.IllegalArgumentException - if either the the Frustum or the viewport are null.

areExtentsContained

public boolean areExtentsContained(View view)

Returns true if the model coordinates scene elements are completely inside the space enclosed by the specified View in model coordinates, and the screen coordinate scene elements are completely inside the View's viewport rectangle. Otherwise, this returns false. If this ExtentVisibilitySupport has no scene elements, this returns true.

Parameters:

view - The View with which to test for containment.

Returns:

true if the scene elements are completely inside the View and it's viewport rectangle, or if this has no scene elements. false if any scene element is partially or completely outside the View or it's viewport rectangle.

Throws:

java.lang.IllegalArgumentException - if either the the Frustum or the viewport are null.

computeCenterPoint

protected Vec4 computeCenterPoint(Globe globe,
                                  double verticalExaggeration,
                                  java.lang.Iterable<? extends Extent> modelExtents,
                                  java.lang.Iterable<? extends ExtentVisibilitySupport.ScreenExtent> screenExtents)

computeEyePoint

protected Vec4 computeEyePoint(Vec4 eye,
                               Vec4 center,
                               Vec4 up,
                               Angle fieldOfView,
                               java.awt.Rectangle viewport,
                               double nearClipDistance,
                               double farClipDistance,
                               java.lang.Iterable<? extends Extent> modelExtents,
                               java.lang.Iterable<? extends ExtentVisibilitySupport.ScreenExtent> screenExtents)

computeEyePointForModelExtents

protected Vec4 computeEyePointForModelExtents(Vec4 eye,
                                              Vec4 center,
                                              Vec4 up,
                                              Angle fieldOfView,
                                              java.awt.Rectangle viewport,
                                              java.lang.Iterable<? extends Extent> modelExtents)

computeEyePointForScreenBounds

protected Vec4 computeEyePointForScreenBounds(Vec4 eye,
                                              Vec4 center,
                                              Vec4 up,
                                              Angle fieldOfView,
                                              java.awt.Rectangle viewport,
                                              double nearClipDistance,
                                              double farClipDistance,
                                              java.lang.Iterable<? extends ExtentVisibilitySupport.ScreenExtent> screenExtents)

computeEyePointForScreenExtents

protected Vec4 computeEyePointForScreenExtents(Vec4 eye,
                                               Vec4 center,
                                               Vec4 up,
                                               Angle fieldOfView,
                                               java.awt.Rectangle viewport,
                                               double nearClipDistance,
                                               double farClipDistance,
                                               java.lang.Iterable<? extends ExtentVisibilitySupport.ScreenExtent> screenExtents)

computeEyePointForScreenReferencePoints

protected Vec4 computeEyePointForScreenReferencePoints(Vec4 eye,
                                                       Vec4 center,
                                                       Vec4 up,
                                                       Angle fieldOfView,
                                                       java.awt.Rectangle viewport,
                                                       java.lang.Iterable<? extends ExtentVisibilitySupport.ScreenExtent> screenExtents)

computeViewLookAtContainingExtents

public Vec4[] computeViewLookAtContainingExtents(Globe globe,
                                                 double verticalExaggeration,
                                                 Vec4 eyePoint,
                                                 Vec4 centerPoint,
                                                 Vec4 upVector,
                                                 Angle fieldOfView,
                                                 java.awt.Rectangle viewport,
                                                 double nearClipDistance,
                                                 double farClipDistance)

Returns an array of View look-at vectors optimal for viewing the the scene elements, or null if this has no scene elements. The returned look-at vectors define a new viewing coordinate system as follows: The vector at index 0 defines the eye point, the vector at index 1 defines the reference center point, and the value at index 2 defines the up vector.

The specified eye point, reference center point, and up vector define the input view coordinate system, and the returned view coordinates preserve the input view coordinates' orientation relative to the specified Globe. The field-of-view, viewport and clip distances define the input view projection parameters, and are used to compute the optimal look-at vectors to view the scene elements.

Parameters:

globe - the Globe the scene elements are related to.

verticalExaggeration - the vertical exaggeration of the scene.

eyePoint - the current eye point, in model coordinates.

centerPoint - the scene's current reference center point, in model coordinates.

upVector - the current direction of the up vector, in model coordinates.

fieldOfView - the horizontal field of view.

viewport - the viewport bounds, in window coordinates (screen pixels).

nearClipDistance - the near clipping plane distance, in model coordinates.

farClipDistance - the far clipping plane distance, in model coordinates.

Returns:

an array of View look-at vectors optimal for viewing the scene elements, or null if this has no scene elements.

Throws:

java.lang.IllegalArgumentException - if any of the globe, eyePoint, centerPoint, upVector, field-of-view, or viewport are null, if if the eye point and reference center point are coincident, if the up vector and the line of sight are parallel, or if any of the view projection parameters are out-of-range.

computeViewLookAtContainingExtents

public Vec4[] computeViewLookAtContainingExtents(Globe globe,
                                                 double verticalExaggeration,
                                                 View view)

Returns an array of View look-at vectors optimal for viewing the the scene elements, or null if this has no scene elements. The returned look-at vectors define a new viewing coordinate system as follows: The vector at index 0 defines the eye point, the vector at index 1 defines the reference center point, and the value at index 2 defines the up vector.

The specified View defines both the input view coordinate system, and the input view projection parameters. The returned view coordinates preserve the input view's orientation relative to the specified Globe, and are optimal for the View's projection parameters.

Parameters:

globe - the Globe the scene elements are related to.

verticalExaggeration - the vertical exaggeration of the scene.

view - the View defining the import view coordinate system and view projection parameters.

Returns:

an array of View look-at vectors optimal for viewing the scene elements, or null if this has no scene elements.

Throws:

java.lang.IllegalArgumentException - if either the globe or view are null.

extentsFromExtentHolders

public static java.lang.Iterable<Extent> extentsFromExtentHolders(java.lang.Iterable<? extends ExtentHolder> extentHolders,
                                                                  Globe globe,
                                                                  double verticalExaggeration)

Converts the specified Iterable of ExtentHolder references to a new Iterable of Extent references. The new Extents are constructed from the specified ExtentHolders by invoking ExtentHolder.getExtent(gov.nasa.worldwind.globes.Globe, double) with the specified Globe and vertical exaggeration. This ignores any null ExtentHolders in the specified Iterable, and any null Extents returned by the ExtentHolders. This returns null if the Iterable is null or empty.

Parameters:

extentHolders - Iterable of ExtentHolders used to construct the new Extents.

globe - the Globe used to construct the Extents.

verticalExaggeration - the vertical exaggeration used to construct the new Extents.

Returns:

a new Iterable of Extents constructed from the specified ExtentHolder, Globe, and vertical exaggeration.

getExtents

public java.lang.Iterable<? extends Extent> getExtents()

Returns this ExtentVisibilitySupport's Iterable of Extents.

Returns:

the Iterable of Extents this ExtentVisibilitySupport operates on, or null if none exists.

getScreenExtents

public java.lang.Iterable<? extends ExtentVisibilitySupport.ScreenExtent> getScreenExtents()

Returns this ExtentVisibilitySupport's Iterable of ScreenExtents.

Returns:

the Iterable of ScreenExtents this ExtentVisibilitySupport operates on, or null if none exists.

setExtents

public void setExtents(java.lang.Iterable<? extends Extent> extents)

Sets this ExtentVisibilitySupport's Iterable of Extents.

Parameters:

extents - the Iterable of Extents defining this ExtentVisibilitySupport's model coordinate scene elements. This iterable can be null, indicating that this ExtentVisibilitySupport has no model coordinate scene.

setScreenExtents

public void setScreenExtents(java.lang.Iterable<? extends ExtentVisibilitySupport.ScreenExtent> screenExtents)

Sets this ExtentVisibilitySupport's Iterable of ScreenExtents.

Parameters:

screenExtents - the Iterable of ScreenExtents defining this ExtentVisibilitySupport's screen coordinate scene elements. This iterable can be null, indicating that this ExtentVisibilitySupport has no screen coordinate scene.

translateScreenExtents

protected java.lang.Iterable<ExtentVisibilitySupport.ScreenExtent> translateScreenExtents(java.lang.Iterable<? extends ExtentVisibilitySupport.ScreenExtent> screenExtents,
                                                                                          Matrix oldModelview,
                                                                                          Matrix newModelview,
                                                                                          Matrix projection,
                                                                                          java.awt.Rectangle viewport)

validate

protected java.lang.String validate(Vec4 eye,
                                    Vec4 center,
                                    Vec4 up,
                                    Angle fieldOfView,
                                    java.awt.Rectangle viewport,
                                    double nearClipDistance,
                                    double farClipDistance)