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:

  1. Retrieving it from the data. In this case, the CRS is included in the data files.

  2. 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 offers ILcdModelReferenceDecoder implementations that allow you to read Well-Known Text (WKT) or EPSG codes, for example. You can set the ILcdModelReferenceDecoder as a property of the model decoder, so that the reference is constructed and set directly on the decoded model.

  3. 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 the ILcdModelDecoder 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:

See the API reference documentation for more information about the available ILcdModelReferenceDecoder implementations.

There is also a composite model reference decoder implementation available (TLcdCompositeModelReferenceDecoder) which can handle all those files. See the class javadoc of the composite decoder for example usages.

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.

Program: Example of a JAI file
# 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.

Program: Example of an RST file
# 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.

Program: 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");
Program: 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:

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 (.tif/.tiff) is wrong or incomplete, you can create an external file with the correct reference, and set the system property: com.luciad.format.raster.TLcdGeoTIFFModelDecoder.referenceDecoderPriority=EXTERNAL_FIRST.

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:

Table 1. Supported model reference decoder priorities
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 (.prj), REF (.ref) and EPSG (.epsg).

EXTERNAL_FIRST

The reference decoder first tries to decode the reference from external reference source files such as WKT (.prj), REF (.ref) and EPSG (.epsg). If that fails, the decoder tries to decode the reference from the main data file embedded with reference information.

If the model decoder supports priority setting, you can use the corresponding system property to set the reference decoder priority:

Table 2. Model decoders supporting model reference decoder priority
Model decoder System property

TLcdGeoTIFFModelDecoder

com.luciad.format.raster.TLcdGeoTIFFModelDecoder.referenceDecoderPriority

TLcdLASModelDecoder

com.luciad.format.las.TLcdLASModelDecoder.referenceDecoderPriority

TLcdE57ModelDecoder

com.luciad.format.e57.TLcdE57ModelDecoder.referenceDecoderPriority

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.