Package gov.nasa.worldwindx.examples.util

Class 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

    • Constructor Detail

      • ExtentVisibilitySupport

        public ExtentVisibilitySupport()
        Constructs a new ExtentVisibilitySupport, but otherwise does nothing.

    • Method Detail

      • 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.

      • 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.

      • 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.

      • 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.

      • 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.

      • 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.

      • validate

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

      • 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)

      • 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)

      • 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)