RasterSummaryManager.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/raster/RasterSummaryManager.h
 
  \brief A singleton for keeping raster summaries (most statistics).
*/
 
#ifndef __TERRALIB_RASTER_INTERNAL_RASTERSUMMARYMANAGER_H
#define __TERRALIB_RASTER_INTERNAL_RASTERSUMMARYMANAGER_H
 
// TerraLib
#include "../common/Singleton.h"
#include "../common/Enums.h"
#include "Config.h"
#include "Enums.h"
#include "RasterSummary.h"
 
//STL
#include <list>
#include <mutex>
 
namespace te
{
  namespace rst
  {
// Forward declaration
    class Raster;
 
    /*!
      \class RasterSummaryManager
 
      \brief A singleton for keeping raster summaries (most statistics).
             It stores an internal map of raster conn info str and their
             respective summaries.
 
      \ingroup rst
 
      \sa RasterSummary, BandSummary.
    */
    class TERASTEREXPORT RasterSummaryManager : public te::common::Singleton<RasterSummaryManager>
    {
      friend class te::common::Singleton<RasterSummaryManager>;
 
      public:
 
        /*!
          \brief Searches for a raster summary.
          \param raster The raster to be found.
          \param summary The found raster summary.
          \return true if the summary has been found, false if not found.
          \note This is a thread safe method (an internal mutex is used).
        */
        bool find(const Raster* raster, RasterSummary& summary ) const;
        
        /*!
          \brief Searches for a band summary.
          \param raster The raster to be found.
          \param rowStart The starting row.
          \param colStart The starting column.
          \param finalRow The final row.
          \param finalCol The final column.
          \param histoBins  The number of bins (intervals from minimum pixel to maximum). When b = 0, the histogram will be divided according to all pixel values.
          \param sampleStep The row/column step used when reading pixels (to read all pixels sampleStep=1, to read half of pixels use sampleStep=2 );
          \param summary The found raster summary.
          \return true if the summary has been found, false if not found.
          \note This is a thread safe method (an internal mutex is used).
        */
        bool find(const Raster* raster, const unsigned int bandIndex,
          const unsigned int rowStart, const unsigned int colStart,
          const unsigned int finalRow, const unsigned int finalCol,
          const unsigned int histoBins, const unsigned int sampleStep,
          BandSummary& summary ) const;
 
        /*!
          \brief Removes the summary from the specified raster.
          \param raster The raster to be found.
          \param rowStart The starting row.
          \param colStart The starting column.
          \param finalRow The final row.
          \param finalCol The final column.
          \param histoBins  The number of bins (intervals from minimum pixel to maximum). When b = 0, the histogram will be divided according to all pixel values.
          \param sampleStep The row/column step used when reading pixels (to read all pixels sampleStep=1, to read half of pixels use sampleStep=2 );
        */
        void remove(const Raster* raster, const unsigned int bandIndex,
          const unsigned int rowStart, const unsigned int colStart,
          const unsigned int finalRow, const unsigned int finalCol,
          const unsigned int histoBins, const unsigned int sampleStep);
        
        /*!
          \brief Removes all summary ocurrences related to the specified raster pointer
          \param raster The raster pointer to remove the summary.
          \note This is a thread safe method (an internal mutex is used).
        */
        void remove(const Raster* raster);        
        
        /*!
          \brief Removes all raster summary entries.
          \note This is a thread safe method (an internal mutex is used).
          \note All cached info will be removed.
        */
        void removeAll();
 
        /*!
          \brief It searches for a raster summary. If not found it creates the summary and returns it.
          \param raster      The raster to be found.
          \param readall     If false, the cache will be used or if true the entire image will be read again (can be slow).
          \param summary     The found raster summary.
          \return true if ok, false on errors.
          \note This is a thread safe method (an internal mutex is used).
        */
        bool get( const Raster* raster, bool readall, RasterSummary& summary );
        
        /*!
          \brief It searches for a raster summary. If not found it creates the summary and returns it.
          \param raster      The raster to be found.
          \param rowStart The starting row.
          \param colStart The starting column.
          \param finalRow The final row.
          \param finalCol The final column.
          \param histoBins  The number of bins (intervals from minimum pixel to maximum). When b = 0, the histogram will be divided according to all pixel values.
          \param sampleStep The row/column step used when reading pixels (to read all pixels sampleStep=1, to read half of pixels use sampleStep=2 );
          \param readall     Force the reading the entire image (can be slow) for computing min and max values.
          \param summary     The found raster summary.
          \return true if ok, false on errors.
          \note This is a thread safe method (an internal mutex is used).
        */
        bool get( const Raster* raster, const unsigned int rowStart, 
          const unsigned int colStart, const unsigned int finalRow, 
          const unsigned int finalCol, const unsigned int histoBins, 
          const unsigned int sampleStep, bool readall, RasterSummary& summary );
        
        /*!
          \brief Searches for a band summary and creates it if it does not exist.
          \param raster      The raster to be found.
          \param bandIndex Band index.
          \param readall     If false, the cache will be used or if true the entire image will be read again (can be slow).
          \param summary     The found band summary.
          \return true if ok, false on errors.
          \note This is a thread safe method (an internal mutex is used).
        */
        bool get( const Raster* raster, const unsigned int bandIndex, bool readall, BandSummary& summary );
        
        /*!
          \brief Searches for a band summary and creates it if it does not exist.
          \param raster The raster to be found.
          \param bandIndex Band index.
          \param rowStart The starting row.
          \param colStart The starting column.
          \param finalRow The final row.
          \param finalCol The final column.
          \param histoBins  The number of bins (intervals from minimum pixel to maximum). When b = 0, the histogram will be divided according to all pixel values.
          \param sampleStep The row/column step used when reading pixels (to read all pixels sampleStep=1, to read half of pixels use sampleStep=2 );
          \param readall     Force the reading the entire image (can be slow) for computing min and max values.
          \param summary The found band summary.
          \return true if the summary has been found, false if not found.
          \note This is a thread safe method (an internal mutex is used).
        */
        bool get( const Raster* raster, const unsigned int bandIndex,
          const unsigned int rowStart, const unsigned int colStart,
          const unsigned int finalRow, const unsigned int finalCol,
          const unsigned int histoBins, const unsigned int sampleStep,
          bool readall, BandSummary& summary );        
 
        /*! \brief Destructor. */
        ~RasterSummaryManager();
        
        /*!
          \brief Enable/disable the cache of deleted rasters. 
          \param enabled Enable or disable this feature.
          \note Only rasters without the write policy can be cached.
        */        
        void enableDeletedRastersCache( const bool enabled );
        
        /*!
          \brief Set the default rasters histograms bins.
          \param binsNumber Histograms bins number ( When b = 0, the histogram will be divided according to all pixel values.).
        */        
        void setDefaultRasterHistSize( const unsigned int binsNumber );
        
        /*!
          \brief Get the default rasters histograms bins.
          \return Get the default rasters histograms bins.
        */        
        unsigned int getDefaultRasterHistSize();
        
      protected:
        
        /*!
          \class SumManKey
          \brief Summary manager key.
          \ingroup rst
          \sa RasterSummary, BandSummary.
        */
        class SumManKey
        {
          public :
            unsigned int m_bandIndex;
            unsigned int m_rowStart;
            unsigned int m_colStart;
            unsigned int m_finalRow;
            unsigned int m_finalCol;
            unsigned int m_histoBins;
            unsigned int m_sampleStep;
            Raster const* m_rasterPtr; // not used in comparison operators
            te::common::AccessPolicy m_rasterPolicy; // not used in comparison operators
            std::map<std::string, std::string> m_connInfo;
            BandSummary m_summary;
 
            SumManKey();
            
            SumManKey(const SumManKey& other);
            
            ~SumManKey();
            
            bool operator==( const SumManKey& other ) const;
            
            bool operator<( const SumManKey& other ) const;
            
            SumManKey& operator=(const SumManKey& other);
        };
        
        typedef std::list< SumManKey > SummaryContT;
        
        RasterSummaryManager();
 
      private:
 
        bool m_enableDeletedRastersCache;
        unsigned int m_defRastersHistBins;
        SummaryContT m_rasterSummaries;    //!< A rasters band summaries.        
        mutable std::mutex m_syncMutex;  //!< Internal mutex.
    };
 
  } // end namespace rst
}   // end namespace te
 
#endif  // __TERRALIB_RASTER_INTERNAL_RASTERSUMMARYMANAGER_H