Contrast.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/Contrast.h
  \brief Contrast enhancement.
 */

#ifndef __TERRALIB_RP_INTERNAL_CONTRAST_H
#define __TERRALIB_RP_INTERNAL_CONTRAST_H

#include "Algorithm.h"

#include <vector>
#include <string>
#include <map>
#include <memory>
#include <cmath>

namespace te
{
  namespace da
  {
    class DataSource;
  }

  namespace rst
  {
    class Raster;
    class Band;
  }

  namespace rp
  {
    /*!
      \class Contrast
      \brief Contrast enhancement.
      \details Apply contrast enhencement on the selected bands.
      \ingroup rp_enh
     */
    class TERPEXPORT Contrast : public Algorithm
    {
      public:
        
        /*!
          \class InputParameters
          \brief Contrast input parameters
         */        
        class TERPEXPORT InputParameters : public AlgorithmInputParameters
        {
          public:
            
            /*!
              \name Global parameters
            */
            /**@{*/              
            
            /*! \enum  Allowed contrast types. */
            enum ContrastType
            {
              InvalidContrastT, /*!< Invalid contrast. */
              LinearContrastT, /*!< The histogram range will be changed to the supplied min/max range ( linear function ). */
              HistogramEqualizationContrastT, /*!< The histogram of the image will be equalized automatically. */
              SquareContrastT, /*!< The contrasted image will be created by using a square function. */
              SquareRootContrastT, /*!< The contrasted image will be created by using a square root function. */
              LogContrastT, /*!< The contrasted image will be created by using a log function. */
              MeanAndStdContrastT, /*!< The contrasted image will have a predefined mean and standard deviation normalization. */
              DecorrelationEnhancementT, /*!< Decorrelation Enhancement using principal components. */
              CumulativeCut2EnhancementT /*!< Linear cumulative cutted in 2 - 98%. */
            };

            ContrastType m_type; //!< The contrast type to be applied.
            
            te::rst::Raster const* m_inRasterPtr; //!< Input raster.
            
            std::vector< unsigned int > m_inRasterBands; //!< Bands to be processed from the input raster.

            double m_outRangeMin; //!< Minimum value of data type range (default: -1.0 * std::numeric_limits<double>::max() ).

            double m_outRangeMax; //!< Maximum value of data type range (default: std::numeric_limits<double>::max().
            
            bool m_enableProgress; //!< Enable/Disable the progress interface (default:false).

            bool m_sampled; //!< Enable/Disable uses all values to calculate histogram
            
            //@}
            
            /*!
              \name Linear contrast parameters
            */
            /**@{*/             
            
            std::vector< double > m_lCMinInput; //!< The contrast minimum input greyscale value of each band.
            
            std::vector< double > m_lCMaxInput; //!< The contrast maximum input greyscale value of each band.
            
            //@}
            
            /*!
              \name Histogram equalization contrast parameters
            */
            /**@{*/             
            
            std::vector< double > m_hECMaxInput; //!<  The contrast maximum input greyscale value of each band.
            
            //@}
            
            /*!
              \name Square contrast parameters
            */
            /**@{*/             
            
            std::vector< double > m_squareCMinInput; //!< The contrast minimum input greyscale value of each band.
            
            std::vector< double > m_squareCMaxInput; //!< The contrast maximum input greyscale value of each band.
            
            //@}            
            
            /*!
              \name Square root contrast parameters
            */
            /**@{*/             
            
            std::vector< double > m_squareRootCMinInput; //!< The contrast minimum input greyscale value of each band.
            
            std::vector< double > m_squareRootCMaxInput; //!< The contrast maximum input greyscale value of each band.
            
            //@}                        
            
            /*!
              \name Log contrast parameters
            */
            /**@{*/             
            
            std::vector< double > m_logCMinInput; //!< The contrast minimum input greyscale value of each band.
            
            std::vector< double > m_logCMaxInput; //!< The contrast maximum input greyscale value of each band.
            
            //@}                
            
            /*!
              \name Mean and standard deviation normalization contrast parameters
            */
            /**@{*/             
            
            std::vector< double > m_sMASCMeanInput; //!<  The mean greyscale to be applied in each band.
            
            std::vector< double > m_sMASCStdInput; //!< The standard deviation to be applied in each band.

            //@}
          
            InputParameters();
            
            ~InputParameters();
            
            //overload
            void reset() throw( te::rp::Exception );
            
            //overload
            const  InputParameters& operator=( const InputParameters& params );
            
            //overload
            AbstractParameters* clone() const;
        };
        
        /*!
          \class OutputParameters
          \brief Contrast output parameters
          \details The result will be written to the raster instance pointed 
          by m_outRasterPtr (in this case the output bands must also be 
          passed by m_outRasterBands ); or written to a new raster instance 
          created inside the given data source pointed by m_outDataSourcePtr 
          (in this case the data set name must be supplied - m_outDataSetName ).
         */        
        class TERPEXPORT OutputParameters : public AlgorithmOutputParameters
        {
          public:
            
            te::rst::Raster* m_outRasterPtr; //!< A pointer to a valid initiated raster instance where the result must be written, leave NULL to create a new instance(in this case the other output parameters must be used).
            
            std::unique_ptr< te::rst::Raster > m_createdOutRasterPtr; //!< A pointer to the created output raster instance, or an empty pointer empty if the result must be written to the raster pointed m_outRasterPtr.
            
            std::vector< unsigned int > m_outRasterBands; //!< Bands to be processed from the output raster.
            
            std::string m_createdOutRasterDSType; //!< Output raster data source type (as described in te::raster::RasterFactory ), leave empty if the result must be written to the raster pointed m_outRasterPtr.
            
            std::map< std::string, std::string > m_createdOutRasterInfo; //!< The necessary information to create the raster (as described in te::raster::RasterFactory), leave empty if the result must be written to the raster pointed m_outRasterPtr.
          
            OutputParameters();
            
            OutputParameters( const OutputParameters& );
            
            ~OutputParameters();
            
            //overload
            void reset() throw( te::rp::Exception );
            
            //overload
            const  OutputParameters& operator=( const OutputParameters& params );
            
            //overload
            AbstractParameters* clone() const;
        };        

        Contrast();
        
        ~Contrast();
       
        //overload
        bool execute( AlgorithmOutputParameters& outputParams ) throw( te::rp::Exception );
        
        //overload
        void reset() throw( te::rp::Exception );
        
        //overload
        bool initialize( const AlgorithmInputParameters& inputParams ) throw( te::rp::Exception );
        
        bool isInitialized() const;

        /*!
          \brief Returns gain and offset values for contrast types (when applicable).
          \param inRangeMin Input values range minimum value.
          \param inRangeMax Input values range maximum value.
          \param outRangeMin Output values range minimum value.
          \param outRangeMax Output values range maximum value.
          \param gain Calculated gain.
          \param offset1 Calculated offset 1.
          \param offset2 Calculated offset 2.
          \return true if OK, false on errors.
         */
        static bool getGainAndOffset( const InputParameters::ContrastType& type,
          const double& inRangeMin, const double& inRangeMax,
          const double& outRangeMin, const double& outRangeMax,
          double& gain, double& offset1, double& offset2 );

      protected:
        
        /*!
          \brief Type definition for a remapping function pointer.
         */        
        typedef void (Contrast::*RemapFuncPtrT)( const double& inValue, 
          double& outValue );

        Contrast::InputParameters m_inputParameters; //!< Contrast input execution parameters.
        Contrast::OutputParameters* m_outputParametersPtr; //!< Contrast input execution parameters.
        
        bool m_isInitialized; //!< Tells if this instance is initialized.

        /*!
          \brief Execute a linear contrast following the internal parameters
          \return true if OK, false on errors.
         */
        bool execLinearContrast();

        /*!
          \brief Execute the histogram equalization contrast following the internal parameters
          \return true if OK, false on errors.
        */
        bool execHistogramEqualizationContrast();
        
        /*!
          \brief Execute a square contrast following the internal parameters
          \return true if OK, false on errors.
         */
        bool execSquareContrast();      
        
        /*!
          \brief Execute a square root contrast following the internal parameters
          \return true if OK, false on errors.
         */
        bool execSquareRootContrast(); 

        /*!
          \brief Execute a log contrast following the internal parameters
          \return true if OK, false on errors.
         */
        bool execLogContrast();         

        /*!
          \brief Execute the histogram equalization contrast following the internal parameters
          \return true if OK, false on errors.
        */
        bool execSetMeanAndStdContrast();
        
        /*!
          \brief Execute the decorrelation enhancement contrast following the internal parameters
          \return true if OK, false on errors.
        */
        bool execDecorrelationEnhancement();

        /*!
        \brief Execute a cumulative linear contrast cutted by 2-98% following the internal parameters
        \return true if OK, false on errors.
        */
        bool execCumulativeCut2Enhancement();

        /*!
          \brief Band gray levels remap using a remap function.
          \param inRaster Input Raster
          \param inRasterBandIdx Input raster band index.
          \param outRaster Output raster.
          \param outRasterBandIdx Output raster band index.
          \param remapFuncPtr The remap function pointer used.
          \param enableProgress Enable the use of a progress interface.
          \return true if OK, false on errors.
         */        
        bool remapBandLevels( const te::rst::Raster& inRaster,
          const unsigned int inRasterBandIdx,
          te::rst::Raster& outRaster,
          const unsigned int outRasterBandIdx,
          RemapFuncPtrT remapFuncPtr,
          const bool enableProgress );
          
        // Variables used by offSetGainRemap
        double m_offSetGainRemap_offset1;
        double m_offSetGainRemap_offset2;
        double m_offSetGainRemap_gain;
        
        // Variables used by offSetGainRemap
        double m_squareRemap_gain;
        
        // Variables used by offSetGainRemap
        double m_squareRootRemap_gain;        
        
        // Variables used by offSetGainRemap
        double m_logRemap_gain;
        double m_logRemap_offset;                

        // Variables used by DecorrelationEnhancementRemap
        double m_decorrelationEnhancementRemap_gain;
        double m_decorrelationEnhancementRemap_offset1;
        double m_decorrelationEnhancementRemap_offset2;

        // Variables used by HistogramEqualizationRemap
        double m_histogramEqualizationRemap_cDFMin;
        double m_histogramEqualizationRemap_gain;
        std::map<double, double> m_histogramEqualizationRemap_cdf;
        
        /*!
          \brief Remap on gray level using an offset and gain.
          \param inValue Input gray level.
          \param outValue Output gray level.
          \note outValue = ( ( inValue + m_offSetGainRemap_offset1 ) * m_offSetGainRemap_gain ) + m_offSetGainRemap_offset2
         */         
        inline void offSetGainRemap( const double& inValue, double& outValue )
        {
          outValue = ( ( inValue + m_offSetGainRemap_offset1 ) *
            m_offSetGainRemap_gain ) + m_offSetGainRemap_offset2;
        };
        
        /*!
          \brief Remap on gray level using a square.
          \param inValue Input gray level.
          \param outValue Output gray level.
          \note outValue = m_squareRemap_factor * std::pow( inValue, 2.0 )
         */         
        inline void squareRemap( const double& inValue, double& outValue )
        {
          outValue = m_squareRemap_gain * std::pow( inValue, 2.0 );
        };  
        
        /*!
          \brief Remap on gray level using a square root.
          \param inValue Input gray level.
          \param outValue Output gray level.
          \note outValue = m_squareRootRemap_gain * std::sqrt( inValue );
         */         
        inline void squareRootRemap( const double& inValue, double& outValue )
        {
          outValue = m_squareRootRemap_gain * std::sqrt( inValue );
        };       
        
        /*!
          \brief Remap on gray level using a log.
          \param inValue Input gray level.
          \param outValue Output gray level.
          \note outValue = m_logRemap_gain * std::log10( inValue + m_logRemap_offset + 1.0 );
         */         
        inline void logRemap( const double& inValue, double& outValue )
        {
          outValue = m_logRemap_gain * std::log10( inValue + m_logRemap_offset + 1.0 );
        };             

        /*!
          \brief Remap on gray level using two offsets and gain.
          \param inValue Input gray level.
          \param outValue Output gray level.
         */
        inline void DecorrelationEnhancementRemap( const double& inValue, double& outValue )
        {
          outValue = ( ( inValue + m_decorrelationEnhancementRemap_offset1 ) *
            m_decorrelationEnhancementRemap_gain )
            + m_decorrelationEnhancementRemap_offset2;
        };

        /*!
          \brief Remap on gray level using two offsets and gain.
          \param inValue Input gray level.
          \param outValue Output gray level.
         */
        inline void histogramEqualizationRemap( const double& inValue, double& outValue )
        {
          outValue = ( ( m_histogramEqualizationRemap_cdf.lower_bound( inValue )->second ) -  m_histogramEqualizationRemap_cDFMin ) *
            m_histogramEqualizationRemap_gain;
        };
    };

  } // end namespace rp
}   // end namespace te

#endif