Why do it?

You have a raster-based image file and you want to add it to a LuciadLightspeed view. However, the LuciadLightspeed decoder only returns errors when you are decoding the file. Those errors are caused by a lack of georeferencing information for the image. LuciadLightspeed does not know how it needs to position the image.

For instance, when you try to decode a TIFF image file with a TLcdGeoTIFFModelDecoder, you receive these types of warnings:

  • missing model reference

  • Could not decode model reference. Attempts: model reference from TAB file (file not found <filename>.TAB), model reference from reference decoder (file not found <filename>.ref)

In this case, your TIFF file does not contain the correct georeferencing information, and does not qualify as a georeferenced GeoTIFF file. You will have to specify or complete the georeferencing information before LuciadLightspeed allows you to decode the image.

How to position a raster-based image

To add a raster image in a LuciadLightspeed view, you need to provide:

  • A reference file specifying the coordinate reference system associated with the image.

  • A world file, a plain text file that provides information about the bounding box of the image. LuciadLightspeed can derive image location, resolution and size from the bounding box information.

The LuciadLightspeed raster model decoders use this information to translate image coordinates to earth coordinates. Both files need to be placed next to the image file in the directory hierarchy.

How to construct a reference file

You can choose to specify the coordinate reference system in one of multiple file types.

For more information, see Decoding model references.

If necessary, you can create the standard file types yourself. In a .prj file, for example, you specify the coordinate reference system in the WKT format. Next, you store the file alongside the image file.

myImage.prj file 
GEOGCS["WGS_1984",DATUM["WGS_1984",SPHEROID["WGS_1984",6378137.0,298.257223563],TOWGS84[0,0,0]],PRIMEM["Greenwich",0.0],UNIT["Degrees",0.0]]

An .epsg file looks like this:

myImage.epsg file 
EPSG:4326

The provider of the image file determines which coordinate reference system applies, and usually offers that information with the file. If you cannot find that information, contact the image provider.

How to construct a world file

The format of your image file determines the extension of the world file. If you have a TIFF file, for instance, you need to save the world file with the .tfw extension.

Image format File extension

BMP

.bpw

GIF

.gfw

JPEG

.jgw

PNG

.pgw

TIFF

.tfw

A world file always provides its information in the same line sequence:

  1. Pixel width in map units per pixel

  2. Y-axis rotation

  3. X-axis rotation

  4. Negative pixel height in map units per pixel

  5. X-coordinate of the center of the upper left pixel

  6. Y-coordinate of the center of the upper left pixel

An image that does not need to be rotated or rectified could have the following world file, for instance:

myImage.bpw
0.00007500
0.
0.
-0.00006250
21.60003750
42.37496875

For more information about determining the image positioning values for a World file, see link:en.wikipedia.org/wiki/World_file

Decoding the image file

Once the reference file and world file are in place, you can use a world file model decoder, TLcdTFWRasterModelDecoder, to decode the file into an ILcdModel. The following code snippet shows how to decode the image.png file with TLcdTFWRasterModelDecoder.

Program: Decoding an image file
TLcdTFWRasterModelDecoder tfwRasterModelDecoder = new TLcdTFWRasterModelDecoder();
ILcdModel model = tfwRasterModelDecoder.decode("image/image.pgw");

Alternatively, you can use the LuciadLightspeed image framework API to create an ALcdImage, and work from there. For instance, you can use a TLcdImageBuilder to construct an image from its georeference and position information:

Program: Using TLcdImageBuilder to add an image
RenderedImage image = ImageIO.read(new File("image/image.png"));
ALcdBasicImage geoImage =
   TLcdImageBuilder.newBuilder().image(image).imageReference(imageGeoReference).bounds(imageBounds).buildBasicImage();

Lucy also requires reference and positioning information to open an image. To load an image in Lucy, open the world file first. Lucy then automatically loads the image it belongs to.