Package com.luciad.format.raster

Class TLcdJAIRasterModelDecoder

java.lang.Object
com.luciad.format.raster.TLcdJAIRasterModelDecoder
All Implemented Interfaces:
ILcdModelDecoder
@LcdService(service=ILcdModelDecoder.class, priority=20000) public class TLcdJAIRasterModelDecoder extends Object implements ILcdModelDecoder
This model decoder decodes jai files. A jai file is a java properties file that describes the spatial reference of an image. The actual image is decoded by the Java Advanced Imaging library.

Input files

File Required Entry point Description
*.jai x x File containing the raster metadata: image file name, a model reference, and raster bounds
*.* x
Image file 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 "TLcdJAIRasterModelDecoder.". If a property is not specified, the corresponding property of the decoder is used as default.

The name of the single image file that contains the raster data:

  • directoryPath (optional): the location of the image data. This string is prefixed to the file name, 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 jai file itself.
  • fileName: the relative file name of the image.

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,...

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/level 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, the decoder can compute the pixel density itself, based on the image file and its bounds in model coordinates or the pixel size metadata documented below. The pixel density is typically used to determine the right level of detail during display, without having to read the all the tiles.

Information about the size in pixels of the raster and tiles. These properties are optional and are only used for pixel density calculation.

  • tilePixelWidth: the width of a single tile in pixels.
  • tilePixelHeight: the height of a single tile in pixels.
  • rasterPixelWidth: the width of the raster in pixels.
  • rasterPixelHeight: the height of the raster in pixels.

Information about the size in pixels of the raster and tiles. These properties are optional and are only used for pixel density calculation.

  • tilePixelWidth: the width of a single tile in pixels.
  • tilePixelHeight: the height of a single tile in pixels.
  • rasterPixelWidth: the width of the raster in pixels.
  • rasterPixelHeight: the height of the raster in pixels.

Information for creating multiple raster levels on the fly:

  • noLevels (default = 1): 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.
  • levelScaleFactor (default = 0.5): the scale factor between subsequent levels.

Information needed to create an appropriate ColorModel:

  • ILcdColorModelFactory.class (default = none): the name of the class that implements an optional ILcdColorModelFactory. This factory must produce a ColorModel that is compatible with the given data. It is only required if the image files themselves don't provide the right color model.
  • 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.

Model reference

Finally, an important set of properties specifies the appropriate ILcdModelReference. The creation as such of an 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 above properties can also be set on this class directly. The method decodeJAI will then decode the given image file with these settings.

The following excerpt of an jai 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
 TLcdJAIRasterModelDecoder.TLcdGridReference.projection.ILcdProjection.class = com.luciad.projection.TLcdTransverseMercator
 TLcdJAIRasterModelDecoder.TLcdGridReference.projection.TLcdTransverseMercator.centralMeridian =-75.0
 TLcdJAIRasterModelDecoder.TLcdGridReference.falseEasting = 500000
 TLcdJAIRasterModelDecoder.TLcdGridReference.falseNorthing = 0.0
 TLcdJAIRasterModelDecoder.TLcdGridReference.scale = 0.9996
 TLcdJAIRasterModelDecoder.TLcdGridReference.unitOfMeasure = 1
 TLcdJAIRasterModelDecoder.TLcdGridReference.geodeticDatum.ILcdGeodeticDatumFactory.class = com.luciad.geodesy.TLcdJPLGeodeticDatumFactory
 TLcdJAIRasterModelDecoder.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 imageInputStreamFactory of this decoder. The imageInputStreamFactory must produce a SeekableStream.

Model structure

  • This model decoder creates a model per jai 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 property sourceName (default = fileName) allows to specify the full name of the image, in case only a RenderedImage is provided to the decoder.
  • The property JAIOperator (default = "stream") specifies the JAI operator that is used to load the image.
  • The property imageInputStreamFactory specifies the factory that will be used to create the input streams from which images can be decoded. It is only used if the JAI operator is "stream" (the default). It must create SeekableInputStream instances, in order for JAI to be able to use them.
  • The property levelInterpolation specifies the interpolation that is used to derive lower-resolution levels (default = null, for nearest neighbor interpolation).
  • 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 TLcdJAIRasterModelDecoder();

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

Performance tips

  • The decoder makes use of the Java Advanced Imaging library for decoding and caching images. It may therefore be helpful to tune the cache size of Java Advanced Imaging: 
    
 JAI.getDefaultInstance().getTileCache().setMemoryCapacity(size);
  • 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.
  • 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 the precomputed levels of detail, this technique still provides better raster painting performance 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 jai format is closely tied to the LuciadLightspeed library.
  • The current implementation of Java Advanced Imaging does not support TIFF RGB rasters with a planar configuration.

  • Field Details

  • Constructor Details

    • TLcdJAIRasterModelDecoder

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

    • TLcdJAIRasterModelDecoder

      public TLcdJAIRasterModelDecoder(int aLevelCount, double aLevelScaleFactor, javax.media.jai.Interpolation aLevelInterpolation)
      Creates a new TLcdJAIRasterModelDecoder 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.
      aLevelInterpolation - the type of interpolation between subsequent levels.

  • Method Details

    • setClassTraceOn

      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

      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

      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.

    • setSourceName

      public void setSourceName(String aSourceName)
      Sets the default source name for decoded raster models, in case the properties file doesn't provide one.

    • getSourceName

      public String getSourceName()
      Returns the default source name for decoded raster models.

    • setDisplayName

      public void setDisplayName(String aDisplayName)
      Sets the default display name for decoded raster models, in case the properties file doesn't provide one.

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

    • setTypeName

      public void setTypeName(String aTypeName)
      Sets the default type name for decoded raster models, in case the properties file doesn't provide one.

    • getTypeName

      public String getTypeName()
      Returns the default type name for decoded raster models.

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

    • setImageInputStreamFactory

      public void setImageInputStreamFactory(ILcdInputStreamFactory aImageInputStreamFactory)
      Sets the factory that will create the input streams from which images can be decoded. It will only be used if the JAI operator is "stream" (the default). It must create javax.media.jai.codec.SeekableStream instances, in order for JAI to be able to use them.

    • getImageInputStreamFactory

      public ILcdInputStreamFactory getImageInputStreamFactory()
      Returns the factory that creates the input streams for decoding images.

    • setLevelCount

      public void setLevelCount(int aLevelCount)
      Sets the default number of raster levels with varying levels of detail that should be constructed on the fly, in case the properties file doesn't provide one. 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 default scale factor between subsequent levels, in case the properties file doesn't provide one.
      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.

    • setModelReference

      public void setModelReference(ILcdModelReference aModelReference)
      Sets the model reference to be assigned to decoded models.

    • getModelReference

      public ILcdModelReference getModelReference()
      Returns the model reference that is assigned to decoded models.

    • setModelBounds

      public void setModelBounds(ILcdBounds aModelBounds)
      Sets the model bounds to be assigned to decoded rasters.

    • getModelBounds

      public ILcdBounds getModelBounds()
      Returns the model bounds that are assigned to decoded rasters.

    • setPixelDensity

      public void setPixelDensity(double aPixelDensity)
      Sets the pixel density to be assigned to decoded rasters.

    • getPixelDensity

      public double getPixelDensity()
      Returns the pixel density that is assigned to decoded rasters.

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

    • canDecodeSource

      public boolean canDecodeSource(String aSourceName)
      Checks whether this class can decode the given data. The extension of the file name should be "jai".
      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:

    • decodeProperties

      public ILcdModel decodeProperties(String aDirectoryPath, Properties aProperties) throws IOException
      Decodes a model containing a raster, based on a given set of properties.
      Parameters:
      aDirectoryPath - the directory containing the image file.
      aProperties - the properties describing the image file and the way it should be decoded.
      Throws:
      IOException

    • decodeRenderedImage

      public ILcdModel decodeRenderedImage(RenderedImage aRenderedImage) throws IOException
      Decodes a given rendered image with the current settings of this model decoder.
      Throws:
      IOException