Utils.h
Go to the documentation of this file.
1 /* Copyright (C) 2008 National Institute For Space Research (INPE) - Brazil.
2 
3  This file is part of the TerraLib - a Framework for building GIS enabled applications.
4 
5  TerraLib is free software: you can redistribute it and/or modify
6  it under the terms of the GNU Lesser General Public License as published by
7  the Free Software Foundation, either version 3 of the License,
8  or (at your option) any later version.
9 
10  TerraLib is distributed in the hope that it will be useful,
11  but WITHOUT ANY WARRANTY; without even the implied warranty of
12  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13  GNU Lesser General Public License for more details.
14 
15  You should have received a copy of the GNU Lesser General Public License
16  along with TerraLib. See COPYING. If not, write to
17  TerraLib Team at <terralib-team@terralib.org>.
18  */
19 
20 /*!
21  \file terralib/gdal/Utils.h
22 
23  \brief Utilitary functions to access GDAL and match some of its concepts to TerraLib concepts.
24  */
25 
26 #ifndef __TERRALIB_GDAL_INTERNAL_UTILS_H
27 #define __TERRALIB_GDAL_INTERNAL_UTILS_H
28 
29 // TerraLib
30 #include "../raster/BandProperty.h"
31 #include "../raster/Enums.h"
32 #include "../raster/Raster.h"
33 #include "../common/Translator.h"
34 #include "Config.h"
35 #include "Band.h"
36 #include "Raster.h"
37 
38 // GDAL
39 #include <gdal_priv.h>
40 
41 // STL
42 #include <map>
43 #include <string>
44 #include <vector>
45 #include <set>
46 
47 #include <boost/filesystem.hpp>
48 #include <boost/thread/mutex.hpp>
49 
50 namespace te
51 {
52  namespace gm {class Envelope; class Geometry;}
53 
54  namespace rst {class Grid; class RasterProperty; }
55 
56  namespace gdal
57  {
58  /*!
59  \brief GDAL driver metadata.
60  */
62  {
63  std::string m_driverName; //!< Driver name (driver description).
64  std::string m_extension; //!< File extension (DMD_EXTENSION).
65  std::string m_longName; //!< File long name (DMD_LONGNAME).
66  bool m_subDatasetsSupport; //!< true if the driver has support for sub-datasets (DMD_SUBDATASETS).
67  };
68 
69  /*!
70  \brief It translates a GDAL DataType to a TerraLib DataType.
71  */
72  inline int GetTeDataType(GDALDataType gt)
73  {
74  switch(gt)
75  {
76  case GDT_Byte : return te::dt::UCHAR_TYPE;
77  case GDT_UInt16 : return te::dt::UINT16_TYPE;
78  case GDT_Int16 : return te::dt::INT16_TYPE;
79  case GDT_UInt32 : return te::dt::UINT32_TYPE;
80  case GDT_Int32 : return te::dt::INT32_TYPE;
81  case GDT_Float32 : return te::dt::FLOAT_TYPE;
82  case GDT_Float64 : return te::dt::DOUBLE_TYPE;
83 
84  case GDT_CInt16 : return te::dt::CINT16_TYPE;
85  case GDT_CInt32 : return te::dt::CINT32_TYPE;
86  case GDT_CFloat32 : return te::dt::CFLOAT_TYPE;
87  case GDT_CFloat64 : return te::dt::CDOUBLE_TYPE;
88 
89  default : return te::dt::UNKNOWN_TYPE;
90  }
91  }
92 
93  /*!
94  \brief It translates a TerraLib DataType to a GDAL DataType.
95  */
96  inline GDALDataType GetGDALDataType(int tet)
97  {
98  switch(tet)
99  {
100  case te::dt::UCHAR_TYPE : return GDT_Byte;
101  case te::dt::CHAR_TYPE : return GDT_Byte;
102  case te::dt::UINT16_TYPE : return GDT_UInt16;
103  case te::dt::INT16_TYPE : return GDT_Int16;
104  case te::dt::UINT32_TYPE : return GDT_UInt32;
105  case te::dt::INT32_TYPE : return GDT_Int32;
106  case te::dt::FLOAT_TYPE : return GDT_Float32;
107  case te::dt::DOUBLE_TYPE : return GDT_Float64;
108 
109  case te::dt::CINT16_TYPE : return GDT_CInt16;
110  case te::dt::CINT32_TYPE : return GDT_CInt32;
111  case te::dt::CFLOAT_TYPE : return GDT_CFloat32;
112  case te::dt::CDOUBLE_TYPE : return GDT_CFloat64;
113 
114  default : return GDT_Unknown;
115  }
116  }
117 
118  /*!
119  \brief It translates a GDAL ColorInterpretation to a TerraLib ColorInterpretation.
120  */
121  inline te::rst::ColorInterp GetTeColorInterpretation(GDALColorInterp gci)
122  {
123  switch(gci)
124  {
125  case GCI_GrayIndex : return te::rst::GrayIdxCInt;
126  case GCI_PaletteIndex : return te::rst::PaletteIdxCInt;
127  case GCI_RedBand : return te::rst::RedCInt;
128  case GCI_GreenBand : return te::rst::GreenCInt;
129  case GCI_BlueBand : return te::rst::BlueCInt;
130  case GCI_AlphaBand : return te::rst::AlphaCInt;
131  case GCI_HueBand : return te::rst::HueCInt;
132  case GCI_SaturationBand : return te::rst::SatCInt;
133  case GCI_LightnessBand : return te::rst::LigCInt;
134  case GCI_CyanBand : return te::rst::CyanCInt;
135  case GCI_MagentaBand : return te::rst::MagentaCInt;
136  case GCI_YellowBand : return te::rst::YellowCInt;
137  case GCI_BlackBand : return te::rst::KeyCInt;
138  case GCI_YCbCr_YBand : return te::rst::YCInt;
139  case GCI_YCbCr_CbBand : return te::rst::CbCInt;
140  case GCI_YCbCr_CrBand : return te::rst::CrCInt;
141  default : return te::rst::UndefCInt;
142  }
143  }
144 
145  /*!
146  \brief It translates a TerraLib ColorInterpretation to a GDAL ColorInterpretation.
147  */
149  {
150  switch(ci)
151  {
152  case te::rst::GrayIdxCInt : return GCI_GrayIndex;
153  case te::rst::PaletteIdxCInt : return GCI_PaletteIndex;
154  case te::rst::RedCInt : return GCI_RedBand;
155  case te::rst::GreenCInt : return GCI_GreenBand;
156  case te::rst::BlueCInt : return GCI_BlueBand;
157  case te::rst::AlphaCInt : return GCI_AlphaBand;
158  case te::rst::HueCInt : return GCI_HueBand;
159  case te::rst::SatCInt : return GCI_SaturationBand;
160  case te::rst::LigCInt : return GCI_LightnessBand;
161  case te::rst::CyanCInt : return GCI_CyanBand;
162  case te::rst::MagentaCInt : return GCI_MagentaBand;
163  case te::rst::YellowCInt : return GCI_YellowBand;
164  case te::rst::KeyCInt : return GCI_BlackBand;
165  case te::rst::YCInt : return GCI_YCbCr_YBand;
166  case te::rst::CbCInt : return GCI_YCbCr_CbBand;
167  case te::rst::CrCInt : return GCI_YCbCr_CrBand;
168  default : return GCI_Undefined;
169  }
170  }
171 
172  /*!
173  \brief It translates a GDAL Pallete Interpretation to a TerraLib Pallete Interpretation.
174  */
176  {
177  switch (gpi)
178  {
179  case GPI_Gray : return te::rst::GrayPalInt;
180  case GPI_RGB : return te::rst::RGBPalInt;
181  case GPI_CMYK : return te::rst::CMYKPalInt;
182  case GPI_HLS : return te::rst::HSLPalInt;
183  default : return te::rst::UndefPalInt;
184  }
185  }
186 
187  /*!
188  \brief It translates a TerraLib interpolation method into a GDAL ressampling method name string.
189  */
190  inline std::string GetGDALRessamplingMethod(te::rst::InterpolationMethod interpolationMethod )
191  {
192  switch(interpolationMethod)
193  {
194  case te::rst::NearestNeighbor : return std::string( "NEAREST" );
195  case te::rst::Bilinear : return std::string( "AVERAGE" );
196  case te::rst::Bicubic : return std::string( "CUBIC" );
197  default : throw Exception(TE_TR("Invalid interpolation method"));
198  }
199  }
200 
201  /*!
202  \brief Gets the grid definition from a GDAL dataset.
203  \param gds A pointer to a GDAL dataset.
204  \return A pointer to the grid definition from a GDAL dataset. Caller takes its ownership.
205  */
206  TEGDALEXPORT te::rst::Grid* GetGrid(GDALDataset* gds);
207 
208  /*!
209  \brief Gets the grid definition from a GDAL dataset.
210  \param gds A pointer to a GDAL dataset.
211  \param multiResLevel Multi resolution level (use -1 to use the original resolution).
212  \return A pointer to the grid definition from a GDAL dataset. Caller takes its ownership.
213  */
214  TEGDALEXPORT te::rst::Grid* GetGrid(GDALDataset* gds, const int multiResLevel );
215 
216  /*!
217  \brief Gets the list of bands definition from a GDAL dataset.
218  \param gds A pointer to a GDAL dataset.
219  \param bprops A reference to a vector to be filled with the bands description extracted from a dataset.
220  \note The caller of this method must take the ownership of the returned properties.
221  */
222  TEGDALEXPORT void GetBandProperties(GDALDataset* gds, std::vector<te::rst::BandProperty*>& bprops);
223 
224  /*!
225  \brief Gets the properties of a single band from a GDAL dataset.
226 
227  \param gband A pointer to a GDAL Raster Band.
228 
229  \param bandIndex The band index (starting from 0).
230 
231  \return A band property.
232 
233  \note The caller of this method must take the ownership of the returned properties.
234  */
235  te::rst::BandProperty* GetBandProperty(GDALRasterBand* gband, const unsigned int bandIndex );
236 
237  /*!
238  \brief Gets the list of bands from a GDAL dataset.
239 
240  \param rst A pointer to the raster.
241  \param bands A reference to a vector to be filled with the bands extracted from a dataset.
242  \note The caller of this method must take the ownership of the returned properties.
243  */
244  void GetBands(te::gdal::Raster* rst, std::vector<te::gdal::Band*>& bands);
245 
246  /*!
247  \brief Gets the list of bands from a GDAL dataset.
248 
249  \param rst A pointer to the raster.
250  \param multiResLevel Multi-resolution pyramid level (value -1 -> overviews disabled).
251  \param bands A reference to a vector to be filled with the bands extracted from a dataset.
252  \note The caller of this method must take the ownership of the returned properties.
253  */
254  bool GetBands(te::gdal::Raster* rst, int multiResLevel, std::vector<te::gdal::Band*>& bands);
255 
256  /*!
257  \brief Gets the complete description from a GDAL dataset.
258  \param strAccessInfo A a string to be used by GDAL to access the raster.
259  \return A pointer to the raster description from a GDAL dataset. Caller takes its ownership.
260  */
261  te::rst::RasterProperty* GetRasterProperty(std::string strAccessInfo);
262 
263  /*!
264  \brief Creates a raster data using GDAL.
265 
266  \param g Raster grid info.
267  \param bands Band info.
268  \param optParams A vector of optional parameters that are valid only for some data formats.
269 
270  \return A pointer to a GDALDataset if it succeeds or a NULL pointer otherwise. Caller is responsible for closing it.
271 
272  \exception Exception It throws an exception if the raster can not be created.
273  */
274  GDALDataset* CreateRaster(te::rst::Grid* g, const std::vector<te::rst::BandProperty*>& bands, const std::map<std::string, std::string>& optParams);
275 
276  /*!
277  \brief Creates a raster data using GDAL.
278  \param name The name of the dataset to create. UTF-8 encoded.
279  \param g Raster grid info.
280  \param bands Band info.
281  \param optParams A vector of optional parameters that are valid only for some data formats.
282 
283  \return A pointer to a GDALDataset if it succeeds or a NULL pointer otherwise. Caller is responsible for closing it.
284 
285  \exception Exception It throws an exception if the raster can not be created.
286  */
287  GDALDataset* CreateRaster(const std::string& name, te::rst::Grid* g, const std::vector<te::rst::BandProperty*>& bands, const std::map<std::string, std::string>& optParams);
288 
289  /*!
290  \brief Gets the extent of a raster data decoded by GDAL.
291  \param strAccessInfo A a string to be used by GDAL to access the raster.
292  \return A pointer to raster extent. Caller takes its ownership.
293  */
294  te::gm::Envelope* GetExtent(std::string strAccessInfo);
295 
296  /*!
297  \brief Get a handle to a raster file.
298  \param filename File name (path included).
299  \param policy The access permission requested.
300  \return A pointer to GDAL dataset if it succeeds or a NULL pointer otherwise.
301  */
302  GDALDataset* GetRasterHandle(std::string strAccessInfo, te::common::AccessPolicy policy = te::common::RAccess);
303 
304  /*!
305  \brief Returns a PostGIS connection string from the set connection information.
306  The connection string is to be used as a dataset name in GDAL data model. See also http://trac.osgeo.org/gdal/wiki/frmts_wtkraster.html.
307  \param connInfo The connection parameters.
308  \return Returns a PostGIS connection string from the set connection information.
309  */
310  std::string MakePGConnectionStr(const std::map<std::string, std::string>& dsInfo);
311 
312  /*!
313  \brief Reprojects a raster to another SRS.
314  \param rin The input raster file. Do not pass a null pointer.
315  \param rout The new output raster. Do not pass a null pointer.
316  \return true If the reprojection was done or false otherwise.
317  */
318  bool ReprojectRaster(te::rst::Raster const * const rin, te::rst::Raster* rout);
319 
320  /*!
321  \brief It returns the GDAL driver name associated to a data source name.
322 
323  \param dsName the name of the file that represents the data source.
324 
325  \return the GDAL driver name, or its identifier if succeeds and a null string otherwise.
326  */
327  std::string GetDriverName(const std::string& dsName);
328 
329  /*!
330  \brief It returns a GDAL connection string from the given map.
331 
332  \param connInfo An associative conteiner with data source connection info.
333 
334  \return a GDAL connection string from the given map.
335 
336  \exception Exception It throws an exception if no connection info exists in the input map.
337  */
338  std::string GetGDALConnectionInfo(const std::map<std::string, std::string>& connInfo);
339 
340  /*!
341  \brief It returns the Sub DataSet name from the given name or the same name.
342 
343  \param name The Full SubDataSet string name.
344 
345  \param driverName The driver name.
346 
347  \return The Sub DataSet name from the given name.
348  */
349  std::string GetSubDataSetName(const std::string& name, const std::string& driverName);
350 
351  /*!
352  \brief It returns true if GDAL recognizes the given SRS id.
353 
354  \param srid The SRS identifier.
355 
356  \return true if GDAL recognizes the given SRS id or false otherwise.
357  */
358  bool RecognizesSRID(unsigned int srid);
359 
360  /*!
361  \brief Vectorizes a given raster band, using GDALPolygonize function.
362 
363  \param band The band to vectorize.
364  \param geometries A reference to a vector of geometries. Will be filled with geometries found in band.
365  */
366  TEGDALEXPORT void Vectorize(GDALRasterBand* band, std::vector<te::gm::Geometry*>& geometries);
367 
368  /*!
369  \brief Rasterizes a given vector of geometries, using GDALRasterizeGeometries function.
370 
371  \param geometries A vector of geometries to be rasterized.
372  \param outraster A reference to the GDAL dataset where the rasterized geometries will be drawn.
373  */
374  TEGDALEXPORT void Rasterize(std::vector<te::gm::Geometry*> geometries, GDALDataset* outraster);
375 
376  /*!
377  \brief Returns true if the given URI is related to a sub-dataset.
378  \param uri The given URI.
379  \return true if the given URI is related to a sub-dataset.
380  */
381  bool IsSubDataSet( const std::string& uri );
382 
383  /*!
384  \brief It returns the parent dataset name from a Sub DataSet name.
385  \param subDataSetName The Full SubDataSet string name.
386  \return the parent dataset name from a Sub DataSet name.
387  \note If the given name does not refers to a sub-dataset it will be returned.
388  */
389  std::string GetParentDataSetName(const std::string& subDataSetName);
390 
391  /*!
392  \brief Returns a reference to a static mutex initialized when this module is initialized.
393  \return Returns a reference to a static mutex initialized when this module is initialized.
394  */
395  TEGDALEXPORT boost::mutex& getStaticMutex();
396 
397  /*!
398  \brief Returns metadata from all registered GDAL drivers (key: driver name).
399  \return Metadata from all registered GDAL drivers (key: driver name).
400  */
401  const std::map< std::string, DriverMetadata >& GetGDALDriversMetadata();
402 
403  /*!
404  \brief Returns a map all GDAL supported Upper-case extensions to their respective driver names.
405  \return Returns a map all GDAL supported Upper-case extensions to their respective driver names.
406  */
407  const std::multimap< std::string, std::string >& GetGDALDriversUCaseExt2DriversMap();
408  } // end namespace gdal
409 } // end namespace te
410 #endif
GDALColorInterp GetGDALColorInterpretation(te::rst::ColorInterp ci)
It translates a TerraLib ColorInterpretation to a GDAL ColorInterpretation.
Definition: Utils.h:148
HSL indexed palette interpretation.
Definition: Enums.h:86
Palette indexes color interpretation.
Definition: Enums.h:58
This is a class that represents a GDAL Raster.
bool m_subDatasetsSupport
true if the driver has support for sub-datasets (DMD_SUBDATASETS).
Definition: Utils.h:66
GDALDataType GetGDALDataType(int tet)
It translates a TerraLib DataType to a GDAL DataType.
Definition: Utils.h:96
Near neighborhood interpolation method.
Definition: Enums.h:95
const std::multimap< std::string, std::string > & GetGDALDriversUCaseExt2DriversMap()
Returns a map all GDAL supported Upper-case extensions to their respective driver names...
Hue channel color interpretation.
Definition: Enums.h:63
te::rst::PaletteInterpretation GetTePaletteInterpretation(GDALPaletteInterp gpi)
It translates a GDAL Pallete Interpretation to a TerraLib Pallete Interpretation. ...
Definition: Utils.h:175
Alpha channel color interpretation.
Definition: Enums.h:62
void GetBands(te::gdal::Raster *rst, std::vector< te::gdal::Band * > &bands)
Gets the list of bands from a GDAL dataset.
std::string m_driverName
Driver name (driver description).
Definition: Utils.h:63
Index into a lookup table.
Definition: Enums.h:57
Lightness color interpretation.
Definition: Enums.h:65
te::rst::ColorInterp GetTeColorInterpretation(GDALColorInterp gci)
It translates a GDAL ColorInterpretation to a TerraLib ColorInterpretation.
Definition: Utils.h:121
ColorInterp
Color model component use.
Definition: Enums.h:54
A raster band description.
Definition: BandProperty.h:61
RGB indexed palette interpretation.
Definition: Enums.h:84
This class represents Raster data.
Definition: Raster.h:61
Base exception class for plugin module.
Definition: Exception.h:42
te::rst::RasterProperty * GetRasterProperty(std::string strAccessInfo)
Gets the complete description from a GDAL dataset.
TEGDALEXPORT te::rst::Grid * GetGrid(GDALDataset *gds)
Gets the grid definition from a GDAL dataset.
Gray indexed palette interpretation.
Definition: Enums.h:83
It gives access to values in one band (dimension) of a raster.
#define TEGDALEXPORT
You can use this macro in order to export/import classes and functions from this module.
Definition: Config.h:67
GDALDataset * GetRasterHandle(std::string strAccessInfo, te::common::AccessPolicy policy=te::common::RAccess)
Get a handle to a raster file.
Red channel color interpretation.
Definition: Enums.h:59
#define TE_TR(message)
It marks a string in order to get translated.
Definition: Translator.h:346
Cyan color interpretation.
Definition: Enums.h:66
InterpolationMethod
Allowed interpolation methods.
Definition: Enums.h:92
Raster property.
TEGDALEXPORT void Rasterize(std::vector< te::gm::Geometry * > geometries, GDALDataset *outraster)
Rasterizes a given vector of geometries, using GDALRasterizeGeometries function.
std::string GetGDALRessamplingMethod(te::rst::InterpolationMethod interpolationMethod)
It translates a TerraLib interpolation method into a GDAL ressampling method name string...
Definition: Utils.h:190
int GetTeDataType(GDALDataType gt)
It translates a GDAL DataType to a TerraLib DataType.
Definition: Utils.h:72
AccessPolicy
Supported data access policies (can be used as bitfield).
Definition: Enums.h:40
YCbCr Cr Band color interpretation.
Definition: Enums.h:72
An Envelope defines a 2D rectangular region.
Definition: Envelope.h:51
An abstract class for raster data strucutures.
Definition: Raster.h:71
std::string GetParentDataSetName(const std::string &subDataSetName)
It returns the parent dataset name from a Sub DataSet name.
URI C++ Library.
No color interpretation is associated with the band.
Definition: Enums.h:56
TEGDALEXPORT void GetBandProperties(GDALDataset *gds, std::vector< te::rst::BandProperty * > &bprops)
Gets the list of bands definition from a GDAL dataset.
te::gm::Envelope * GetExtent(std::string strAccessInfo)
Gets the extent of a raster data decoded by GDAL.
Undefined palette interpretation.
Definition: Enums.h:82
Key (black) color interpretation.
Definition: Enums.h:69
Yellow color interpretation.
Definition: Enums.h:68
std::string GetDriverName(const std::string &dsName)
It returns the GDAL driver name associated to a data source name.
Bicubic interpolation method.
Definition: Enums.h:97
TEGDALEXPORT boost::mutex & getStaticMutex()
Returns a reference to a static mutex initialized when this module is initialized.
GDAL driver metadata.
Definition: Utils.h:61
bool IsSubDataSet(const std::string &uri)
Returns true if the given URI is related to a sub-dataset.
bool ReprojectRaster(te::rst::Raster const *const rin, te::rst::Raster *rout)
Reprojects a raster to another SRS.
std::string m_extension
File extension (DMD_EXTENSION).
Definition: Utils.h:64
bool RecognizesSRID(unsigned int srid)
It returns true if GDAL recognizes the given SRS id.
std::string GetGDALConnectionInfo(const std::map< std::string, std::string > &connInfo)
It returns a GDAL connection string from the given map.
std::string MakePGConnectionStr(const std::map< std::string, std::string > &dsInfo)
Returns a PostGIS connection string from the set connection information. The connection string is to ...
YCbCr Y Band color interpretation.
Definition: Enums.h:70
Bilinear interpolation method.
Definition: Enums.h:96
CMYK indexed palette interpretation.
Definition: Enums.h:85
Saturation color interpretation.
Definition: Enums.h:64
Blue channel color interpretation.
Definition: Enums.h:61
PaletteInterpretation
Palette interpratation types.
Definition: Enums.h:80
TEGDALEXPORT void Vectorize(GDALRasterBand *band, std::vector< te::gm::Geometry * > &geometries)
Vectorizes a given raster band, using GDALPolygonize function.
A rectified grid is the spatial support for raster data.
Definition: Grid.h:68
std::string m_longName
File long name (DMD_LONGNAME).
Definition: Utils.h:65
std::string GetSubDataSetName(const std::string &name, const std::string &driverName)
It returns the Sub DataSet name from the given name or the same name.
Green channel color interpretation.
Definition: Enums.h:60
GDALDataset * CreateRaster(te::rst::Grid *g, const std::vector< te::rst::BandProperty * > &bands, const std::map< std::string, std::string > &optParams)
Creates a raster data using GDAL.
te::rst::BandProperty * GetBandProperty(GDALRasterBand *gband, const unsigned int bandIndex)
Gets the properties of a single band from a GDAL dataset.
Magenta color interpretation.
Definition: Enums.h:67
YCbCr Cb Band color interpretation.
Definition: Enums.h:71
const std::map< std::string, DriverMetadata > & GetGDALDriversMetadata()
Returns metadata from all registered GDAL drivers (key: driver name).
Configuration flags for the GDAL Driver of TerraLib.