Grid.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/raster/Grid.h
22 
23  \brief A rectified grid is the spatial support for raster data.
24 */
25 
26 #ifndef __TERRALIB_RASTER_INTERNAL_GRID_H
27 #define __TERRALIB_RASTER_INTERNAL_GRID_H
28 
29 // TerraLib
30 #include "../geometry/Coord2D.h"
31 #include "../srs/Config.h"
32 #include "Config.h"
33 
34 // Boost
35 #include <boost/shared_ptr.hpp>
36 
37 namespace te
38 {
39 // Forward declaration
40  namespace gm { class Envelope; }
41 
42  namespace rst
43  {
44  /*!
45  \class Grid
46 
47  \brief A rectified grid is the spatial support for raster data.
48 
49  \note The upper left corner of the upper left pixel is considered the grid extent top-left reference.
50 
51  \code
52  Affine transformation:
53 
54  u = a.x + b.y + c
55  v = d.x + e.y + f
56 
57  | x | | a b c | | column |
58  | y | = | d e f | * | row |
59  | 1 | | 0 0 1 | | 1 |
60 
61  Georeference parameters order = [ a b c d e f ]
62  \endcode
63 
64  \ingroup rst
65 
66  \sa Raster
67  */
69  {
70  public:
71 
72  /*!
73  \brief Constructor.
74 
75  \param nCols The number of columns.
76  \param nRows The number of rows.
77  \param srid The SRS associated to the grid.
78  \param mbr The grid extent. The grid will take the ownership of the given envelope.
79 
80  \note If extent is not specified, no georeferencing is assumed.
81  \note The grid resolution (x-axis and y-axis) will be computed based on the number of columns/rows and the provided extent.
82  */
83  Grid(unsigned int nCols = 0, unsigned int nRows = 0,
84  te::gm::Envelope* mbr = 0, int srid = TE_UNKNOWN_SRS);
85 
86  /*!
87  \brief Constructor.
88 
89  \param nCols The number of columns.
90  \param nRows The number of rows.
91  \param resX The grid horizontal (x-axis) resolution.
92  \param resY The grid vertical (y-axis) resolution.
93  \param ulc The location of the upper-left corner of the upper-left pixel (or cell) of the grid assuming srid as the SRS.
94  \param srid The SRS associated to the grid.
95 
96  \note If ulc is not specified, no georeferencing is assumed.
97  */
98  Grid(unsigned int nCols, unsigned int nRows,
99  double resX, double resY,
100  const te::gm::Coord2D* ulc, int srid = TE_UNKNOWN_SRS);
101 
102  /*!
103  \brief Constructor.
104 
105  \param nCols The number of columns.
106  \param nRows The number of rows.
107  \param resX The grid horizontal (x-axis) resolution.
108  \param resY The grid vertical (y-axis) resolution.
109  \param mbr The grid extent. The grid will take the ownership of the given envelope.
110  \param srid The SRS associated to the grid.
111 
112  \note If extent is not specified, no georeferencing is assumed.
113  */
114  Grid(unsigned int nCols, unsigned int nRows,
115  double resX, double resY,
116  te::gm::Envelope* mbr, int srid = TE_UNKNOWN_SRS);
117 
118  /*!
119  \brief Constructor.
120 
121  \param resX The grid horizontal (x-axis) resolution.
122  \param resY The grid vertical (y-axis) resolution.
123  \param mbr The grid extent. The grid will take the ownership of the given envelope.
124  \param srid The SRS associated to the grid.
125 
126  \note The grid resolution (x-axis and y-axis) will be computed based on the number of columns/rows and the provided extent.
127  */
128  Grid(double resX, double resY,
129  te::gm::Envelope* mbr, int srid = TE_UNKNOWN_SRS);
130 
131  /*!
132  \brief Constructor.
133 
134  \param nCols The number of columns.
135  \param nRows The number of rows.
136  \param geoTrans[] A list of 6 coefficients describing an affine transformation to georeference a grid.
137  \param srid The SRS associated to the grid.
138 
139  \note If extent is not specified, no georeferencing is assumed.
140  */
141  Grid(const double geoTrans[], unsigned int nCols, unsigned int nRows,
142  int srid = TE_UNKNOWN_SRS);
143 
144  /*!
145  \brief Copy constructor.
146 
147  \param rhs The right-hand-side object to be used to copy from.
148  */
149  Grid(const Grid& rhs);
150 
151  /*! \brief Destructor. */
152  ~Grid();
153 
154  /*!
155  \brief Assignment operator.
156 
157  \param rhs The right-hand-side object to be used to copy from.
158 
159  \return A reference to this.
160  */
161  Grid& operator=(const Grid& rhs);
162 
163  /*!
164  \brief Sets the grid number of columns.
165 
166  \param nCols The number of columns.
167  */
168  void setNumberOfColumns(unsigned int nCols);
169 
170  /*! \brief Returns the grid number of columns. */
171  unsigned int getNumberOfColumns() const;
172 
173  /*!
174  \brief Sets the grid number of rows.
175 
176  \param nRows The number of rows.
177  */
178  void setNumberOfRows(unsigned int nRows);
179 
180  /*! \brief Returns the grid number of rows. */
181  unsigned int getNumberOfRows() const;
182 
183  /*!
184  \brief Sets the information needed to georeference the grid.
185 
186  Specifies a transformation that maps a grid point (col, row) to a spatial location (x, y).
187 
188  This method should be used when there is no translation associated to the mapping.
189 
190  \param ulLocation The location of the upper-left corner of the upper-left pixel (or cell) of the grid.
191  \param srid The id of the SRS that the location refers to.
192  \para resX The grid horizontal (x-axis) resolution
193  \para resY The grid vertical (y-axis) resolution
194  */
195  void setGeoreference(const te::gm::Coord2D& ulLocation, int srid, double resX, double resY);
196 
197  /*!
198  \brief Sets the information needed to georeference the grid using an affine transformation.
199 
200  An affine transformation maps grid point (col,lin) to a spatial location (x,y) using to the
201  following relationship:
202  This method should be used mainly when there is a translation associated to the mapping.
203  Otherwise use the method above.
204 
205  \param geoTrans[] A list of 6 coefficients describing an affine transformation to georeference a grid.
206  \param srid The SRS id to which the location refers to.
207  */
208  void setGeoreference(const double geoTrans[], int srid);
209 
210  /*! \brief Returns a list of 6 coefficients describing an affine transformation to georeference a grid. */
211  const double* getGeoreference() const;
212 
213  /*! \brief Returns the grid horizontal (x-axis) resolution. */
214  double getResolutionX() const;
215 
216  /*! \brief Returns the grid vertical (y-axis) resolution. */
217  double getResolutionY() const;
218 
219  /*! \brief Returns the grid spatial reference system identifier. */
220  int getSRID() const;
221 
222  /*! \brief Just sets the grid spatial reference system identifier. */
223  void setSRID(int srid);
224 
225  /*! \brief Returns the geographic extension of the grid. */
226  te::gm::Envelope* getExtent();
227 
228  /*! \brief Returns the geographic extension of the grid. */
229  const te::gm::Envelope* getExtent() const;
230 
231  /*!
232  \brief Get the spatial location of a grid point.
233 
234  \param col The grid point column.
235  \param row The grid point row.
236  \param x The spatial location (X axis).
237  \param y The spatial location (Y axis).
238  */
239  void gridToGeo(const double& col, const double& row, double& x, double& y) const;
240 
241  /*!
242  \brief Get the spatial location of a grid point.
243 
244  \param col The grid point column.
245  \param row The grid point row.
246 
247  \return The spatial location.
248  */
249  te::gm::Coord2D gridToGeo(const double& col, const double& row) const;
250 
251  /*!
252  \brief Get the grid point associated to a spatial location.
253 
254  \param x The spatial x-coordiante.
255  \param y The spatial y-coordiante.
256  \param col The grid point column.
257  \param row The grid point row.
258  */
259  void geoToGrid(const double& x, const double& y, double& col, double& row) const;
260 
261  /*!
262  \brief Get the grid point associated to a spatial location.
263 
264  \param x The spatial x-coordiante.
265  \param y The spatial y-coordiante.
266 
267  \return The grid location.
268  */
269  te::gm::Coord2D geoToGrid(const double& x, const double& y) const;
270 
271  /*!
272  \brief Equal operator.
273 
274  \param rhs The source object to be compared.
275 
276  \return True if the grids have the same exact coordinates, number of cols and rows, srid, and 6 coefficients.
277  */
278  bool operator==(const Grid& rhs) const;
279 
280  /*
281  \brief Returns if point is in the grid.
282 
283  \param col The column to test.
284  \param row The row to test.
285 
286  \return True if point is in the grid, and false otherwise.
287  */
288  bool isPointInGrid(unsigned int col, unsigned int row) const;
289 
290  private:
291 
292  mutable te::gm::Envelope* m_extent; //!< The grid extent.
293  unsigned int m_nCols; //!< Number of columns.
294  unsigned int m_nRows; //!< Number of rows.
295  int m_srid; //!< The associated SRS.
296  double m_geoT[6]; //!< A list of 6 coefficients describing an affine transformation to georeference a grid.
297  double m_geoTInverse[6]; //!< A list of 6 coefficients describing an inverse affine transformation to georeference a grid.
298 
299  /*! \brief Computes the geographic extension of the grid. */
300  void computeExtent() const;
301 
302  /*!
303  \brief Compute affine parameters from the given input parameters.
304 
305  \param extentWidth Extent width.
306  \param extentHeight Extent height.
307  \param nColumns Number of columns.
308  \param nRows Number of rows.
309  \param extentULX Extent upper-left X coordinate.
310  \param extentULY Extent upper-left Y coordinate.
311  \param affineParamsPtr A pointer to a allocated vector of 6 elements where the parameters will be stored.
312  \return true if ok, false on errors.
313  */
314  bool computeAffineParameters( const double extentWidth,
315  const double extentHeight,
316  const unsigned int nColumns,
317  const unsigned int nRows,
318  const double extentULX,
319  const double extentULY,
320  double* affineParamsPtr,
321  double* inverseAffineParamsPtr ) const;
322 
323  /*!
324  \brief Compute inverse affine parameters
325  \param affineParamsPtr A pointer to a allocated vector of 6 elements (affine parameters).
326  \param inverseAffineParamsPtr A pointer to a allocated vector of 6 elements where the parameters will be stored.
327  \return true if ok, false on errors
328  */
329  bool computeInverseParameters( double* const affineParamsPtr,
330  double* inverseAffineParamsPtr ) const;
331  };
332 
333  typedef boost::shared_ptr<Grid> GridPtr;
334 
335  inline te::gm::Coord2D Grid::gridToGeo(const double& col, const double& row) const
336  {
337  te::gm::Coord2D c;
338  gridToGeo(col, row, c.x, c.y);
339  return c;
340  }
341 
342  inline te::gm::Coord2D Grid::geoToGrid(const double& x, const double& y) const
343  {
344  te::gm::Coord2D c;
345  geoToGrid(x, y, c.x, c.y);
346  return c;
347  }
348 
349  inline bool Grid::isPointInGrid(unsigned int col, unsigned int row) const
350  {
351  return (col < m_nCols) && (row < m_nRows);
352  }
353 
354  } // end namespace rst
355 } // end namespace te
356 
357 #endif // __TERRALIB_RASTER_INTERNAL_GRID_H
bool isPointInGrid(unsigned int col, unsigned int row) const
Definition: Grid.h:349
#define TERASTEREXPORT
You can use this macro in order to export/import classes and functions from this module.
Definition: Config.h:62
te::gm::Envelope * m_extent
The grid extent.
Definition: Grid.h:292
double y
y-coordinate.
Definition: Coord2D.h:114
double x
x-coordinate.
Definition: Coord2D.h:113
An utility struct for representing 2D coordinates.
Definition: Coord2D.h:40
TEDATAACCESSEXPORT te::da::Expression * operator==(const te::da::Expression &e1, const te::da::Expression &e2)
void geoToGrid(const double &x, const double &y, double &col, double &row) const
Get the grid point associated to a spatial location.
boost::shared_ptr< Grid > GridPtr
Definition: Grid.h:333
An Envelope defines a 2D rectangular region.
Definition: Envelope.h:51
int m_srid
The associated SRS.
Definition: Grid.h:295
#define TE_UNKNOWN_SRS
A numeric value to represent a unknown SRS identification in TerraLib.
Definition: Config.h:41
unsigned int m_nCols
Number of columns.
Definition: Grid.h:293
URI C++ Library.
void gridToGeo(const double &col, const double &row, double &x, double &y) const
Get the spatial location of a grid point.
Configuration flags for the Raster module of TerraLib.
A rectified grid is the spatial support for raster data.
Definition: Grid.h:68
unsigned int m_nRows
Number of rows.
Definition: Grid.h:294