Modeling raster data as ILcdRaster objects

This article discusses the ILcdRaster and ILcdMultilevelRaster interfaces. Just like the ALcdImage class and its variants, they represent grids of pixels with geographical bounds. The ILcdRaster interfaces and their implementations pre-date ALcdImage, however. The ALcdImage classes offer more functionality: they allow working with multi-band and HDR imagery, and let you apply the image operators discussed in how to model raster data for image processing.

If you want to process or access decoded data, it is recommended to work with ALcdBasicImage and its related classes, instead of ILcdRaster or ILcdMultilevelRaster interface. You can use TLcdImageBuilder to create ALcdImage objects.

Note that ALcdImage and ILcdRaster and the related classes are compatible in the sense that a single Java object can extend from ALcdImage and implement ILcdRaster at the same time. All model decoders that produce raster data provide domain objects that do so.

What is an ILcdRaster?

An ILcdRaster is a basic extension of ILcdBounded and represents a 2D rectangular area consisting of rows and columns with equally sized tiles. Each tile (ILcdTile) is a matrix of integer values. The tiling structure allows a fast retrieval of data for a specific area in a specific resolution. What is an ILcdTile? provides more information on the usage of ILcdTile instances.

You can retrieve the value of a tile in two ways:

  • By using the retrieveValue method and specifying the raster coordinates. Note that for some data types, such as elevation data, the returned value can be the result of interpolation or filtering.

  • By using the retrieveTile method and specifying a tile row index and tile column index. The returned tile can then be queried for the actual value without interpolation or filtering. For more information on working with tiles, refer to What is an ILcdTile?.

The level of detail of a raster is determined by the pixel density of the raster. The pixel density provides an estimate for the number of pixels per unit surface area in model coordinates. The higher the pixel density, the more detailed the raster. You can retrieve the pixel density by using the method getPixelDensity. This allows you to determine whether a raster is too detailed or not detailed enough for visualization or for other purposes. Especially since rasters are typically loaded lazily, a simple check of the pixel density can prevent the loading of massive amounts of data with the wrong level of detail.

For visualization purposes, you can set a java.awt.image.ColorModel on the raster by using the setColorModel method. Because ILcdRaster implements ILcdCache, it is also possible to attach cached data to an ILcdRaster. The main implementation of the ILcdRaster interface is the TLcdRaster class. For more information on ILcdRaster, TLcdRaster, their properties and methods, refer to the API reference.

An ILcdRaster can also be part of an ILcdMultilevelRaster or an ILcdMultivaluedRaster as described in the following sections.

What is an ILcdMultilevelRaster?

An ILcdMultilevelRaster is essentially a list of ILcdRaster instances covering the same area at different levels of detail. The different levels are ordered by an increasing pixel density, from the least detailed to the most detailed level.

An ILcdMultilevelRaster has bounds of its own, which are the union of the bounds of the rasters that it contains. The bounds of the rasters are typically identical but can be different, when rasters from different sources cover approximately the same area, for example. The main implementation of the ILcdMultilevelRaster interface is the TLcdMultilevelRaster class. For more information on their properties and methods, refer to the API reference.

What is an ILcdTile?

An ILcdTile raster tile is a matrix of integer values. A tile has a resolution expressed in pixels and a pixel size expressed in bits. There are two ways to retrieve the contents of a tile:

  • As individual values, by using the method retrieveValue with coordinates expressed in pixels.

  • As images, by using the method createImage. The tile contents are retrieved in bulk.

Similar to an ILcdRaster, an ILcdTile can have a ColorModel for visualization purposes. The major difference between an ILcdRaster and an ILcdTile is that an ILcdRaster is defined in model coordinates (doubles) and an ILcdTile in pixel coordinates (integer).

It is not required that all tiles in a raster have the same tile resolution. For example, a raster representing a DTED data set covers a rectangular area in geodetic coordinates. Each tile covers a cell of 1 degree by 1 degree, but tiles near the poles have a lower resolution than tiles near the equator.

ILcdRaster and ILcdTile sizes

The tiles in a raster usually all have the same size defined by the tile width and the tile height, in the coordinates of the associated reference system. In some cases, the tiles in the last grid column and the last grid row may be truncated to smaller sizes. This may happen if the number of columns times the nominal tile width is larger than the raster width. Or if the number of rows times the nominal tile height is larger than the raster height. For example, a raster with a size of 5000m by 2500m may have 5 by 3 tiles with nominal sizes of 1000m by 1000m. The tiles in the last row are then truncated to 1000m by 500m. Figure 1, “Properties of an ILcdRaster and its tiles” provides a schematic overview of a raster and its tiles.

Figure 1. Properties of an ILcdRaster and its tiles