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"

// 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 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 three channels of a display
        enum RGBChannels 
        { 
          RED_CHANNEL=0,
          GREEN_CHANNEL=1,
          BLUE_CHANNEL=2,
          ALPHA_CHANNEL=3
        };

        // 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. */
        };

      public:

        /*!
          \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);

        /*! \brief Gets the gain. */
        double getGain() const;

        /*! \brief Sets the offset 1. */
        void setOffset(double value);

        /*!
          \brief Set the current contrast type.
          \param newType New contrast type.
         */
        void setContrastType( const ContrastType& newType );

        /*! \brief Gets the offset. */
        double getOffset();

        /*! \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) { m_rgbMap[bOut] = bIn; }

        /*! Clears current mapping from bands to channel */
        void clearRGBMap() { m_rgbMap.clear(); }

        /*! Returns the mapping from a particular input band to a particular output channel */
        std::map<RGBChannels, short>& getRGBMap() { return m_rgbMap; }

        /*! Sets the mono band to be transformed */
        void setSrcBand(short n) { m_monoBand = n; }

        /*! Gets the mono band to be transformed */
        short getSrcBand() { return m_monoBand; }

        /*! Sets the destination of the mono band */
        void setDestBand(short n) { m_monoBandOut = n; }

        /*! Gets the destination of the mono band */
        short getDestBand() { return m_monoBandOut; }

        /*! 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);

        /*! 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 );

      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;

        /*!
          \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_contrastOffsets1.size() );
          outputValue = ( ( inputValue + m_contrastOffsets1[ bandIdx ] ) *
            m_contrastGains[ bandIdx ] ) + m_contrastOffsets2[ bandIdx ];
        }

        /*! This transformation aplies a square contrast */
        inline void applySquareContrast(const unsigned int& bandIdx, const double& inputValue, double& outputValue) const
        {
          assert( bandIdx < m_contrastGains.size() );
          outputValue = std::pow( inputValue, 2.0  ) * m_contrastGains[ bandIdx ];
        }

        /*! This transformation aplies a square root contrast */
        inline void applySquareRootContrast(const unsigned int& bandIdx, const double& inputValue, double& outputValue) const
        {
          assert( bandIdx < m_contrastGains.size() );
          outputValue = std::sqrt( inputValue  ) *  m_contrastGains[ bandIdx ];
        }

        /*! This transformation aplies a log contrast */
        inline void applyLogContrast(const unsigned int& bandIdx, const double& inputValue, double& outputValue) const
        {
          assert( bandIdx < m_contrastOffsets1.size() );
          outputValue = std::log10( inputValue + m_contrastOffsets1[ bandIdx ] + 1.0 ) *
            m_contrastGains[ bandIdx ];
        }

        /*! Function used to adjust the value in raster range */
        inline void fixValue(double& value, short& band) const
        {
          value = std::max(m_rstMinValue[static_cast<size_t>(band)], std::min(m_rstMaxValue[static_cast<size_t>(band)], 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_rasterIn->getBand(static_cast<size_t>(band))->getProperty()->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);

      private:

        te::rst::Raster* m_rasterIn;              //!< Pointer to a input raster.
        te::rst::Raster* m_rasterOut;             //!< Pointer to a output raster.

        ContrastType m_currentContrastType;       //!< Current contrast type.
        ContrastTransformFunction m_contrastTransfFuncPtr; //!< Function used in contrast transformation operation.

        double m_transp;                          //!< Transparency factor
        std::vector< double > m_rstMinValue;      //!< Min value from input raster.
        std::vector< double > m_rstMaxValue;      //!< Max value from input raster.

        std::map<RGBChannels, short> m_rgbMap;    //!< Map used to set the band order.
        short m_monoBand;                         //!< Value for the gray band.
        short m_monoBandOut;                      //!< Value for output gray band channel.

        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.

        std::vector< double > m_gamma;   //!< A vector of gamma gains for each band.
        std::vector< double > m_contrastGains;   //!< A vector of gains for each band used by the CONTRAST method.
        std::vector< double > m_contrastOffsets1;//!< A vector of offsets1 for each band used by the CONTRAST method.
        std::vector< double > m_contrastOffsets2;//!< A vector of offsets2 for each band used by the CONTRAST method.
    };

  } // end namespace map
}   // end namespace te

#endif  // __TERRALIB_MAPTOOLS_INTERNAL_RASTERTRANSFORM_H