Data Access → Drivers → GDAL

The GDAL data access driver allows applications to access raster data stored in several formats and systems. This driver is built on top of GDAL multi-access library.

This section describes the design and implementation issues of this driver and how it can be used by application developers.

The GDAL driver implements all the data access foundation classes as showned in the following class diagram.

The above implementation allows one to obtain a GDAL data source from the abstract factory using the “GDAL” identifier as is shown in the code snippet bellow:

te::da::DataSource* ds = te::da::DataSourceFactory::make("GDAL");

You can also open a GDAL data source as:

std::map<std::string, std::string> dsInfo;
 
dsInfo["SOURCE"] = "/data/raster-directory/";
 
te::da::DataSource* ds = te::da::DataSourceFactory::open("GDAL", dsInfo);

The following set of parameters can be used when accessing data through GDAL using the Data Access classes.

• URI: the name of a file or any other string used to open a dataset in GDAL. The value of this key must be something accepted by GDAL.
• SOURCE: the name of a directory containing raster files with formats supported by GDAL.

By now, the only supported data source creation is for directories. Dropping is also supported only for directories so far.

The only supported data type in this driver is te::dt::RASTER_TYPE.

The GDAL driver also implements all the raster foundation classes as showned in the following class diagram.

The above implementation allows one to access raster data through GDAL using the TerraLib Raster API simplified form.

std::map<std::string, std::string> rinfo;
 
rinfo["URI"] = "/data/geotiff/my-raster.tif";
 
te::rst::Raster* inraster = te::rst::RasterFactory::open("GDAL", rinfo);

SUPPORTED_EXTENSIONS - Will return a semicolon separated list of supported file extensions.

  std::auto_ptr< te::da::DataSource > dsPtr = te::da::DataSourceFactory::make( "GDAL" );
  QString filter;
  if( dsPtr.get() )
  {
    std::map< std::string, std::string > specCap = dsPtr->getCapabilities().getSpecificCapabilities();
 
    if( specCap.find( "SUPPORTED_EXTENSIONS" ) != specCap.end() )
    {
      std::string fileExtensions = specCap[ "SUPPORTED_EXTENSIONS" ];
 
      std::vector< std::string > tokens;
      te::common::Tokenize( fileExtensions, tokens, ";" );
 
      for( unsigned int tokensIdx = 0 ; tokensIdx < tokens.size() ; ++tokensIdx )
      {
        std::cout << tokens[ tokensIdx ];
      }
    }
  }

When using this driver to create a new empty raster you must know all the optional parameters needed by the underlying format. This section explains some special paramenters that can be used by each format.

The raster information used to create a new tiff file can contains the following creational parameters:

rinfo["URI"] = "/data/geotiff/my-raster.tif";
 
rinfo["BLOCKXSIZE"] = "256";
rinfo["BLOCKYSIZE"] = "256";
rinfo["TILED"] = "YES";
rinfo["INTERLEAVE"] = "BAND";

If a different number of bits is needed (e.g. 1, 2, or 4), the tag “NBITS” must be set:

rinfo["NBITS"] = "1"; // for 1bit raster

For a complete list see: http://www.gdal.org/frmt_gtiff.html.

If you need to create new raster file in formats other than Tiff, you need to inform the correct creational parameters as defined by GDAL. For a complete list of GDAL formats check the link http://www.gdal.org/formats_list.html and execute the following steps:

1. Check if the column “creation” to see if GDAL supports or not the creation of raster files in this format;
2. Check the code for the GDAL driver associated to the format. E.g. GeoTiff ⇒ “GTiff”
3. Include the creation parameters specific to this format

-------------------------------------------------------------------------------
Language          files     blank   comment      code    scale   3rd gen. equiv
-------------------------------------------------------------------------------
C++                  15       752       418      2072 x   1.51 =        3128.72
C/C++ Header         16       564       665       756 x   1.00 =         756.00
XML                   1         0         0        24 x   1.90 =          45.60
-------------------------------------------------------------------------------
SUM:                 32      1316      1083      2852 x   1.38 =        3930.32
-------------------------------------------------------------------------------

• This driver supports the use of directories as data sources. In this case, all image files recognized by GDAL will be a new dataset in the data source catalog.
• The driver supports the GDAL concept of subdatasets and it makes easy to work with them. Each subdataset is mapped to a dataset in the data source catalog. You just need to inform the general dataset string information and the driver will automatically discover the subdasets.
• The GDAL driver doesn't provide a query dialect nor a connection pooling.
• Most formats of GDAL provides a handle that is not thread-safe.

TO BE DONE