The com.luciad.util.height package contains general interfaces and implementations to retrieve heights from elevation rasters or other data. The two interfaces are:

Using an ILcdHeightProvider

The interface ILcdHeightProvider provides height values for 2D points inside known bounds. The spatial reference of the points, of the bounds, and of the resulting elevation is determined by the implementation of this interface. When no data is found at a certain point, the returned height value is NaN.

Standard implementations of ILcdHeightProvider

The height package contains six standard ILcdHeightProvider implementations:

  • TLcdFixedHeightProvider: returns a constant height for any given point. The bounds are not taken into account.

  • TLcdImageHeightProvider: retrieves height values from a given image.

  • TLcdRasterHeightProvider: retrieves height values from a given raster. A similar implementation is TLcdInterpolatingRasterHeightProvider. The latter also retrieves height values from a given raster, but uses interpolation between height values to obtain a smoother result.

  • TLcdTransformedHeightProvider: retrieves height values from another height provider with a different reference.

  • TLcdCompositeHeightProvider: combines a list of height providers. All height providers must have the same reference as the composite height provider. When height providers have overlapping bounds, the first height provider that returns a valid height prevails.

Typical usage of an ILcdHeightProvider

In most cases, two or more height providers are combined into one height provider. Figure 1, “A height provider composed of multiple height providers” shows an example of such a height provider.

height provider example
Figure 1. A height provider composed of multiple height providers

When you are querying a height, the 2D point should be defined in reference 1. The point is then transformed to reference 2 and passed to the composite height provider. This height provider first tries to retrieve a height from the first raster height provider. When NaN is returned, it tries to retrieve a height from the next transformed height provider. When this height provider returns NaN, a fixed value is returned from the fixed height provider.

Creating an ILcdHeightProvider

Use the ILcdModelHeightProviderFactory interface to create an ILcdHeightProvider instance from a model. The ILcdModelHeightProviderFactory interface has four standard implementations:

Using properties

When using an ILcdModelHeightProviderFactory to create an ILcdHeightProvider, you can use properties to provide additional arguments. You can classify properties as required or optional:

  • Required: when you want to make sure that this property is actually used. When this property is not used during the creation of an ILcdHeightProvider, a TLcdUnsupportedPropertyException must be thrown. When you are implementing an ILcdModelHeightProviderFactory, make sure that required properties are removed when they are used, and that the list of required properties is verified when a height provider is created.

  • Optional: when it is not necessary to use this property.

When implementing an ILcdModelHeightProviderFactory, you can also classify properties as follows:

  • Necessary: the implementation needs this property to work correctly. When a necessary property is not provided, a TLcdMissingPropertyException must be thrown.

  • Not necessary: the implementation does not need this property to work correctly.

These properties are frequently used:

  • ALcdModelHeightProviderFactory.KEY_GEO_REFERENCE: ALcdModelHeightProviderFactory uses this key as a necessary property. The given reference is used as the reference of the height provider. This means that the given 2D points, the bounds, and the returned height are expressed in function of this reference.

  • ALcdRasterModelHeightProviderFactory.KEY_PIXEL_DENSITY: This property represents a desired pixel density. The implementations use this property to select an image or raster with a similar pixel density from multilevel data. The pixel density should be expressed in function of the given KEY_GEO_REFERENCE property. If this property is not provided, or set to Double.NaN, the most detailed level is chosen.

  • ALcdRasterModelHeightProviderFactory.KEY_INTERPOLATE_DATA: This property is used to indicate whether the data should be interpolated.

Program: Typical creation of an ILcdHeightProvider using an ILcdModelHeightProviderFactory shows the typical usage of an ILcdModelHeightProviderFactory.

Program: Typical creation of an ILcdHeightProvider using an ILcdModelHeightProviderFactory
// Create a height provider factory.
ILcdModelHeightProviderFactory factory = new TLcdRasterModelHeightProviderFactory();

try {
  // Specify the desired properties for the height provider.
  Map<String, Object> requiredProperties = new HashMap<>();
  ILcdGeoReference geoReference = new TLcdGeodeticReference();
  requiredProperties.put(ALcdModelHeightProviderFactory.KEY_GEO_REFERENCE, geoReference);

  Map<String, Object> optionalProperties = new HashMap<>();
  optionalProperties.put(TLcdRasterModelHeightProviderFactory.KEY_INTERPOLATE_DATA, true);

  // Create a height provider from a raster model.
  ILcdHeightProvider heightProvider =
      factory.createHeightProvider(aModel, requiredProperties, optionalProperties);

  // Retrieve height values.
  double height = heightProvider.retrieveHeightAt(new TLcdLonLatPoint(10.0, 20.0));

} catch (TLcdMissingPropertyException ex) {
  // A necessary property is missing : see ex.getMissingPropertyName()
  // ...
} catch (TLcdUnsupportedPropertyException ex) {
  // A required property was not used during the creation of the height provider :
  // see ex.getUnsupportedProperties()
  // ...
}

Retrieving heights for an entire view

A special instance of ILcdHeightProvider is TLcdViewHeightProvider. This height provider uses a view and an ILcdModelHeightProviderFactory. It uses the view to retrieve a list of models. After that, it uses the height provider factory internally to create a height provider. When layers are added or removed from the view, or made visible or invisible, the height provider updates itself. Program: Typical creation of a TLcdViewHeightProvider shows how to create a TLcdViewHeightProvider.

Program: Typical creation of a TLcdViewHeightProvider (from samples/gxy/height/MainPanel) 
/*
 * Create a height provider using the entire view as height source.
 */
private ILcdHeightProvider createHeightProvider() {
  ILcdModelHeightProviderFactory factory = new TLcdImageModelHeightProviderFactory();

  Map<String, Object> requiredProperties = new HashMap<String, Object>();
  Map<String, Object> optionalProperties = new HashMap<String, Object>();
  requiredProperties.put(ILcdModelHeightProviderFactory.KEY_GEO_REFERENCE,
                         fGeoReference);

  return new TLcdViewHeightProvider<ILcdGXYView>(getView(),
                                                 factory,
                                                 requiredProperties,
                                                 optionalProperties);
}