Package com.luciad.format.raster

Class TLcdGeoTIFFModelDecoder

java.lang.Object
com.luciad.format.raster.TLcdGeoTIFFModelDecoder
All Implemented Interfaces:
ILcdInputStreamFactoryCapable, ILcdModelDecoder
@LcdService(service=ILcdModelDecoder.class, priority=20000) public class TLcdGeoTIFFModelDecoder extends Object implements ILcdModelDecoder, ILcdInputStreamFactoryCapable
This model decoder decodes GeoTIFF files, or more generally, georeferenced TIFF files.

Input files

File Required Entry point Description
*.tif
*.tiff		 x x GeoTIFF/TIFF file containing the raster data and possibly specifying a model reference and raster bounds
*.tab

TAB file specifying a model reference and raster bounds
*.tfw

TIFF World file specifying raster bounds

If none of the files specify a model reference, the model reference is obtained from an ILcdModelReferenceDecoder. The default reference decoder set on this model decoder is based on all model reference decoders annotated with the LcdService annotation, and can handle

If this fails, the decoder's default model reference is returned. Unless set by the user, the default model reference is null.

If none of the files specify raster bounds, it is retrieved from the bounds property of this decoder.

You can find all details about reference decoding in the model reference section below.

Supported file transfer protocols

  • This model decoder supports all transfer protocols that are supported by the inputStreamFactory of this decoder. The input stream factory must produce a SeekableStream or ImageInputStream for the image file.

Model structure

  • This model decoder creates a model per GeoTIFF file or georeferenced TIFF file.
  • All models returned by this model decoder implement ILcd2DBoundsIndexedModel.

Model descriptor

The decoder uses a heuristic when to indicate data is considered as elevation data. Data is marked as elevation when the data consists of a single band with signed shorts or floats as values.

Model reference

  • All models returned by this model decoder have instances of ILcdGeodeticReference or ILcdGridReference as model references.
  • The reference is decoded using the following methods (tried in this order):
    1. the GeoTIFF tags in the .tif file
    2. the corresponding TAB file
    3. the ModelReferenceDecoder (the default supports WKT (*.prj), REF (*.ref), and EPSG (*.epsg)); note that this only specifies the coordinate reference so you need another source for the bounds (ex. TFW file)
    4. the default ModelReference
    5. the corresponding TFW file; note that this only specifies the bounds so you need another source for the coordinate reference (ex. ModelReferenceDecoder)
    6. the default Bounds; note that if this is used then the default ModelReference is also used (if set)
  • By default, if the GeoTIFF tags specify a supported vertical coordinate system, the model reference will have a geoid datum like EGM84, EGM96, NGVD27, or NAVD88. This is mostly relevant for GeoTIFF files containing elevation data. If supportGeoidDatums is set to false, a less accurate ellipsoidal geodetic datum like WGS84 will be created (regardless of whether or not the GeoTIFF tags specify a supported vertical coordinate system).

Model reference decoder priority

A model reference decoder priority for TLcdGeoTIFFModelDecoder can be set to change the order in which an ILcdModelReference is decoded by setting the system property com.luciad.format.raster.TLcdGeoTIFFModelDecoder.referenceDecoderPriority to one of these priority values.

Priority Explanation
EMBEDDED_FIRST The model reference decoding is first attempted from the reference information embedded in the data file (.tif/tiff). If that fails, the model reference decoding is tried from external reference source files such as WKT (.prj), REF (.ref) and EPSG (*.epsg).
EXTERNAL_FIRST The model reference decoding is first attempted from external reference source files such as WKT (.prj), REF (.ref) and EPSG (*.epsg). If that fails, the model reference decoding is tried from the reference information embedded in the data file (.tif/tiff).
By default, the priority is set to use EMBEDDED_FIRST.
This configuration can be useful in scenarios where the model reference embedded in the data file (.tif/.tiff) might be incorrect or incomplete. You can fix it by placing an external reference file next to the data file, and setting the system property com.luciad.format.raster.TLcdGeoTIFFModelDecoder.referenceDecoderPriority to EXTERNAL_FIRST.

Model elements

  • Each decoded model contains a single element that implements ALcdImage (and either ILcdRaster or ILcdMultilevelRaster)).
  • The model elements also implement ILcdDisposable. Disposing an element will release all associated resources (ex. open files) immediately, afterwards it must not be used anymore. Elements that are not disposed explicitly rely on the garbage collector to handle this.
  • Elevation data in the model can either be area- or point-sampled, as indicated by GeoTIFF tag GTRasterTypeGeoKey (1025). The sampling nature of the data is only exposed through the image API. The legacy ILcdRaster API assumes area-sampled.

Useful settings

  • If the raster location is specified by means of tie points, the properties minimumTiePointCount, allowOrthographicReferencing, and maximumResidualTiePointError provide some control over the model reference system that is created and the minimal accuracy that is required. Alternatively, the property rasterReferencer provides a means to completely control the way in which the raster model reference and bounds are created.
  • 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. Notably, 16-bits gray-scale images or elevation rasters don't have a color map, so you should provide a suitable IndexColorModel if the raster is to be painted.

Sample code


 ILcdModelDecoder decoder =
   new TLcdGeoTIFFModelDecoder();

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

Performance tips

  • The decoder supports tiled images. Tiling 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 TIFF files containing multiple images at different resolutions. The first image is assumed to be at the highest resolution; any subsequent images are thumbnails at decreasing resolutions. These precomputed levels of detail can greatly improve raster painting performance and quality of the image rendering when zoomed out.
  • If the TIFF file only contains a single image, it is still possible to compute and cache lower resolution images on the fly, by means of the properties levelCount and levelScaleFactor. Although there is an obvious overhead compared to the precomputed levels of detail, this technique still provides better raster painting performance when zoomed out.
  • For large rasters, precomputing and storing multiple levels of detail may speed up visualization and some computations. For instance, the TLcdGeoTIFFModelEncoder can create compressed and tiled multilevel GeoTIFF files that can replace the original GeoTIFF files.
  • The implementation can read data from general URLs. However, if the source is not a local file, it is first copied to the local file system, because the decoder requires random access to read the tiles lazily. If opening a GeoTIFF seems slow, you should check if it is being copied locally in the temporary directory. You should then make sure that the source name is a local file name.
  • The current implementation sets up a global optimized cache for the Java Advanced Imaging library. If you want to disable this optimization, for example because you have your own cache implementation, you can set the Java system property optimize.jai.tile.cache to false when starting up the Java Virtual Machine. The command line then typically looks as follows: 
    
   java -Doptimize.jai.tile.cache=false ....

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.

Supported versions and specifications

  • GeoTIFF Format Specification, Revision 1.0, Specification Version 1.8.2 (Baseline GeoTIFF)
  • Tagged Image File Format, TIFF, Revision 6.0, Aldus Developers Desk, 3 June 1992 (Baseline TIFF, plus extensions: CCITT Bilevel Encodings, LZW Compression, Tiled Images, Associated Alpha Handling, JPEG Compression)
  • BigTIFF. An extension of the TIFF format that supports files larger than 4Gb. See the BigTIFF File Format Proposal for details

Known limitations

  • Some rare EPSG model references are not supported.
  • Decoding RGB rasters with a planar configuration is relatively slow in the current implementation. The stack trace that is printed out in the console originates from the Java Advanced Imaging library, which currently can't handle this type of images. The stack trace is harmless, since the decoding is delegated to the ImageIO library which can handle this type of images, albeit less efficiently.

  • Field Details

  • Constructor Details

    • TLcdGeoTIFFModelDecoder

      public TLcdGeoTIFFModelDecoder()
      Creates a new TLcdGeoTIFFModelDecoder.

    • TLcdGeoTIFFModelDecoder

      public TLcdGeoTIFFModelDecoder(ILcdModelReferenceDecoder aModelReferenceDecoder)
      Creates a new TLcdGeoTIFFModelDecoder with a model reference decoder.

    • TLcdGeoTIFFModelDecoder

      public TLcdGeoTIFFModelDecoder(ILcdModelReferenceDecoder aModelReferenceDecoder, int aDefaultValue)
      Creates a new TLcdGeoTIFFModelDecoder with a model reference decoder and a default value.

    • TLcdGeoTIFFModelDecoder

      public TLcdGeoTIFFModelDecoder(ILcdModelReference aDefaultModelReference)
      Creates a new TLcdGeoTIFFModelDecoder with a default model reference.

    • TLcdGeoTIFFModelDecoder

      public TLcdGeoTIFFModelDecoder(ILcdModelReference aDefaultModelReference, int aDefaultValue)
      Creates a new TLcdGeoTIFFModelDecoder with a default model reference and a default value.

    • TLcdGeoTIFFModelDecoder

      public TLcdGeoTIFFModelDecoder(ILcdModelReferenceDecoder aModelReferenceDecoder, ILcdModelReference aDefaultModelReference, int aDefaultValue)
      Creates a new TLcdGeoTIFFModelDecoder with a model reference decoder, a default model reference, and a default value.

  • Method Details

    • setClassTraceOn

      @Deprecated public static void setClassTraceOn(boolean aClassTraceOn)
      Deprecated.
      This method has been deprecated. It is recommended to use the standard Java logging framework directly.
      Enables tracing for all instances of this class. If the argument is true then all log messages are recorded, otherwise only the informative, warning and error messages are recorded.
      Parameters:
      aClassTraceOn - if true then all log messages are recorded, otherwise only the informative, warning and error messages are recorded.

    • setTraceOn

      @Deprecated public void setTraceOn(boolean aTraceOn)
      Deprecated.
      This method has been deprecated. It is recommended to use the standard Java logging framework directly.
      Enables tracing for this class instance. Calling this method with either true or false as argument automatically turns off tracing for all other class instances for which setTraceOn has not been called. If the argument is false then only the informative, warning and error log messages are recorded.
      Parameters:
      aTraceOn - if true then all log messages are recorded for this instance. If false, then only the informative, warning and error log messages are recorded.

    • isTraceOn

      @Deprecated public boolean isTraceOn()
      Deprecated.
      This method has been deprecated. It is recommended to use the standard Java logging framework directly.
      Returns true if tracing is enabled for this class.
      Returns:
      true if tracing is enabled for this class, false otherwise.

    • setModelReferenceDecoder

      public void setModelReferenceDecoder(ILcdModelReferenceDecoder aModelReferenceDecoder)
      Sets the model reference decoder that will be used for image files that don't specify model references.
      Parameters:
      aModelReferenceDecoder - the model reference decoder.

    • getModelReferenceDecoder

      public ILcdModelReferenceDecoder getModelReferenceDecoder()
      Returns the model reference decoder that is used for image files that don't specify model references. The default value supports WKT (*.prj), REF (*.ref), and EPSG (*.epsg).
      Returns:
      the model reference decoder used by this decoder
      See Also:

    • setDefaultModelReference

      public void setDefaultModelReference(ILcdModelReference aDefaultModelReference)
      Sets the default model reference to be assigned to decoded models of which the image files don't specify model references.
      Parameters:
      aDefaultModelReference - the default model reference.

    • getDefaultModelReference

      public ILcdModelReference getDefaultModelReference()
      Returns the default model reference that is assigned to decoded models whose image files don't specify model references.

    • isStrictMode

      public boolean isStrictMode()
      Determines if strict mode is enabled or not.
      Returns:
      true if strict mode is enabled; false otherwise
      See Also:

    • setStrictMode

      public void setStrictMode(boolean aStrictMode)
      Enables or disables strict decoding mode. When disabled the decoder will make a best effort to decode GeoTIFF files that contain corrupt or incomplete data. When enabled IO exceptions will be generated instead.

      Strict mode is disabled by default.

      Parameters:
      aStrictMode - true to enable strict mode; false to disable it

    • setBounds

      public void setBounds(ILcdBounds aBounds)
      Sets the default model bounds to be assigned to decoded models of which the image files don't specify bounds.
      Parameters:
      aBounds - the default model bounds.

    • getBounds

      public ILcdBounds getBounds()
      Sets the default model bounds that are assigned to decoded models of which the image files don't specify bounds.

    • setSupportGeoidDatums

      public void setSupportGeoidDatums(boolean aSupportGeoidDatums)
      Specifies whether the geodetic datums of the decoded GeoTIFF model references may be geoid datums (like EGM96), instead of the default ellipsoid datums (like WGS84). Geoids vary smoothly between -110m and +90m around the ellipsoid. Geoid datums are more accurate for elevation data, but they require more memory and more processing time when they are being used in transformation calculations.

    • isSupportGeoidDatums

      public boolean isSupportGeoidDatums()
      Returns whether the geodetic datums of the decoded GeoTIFF model references may be geoid datums.

      The default value is true, applying the vertical datum information if available.

    • setMinimumTiePointCount

      public void setMinimumTiePointCount(int aMinimumTiePointCount)
      Sets the minimum number of tie points required for positioning image files that provide tie points instead of scaling information or transformation matrices. The default is 4.

      A value of 3 can be used, if the assumption is made that 3 tie points always define an affine transformation (which is not strictly guaranteed by the GeoTIFF specifications).

      A value of 2 can be used, if the assumption is made that 2 tie points always define an affine transformation without rotation.

      Parameters:
      aMinimumTiePointCount - the minimum number of tie points.
      See Also:

    • getMinimumTiePointCount

      public int getMinimumTiePointCount()
      Returns the minimum number of tie points required for positioning image files that provide tie points.

    • setAllowOrthographicReferencing

      public void setAllowOrthographicReferencing(boolean aAllowOrthographicReferencing)
      Specifies whether images that are positioned in geodetic references using tie points may be put in approximating orthographic grid references that are centered around the images. The default is true.

    • isAllowOrthographicReferencing

      public boolean isAllowOrthographicReferencing()
      Returns whether images that are positioned in geodetic references using tie points may be put in approximating orthographic grid references that are centered around the images.

    • setMaximumResidualTiePointError

      public void setMaximumResidualTiePointError(double aMaximumResidualTiePointError)
      Sets the maximum acceptable average residual error for tie points, when positioning image files that provide tie points instead of scaling information or transformation matrices.

      A raster is always positioned by means of an affine transformation in its coordinate system. For tie points that define an affine transformation, the residual error should therefore be 0. For tie points that define more complex, non-linear warping of the image, it will be larger than 0.

      The residual error is computed in image coordinates and expressed in pixels. The default is EPSILON.

      Parameters:
      aMaximumResidualTiePointError - the maximum residual error, expressed in pixels.
      See Also:

    • getMaximumResidualTiePointError

      public double getMaximumResidualTiePointError()
      Returns the maximum acceptable average residual error for tie points.

    • setRasterReferencer

      public void setRasterReferencer(ILcdRasterReferencer aRasterReferencer)
      Sets the raster referencer that will be used when positioning image files based on tie points. If it is set, it replaces the more basic settings minimumTiePointCount, allowOrthographicReferencing, and maximumResidualTiePointError, which are used by default.
      Parameters:
      aRasterReferencer - the raster referencer, which will create model references and raster bounds based on tie points.

    • getRasterReferencer

      public ILcdRasterReferencer getRasterReferencer()
      Returns the raster referencer that is used when positioning image files based on tie points.

    • setInputStreamFactory

      public void setInputStreamFactory(ILcdInputStreamFactory aInputStreamFactory)
      Sets the input stream factory that will be used for creating input streams.

      To ensure good performance, this factory should create streams that allow seeking for the image file. To do so the created stream must implement one of the following interfaces:

      Otherwise, a temporary file may be created.
      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.

    • setJAIOperator

      @Deprecated public void setJAIOperator(String aJAIOperator)
      Deprecated.
      This field no longer has any effect
      Sets the JAI operator to be used for loading the TIFF files.

    • getJAIOperator

      @Deprecated public String getJAIOperator()
      Deprecated.
      This field no longer has any effect
      Returns the JAI operator that is used for loading the TIFF files.

    • setLevelCount

      public void setLevelCount(int aLevelCount)
      Sets the number of raster levels with varying levels of detail that should be computed on the fly, and cached, for more efficient access by the application. The default is 1, meaning that a single level raster is constructed. If set to a value larger than 1, a multi-level raster is constructed.

    • getLevelCount

      public int getLevelCount()
      Returns the number of raster levels that is constructed on the fly.

    • setLevelScaleFactor

      public void setLevelScaleFactor(double aLevelScaleFactor)
      Sets the scale factor between subsequent levels. The default is 0.5.
      See Also:

    • getLevelScaleFactor

      public double getLevelScaleFactor()
      Returns the scale factor between subsequent levels.

    • setColorModel

      public void setColorModel(ColorModel aColorModel)
      Sets the default color model to be assigned to decoded rasters.

    • getColorModel

      public ColorModel getColorModel()
      Returns the default color model that is assigned to decoded rasters.

    • setDefaultValue

      public void setDefaultValue(int aDefaultValue)
      Sets the default color or color index to be assigned to decoded rasters.

    • getDefaultValue

      public int getDefaultValue()
      Returns the default color or color index that is assigned to decoded rasters.

    • setForcedTransparentColorIndex

      public void setForcedTransparentColorIndex(int aForcedTransparentColorIndex)
      Sets the index of the color that should be made transparent in the rasters 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.

      Note that is a better solution to express this within the TIFF file itself. This can be done via the TIFF tag 42113 (GDAL_NODATA) to indicate the no data value.

    • getForcedTransparentColorIndex

      public int getForcedTransparentColorIndex()
      Returns the index of the color that is made transparent.

    • setExpandColorMap

      public void setExpandColorMap(boolean aExpandColorMap)
      Sets whether the color maps of decoded images should be expanded.

    • isExpandColorMap

      public boolean isExpandColorMap()
      Returns whether the color maps of decoded images are expanded.

    • 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)
      Description copied from interface: ILcdModelDecoder
      Checks whether this model decoder can decode the specified data source. It is acceptable for this method to return true for a source name while decode throws an exception for that same source name.

      For performance reasons, we strongly recommend that this will only be a simple test. For example: check the file extension of a file, but not that the file exists or contains expected content.

      Specified by:
      canDecodeSource in interface ILcdModelDecoder
      Parameters:
      aSourceName - the data source to be verified; typically a file name or a URL.
      Returns:
      true if this decoder can likely decode the data specified by the source name, 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:

    • combine

      public static RenderedImage combine(RenderedImage aRGBImage, RenderedImage aAlphaImage)
      Combines an RGB image and a transparency bitmask image into a single RGBA image.