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.
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
ILcdModelReferenceDecoderis used to decode such files. LuciadLightspeed offers
ILcdModelReferenceDecoderimplementations that allow you to read Well-Known Text (WKT) or EPSG codes, for example. You can set the
ILcdModelReferenceDecoderas 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
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.
These are some of the available implementations of
.reffiles, a format created by Luciad defining the properties in a Java properties file.
.prjfiles 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.
.epsgfile is a text file containing a single decimal EPSG code, formatted as
EPSG:n. For details about EPSG codes, refer to http://epsg.org/. See the
TLcdEPSGReferenceParserreference documentation for a list of supported EPSG codes.
TLcdRPCModelReferenceDecoderto decode RPC files, which typically come with GeoTIFF files and have the extension
See the API reference documentation for more information about the available
There is also a composite model reference decoder implementation available (
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.
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.
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
# 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
The TAB file format points to a single image, and specifies its coordinate system and its position in this coordinate system.
TLcdTABRasterModelDecoder decodes TAB files, including the model reference. The image file can be in any format that is supported by the Java Advanced
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.
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
# 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
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,
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:
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");
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
LuciadLightspeed provides the following implementations of
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.
TLcdEPSGReferenceParserparses most commonly used coordinate reference systems in the EPSG database.
TLcdWKTReferenceParserparses a CRS in the Well-Known Text format of the OpenGIS Specification.
TLcdMIFModelReferenceParserparses a CRS code formatted in the MapInfo Interchange Format (MIF).
A model reference can be read from either a
String or a file. Therefore, it can also be formatted as a
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.