Package com.luciad.format.raster

Class TLcdRasterModelDecoder

java.lang.Object
com.luciad.format.raster.TLcdRasterModelDecoder
All Implemented Interfaces:
ILcdInputStreamFactoryCapable, ILcdModelDecoder
@LcdService(service=ILcdModelDecoder.class, priority=20000) public class TLcdRasterModelDecoder extends Object implements ILcdModelDecoder, ILcdInputStreamFactoryCapable
This model decoder decodes rst files. An rst file is a java properties file that describes the structure and the spatial reference of a set of raster data. The actual raster data are contained in external files or URLs.

Raster data can be given at one or more levels of detail. Level 0 has the lowest resolution; subsequent levels have increasing resolutions. Users of the decoded models (e.g. painters) can pick a suitable level of detail based on the pixel density of each level (the number of pixels per unit area).

The location of a raster is specified by its bounds in model coordinates.

The contents of a raster is specified by a regular grid of one or more tiles. Each tile generally corresponds to one image file, which is specified in the rst file. Missing tiles may be left unspecified.

All tiles at a given level have equal sizes in model coordinates (except possibly for tiles in the right-most column or in the bottom-most row, which may be truncated). On the other hand, tiles may have different pixel sizes. For instance, tiles in a geodetic coordinate system have equal sizes in model coordinates, but they may have lower resolutions near the poles (like the 1x1 degree tiles in the DTED format).

For improving the efficiency of decoding and caching, tiles may be further subdivided into sub-tiles, typically corresponding to the tiling inside the image files.

Input files

File Required Entry point Description
*.rst x x Raster file containing the raster metadata: image file name(s), a model reference, and raster bounds
*.* x
Image file(s) containing the actual raster data

The decoder looks for the following properties when decoding an rst file. Each of the keys must be preceded by "TLcdRasterModelDecoder.".

General information that may be useful for applications:

  • displayName: a convenient name for the data, stored in the ILcdModelDescriptor of the decoded model.
  • typeName: the type of the data, stored in the ILcdModelDescriptor of the decoded model. For instance CADRG, jog, GeoTIFF,...
  • isElevation (default = false): a boolean flag that specifies whether the raster contains elevation data.

Information about the number of levels in a multi-level raster:

  • noLevels (default = 0): the number of raster levels. If 0 or 1, a single-level raster is constructed. If larger than 1, a multi-level raster is constructed.

For a multi-level raster, each of the properties below may be suffixed by '.i', with i referring to the level (0 <= i < noLevels). The properties can also be included without a suffix, in order to specify defaults for all levels.

Information needed to create rasters:

  • ILcdColorModelFactory.class (default = none): optionally, the name of a class that implements ILcdColorModelFactory. This factory must produce a ColorModel that is compatible with the given data. It is only required if the raster files themselves don't provide the desired color model.
  • pixelByteSize: the size of a pixel, expressed in bytes. This may be 1, 2, or 4.
  • defaultPixel (default = 0): the default color value or index that is assigned to pixels that don't have a value, e.g. pixels outside the raster bounds. This should typically be the transparent color or color index, so that missing pixels inside the raster and pixels outside the raster are transparent. The value may be prefixed by 0x to indicate a hexadecimal value.
  • forcedTransparentColorIndex (default = -1): the index of a color that should be made transparent in the models that will be decoded next. This can be useful if the image has an IndexColorModel that doesn't contain a transparent color of its own. The value may be prefixed by 0x to indicate a hexadecimal value.

Information about the position and size of the raster in model coordinates:

  • ulx: the abscissa of the upper-left corner of the raster, expressed in model coordinates.
  • uly: the ordinate of the upper-left corner of the raster, expressed in model coordinates.
  • rasterWidth: the width of the raster, expressed in model coordinates.
  • rasterHeight: the height of the raster, expressed in model coordinates.

Information about the tile structure of each raster.

  • noTileRows (default = 1): the number of tile rows per raster.
  • noTileColumns (default = 1): the number of tile columns per raster.
  • tileWidth: the width of one tile, expressed in model coordinates. The default is the raster width divided by the number of tile columns.
  • tileHeight: the height of one tile, expressed in model coordinates. The default is the raster height divided by the number of tile rows.
  • pixelDensity: the estimated number of pixels per unit area in this raster. Alternatively, one can specify the nominal size of the entire raster, expressed in pixels, by means of the properties rasterPixelWidth and rasterPixelHeight, or the size of a nominal tile, expressed in pixels, by means of the properties tilePixelWidth and tilePixelHeight. The decoder will then compute the pixel density. The pixel density is typically used to determine the right level of detail during display, without having to read the all the tiles.

Information needed to create the tiles of each raster. Each of these properties may be suffixed by '.r.c', with r referring to the row index and c referring to the column index within the raster (0 <= r < noTileRows and (0 <= c < noTileColumns). As before, each of these properties may be further suffixed by the level number. The properties can be included without either or both suffixes, in order to specify defaults for all tiles and/or levels.

  • ILcdTile.class: the name of the class that implements ILcdTile. The current implementation supports two types:
    • com.luciad.format.raster.TLcdBufferedTile (the default): the tile that decodes and caches rasters with the help of ILcdTileDecoder and ILcdBuffer.
    • com.luciad.format.raster.TLcdRenderedImageTile: the tile that decodes and caches rasters with the help of the Java Advanced Imaging library.
  • ILcdTileDecoder.class (default = none): the name of the class that implements ILcdTileDecoder and that can decode the actual raster files.
  • directoryPath (optional): the location of the image data. This string is prefixed to the file names, so it typically should contain a trailing slash or backslash. The path can be a file path or a URL. The default is the location of the rst file itself.
  • fileName: the relative file name of the image tile.
  • imageIndex (default = 0): the index of the image within the image file of the tile.
  • tilePixelWidth (optional): the width of one tile, expressed in pixels. The value may be required if it can't be read from the image file itself.
  • tilePixelHeight (optional): the width of one tile, expressed in pixels. The value may be required if it can't be read from the image file itself.
  • subTilePixelWidth (optional): the width of the sub-tiles of the tiles, expressed in pixels. The default is the width of the tiles.
  • subTilePixelHeight (optional): the height of the sub-tiles of the tiles, expressed in pixels. The default is the height of the tiles.

Model reference

Finally, an important set of properties specifies the appropriate ILcdModelReference. The model reference is the common to all tiles and, in the case of a multi-level raster, to all raster levels. The creation of the ILcdModelReference is delegated to the TLcdModelReferenceFactory. The starting point is a property that specifies the class:
  • ILcdModelReference.class: the fully qualified class name of the model reference.
Further properties then specify the parameters of the model reference. The selected ILcdModelReference determines which properties are required. For more information on what properties are needed, see the various implementations of ILcdModelReference.

The following excerpt of an rst file illustrates the creation of a TLcdGridReference based on a Transverse Mercator projection and the WGS84 geodetic datum. 


 TLcdRasterModelDecoder.ILcdModelReference.class = com.luciad.reference.TLcdGridReference
 TLcdRasterModelDecoder.TLcdGridReference.projection.ILcdProjection.class = com.luciad.projection.TLcdTransverseMercator
 TLcdRasterModelDecoder.TLcdGridReference.projection.TLcdTransverseMercator.centralMeridian =-75.0
 TLcdRasterModelDecoder.TLcdGridReference.falseEasting = 500000
 TLcdRasterModelDecoder.TLcdGridReference.falseNorthing = 0.0
 TLcdRasterModelDecoder.TLcdGridReference.scale = 0.9996
 TLcdRasterModelDecoder.TLcdGridReference.unitOfMeasure = 1
 TLcdRasterModelDecoder.TLcdGridReference.geodeticDatum.ILcdGeodeticDatumFactory.class
      = com.luciad.geodesy.TLcdJPLGeodeticDatumFactory
 TLcdRasterModelDecoder.TLcdGridReference.geodeticDatum.TLcdJPLGeodeticDatumFactory = WGS\ 84
Note that the TLcdModelReferenceFactory may call on other factories to which it will pass on the properties, so that those factories may look for the information that they require. The class ILcdGeodeticDatumFactory, in previous illustration, is such a factory.

Supported file transfer protocols

  • This model decoder supports all transfer protocols that are supported by the InputStreamFactory of this decoder.

Model structure

  • This model decoder creates a model per raster file.
  • All models returned by this model decoder implement ILcd2DBoundsIndexedModel.

Model descriptor

Model elements

  • Each decoded model contains a single element that implements ALcdImage (and either ILcdRaster or ILcdMultilevelRaster)).

Useful settings

  • The properties colorModel, defaultValue, forcedTransparentColorIndex, and expandColorMap provide some control over the color models that are attached to the decoded rasters, if the color models of the images aren't quite suitable.

Sample code


 ILcdModelDecoder decoder = new TLcdRasterModelDecoder();

 ILcdModel model = decoder.decode("raster.rst");

Performance tips

  • The decoder makes use of a shared buffer that can provide buffer segments. These are essentially byte arrays that are used for decoding and caching the actual raster data. Depending on the implementation of the shared buffer, buffer segments may be allocated in a buffer with a fixed size, which is then managed as a cache (see TLcdBuffer), or they may be allocated whenever required and managed using soft references (see TLcdConcurrentBuffer).
  • The decoder supports tiled images. Tiled images can greatly improve access times and reduce memory usage, since only the required parts of the images are decoded and cached.
  • The decoder also supports raster files containing multiple images at different resolutions. The first image is assumed to be a thumbnail at the lowest resolution; any subsequent images are at increasing resolutions. These precomputed levels of detail can greatly improve raster painting performance and quality of the image rendering when zoomed out.

Thread safety

  • The decoding of models is thread-safe, as long as no properties are changed during the decoding.
  • The decoded models are thread-safe for read access.

Known limitations

  • The rst format is closely tied to the LuciadLightspeed library.

  • Field Details

  • Constructor Details

    • TLcdRasterModelDecoder

      public TLcdRasterModelDecoder()
      Creates a new TLcdRasterModelDecoder, with a globally shared buffer for caching tiles.
      See Also:

    • TLcdRasterModelDecoder

      public TLcdRasterModelDecoder(ILcdBuffer aBuffer)
      Creates a new TLcdRasterModelDecoder.
      Parameters:
      aBuffer - the buffer into which the raster values can be decoded.

  • Method Details

    • setBuffer

      public void setBuffer(ILcdBuffer aBuffer)
      Should be used when this class was constructed from within COM or with the default constructor.

    • setInputStreamFactory

      public void setInputStreamFactory(ILcdInputStreamFactory aInputStreamFactory)
      Sets the factory that will create the input streams. This factory will only be set on tile decoders which are ILcdInputStreamFactoryCapable.
      Specified by:
      setInputStreamFactory in interface ILcdInputStreamFactoryCapable
      Parameters:
      aInputStreamFactory - the input stream factory to be used.

    • getInputStreamFactory

      public ILcdInputStreamFactory getInputStreamFactory()
      Description copied from interface: ILcdInputStreamFactoryCapable
      Returns the input stream factory that is used.
      Specified by:
      getInputStreamFactory in interface ILcdInputStreamFactoryCapable
      Returns:
      the input stream factory that is used.

    • getDisplayName

      public String getDisplayName()
      Description copied from interface: ILcdModelDecoder
      Returns a short, displayable name for the format that is decoded by this ILcdModelDecoder.
      Specified by:
      getDisplayName in interface ILcdModelDecoder
      Returns:
      the displayable name of this ILcdModelDecoder.

    • canDecodeSource

      public boolean canDecodeSource(String aSourceName)
      Checks whether this class can decode the given data. The extension of the file name should be "rst".
      Specified by:
      canDecodeSource in interface ILcdModelDecoder
      Parameters:
      aSourceName - the name of the file or URL that is to be decoded.
      Returns:
      true if the data specified by the source name can be decoded, false otherwise.
      See Also:

    • decode

      public ILcdModel decode(String aSourceName) throws IOException
      Description copied from interface: ILcdModelDecoder
      Creates a new model from the given data source.
      Specified by:
      decode in interface ILcdModelDecoder
      Parameters:
      aSourceName - the data source to be decoded; typically a file name or a URL.
      Returns:
      A model containing the decoded data. While null is allowed, implementors are advised to throw an error instead.
      Throws:
      IOException - for any exceptions caused by IO problems or invalid data. Since decoding invalid data almost always results in RunTimeExceptions (NullPointerException, IndexOutOfBoundsException, IllegalArgumentException, ...) on unexpected places, implementations are advised to catch RuntimeExceptions in their decode() method, and wrap them into an IOException, as illustrated in the code snippet below. 
      
   public ILcdModel decode( String aSourceName ) throws IOException {
      try (InputStream input = fInputStreamFactory.createInputStream(aSourceName)) {
         // Perform decoding ...
      } catch (RuntimeException e) {
         throw new IOException(e);
      }
   }
      See Also: