AssistedHarmonization.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>.
 */
 
#ifndef __TERRALIB_RP_INTERNAL_ASSISTEDHARMONIZATION_H
#define __TERRALIB_RP_INTERNAL_ASSISTEDHARMONIZATION_H
 
#include "Algorithm.h"
#include "../raster/Raster.h"
#include "../geometry/Polygon.h"
#include "../memory/CachedRaster.h"
 
#include <boost/ptr_container/ptr_vector.hpp>
 
#include <vector>
#include <map>
#include <string>
 
namespace te
{
  namespace rp
  {
    /*!
      \class AssistedHarmonization
      \brief Performs raster data assisted histogram harmonization.
      \ingroup rp_gen
      \sa Reference: MOREIRA, N. A. P. ; KORTING, T. S. ; DUTRA, L. V. ; CASTEJON, E. F. ; ARAI, E. . Calibração relativa para extensão de assinaturas em série de imagens MODIS. Journal of Information and Data Management, v. 20, p. 230-236, 2019.
    */
    class TERPEXPORT AssistedHarmonization : public Algorithm
    {
      public:
        
        /*!
          \class InputParameters
          \brief AssistedHarmonization input parameters
         */        
        class TERPEXPORT InputParameters : public AlgorithmInputParameters
        {
          public:
            
            typedef te::gm::Polygon TargetAreasGeomT;            
            
            typedef unsigned int TargetAreasClassIDT;
            
            typedef std::vector< TargetAreasGeomT* > TargetAreasGeomContT;
            
            typedef std::map< TargetAreasClassIDT, TargetAreasGeomContT >
              TargetAreasContT;
            
            /*! \enum BlendMethod te::rp::Blender class pixel blend methods. */      
            enum HarmonizationMethod 
            {
              InvalidMethod = 0, //!< Invalid method.
              MeanStdHMethod = 1, //!< Mean and Standart deviation are used to perform equalization by gain and offset.
              MSEHMethod = 2 //!< Mean square errors of classes means are used to calculate gain & offset"
            };
            
            HarmonizationMethod m_method;
            
            bool m_enableProgress; //!< Enable/Disable the progress interface (default:false).            
 
            te::rst::Raster const* m_refInputRasterPtr; //!< Reference Input raster.
            
            std::vector< unsigned int > m_refInputRasterBands; //!< Referebce input raster bands to process.
            
            te::rst::Raster const* m_adjInputRasterPtr; //!< Adjust Input raster.
            
            std::vector< unsigned int > m_adjInputRasterBands; //!< Adjust input raster bands to process.
            
            TargetAreasContT m_referenceTargetAreas; //!< Areas of interest over the reference image groupped by class ID.
            
            TargetAreasContT m_adjustTargetAreas; //!< Areas of interest over the adjust image groupped by class ID.
            
            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;
            
            void getMethodsInfo( std::map< HarmonizationMethod, std::pair< 
              std::string, std::string > >& info ) const;
        };
        
        /*!
          \class OutputParameters
          \brief AssistedHarmonization 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 registered raster.
            
            std::vector< double > m_gains; //!< The bands gains used to generate the output raster (output = ( ( input - input_offset ) * gain ) + output_offset).
            
            std::vector< double > m_inOffsets; //!< The bands input offsets used to generate the output raster (output = ( ( input - input_offset ) * gain ) + output_offset).
            
            std::vector< double > m_outOffsets; //!< The bands output offsets used to generate the output raster (output = ( ( input - input_offset ) * gain ) + output_offset).
            
            OutputParameters();
            
            OutputParameters( const OutputParameters& );
            
            ~OutputParameters();
            
            //overload
            void reset() ;
            
            //overload
            const  OutputParameters& operator=( const OutputParameters& params );
            
            //overload
            AbstractParameters* clone() const;
        };        
 
        AssistedHarmonization();
        
        ~AssistedHarmonization();
       
        //overload
        bool execute( AlgorithmOutputParameters& outputParams ) ;
        
        //overload
        void reset() ;
        
        //overload
        bool initialize( const AlgorithmInputParameters& inputParams ) ;
        
        bool isInitialized() const;
 
      protected:
        
        AssistedHarmonization::InputParameters m_inputParameters; //!< Input execution parameters.
        
        bool m_isInitialized; //!< Tells if this instance is initialized.
        
        bool CreateOutRaster(
          const te::mem::CachedRaster& adjInputCRaster,
          const std::vector< double >& gains,
          const std::vector< double >& inputOffsets,
          const std::vector< double >& outputOffsets,
          AssistedHarmonization::OutputParameters* outParamsPtr );
        
        bool MeanStdHMethodImp( 
          const te::mem::CachedRaster& refInputCRaster,
          const te::mem::CachedRaster& adjInputCRaster,
          const InputParameters::TargetAreasContT& referenceTargetAreasReproj,
          const InputParameters::TargetAreasContT& adjustTargetAreasReproj,
          AssistedHarmonization::OutputParameters* outParamsPtr  );
        
        bool MSEHMethodImp( 
          const te::mem::CachedRaster& refInputCRaster,
          const te::mem::CachedRaster& adjInputCRaster,
          const InputParameters::TargetAreasContT& referenceTargetAreasReproj,
          const InputParameters::TargetAreasContT& adjustTargetAreasReproj,        
          AssistedHarmonization::OutputParameters* outParamsPtr );
        
        bool getRasterStatistics( 
          const te::rst::Raster& inputRaster,
          const std::vector< unsigned int >& inputRasterBandsIndexes,
          const InputParameters::TargetAreasContT& targetAreas,
          std::map< InputParameters::TargetAreasClassIDT, unsigned int>& samplesNumber,
          std::map< unsigned int, std::vector< double > >& means,
          std::map< unsigned int, std::vector< double > >& stdDevs ) const;
          
        void reprojectGeometries( 
          const AssistedHarmonization::InputParameters::TargetAreasContT& inGeoms,
          AssistedHarmonization::InputParameters::TargetAreasContT& outGeoms,
          boost::ptr_vector< InputParameters::TargetAreasGeomT >& outGeomHandler,
          const int targetSRID );
        
        // gains and offsets under reference ranges.
        // gain = ref / adj
        // off = ref - ( gain * adj )        
        bool calcClassGainsOffsets( 
          const std::map< InputParameters::TargetAreasClassIDT, std::vector< double > >& 
            referenceMeans,
          const std::map< InputParameters::TargetAreasClassIDT, std::vector< double > >& 
            referenceStdDevs,  
          const std::map< InputParameters::TargetAreasClassIDT, unsigned int>& 
            referenceSamplesNumber,
          const std::map< InputParameters::TargetAreasClassIDT, std::vector< double > >& 
            adjustMeans,
          const std::map< InputParameters::TargetAreasClassIDT, std::vector< double > >& 
            adjustStdDevs,  
          std::map< InputParameters::TargetAreasClassIDT, std::vector< double > >& 
            classesGains,
          std::map< InputParameters::TargetAreasClassIDT, std::vector< double > >& 
            classesOffsets );
        
        // output = ( ( input - input_offset ) * gain ) + output_offset
        bool copyRasterData( const te::rst::Raster& inRaster,
          const std::vector< double >& gains,
          const std::vector< double >& inputOffsets,
          const std::vector< double >& outputOffsets,
          te::rst::Raster& outRaster );
        
        // means square root to find a and b ( y = a + b * x ).
        // given a set off coods
        // reference: https://pt.wikipedia.org/wiki/M%C3%A9todo_dos_m%C3%ADnimos_quadrados        
        bool linearRegression( std::vector< std::pair< double, double > >& coords, 
          double&a, double& b );
    };
 
  } // end namespace rp
}   // end namespace te
 
#endif