Functions.h

Go to the documentation of this file.

/*  Copyright (C) 2008 National Institute For Space Research (INPE) - Brazil.
 
    This file is part of the TerraLib - a Framework for building GIS enabled applications.
 
    TerraLib is free software: you can redistribute it and/or modify
    it under the terms of the GNU Lesser General Public License as published by
    the Free Software Foundation, either version 3 of the License,
    or (at your option) any later version.
 
    TerraLib is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
    GNU Lesser General Public License for more details.
 
    You should have received a copy of the GNU Lesser General Public License
    along with TerraLib. See COPYING. If not, write to
    TerraLib Team at <terralib-team@terralib.org>.
 */
 
/*!
  \file terralib/rp/Functions.h
  \brief Raster Processing functions.
 */
 
#ifndef __TERRALIB_RP_INTERNAL_FUNCTIONS_H
#define __TERRALIB_RP_INTERNAL_FUNCTIONS_H
 
#include "Config.h"
 
#include "FeedersRaster.h"
#include "Matrix.h"
#include "Macros.h"
#include "RasterHandler.h"
#include "../dataaccess/datasource/DataSource.h"
#include "../raster/Raster.h"
#include "../raster/RasterFactory.h"
#include "../raster/Grid.h"
#include "../raster/BandProperty.h"
#include "../raster/RasterFactory.h"
#include "../raster/Interpolator.h"
#include "../raster/Utils.h"
#include "../raster/PositionIterator.h"
#include "../srs/Converter.h"
#include "../geometry/LinearRing.h"
#include "../geometry/GTParameters.h"
#include "../geometry/MultiPoint.h"
#include "../geometry/Surface.h"
 
// STL
#include <memory>
#include <map>
#include <vector>
#include <string>
#include <limits>
 
// Boost
#include <boost/numeric/ublas/matrix.hpp>
#include <boost/shared_ptr.hpp>
 
namespace te
{
  namespace rst
  {
    class BandProperty;
    class Grid;
  }
 
  namespace rp
  {
    /*!
      \brief Wavelet Atrous Filter types.
      \ingroup rp_func
     */    
    enum WaveletAtrousFilterType
    {
      InvalidWAFilter, //!< Invalid filter type
      B3SplineWAFilter, //!< Spline filter type.
      TriangleWAFilter //!< Triangle filter type.
    };
 
    struct TERPEXPORT SpectralSensorParams
    {
      SpectralSensorParams() {}
 
      SpectralSensorParams(const int &band, const double &lower, const double &upper, const double &min, const double &max) :
        m_band(band),
        m_lower(lower),
        m_upper(upper),
        m_min(min),
        m_max(max)
      {}
 
      int m_band;
      double m_lower;
      double m_upper;
      double m_min;
      double m_max;
    };
 
    /*!
      \brief Create a new raster into the givem data source.
      \param rasterGrid The template grid used to create the output raster.
      \param bandsProperties The template band properties used to create the output raster.
      \param outDataSetName The data set name to give to the created data set.
      \param dataSourceType The data source type string (i.e. GDAL, MEM.)( See te::rst::RasterFactory dictionary for valid registered values ).
      \param outRasterHandler The created raster handler.
      \return true if OK, false on errors.
      \note All bandsProperties pointed objects will be acquired by this function and must not be deleted.
      \ingroup rp_func
     */
    bool TERPEXPORT CreateNewRaster( const te::rst::Grid& rasterGrid,
      const std::vector< te::rst::BandProperty* >& bandsProperties,
      const std::string& outDataSetName,
      const std::string& dataSourceType,
      RasterHandler& outRasterHandler );    
 
    /*!
      \brief Create a new raster into the givem data source.
      \param rasterGrid The template grid used to create the output raster.
      \param bandsProperties The template band properties used to create the output raster.
      \param outDataSetName The data set name to give to the created data set.
      \param outDataSource The data source to use when creating the output data set.
      \param outRasterHandler The created raster handler.
      \return true if OK, false on errors.
      \note All bandsProperties pointed objects will be acquired by this function and must not be deleted.
      \ingroup rp_func
     */
    bool TERPEXPORT CreateNewRaster( const te::rst::Grid& rasterGrid,
      const std::vector< te::rst::BandProperty* >& bandsProperties,
      const std::string& outDataSetName,
      te::da::DataSource& outDataSource,
      RasterHandler& outRasterHandler );
    
    /*!
      \brief Create a new raster into the givem data source.
      \param rasterGrid The template grid used to create the output raster.
      \param bandsProperties The template band properties used to create the output raster.
      \param rasterInfo The output raster info (specific driver info).
      \param rasterType The output raster type (specific driver name - See te::rst::RasterFactory dictorary for more info).
      \param outRasterPtr The created raster pointer.
      \return true if OK, false on errors.
      \note All bandsProperties pointed objects will be acquired by this function and must not be deleted.
      \ingroup rp_func
     */
    bool TERPEXPORT CreateNewRaster( const te::rst::Grid& rasterGrid,
      const std::vector< te::rst::BandProperty* >& bandsProperties,
      const std::map< std::string, std::string>& rasterInfo,
      const std::string& rasterType,
      std::unique_ptr< te::rst::Raster >& outRasterPtr );    
 
    /*!
      \brief Create a new raster into a new memory datasource.
      \param rasterGrid The template grid used to create the output raster.
      \param bandsProperties The template band properties used to create the output raster.
      \param outRasterHandler The created raster handler.
      \return true if OK, false on errors.
      \note All bandsProperties pointed objects will be acquired by this function and must not be deleted.
      \ingroup rp_func
     */
    bool TERPEXPORT CreateNewMemRaster( const te::rst::Grid& rasterGrid,
      std::vector< te::rst::BandProperty* > bandsProperties,
      RasterHandler& outRasterHandler );
 
    /*!
      \brief Create a new raster into a GDAL datasource.
      \param rasterGrid The template grid used to create the output raster.
      \param bandsProperties The template band properties used to create the output raster.
      \param fileName The output tif file name.
      \param outRasterHandler The created raster handler.
      \return true if OK, false on errors.
      \note All bandsProperties pointed objects will be acquired by this function and must not be deleted.
      \ingroup rp_func
     */
    bool TERPEXPORT CreateNewGdalRaster( const te::rst::Grid& rasterGrid,
      std::vector< te::rst::BandProperty* > bandsProperties,
      const std::string& fileName,
      RasterHandler& outRasterHandler );
    
    /*!
      \brief Create a new raster into a GDAL datasource.
      \param rasterGrid The template grid used to create the output raster.
      \param bandsProperties The template band properties used to create the output raster.
      \param fileName The output tif file name.
      \param outRasterPtr The created raster pointer.
      \return true if OK, false on errors.
      \note All bandsProperties pointed objects will be acquired by this function and must not be deleted.
      \ingroup rp_func
     */
    bool TERPEXPORT CreateNewGdalRaster( const te::rst::Grid& rasterGrid,
      std::vector< te::rst::BandProperty* > bandsProperties,
      const std::string& fileName,
      std::unique_ptr< te::rst::Raster >& outRasterPtr );    
      
    /*!
      \brief Create a new raster into a GDAL datasource.
      \param rasterGrid The template grid used to create the output raster.
      \param bandsProperties The template band properties used to create the output raster.
      \param fileName The output tif file name.
      \param outRasterHandler The created raster handler.
      \return true if OK, false on errors.
      \note All bandsProperties pointed objects will be acquired by this function and must not be deleted.
      \ingroup rp_func
     */
    bool TERPEXPORT Copy2DiskRaster( 
      const te::rst::Raster& inputRaster,
      const std::string& fileName );      
 
    /*!
      \brief Returns the real data type range (all values that can be represented by the given data type).
      \param dataType The data type.
      \param min The minimum value.
      \param max The maximum value.
      \note The types are listed in terralib/datatype/DataTypes.h
      \ingroup rp_func
    */
    inline void TERPEXPORT GetDataTypeRange( const int dataType, double& min, double& max )
    {
      te::rst::GetDataTypeRanges( dataType, min, max );
    }
 
    /*!
      \brief Convert vector elements.
      \param inputVector Input vector.
      \param inputVectorDataType Input vector data type.
      \param inputVectorSize The numer of input vector elements.
      \param outputVector A pré-allocated output vector.
      \note The types are listed in terralib/datatype/DataTypes.h
      \ingroup rp_func
    */
    void TERPEXPORT Convert2DoublesVector( void* inputVector, const int inputVectorDataType,
      unsigned int inputVectorSize, double* outputVector );
 
    /*!
      \brief Convert a doubles vector.
      \param inputVector Input vector.
      \param inputVectorSize The numer of input vector elements.
      \param inputVectorDataType Input vector data type.
      \param outputVector A pré-allocated output vector.
      \note The types are listed in terralib/datatype/DataTypes.h
      \ingroup rp_func
    */
    void TERPEXPORT ConvertDoublesVector( double* inputVector,
      unsigned int inputVectorSize, const int outputVectorDataType,
      void* outputVector );
      
    /*!
      \brief Create a tiff file from a matrix.
      \param matrix The matrix.
      \param normalize Enable/disable pixel normalization (8bit);
      \param tifFileName Tif file name.
      \param return true if OK, false on errors.
      \ingroup rp_func
    */      
    template< typename MatrixElementT >
    bool CreateRasterFileFromMatrix( const te::rp::Matrix< MatrixElementT >& matrix,
      const bool normalize, const std::string& fileName )
    {
      std::map<std::string, std::string> rInfo;
      rInfo["URI"] = fileName;
      
      std::vector<te::rst::BandProperty*> bandsProperties;
      if( normalize )
        bandsProperties.push_back(new te::rst::BandProperty( 0, te::dt::UCHAR_TYPE, "" ));
      else
        bandsProperties.push_back(new te::rst::BandProperty( 0, te::dt::DOUBLE_TYPE, "" ));
      bandsProperties[0]->m_colorInterp = te::rst::GrayIdxCInt;
      bandsProperties[0]->m_noDataValue = -1.0 * std::numeric_limits<double>::max();
 
      te::rst::Grid* newgrid = new te::rst::Grid( matrix.getColumnsNumber(),
        matrix.getLinesNumber(), 0, -1 );
 
      std::unique_ptr< te::rst::Raster > outputRasterPtr;
      try
      {
        outputRasterPtr.reset(
          te::rst::RasterFactory::make( "GDAL", newgrid, bandsProperties, rInfo, 0, 0));
      }
      catch(...)
      {
        outputRasterPtr.reset();
      }
      TERP_TRUE_OR_RETURN_FALSE( outputRasterPtr.get(), "Output raster creation error");
          
      unsigned int line = 0;
      unsigned int col = 0;
      const unsigned int nLines = matrix.getLinesNumber();
      const unsigned int nCols = matrix.getColumnsNumber();
      MatrixElementT matrixValue = 0;
 
      MatrixElementT gain = 1.0;
      MatrixElementT offset = 0.0;
      if( normalize )
      {
        MatrixElementT matrixValueMin = std::numeric_limits< MatrixElementT >::max();
        MatrixElementT matrixValueMax = -1.0 * matrixValueMin;
        for( line = 0 ; line < nLines ; ++line )
        {
          for( col = 0 ; col < nCols ; ++col )
          {
            matrixValue = matrix[ line ][ col ];
            if( matrixValue < matrixValueMin )
              matrixValueMin = matrixValue;
            if( matrixValue > matrixValueMax )
              matrixValueMax = matrixValue;
          }
        }
          
        if( matrixValueMax == matrixValueMin )
        {
          gain = 0.0;
          offset = 0.0;
        }
        else
        {
          gain = 255.0 / ( matrixValueMax - matrixValueMin );
          offset = -1.0 * ( matrixValueMin );
        }
      }
      
      const MatrixElementT min0 = 0;
      const MatrixElementT max255 = 255;
      
      for( line = 0 ; line < nLines ; ++line )
      {
        for( col = 0 ; col < nCols ; ++col )
        {
          matrixValue = matrix[ line ][ col ];
        
          if( normalize )
          {
            matrixValue += offset;
            matrixValue *= gain;
            matrixValue = std::max( min0, matrixValue );
            matrixValue = std::min( max255, matrixValue );
          }
          
          outputRasterPtr->setValue( col, line, static_cast<double>(matrixValue), 0 );
        }
      }
      
      return true;
    } 
    
    /*!
    \brief Returns a json filename with spectral sensors parameters.
    \ingroup rp_func
    */
    TERPEXPORT std::string GetSensorFilename();
 
    /*! 
      \brief Returns a vector os with band's names. 
      \ingroup rp_func
    */
    TERPEXPORT std::vector<std::string> GetBandNames();
 
    /*!
    \brief Returns a map with spectral sensors parameters defined in SpectralSensor.json file.
    \ingroup rp_func
    */
    TERPEXPORT std::map<std::string, SpectralSensorParams > getSensorParams();
 
    /*!
    \brief Saves in SpectralSensor.json file the spectral sensors parameters.
    \ingroup rp_func
    */
    TERPEXPORT void SaveSensorParams(std::map<std::string, SpectralSensorParams > &);
    
    /*!
      \brief Get the maximun and minimum reflectance values of a given sensor/band.
      \param specBandInfo The requested band info.
      \return true if the requested band name was found, false if not.  
      \ingroup rp_func
    */
    TERPEXPORT bool GetSpectralBandInfo(const std::string& bandName,
      SpectralSensorParams& specBandInfo );    
 
    /*!
      \brief Get all spectral band infos.
      \param specBandInfos The requested bands infos.
      \ingroup rp_func
    */
    TERPEXPORT void GetAllSpectralBandInfos(
      std::map<std::string, struct SpectralSensorParams >& specBandInfos );
 
    /*! 
      \brief Returns the minimum reflectance value of a given sensor/band. 
      \ingroup rp_func
    */
    TERPEXPORT double GetSpectralBandMin(std::string bandName);
 
    /*! 
      \brief Returns the maximum reflectance value of a given sensor/band. 
      \ingroup rp_func
    */
    TERPEXPORT double GetSpectralBandMax(std::string bandName);
 
    /*! 
      \brief Returns the maximun and minimum digital numbers of a given sensor/band. 
      \ingroup rp_func
    */
    TERPEXPORT std::pair<double, double> GetDigitalNumberBandInfo(std::string bandName);
 
    /*!
    \brief Returns the maximum digital number of a given sensor/band.
    \ingroup rp_func
    */
    TERPEXPORT double GetDigitalNumberBandMax(std::string bandName);
 
    /*!
    \brief Returns the minimum digital number of a given sensor/band.
    \ingroup rp_func
    */
    TERPEXPORT double GetDigitalNumberBandMin(std::string bandName);
 
    /*!
      \brief Normalizes one raster in a given interval.
 
      \param inputRaster     The given raster.
      \param nmin            The new minimum value (default = 0.0).
      \param nmax            The new maximum value (default = 255.0).
 
      \return true if normalization occurs and false otherwise.
      \ingroup rp_func
    */
    TERPEXPORT bool NormalizeRaster(te::rst::Raster& inputRaster, double nmin = 0.0, double nmax = 255.0);
 
    /*!
      \brief Normalizes a raster in a given interval.
 
      \param inputRaster     The given raster.
 
      \return a raster normalized or null pointer on errors.
      \ingroup rp_func
    */
    TERPEXPORT te::rst::Raster* NormalizeRaster(const te::rst::Raster *inputRaster);
 
    /*!
      \brief RGB to IHS conversion.
      \param inputRGBRaster The input raster.
      \param redBandIdx The red band index.
      \param greenBandIdx The red band index.
      \param blueBandIdx The red band index.
      \param rgbRangeMin The minimum RGB value.
      \param rgbRangeMax The maximum RGB value.
      \param outputIHSRaster An output pré-initiated raster (with the same dimensions of inputRGBRaster) where the IHS data will be written (double or float as the data type).
      \return true if OK, false on errors.
      \note The outputIHSRaster mas have a float or double data type. 
      \note IHS data with the following channels ranges: I:[0,1] H:[0,2pi] (radians) S:[0,1].
      \ingroup rp_func   
    */
    TERPEXPORT bool ConvertRGB2IHS( const te::rst::Raster& inputRGBRaster, 
      const unsigned int redBandIdx, const unsigned int greenBandIdx,
      const unsigned int blueBandIdx, const double rgbRangeMin, 
      const double rgbRangeMax, te::rst::Raster& outputIHSRaster );  
 
    /*!
    \brief RGB to IHS conversion.
    \param inputRedRaster The input red raster.
    \param redBandIdx The red band index.
    \param inputGreenRaster The input green raster.
    \param greenBandIdx The green band index.
    \param inputBlueRaster The input blue raster.
    \param blueBandIdx The blue band index.
    \param rgbRangeMin The minimum RGB value.
    \param rgbRangeMax The maximum RGB value.
    \param outputIHSRaster An output pré-initiated raster (with the same dimensions of inputRGBRaster) where the IHS data will be written (double or float as the data type).
    \return true if OK, false on errors.
    \note The outputIHSRaster mas have a float or double data type.
    \note IHS data with the following channels ranges: I:[0,1] H:[0,2pi] (radians) S:[0,1].
    \ingroup rp_func
    */
    TERPEXPORT bool ConvertRGB2IHS(const te::rst::Raster& inputRedRaster, const unsigned int redBandIdx,
      const te::rst::Raster& inputGreenRaster, const unsigned int greenBandIdx,
      const te::rst::Raster& inputBlueRaster, const unsigned int blueBandIdx,
      const double rgbRangeMin, const double rgbRangeMax, te::rst::Raster& outputIHSRaster);
      
    /*!
      \brief IHS to RGB conversion.
      \param inputIHSRaster The input raster.
      \param intensityBandIdx The intensity band index.
      \param hueBandIdx The hue band index.
      \param saturationBandIdx The saturation band index.
      \param rgbRangeMin The minimum RGB value.
      \param rgbRangeMax The maximum RGB value.      
      \param outputRGBRaster An output pré-initiated raster (with the same dimensions of inputIHSRaster) where the RGB data will be written.
      \return true if OK, false on errors.
      \note IHS data with the following channels ranges: I:[0,1] H:[0,2pi] (radians) S:[0,1].      
      \ingroup rp_func
    */
    TERPEXPORT bool ConvertIHS2RGB( const te::rst::Raster& inputIHSRaster, 
      const unsigned int intensityBandIdx, const unsigned int hueBandIdx,
      const unsigned int saturationBandIdx, const double rgbRangeMin, 
      const double rgbRangeMax, te::rst::Raster& outputRGBRaster );      
 
    /*!
    \brief IHS to RGB conversion.
    \param inputIRaster The input intensity raster.
    \param intensityBandIdx The intensity band index.
    \param inputHRaster The input hue raster.
    \param hueBandIdx The hue band index.
    \param inputSRaster The input saturation raster.
    \param saturationBandIdx The saturation band index.
    \param rgbRangeMin The minimum RGB value.
    \param rgbRangeMax The maximum RGB value.
    \param outputRGBRaster An output pré-initiated raster (with the same dimensions of inputIHSRaster) where the RGB data will be written.
    \return true if OK, false on errors.
    \note IHS data with the following channels ranges: I:[0,1] H:[0,2pi] (radians) S:[0,1].
    \ingroup rp_func
    */
    TERPEXPORT bool ConvertIHS2RGB(const te::rst::Raster& inputIRaster, const unsigned int intensityBandIdx,
      const te::rst::Raster& inputHRaster, const unsigned int hueBandIdx,
      const te::rst::Raster& inputSRaster, const unsigned int saturationBandIdx,
      const double rgbRangeMin, const double rgbRangeMax, te::rst::Raster& outputRGBRaster);
 
    /*!
    \brief RGB to HLS conversion.
    \param inputRGBRaster The input raster.
    \param redBandIdx The red band index.
    \param greenBandIdx The red band index.
    \param blueBandIdx The red band index.
    \param rgbRangeMin The minimum RGB value.
    \param rgbRangeMax The maximum RGB value.
    \param outputHLSRaster An output pré-initiated raster (with the same dimensions of inputRGBRaster) where the HLS data will be written (double or float as the data type).
    \return true if OK, false on errors.
    \note The outputHLSRaster mas have a float or double data type.
    \ingroup rp_func
    */
    TERPEXPORT bool ConvertRGB2HLS(const te::rst::Raster& inputRGBRaster,
      const unsigned int redBandIdx, const unsigned int greenBandIdx,
      const unsigned int blueBandIdx, const double rgbRangeMin,
      const double rgbRangeMax, te::rst::Raster& outputHLSRaster);
 
    /*!
    \brief RGB to HLS conversion.
    \param inputRedRaster The input red raster.
    \param redBandIdx The red band index.
    \param inputGreenRaster The input green raster.
    \param greenBandIdx The green band index.
    \param inputBlueRaster The input blue raster.
    \param blueBandIdx The blue band index.
    \param rgbRangeMin The minimum RGB value.
    \param rgbRangeMax The maximum RGB value.
    \param outputHLSRaster An output pré-initiated raster (with the same dimensions of inputRGBRaster) where the HLS data will be written (double or float as the data type).
    \return true if OK, false on errors.
    \note The outputHLSRaster mas have a float or double data type.
    \ingroup rp_func
    */
    TERPEXPORT bool ConvertRGB2HLS(const te::rst::Raster& inputRedRaster, const unsigned int redBandIdx,
      const te::rst::Raster& inputGreenRaster, const unsigned int greenBandIdx,
      const te::rst::Raster& inputBlueRaster, const unsigned int blueBandIdx,
      const double rgbRangeMin, const double rgbRangeMax, te::rst::Raster& outputHLSRaster);
 
    /*!
    \brief HLS to RGB conversion.
    \param inputHLSRaster The input raster.
    \param hueBandIdx The hue band index.
    \param lightBandIdx The light band index.
    \param saturationBandIdx The saturation band index.
    \param rgbRangeMin The minimum RGB value.
    \param rgbRangeMax The maximum RGB value.
    \param outputRGBRaster An output pré-initiated raster (with the same dimensions of inputHLSRaster) where the RGB data will be written.
    \return true if OK, false on errors.
    \ingroup rp_func
    */
    TERPEXPORT bool ConvertHLS2RGB(const te::rst::Raster& inputHLSRaster,
      const unsigned int hueBandIdx, const unsigned int lightBandIdx,
      const unsigned int saturationBandIdx, const double rgbRangeMin,
      const double rgbRangeMax, te::rst::Raster& outputRGBRaster);
 
    /*!
    \brief HLS to RGB conversion.
    \param inputHRaster The input hue raster.
    \param hueBandIdx The hue band index.
    \param inputLRaster The input light raster.
    \param lightBandIdx The light band index.
    \param inputSRaster The input saturation raster.
    \param saturationBandIdx The saturation band index.
    \param rgbRangeMin The minimum RGB value.
    \param rgbRangeMax The maximum RGB value.
    \param outputRGBRaster An output pré-initiated raster (with the same dimensions of inputHLSRaster) where the RGB data will be written.
    \return true if OK, false on errors.
    \ingroup rp_func
    */
    TERPEXPORT bool ConvertHLS2RGB(const te::rst::Raster& inputHRaster, const unsigned int hueBandIdx,
      const te::rst::Raster& inputLRaster, const unsigned int lightBandIdx,
      const te::rst::Raster& inputSRaster, const unsigned int saturationBandIdx,
      const double rgbRangeMin, const double rgbRangeMax, te::rst::Raster& outputRGBRaster);
      
    /*!
      \brief Get the mean of band pixel values.
      \param inputRaster The input raster.
      \param inputBandIndex Input band index.
      \param maxThreads The maximum number of threads to use (0-auto, 1-single thread used).
      \param forceNoDataValue Ignore the raster original band no-data value and use the value given by the parameter noDataValue.
      \param noDataValue The no-data value to be used insted of the original raster band no-data value.
      \param meanValue The calculated mean value.
      \return true if OK, false on errors.
      \note Optimized for rasters where the used bands have the same blocking scheme.
      \ingroup rp_func
    */
    TERPEXPORT bool GetMeanValue(
      const te::rst::Raster& inputRaster,
      const unsigned int inputBandIndex,
      const unsigned int maxThreads, 
      const bool forceNoDataValue,
      const double noDataValue,
      double& meanValue );    
      
    /*!
      \brief Get the standard deviation of band pixel values.
      \param inputRaster The input raster.
      \param inputBandIndex Input band index.
      \param maxThreads The maximum number of threads to use (0-auto, 1-single thread used).
      \param forceNoDataValue Ignore the raster original band no-data value and use the value given by the parameter noDataValue.
      \param noDataValue The no-data value to be used insted of the original raster band no-data value.      
      \param meanValuePtr A pointer to a pre-calculated band mean value or zero if it does not exist.
      \param stdDevValue The calculated standard deviation value.
      \return true if OK, false on errors.
      \note Optimized for rasters where the used bands have the same blocking scheme.
      \ingroup rp_func
    */
    TERPEXPORT bool GetStdDevValue( 
      const te::rst::Raster& inputRaster,
      const unsigned int inputBandIndex,
      const unsigned int maxThreads, 
      const bool forceNoDataValue,
      const double noDataValue,      
      double const * const meanValuePtr, 
      double& stdDevValue );         
      
    /*!
      \brief Get the covariance of band pixel values.
      \param inputRaster1 The input raster 1.
      \param inputBandIndex1 Input raster 1 band index.
      \param inputRaster2 The input raster 2.
      \param inputBandIndex2 Input raster 2 band index.
      \param maxThreads The maximum number of threads to use (0-auto, 1-single thread used).
      \param mean1ValuePtr A pointer to a pre-calculated band1 mean value or zero if it does not exist.
      \param mean2ValuePtr A pointer to a pre-calculated band2 mean value or zero if it does not exist.
      \param covarianceValue The calculated covariance value.
      \return true if OK, false on errors.
      \ingroup rp_func
    */
    TERPEXPORT bool GetCovarianceValue( 
      const te::rst::Raster& inputRaster1,
      const unsigned int inputBandIndex1,
      const te::rst::Raster& inputRaster2,
      const unsigned int inputBandIndex2,
      const unsigned int maxThreads,
      double const * const mean1ValuePtr, 
      double const * const mean2ValuePtr,
      double& covarianceValue );      
      
    /*!
      \brief Generate all principal components from the given input raster.
      \param inputRaster Input raster.
      \param inputRasterBands Input raster bands.
      \param pcaMatrix The matrix generated over the principal components process.
      \param pcaRaster The pré-initiated output PCA raster (with the same dimensions of inputRaster) and double as the data type.
      \param pcaRasterBands Output raster bands.
      \param maxThreads The maximum number of threads to use (0-auto, 1-single thread used).
      \return true if OK, false on errors.
      \note Optimized for rasters where the used bands have the same blocking scheme.
      \ingroup rp_func
    */
    TERPEXPORT bool DirectPrincipalComponents( 
      const te::rst::Raster& inputRaster,
      const std::vector< unsigned int >& inputRasterBands,
      boost::numeric::ublas::matrix< double >& pcaMatrix,
      te::rst::Raster& pcaRaster,
      const std::vector< unsigned int >& pcaRasterBands,
      const unsigned int maxThreads );  
      
    /*!
      \brief Regenerate the original raster from its principal components.
      \param pcaRaster The principal components raster (with the same dimensions of outputRaster).
      \param pcaMatrix The matrix generated by the direct principal components process.
      \param outputRaster The regenerated output raster (with the same dimentions.
      \param outputRasterBands Output raster bands.
      \param maxThreads The maximum number of threads to use (0-auto, 1-single thread used).
      \return true if OK, false on errors.
      \note Optimized for rasters where the used bands have the same blocking scheme.
      \ingroup rp_func
    */
    TERPEXPORT bool InversePrincipalComponents( 
      const te::rst::Raster& pcaRaster,
      const boost::numeric::ublas::matrix< double >& pcaMatrix,
      te::rst::Raster& outputRaster,
      const std::vector< unsigned int >& outputRasterBands,
      const unsigned int maxThreads );       
 
    /*!
      \brief Remap all pixel values using a user supplied target values (non-target values are just copied from input to output).
      \param inputRaster Input raster.
      \param inputRasterBandIdx Input raster band.
      \param targetValues A vector of target values pairs in the form: std::pair< old_value, new_value >.
      \param enableProgress Enable/disable the progress interface.
      \param restrictionPols A vector of polygons where the remap must be executed or an empty vector indicating all pixels must be remapped.
      \param outputRaster The pré-initiated output raster.
      \param outputRasterBandIdx Output raster band.
      \return true if OK, false on errors.
      \note Optimized for rasters where the used bands have the same blocking scheme.
      \ingroup rp_func
    */
    TERPEXPORT bool SelectiveReplaceValues(
      const te::rst::Raster& inputRaster,
      const unsigned int& inputRasterBandIdx,
      const std::vector< std::pair< double, double > >& targetValues,
      const bool enableProgress,
      const std::vector< te::gm::Polygon* >& restrictionPols,
      te::rst::Raster& outputRaster,
      const unsigned int& outputRasterBandIdx );
      
    /*!
      \brief Remap pixel values using a remap function matrix.
      \param inputRaster Input raster.
      \param inputRasterBands Input raster bands.
      \param remapMatrix The remap function matrix.
      \param outputRaster The pré-initiated output raster (with the same dimentions of inputRaster).
      \param outputRasterBands Output raster bands.
      \param maxThreads The maximum number of threads to use (0-auto, 1-single thread used).
      \return true if OK, false on errors.
      \note Optimized for rasters where the used bands have the same blocking scheme.
      \ingroup rp_func
    */
    TERPEXPORT bool RemapValues( 
      const te::rst::Raster& inputRaster,
      const std::vector< unsigned int >& inputRasterBands,
      const boost::numeric::ublas::matrix< double >& remapMatrix,
      te::rst::Raster& outputRaster,
      const std::vector< unsigned int >& outputRasterBands,
      const unsigned int maxThreads ); 
    
    /*!
      \brief Decompose a multi-band raster into a set of one-band rasters.
      \param inputRaster Input raster.
      \param inputRasterBands Input raster bands.
      \param outputRastersInfos Output rasters connections infos. (one info for each decomposed band).
      \param outputDataSourceType Output raster datasource type.
      \param outputRastersPtrs Pointers to the generated outputs rasters.
      \return true if OK, false on errors.
      \ingroup rp_func
    */
    TERPEXPORT bool DecomposeBands( 
      const te::rst::Raster& inputRaster,
      const std::vector< unsigned int >& inputRasterBands,
      const std::vector< std::map<std::string, std::string> > & outputRastersInfos,
      const std::string& outputDataSourceType,
      std::vector< boost::shared_ptr< te::rst::Raster > > & outputRastersPtrs );   
    
    /*!
      \brief Compose a set of bands into one multi-band raster.
      \param inputRasters Input rasters.
      \param inputRasterBands Input raster bands (one band for each input raster).
      \param interpMethod The interpolator method to use.
      \param outputRasterInfo Output raster connection info.
      \param outputDataSourceType Output raster datasource type.
      \param maxThreads The maximum number of threads to use (0-auto, 1-single thread used).
      \param outputRasterPtr A pointer to the generated output raster.
      \param allowNoDataPixels If disabled only pixels with valid data on all bands will be written to the output raster.
      \param enableProgress Enable/disable the progress interface.
      \return true if OK, false on errors.
      \note The first raster Grid will be taken as reference for the composed raster.
      \ingroup rp_func
    */
    TERPEXPORT bool ComposeBands( 
      const std::vector< te::rst::Raster const * >& inputRasters,
      const std::vector< unsigned int >& inputRasterBands,
      const te::rst::Interpolator::Method& interpMethod,
      const std::map<std::string, std::string>& outputRasterInfo,
      const std::string& outputDataSourceType,
      const unsigned int maxThreads,
      const bool allowNoDataPixels,
      const bool enableProgress,
      std::unique_ptr< te::rst::Raster >& outputRasterPtr );
    
    /*!
      \brief Create a datailed extent from the given grid.
      \param grid Input grid.
      \param detailedExtent The created detailed extent.
      \return true if ok, false on errors.
      \ingroup rp_func
    */
    TERPEXPORT bool GetDetailedExtent( const te::rst::Grid& grid, 
      te::gm::LinearRing& detailedExtent );
    
    /*!
      \brief Create a indexed (lines,columns) datailed extent from the given grid.
      \param grid Input grid.
      \param indexedDetailedExtent The created detailed extent.
      \return true if ok, false on errors.
      \ingroup rp_func
    */
    TERPEXPORT bool GetIndexedDetailedExtent( const te::rst::Grid& grid, 
      te::gm::LinearRing& indexedDetailedExtent );  
    
    /*!
      \brief Create a Wavele Atrous Filter.
      \param filterType The filter type.
      \return the created filter.
      \ingroup rp_func
    */
    TERPEXPORT boost::numeric::ublas::matrix< double > 
      CreateWaveletAtrousFilter( const WaveletAtrousFilterType& filterType );     
    
    /*!
      \brief Generate all wavelet planes from the given input raster.
      \param inputRaster Input raster.
      \param inputRasterBands Input raster bands.
      \param waveletRaster The pré-initiated output wavelet raster (with the same dimensions of inputRaster) and double as the data type.
      \param levelsNumber The number of decomposed wavelet levels to generate for each input raster band;
      \param filter The square filter to use.
      \return true if OK, false on errors.
      \note The band order of the generated wavelet levels: { [ band0-smoothed0, band0-wavelet0, ... , band0-smoothedN, band0-waveletN ], ... }
      \note The number of bands of waveletRaster must be ( inputRasterBands.size() * 2 * levelsNumber ) at least.
      \ingroup rp_func
    */
    TERPEXPORT bool DirectWaveletAtrous( 
      const te::rst::Raster& inputRaster,
      const std::vector< unsigned int >& inputRasterBands,
      te::rst::Raster& waveletRaster,
      const unsigned int levelsNumber,
      const boost::numeric::ublas::matrix< double >& filter );     
    
    /*!
      \brief Regenerate the original raster from its wavelets planes.
      \param waveletRaster The input wavelet raster (with the same dimensions of outputRaster).
      \param levelsNumber The number of decomposed wavelet levels present inside the wavelet raster.
      \param outputRaster The regenerated output raster.
      \param outputRasterBands Output raster bands.
      \return true if OK, false on errors.
      \note The band order of the expected wavelet levels: { [ band0-smoothed0, band0-wavelet0, ... , band0-smoothedN, band0-waveletN ], ... }
      \note The number of bands of waveletRaster must be ( outputRasterBands.size() * 2 * levelsNumber ) at least.
      \note Only the wavelet bands and the last smoothed band are used.
      \ingroup rp_func
    */
    TERPEXPORT bool InverseWaveletAtrous( 
      const te::rst::Raster& waveletRaster,
      const unsigned int levelsNumber,
      te::rst::Raster& outputRaster,
      const std::vector< unsigned int >& outputRasterBands ); 
    
    /*!
      \brief Resample a subset of the raster, given a box.
      \param inputRaster Input raster.
      \param inputRasterBands Input raster bands to process.
      \param interpMethod      The method of interpolation. \sa te::rst::Interpolator
      \param interpWindowRadius Interpolator windows radius around the target pixel (when applicable).
      \param firstRow        The starting row to make a subset of the image.
      \param firstColumn     The starting column to make a subset of the image.
      \param height      The height of the subset.
      \param width       The width of the subset.
      \param newheight   The resampled height of the new raster.
      \param newwidth    The resampled width of the new raster.
      \param rinfo       The parameters needed to build the output raster (see RasterFactory documentation).
      \param dataSourceType Data source type (raster type. I.E. GDAL).
      \param resampledRasterPtr The resampled raster pointer.
      \return true if ok, false on errors.
      \ingroup rp_func
    */
    TERPEXPORT bool RasterResample( 
      const te::rst::Raster& inputRaster,
      const std::vector< unsigned int >& inputRasterBands,
      const te::rst::Interpolator::Method interpMethod, 
      const unsigned int interpWindowRadius, 
      const unsigned int firstRow,
      const unsigned int firstColumn, 
      const unsigned int height, 
      const unsigned int width,
      const unsigned int newheight, 
      const unsigned int newwidth, 
      const std::map<std::string, std::string>& rinfo,
      const std::string& dataSourceType,
      std::unique_ptr< te::rst::Raster >& resampledRasterPtr ); 
    
    /*!
      \brief Returns the tie points converx hull area.
      \param tiePoints Input tie-points (container of te::gm::GTParameters::TiePoint).
      \param useTPSecondCoordPair If true the sencond tie-point component (te::gm::GTParameters::TiePoint::second) will be used for the area calcule, otherwize the first component will be used.
      \return Returns the tie points converx hull area.
      \ingroup rp_func
    */          
    template< typename ContainerT >
    double GetTPConvexHullArea( const ContainerT& tiePoints,
      const bool useTPSecondCoordPair )
    {
      if( tiePoints.size() < 3 )
      {
        return 0;
      }
      else
      {
        te::gm::MultiPoint points( 0, te::gm::MultiPointType );
        
        typename ContainerT::const_iterator it =
          tiePoints.begin();
        const typename ContainerT::const_iterator itE =
          tiePoints.end();        
        
        while( it != itE )
        {
          if( useTPSecondCoordPair )
            points.add(new te::gm::Point(it->second.x, it->second.y));
          else
            points.add(new te::gm::Point(it->first.x, it->first.y));
            
          ++it;
        }
        
        std::unique_ptr< te::gm::Geometry > convexHullPolPtr( points.convexHull() );
        
        if( dynamic_cast< te::gm::Surface* >( convexHullPolPtr.get() ) )
        {
          return ( (te::gm::Surface*)( convexHullPolPtr.get() ) )->getArea();
        }
        else
        {
          return 0.0;
        }
      }
    }
    
    /*!
      \brief Create a fixed step sequential color palette.
      \param paletteSize The desired palette size.
      \param palette The crated palette.
      \ingroup rp_func
    */
    TERPEXPORT void CreateFixedStepPalette( 
      const unsigned int paletteSize,
      const bool randomize,
      std::vector< te::rst::BandProperty::ColorEntry >& palette );
    
    /*!
      \brief Create a new raster grouping pixel values following the number of slices and/or slice limits.
      \param inputRaster Input raster.
      \param inputRasterBand Input raster band.
      \param createPaletteRaster If true a paletted raster will be created instead of a multi-band raster..
      \param slicesNumber The number of histogram slices to create;
      \param eqHistogram If true, the input raster will be equalized before the slicing process.
      \param rasterInfo The output raster info (specific driver info).
      \param rasterType The output raster type (specific driver name - See te::rst::RasterFactory dictorary for more info).
      \param enableProgress Enable/disable the progress interface.
      \param palettePtr A pointer to an optional user given palette (if null, an fixed step pallete will be generated).
      \param outRasterPtr The output sliced raster pointer.
      \param slicesLimitsPtr A null pointer  or a pointer to a container of slice limits ( the small of the the values for each slice range ).
      \param slicesOutputValuesPtr A null pointer or a pointer to a vector of output raster values related to each slice.
      \return true if OK, false on errors.
      \ingroup rp_func
    */
    TERPEXPORT bool RasterSlicing( 
      const te::rst::Raster& inputRaster,
      const unsigned int inputRasterBand,
      const bool createPaletteRaster,
      const unsigned int slicesNumber,
      const bool eqHistogram,
      const std::map< std::string, std::string >& rasterInfo,
      const std::string& rasterType,
      const bool enableProgress,
      std::vector< te::rst::BandProperty::ColorEntry > const * const palettePtr,
      std::unique_ptr< te::rst::Raster >& outRasterPtr,
      std::vector< double > const* slicesLimitsPtr,
      std::vector< double > const* slicesOutputValuesPtr );
 
    /*!
      \brief Replace a contiguos segment pixel values.
      \param inputRaster Input raster.
      \param inputRasterBandIdx Input raster band to use.
      \param targetRow Target row (a point inside the target segment).
      \param targetCol Target col (a point inside the target segment).
      \param outputValue Output segment final value.
      \return true if OK, false on errors.
      \ingroup rp_func
    */
    TERPEXPORT bool ReplaceContiguousSegmentValues(
      te::rst::Raster& inputRaster,
      const unsigned int& inputRasterBandIdx,
      const unsigned targetRow,
      const unsigned targetCol,
      const double& outputValue );
 
    /*!
      \brief Replace a contiguos segment pixel values.
      \param inputRaster Input raster.
      \param inputRasterBandIdx Input raster band to use.
      \param outputRaster Input raster.
      \param outputRasterBandIdx Input raster band to use.
      \param targetRow Target row (a point inside the target segment).
      \param targetCol Target col (a point inside the target segment).
      \param outputValue Output segment final value.
      \return true if OK, false on errors.
      \ingroup rp_func
    */
    TERPEXPORT bool ReplaceContiguousSegmentValues(
      const te::rst::Raster& inputRaster,
      const unsigned int& inputRasterBandIdx,
      te::rst::Raster& outputRaster,
      const unsigned int& outputRasterBandIdx,
      const unsigned targetInputRow,
      const unsigned targetInputCol,
      const double& outputValue );
    
    /*!
      \brief Compute and return the histogram soccurring values (real and imaginary) inside defined regions of interest.
 
      \param raster Input raster.
      \param bandIndex Band index.
      \param rois Regions of interest (under the same SRID as the input raster) or an empty vector for the case where all the image must be processed.
      \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.
      \param maxThreads Maximum number of used threads to use (0-Automatic, 1-No threads used).
      \param roisItType ROIs polygons iteration type.
      \param rHistogram The generated histogram (real).
      \param iHistogram The generated histogram (imaginary).
      \return true if ok, false on errors
      \note This method will ignore storage specific tags and will read all raster data to compute the histograms (use te::rst::Band methods to use storage specifc tags).
      \ingroup rp_func
    */
    TERPEXPORT bool getHistograms(
      const te::rst::Raster& raster,
      const unsigned int bandIndex,
      const std::vector< te::gm::Polygon const* >& rois,
      const unsigned int histoBins,
      const unsigned int maxThreads,
      const te::rst::PolygonIterator< double >::IterationType roisItType,
      std::map<double, unsigned>& rHistogram,
      std::map<double, unsigned>& iHistogram );
    
    /*!
      \brief Compute statiscts from the given histogram.
 
      \param histogram Input histogram.
      \param min Histogram minimun value.
      \param max Histogram maximum value.
      \param mean Histogram mean value.
      \param stdDev Histogram standard deviation value.
      \param mode Histogram mode value.
      \param entropy Histogram mode value.
      \param sum Sum of all pixels values.
      \param sum2 Quadratic sum of all pixels values.
      \param sum3 The cubic sum of pixels values.
      \param sum4 The quartic sum of pixels values.
      \param variance Histogram variance value.
      \param median Histogram median value.
      \ingroup rp_func
    */
    TERPEXPORT void getHistogramStats(
      const std::map<double, unsigned int>& histogram,
      double& min,
      double& max,
      double& mean,
      double& stdDev,
      double& mode,
      double& entropy,
      double& sum,
      double& sum2,
      double& sum3,
      double& sum4,
      double& variance,
      double& median
      );
    
    /*!
      \brief Compute and return the joint histogram of occurring values (real and imaginary) inside defined regions of interest.
      \param raster Input raster.
      \param bandIndex1 Input raster Band 1 index.
      \param bandIndex2 Input raster Band 2 index.
      \param rois Regions of interest (under the same SRID as the input raster) or an empty vector for the case where all the image must be processed.
      \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.
      \param maxThreads Maximum number of used threads to use (0-Automatic, 1-No threads used).
      \param roisItType ROIs polygons iteration type.
      \param realJointHistogram The generated joint histogram (real).
      \param imagJointHistogram The generated joint histogram (imaginary).
      \param rasterRealHistogram1ptr A pointer to a pre-calculated input raster band 1 histogram (real) or a null pointer.
      \param rasterImagHistogram1Ptr A pointer to a pre-calculated input raster band 1 histogram (imaginary) or a null pointer.
      \param rasterRealHistogram2Ptr A pointer to a pre-calculated input raster band 2 histogram (real) or a null pointer.
      \param rasterImagHistogram2Ptr A pointer to a pre-calculated input raster band 2 histogram (imaginary) or a null pointer.
      \return true if ok, false on errors
      \note This method will ignore storage specific tags and will read all raster data to compute the histograms (use te::rst::Band methods to use storage specifc tags).
      \ingroup rp_func
    */
    TERPEXPORT bool getJointHistograms(
      const te::rst::Raster& raster,
      const unsigned int bandIndex1,
      const unsigned int bandIndex2,      
      const std::vector< te::gm::Polygon const* >& rois,
      const unsigned int histoBins,
      const unsigned int maxThreads,
      const te::rst::PolygonIterator< double >::IterationType roisItType,
      std::map< std::pair< double, double >, unsigned int>& realJointHistogram,
      std::map< std::pair< double, double >, unsigned int>& imagJointHistogram,
      std::map<double, unsigned int> const * const rasterRealHistogram1ptr,
      std::map<double, unsigned int> const * const rasterImagHistogram1Ptr,
      std::map<double, unsigned int> const * const rasterRealHistogram2Ptr,
      std::map<double, unsigned int> const * const rasterImagHistogram2Ptr );
    
    /*!
      \brief Compute statiscts from the given histogram.
 
      \param jointHistogram Input joint histogram where std::pair< double, double >.first are histogram1 values and std::pair< double, double >.second are histogram2 values
      \param histogram1 Histogram 1.
      \param histogram2 Histogram 2.
      \param covariance Calculated covariance value.
      \param corrlationCoef Pearson's Correlation coeficient.
      \return true if ok, false on errors.
    */
    TERPEXPORT bool getJointHistogramStats(
      const std::map< std::pair< double, double >, unsigned int>& jointHistogram,
      const std::map<double, unsigned int>& histogram1,
      const std::map<double, unsigned int>& histogram2,
      double& covariance,
      double& corrlationCoef );
    
    /*!
      \brief Raster data alignment by reprojection and clipping following a user defined area.
      \param inputRaster The input raster.
      \param inRasterBands Input raster bands to process.
      \param outputSRID The target SRID for the reprojection.
      \param llx Lower-left X-coordinate of target area (in the output SRS).
      \param lly Lower-left Y-coordinate of target area (in the output SRS).
      \param urx Upper-Right X-coordinate of target area (in the output SRS).
      \param ury Upper-Right Y-coordinate of target area (in the output SRS).
      \param routInfo   The basic parameters necessary to create the output raster.
      \param interpMethod The method of interpolation to apply.
      \param outputRasterPtr Output raster pointer.
      \return true if OK, false on errors.
      \note The output raster extent will be created from llx, lly, urx, ury.
      \ingroup rp_func
    */
    TERASTEREXPORT bool AlignRaster(
      const te::rst::Raster& inputRaster,
      const std::vector< unsigned int >& inRasterBands,
      const int outputSRID,
      const double llx, 
      const double lly, 
      const double urx, 
      const double ury, 
      const std::map<std::string, std::string>& routInfo, 
      const te::rst::Interpolator::Method& interpMethod,
      std::unique_ptr< te::rst::Raster >& outputRasterPtr );
 
    /*!
      \param Fill the target band with the target value.
      \param bandIndex Band index.
      \param value Target value.
      \return true if OK, false on errors.
      \ingroup rp_func
    */
    TERPEXPORT bool FillBand(
      te::rst::Raster& raster,
      const unsigned int bandIndex,
      const std::complex< double >& value );
    
    /*!
      \brief Compute the external raster valid data area polygon.
      \param inputRaster Input raster.
      \param inputRasterBandsIdx Input raster bands to use.
      \param bandNoDataValues Optional vector of no-data values for each target band or an empty vector to use the original raster no-data values..
      \param outPolygonPtr The computed external valid data area polygon.
      \return true if OK, false on errors.
      \note The pixel centers will be used as coords.
      \note The returned polygon is a convex hull.
      \note If no valid raster data is present, this function returns false.
      \ingroup rp_func
    */
    TERPEXPORT bool GetExternalValidDataPolygon(
      const te::rst::Raster& inputRaster,
      const std::vector< unsigned int >& inputRasterBandsIdx,
      const std::vector< double >& bandNoDataValues,
      std::unique_ptr< te::gm::Polygon >& outPolygonPtr );    
    
  } // end namespace rp
}   // end namespace te
 
#endif  // __TERRALIB_RP_INTERNAL_FUNCTIONS_H