For the application to display data correctly on a map, the data should have a coordinate reference system associated with it. This allows the application to interpret the coordinates of the data correctly.
Not all data has its coordinate reference system (CRS) stored digitally. Sometimes, the CRS is known for a whole data repository and is implied when the data is used. In other cases, the data is in a format that does not support storing the CRS, for example JPEG or GIF, or that does not impose the storage of the CRS, such as TIFF. If the CRS is not available for the source data, you have to define a CRS for the data yourself. In that case, you need to contact the supplier of the data to find out the reference system and the format in which to store it.
This article explains how to use an ILcdModelDecoder
to handle the CRS associated with a model, also known as the model reference. First, it describes the logic used to determine
a model’s coordinate reference. Next, it discusses how to provide reference information. Finally, it explains how to encode
and store a model reference.
How does a model decoder determine the model reference?
To decode a model, the model decoder tries to determine the model reference by:
-
Retrieving it from the data. In this case, the CRS is included in the data files.
-
If the reference is not available in the data itself, checking for an additional file that defines the model reference. The CRS can be included with the data in a separate file. An
ILcdModelReferenceDecoder
is used to decode such files. LuciadLightspeed offersILcdModelReferenceDecoder
implementations that allow you to read Well-Known Text (WKT) or EPSG codes, for example. You can set theILcdModelReferenceDecoder
as a property of the model decoder, so that the reference is constructed and set directly on the decoded model. -
Using a fixed default reference, set on the decoder. Some model decoders offer the possibility to set a default model reference, which is used as a fall-back mechanism if no other model reference is available. Use the method
setDefaultModelReference
on theILcdModelDecoder
implementation.
Providing model reference information
This section discusses some available implementations of the ILcdModelReferenceDecoder
interface, and goes into more detail about using particular ILcdModelDecoder
implementations to decode raster models and their model references.
ILcdModelReferenceDecoder implementations
These are some of the available implementations of ILcdModelReferenceDecoder
:
-
TLcdModelReferenceDecoder
to decode.ref
files, a format created by Luciad defining the properties in a Java properties file. -
TLcdWKTModelReferenceDecoder
to decode.prj
files which store the CRS in the Well-Known Text (WKT) format. Refer to the OpenGIS Coordinate Transformation Service Implementation Specification at http://www.opengeospatial.org/standards/ct. -
TLcdEPSGModelReferenceDecoder
to decode.epsg
files. An.epsg
file is a text file containing a single decimal EPSG code, formatted asn
orEPSG:n
. For details about EPSG codes, refer to http://epsg.org/. See theTLcdEPSGReferenceParser
reference documentation for a list of supported EPSG codes. -
TLcdRPCModelReferenceDecoder
to decode RPC files, which typically come with GeoTIFF files and have the extension_rpc.txt
.
See the API reference documentation for more information about the available ILcdModelReferenceDecoder
implementations.
There is also a composite model reference decoder implementation available ( |
Providing reference information for raster data
To decode raster data, additional information about the raster bounds is required. The raster bounds are the real-world extents of the raster data, expressed in coordinates. LuciadLightspeed supports a number of file formats and decoders, which allow you to define and decode referencing information for raster data.
Decoding the JAI file format
The JAI file format, defined by Luciad, points to a single image that can be decoded by the Java Advanced Imaging library.
It contains all the necessary referencing information, in terms of LuciadLightspeed classes and their properties. The TLcdJAIRasterModelDecoder
decodes JAI files, including the model reference.
The generic TLcdJAIRasterModelDecoder
decodes properties files with extension .jai
. A JAI file defines a raster with a single tile image, and the reference information of the raster. The JAI file itself does
not contain any image data. It points to an external file that can be decoded by the Java Advanced Imaging library and that
lacks georeferencing information, for example, PNM, GIF, JPEG, and TIFF. Program: Example of a JAI file shows an example of a JAI file. It specifies a GIF image, positioned in a grid reference with a transverse mercator projection
and the WGS-84 geodetic datum. The properties supported in JAI files are described in detail in the reference documentation
of TLcdJAIRasterModelDecoder
.
# Some general information.
TLcdJAIRasterModelDecoder.displayName = DC_SPOT
TLcdJAIRasterModelDecoder.typeName = geoTIFF
# The model reference.
TLcdJAIRasterModelDecoder.ILcdModelReference.class = com.luciad.reference.TLcdGridReference
TLcdJAIRasterModelDecoder.TLcdGridReference.geodeticDatum.ILcdGeodeticDatumFactory.class = \
com.luciad.geodesy.TLcdJPLGeodeticDatumFactory
TLcdJAIRasterModelDecoder.TLcdGridReference.geodeticDatum.TLcdJPLGeodeticDatumFactory.geodeticDatumName = \
WGS\ 84
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
# The raster bounds in model coordinates.
TLcdJAIRasterModelDecoder.ulx = 316393.8
TLcdJAIRasterModelDecoder.uly = 4319175.0
TLcdJAIRasterModelDecoder.rasterWidth = 10430.0
TLcdJAIRasterModelDecoder.rasterHeight = 21180.0
# The image filename.
TLcdJAIRasterModelDecoder.fileName = wash_spot_small.gif
Decoding the TAB file format
The TAB file format points to a single image, and specifies its coordinate system and its position in this coordinate system.
The TLcdTABRasterModelDecoder
decodes TAB files, including the model reference. The image file can be in any format that is supported by the Java Advanced
Imaging library.
Decoding the RST file format
The RST file format, defined by Luciad , is similar to the TAB and JAI file format, but it allows defining multiple levels
and tiles. The tiles point to an entire dataset of images that can be decoded by the TLcdRasterModelDecoder
, which adds all the necessary referencing information.
The generic TLcdRasterModelDecoder
decodes properties files with extension
.rst
. An RST file defines a raster with any number of levels and tiles, and the reference information of the raster. Like a JAI
file, an RST file itself does not contain any image data. It points to the external files that can be decoded by the ILcdTileDecoder
that is specified in the RST file as well. Program: Example of an RST file shows an example of a simple RST file. It contains only a single level and a
single tile in GIF format, positioned in a grid reference with a transverse mercator projection and the WGS-84 geodetic datum.
The properties supported in RST files are described in detail in the reference documentation of
TLcdRasterModelDecoder
.
# Some general information.
TLcdRasterModelDecoder.displayName = DC_SPOT
TLcdRasterModelDecoder.sourceName = DC_SPOT2
TLcdRasterModelDecoder.typeName = gif
# The model reference.
TLcdRasterModelDecoder.ILcdModelReference.class = com.luciad.reference.TLcdGridReference
TLcdRasterModelDecoder.TLcdGridReference.geodeticDatum.ILcdGeodeticDatumFactory.class = \
com.luciad.geodesy.TLcdJPLGeodeticDatumFactory
TLcdRasterModelDecoder.TLcdGridReference.geodeticDatum.TLcdJPLGeodeticDatumFactory.geodeticDatumName = \
WGS\ 84
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
# The decoder that can decode the image.
TLcdRasterModelDecoder.ILcdTileDecoder.class = com.luciad.format.raster.TLcdGIFImageDecoder
TLcdRasterModelDecoder.pixelByteSize = 1
TLcdRasterModelDecoder.defaultPixel = 255
TLcdRasterModelDecoder.forcedTransparentColorIndex = 255
# The raster bounds in model coordinates.
TLcdRasterModelDecoder.ulx = 316393.8
TLcdRasterModelDecoder.uly = 4319175.0
TLcdRasterModelDecoder.rasterWidth = 10430.0
TLcdRasterModelDecoder.rasterHeight = 21180.0
# The raster size in pixels.
TLcdRasterModelDecoder.tilePixelWidth = 348
TLcdRasterModelDecoder.tilePixelHeight = 707
# The image filename.
TLcdRasterModelDecoder.fileName = wash_spot_small.gif
Decoding the EPSG, PROJ and REF file formats
The EPSG, PROJ, and REF file formats all define part of the necessary referencing information, namely the coordinate system
in which the raster is positioned. They are decoded by model reference decoders as described in ILcdModelReferenceDecoder implementations. These model reference decoders can be set on raster model decoders for which they are useful, for instance, TLcdBILModelDecoder
and TLcdGeoTIFFModelDecoder
.
Decoding the TFW file format
The TFW file format defines the necessary referencing information for a corresponding TIFF file, namely its position in a
given coordinate system. Similarly, JGW files provide positioning information for JPEG images, BLW files provide positioning
information for BIL images, and BPW files provide positioning information for BMP images. This format is decoded by the raster
model decoders for which this information is useful, for example: TLcdBILModelDecoder
, TLcdTFWRasterModelDecoder
, and TLcdGeoTIFFModelDecoder
.
Using an ILcdModelReferenceDecoder
As illustrated in Program: Using a reference decoder with a model decoder
and Program: Direct decoding of the reference from an external file
,
the reference decoder can be set as a property of the model decoder, or can be used directly to obtain a
reference that is manually set onto the model itself.
Using a reference decoder with a model decoder
Iterable<ILcdModelReferenceDecoder> modelReferenceDecoderIterable =
TLcdServiceLoader.getInstance(ILcdModelReferenceDecoder.class);
//Create a composite reference decoder based on all available
//ILcdModelReferenceDecoder implementations
ILcdModelReferenceDecoder referenceDecoder =
new TLcdCompositeModelReferenceDecoder(modelReferenceDecoderIterable);
//Configure the reference decoder on a model decoder.
//This example uses the model decoder for SHP files.
//
//Note that not all ILcdModelDecoder implementations allow to set one
TLcdSHPModelDecoder2 modelDecoder = new TLcdSHPModelDecoder2();
modelDecoder.setModelReferenceDecoder(referenceDecoder);
//Decode the model
//The model reference decoder will be used to decode the reference file
//which is located next to the source file
ILcdModel model = modelDecoder.decode("Data/Shp/Usa/rivers.shp");
Direct decoding of the reference from an external file
Iterable<ILcdModelReferenceDecoder> modelReferenceDecoderIterable =
TLcdServiceLoader.getInstance(ILcdModelReferenceDecoder.class);
//Create a composite reference decoder based on all available
//ILcdModelReferenceDecoder implementations
ILcdModelReferenceDecoder referenceDecoder =
new TLcdCompositeModelReferenceDecoder(modelReferenceDecoderIterable);
//Use it to decode a model reference file
ILcdModelReference modelReference =
referenceDecoder.decodeModelReference("Data/Shp/Usa/rivers.ref");
Parsing references from text
In some cases, there is no additional file that stores the coordinate reference system. Instead, the model reference is expressed as a code in the data file, in text format. The code used to identify the CRS is defined by widely accepted standards.
You can use an implementation of ILcdModelReferenceParser
to handle these cases, and convert the reference’s string representation into an ILcdModelReference
instance.
LuciadLightspeed provides the following implementations of ILcdModelReferenceParser
:
-
TLcdEPSGReferenceParser
: the European Petroleum Survey Group (EPSG, http://epsg.org) provides an extensive database of coordinate reference systems, uniquely identified by 4 or 5 digit numbers.TLcdEPSGReferenceParser
parses most commonly used coordinate reference systems in the EPSG database. -
TLcdAUTOReferenceParser
andTLcdAUTO2ReferenceParser
parse a CRS formatted according to the OpenGIS Web Map Service (WMS) 1.1.1 and 1.3.0 specifications. -
TLcdWKTReferenceParser
parses a CRS in the Well-Known Text format of the OpenGIS Specification. -
TLcdMIFModelReferenceParser
parses a CRS code formatted in the MapInfo Interchange Format (MIF). -
TLcdSpatialReferenceParser
parses CRS codes formatted in one of the Spatial Reference formats listed on http://spatialreference.org.
Setting model reference decoder priority
If your model decoder supports it, you can set a priority that determines which reference source is checked first: the reference within the main data file, or the reference stored in an external source.
You can use the reference decoder priority to deal with cases in which the model reference embedded in the data file might
be wrong or incomplete. For example, if the embedded reference in a GeoTIFF data file ( |
The priority influences the order in which the model reference decoder checks reference sources to determine the model reference.
It decides whether the decoder first tries an EXTERNAL
reference source or an EMBEDDED
reference source. If an error occurs while decoding the reference in the first source, the reference decoder falls back to
the other source.
This table lists the priorities supported by the decoders:
Priority | Explanation |
---|---|
EMBEDDED_FIRST |
The reference decoder first tries to decode the reference from reference information embedded in the main data file. If that
fails, the decoder tries to decode the reference from external reference source files such as
WKT ( |
EXTERNAL_FIRST |
The reference decoder first tries to decode the reference from external reference source files such as
WKT ( |
If the model decoder supports priority setting, you can use the corresponding system property to set the reference decoder priority:
Model decoder | System property |
---|---|
|
|
|
|
|
By default, the priority for these model decoders is EMBEDDED_FIRST
.
Storing a model reference
A model reference can be read from either a String
or a file. Therefore, it can also be formatted as a String
, using ILcdModelReferenceFormatter
, or stored in a file, using ILcdModelReferenceEncoder
. LuciadLightspeed provides encoding counterparts for most of the implementations in ILcdModelReferenceDecoder implementations and Parsing references from text. See the API reference for an overview of the available implementations.