@LcdService(service=ILcdModelDecoder.class, priority=20000) public class TLcdJAIRasterModelDecoder extends Object implements ILcdModelDecoder
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.
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.
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.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.
imageInputStreamFactory
of this decoder. The
imageInputStreamFactory
must produce a
SeekableStream
.jai
file.ILcd2DBoundsIndexedModel
.TLcdJAIModelDescriptor
or a
TLcdMultilevelJAIModelDescriptor
.ALcdImage
(and either ILcdRaster
or ILcdMultilevelRaster)
).sourceName
(default = fileName) allows to
specify the full name of the image, in case only a
RenderedImage
is provided to the decoder.JAIOperator
(default = "stream
")
specifies the JAI operator that is used to load the image.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.
levelInterpolation
specifies the interpolation
that is used to derive lower-resolution levels (default =
null
, for nearest neighbor interpolation).
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.
ILcdModelDecoder decoder = new TLcdJAIRasterModelDecoder();
ILcdModel model = decoder.decode("raster.jai");
JAI.getDefaultInstance().getTileCache().setMemoryCapacity(size);
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.jai
format is closely tied to the LuciadLightspeed library.Modifier and Type | Field and Description |
---|---|
static String |
DEFAULT_DISPLAY_NAME |
static String |
DEFAULT_EXTENSION |
static String |
DEFAULT_JAI_OPERATOR |
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.
|
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.
|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
canDecodeSource, decodeModelMetadata, decodeModelMetadata, decodeSource, discoverDataSources
public static final String DEFAULT_DISPLAY_NAME
public static final String DEFAULT_EXTENSION
public static final String DEFAULT_JAI_OPERATOR
public TLcdJAIRasterModelDecoder()
public TLcdJAIRasterModelDecoder(int aLevelCount, double aLevelScaleFactor, javax.media.jai.Interpolation aLevelInterpolation)
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.public static void setClassTraceOn(boolean aClassTraceOn)
true
then all log messages are recorded, otherwise only
the informative, warning and error messages are recorded.aClassTraceOn
- if true then all log messages are recorded,
otherwise only the informative, warning and error messages are recorded.public void setTraceOn(boolean aTraceOn)
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.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.public boolean isTraceOn()
true
if tracing is enabled for this class.public void setSourceName(String aSourceName)
public String getSourceName()
public void setDisplayName(String aDisplayName)
public String getDisplayName()
ILcdModelDecoder
ILcdModelDecoder
.getDisplayName
in interface ILcdModelDecoder
ILcdModelDecoder
.public void setTypeName(String aTypeName)
public String getTypeName()
public void setJAIOperator(String aJAIOperator)
public String getJAIOperator()
public void setImageInputStreamFactory(ILcdInputStreamFactory aImageInputStreamFactory)
stream
"
(the default). It must create
javax.media.jai.codec.SeekableStream
instances,
in order for JAI to be able to use them.public ILcdInputStreamFactory getImageInputStreamFactory()
public void setLevelCount(int aLevelCount)
public int getLevelCount()
public void setLevelScaleFactor(double aLevelScaleFactor)
setLevelCount(int)
public double getLevelScaleFactor()
public void setLevelInterpolation(javax.media.jai.Interpolation aLevelInterpolation)
setLevelCount(int)
public javax.media.jai.Interpolation getLevelInterpolation()
public void setModelReference(ILcdModelReference aModelReference)
public ILcdModelReference getModelReference()
public void setModelBounds(ILcdBounds aModelBounds)
public ILcdBounds getModelBounds()
public void setPixelDensity(double aPixelDensity)
public double getPixelDensity()
public void setColorModel(ColorModel aColorModel)
public ColorModel getColorModel()
public void setDefaultValue(int aDefaultValue)
public int getDefaultValue()
public void setForcedTransparentColorIndex(int aForcedTransparentColorIndex)
public int getForcedTransparentColorIndex()
public boolean canDecodeSource(String aSourceName)
canDecodeSource
in interface ILcdModelDecoder
aSourceName
- the name of the file or URL that is to be decoded.true
if the data specified by the source name can be
decoded, false
otherwise.ILcdModelDecoder.decode(String)
,
ILcdModelDecoder.decodeModelMetadata(String)
public ILcdModel decode(String aSourceName) throws IOException
ILcdModelDecoder
decode
in interface ILcdModelDecoder
aSourceName
- the data source to be decoded; typically a file name or a URL.null
is allowed, implementors are advised to throw an error instead.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.ILcdModelDecoder.canDecodeSource(String)
public ILcdModel decodeProperties(String aDirectoryPath, Properties aProperties) throws IOException
aDirectoryPath
- the directory containing the image file.aProperties
- the properties describing the image file and the
way it should be decoded.IOException
public ILcdModel decodeRenderedImage(RenderedImage aRenderedImage) throws IOException
IOException