Band.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/Band.h
22 
23  \brief It gives access to values in one band (dimension) of a raster.
24 */
25 
26 #ifndef __TERRALIB_RASTER_INTERNAL_BAND_H
27 #define __TERRALIB_RASTER_INTERNAL_BAND_H
28 
29 // TerraLib
30 #include "Config.h"
31 #include "Raster.h"
32 #include "RasterProperty.h"
33 
34 // STL
35 #include <complex>
36 #include <string>
37 #include <vector>
38 
39 namespace te
40 {
41  namespace rst
42  {
43 // Forward declaration
44  class BandProperty;
45  class Raster;
46 
47  /*!
48  \class Band
49 
50  \brief A raster band description.
51 
52  The raster band describes how to interpret (and use) values that
53  can be associated to each element of a raster, in one given dimension
54  (e.g. a band of multi-hiperspectral remote sensing image).
55  Each instance of this class refers to a particular dimension.
56  This implementation defines a set of information commonly used to describe any
57  raster.
58 
59  \ingroup rst
60 
61  \sa Raster, BandProperty
62  */
63  class TERASTEREXPORT Band
64  {
65  public:
66 
67  /*!
68  \brief Constructor.
69 
70  \param p The band property. The Band will take its ownership.
71  \param idx The band index.
72 
73  \warning The class takes the ownership of the passed pointer. Do not pass a null pointer.
74  */
75  Band(BandProperty* p, std::size_t idx);
76 
77  /*! \brief Virtual destructor. */
78  virtual ~Band();
79 
80  /*! \brief Returns the associated raster. */
81  virtual Raster* getRaster() const = 0;
82 
83  /*!
84  \brief Assignment operator.
85 
86  \param rhs The right-hand-side copy used to copy from.
87 
88  \return A reference to this object.
89  */
90  virtual Band& operator=(const Band& rhs);
91 
92  /*!
93  \brief Returns the cell attribute value.
94 
95  \param c The column location of the cell.
96  \param r The row location of the cell.
97  \param value To return the attribute value.
98 
99  \warning The caller is responsible for providing correct values for the range [c x r].
100 
101  \exception Exception Subclasses may throw an exception if the data value can not be read.
102  */
103  virtual void getValue(unsigned int c, unsigned int r, double& value) const = 0;
104 
105  /*!
106  \brief Sets the cell attribute value.
107 
108  \param c The column location of the cell.
109  \param r The row location of the cell.
110  \param value The attribute value to be assigned.
111 
112  \warning The caller is responsible for providing correct values for the range [c x r].
113 
114  \exception Exception Subclasses may throw an exception if the data value can not be write.
115  */
116  virtual void setValue(unsigned int c, unsigned int r, const double value) = 0;
117 
118  /*!
119  \brief Returns the imaginary attribute value in a complex band of a cell.
120 
121  \param c The column location of the cell.
122  \param r The row location of the cell.
123  \param value The attribute value to be assigned.
124 
125  \warning The caller is responsible for providing correct values for the range [c x r].
126 
127  \exception Exception Subclasses may throw an exception if the data value can not be read.
128  */
129  virtual void getIValue(unsigned int c, unsigned int r, double& value) const = 0;
130 
131  /*!
132  \brief Sets the imaginary attribute value in a complex band of a cell.
133 
134  \param c The column location of the cell.
135  \param r The row location of the cell.
136  \param value The attribute value to be assigned.
137 
138  \warning The caller is responsible for providing correct values for the range [c x r].
139 
140  \exception Exception Subclasses may throw an exception if the data value can not be write.
141  */
142  virtual void setIValue(unsigned int c, unsigned int r, const double value) = 0;
143 
144  /*!
145  \brief Returns the imaginary attribute value in a complex band of a cell.
146 
147  \param c The column location of the cell.
148  \param r The row location of the cell.
149  \param value The complex attribute value to be assigned (real, imaginary).
150 
151  \warning The caller is responsible for providing correct values for the range [c x r].
152 
153  \exception Exception Subclasses may throw an exception if the data value can not be read.
154  */
155  virtual void getValue(unsigned int c, unsigned int r, std::complex<double>& value) const;
156 
157  /*!
158  \brief Sets the imaginary attribute value in a complex band of a cell.
159 
160  \param c The column location of the cell.
161  \param r The row location of the cell.
162  \param value The complex attribute value to be assigned (real, imaginary).
163 
164  \warning The caller is responsible for providing correct values for the range [c x r].
165 
166  \exception Exception Subclasses may throw an exception if the data value can not be write.
167  */
168  virtual void setValue(unsigned int c, unsigned int r, const std::complex<double>& value);
169 
170  /*!
171  \brief It reads a data block to the specified buffer.
172 
173  \param x The block-id in x (or x-offset).
174  \param y The block-id in y (or y-offset).
175  \param buffer The buffer to be used to read from the band.
176 
177  \note The upper-left corner is (0, 0).
178 
179  \warning The buffer must have been previously allocated and must have enough capacity.
180  */
181  virtual void read(int x, int y, void* buffer) const = 0;
182 
183  /*!
184  \brief It reads and returns a data block.
185 
186  \param x The block-id in x (or x-offset).
187  \param y The block-id in y (or y-offset).
188 
189  \note The upper-left corner is (0, 0).
190 
191  \return The specified data block.
192  */
193  virtual void* read(int x, int y) = 0;
194 
195  /*!
196  \brief It writes a data block from the specified buffer.
197 
198  \param x The block-id in x (or x-offset).
199  \param y The block-id in y (or y-offset).
200  \param buffer The buffer to be used to write to the band.
201 
202  \note The upper-left corner is (0, 0).
203 
204  \warning The method will copy the same amount of bytes used by the internal band block representation.
205  */
206  virtual void write(int x, int y, void* buffer) = 0;
207 
208  /*!
209  \brief It computes and returns the minimum occurring value in a window of the band.
210 
211  \param readall Force the reading the entire image (can be slow). If false, will read up to 1000 pixels of the image, equally spaced.
212  \param rs The starting row.
213  \param cs The starting column.
214  \param rf The final row.
215  \param cf The final column.
216 
217  \note This method without parameters will compute for the entire image.
218 
219  \warning The caller is responsible for providing correct values for the range [rs, cs x rf, cf x b].
220 
221  \return The minimum occurring value in the window, real and imaginary (if present).
222  */
223  virtual std::complex<double> getMinValue(bool readall = false, unsigned int rs = 0, unsigned int cs = 0, unsigned int rf = 0, unsigned int cf = 0) const;
224 
225  /*!
226  \brief It computes and returns the maximum occurring value in a window of the band.
227 
228  \param readall Force the reading the entire image (can be slow). If false, will read up to 1000 pixels of the image, equally spaced.
229  \param rs The starting row.
230  \param cs The starting column.
231  \param rf The final row.
232  \param cf The final column.
233 
234  \note This method without parameters will compute for the entire raster band.
235 
236  \warning The caller is responsible for providing correct values for the range [rs, cs x rf, cf].
237 
238  \return The maximum occurring value in the window, real and imaginary (if present).
239  */
240  virtual std::complex<double> getMaxValue(bool readall = false, unsigned int rs = 0, unsigned int cs = 0, unsigned int rf = 0, unsigned int cf = 0) const;
241 
242  /*!
243  \brief It computes and returns the standard deviation of the occurring values in a window of the band.
244 
245  \param rs The starting row.
246  \param cs The starting column.
247  \param rf The final row.
248  \param cf The final column.
249 
250  \note This method without parameters will compute for the entire raster band.
251 
252  \warning The caller is responsible for providing correct values for the range [rs, cs x rf, cf].
253 
254  \return The standard deviation of the occurring values in the window, real and imaginary (if present).
255  */
256  virtual std::complex<double> getStdValue(unsigned int rs = 0, unsigned int cs = 0, unsigned int rf = 0, unsigned int cf = 0) const;
257 
258  /*!
259  \brief It computes and returns the mean of the occurring values in a window of the band.
260 
261  \param rs The starting row.
262  \param cs The starting column.
263  \param rf The final row.
264  \param cf The final column.
265 
266  \note This method without parameters will compute for the entire raster band.
267 
268  \warning The caller is responsible for providing correct values for the range [rs, cs x rf, cf].
269 
270  \return The mean of the occurring values in the window, real and imaginary (if present).
271  */
272  virtual std::complex<double> getMeanValue(unsigned int rs = 0, unsigned int cs = 0, unsigned int rf = 0, unsigned int cf = 0) const;
273 
274  /*!
275  \brief It computes and returns the histogram occurring values (real part) in a window of the band.
276 
277  \param rs The starting row.
278  \param cs The starting column.
279  \param rf The final row.
280  \param cf The final column.
281  \param b The number of bins (intervals from minimum pixel to maximum). When b = 0, the histogram will be divided according to all pixel values.
282 
283  \note This method without parameters will compute for the entire raster band.
284 
285  \warning The caller is responsible for providing correct values for the range [rs, cs x rf, cf].
286 
287  \return The histogram of the occurring values (real part) in the window.
288  */
289  virtual std::map<double, unsigned> getHistogramR(unsigned int rs = 0, unsigned int cs = 0, unsigned int rf = 0, unsigned int cf = 0, unsigned int b = 0) const;
290 
291  /*!
292  \brief It computes and returns the histogram occurring values (real part) in a window of the band.
293 
294  \param rowStart The starting row.
295  \param colStart The starting column.
296  \param finalRow The final row.
297  \param finalCol The final column.
298  \param histoBins The number of bins (intervals from minimum pixel to maximum). When b = 0, the histogram will be divided according to all pixel values.
299  \param sampleStep The row/column step used when reading pixels (to read all pixels sampleStep=1, to read half of pixels use sampleStep=2 );
300  \param histogram The generated histogram.
301 
302  \note This method without parameters will compute for the entire raster band.
303 
304  \warning The caller is responsible for providing correct values for the range [rs, cs x rf, cf].
305 
306  \return The histogram of the occurring values (real part) in the window.
307  */
308  virtual void getHistogramR( const unsigned int rowStart,
309  const unsigned int colStart,
310  const unsigned int finalRow,
311  const unsigned int finalCol,
312  const unsigned int histoBins,
313  const unsigned int sampleStep,
314  std::map<double, unsigned>& histogram ) const;
315 
316  /*!
317  \brief It computes and returns the histogram occurring values (imaginary part) in a window of the band.
318 
319  \param rs The starting row.
320  \param cs The starting column.
321  \param rf The final row.
322  \param cf The final column.
323  \param b The number of bins (intervals from minimum pixel to maximum). When b = 0, the histogram will be divided according to all pixel values.
324 
325  \note This method without parameters will compute for the entire raster band.
326 
327  \warning The caller is responsible for providing correct values for the range [rs, cs x rf, cf].
328 
329  \return The histogram of the occurring values (imaginary part) in the window.
330  */
331  virtual std::map<double, unsigned> getHistogramI(unsigned int rs = 0, unsigned int cs = 0, unsigned int rf = 0, unsigned int cf = 0, unsigned int b = 0) const;
332 
333  /*! \brief It returns the scale values (real and imaginary) to be applied to the band. */
334  std::complex<double> getScaleValue() const;
335 
336  /*!
337  \brief Sets the scale values (real and imaginary) to be applied to the band.
338 
339  \param s The new scale.
340  */
341  void setScaleValue(const std::complex<double> s);
342 
343  /*! \brief It returns the offset values (real and imaginary) to be applied to the band. */
344  std::complex<double> getOffsetValue() const;
345 
346  /*!
347  \brief Sets the offset values (real and imaginary) to be applied to the band.
348 
349  \param o The new offset.
350  */
351  void setOffsetValue(const std::complex<double> o);
352 
353  /*! \brief Returns the band property. */
354  BandProperty* getProperty();
355 
356  /*! \brief Returns the band property. */
357  const BandProperty* getProperty() const;
358 
359  /*!
360  \brief It calls a parameter function f to apply in all pixels from two bands, e.g. pixel = f(lhs, rhs);
361 
362  \param (*f) a function with the signature complex<double>(*f)(complex<double>, complex<double>)
363 
364  \param rhs The rhs band to apply the function.
365 
366  \return The resultant band.
367  */
368  Band& callOperator(std::complex<double>(*f)(std::complex<double>, std::complex<double>), Band& rhs);
369 
370  /*!
371  \brief It calls a parameter function f to apply in all pixels from the band, e.g. pixel = f(lhs, rhs);
372 
373  \param (*f) a function with the signature complex<double>(*f)(complex<double>, complex<double>)
374 
375  \param cvalue The constant value that will work with the generic function.
376 
377  \return The resultant band.
378  */
379  Band& callOperator(std::complex<double>(*f)(std::complex<double>, std::complex<double>), std::complex<double>& cvalue);
380 
381  /*!
382  \brief It returns the band sum (pixel by pixel).
383 
384  \param rhs The band to be added, right-hand side.
385 
386  \note Both bands must have the same properties, #columns, #rows, and data type.
387 
388  \note The caller is responsible to guarantee that resultant values
389  will not exceed the range of the data type.
390 
391  \return The band sum.
392  */
393  virtual Band& operator+=(Band& rhs);
394 
395  /*!
396  \brief It returns the sum of a constant value to all pixels in the band.
397 
398  \param cvalue The constant value to be added.
399 
400  \note The caller is responsible to guarantee that resultant values
401  will not exceed the range of the data type.
402 
403  \return The band sum.
404  */
405  virtual Band& operator+=(std::complex<double>& cvalue);
406 
407  /*!
408  \brief It returns the band subtraction (pixel by pixel).
409 
410  \param rhs The band to be subtracted, right-hand side.
411 
412  \note Both bands must have the same properties, #columns, #rows, and data type.
413 
414  \note The caller is responsible to guarantee that resultant values
415  will not exceed the range of the data type.
416 
417  \return The band subtraction.
418  */
419  virtual Band& operator-=(Band& rhs);
420 
421  /*!
422  \brief It returns the difference from all pixels in the band to a constant value (pixel - constant).
423 
424  \param cvalue The constant value to be subtracted.
425 
426  \note The caller is responsible to guarantee that resultant values
427  will not exceed the range of the data type.
428 
429  \return The band difference.
430  */
431  virtual Band& operator-=(std::complex<double>& cvalue);
432 
433  /*!
434  \brief It returns the band product (pixel by pixel).
435 
436  \param rhs The band to be multiplied, right-hand side.
437 
438  \note Both bands must have the same properties, #columns, #rows, and data type.
439 
440  \note The caller is responsible to guarantee that resultant values
441  will not exceed the range of the data type.
442 
443  \return The band product.
444  */
445  virtual Band& operator*=(Band& rhs);
446 
447  /*!
448  \brief It returns the product of a constant value to all pixels in the band.
449 
450  \param cvalue The constant value to be multiplied.
451 
452  \note The caller is responsible to guarantee that resultant values
453  will not exceed the range of the data type.
454 
455  \return The band product.
456  */
457  virtual Band& operator*=(std::complex<double>& cvalue);
458 
459  /*!
460  \brief It returns the band division (pixel by pixel).
461 
462  \param rhs The band to be divided, right-hand side.
463 
464  \note Both bands must have the same properties, #columns, #rows, and data type.
465 
466  \note The caller is responsible to guarantee that resultant values
467  will not exceed the range of the data type.
468 
469  \return The band division.
470  */
471  virtual Band& operator/=(Band& rhs);
472 
473  /*!
474  \brief It returns the division of all pixels in the band by a constant value (pixel / constant).
475 
476  \param cvalue The constant value to be divided.
477 
478  \note The caller is responsible to guarantee that resultant values
479  will not exceed the range of the data type.
480 
481  \return The band division.
482  */
483  virtual Band& operator/=(std::complex<double>& cvalue);
484 
485  /*! \brief It returns the number of bytes ocuppied by a data block. */
486  virtual int getBlockSize() const;
487 
488  protected:
489 
490  /*!
491  \brief Copy constructor.
492 
493  \param rhs The right-hand-side copy used to copy from.
494  */
495  Band(const Band& rhs);
496 
497  protected:
498 
499  BandProperty* m_property; //!< The band information.
500  std::size_t m_idx; //!< The band index.
501  };
502 
503  } // end namespace rst
504 } // end namespace te
505 
506 #endif // __TERRALIB_RASTER_INTERNAL_BAND_H
TERASTEREXPORT
#define TERASTEREXPORT
You can use this macro in order to export/import classes and functions from this module.
Definition: Config.h:63
te::rst::BandProperty
A raster band description.
Definition: BandProperty.h:61
RasterProperty.h
Raster property.
Raster.h
An abstract class for raster data strucutures.
te::rst::Raster
An abstract class for raster data strucutures.
Definition: Raster.h:71
te
URI C++ Library.
Definition: AddressGeocodingOp.h:51
te::rst::Band
A raster band description.
Definition: Band.h:63
te::rst::Band::m_idx
std::size_t m_idx
The band index.
Definition: Band.h:500
Config.h
Configuration flags for the Raster module of TerraLib.
te::rst::Band::m_property
BandProperty * m_property
The band information.
Definition: Band.h:499