PCAFusion.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/PCAFusion.h
  \brief Creation of skeleton imagems.
 */
 
#ifndef __TERRALIB_RP_INTERNAL_PCAFUSION_H
#define __TERRALIB_RP_INTERNAL_PCAFUSION_H
 
#include "Algorithm.h"
#include "../raster/Raster.h"
#include "../raster/Band.h"
#include "../raster/Interpolator.h"
#include "../raster/RasterSynchronizer.h"
 
#include <boost/numeric/ublas/matrix.hpp>
 
#include <vector>
#include <string>
#include <map>
#include <memory>
 
namespace te
{
  namespace rp
  {
    /*!
      \class PCAFusion
      \brief Fusion of a low-resolution multi-band image with a high resolution image using the PCA (Principal components analysis) method.
      \details The PCA performs image fusion where the first principal component of the multi-spectral image is replaced by the histogram matched panchromatic imagery.
      \note Reference: Tania Stathaki, "Image Fusion: Algorithms and Applications", Elsevier, First edition 2008.
      \note This algorithm expects both images to be aligned over the same geographic region. No reprojection or crop operations are performed.
      \ingroup rp_fus
     */
    class TERPEXPORT PCAFusion : public Algorithm
    {
      public:
        
        /*!
          \class InputParameters
          \brief PCAFusion 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.
              MeanStdDevHistoFitAndClipMethod = 3,    //!< Fitting by using mean and Standard deviation and clipping to minimum and maximum values.
            };                
            
            te::rst::Raster const* m_lowResRasterPtr; //!< Input low-resolution multi-band raster.
            
            std::vector< unsigned int > m_lowResRasterBands; //!< The low-resolution raster band indexes.
            
            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).
            
            bool m_enableThreadedProcessing; //!< If true, threaded processing will be performed (best with  multi-core or multi-processor systems (default:true).
            
            te::rst::Interpolator::Method m_interpMethod; //!< The raster interpolator method (default:NearestNeighbor).
            
            bool m_autoAlignRasters; //!< If true, the HR image will be clipped and reprojected to mach the LR image area.
            
            HRHistoFitMethod m_hrHistoFitMethod;  //!< High resolution image histogram fitting method (default: MeanStdDevHistoFitMethod).
 
            boost::numeric::ublas::matrix< double > m_directPCAMatrix; //!< A valid direct transformation PCA matrix or an empty matrix (will be automcaticall calculated).
 
            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.
            
            std::vector< double > m_lowResRastersStdDevGains; //!< A vector of positive gains to be applied when normalizing the low resolution raster bands standard deviation. To automatically apply gains a vector of size 1 can be supplied. An empty vector means no gain will be applied.
            
            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 PCAFusion 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.
 
            boost::numeric::ublas::matrix< double > m_directPCAMatrix; //!< The calculated direct PCA transformation matrix.
            
            OutputParameters();
            
            OutputParameters( const OutputParameters& );
            
            ~OutputParameters();
            
            //overload
            void reset() ;
            
            //overload
            const  OutputParameters& operator=( const OutputParameters& params );
            
            //overload
            AbstractParameters* clone() const;
        };        
 
        PCAFusion();
        
        ~PCAFusion();
       
        //overload
        bool execute( AlgorithmOutputParameters& outputParams ) ;
        
        //overload
        void reset() ;
        
        //overload
        bool initialize( const AlgorithmInputParameters& inputParams ) ;
        
        //overload
        bool isInitialized() const;
 
      protected:
        
        struct SwapBandByHighResRasterThreadParameters
        {
          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;
          double m_outMinValue;
          double m_outMaxValue;
        };                        
        
        InputParameters m_inputParameters; //!< Input execution parameters.
        
        bool m_isInitialized; //!< Tells if this instance is initialized.
        
        /*!
          \brief Swap the band values by the normalized high resolution raster data.
          \param highResRaster High resolution raster.
          \param highResRaster High resolution raster.
          \param pcaRaster The PCA raster.
          \param pcaRasterBandIdx The band index where the values will be swapped.
          \return true if ok, false on errors.
         */
        bool swapBandByHighResRaster( const te::rst::Raster& highResRaster,
          const unsigned int highResRasterBand,
          te::rst::Raster& pcaRaster, const unsigned int pcaRasterBandIdx );
        
        static void swapBandByHighResRasterThreadEntry( SwapBandByHighResRasterThreadParameters* paramsPtr );
        
        /*!
          \brief Apply a gain to each band values.
          \param raster Input raster.
          \param gains Gains for each raster band.
          \return true if ok, false on errors.
          \note outValue = ( ( inValue - off ) * gain ] + off
         */
        bool applyGainsAndOffsets( te::rst::Raster& raster, 
          std::vector< double >& gains, std::vector< double >& offsets );       
    };
 
  } // end namespace rp
}   // end namespace te
 
#endif