Package com.luciad.format.raster

Class TLcdTABRasterModelDecoder

java.lang.Object
com.luciad.format.raster.TLcdTABRasterModelDecoder
All Implemented Interfaces:
ILcdInputStreamFactoryCapable, ILcdModelDecoder
@LcdService(service=ILcdModelDecoder.class, priority=20000) public class TLcdTABRasterModelDecoder extends Object implements ILcdModelDecoder, ILcdInputStreamFactoryCapable
This model decoder decodes MapInfo TAB Raster files. A TAB Raster file provides the file name and the geo-referencing information of its corresponding image file.

Input files

File Required Entry point Description
*.tab x x TAB file specifying a model reference, raster tie points, and the actual raster image file
*.tif
...		 x
image file containing the raster data. Note that the case of the image file name may matter, depending on your file system.

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 for the image file.

Model structure

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

Model descriptor

Model reference

The model reference is decoded from the tab file.

Model elements

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

Useful settings

  • Since 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, and forcedTransparentColorIndex 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 often 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 TLcdTABRasterModelDecoder();

 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.
  • It is possible to compute and cache lower resolution images on the fly, by means of the properties levelCount, levelScaleFactor, and levelInterpolation. Although there is an obvious overhead compared to precomputed levels of detail, this technique still provides better raster painting performance when zoomed out.

Thread safety

  • The decoding of models is not thread-safe.
  • The decoded models are thread-safe for read access.

Supported versions and specifications

  • TAB Format Specification, Revision 1.0, Specification Version 1.8.2
  • Tagged Image File Format, TIFF, Revision 6.0, Aldus Developers Desk, 3 June 1992

Known limitations

  • Some rare model references are not supported.
  • The current implementation does not support TIFF RGB rasters with a planar configuration.

Requirements

  • The current implementation delegates image decoding to the Java Advanced Imaging library.

  • Field Details

  • Constructor Details

    • TLcdTABRasterModelDecoder

      public TLcdTABRasterModelDecoder()
      Creates a new TLcdTABRasterModelDecoder that creates single level raster models by default.

    • TLcdTABRasterModelDecoder

      public TLcdTABRasterModelDecoder(int aLevelCount, double aLevelScaleFactor)
      Creates a new TLcdTABRasterModelDecoder that creates multi-level raster models by default.
      Parameters:
      aLevelCount - the number of rasters levels.
      aLevelScaleFactor - the scale factor between subsequent levels, in both raster dimensions.

  • Method Details

    • setJAIOperator

      public void setJAIOperator(String aJAIOperator)
      Sets the JAI operator to be used to load raster images.

    • getJAIOperator

      public String getJAIOperator()
      Returns the JAI operator that is used to load raster images.

    • setAllowOrthographicReferencing

      public void setAllowOrthographicReferencing(boolean aAllowOrthographicReferencing)
      Specifies whether images that are positioned in geodetic references 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 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 the tie points.

      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.

    • 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. It must create SeekableStream instances for the image file in order for JAI to be able to use them.
      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.

    • setLevelCount

      public void setLevelCount(int aLevelCount)
      Sets the number of raster levels with varying levels of detail that should be constructed on the fly, and cached, for more efficient access by the application. If 1, a single level raster is constructed. If 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.
      See Also:

    • getLevelScaleFactor

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

    • setLevelInterpolation

      public void setLevelInterpolation(javax.media.jai.Interpolation aLevelInterpolation)
      Sets the Interpolation to be applied between subsequent levels.
      See Also:

    • getLevelInterpolation

      public javax.media.jai.Interpolation getLevelInterpolation()
      Returns the Interpolation that is applied between subsequent levels.

    • setColorModel

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

    • getColorModel

      public ColorModel getColorModel()
      Returns the 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.

    • getForcedTransparentColorIndex

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

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