TLcdJAIRasterModelDecoder (LuciadLightspeed API documentation)

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

All models returned by this model decoder have a TLcdJAIModelDescriptor or a TLcdMultilevelJAIModelDescriptor.
The type name of the model descriptor is the display name of this decoder.

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 Summary

Fields
Modifier and Type Field and Description

static String DEFAULT_DISPLAY_NAME

static String DEFAULT_EXTENSION

static String DEFAULT_JAI_OPERATOR

Fields
Modifier and Type	Field and Description
`static String`	`DEFAULT_DISPLAY_NAME`
`static String`	`DEFAULT_EXTENSION`
`static String`	`DEFAULT_JAI_OPERATOR`

Constructor Summary

Constructors
Constructor and Description
`TLcdJAIRasterModelDecoder()` Creates a new TLcdJAIRasterModelDecoder that creates single level raster models by default.
`TLcdJAIRasterModelDecoder(int aLevelCount, double aLevelScaleFactor, javax.media.jai.Interpolation aLevelInterpolation)` Creates a new TLcdJAIRasterModelDecoder that creates multi-level raster models by default.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods
Modifier and Type	Method and Description
`boolean`	`canDecodeSource(String aSourceName)` Checks whether this class can decode the given data.
`ILcdModel`	`decode(String aSourceName)` Creates a new model from the given data source.
`ILcdModel`	`decodeProperties(String aDirectoryPath, Properties aProperties)` Decodes a model containing a raster, based on a given set of properties.
`ILcdModel`	`decodeRenderedImage(RenderedImage aRenderedImage)` Decodes a given rendered image with the current settings of this model decoder.
`ColorModel`	`getColorModel()` Returns the color model that is assigned to decoded rasters.
`int`	`getDefaultValue()` Returns the default color or color index that is assigned to decoded rasters.
`String`	`getDisplayName()` Returns a short, displayable name for the format that is decoded by this `ILcdModelDecoder`.
`int`	`getForcedTransparentColorIndex()` Returns the index of the color that is made transparent.
`ILcdInputStreamFactory`	`getImageInputStreamFactory()` Returns the factory that creates the input streams for decoding images.
`String`	`getJAIOperator()` Returns the JAI operator that is used to load raster images.
`int`	`getLevelCount()` Returns the number of raster levels that is constructed on the fly.
`javax.media.jai.Interpolation`	`getLevelInterpolation()` Returns the Interpolation that is applied between subsequent levels.
`double`	`getLevelScaleFactor()` Returns the scale factor between subsequent levels.
`ILcdBounds`	`getModelBounds()` Returns the model bounds that are assigned to decoded rasters.
`ILcdModelReference`	`getModelReference()` Returns the model reference that is assigned to decoded models.
`double`	`getPixelDensity()` Returns the pixel density that is assigned to decoded rasters.
`String`	`getSourceName()` Returns the default source name for decoded raster models.
`String`	`getTypeName()` Returns the default type name for decoded raster models.
`boolean`	`isTraceOn()` Deprecated. This method has been deprecated. It is recommended to use the standard Java logging framework directly.
`static void`	`setClassTraceOn(boolean aClassTraceOn)` Deprecated. This method has been deprecated. It is recommended to use the standard Java logging framework directly.
`void`	`setColorModel(ColorModel aColorModel)` Sets the color model to be assigned to decoded rasters.
`void`	`setDefaultValue(int aDefaultValue)` Sets the default color or color index to be assigned to decoded rasters.
`void`	`setDisplayName(String aDisplayName)` Sets the default display name for decoded raster models, in case the properties file doesn't provide one.
`void`	`setForcedTransparentColorIndex(int aForcedTransparentColorIndex)` Sets the index of the color that should be made transparent in the rasters that will be decoded next.
`void`	`setImageInputStreamFactory(ILcdInputStreamFactory aImageInputStreamFactory)` Sets the factory that will create the input streams from which images can be decoded.
`void`	`setJAIOperator(String aJAIOperator)` Sets the JAI operator to be used to load raster images.
`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.
`void`	`setLevelInterpolation(javax.media.jai.Interpolation aLevelInterpolation)` Sets the Interpolation to be applied between subsequent levels.
`void`	`setLevelScaleFactor(double aLevelScaleFactor)` Sets the default scale factor between subsequent levels, in case the properties file doesn't provide one.
`void`	`setModelBounds(ILcdBounds aModelBounds)` Sets the model bounds to be assigned to decoded rasters.
`void`	`setModelReference(ILcdModelReference aModelReference)` Sets the model reference to be assigned to decoded models.
`void`	`setPixelDensity(double aPixelDensity)` Sets the pixel density to be assigned to decoded rasters.
`void`	`setSourceName(String aSourceName)` Sets the default source name for decoded raster models, in case the properties file doesn't provide one.
`void`	`setTraceOn(boolean aTraceOn)` Deprecated. This method has been deprecated. It is recommended to use the standard Java logging framework directly.
`void`	`setTypeName(String aTypeName)` Sets the default type name for decoded raster models, in case the properties file doesn't provide one.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface com.luciad.model.ILcdModelDecoder
canDecodeSource, decodeModelMetadata, decodeModelMetadata, decodeSource, discoverDataSources

- Field Detail
  - DEFAULT_DISPLAY_NAME
```
public static final String DEFAULT_DISPLAY_NAME
```
    See Also:
    
    Constant Field Values
  - DEFAULT_EXTENSION
```
public static final String DEFAULT_EXTENSION
```
    See Also:
    
    Constant Field Values
  - DEFAULT_JAI_OPERATOR
```
public static final String DEFAULT_JAI_OPERATOR
```
    See Also:
    
    Constant Field Values
- Constructor Detail
  - 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 Detail
  - 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:
    
    setLevelCount(int)
  - 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:
    
    setLevelCount(int)
  - 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:
    
    ILcdModelDecoder.decode(String), ILcdModelDecoder.decodeModelMetadata(String)
  - 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); } }
    InterruptedIOException - When the thread on which this method is called is interrupted: it is recommended to stop the decoding and throw an InterruptedIOException. This same exception can also be used if the decoder shows UI to the user, and the user cancels the decoding through the UI.
    
    See Also:
    
    ILcdModelDecoder.canDecodeSource(String)
  - 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

LuciadLightspeedClass TLcdJAIRasterModelDecoder

Input files

Model reference

Supported file transfer protocols

Model structure

Model descriptor

Model elements

Useful settings

Sample code

Performance tips

Thread safety

Known limitations

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Methods inherited from interface com.luciad.model.ILcdModelDecoder

Field Detail

DEFAULT_DISPLAY_NAME

DEFAULT_EXTENSION

DEFAULT_JAI_OPERATOR

Constructor Detail

TLcdJAIRasterModelDecoder

TLcdJAIRasterModelDecoder

Method Detail

setClassTraceOn

setTraceOn

isTraceOn

setSourceName

getSourceName

setDisplayName

getDisplayName

setTypeName

getTypeName

setJAIOperator

getJAIOperator

setImageInputStreamFactory

getImageInputStreamFactory

setLevelCount

getLevelCount

setLevelScaleFactor

getLevelScaleFactor

setLevelInterpolation

getLevelInterpolation

setModelReference

getModelReference

setModelBounds

getModelBounds

setPixelDensity

getPixelDensity

setColorModel

getColorModel

setDefaultValue

getDefaultValue

setForcedTransparentColorIndex

getForcedTransparentColorIndex

canDecodeSource

decode

decodeProperties

decodeRenderedImage