Raster

The Raster module provides the base classes foundation for handling geographical data such as remote sensing imagery data. The raster data structure can be viewed as a matrix of cells or pixels associated with spatial locations forming a regular grid. By design each cell can be viewed, individually, as a multi-dimensional data.

This module defines only the abstract classes and therefore implementations must be provided. We call these implementations: raster drivers. TerraLib provides raster drivers on top of other libraries (GDAL, GRIB API, RasterLite), DBMS (PostGIS Raster, MySQL, SQLite) and one In-Memory implementation.

This section explains the design an implementation of this module.

The following class diagram shows the main classes in this module:

The Raster class is an abstract class and it is the main raster data container.

A raster is composed by raster bands. A band is represented by the abstract class Band.

For detailed documentation, find the doxygen documentation of Raster class.

One Raster is composed by one or more bands. Depending on the raster configuration, two data storage mechanisms are possible:

• One raster per band. One example is the CBERS-2B:
  • CBERS_2B_CCD1XS_20080223_148_120_L2_BAND2.tif (raster 1)
  • CBERS_2B_CCD1XS_20080223_148_120_L2_BAND3.tif (raster 0)
  • CBERS_2B_CCD1XS_20080223_148_120_L2_BAND4.tif (raster 2)
  • …

• The second mechanism is to provide one raster with multiple bands. One example is the World View II satellite:
  • WV2_RASTER.tif:
    • WV2_MUL_2_BLUE (band 2)
    • WV2_MUL_3_GREEN (band 1)
    • WV2_MUL_4_YELLOW
    • WV2_MUL_5_RED (band 0)
    • …

Each band is described by a BandProperty.

Follow this link to reach the detailed information of BandProperty class generated by doxygen.

The summarized information are here:

• the band index.
• the data type of the elements in the band.
• a brief description of the band.
• a list of metadata where each element consists of a key-value pair.
• the minimum occurring value in the band.
• the maximum occurring value in the band.
• the standard deviation of the occurring values.
• the mean of the occurring values.
• a value indicating elements where there is no data.
• offset value to be added to grid values for the sample dimension.
• scale value which is multiplied to grid values for this sample dimension.
• a set of categoric names for the values contained in a dimension.
• the color interpretation.
• the pallete interpretation and its color palette.
• the unit of measure of the values.

The BandProperty class also keeps information on how the band is arranged in blocks. Besides the above information it also provides:

• Block width and height (in pixels or elements).
• The number of blocks in x and y directions.

A raster also has a grid that defines its spatial support (a rectified grid).

Follow this link to reach the detailed documentation of grid class generated by doxygen, but basically the Grid class contains:

• an envelope that defines its extent
• the identifier of the spatial reference system associated to the grid points
• the number of columns
• the number of rows
• and a list of 6 coefficients describing an affine transformation that maps raster positions in pixel/row coordinates to georeferenced coordinates (in the srs defined by srid).

The list of 6 coefficients contains:

• [0] is the x coordinate of the upper left cell in raster
• [1] is the width of the elements in the raster
• [2] is the element rotation in x, is set to 0 if a north up raster
• [3] is the y coordinate of the upper left cell in raster
• [4] is the element rotation in y, is set to 0 if a north up raster
• [5] is the height of the elements in the raster (negative)

They are used to interchange the raster space (Column, Row) with the projection coordinates (X, Y) space, according to the following equation:

X = [0] + C * [1] + R * [2]
Y = [3] + C * [4] + R * [5]

In order to have access to cell values one should access the appropriated Band or use the pixel access methods in the Raster class.

double value;
std::complex<double> cvalue; // cvalue.real() is the real part, and cvalue.imag() is the imaginary part, when available
std::vector<std::complex<double> > values;
 
// for example, to get the value in position (10,50) from band 2 in myraster
 
// method 1, using Raster class
myraster->getValue(10, 50, value, 2);
 
// method 2, using Raster class
myraster->getValue(10, 50, cvalue, 2);
value = cvalue.real();
 
// method 3, using vector of complex data in Raster class
myraster->getValues(10, 50, values);
value = values[2].real();
 
// method 4, using Band class
myraster->getBand(2)->getValue(10, 50, value);
 
// method 5, using Band class
myraster->getBand(2)->getValue(10, 50, cvalue);
value = cvalue.real();

There are two ways to handle rasters in TerraLib:

• You can use it as a regular library
• or you can use it embedded in the TerraLib Data Access API.

For using as a regular library you can use the RasterFactory class in order to start working with raster data.

Follow this link to reach the detailed documentation of RasterFactory class generated by doxygen.

The following code snippet shows how to open a raster file for reading using the default raster library support:

std::map<std::string, std::string> rinfo;
 
rinfo["URI"] = "/dir/myfile.tif";
 
te::rst::Raster* r = te::rst::RasterFactory::make();
 
r->open(rinfo, te::common::RAccess);
 
// your code manipulating the raster goes here!
 
delete r;

If you prefer using another raster library support for reading a raster file:

std::map<std::string, std::string> rinfo;
 
rinfo["URI"] = "/dir/myfile.tif";
 
te::rst::Raster* r = te::rst::RasterFactory::make("MY_OWN_IMPLEMENTATION");
 
r->open(rinfo, te::common::RAccess);
 
// your code manipulating the raster goes here!
 
delete r;

The following code snippet shows how to create a new raster file:

te::rst::Grid* grid = new te::rst::Grid(...);
 
te::rst::BandProperty* b1 = new te::rst::BandProperty(...);
 
te::rst::BandProperty* b2 = new te::rst::BandProperty(...);
 
te::rst::BandProperty* b3 = new te::rst::BandProperty(...);
 
std::vector<te::rst::BandProperty*> bands; bands.push_back(b1); bands.push_back(b2); bands.push_back(b3);
 
std::map<std::string, std::string> rinfo;
 
rinfo["URI"] = "/dir/myfile.tif";
 
te::rst::Raster* r = te::rst::RasterFactory::make(grid, bands, rinfo);
 
// R is ready for working!!
 
delete r;

If you want to use a more specific library for creating a new raster file:

te::rst::Grid* grid = new te::rst::Grid(...);
 
te::rst::BandProperty* b1 = new te::rst::BandProperty(...);
 
te::rst::BandProperty* b2 = new te::rst::BandProperty(...);
 
te::rst::BandProperty* b3 = new te::rst::BandProperty(...);
 
std::vector<te::rst::BandProperty*> bands; bands.push_back(b1); bands.push_back(b2); bands.push_back(b3);
 
std::map<std::string, std::string> rinfo;
 
rinfo["URI"] = "/dir/myfile.tif";
 
te::rst::Raster* r = te::rst::RasterFactory::make("MY_OWN_IMPLEMENTATION", grid, bands, rinfo);
 
// R is ready for working!!
 
delete r;

For using raster in the data source API… <color red>!!forma normal!!</color>

Follow this link to reach the updated documentation of RasterProperty class generated by doxygen.

-------------------------------------------------------------------------------
Language          files     blank   comment      code    scale   3rd gen. equiv
-------------------------------------------------------------------------------
C++                  15       798       391      2442 x   1.51 =        3687.42
C/C++ Header         22      1457      1953      2022 x   1.00 =        2022.00
-------------------------------------------------------------------------------
SUM:                 37      2255      2344      4464 x   1.28 =        5709.42
-------------------------------------------------------------------------------

• We need to explore better the block-size and number of pixels: there are cases where we must do some checks in the last blocks.
• We need to revise overviews/pyramids.
• See dependences GDAL/OGR
• In future releases we will provide raster support over Web Services.

TO BE DONE