Package com.luciad.view.lightspeed.services.terrain

Interface ILspTerrainSupport

public interface ILspTerrainSupport
Adds 3D terrain support to an ILspView.

Each view automatically creates a terrain layer onto which terrain can be applied. This layer automatically incorporates elevation data from other layers to provide a consolidated terrain elevation model on which various other 2D data can be draped. If the terrain elevation is disabled, draping is performed on the surface of the ellipsoid of the view's world reference system.

The getDrapingContext and convertFromDrapingContext methods should be used by a painter that drapes certain objects to correctly implement methods such as the query method: 


 public boolean query( List<TLspPaintGroup> aPaintGroups, ALspPaintQuery<T> aQuery, TLspPaintRepresentationState aPaintRepresentationState, TLspContext aContext ) {
   if ( aQuery instanceof TLspIsTouchedQuery ) {
    // The terrain support can be retrieved from the view.
    ILspTerrainSupport drapingSupport = aContext.getView().getServices().getTerrainSupport();

    // Your painter should know which objects to drape.
    // This is typically known by querying the style for the given object.
    boolean terrain = isDraping(aObject);

    // In case the object is draped on terrain, convert the context to a proper context for terrain.
    if (terrain) {
       aContext = drapingSupport.getDrapingContext(aContext);
    }

    // Implement the isTouched query, now using the proper aContext.
    TLspWorldTouchInfo touchInfo = ...

    // If the object is draped on terrain, convert the resulting world point in the terrain
    // context to a world point in the regular context by including the elevation.
    // The terrain support provides a method for this.
    if (touchInfo != null && terrain) {
      TLcdXYZPoint convertedWorldPoint = new TLcdXYZPoint();
       drapingSupport.convertFromDrapingContextSFCT(touchInfo.getTouchedWorldPoint(), aContext, convertedWorldPoint);
      touchInfo = new TLspWorldTouchInfo(touchInfo.getDomainObject(), convertedWorldPoint, touchInfo.getElevationMode());
    }

    // Return the result
    return true;
   } else {
     // Handle other queries similarly
     ...
   }
 }

Since:
2012.0
See Also:

  • Method Details

    • getBackgroundStyler

      ILspStyler getBackgroundStyler()
      Returns the styler for the background layers.
      Returns:
      the background styler
      See Also:

    • setBackgroundStyler

      void setBackgroundStyler(ILspStyler aStyler)
      Sets the styler for the background layers.

      This styler will affect the style of all raster layers with layer type ILspLayer.LayerType.BACKGROUND that are at the bottom of the view (that is there is no non non-background or non-raster layers below these layers).

      Changing the background styler is typically more efficient than changing the styles of the individual background raster layers.

      The specified styler can submit:

      Parameters:
      aStyler - a styler

    • isElevationEnabled

      boolean isElevationEnabled()
      Returns whether the elevation of the terrain is enabled.
      Returns:
      true if the elevation of the terrain is enabled
      See Also:

    • setElevationEnabled

      void setElevationEnabled(boolean aEnabled)
      Sets whether the elevation of the terrain is enabled.

      If the terrain elevation is disabled, draping is performed on the surface of the ellipsoid of the view's world reference system.

      The elevation is enabled by default.

      Parameters:
      aEnabled - true if the elevation of the terrain should be enabled
      See Also:

    • getViewDependentHeightProvider

      ILcdHeightProvider getViewDependentHeightProvider(ILcdGeoReference aGeoReference, boolean aValidHeightsOnly)
      Returns a height provider that computes heights based on the tiles that are currently loaded by the terrain painter associated with the terrain layer. The accuracy of the returned height will depend on the current view and painter settings, but will be consistent with what is shown in the view.

      An important advantage of the view-based height provider vs. model-based height provider is that the returned heights are the same as those visible in the view (e.g. WYSIWYG). This is for example important when you want to put an object on top of a 3D terrain or when you have a label that displays the height at the cursor position. Another important advantage is that using a view-based height provider typically results in significantly better performance than the model-based counterpart because all necessary tiles are already cached. This is especially important when the heights need to be retrieved while painting.

      A 3D terrain painter may still paint terrain at places where no height data is available. For example because there is still some imagery available at this location. In such a case a default height value is typically used for the terrain. This property indicates whether the height provider should use these invalid height values or not (e.g. return unknown height instead). A typical use case for still using these invalid heights is putting objects on top of the terrain: if there is only imagery you still want to put the object on top of it. On the other hand a UI component that shows the height at the mouse location would only use valid heights.

      Note that the returned heights do not take into account the altitude exaggeration of the view. If needed this has to be applied separately.

      Parameters:
      aGeoReference - the geographic reference of the height provider
      aValidHeightsOnly - true if only valid heights may be returned
      Returns:
      a height provider based on the terrain painter
      Throws:
      IllegalArgumentException - when aGeoReference is a 3D reference.
      See Also:

    • getModelHeightProvider

      ILcdHeightProvider getModelHeightProvider(ILcdGeoReference aGeoReference, double aPixelDensity)
      Returns a height provider based on the terrain contained in the terrain layer. The returned height data will be loaded from the model.

      The aPixelDensity parameter can be used to select a proper level of detail. This density is expressed in the specified geographic reference. When sampling the height at multiple points the pixel density should typically to match the distance between two samples: 1 / d^2, where d is the distance between two samples in the specified geographic reference.

      Parameters:
      aGeoReference - the geographic reference of the height provider
      aPixelDensity - the pixel density of the height data that should be used
      Returns:
      An elevation provider based on the terrain model.
      Throws:
      IllegalArgumentException - when aGeoReference is a 3D reference.
      See Also:

    • getElevationTileSet

      ILcdEarthTileSet getElevationTileSet()
      Returns a tileset with exactly one coverage containing the elevation data of the terrain.
      Returns:
      an earth tileset

    • getPointOnTerrain

      ILcdPoint getPointOnTerrain(ILcdPoint aViewPoint, TLspContext aContext)
      Gets the front-most point in world coordinates on the terrain. If no terrain is used (e.g. isDrapingOnTerrain() returns false), the intersection at zero elevation (i.e., with the ellipsoid or z=0 plane) is returned. If no intersection is found, null is returned.

      The implementation can use the level of detail of the terrain as currently shown in the view.

      The layer dependent attributes of the aContext argument are not relevant for this method.

      When used in 2D, the result will have a z-coordinate always equal to 0.

      Parameters:
      aViewPoint - a point in view coordinates
      aContext - the context for the point
      Returns:
      a point in world coordinates on the terrain (or the ellipsoid if there is no terrain) that is projected to the given view point's x,y coordinates, or null if no intersection is found.

    • intersectTerrain

      ILcdPoint intersectTerrain(ILcdPoint aWorldOrigin, ILcdPoint aWorldDestination, TLspContext aContext)
      Finds a point on the terrain that is the first intersection of the ray originating from the given origin and cast in the direction of the given destination (both defined in the view's world reference system). If no terrain is used (e.g. isDrapingOnTerrain() returns false), the intersection at zero elevation (i.e. with the ellipsoid or z=0 plane) is returned. If no intersection is found, null is returned.

      Note that the ray doesn't end at the passed destination.

      The layer dependent attributes of the aContext argument are not relevant for this method.

      Parameters:
      aWorldOrigin - the ray origin
      aWorldDestination - a point somewhere along the ray
      aContext - the context of the points
      Returns:
      the first intersection point of the ray with the terrain (or the ellipsoid if there is no terrain), or null if no intersection is found

    • intersectTerrain

      default ILcdPoint intersectTerrain(ILcdPoint aWorldOrigin, ILcdPoint aWorldDestination, boolean aForceUseTerrain, TLspContext aContext)
      Equivalent to intersectTerrain(ILcdPoint, ILcdPoint, TLspContext), but can also return intersections when the view is set to 2D. The aForceUseTerrain controls this behavior. When the value is false, this method behaves exactly like the one that does not have the extra boolean parameter. When it is true, this method will perform intersection tests with the 3D terrain regardless of the current state of the view.
      Parameters:
      aWorldOrigin - the ray origin
      aWorldDestination - a point somewhere along the ray
      aForceUseTerrain - set to true to produce 3D intersections even in a 2D view
      aContext - the context of the points
      Returns:
      the first intersection point of the ray with the terrain, or null if no intersection is found
      Since:
      2018.1

    • getDrapingContext

      TLspContext getDrapingContext(TLspContext aContext)
      Converts the given context to a context that should be used for objects to be draped.
      Parameters:
      aContext - the original context
      Returns:
      a context that can be used for objects to be draped

    • getViewPointForDraping

      ILcdPoint getViewPointForDraping(ILcdPoint aViewPoint, TLspContext aContext)
      Converts the given view space point to a point that should be used to check for interaction with objects in the draping view.
      Parameters:
      aViewPoint - the view point to convert
      aContext - the original context
      Returns:
      a view point that can be used to check for interaction in the draping view, or null if such a point does not exist

    • getViewBoundsForDraping

      ILcdBounds getViewBoundsForDraping(ILcdBounds aViewBounds, TLspContext aContext)
      Converts the given view space bounds to a bounds that should be used to check for interaction with objects in the draping view.
      Parameters:
      aViewBounds - the view bounds to convert
      aContext - the original context
      Returns:
      view bounds that can be used to check for interaction in the draping view.

    • getDrapingView

      ILspView getDrapingView()
      Returns the draping view used for objects that are draped.
      Returns:
      a view used for draped objects.

    • convertFromDrapingContextSFCT

      void convertFromDrapingContextSFCT(ILcdPoint aDrapingWorldPoint, TLspContext aContext, ILcd3DEditablePoint aWorldPointSFCT)
      Converts the given world point in the draping context back to the regular context. It basically uses the elevation provider to add the elevation to the provided world point.

      This method can for example be used in isTouched implementations for objects that are draped.

      The layer dependent attributes of the aContext argument are not relevant for this method.

      Note that the returned point does not take into account the altitude exaggeration of the view. If needed this has to be applied separately.

      Parameters:
      aDrapingWorldPoint - the point in world coordinates in the draping context
      aContext - the context
      aWorldPointSFCT - the world point in the regular context

    • addPropertyChangeListener

      void addPropertyChangeListener(PropertyChangeListener aListener)
      Adds the given listener to receive property change events.
      Parameters:
      aListener - the listener to be added

    • removePropertyChangeListener

      void removePropertyChangeListener(PropertyChangeListener aListener)
      Removes the given listener so that it stops receiving property change events.
      Parameters:
      aListener - the listener to remove

    • addTerrainChangeListener

      void addTerrainChangeListener(ILspTerrainChangeListener aListener)
      Adds the given listener to receive change events when the terrain that is painted in the view changes.

      This can be used to be notified when the results of the following methods may have changed:

      Parameters:
      aListener - the listener to be added

    • removeTerrainChangeListener

      void removeTerrainChangeListener(ILspTerrainChangeListener aListener)
      Removes the given listener so that it stops receiving terrain change events.
      Parameters:
      aListener - the listener to remove

    • isDrapingOnTerrain

      boolean isDrapingOnTerrain()
      Returns true only if the terrain is visible and contains data and if the view is configured as a 3D view.
      Returns:
      whether or not data is draped on the terrain.