Blender.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/Blender.h
  \brief Blended pixel value calculation for two overlaped rasters.
 */
 
#ifndef __TERRALIB_RP_INTERNAL_BLENDER_H
#define __TERRALIB_RP_INTERNAL_BLENDER_H
 
#include "Config.h"
#include "Macros.h"
#include "BlenderRule.h"
#include "../raster/Grid.h"
#include "../raster/Raster.h"
#include "../raster/Interpolator.h"
#include "../raster/RasterSynchronizer.h"
#include "../raster/TileIndexer.h"
#include "../geometry/Polygon.h"
#include "../geometry/MultiPolygon.h"
#include "../geometry/Point.h"
#include "../geometry/GeometricTransformation.h"
 
#include <boost/noncopyable.hpp>
#include <boost/ptr_container/ptr_vector.hpp>
 
#include <vector>
#include <complex>
#include <memory>
#include <thread>
 
namespace te
{
  namespace rp
  {
    /*!
      \class Blender
      \brief Blended pixel value calculation for two overlaped rasters.
      \details The overlap between the two images is modeled by the given geometric transformation direct mapping input raster 1 indexed coords (line, column) to input raster 2 indexed coords.
      \note Optimized for rasters where all bands have the same blocking scheme.
      \ingroup rp_aux
     */
    class TERPEXPORT Blender : public boost::noncopyable
    {
      public:
        
        /*!
          \typedef BlendMethod te::rp::Blender class pixel blend methods.
        */        
        typedef te::rp::blender::BlendMethod BlendMethod;
        
        /*! Default constructor. */
        Blender();
        
        /*! Default destructor. */
        ~Blender();
        
        /*!
          \brief Inititate the blender instance.
          \param raster1 Input raster 1.
          \param raster1Bands Input raster 1 band indexes to use.
          \param raster2 Input raster 2.
          \param raster2Bands Input raster 2 band indexes to use (this vector has the same size as raster1Bands).
          \param blendMethod The blend method to apply.
          \param interpMethod1 The interpolation method to use when reading raster 1 data.
          \param interpMethod2 The interpolation method to use when reading raster 2 data.
          \param noDataValue The value returned where there is no pixel data bo blend.
          \param forceRaster1NoDataValue Use noDataValue as the input raster 1 no-data value (The original rasters no-data values will be ignored)
          \param forceRaster2NoDataValue Use noDataValue as the input raster 1 no-data value (The original rasters no-data values will be ignored)  
          \param pixelOffsets1 The values offset to be applied to raster 1 pixel values before the blended value calcule (one element for each used raster channel/band).
          \param pixelScales1 The values scale to be applied to raster 1 pixel values before the blended value calcule (one element for each used raster channel/band).
          \param pixelOffsets2 The values offset to be applied to raster 2 pixel values before the blended value calcule (one element for each used raster channel/band).
          \param pixelScales2 The values scale to be applied to raster 2 pixel values before the blended value calcule (one element for each used raster channel/band).
          \param r1ValidDataDelimiterPtr A pointer to a geometry (raster 1 world/projected coords) delimiting the raster region with valid data, or null if all raster data area is valid.
          \param r2ValidDataDelimiterPtr A pointer to a geometry (raster 2 world/projected coords) delimiting the raster region with valid data, or null if all raster data area is valid.
          \param geomTransformation A transformation mapping raster 1 pixels ( te::gm::GTParameters::TiePoint::first ) to raster 2 pixels ( te::gm::GTParameters::TiePoint::second ) (Note: all coords are indexed by lines/columns).
          \param threadsNumber Enable/disable the use of threads when applicable (0:automatic , 1:disabled, any other integer dictates the number of threads).
          \param enableProgressInterface Enable/disable the use of a progress interface when applicable.
          \param rulePtr A pointer to a valid blender rule (this implies using RulesMethod on the blendMethod parameter) or a null pointer.
          \param enableRasterCache Enable/disable the use of raster cache.
          \return true if ok, false on errors
          \note Aboute scale and offset parametrs:  outValue = ( inputValue * scale ) + offset
        */
        bool initialize( 
          te::rst::Raster& raster1, 
          const std::vector< unsigned int >& raster1Bands, 
          const te::rst::Raster& raster2, 
          const std::vector< unsigned int >& raster2Bands,
          const BlendMethod& blendMethod, 
          const te::rst::Interpolator::Method& interpMethod1,
          const te::rst::Interpolator::Method& interpMethod2,
          const double& noDataValue,
          const bool forceRaster1NoDataValue,
          const bool forceRaster2NoDataValue,
          const std::vector< double >& pixelOffsets1,
          const std::vector< double >& pixelScales1,
          const std::vector< double >& pixelOffsets2,
          const std::vector< double >& pixelScales2,
          te::gm::MultiPolygon const * const r1ValidDataDelimiterPtr,
          te::gm::MultiPolygon const * const r2ValidDataDelimiterPtr,
          const te::gm::GeometricTransformation& geomTransformation,
          const unsigned int threadsNumber,
          const bool enableProgressInterface,
          BlenderRule const * const rulePtr,
          const bool enableRasterCache );
        
        
        /*!
          \brief Blend a pixel value using the current parameters.
          \param line Line (raster 1 reference).
          \param col Column (raster 1 reference).
          \param values A pointer to a pre-allocated vector where the blended values will be stored.
          \note The caller of this method must be aware that the returned blended value may be outside the original input rasters valid values range.
          \note Raster 1 values have precedence over raster 2 values (when applicable).
        */
        inline void getBlendedValues( const double& line, const double& col, 
          double* const values )
        {
          TERP_DEBUG_TRUE_OR_THROW( m_primaryBlendFuncPtr, "Invalid blend function pointer" );
          (this->*m_primaryBlendFuncPtr)( line, col, values );
        };
 
        /*!
          \brief Execute blending of the given input rasters and write the result into raster1.
          \note Raster 1 values have precedence over raster 2 values (when applicable).
        */        
        bool blendIntoRaster1();
        
        /*!
          \brief Return the current error message if there is any.
 
          \return Return the current error message if there is any.
         */
        const std::string& getErrorMessage() const;        
 
      protected:
        
        /*!
          \brief Type definition for the a primary bleding function pointer.
          \param line Raster 1 Line.
          \param col Raster 1 Column.
          \param values A pointer to a pre-allocated vector where the blended values will be stored.
          \note The caller of this method must be aware that the returned blended value may be outside the original input rasters valid values range.
          \note Raster 1 values have precedence over raster 2 values (when applicable).
        */      
        typedef void (Blender::*PrimaryBlendFunctPtr)( const double& line, 
          const double& col, double* const values );   
        
        /*!
          \brief Raster block info
        */  
        struct RasterBlockInfo
        {
          bool m_wasProcessed;
          unsigned int m_blkX;
          unsigned int m_blkY;
          unsigned int m_blkTotalPixelsNumber;
          unsigned int m_firstRasterRow2Process;
          unsigned int m_rasterRows2ProcessBound;
          unsigned int m_firstRasterCol2Process;
          unsigned int m_rasterCols2ProcessBound;
        };
        
        /*! 
          \brief The parameters passed to blendIntoRaster1Thread method.
        */     
        class BlendIntoRaster1ThreadParams
        {
          public :
            
            bool* m_returnValuePtr; //!< A pointer to the threadreturn value.
            bool* m_abortValuePtr; //!< A pointer to the abort execution value.
            te::rst::RasterSynchronizer* m_sync1Ptr; //!< Raster 1 syncronizer pointer.
            te::rst::RasterSynchronizer* m_sync2Ptr; //!< Raster 1 syncronizer pointer.
            std::vector< RasterBlockInfo >* m_raster1BlocksInfosPtr; //!< blocks to process.
            std::mutex* m_mutexPtr; //!< mutex pointer.
            std::mutex* m_blockProcessedSignalMutexPtr; //!< Mutex used to update the main process progress update.
            std::condition_variable* m_blockProcessedSignalPtr; //!< Signal used to update the main process progress update.            
            unsigned int* m_runningThreadsCounterPtr; //!< a pointer to the running threads counter.
            std::vector< unsigned int > const* m_raster1BandsPtr; //!< Input raster 1 band indexes to use.
            std::vector< unsigned int > const* m_raster2BandsPtr; //!< Input raster 2 band indexes to use (this vector has the same size as raster1Bands).
            BlendMethod m_blendMethod; //!<  The blend method to apply.
            te::rst::Interpolator::Method m_interpMethod2; //!< The interpolation method to use when reading raster 2 data.
            double m_noDataValue; //!< The value returned where there is no pixel data bo blend.
            bool m_forceRaster1NoDataValue; //!< Use noDataValue as the input rasters no-data value (The original rasters no-data values will be ignored)
            bool m_forceRaster2NoDataValue; //!< Use noDataValue as the input rasters no-data value (The original rasters no-data values will be ignored)  
            std::vector< double > const* m_pixelOffsets1Ptr; //!< The values offset to be applied to raster 1 pixel values before the blended value calcule (one element for each used raster channel/band).
            std::vector< double > const* m_pixelScales1Ptr; //!< The values scale to be applied to raster 1 pixel values before the blended value calcule (one element for each used raster channel/band).
            std::vector< double > const* m_pixelOffsets2Ptr; //!< The values offset to be applied to raster 2 pixel values before the blended value calcule (one element for each used raster channel/band).
            std::vector< double > const* m_pixelScales2Ptr; //!< The values scale to be applied to raster 2 pixel values before the blended value calcule (one element for each used raster channel/band).
            te::gm::MultiPolygon const* m_r1ValidDataDelimiterPtr; //!< A pointer to a geometry (raster 1 world/projected coords) delimiting the raster region with valid data, or null if all raster data area is valid.
            te::gm::MultiPolygon const* m_r2ValidDataDelimiterPtr; //!< A pointer to a geometry (raster 2 world/projected coords) delimiting the raster region with valid data, or null if all raster data area is valid.
            te::gm::GeometricTransformation const* m_geomTransformationPtr; //!< A transformation mapping raster 1 pixels ( te::gm::GTParameters::TiePoint::first ) to raster 2 pixels ( te::gm::GTParameters::TiePoint::second ) (Note: all coords are indexed by lines/columns).
            unsigned long int m_maxRasterCachedBlocks; //!< The maximum number of raster cache blocks.
            bool m_useProgress; //!< If enabled each thread will use its own progress interface, if false only a signal will be emitted on each processed block.
            BlenderRule const * m_rulePtr; // a pointer to a rula to be used or a null pointer.
            unsigned int* m_processedBlocksNmbPtr;
            
            BlendIntoRaster1ThreadParams() {};
            
            ~BlendIntoRaster1ThreadParams() {};
            
          protected :
            
            BlendIntoRaster1ThreadParams( const BlendIntoRaster1ThreadParams& ) {};
            
            BlendIntoRaster1ThreadParams& operator=( const BlendIntoRaster1ThreadParams& ) { return *this; };
        };           
 
        bool m_enableProgressInterface; //!< Enable progress interface.
        bool m_forceRaster1NoDataValue; //!<  Use noDataValue as the input raster 1 no-data value (The original rasters no-data values will be ignored)
        bool m_forceRaster2NoDataValue; //!<  Use noDataValue as the input raster 2 no-data value (The original rasters no-data values will be ignored)  
        unsigned int m_threadsNumber; //!< The number of threads to use (0:automatic , 1:disabled, any other integer dictates the number of threads)..
        BlendMethod m_blendMethod; //!< The blend method to apply.
        PrimaryBlendFunctPtr m_primaryBlendFuncPtr; //!< The primary blend function.
        te::rst::Raster * m_raster1Ptr; //!< Input raster 1.
        te::rst::Raster const * m_raster2Ptr; //!< Input raster 2.
        std::unique_ptr< te::gm::MultiPolygon > m_r1ValidDataDelimiterPtr; //!< A pointer to a geometry (raster 1 world/projected coords) delimiting the raster region with valid data, or null if all raster data area is valid.
        std::unique_ptr< te::gm::MultiPolygon > m_r2ValidDataDelimiterPtr; //!< A pointer to a geometry (raster 2 world/projected coords) delimiting the raster region with valid data, or null if all raster data area is valid.
        std::unique_ptr< te::gm::Geometry > m_intersectionPtr; //!< The Intersection geometry ( raster 1 indexed coods).
        std::vector< std::pair< te::gm::Coord2D, te::gm::Coord2D > > m_r1IntersectionSegmentsPoints; //!< A sub-set of the intersection polygon wich is part of raster 1 valid data polygon ( raster 1 indexed coods).
        std::size_t m_r1IntersectionSegmentsPointsSize; //!< Size of m_r1IntersectionSegmentsPoints;
        std::vector< std::pair< te::gm::Coord2D, te::gm::Coord2D > > m_r2IntersectionSegmentsPoints; //!< A sub-set of the intersection polygon wich is part of raster 2 valid data polygon ( raster 1 indexed coods).
        std::size_t m_r2IntersectionSegmentsPointsSize; //!< Size of m_r2IntersectionSegmentsPoints;
        te::gm::GeometricTransformation* m_geomTransformationPtr; //!< A transformation mapping raster 1 pixels ( te::gm::GTParameters::TiePoint::first ) to raster 2 ( te::gm::GTParameters::TiePoint::second ) (Note: all coords are indexed by lines/columns).
        te::rst::Interpolator::Method m_interpMethod1; //!< The interpolation method to use when reading raster 1 data.
        te::rst::Interpolator::Method m_interpMethod2; //!< The interpolation method to use when reading raster 2 data.
        double m_outputNoDataValue; //!< The output raster no-data value.
        std::unique_ptr< te::rst::Interpolator > m_interp1Ptr; //!< Raster 1 interpolator instance pointer.
        std::unique_ptr< te::rst::Interpolator > m_interp2Ptr; //!< Raster 2 interpolator instance pointer.        
        std::vector< unsigned int > m_raster1Bands; //!< Input raster 1 band indexes to use.
        std::vector< unsigned int > m_raster2Bands; //!< Input raster 2 band indexes to use.
        unsigned int m_raster1BandsSize;
        unsigned int m_raster2BandsSize;
        std::vector< double > m_pixelOffsets1; //!< The values offset to be applied to raster 1 pixel values before the blended value calcule (one element for each used raster channel/band).
        std::vector< double > m_pixelScales1; //!< The values scale to be applied to raster 1 pixel values before the blended value calcule (one element for each used raster channel/band).
        std::vector< double > m_pixelOffsets2; //!< The values offset to be applied to raster 2 pixel values before the blended value calcule (one element for each used raster channel/band).
        std::vector< double > m_pixelScales2; //!< The values scale to be applied to raster 2 pixel values before the blended value calcule (one element for each used raster channel/band).
        std::vector< double > m_raster1NoDataValues; //!< Raster 1 no-data values (on value per band).
        std::vector< double > m_raster2NoDataValues; //!< Raster 2 no-data values (on value per band).
        boost::ptr_vector< te::rst::TileIndexer > m_intersectionTileIndexers; //!< The Intersection geometry tile indexers( raster 1 indexed coods), one indexer for each intersection polygon.
        std::unique_ptr< BlenderRule > m_rulePtr; //!< Blender rule pointer.
        std::string m_errorMessage; //!< Current error message.
        bool m_enableRasterCache; //!< enable/disable the use of raster cache.
        
        // variables used by the noBlendMethodImp method
        double m_noBlendMethodImp_Point2Line;
        double m_noBlendMethodImp_Point2Col;        
        unsigned int m_noBlendMethodImp_BandIdx;
        bool m_noBlendMethodImp_pixel1IsValid;
        bool m_noBlendMethodImp_pixel2IsValid;
        std::vector< std::complex< double > > m_noBlendMethodImp_pixel1Values;
        std::vector< std::complex< double > > m_noBlendMethodImp_pixel2Values;                
        
        // variables used by the euclideanDistanceMethodImp method
        double m_euclideanDistanceMethodImp_Point2Line;
        double m_euclideanDistanceMethodImp_Point2Col;        
        unsigned int m_euclideanDistanceMethodImp_BandIdx;   
        double m_euclideanDistanceMethodImp_currDist;
        double m_euclideanDistanceMethodImp_dist1;
        double m_euclideanDistanceMethodImp_dist2;
        std::size_t m_euclideanDistanceMethodImp_vecIdx;
        double m_euclideanDistanceMethodImp_aux1;
        double m_euclideanDistanceMethodImp_aux2;
        bool m_euclideanDistanceMethodImp_pixel1IsValid;
        bool m_euclideanDistanceMethodImp_pixel2IsValid;
        std::vector< std::complex< double > > m_euclideanDistanceMethodImp_pixel1Values;
        std::vector< std::complex< double > > m_euclideanDistanceMethodImp_pixel2Values;        
        
        // variables used by the sumMethodImp method
        te::gm::Point m_sumMethodImp_auxPoint;
        double m_sumMethodImp_Point2Line;
        double m_sumMethodImp_Point2Col;        
        std::complex< double > m_sumMethodImp_cValue1;
        std::complex< double > m_sumMethodImp_cValue2;
        unsigned int m_sumMethodImp_BandIdx; 
        unsigned int m_sumMethodImp_IntersectionTileIndexersIdx;
        bool m_sumMethodImp_PointInsideIntersection;
        
        // variables used by the maxMethodImp method
        te::gm::Point m_maxMethodImp_auxPoint;
        double m_maxMethodImp_Point2Line;
        double m_maxMethodImp_Point2Col;        
        std::complex< double > m_maxMethodImp_cValue1;
        std::complex< double > m_maxMethodImp_cValue2;
        unsigned int m_maxMethodImp_BandIdx; 
        unsigned int m_maxMethodImp_IntersectionTileIndexersIdx;
        bool m_maxMethodImp_PointInsideIntersection;        
        
        // variables used by the minMethodImp method
        te::gm::Point m_minMethodImp_auxPoint;
        double m_minMethodImp_Point2Line;
        double m_minMethodImp_Point2Col;        
        std::complex< double > m_minMethodImp_cValue1;
        std::complex< double > m_minMethodImp_cValue2;
        unsigned int m_minMethodImp_BandIdx; 
        unsigned int m_minMethodImp_IntersectionTileIndexersIdx;
        bool m_minMethodImp_PointInsideIntersection;             
        
        // variables used by the ruleMethodImp method
        double m_ruleMethodImp_Point2Line;
        double m_ruleMethodImp_Point2Col;
        
        /*! \brief Reset the instance to its initial default state. */
        void initState();
        
        /*! \brief Clear all internal allocated resources. */
        void clear();
        
        /*! \brief Set the value of m_blendFuncPtr following the given blend method. */
        void setBlendFunctionsPonters( const BlendMethod blendMethod );
        
        /*!
          \brief Implementation for NoBlendMethod.
          \param line Raster 1 Line.
          \param col Raster 1 Column.
          \param values A pointer to a pre-allocated vector where the blended values will be stored.
        */
        void noBlendMethodImp( const double& line1, const double& col1,
          double* const values );        
 
        /*!
          \brief Implementation for EuclideanDistanceMethod.
          \param line Raster 1 Line.
          \param col Raster 1 Column.
          \param values A pointer to a pre-allocated vector where the blended values will be stored.
        */
        void euclideanDistanceMethodImp( const double& line1, const double& col1,
          double* const values );
        
        /*!
          \brief Implementation for SumMethod.
          \param line Raster 1 Line.
          \param col Raster 1 Column.
          \param values A pointer to a pre-allocated vector where the blended values will be stored.
        */
        void sumMethodImp( const double& line1, const double& col1,
          double* const values );        
        
        /*!
          \brief Implementation for MaxMethod.
          \param line Raster 1 Line.
          \param col Raster 1 Column.
          \param values A pointer to a pre-allocated vector where the blended values will be stored.
        */
        void maxMethodImp( const double& line1, const double& col1,
          double* const values );      
 
        /*!
          \brief Implementation for MinMethod.
          \param line Raster 1 Line.
          \param col Raster 1 Column.
          \param values A pointer to a pre-allocated vector where the blended values will be stored.
        */
        void minMethodImp( const double& line1, const double& col1,
          double* const values );              
        
        /*!
          \brief Rule based Implementation.
          \param line Raster 1 Line.
          \param col Raster 1 Column.
          \param values A pointer to a pre-allocated vector where the blended values will be stored.
        */
        void ruleMethodImp( const double& line1, const double& col1,
          double* const values );
        
        /*!
          \brief Thread entry for the method blendIntoRaster1.
 
        */        
        static void blendIntoRaster1Thread( BlendIntoRaster1ThreadParams* paramsPtr );
        
        /*!
          \brief Extract segments from the given geometry.
          \param geometryPtr Input geometry.
          \param segments Found segments (appended here).
          \note The only supported geometry types are those composed by te::gm::LineString or te::gm::CircularString (for other types no segments will be returned).
        */        
        void getSegments( te::gm::Geometry const * const geometryPtr,
          std::vector< std::pair< te::gm::Coord2D, te::gm::Coord2D > >& segments ) const;
          
        
        /*!
          \brief Creater polygon tile indexers from the given geometry (only if it is a polygon or a collection of polygons).
          \param geometryPtr Input geometry.
          \param tileIndexers Created indexers (appended here).
          \return true if OK, false on errors.
          \note No indexers will be returned for geometries other than polygons or collections of polygons.
        */        
        bool getTileIndexers( te::gm::Geometry const * const geometryPtr, 
          boost::ptr_vector< te::rst::TileIndexer >& tileIndexers ) const;          
          
        /*!
          \brief Set the current error message.
 
          \param newErrorMessage New error message;
         */
        void setErrorMessage( const std::string& newErrorMessage );          
    };
 
  } // end namespace rp
}   // end namespace te
 
#endif  // __TERRALIB_RP_INTERNAL_ALGORITHM_H