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 gets the buffer in just only one block that represents the region informed.
210 
211  \param buffer Buffer with resampled recovered image
212  \param x0 Start point (upper left X) from input image
213  \param y0 Start point (upper left Y) from input image
214  \param width Width of input image
215  \param height Height of input image
216  \param outWidth Width of output buffer
217  \param outHeight Height of output buffer
218 
219  \NOTE: This method was defined to increase draw speed.
220  */
221  virtual void getBlockBuffer(void* buffer, int x0, int y0, int width, int height, int outWidth, int outHeight, int dataType);
222 
223  /*!
224  \brief It computes and returns the minimum occurring value in a window of the band.
225 
226  \param readall Force the reading the entire image (can be slow). If false, will read up to 1000 pixels of the image, equally spaced.
227  \param rs The starting row.
228  \param cs The starting column.
229  \param rf The final row.
230  \param cf The final column.
231 
232  \note This method without parameters will compute for the entire image.
233 
234  \warning The caller is responsible for providing correct values for the range [rs, cs x rf, cf x b].
235 
236  \return The minimum occurring value in the window, real and imaginary (if present).
237  */
238  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;
239 
240  /*!
241  \brief It computes and returns the maximum occurring value in a window of the band.
242 
243  \param readall Force the reading the entire image (can be slow). If false, will read up to 1000 pixels of the image, equally spaced.
244  \param rs The starting row.
245  \param cs The starting column.
246  \param rf The final row.
247  \param cf The final column.
248 
249  \note This method without parameters will compute for the entire raster band.
250 
251  \warning The caller is responsible for providing correct values for the range [rs, cs x rf, cf].
252 
253  \return The maximum occurring value in the window, real and imaginary (if present).
254  */
255  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;
256 
257  /*!
258  \brief It computes and returns the standard deviation of the occurring values in a window of the band.
259 
260  \param rs The starting row.
261  \param cs The starting column.
262  \param rf The final row.
263  \param cf The final column.
264 
265  \note This method without parameters will compute for the entire raster band.
266 
267  \warning The caller is responsible for providing correct values for the range [rs, cs x rf, cf].
268 
269  \return The standard deviation of the occurring values in the window, real and imaginary (if present).
270  */
271  virtual std::complex<double> getStdValue(unsigned int rs = 0, unsigned int cs = 0, unsigned int rf = 0, unsigned int cf = 0) const;
272 
273  /*!
274  \brief It computes and returns the mean of the occurring values in a window of the band.
275 
276  \param rs The starting row.
277  \param cs The starting column.
278  \param rf The final row.
279  \param cf The final column.
280 
281  \note This method without parameters will compute for the entire raster band.
282 
283  \warning The caller is responsible for providing correct values for the range [rs, cs x rf, cf].
284 
285  \return The mean of the occurring values in the window, real and imaginary (if present).
286  */
287  virtual std::complex<double> getMeanValue(unsigned int rs = 0, unsigned int cs = 0, unsigned int rf = 0, unsigned int cf = 0) const;
288 
289  /*!
290  \brief It computes and returns the histogram occurring values (real part) in a window of the band.
291 
292  \param rs The starting row.
293  \param cs The starting column.
294  \param rf The final row.
295  \param cf The final column.
296  \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.
297 
298  \note This method without parameters will compute for the entire raster band.
299 
300  \warning The caller is responsible for providing correct values for the range [rs, cs x rf, cf].
301 
302  \return The histogram of the occurring values (real part) in the window.
303  */
304  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;
305 
306  /*!
307  \brief It computes and returns the histogram occurring values (real part) in a window of the band.
308 
309  \param rowStart The starting row.
310  \param colStart The starting column.
311  \param finalRow The final row.
312  \param finalCol The final column.
313  \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.
314  \param sampleStep The row/column step used when reading pixels (to read all pixels sampleStep=1, to read half of pixels use sampleStep=2 );
315  \param histogram The generated histogram.
316 
317  \note This method without parameters will compute for the entire raster band.
318 
319  \warning The caller is responsible for providing correct values for the range [rowStart, colStart, finalRow, finalCol].
320 
321  \return The histogram of the occurring values (real part) in the window.
322  */
323  virtual void getHistogramR( const unsigned int rowStart,
324  const unsigned int colStart,
325  const unsigned int finalRow,
326  const unsigned int finalCol,
327  const unsigned int histoBins,
328  const unsigned int sampleStep,
329  std::map<double, unsigned>& histogram ) const;
330 
331  /*!
332  \brief It computes and returns the histogram occurring values (imaginary part) in a window of the band.
333 
334  \param rs The starting row.
335  \param cs The starting column.
336  \param rf The final row.
337  \param cf The final column.
338  \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.
339 
340  \note This method without parameters will compute for the entire raster band.
341 
342  \warning The caller is responsible for providing correct values for the range [rs, cs x rf, cf].
343 
344  \return The histogram of the occurring values (imaginary part) in the window.
345  */
346  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;
347 
348  /*! \brief It returns the scale values (real and imaginary) to be applied to the band. */
349  std::complex<double> getScaleValue() const;
350 
351  /*!
352  \brief Sets the scale values (real and imaginary) to be applied to the band.
353 
354  \param s The new scale.
355  */
356  void setScaleValue(const std::complex<double> s);
357 
358  /*! \brief It returns the offset values (real and imaginary) to be applied to the band. */
359  std::complex<double> getOffsetValue() const;
360 
361  /*!
362  \brief Sets the offset values (real and imaginary) to be applied to the band.
363 
364  \param o The new offset.
365  */
366  void setOffsetValue(const std::complex<double> o);
367 
368  /*! \brief Returns the band property. */
369  BandProperty* getProperty();
370 
371  /*! \brief Returns the band property. */
372  const BandProperty* getProperty() const;
373 
374  /*!
375  \brief It calls a parameter function f to apply in all pixels from two bands, e.g. pixel = f(lhs, rhs);
376 
377  \param (*f) a function with the signature complex<double>(*f)(complex<double>, complex<double>)
378 
379  \param rhs The rhs band to apply the function.
380 
381  \return The resultant band.
382  */
383  Band& callOperator(std::complex<double>(*f)(std::complex<double>, std::complex<double>), Band& rhs);
384 
385  /*!
386  \brief It calls a parameter function f to apply in all pixels from the band, e.g. pixel = f(lhs, rhs);
387 
388  \param (*f) a function with the signature complex<double>(*f)(complex<double>, complex<double>)
389 
390  \param cvalue The constant value that will work with the generic function.
391 
392  \return The resultant band.
393  */
394  Band& callOperator(std::complex<double>(*f)(std::complex<double>, std::complex<double>), std::complex<double>& cvalue);
395 
396  /*!
397  \brief It returns the band sum (pixel by pixel).
398 
399  \param rhs The band to be added, right-hand side.
400 
401  \note Both bands must have the same properties, #columns, #rows, and data type.
402 
403  \note The caller is responsible to guarantee that resultant values
404  will not exceed the range of the data type.
405 
406  \return The band sum.
407  */
408  virtual Band& operator+=(Band& rhs);
409 
410  /*!
411  \brief It returns the sum of a constant value to all pixels in the band.
412 
413  \param cvalue The constant value to be added.
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 sum.
419  */
420  virtual Band& operator+=(std::complex<double>& cvalue);
421 
422  /*!
423  \brief It returns the band subtraction (pixel by pixel).
424 
425  \param rhs The band to be subtracted, right-hand side.
426 
427  \note Both bands must have the same properties, #columns, #rows, and data type.
428 
429  \note The caller is responsible to guarantee that resultant values
430  will not exceed the range of the data type.
431 
432  \return The band subtraction.
433  */
434  virtual Band& operator-=(Band& rhs);
435 
436  /*!
437  \brief It returns the difference from all pixels in the band to a constant value (pixel - constant).
438 
439  \param cvalue The constant value to be subtracted.
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 difference.
445  */
446  virtual Band& operator-=(std::complex<double>& cvalue);
447 
448  /*!
449  \brief It returns the band product (pixel by pixel).
450 
451  \param rhs The band to be multiplied, right-hand side.
452 
453  \note Both bands must have the same properties, #columns, #rows, and data type.
454 
455  \note The caller is responsible to guarantee that resultant values
456  will not exceed the range of the data type.
457 
458  \return The band product.
459  */
460  virtual Band& operator*=(Band& rhs);
461 
462  /*!
463  \brief It returns the product of a constant value to all pixels in the band.
464 
465  \param cvalue The constant value to be multiplied.
466 
467  \note The caller is responsible to guarantee that resultant values
468  will not exceed the range of the data type.
469 
470  \return The band product.
471  */
472  virtual Band& operator*=(std::complex<double>& cvalue);
473 
474  /*!
475  \brief It returns the band division (pixel by pixel).
476 
477  \param rhs The band to be divided, right-hand side.
478 
479  \note Both bands must have the same properties, #columns, #rows, and data type.
480 
481  \note The caller is responsible to guarantee that resultant values
482  will not exceed the range of the data type.
483 
484  \return The band division.
485  */
486  virtual Band& operator/=(Band& rhs);
487 
488  /*!
489  \brief It returns the division of all pixels in the band by a constant value (pixel / constant).
490 
491  \param cvalue The constant value to be divided.
492 
493  \note The caller is responsible to guarantee that resultant values
494  will not exceed the range of the data type.
495 
496  \return The band division.
497  */
498  virtual Band& operator/=(std::complex<double>& cvalue);
499 
500  /*! \brief It returns the number of bytes ocuppied by a data block. */
501  virtual int getBlockSize() const;
502 
503  protected:
504 
505  /*!
506  \brief Copy constructor.
507 
508  \param rhs The right-hand-side copy used to copy from.
509  */
510  Band(const Band& rhs);
511 
512  protected:
513 
514  BandProperty* m_property; //!< The band information.
515  std::size_t m_idx; //!< The band index.
516  };
517 
518  } // end namespace rst
519 } // end namespace te
520 
521 #endif // __TERRALIB_RASTER_INTERNAL_BAND_H
te::rst::Band::getMeanValue
virtual std::complex< double > getMeanValue(unsigned int rs=0, unsigned int cs=0, unsigned int rf=0, unsigned int cf=0) const
It computes and returns the mean of the occurring values in a window of the band.
Raster.h
Raster implementaton for TerraLib 4.x.
RasterProperty.h
Raster property.
te
TerraLib.
Definition: AddressGeocodingOp.h:52
te::rst::Band
A raster band description.
Definition: Band.h:64
te::rst::Band::Band
Band(const Band &rhs)
Copy constructor.
te::rst::Band::m_property
BandProperty * m_property
The band information.
Definition: Band.h:514
te::rst::Band::operator+=
virtual Band & operator+=(std::complex< double > &cvalue)
It returns the sum of a constant value to all pixels in the band.
te::rst::Band::callOperator
Band & callOperator(std::complex< double >(*f)(std::complex< double >, std::complex< double >), std::complex< double > &cvalue)
It calls a parameter function f to apply in all pixels from the band, e.g. pixel = f(lhs,...
te::rst::Band::setIValue
virtual void setIValue(unsigned int c, unsigned int r, const double value)=0
Sets the imaginary attribute value in a complex band of a cell.
te::rst::Raster
An abstract class for raster data strucutures.
Definition: Raster.h:72
te::rst::Band::getBlockSize
virtual int getBlockSize() const
It returns the number of bytes ocuppied by a data block.
te::rst::Band::Band
Band(BandProperty *p, std::size_t idx)
Constructor.
te::rst::Band::getIValue
virtual void getIValue(unsigned int c, unsigned int r, double &value) const =0
Returns the imaginary attribute value in a complex band of a cell.
te::rst::Band::setOffsetValue
void setOffsetValue(const std::complex< double > o)
Sets the offset values (real and imaginary) to be applied to the band.
te::rst::Band::getMaxValue
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
It computes and returns the maximum occurring value in a window of the band.
te::rst::Band::getHistogramI
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
It computes and returns the histogram occurring values (imaginary part) in a window of the band.
te::rst::Band::read
virtual void read(int x, int y, void *buffer) const =0
It reads a data block to the specified buffer.
te::rst::Band::operator*=
virtual Band & operator*=(Band &rhs)
It returns the band product (pixel by pixel).
te::rst::Band::operator/=
virtual Band & operator/=(std::complex< double > &cvalue)
It returns the division of all pixels in the band by a constant value (pixel / constant).
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::Band::setScaleValue
void setScaleValue(const std::complex< double > s)
Sets the scale values (real and imaginary) to be applied to the band.
te::rst::Band::setValue
virtual void setValue(unsigned int c, unsigned int r, const double value)=0
Sets the cell attribute value.
te::rst::Band::getProperty
BandProperty * getProperty()
Returns the band property.
te::rst::Band::callOperator
Band & callOperator(std::complex< double >(*f)(std::complex< double >, std::complex< double >), Band &rhs)
It calls a parameter function f to apply in all pixels from two bands, e.g. pixel = f(lhs,...
te::rst::Band::getProperty
const BandProperty * getProperty() const
Returns the band property.
te::rst::Band::operator-=
virtual Band & operator-=(Band &rhs)
It returns the band subtraction (pixel by pixel).
te::rst::Band::getRaster
virtual Raster * getRaster() const =0
Returns the associated raster.
te::rst::Band::operator+=
virtual Band & operator+=(Band &rhs)
It returns the band sum (pixel by pixel).
te::rst::Band::~Band
virtual ~Band()
Virtual destructor.
te::rst::Band::getOffsetValue
std::complex< double > getOffsetValue() const
It returns the offset values (real and imaginary) to be applied to the band.
te::rst::Band::operator=
virtual Band & operator=(const Band &rhs)
Assignment operator.
te::rst::Band::getScaleValue
std::complex< double > getScaleValue() const
It returns the scale values (real and imaginary) to be applied to the band.
te::rst::Band::getValue
virtual void getValue(unsigned int c, unsigned int r, std::complex< double > &value) const
Returns the imaginary attribute value in a complex band of a cell.
te::rst::BandProperty
A raster band description.
Definition: BandProperty.h:62
te::rst::Band::write
virtual void write(int x, int y, void *buffer)=0
It writes a data block from the specified buffer.
te::rst::Band::getHistogramR
virtual void getHistogramR(const unsigned int rowStart, const unsigned int colStart, const unsigned int finalRow, const unsigned int finalCol, const unsigned int histoBins, const unsigned int sampleStep, std::map< double, unsigned > &histogram) const
It computes and returns the histogram occurring values (real part) in a window of the band.
te::rst::Band::m_idx
std::size_t m_idx
The band index.
Definition: Band.h:515
te::rst::Band::getBlockBuffer
virtual void getBlockBuffer(void *buffer, int x0, int y0, int width, int height, int outWidth, int outHeight, int dataType)
It gets the buffer in just only one block that represents the region informed.
te::rst::Band::operator*=
virtual Band & operator*=(std::complex< double > &cvalue)
It returns the product of a constant value to all pixels in the band.
te::rst::Band::setValue
virtual void setValue(unsigned int c, unsigned int r, const std::complex< double > &value)
Sets the imaginary attribute value in a complex band of a cell.
te::rst::Band::getMinValue
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
It computes and returns the minimum occurring value in a window of the band.
te::rst::Band::getHistogramR
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
It computes and returns the histogram occurring values (real part) in a window of the band.
Config.h
Proxy configuration file for TerraView (see terraview_config.h).
te::rst::Band::operator/=
virtual Band & operator/=(Band &rhs)
It returns the band division (pixel by pixel).
te::rst::Band::operator-=
virtual Band & operator-=(std::complex< double > &cvalue)
It returns the difference from all pixels in the band to a constant value (pixel - constant).
te::rst::Band::getStdValue
virtual std::complex< double > getStdValue(unsigned int rs=0, unsigned int cs=0, unsigned int rf=0, unsigned int cf=0) const
It computes and returns the standard deviation of the occurring values in a window of the band.
te::rst::Band::getValue
virtual void getValue(unsigned int c, unsigned int r, double &value) const =0
Returns the cell attribute value.
te::rst::Band::read
virtual void * read(int x, int y)=0
It reads and returns a data block.