Package com.luciad.earth.tileset

Interface ILcdEarthTileSet

All Superinterfaces:
AutoCloseable, ILcdBounded, ILcdDisposable
All Known Subinterfaces:
ILcdEarthEditableTileSet, ILcdEarthIterableTileSet
All Known Implementing Classes:
ALcdEarthCoverageFilterTileSet, ALcdEarthTileSet, ALcdEarthTileSetMultilevelRaster, ALcdEarthTileSetWrapper, TLcdEarthAssetGXYViewTileSet, TLcdEarthAssetTerrainElevationTileSet, TLcdEarthAsynchronousTileSet, TLcdEarthCompositeImageTileSet, TLcdEarthCompositeTileSet, TLcdEarthGXYViewTileSet, TLcdEarthLevelFallbackTileSet, TLcdEarthMemoryCachingTileSet, TLcdEarthMetadataTerrainTileSet, TLcdEarthMultiTileSet, TLcdEarthReadOnlyTileSet, TLcdEarthTerrainElevationTileSet, TLcdEarthTerrainHeightTileSet, TLcdEarthTexturedTerrainTileSet, TLcdEarthThreadSafeEditableTileSet, TLcdEarthThreadSafeTileSet, TLcdEarthTileRepository, TLcdEarthTileSetElevationMultilevelRaster, TLcdEarthTileSetMultilevelRaster
public interface ILcdEarthTileSet extends ILcdBounded, ILcdDisposable

Important notice: the package com.luciad.imaging presents a new API for the modeling of raster data. For new projects, it is recommended to use this API instead of ILcdEarthTileSet et al. Provides a tiled and multi-leveled view on some data set. Applications can use the tileset to extract a limited working set from the data, which they can then visualize or otherwise process. The contents of the tiles are not specified by this interface.

A tileset knows the underlying data's bounds and geo reference, as well as the number of levels and the number of tile rows and columns on each level. The structure of the tiles is expected to be as follows:

  • Level 0 is the least detailed and must have at least 1x1 tiles.
  • Each tile on level N corresponds to a block of 2x2 tiles on level N+1.
The bounds of the tileset are expressed in the model reference of the model that contains it. This reference is also referred to as the tileset reference or the model reference of the tileset.

The tileset interface allows:

  • Asynchronous loading: requested tiles are returned via a callback mechanism (see ILcdEarthTileSetCallback. Note that asynchronous production can be achieved via the wrapper class TLcdEarthAsynchronousTileSet, so that not all tilesets need to implement multi-threaded behaviour themselves.
  • Sparse storage: ILcdEarthTileSetCallback may also indicate that a tile is not available. In other words, although the tiles on each detail level form a regular grid, not all cells in this grid need to be populated. This allows for the creation of high resolution overlays on lower resolution data.
  • Minimal memory footprints: there is no explicit modeling of the tile hierarchy. Objects that represent tiles need only be instantiated when those tiles are actually requested, and are available for garbage collection as soon as the application stops referencing them.

A tileset may contain one or more "coverages" of data (ILcdEarthTileSetCoverage objects). All coverages within one tileset share the same tiling and multi-leveling layout. Coverages are used for two purposes:

  • To group different data sets that logically belong together in a single tileset (e.g. 3D terrain geometry and its corresponding textures).
  • To provide the same data in different exchange formats (e.g. 3D terrain in the form of triangle meshes or in the form of a 2D elevation raster).

It is often desired to retrieve tiles from multiple threads concurrently. For example when visualizing it in both a 2D and 3D view. It can however not generally be assumed that a tileset implementation is (completely) thread-safe. A common case is that the tileset can safely perform tile reading operations. This is referred to as thread-safe for tile reading and means that the following methods may be called concurrently:

Since:
8.2

  • Method Details

    • produceTile

      void produceTile(ILcdEarthTileSetCoverage aCoverage, int aLevel, long aTileX, long aTileY, ILcdGeoReference aGeoReference, TLcdEarthTileFormat aFormat, TLcdEarthTileOperationMode aMode, ILcdEarthTileSetCallback aCallback, Object aContext)
      Produces the requested tile, and invoke the supplied callback when done. The resulting tile is passed to the call back's tileAvailable() method. If the tile cannot be produced for some reason, the method tileNotAvailable() should be called instead.

      If the tileset supports it and aMode is TLcdEarthTileOperationMode.PREFER_ASYNCHRONOUS, the tile request may be executed asynchronously. However, the callback must be invoked at some point in time, unless the cancelTile() method is used to cancel the tile request before it is executed. If aMode is TLcdEarthTileOperationMode.FORCE_SYNCHRONOUS, the request must be executed synchronously and the callback must be invoked before produceTile() returns.

      Tiles may be requested in reference systems other than the native geo reference of the underlying data, provided that the isGeoReferenceSupported() method returns true for the requested reference. If this is not the case, the tileset should call tileNotAvailable(). If the tileset calls tileAvailable(), the geo reference of the resulting tile must be equal to aGeoReference, and the tile's bounds must likewise be expressed in this reference.

      Similarly, tiles may be requested in different data formats, as described by TLcdEarthTileFormat. The format determines the type of the data object that will be contained in the requested tile. To check if a format is supported, use isFormatSupported(). If the specified format is not supported, the tileset should call tileNotAvailable().

      The context parameter may be used to pass application-specific data into the tileset. If it is not needed, its value may be null.

      Parameters:
      aCoverage - the coverage from which the tile is requested
      aLevel - the level from which the tile is requested
      aTileX - the column index of the requested tile
      aTileY - the row index of the requested tile
      aGeoReference - the reference system in which the tile should be returned
      aFormat - the desired format of the tile's data
      aMode - controls the synchronous or asynchronous behaviour of the tileset
      aCallback - will be invoked when the tile is available to be used
      aContext - application-specific data to be used by the tileset, if any

    • dispose

      void dispose()
      This method releases all resources held by the repository, such as file locks, threads or server connections.
      Specified by:
      dispose in interface ILcdDisposable

    • getBounds

      ILcdBounds getBounds()
      Returns the bounds of this tile set, expressed in the model reference of the model that contains this tile set.
      Specified by:
      getBounds in interface ILcdBounded
      Returns:
      the bounds of this tile set
      See Also:

    • getLevelCount

      int getLevelCount()
      Returns the number of available detail levels. Level 0 is the coarsest level.
      Returns:
      the number of available detail levels

    • getTileRowCount

      long getTileRowCount(int aLevel)
      Returns the number of rows in the tile grid at the given level. Each level should have twice the number of rows of the previous one.
      Parameters:
      aLevel - the level to be queried
      Returns:
      the number of tile rows on the specified level

    • getTileColumnCount

      long getTileColumnCount(int aLevel)
      Returns the number of columns in the tile grid at the given level. Each level should have twice the number of columns of the previous one.
      Parameters:
      aLevel - the level to be queried
      Returns:
      the number of tile columns on the specified level

    • getTileSetCoverageCount

      int getTileSetCoverageCount()
      Returns the number of coverages this tileset contains.
      Returns:
      the number of coverages this tileset contains

    • getTileSetCoverage

      ILcdEarthTileSetCoverage getTileSetCoverage(int aIndex)
      Returns the coverage at the specified index.
      Parameters:
      aIndex - the index of the coverage to return
      Returns:
      the requested ILcdEarthTileSetCoverage

    • containsTileSetCoverage

      boolean containsTileSetCoverage(String aCoverageName)
      Returns true if the repository contains a coverage with the specified name.
      Parameters:
      aCoverageName - the name of the coverage to look for
      Returns:
      true if the repository contains a coverage with the specified name, false otherwise

    • getTileSetCoverage

      ILcdEarthTileSetCoverage getTileSetCoverage(String aCoverageName)
      Returns the tileset coverage with the specified name.
      Parameters:
      aCoverageName - the name of the coverage to look for
      Returns:
      the tileset coverage with the specified name

    • updateTile

      void updateTile(ALcdEarthTile aTile, TLcdEarthTileOperationMode aMode, ILcdEarthTileSetCallback aCallback, Object aContext)
      Produces an updated version of the given tile, if necessary. Produces the same tile if the given tile is up to date.
      Parameters:
      aTile - tile to check
      aMode - controls the synchronous or asynchronous behaviour of the tileset
      aCallback - will be invoked when the tile is available to be used
      aContext - application-specific data to be used by the tileset, if any

    • updateTile

      ALcdEarthTile updateTile(ALcdEarthTile aEarthTile, Object aContext) throws IOException
      Returns an updated version of the specified tile.
      Parameters:
      aEarthTile - the tile to check
      aContext - application-specific data to be used by the tileset, if any
      Returns:
      the tile itself or a new, updated version
      Throws:
      IOException - if the tile cannot be updated

    • cancelTile

      void cancelTile(int aLevel, long aTileX, long aTileY, ILcdEarthTileSetCoverage aCoverage, ILcdGeoReference aGeoReference, TLcdEarthTileFormat aFormat, ILcdEarthTileSetCallback aCallback, Object aContext)
      Cancels any pending tile requests for the given parameters. This method is only meaningful in tilesets that support the asynchronous operation mode. If cancelTile() is called, the tileset is no longer required to invoke the ILcdEarthTileSetCallback for the tile in question. The tileset is not obligated to honor the cancelTile() request, but if cancelTile() is not called, then it is required to invoke the ILcdEarthTileSetCallback at some point.
      Parameters:
      aLevel - the level from which the tile is requested
      aTileX - the column index of the requested tile
      aTileY - the row index of the requested tile
      aCoverage - the coverage from which the tile is requested
      aGeoReference - the reference system in which the tile is requested
      aFormat - the format in which the tile is requested
      aCallback - would be invoked when the tile would have been available to be used
      aContext - application-specific data to be used by the tileset, if any

    • containsTile

      boolean containsTile(ILcdEarthTileSetCoverage aCoverage, int aLevel, long aX, long aY, Object aContext)
      Returns true if the repository contains the specified tile.
      Parameters:
      aCoverage - the coverage from which to query a tile
      aLevel - the detail level for which to query a tile
      aX - the column index at which to query a tile
      aY - the row index at which to query a tile
      aContext - application-specific data to be used by the tileset, if any
      Returns:
      true if the repository contains the requested tile

    • produceTile

      ALcdEarthTile produceTile(ILcdEarthTileSetCoverage aCoverage, int aLevel, long aX, long aY, ILcdGeoReference aGeoReference, TLcdEarthTileFormat aFormat, Object aContext) throws IOException
      Gets a tile from the repository.
      Parameters:
      aCoverage - the coverage from which to query a tile
      aLevel - the detail level for which to query a tile
      aX - the column index at which to query a tile
      aY - the row index at which to query a tile
      aGeoReference - the georeference of the requested tile
      aFormat - the format of the requested tile
      aContext - application-specific data to be used by the tileset, if any
      Returns:
      the requested tile, or null if the repository does not contain this tile
      Throws:
      IOException - if the tile cannot be produced

    • isGeoReferenceSupported

      boolean isGeoReferenceSupported(ILcdEarthTileSetCoverage aCoverage, ILcdGeoReference aGeoReference)
      Returns true if the tileset can produce tiles for the given coverage in the given reference system. Note that any reference other than the native reference may result in reduced performance.

      This method must always return true for the native reference of the coverage. If it returns true for any other georeference, then the tileset must be able to handle the georeference in question in its produceTile() method.

      Parameters:
      aCoverage - the coverage to check for
      aGeoReference - the reference to check for
      Returns:
      true if the given coverage can be queried with the given reference

    • isFormatSupported

      boolean isFormatSupported(ILcdEarthTileSetCoverage aCoverage, TLcdEarthTileFormat aFormat)
      Returns true if the tileset can produce tiles for the given coverage in the given format. Note that any format other than the native format may result in reduced performance.

      This method must always return true for the native format of the coverage. If it returns true for any other format, then the tileset must be able to handle the format in question in its produceTile() method.

      Parameters:
      aCoverage - the coverage to check for
      aFormat - the format to check for
      Returns:
      true if the given coverage can be queried with the given format