IHSFusion.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/IHSFusion.h
  \brief Creation of skeleton imagems.
 */
 
#ifndef __TERRALIB_RP_INTERNAL_IHSFUSION_H
#define __TERRALIB_RP_INTERNAL_IHSFUSION_H
 
#include "Algorithm.h"
#include "Matrix.h"
#include "../raster/Raster.h"
#include "../raster/Interpolator.h"
#include "../raster/RasterSynchronizer.h"
 
#include <vector>
#include <string>
#include <map>
#include <limits>
#include <memory>
 
namespace te
{
  namespace rp
  {
    /*!
      \class IHSFusion
      
      \brief Fusion of a low-resolution multi-band image with a high resolution image using the IHS method.
      
      \details The IHS is one of the widespread image fusion methods in the remote sensing community and has been employed as a standard procedure in many commercial packages; IHS is the intrinsic method when the intensity channel is replaced by the high-resolution Pan image.
      
      \note This algorithm expects both images to be aligned over the same geographic region. No reprojection or crop operations are performed.
      
      \note Reference: Te-Ming Tu, Shun-Chi Su, Hsuen-Chyun Shyu, Ping S. Huang, A new look at IHS-like image fusion methods, Information Fusion, Volume 2, Issue 3, September 2001, Pages 177-186, ISSN 1566-2535.
      
      \note Reference: W.J. Carper, T.M. Lillesand, R.W. Kiefer, The use of intensity-hue-saturation transformations for merging SPOT panchromatic and multispectral image data Photogramm. Eng. Remote Sensing, 56 (1990), pp. 459–467.
 
      \ingroup rp_fus
     */
    class TERPEXPORT IHSFusion : public Algorithm
    {
      public:
        
        /*!
          \class InputParameters
          \brief IHSFusion input parameters
         */        
        class TERPEXPORT InputParameters : public AlgorithmInputParameters
        {
          public:
            
            /*!
              \enum HRHistoFitMethod High resolution image histogram fitting method.
            */
            enum HRHistoFitMethod
            {
              NoHistoFitMethod = 0,  //!< No fitting performed method.
              MeanStdDevHistoFitMethod = 1,    //!< Fitting by using mean and Standard deviation.
              MinMaxHistoFitMethod = 2           //!< Fitting by using the mininum and maximum values.
            };                            
            
            te::rst::Raster const* m_lowResRasterPtr; //!< Input low-resolution multi-band raster.
            
            unsigned int m_lowResRasterRedBandIndex; //!< The low-resolution raster red band index (default:0).
            
            unsigned int m_lowResRasterGreenBandIndex; //!< The low-resolution raster green band index (default:1).
            
            unsigned int m_lowResRasterBlueBandIndex; //!< The low-resolution raster blue band index (default:2).
            
            te::rst::Raster const* m_highResRasterPtr; //!< Input high-resolution raster.
            
            unsigned int m_highResRasterBand; //!< Band to process from the high-resolution raster.
            
            bool m_enableProgress; //!< Enable/Disable the progress interface (default:false).
            
            te::rst::Interpolator::Method m_interpMethod; //!< The raster interpolator method (default:NearestNeighbor).
            
            double m_RGBMin; //!< The used RGB minimum value (default:0 - leave zero for automatic detection based on the input images).
            
            double m_RGBMax; //!< The used RGB maximum value (default:0 - leave zero for automatic detection based on the input images).            
            
            bool m_enableThreadedProcessing; //!< If true, threaded processing will be performed (best with  multi-core or multi-processor systems (default:true).
            
            bool m_autoAlignRasters; //!< If true, the HR image will be clipped and reprojected to mach the LR image area.
            
            bool m_enableRasterCache; //!< If true, raster cache will be used (default:true).
            
            HRHistoFitMethod m_hrHistoFitMethod;  //!< High resolution image histogram fitting method (default: MeanStdDevHistoFitMethod).
 
            std::vector< double > m_outputNoDataValues; //!< A vector of output raster band no-data values or an empty vector to use low-resolution raster no-data values.
            
            InputParameters();
            
            InputParameters( const InputParameters& );
            
            ~InputParameters();
            
            //overload
            void reset() ;
            
            //overload
            const  InputParameters& operator=( const InputParameters& params );
            
            //overload
            AbstractParameters* clone() const;
 
            //overload
            bool serialize ( AlgorithmParametersSerializer& serializer ) const;
        };
        
        /*!
          \class OutputParameters
          \brief IHSFusion output parameters
         */        
        class TERPEXPORT OutputParameters : public AlgorithmOutputParameters
        {
          public:
            
            std::string m_rType; //!< Output raster data source type (as described in te::raster::RasterFactory ).
            
            std::map< std::string, std::string > m_rInfo; //!< The necessary information to create the output rasters (as described in te::raster::RasterFactory). 
            
            std::unique_ptr< te::rst::Raster > m_outputRasterPtr; //!< The generated output fused raster.
            
            OutputParameters();
            
            OutputParameters( const OutputParameters& );
            
            ~OutputParameters();
            
            //overload
            void reset() ;
            
            //overload
            const  OutputParameters& operator=( const OutputParameters& params );
            
            //overload
            AbstractParameters* clone() const;
        };        
 
        IHSFusion();
        
        ~IHSFusion();
       
        //overload
        bool execute( AlgorithmOutputParameters& outputParams ) ;
        
        //overload
        void reset() ;
        
        //overload
        bool initialize( const AlgorithmInputParameters& inputParams ) ;
        
        //overload
        bool isInitialized() const;
 
      protected:
        
        struct LoadUpsampledIHSDataThreadParameters
        {
          te::rst::RasterSynchronizer* m_inputRasterSyncPtr;
          te::rst::RasterSynchronizer* m_outputRasterSyncPtr;
          
          // std::get< 0 > == processed = true / not processed = false
          // std::get< 1 > == output block X
          // std::get< 2 > == output block Y       
          std::vector< std::tuple< bool, unsigned int,  unsigned int > >*
            m_rasterBlocksStatusPtr;
            
          bool m_returnStatus;
          std::mutex* m_mutexPtr;
          te::rst::Interpolator::Method m_interpMethod;
          unsigned int m_interpWindowRadius;            
          unsigned int m_inputRasterRedBandIndex;
          unsigned int m_inputRasterGreenBandIndex;            
          unsigned int m_inputRasterBlueBandIndex;
          double m_rgbMin;
          double m_rgbMax;           
        };        
        
        struct SwapIntensityThreadParameters
        {
          te::rst::RasterSynchronizer* m_inputRasterSyncPtr;
          te::rst::RasterSynchronizer* m_outputRasterSyncPtr;
          unsigned int m_inputRasterBandIdx;
          unsigned int m_outputRasterBandIdx;
          
          // std::get< 0 > == processed = true / not processed = false
          // std::get< 1 > == output block X
          // std::get< 2 > == output block Y       
          std::vector< std::tuple< bool, unsigned int,  unsigned int > >*
            m_rasterBlocksStatusPtr;
            
          bool m_returnStatus;
          std::mutex* m_mutexPtr;
          double m_inOffset;
          double m_outOffset;
          double m_gain;
        };                
        
        struct SaveRGBDataThreadParameters
        {
          te::rst::RasterSynchronizer* m_inputRasterSyncPtr;
          te::rst::RasterSynchronizer* m_outputRasterSyncPtr;
          
          // std::get< 0 > == processed = true / not processed = false
          // std::get< 1 > == output block X
          // std::get< 2 > == output block Y       
          std::vector< std::tuple< bool, unsigned int,  unsigned int > >*
            m_rasterBlocksStatusPtr;
            
          bool m_returnStatus;
          std::mutex* m_mutexPtr;
          double m_rgbMin;
          double m_rgbMax;
        };                
        
        InputParameters m_inputParameters; //!< Input execution parameters.
        
        bool m_isInitialized; //!< Tells if this instance is initialized.
        
        /*!
          \brief Get the minimum and maximum values from the RGB input image.
          \param rgbMin RGB minimum value.
          \param rgbMax RGB maximum value.
          \return true if ok, false on errors.
         */        
        bool getRGBRange( double& rgbMin, double& rgbMax ) const;
        
        /*!
          \brief Get statistics from the given raster band.
          \param inputRaster Input raster.
          \param inputRasterBand Input raster band index.
          \param mean Mean value.
          \param variance Variance value.
          \param max Maximum value.
          \param min Minimum value.
          \return true if ok, false on errors.
         */
        bool getStatistics( const te::rst::Raster& inputRaster, 
          const unsigned int inputRasterBand, double& mean, double& stdDev,
          double&min, double& max ) const;
        
        /*!
          \brief Swap the intensity data by the high resolution image data.
          \param highResRaster High resolution raster.
          \param highResRasterBand Hight resolution raster band.
          \param ihsRaster IHS raster.
          \return true if ok, false on errors.
         */
        bool swapIntensity( const te::rst::Raster& highResRaster,
          const unsigned int highResRasterBand,
          te::rst::Raster& ihsRaster );
        
        static void swapIntensityThreadEntry( SwapIntensityThreadParameters* paramsPtr );
        
        /*!
          \brief Save resampled IHS data as RGB data to the output image.
          \param rgbMin RGB minimum value.
          \param rgbMax RGB maximum value.
          \param rType Output raster driver type.
          \param rInfo Output raster info.
          \param ihsRaster IHS raster.
          \param outputRasterPtr Output raster pointer.
          \return true if ok, false on errors.
         */
        bool saveRGBData(
          const double& rgbMin, const double& rgbMax,
          const std::string& rType, const std::map< std::string, std::string >& rInfo,
          std::unique_ptr< te::rst::Raster >& outputRasterPtr,
          const te::rst::Raster& ihsRaster );
          
        static void saveRGBDataThreadEntry( SaveRGBDataThreadParameters* paramsPtr );
        
        /*!
          \brief Load resampled IHS data from the lower resolution input image.
          \param upsampledGrid Target upsampled grid.
          \param rgbMin RGB minimum value.
          \param rgbMax RGB maximum value.
          \param ihsRasterPtr Output raster (3 bands - IHS).
          \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].
         */
        bool loadUpsampledIHSData( 
          const te::rst::Grid& upsampledGrid,
          const double& rgbMin, 
          const double rgbMax, 
          std::unique_ptr< te::rst::Raster >& ihsRasterPtr ) const;
          
        static void loadUpsampledIHSDataThreadEntry( LoadUpsampledIHSDataThreadParameters* paramsPtr );
    };
 
  } // end namespace rp
}   // end namespace te
 
#endif