Composer.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_COMPOSER_H
#define __TERRALIB_RP_INTERNAL_COMPOSER_H
 
#include "Config.h"
#include "Macros.h"
#include "ComposerRule.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/ptr_container/ptr_vector.hpp>
 
#include <vector>
#include <complex>
#include <memory>
#include <thread>
 
namespace te
{
  namespace rp
  {
    /*!
      \class Composer
      \brief Composed 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 Composer
    {
      public:
        
        /*! Default constructor. */
        Composer();
        
        /*! Default destructor. */
        ~Composer();
        
        /*!
          \brief Inititate the composer instance.
          \param raster1 Raster 1.
          \param raster1Bands Raster 1 band indexes to use.
          \param raster2 Raster 2.
          \param raster2Bands Raster 2 band indexes to use (this vector has the same size as raster1Bands).
          \param raster3 Raster 3.
          \param raster3Bands Raster 3 band indexes to use (this vector has the same size as raster1Bands).          
          \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 compose.
          \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 composeed 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 composeed 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 composeed 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 composeed value calcule (one element for each used raster channel/band).
          \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 composer rule.
          \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
          \note All raster 3 bands must have the same blocking scheme.
        */
        bool initialize( 
          te::rst::Raster& raster1, 
          const std::vector< unsigned int >& raster1Bands, 
          const te::rst::Raster& raster2, 
          const std::vector< unsigned int >& raster2Bands,
          te::rst::Raster& raster3, 
          const std::vector< unsigned int >& raster3Bands,          
          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,
          const unsigned int threadsNumber,
          const bool enableProgressInterface,
          ComposerRule const * const rulePtr,
          const bool enableRasterCache );
        
        
        /*!
          \brief Compose a pixel value using the current parameters.
          \param line Line (raster 3 reference).
          \param col Column (raster 3 reference).
          \param values A pointer to a pre-allocated vector where the composeed values will be stored.
          \note The caller of this method must be aware that the returned composeed 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 getComposedValues( const double& line, const double& col, 
          double* const values )
        {
          TERP_DEBUG_TRUE_OR_THROW( m_rulePtr.get() != nullptr, "Invalid compose rule" );
          m_rulePtr->getComposedValues( line, col, values );
        };
 
        /*!
          \brief Execute a composition of the given input rasters and write the result into raster 3.
          \note Raster 1 values have precedence over raster 2 values (when applicable).
        */        
        bool composeIntoRaster3();
        
        /*!
          \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 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 composeIntoRaster1Thread method.
        */     
        class ComposeIntoRaster3ThreadParams
        {
          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 2 syncronizer pointer.
            te::rst::RasterSynchronizer* m_sync3Ptr; //!< Raster 3 syncronizer pointer.
            std::vector< RasterBlockInfo >* m_raster3BlocksInfosPtr; //!< 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).
            std::vector< unsigned int > const* m_raster3BandsPtr; //!< Input raster 3 band indexes to use (this vector has the same size as raster1Bands).
            te::rst::Interpolator::Method m_interpMethod1; //!< The interpolation method to use when reading raster 2 data.
            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 compose.
            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 composeed 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 composeed 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 composeed 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 composeed value calcule (one element for each used raster channel/band).
            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.
            ComposerRule const * m_rulePtr; // a pointer to a rula to be used or a null pointer.
            unsigned int* m_processedBlocksNmbPtr;
            
            ComposeIntoRaster3ThreadParams() {};
            
            ~ComposeIntoRaster3ThreadParams() {};
            
          protected :
            
            ComposeIntoRaster3ThreadParams( const ComposeIntoRaster3ThreadParams& ) {};
            
            ComposeIntoRaster3ThreadParams& operator=( const ComposeIntoRaster3ThreadParams& ) { 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)..
        te::rst::Raster const * m_raster1Ptr; //!< Raster 1.
        te::rst::Raster const * m_raster2Ptr; //!< Raster 2.
        te::rst::Raster * m_raster3Ptr; //!< Raster 3.
        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::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.
        std::vector< unsigned int > m_raster3Bands; //!< Input raster 3 band indexes to use.
        std::vector< double > m_pixelOffsets1; //!< The values offset to be applied to raster 1 pixel values before the composeed 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 composeed 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 composeed 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 composeed value calcule (one element for each used raster channel/band).
        std::unique_ptr< ComposerRule > m_rulePtr; //!< Composer rule pointer.
        std::string m_errorMessage; //!< Current error message.
        bool m_enableRasterCache; //!< enable/disable the use of raster cache.
        
        /*! \brief Reset the instance to its initial default state. */
        void initState();
        
        /*! \brief Clear all internal allocated resources. */
        void clear();
        
        /*!
          \brief Thread entry for the method composeIntoRaster1.
        */        
        static void composeIntoRaster3Thread( ComposeIntoRaster3ThreadParams* paramsPtr );
        
        /*!
          \brief Set the current error message.
 
          \param newErrorMessage New error message;
         */
        void setErrorMessage( const std::string& newErrorMessage );
        
      private :
        
        Composer( const Composer& other );
        
        Composer& operator=( const Composer& other );
    };
 
  } // end namespace rp
}   // end namespace te
 
#endif