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 (imaginary part) in a window of the band.
293 
294  \param rs The starting row.
295  \param cs The starting column.
296  \param rf The final row.
297  \param cf The final column.
298  \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.
299 
300  \note This method without parameters will compute for the entire raster band.
301 
302  \warning The caller is responsible for providing correct values for the range [rs, cs x rf, cf].
303 
304  \return The histogram of the occurring values (imaginary part) in the window.
305  */
306  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;
307 
308  /*! \brief It returns the scale values (real and imaginary) to be applied to the band. */
309  std::complex<double> getScaleValue() const;
310 
311  /*!
312  \brief Sets the scale values (real and imaginary) to be applied to the band.
313 
314  \param s The new scale.
315  */
316  void setScaleValue(const std::complex<double> s);
317 
318  /*! \brief It returns the offset values (real and imaginary) to be applied to the band. */
319  std::complex<double> getOffsetValue() const;
320 
321  /*!
322  \brief Sets the offset values (real and imaginary) to be applied to the band.
323 
324  \param o The new offset.
325  */
326  void setOffsetValue(const std::complex<double> o);
327 
328  /*! \brief Returns the band property. */
329  BandProperty* getProperty();
330 
331  /*! \brief Returns the band property. */
332  const BandProperty* getProperty() const;
333 
334  /*!
335  \brief It calls a parameter function f to apply in all pixels from two bands, e.g. pixel = f(lhs, rhs);
336 
337  \param (*f) a function with the signature complex<double>(*f)(complex<double>, complex<double>)
338 
339  \param rhs The rhs band to apply the function.
340 
341  \return The resultant band.
342  */
343  Band& callOperator(std::complex<double>(*f)(std::complex<double>, std::complex<double>), Band& rhs);
344 
345  /*!
346  \brief It calls a parameter function f to apply in all pixels from the band, e.g. pixel = f(lhs, rhs);
347 
348  \param (*f) a function with the signature complex<double>(*f)(complex<double>, complex<double>)
349 
350  \param cvalue The constant value that will work with the generic function.
351 
352  \return The resultant band.
353  */
354  Band& callOperator(std::complex<double>(*f)(std::complex<double>, std::complex<double>), std::complex<double>& cvalue);
355 
356  /*!
357  \brief It returns the band sum (pixel by pixel).
358 
359  \param rhs The band to be added, right-hand side.
360 
361  \note Both bands must have the same properties, #columns, #rows, and data type.
362 
363  \note The caller is responsible to guarantee that resultant values
364  will not exceed the range of the data type.
365 
366  \return The band sum.
367  */
368  virtual Band& operator+=(Band& rhs);
369 
370  /*!
371  \brief It returns the sum of a constant value to all pixels in the band.
372 
373  \param cvalue The constant value to be added.
374 
375  \note The caller is responsible to guarantee that resultant values
376  will not exceed the range of the data type.
377 
378  \return The band sum.
379  */
380  virtual Band& operator+=(std::complex<double>& cvalue);
381 
382  /*!
383  \brief It returns the band subtraction (pixel by pixel).
384 
385  \param rhs The band to be subtracted, right-hand side.
386 
387  \note Both bands must have the same properties, #columns, #rows, and data type.
388 
389  \note The caller is responsible to guarantee that resultant values
390  will not exceed the range of the data type.
391 
392  \return The band subtraction.
393  */
394  virtual Band& operator-=(Band& rhs);
395 
396  /*!
397  \brief It returns the difference from all pixels in the band to a constant value (pixel - constant).
398 
399  \param cvalue The constant value to be subtracted.
400 
401  \note The caller is responsible to guarantee that resultant values
402  will not exceed the range of the data type.
403 
404  \return The band difference.
405  */
406  virtual Band& operator-=(std::complex<double>& cvalue);
407 
408  /*!
409  \brief It returns the band product (pixel by pixel).
410 
411  \param rhs The band to be multiplied, right-hand side.
412 
413  \note Both bands must have the same properties, #columns, #rows, and data type.
414 
415  \note The caller is responsible to guarantee that resultant values
416  will not exceed the range of the data type.
417 
418  \return The band product.
419  */
420  virtual Band& operator*=(Band& rhs);
421 
422  /*!
423  \brief It returns the product of a constant value to all pixels in the band.
424 
425  \param cvalue The constant value to be multiplied.
426 
427  \note The caller is responsible to guarantee that resultant values
428  will not exceed the range of the data type.
429 
430  \return The band product.
431  */
432  virtual Band& operator*=(std::complex<double>& cvalue);
433 
434  /*!
435  \brief It returns the band division (pixel by pixel).
436 
437  \param rhs The band to be divided, right-hand side.
438 
439  \note Both bands must have the same properties, #columns, #rows, and data type.
440 
441  \note The caller is responsible to guarantee that resultant values
442  will not exceed the range of the data type.
443 
444  \return The band division.
445  */
446  virtual Band& operator/=(Band& rhs);
447 
448  /*!
449  \brief It returns the division of all pixels in the band by a constant value (pixel / constant).
450 
451  \param cvalue The constant value to be divided.
452 
453  \note The caller is responsible to guarantee that resultant values
454  will not exceed the range of the data type.
455 
456  \return The band division.
457  */
458  virtual Band& operator/=(std::complex<double>& cvalue);
459 
460  /*! \brief It returns the number of bytes ocuppied by a data block. */
461  virtual int getBlockSize() const;
462 
463  protected:
464 
465  /*!
466  \brief Copy constructor.
467 
468  \param rhs The right-hand-side copy used to copy from.
469  */
470  Band(const Band& rhs);
471 
472  protected:
473 
474  BandProperty* m_property; //!< The band information.
475  std::size_t m_idx; //!< The band index.
476  };
477 
478  } // end namespace rst
479 } // end namespace te
480 
481 #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:62
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:475
Config.h
Configuration flags for the Raster module of TerraLib.
te::rst::Band::m_property
BandProperty * m_property
The band information.
Definition: Band.h:474