com.luciad.view.lightspeed.services.terrain

LuciadLightspeedInterface 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:

ILspView.getServices(), TLspViewServices.getTerrainSupport()

Method Summary

Modifier and Type	Method and Description
void	addPropertyChangeListener(PropertyChangeListener aListener) Adds the given listener to receive property change events.
void	addTerrainChangeListener(ILspTerrainChangeListener aListener) Adds the given listener to receive change events when the terrain that is painted in the view changes.
void	convertFromDrapingContextSFCT(ILcdPoint aDrapingWorldPoint, TLspContext aContext, ILcd3DEditablePoint aWorldPointSFCT) Converts the given world point in the draping context back to the regular context.
ILspStyler	getBackgroundStyler() Returns the styler for the background layers.
TLspContext	getDrapingContext(TLspContext aContext) Converts the given context to a context that should be used for objects to be draped.
ILspView	getDrapingView() Returns the draping view used for objects that are draped.
ILcdEarthTileSet	getElevationTileSet() Returns a tileset with exactly one coverage containing the elevation data of the terrain.
ILcdHeightProvider	getModelHeightProvider(ILcdGeoReference aGeoReference, double aPixelDensity) Returns a height provider based on the terrain contained in the terrain layer.
ILcdPoint	getPointOnTerrain(ILcdPoint aViewPoint, TLspContext aContext) Gets the front-most point in world coordinates on the terrain.
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.
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.
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.
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.
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).
boolean	isDrapingOnTerrain() Returns true only if the terrain is visible and contains data and if the view is configured as a 3D view.
boolean	isElevationEnabled() Returns whether the elevation of the terrain is enabled.
void	removePropertyChangeListener(PropertyChangeListener aListener) Removes the given listener so that it stops receiving property change events.
void	removeTerrainChangeListener(ILspTerrainChangeListener aListener) Removes the given listener so that it stops receiving terrain change events.
void	setBackgroundStyler(ILspStyler aStyler) Sets the styler for the background layers.
void	setElevationEnabled(boolean aEnabled) Sets whether the elevation of the terrain is enabled.

Method Detail

getBackgroundStyler

ILspStyler getBackgroundStyler()

Returns the styler for the background layers.

Returns:

the background styler

See Also:

setBackgroundStyler(com.luciad.view.lightspeed.style.styler.ILspStyler)

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 then changing the styles of the individual background raster layers.

The specified styler can submit:

• a TLspRasterStyle instance: mandatory, this controls the style of the raster values
• a TLspImageProcessingStyle instance: a image processing operator chain applied to the raster

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(boolean)

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:

setElevationEnabled(boolean)

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:

ILcdHeightProvider

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:

ILcdHeightProvider

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:

• getViewDependentHeightProvider(com.luciad.reference.ILcdGeoReference, boolean)
• getPointOnTerrain(com.luciad.shape.ILcdPoint, com.luciad.view.lightspeed.TLspContext) if isDrapingOnTerrain() is true

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.