@LcdService(service=ILcdModelDecoder.class, priority=20000) public class TLcdOracleGeoRasterModelDecoder extends Object implements ILcdModelDecoder
ILcdModelDecoder
decodes rasters stored in an Oracle
Spatial database.
Properties
object, or using a properties file
with extension "ogr
".
The common properties needed to establish a connection are: driver
(default = oracle.jdbc.driver.OracleDriver
):
the JDBC driver that will be used to connect to the database.
url
: the database URL. user
: the database
user name. password
: the user's password.
alwaysCloseConnection
(default = false
): an
optional boolean to specify that the database connection should be closed
after each query. Setting this flag can be useful for database drivers that
pool connections, so the connections are reused instead of really being
closed.
table
: the name of the table containing
the rasters.
geoRasterColumn
: the column containing the
rasters.
selectionTables
(default = null
): an
optional comma-separated list of tables required to constrain the rasters of
the model. These tables will be added after the main table in the FROM parts
of SELECT queries. Note that any column names that are ambiguous (because
they occur in multiple tables), have to be prefixed with the suitable table
names.
selectionFilter
(default = null
): an
optional SQL select query to constrain the rasters of the model. This query
will be added after the spatial query in the WHERE parts of SELECT queries.
preferredBand
(default = -1): optional, indicates that
a single band should be decoded from a multispectral image. For 16 bit
images it has the benefit of producing non-truncated, 16 bit rasters.
sourceFileName
: an optional string to be used as the source
name in the model descriptor. By default it is the name of the "ogr
" file, or "DB" when decoding a stand-alone Properties
object.
displayName
: an optional string to be used as the display
name in the model descriptor. If not specified, it is equal to the
sourceName.
# The basic database connection properties. driver = oracle.jdbc.driver.OracleDriver url = jdbc:oracle:thin:@myhost:1521:LUCIAD user = scott password = tiger # Optional (default is false) alwaysCloseConnection = true # The data of interest. table = COUNTRIES geoRasterColumn = GEORASTER # Optionally, decode a single color band # preferredBand=2 # Optional extra tables and SQL condition to restrict the database elements. # Note that the column names have to be prefixed with the table # name if they are ambiguous, like the ID column below. # selectionTables = POPULATION # selectionFilter = COUNTRIES.ID = POPULATION.ID AND POPULATION.VALUE > 1e7
ogr
file or Properties
object have the same geographic reference, then the model decoder returns an
ILcd2DBoundsIndexedModel
.ogr
file or Properties
object have different geographic references, then the model decoder returns an
ILcdModelTreeNode
. The ILcdModelTreeNode
contains several
ILcd2DBoundsIndexedModel
sub-models, one for each encountered geographic reference.TLcdOracleGeoRasterModelDescriptor
.
sourceFileName
property.
displayName
property.
ILcd2DBoundsIndexedModel
, the model elements
implement ILcdMultilevelRaster
.ILcdModelTreeNode
, the model tree node has no
elements of its own. All the sub-models of the ILcdModelTreeNode
contain elements
that implement ILcdMultilevelRaster
.setDefaultModelReference(com.luciad.model.ILcdModelReference)
).
ILcdModelDecoder decoder = new TLcdOracleGeoRasterModelDecoder();
// decoder.setPreferredBand(0);
ILcdModel model = decoder.decode("file.ogr");
N
color bands are distributed over
M
data blocks (N != M) is not supported.Tiling
: If a database raster uses blocking, the blocks are translated
into tiles. If blocking is not used, the decoded ILcdMultilevelRaster
s
will not be tiled.Pyramids
: If a database raster has multiple resolution levels, they
will be decoded as separate levels in the corresponding
ILcdMultilevelRaster
. If pyramids are not used in the database,
the ILcdMultilevelRaster
will contain a single resolution
level.Cell depth
: The database rasters must have a cell depth of 1, 2, 4,
8, or 16 bits. Higher cell depths are currently not supported.
If the cell depth is 1, 2, or 4 bits (several raster cells are packed in one
byte) then each cell will be expanded to occupy 8 bits in the decoded
raster.
If the database raster has a cell depth of 16 bits, the decoded raster may
have 8 or 16 bits, depending on the database raster's color model and whether
the user specified a single preferred band to be decoded (see the Color
Models section).Elevation data
: If at least one of the matching database rasters
contains 16 bit signed values (16BIT_S) and has exactly one color band then
the data is considered to represent elevations. The isElevation
method of the model descriptor will return true
.Compression
: The following block compression methods are supported:
Color models
: If the database raster has a true
color model and at least 3 color bands, the decoder will normally create an 8
bit RGB raster having a direct color model. The R, G, and B bands are
selected according to the database raster's defaultColorLayer property (see
the Oracle documentation). If the database raster has a cell depth of 16
bits, the decoder truncates the cell values to 8 bits by taking only the most
significant byte of the value.
To decide if the database raster has a true (direct) or an indexed color
model, the decoder checks the colorMap property of the first database raster
layer. If the database defines a color map, the decoded raster will have an
IndexedColorModel using that color map, otherwise the decoded raster will
have a direct color model.
If the user specifies a preferred band via the setPreferredBand(int)
method, the decoded raster will always have an IndexColorModel
.
The color map of this color model is extracted from the database by looking
at the colorMap property of the requested band/layer (see Oracle
documentation for getColorMap). If no color map is specified by the database
then a default IndexColorModel
is created. This color model
contains gray scale values in the usual case, or values suitable for
displaying elevation data, if the raster contains elevations.
If the database raster NODATA value is defined, the color model is expanded to include an alpha
channel or an alpha value and the corresponding pixels are set to full transparency in the
decoded raster.
DB Cell Depth | DB Bands | Preferred Band | Decoded raster |
---|---|---|---|
1,2,4,8 bit | 3 bands or more | No | RGB, 8 bit |
2 bands | No | error | |
2 bands or more | Yes | Indexed, 8 bit | |
1 band or grayscale | - | Indexed, 8 bit | |
16 bit | 3 bands or more | No | RGB, truncated to 8 bit |
2 bands | No | error | |
2 bands or more | Yes | Indexed, 16 bit | |
1 band | - | Indexed, 16 bit |
close()
method of the associated
TLcdOracleGeoRasterModelDescriptor
.
alwaysCloseConnection
to
true
and setting a connection-pooling database driver. This
forces the model to ask for a new connection every time a tile read is
necessary. Multiple threads will obtain different connections from the pool,
so the reading will be done in parallel instead of being serialized on a
single connection object.TLcdOracleGeoRasterModelDescriptor
Constructor and Description |
---|
TLcdOracleGeoRasterModelDecoder()
Constructs a new TLcdOracleGeoRasterModelDecoder, with a globally shared
buffer for caching tiles.
|
TLcdOracleGeoRasterModelDecoder(ILcdBuffer aBuffer)
Constructs a new TLcdOracleGeoRasterModelDecoder.
|
Modifier and Type | Method and Description |
---|---|
boolean |
canDecodeSource(String aSourceName)
Checks whether this model decoder can decode the specified data source.
|
ILcdModel |
decode(Properties aProperties)
Creates a new model from the given set of properties.
|
ILcdModel |
decode(String aSourceName)
Creates a new model from the given data source.
|
ILcdModelReference |
getDefaultModelReference()
Returns the default model reference.
|
String |
getDisplayName()
Returns a short, displayable name for the format that is decoded by this
ILcdModelDecoder . |
int |
getPreferredBand()
Returns the preferred band.
|
static boolean |
isClassTraceOn()
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 |
setDefaultModelReference(ILcdModelReference aDefaultModelReference)
Sets the model reference to be used if the georaster does not define one.
|
void |
setPreferredBand(int aPreferredBand)
Sets the preferred band for extracting the colormap.
|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
canDecodeSource, decodeModelMetadata, decodeModelMetadata, decodeSource, discoverDataSources
public TLcdOracleGeoRasterModelDecoder()
TLcdSharedBuffer.getBufferInstance()
public TLcdOracleGeoRasterModelDecoder(ILcdBuffer aBuffer)
aBuffer
- a buffer used for internal operations. The buffer must be
large enough to keep at least one decoded raster tile (eg. pixel_width x
pixel_height x 3, assuming 3 color bands and one byte per color sample).public void setDefaultModelReference(ILcdModelReference aDefaultModelReference)
aDefaultModelReference
- the default model reference.public ILcdModelReference getDefaultModelReference()
public int getPreferredBand()
public void setPreferredBand(int aPreferredBand)
preferredBand
specified in the ogr
properties
file.aPreferredBand
- the index of the preferred bandpublic static boolean isClassTraceOn()
true
if tracing is enabled for this class.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 String getDisplayName()
ILcdModelDecoder
ILcdModelDecoder
.getDisplayName
in interface ILcdModelDecoder
ILcdModelDecoder
.public boolean canDecodeSource(String aSourceName)
ILcdModelDecoder
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.
canDecodeSource
in interface ILcdModelDecoder
aSourceName
- the data source to be verified; typically a file name or a URL.true
if this decoder can likely decode the data specified by the source name, 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 decode(Properties aProperties) throws IOException
aProperties
- a Properties object containing information about an
Oracle databaseIOException