RasterTransform.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 RasterTransform.h
 
  \brief A Raster Transform is a class that defines functions to transform a styled raster.
*/
 
#ifndef __TERRALIB_MAPTOOLS_INTERNAL_RASTERTRANSFORM_H
#define __TERRALIB_MAPTOOLS_INTERNAL_RASTERTRANSFORM_H
 
// TerraLib
#include "Config.h"
#include "../color/RGBAColor.h"
#include "../color/ColorBar.h"
#include "../raster.h"
#include "Exception.h"
 
// STL
#include <map>
#include <cmath>
 
namespace te
{
// Forward declarations
  namespace se 
  { 
    class RasterSymbolizer;
  }
  
  namespace rst 
  { 
    class Raster;
    class RasterProperty;
  }
 
  namespace map
  {
// Forward declarations
 
    /*!
      \class RasterTransform
 
      \brief A Raster Transform is a class that defines functions to transform a styled raster.
 
      \sa 
    */
    class TEMAPEXPORT RasterTransform
    {
      public:
 
        typedef void (RasterTransform::*TransformFunction)(double, double, double, double);
        typedef te::color::RGBAColor (RasterTransform::*RGBAFunction)(double, double);
        typedef void (RasterTransform::*ChannelDomainGetFunction)(unsigned int c, unsigned int r, double& value, std::size_t band);
 
        typedef std::pair<double, double> RasterThreshold;
 
        typedef std::map<RasterThreshold, te::color::RGBAColor> CategorizedMap;
        typedef std::map<RasterThreshold, te::color::ColorBar> InterpolatedMap;
        typedef std::map<int, te::color::RGBAColor> RecodedMap;
 
        //! The channel domain (real, imaginary, i.e.) to use as source
        /*! \enum  The channel domain (real or imaginary) to use as source. */
        enum ChannelDomain 
        { 
          REAL_CHANNEL_DOMAIN=0, /**< Use real numbers domain */
          IMAGINARY_CHANNEL_DOMAIN=1,  /**< Use imaginary numbers domain */
          SQRT_CHANNEL_DOMAIN=2 /**< Use the square root of the sum of squared real and imaginary values */
        };        
        
        //! The channels of a display
        enum RGBChannels 
        { 
          RED_CHANNEL=0,
          GREEN_CHANNEL=1,
          BLUE_CHANNEL=2,
          ALPHA_CHANNEL=3,
          MONO_CHANNEL=4
        };
 
        // The raster transform functions type
        enum RasterTransfFunctions
        {
          NO_TRANSF=0,
          MONO2THREE_TRANSF=1,
          EXTRACT2RGB_TRANSF=2,
          RED2THREE_TRANSF=3,
          GREEN2THREE_TRANSF=4,
          BLUE2THREE_TRANSF=5,
          CATEGORIZE_TRANSF=6,
          INTERPOLATE_TRANSF=7,
          RECODE_TRANSF = 8,
          BAND2BAND_TRANSF=9,
          EXTRACT2RGBA_TRANSF,
          CONTRAST_TRANSF /*!< Apply a contrast method ( ContrastType ) to the given raster - Use the methods getGain, setOffset and setOffset2 to setup contrast parameters. */
        };
 
        /*! \enum  Allowed contrast types. */
        enum ContrastType
        {
          LINEAR_CONTRAST, /*!< The histogram range will be changed to the supplied min/max range ( linear function ). */
          SQUARE_CONTRAST, /*!< The contrasted image will be created by using a square function. */
          SQUARE_ROOT_CONTRAST, /*!< The contrasted image will be created by using a square root function. */
          LOG_CONTRAST /*!< The contrasted image will be created by using a log function. */
        };
 
        /*!
          \brief Constructor
 
          \param input   
          \param output  
 
          \note 
        */
        RasterTransform(te::rst::Raster* input, te::rst::Raster* output);
 
        /*! \brief Destructor. */
        ~RasterTransform();
 
        /*! \brief Gets the input raster. */
        te::rst::Raster* getInputRaster() { return m_rasterIn; }
 
        /*! \brief Gets the output raster. */
        te::rst::Raster* getOutputRaster() { return m_rasterOut; }
 
        /*! \brief Sets the transparency. */
        void setTransparency(double value) { m_transp = value; }
 
        /*! \brief Gets the transparency. */
        double getTransparency() { return m_transp; }
 
        /*! \brief Sets the gain. */
        void setGain(double value, int band);
 
        /*! \brief Gets the gain. */
        std::vector< double > getGain() const;
 
        /*! \brief Sets the offset 1. */
        void setOffset(double value, int band);
 
        /*! \brief Gets the offset. */
        std::vector< double > getOffset();
 
        /*!
          \brief Set the current contrast type.
          \param newType New contrast type.
         */
        void setContrastType( const ContrastType& newType );
 
        /*! \brief Sets the constrast value for red band. */
        void setGammaR(double value);
 
        /*! \brief Gets the constrast value for red band. */
        double getGammaR();
 
        /*! \brief Sets the constrast value for green band. */
        void setGammaG(double value);
 
        /*! \brief Gets the constrast value for green band. */
        double getGammaG();
 
        /*! \brief Sets the constrast value for blue band. */
        void setGammaB(double value);
 
        /*! \brief Gets the constrast value for blue band. */
        double getGammaB();
 
        /*! \brief Sets the constrast value for gray band. */
        void setGammaM(double value);
 
        /*! \brief Gets the constrast value for gray band. */
        double getGammaM();
 
        /*! \brief Sets the rgb map values. */
        void setRGBMap(std::map<RGBChannels, short>& rgbMap);
 
        /*! Sets the mapping from a particular input band to a particular output channel */
        void setBChannelMapping(short bIn, RGBChannels bOut);
 
        short getBChannelMapping(RGBChannels channel);
 
        /*! Clears current mapping from bands to channel */
        void clearRGBMap();
 
        /*! Returns the mapping from a particular input band to a particular output channel */
        std::map<RGBChannels, short> getRGBMap();
 
        /*! Sets the categorize map information */
        void setCategorizedMap(CategorizedMap map) { m_categorizeMap = map; }
 
        /*! Gets the categorize map information */
        CategorizedMap& getCategorizedMap() { return m_categorizeMap; }
 
        /*! Sets the interpolate map information */
        void setInterpolatedMap(InterpolatedMap map) { m_interpolateMap = map; }
 
        /*! Gets the categorize map information */
        InterpolatedMap& getInterpolatedMap() { return m_interpolateMap; }
 
        /*! Sets the recode map information */
        void setRecodedMap(RecodedMap map) { m_recodeMap = map; }
 
        /*! Gets the recode map information */
        RecodedMap& getRecodedMap() { return m_recodeMap; }
 
        /*! 
          \brief Set parameters of linear transformation
        
          \param vmin smallest input value
          \param vmax largest input value
          \param rmin smallest value of the output range
          \param rmax largest value of the output range
 
        */
        void setLinearTransfParameters(double vmin, double vmax, double rmin, double rmax);
 
        /*!
          \brief Set parameters of linear transformation for each band
 
          \param vmin smallest input value
          \param vmax largest input value
          \param rmin smallest value of the output range
          \param rmax largest value of the output range
          \param band band id
        */
        void setLinearTransfParameters(double vmin, double vmax, double rmin, double rmax, int band);
 
        /*!
          \brief Set parameters of a non linear transformation for each band
 
          \param rmin smallest value of the output range
          \param rmax largest value of the output range
          \param gain value used as gain
          \param offset1 value used as offset
          \param offset2 value used as offset2
          \param band band id
        */
        void setTransfParameters(double rmin, double rmax, double gain, double offset1, double offset2, int band);
 
        /*!
          \brief Set the input/output window that will be transformed. This method enables cache strategy.
 
          \param inputX0        Start point (upper left X) from input image
          \param inputY0        Start point (upper left Y) from input image
          \param inputWidth     Width of input image that will be transformed
          \param inputHeight    Height of input image that will be transformed
          \param outWidth       Width of output image that will receive the transformed input image (canvas size)
          \param outHeight      Height of output image that will receive the transformed input image (canvas size)
 
          \NOTE: This method was defined to increase draw speed.
        */
        void setInputRasterResampleSize(int inputX0, int inputY0, int inputWidth, int inputHeight, int outWidth, int outHeight);
 
        /*! Returns the identifier of the transformation function currently set */
        RasterTransfFunctions getTransfFunction();
 
        /*! Sets the associated transformation function from an identifier */
        void setTransfFunction(RasterTransfFunctions func);
 
        /*! Sets the transformation method to be used */
        void setTransfFunction(RasterTransform::TransformFunction transfFuncPtr) { m_transfFuncPtr = transfFuncPtr; }
 
        /*! Sets the transformation method to be used */
        void setRGBAFunction(RasterTransform::RGBAFunction transfFuncPtr) { m_RGBAFuncPtr = transfFuncPtr; }
 
        /*! Applies the selected transformation method */
        void apply(double icol, double ilin, double ocol, double olin) {(this->*m_transfFuncPtr)(icol,ilin,ocol,olin); }
 
        te::color::RGBAColor apply(double icol, double ilin){return (this->*m_RGBAFuncPtr)(icol,ilin); }
 
        /*!
          \brief Set gain and offset parameters to be used by the CONTRAST_TRANSF method.
          \param contrastGains A vector of gains for each raster band.
          \param contrastOffsets1 A vector of offsets1 for each raster band.
          \param contrastOffsets2 A vector of offsets2 for each raster band.
         */
        void setContrastGainsAndOffsets( const std::vector< double >& contrastGains,
          const std::vector< double >& contrastOffsets1,
          const std::vector< double >& contrastOffsets2 );
        
        /*!
          \brief Set the used channels domain.
          \param domain The new domain.
         */
        void setChannelDomain( const ChannelDomain domain );
        
        /*!
          \brief Return the used channels domain.
          \return Return the used channels domain.
         */
        ChannelDomain getChannelDomain() const;
 
      protected:
 
        /*!
          \brief Type definition for the internal contrast transform function.
          \note void ContrastTransformFunction( bandNumber, inputValue, outputValue )
         */
        typedef void (RasterTransform::*ContrastTransformFunction)(const unsigned int&, const double&, double&) const;
        
        class BandBufferInfo
        {
          public :
 
            BandBufferInfo( const int bandDataType, const int width, 
              const int height, void* buffer, 
              const RasterTransform::ChannelDomain domain )
            :
              m_dataType(bandDataType),
              m_width(width),
              m_height(height),
              m_buffer(buffer)
            {
              te::rst::SetBlockFunctions(&m_getBuff, &m_getBuffI, &m_setBuff, &m_setBuffI, m_dataType);
              
              if( domain == REAL_CHANNEL_DOMAIN )
              {
                m_channelDomainGetFuncPtr = &BandBufferInfo::getRealValueChannelDomainGetFunction;
              }
              else if( domain == IMAGINARY_CHANNEL_DOMAIN )
              {
                m_channelDomainGetFuncPtr = &BandBufferInfo::getImaginaryValueChannelDomainGetFunction;
              }
              else if( domain == SQRT_CHANNEL_DOMAIN )
              {
                m_channelDomainGetFuncPtr = &BandBufferInfo::getSQRTChannelDomainGetFunction;
              }
              else
              {
                throw Exception(TE_TR("Invalid channel domain"));
              }                
            }
            
            void getValue(const unsigned int c, 
              const unsigned int r, double& value ) const
            {
              (this->*(m_channelDomainGetFuncPtr))( c, r, value );
            }
 
            ~BandBufferInfo()
            {
              unsigned char* buffer = static_cast<unsigned char*>(m_buffer);
              delete[] buffer;
            }
            
          protected :
            
            typedef void (BandBufferInfo::*ChannelDomainGetFunction)(
              const unsigned int c, const unsigned int r, double& value ) const;
            
            int m_dataType;
            int m_width;
            int m_height;
            void* m_buffer;
            mutable double m_auxRealValue;
            mutable double m_auxImagValue;
 
            te::rst::GetBufferValueFPtr m_getBuff;   //!< A pointer to a function that helps to extract a double or complex value from a specific buffer data type (char, int16, int32, float, ...).
            te::rst::GetBufferValueFPtr m_getBuffI;  //!< A pointer to a function that helps to extract the imaginary part value from a specific buffer data type (cint16, cint32, cfloat, cdouble).
            te::rst::SetBufferValueFPtr m_setBuff;   //!< A pointer to a function that helps to insert a double or complex value into a specific buffer data type (char, int16, int32, float, ...).
            te::rst::SetBufferValueFPtr m_setBuffI;  //!< A pointer to a function that helps to insert the imaginary part value into a specific buffer data type (cint16, cint32, cfloat, cdouble).
            BandBufferInfo::ChannelDomainGetFunction m_channelDomainGetFuncPtr; //!< Function used to get raster data from the selected domain (real/imaginary).
            
            
            void getRealValueChannelDomainGetFunction( const unsigned int c, 
              const unsigned int r, double& value) const
            {
              assert(m_buffer);
              m_getBuff( c + ( r * m_width ), m_buffer, &value );
            }
 
            void getImaginaryValueChannelDomainGetFunction(const unsigned int c, 
              const unsigned int r, double& value) const
            {
              assert(m_buffer);
              m_getBuffI( c + ( r * m_width ), m_buffer, &value );
            }        
            
            void getSQRTChannelDomainGetFunction(const unsigned int c, 
              const unsigned int r, double& value) const
            {
              assert(m_buffer);
              m_getBuff( c + ( r * m_width ), m_buffer, &m_auxRealValue );
              m_getBuffI( c + ( r * m_width ), m_buffer, &m_auxImagValue );
              value = std::sqrt( ( m_auxRealValue * m_auxRealValue )
                + ( m_auxImagValue * m_auxImagValue ) ) ;
            }                
        };
        
        struct TransformBandInfo
        {
          double m_rstMinValue;      //!< Min value from input raster.
          double m_rstMaxValue;      //!< Max value from input raster.
 
          double m_gamma;            //!< Gamma gain for this band.
 
          double m_contrastGain;     //!< Gains for this band used by the CONTRAST method.
          double m_contrastOffset1;  //!< Offsets1 for this band used by the CONTRAST method.
          double m_contrastOffset2;  //!< Offsets2 for this band used by the CONTRAST method.
 
          double  m_noDataValue;     //!< No data value for this band from input raster.
 
          TransformBandInfo():
            m_rstMinValue(-std::numeric_limits<double>::max()),
            m_rstMaxValue(std::numeric_limits<double>::max()),
            m_gamma(1.0),
            m_contrastGain(1.0),
            m_contrastOffset1(0.0),
            m_contrastOffset2(0.0),
            m_noDataValue(std::numeric_limits<double>::max())
          {
 
          }
 
          ~TransformBandInfo()
          {
 
          }
 
        };        
 
        /*!
          \brief Configures the contrast function pointer.
          \param contrastType Contrast type..
         */
        void setContrastFuncPtr(const RasterTransform::ContrastType contrastType );
 
        /*! This transformation repeats the value of the first band in input three bands of the output */
        void setMono2ThreeBand(double icol, double ilin, double ocol, double olin);
 
        /*! This transformation repeats the value of the first band in input three bands of the output */
        te::color::RGBAColor getMono2ThreeBand(double icol, double ilin);
 
        /*! This transformation is used to define a particular mapping from input bands to RGB channels */
        void setExtractRGB(double icol, double ilin, double ocol, double olin);
 
        /*! This transformation is used to define a particular mapping from input bands to RGB channels */
        te::color::RGBAColor getExtractRGB(double icol, double ilin);
 
        /*! This transformation is used to define a particular mapping from input bands to RGBA channels */
        void setExtractRGBA(double icol, double ilin, double ocol, double olin);
 
        /*! This transformation is used to define a particular mapping from input bands to RGBA channels */
        te::color::RGBAColor getExtractRGBA(double icol, double ilin);
 
        /*! This transformation repeats the value of the first band in input three bands of the output */
        void setRed2ThreeBand(double icol, double ilin, double ocol, double olin);
 
        /*! This transformation repeats the value of the first band in input three bands of the output */
        te::color::RGBAColor getRed2ThreeBand(double icol, double ilin);
 
        /*! This transformation repeats the value of the first band in input three bands of the output */
        void setGreen2ThreeBand(double icol, double ilin, double ocol, double olin);
 
        /*! This transformation repeats the value of the first band in input three bands of the output */
        te::color::RGBAColor getGreen2ThreeBand(double icol, double ilin);
 
        /*! This transformation repeats the value of the first band in input three bands of the output */
        void setBlue2ThreeBand(double icol, double ilin, double ocol, double olin);
 
        /*! This transformation repeats the value of the first band in input three bands of the output */
        te::color::RGBAColor getBlue2ThreeBand(double icol, double ilin);
 
        /*! This transformation get the value of the selected band in input  and set the categorized value in output bands of the output */
        void setCategorize(double icol, double ilin, double ocol, double olin);
 
        /*! This transformation get the value of the selected band in input  and get the categorized value */
        te::color::RGBAColor getCategorize(double icol, double ilin);
 
        /*! This transformation get the value of the selected band in input  and set the interpolated value in output bands of the output */
        void setInterpolate(double icol, double ilin, double ocol, double olin);
 
        /*! This transformation get the value of the selected band in input  and get the interpolated value */
        te::color::RGBAColor getInterpolate(double icol, double ilin);
 
        /*! This transformation get the value of the selected band in input  and set the recoded value in output bands of the output */
        void setRecode(double icol, double ilin, double ocol, double olin);
 
        /*! This transformation get the value of the selected band in input  and get the recoded value */
        te::color::RGBAColor getRecode(double icol, double ilin);
 
        /*! This transformation repeats the value of the n band in input to b band in output */
        void setBand2Band(double icol, double ilin, double ocol, double olin);
 
        /*! This transformation aplies a linear contrast */
        inline void applyLinearContrast(const unsigned int& bandIdx, const double& inputValue, double& outputValue) const
        {
          assert( bandIdx < m_inputNBands );
          outputValue = ( ( inputValue + m_transformBandInfo[bandIdx]->m_contrastOffset1 ) *
            m_transformBandInfo[bandIdx]->m_contrastGain ) + m_transformBandInfo[bandIdx]->m_contrastOffset2;
        }
 
        /*! This transformation aplies a square contrast */
        inline void applySquareContrast(const unsigned int& bandIdx, const double& inputValue, double& outputValue) const
        {
          assert( bandIdx < m_inputNBands );
          outputValue = std::pow( inputValue, 2.0  ) * m_transformBandInfo[bandIdx]->m_contrastGain;
        }
 
        /*! This transformation aplies a square root contrast */
        inline void applySquareRootContrast(const unsigned int& bandIdx, const double& inputValue, double& outputValue) const
        {
          assert( bandIdx < m_inputNBands );
          outputValue = std::sqrt( inputValue  ) *  m_transformBandInfo[bandIdx]->m_contrastGain;
        }
 
        /*! This transformation aplies a log contrast */
        inline void applyLogContrast(const unsigned int& bandIdx, const double& inputValue, double& outputValue) const
        {
          assert( bandIdx < m_inputNBands );
          outputValue = std::log10( inputValue + m_transformBandInfo[bandIdx]->m_contrastOffset1 + 1.0 ) *
            m_transformBandInfo[bandIdx]->m_contrastGain;
        }
 
        /*! Function used to adjust the value in raster range */
        inline void fixValue(double& value, short& band) const
        {
          value = std::max(m_transformBandInfo[band]->m_rstMinValue, std::min(m_transformBandInfo[band]->m_rstMaxValue, value));
        }
 
        /*! 
          \brief Function used to check if value is or not a valid value 
        
          \return True if the value is EQUAL to NoValue and false in other case.
        */
        inline bool checkNoValue(double& value, int band) const
        {
          return (m_transformBandInfo[band]->m_noDataValue == value);
        }
 
        /*!
        \brief Function used to check the alpha value
 
        \return Return the alpha value.
        */
        double checkAlphaValue(double icol, double ilin);
 
        /*! Function used to get the interpolated color given a pixel value */
        te::color::RGBAColor getInterpolatedColor(double value);
 
        /*! Function used to get the categorized color given a pixel value */
        te::color::RGBAColor getCategorizedColor(double value);
 
        /*! Function used to get the recoded color given a pixel value */
        te::color::RGBAColor getRecodedColor(double value);
        
        void getRealValueChannelDomainGetFunction(unsigned int c, unsigned int r, double& value, std::size_t b)
        {
          assert(m_rasterIn);
          m_rasterIn->getValue(c, r, value, b );
        }
 
        void getImaginaryValueChannelDomainGetFunction(unsigned int c, unsigned int r, double& value, std::size_t b)
        {
          assert(m_rasterIn);
          std::complex<double> cValue;
          m_rasterIn->getValue(c, r, cValue, b );
          value = cValue.imag();
        }        
        
        void getSQRTChannelDomainGetFunction(unsigned int c, unsigned int r, double& value, std::size_t b)
        {
          assert(m_rasterIn);
          std::complex<double> cValue;
          m_rasterIn->getValue(c, r, cValue, b );
          value = std::sqrt( ( cValue.real() * cValue.real() )
            + ( cValue.imag() * cValue.imag() ) ) ;
        }           
      private:
 
        te::rst::Raster* m_rasterIn;              //!< Pointer to a input raster.
        te::rst::Raster* m_rasterOut;             //!< Pointer to a output raster.
 
        std::size_t m_inputNBands;                //!< Number of bands from input raster.
 
        short m_monoBand;                         //!< Value for the gray band.
        short m_redBand;                          //!< Value for the red band.
        short m_greenBand;                        //!< Value for the green band.
        short m_blueBand;                         //!< Value for the blue band.
        short m_alphaBand;                        //!< Value for the alpha band.
 
        double m_transp;                          //!< Global transparency value for transformation.
 
        ContrastType m_currentContrastType;       //!< Current contrast type.
        ChannelDomain m_currentChannelDomain;     //!< Current channel domain.
        ChannelDomainGetFunction m_channelDomainGetFuncPtr; //!< Function used to get raster data from the selected domain (real/imaginary).
        ContrastTransformFunction m_contrastTransfFuncPtr; //!< Function used in contrast transformation operation.
 
        TransformFunction m_transfFuncPtr;        //!< Function used in transformation operation.
        RGBAFunction m_RGBAFuncPtr;               //!< Function used in transformation operation.
 
        CategorizedMap m_categorizeMap;           //!< Attribute to define the categorized transformation.
        InterpolatedMap m_interpolateMap;         //!< Attribute to define the interpolated transformation.
        RecodedMap m_recodeMap;                   //!< Attribute to define the recoded transformation.
 
        bool m_useBufferCache;                    //!< Flag used to indicate if a buffer from input image will be used.
        BandBufferInfo**  m_arrayBuffer;          //!< Array of band buffer info from input data.
 
        TransformBandInfo** m_transformBandInfo;  //!< Array of band transformation information.
    };
 
  } // end namespace map
}   // end namespace te
 
#endif  // __TERRALIB_MAPTOOLS_INTERNAL_RASTERTRANSFORM_H