@LcdService(service=ILcdModelDecoder.class, priority=20000) public class TLcdRasterModelDecoder extends Object implements ILcdModelDecoder, ILcdInputStreamFactoryCapable
rst
files. An
rst
file is a java properties file that describes the structure
and the spatial reference of a set of raster data. The actual raster data
are contained in external files or URLs.
Raster data can be given at one or more levels of detail. Level 0 has the lowest resolution; subsequent levels have increasing resolutions. Users of the decoded models (e.g. painters) can pick a suitable level of detail based on the pixel density of each level (the number of pixels per unit area).
The location of a raster is specified by its bounds in model coordinates.
The contents of a raster is specified by a regular grid of one or more tiles.
Each tile generally corresponds to one image file, which is specified in
the rst
file. Missing tiles may be left unspecified.
All tiles at a given level have equal sizes in model coordinates (except possibly for tiles in the right-most column or in the bottom-most row, which may be truncated). On the other hand, tiles may have different pixel sizes. For instance, tiles in a geodetic coordinate system have equal sizes in model coordinates, but they may have lower resolutions near the poles (like the 1x1 degree tiles in the DTED format).
For improving the efficiency of decoding and caching, tiles may be further subdivided into sub-tiles, typically corresponding to the tiling inside the image files.
File | Required | Entry point | Description |
---|---|---|---|
*.rst | x | x | Raster file containing the raster metadata: image file name(s), a model reference, and raster bounds |
*.* | x | Image file(s) 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
"TLcdRasterModelDecoder.
".
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,...isElevation
(default = false
): a boolean flag
that specifies whether the raster contains elevation
data.Information about the number of levels in a multi-level raster:
noLevels
(default = 0): the number of raster levels.
If 0 or 1, a single-level raster is constructed.
If larger than 1, a multi-level raster is
constructed.
For a multi-level raster, each of the properties below may be suffixed by
'.i', with i referring to the level (0 <= i <
noLevels
). The properties can also be included without a suffix,
in order to specify defaults for all levels.
Information needed to create rasters:
ILcdColorModelFactory.class
(default = none): optionally,
the name of a class that implements ILcdColorModelFactory
. This factory
must produce a ColorModel
that is
compatible with the given data. It is only required
if the raster files themselves don't provide the
desired color model.pixelByteSize
: the size of a pixel, expressed in bytes. This may
be 1, 2, or 4.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.
The value may be prefixed by 0x
to
indicate a hexadecimal value.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 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, one can specify the nominal size of the
entire raster, expressed in pixels, by means of the
properties rasterPixelWidth
and
rasterPixelHeight
, or the size of a
nominal tile, expressed in pixels, by means of the
properties tilePixelWidth
and
tilePixelHeight
.
The decoder will then compute the pixel density.
The pixel density is typically used to determine the
right level of detail during display, without having
to read the all the tiles.
Information needed to create the tiles of each raster. Each of
these properties may be suffixed by '.r.c', with
r referring to the row index and c referring to the column
index within the raster (0 <= r < noTileRows
and
(0 <= c < noTileColumns
). As before, each of these
properties may be further suffixed by the level number. The properties can
be included without either or both suffixes, in order to specify defaults for
all tiles and/or levels.
ILcdTile.class
:
the name of the class that implements ILcdTile
. The current implementation supports
two types:
com.luciad.format.raster.TLcdBufferedTile
(the default):
the tile that decodes and caches rasters with the help of
ILcdTileDecoder
and ILcdBuffer
.com.luciad.format.raster.TLcdRenderedImageTile
:
the tile that decodes and caches rasters with the help of
the Java Advanced Imaging library.ILcdTileDecoder.class
(default = none): the name of the
class that implements ILcdTileDecoder
and that can decode the
actual raster files.directoryPath
(optional): the location of the image data.
This string is prefixed to the file names, 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 rst
file itself.fileName
: the relative file name of the image tile.imageIndex
(default = 0): the index of the image within the image
file of the tile.tilePixelWidth
(optional): the width of one tile, expressed in pixels.
The value may be required if it can't be read from the
image file itself.tilePixelHeight
(optional): the width of one tile, expressed in pixels.
The value may be required if it can't be read from the
image file itself.subTilePixelWidth
(optional): the width of the sub-tiles of the tiles, expressed in pixels.
The default is the width of the tiles.subTilePixelHeight
(optional): the height of the sub-tiles of the tiles, expressed in pixels.
The default is the height of the tiles.
ILcdModelReference
. The model reference is the common to all
tiles and, in the case of a multi-level raster, to all raster levels. The
creation of the 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 following excerpt of an rst
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
TLcdRasterModelDecoder.TLcdGridReference.projection.ILcdProjection.class = com.luciad.projection.TLcdTransverseMercator
TLcdRasterModelDecoder.TLcdGridReference.projection.TLcdTransverseMercator.centralMeridian =-75.0
TLcdRasterModelDecoder.TLcdGridReference.falseEasting = 500000
TLcdRasterModelDecoder.TLcdGridReference.falseNorthing = 0.0
TLcdRasterModelDecoder.TLcdGridReference.scale = 0.9996
TLcdRasterModelDecoder.TLcdGridReference.unitOfMeasure = 1
TLcdRasterModelDecoder.TLcdGridReference.geodeticDatum.ILcdGeodeticDatumFactory.class
= com.luciad.geodesy.TLcdJPLGeodeticDatumFactory
TLcdRasterModelDecoder.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.
InputStreamFactory
of this decoder.ILcd2DBoundsIndexedModel
.TLcdRSTModelDescriptor
or a
TLcdMultilevelRSTModelDescriptor
.ALcdImage
(and either ILcdRaster
or ILcdMultilevelRaster)
).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 TLcdRasterModelDecoder();
ILcdModel model = decoder.decode("raster.rst");
TLcdBuffer
),
or they may be allocated whenever required and managed using soft
references (see TLcdConcurrentBuffer
).
rst
format is closely tied to the LuciadLightspeed library.Modifier and Type | Field and Description |
---|---|
static String |
DEFAULT_DISPLAY_NAME |
static String |
DEFAULT_EXTENSION |
Constructor and Description |
---|
TLcdRasterModelDecoder()
Creates a new TLcdRasterModelDecoder, with a globally shared
buffer for caching tiles.
|
TLcdRasterModelDecoder(ILcdBuffer aBuffer)
Creates a new TLcdRasterModelDecoder.
|
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.
|
String |
getDisplayName()
Returns a short, displayable name for the format that is decoded by this
ILcdModelDecoder . |
ILcdInputStreamFactory |
getInputStreamFactory()
Returns the input stream factory that is used.
|
void |
setBuffer(ILcdBuffer aBuffer)
Should be used when this class was constructed from within COM
or with the default constructor.
|
void |
setInputStreamFactory(ILcdInputStreamFactory aInputStreamFactory)
Sets the factory that will create the input streams.
|
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 TLcdRasterModelDecoder()
TLcdSharedBuffer.getBufferInstance()
public TLcdRasterModelDecoder(ILcdBuffer aBuffer)
aBuffer
- the buffer into which the raster values can be decoded.public void setBuffer(ILcdBuffer aBuffer)
public void setInputStreamFactory(ILcdInputStreamFactory aInputStreamFactory)
ILcdInputStreamFactoryCapable
.setInputStreamFactory
in interface ILcdInputStreamFactoryCapable
aInputStreamFactory
- the input stream factory to be used.public ILcdInputStreamFactory getInputStreamFactory()
ILcdInputStreamFactoryCapable
getInputStreamFactory
in interface ILcdInputStreamFactoryCapable
public String getDisplayName()
ILcdModelDecoder
ILcdModelDecoder
.getDisplayName
in interface ILcdModelDecoder
ILcdModelDecoder
.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)