ClassifierISOSegStrategy.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/ClassifierISOSegStrategy.h
  \brief ISOSeg strategy for segmentation-based classification.
 */

#ifndef __TERRALIB_RP_INTERNAL_CLASSIFIERISOSEGSTRATEGY_H
#define __TERRALIB_RP_INTERNAL_CLASSIFIERISOSEGSTRATEGY_H

// TerraLib
#include "ClassifierStrategy.h"
#include "ClassifierStrategyFactory.h"
#include "Config.h"
#include "../raster/RasterSynchronizer.h"

// STL
#include <map>
#include <memory>
#include <mutex>
#include <condition_variable>

// Boost
#include <boost/numeric/ublas/matrix.hpp>

namespace te
{
  namespace rp
  {
    /*!
      \class ClassifierISOSegStrategy

      \brief ISOSeg strategy for OBIA classification. The algorithm orders regions by area (larger first),
             and classify the largest region as Cluster 1. All regions similar to this cluster are inserted
             in Cluster 1, otherwise new Clusters are created. After all regions belong to a cluster, the
             algorithm merges similar clusters. The acceptance threshold is the only parameter given by
             the user, and it indicates the maximum distance between two regions to be clustered togheter.

       \ingroup rp_class
     */
    class TERPEXPORT ClassifierISOSegStrategy : public ClassifierStrategy
    {
      public:

        /*!
          \class Parameters

          \brief Classifier Parameters
        */
        class TERPEXPORT Parameters : public ClassifierStrategyParameters
        {
          public:
            
            /*!
              \enum class DistanceType
              \brief Used distance type.
            */
            enum DistanceType
            {
              InvalidDistanceType, //!< Invalid distance type.
              MahalanobisDistanceType, //!< Mahalanobis Distance Type.
              BhattacharyyaDistanceType //!< Bhattacharyya Distance Type.
            };

            DistanceType m_distanceType; //!< Distance type.
            double m_acceptanceThreshold;   //!< The acceptance threshold (the closer to 100\%, few clusters are created).

            Parameters();

            ~Parameters();

            //overload
            const Parameters& operator=(const Parameters& params);

            //overload
            void reset() throw( te::rp::Exception );

            //overload
            AbstractParameters* clone() const;
        };

        ClassifierISOSegStrategy();

        ~ClassifierISOSegStrategy();

        //overload
        bool initialize(ClassifierStrategyParameters const* const strategyParams) throw(te::rp::Exception);

        //overload
        bool execute() throw(te::rp::Exception);

      protected:

        /*!
          \class Pattern

          \brief Describes a region or a cluster (group of regions with similar properties) to be used by ISOSeg method.
        */
        class TERPEXPORT Pattern
        {
          public:

            Pattern();

            /*!
              \brief Constructor.

              \param i       The id of the initial region.
              \param a       The area of the region.
              \param mv      The vector of mean values, 1 value per band.
              \param cm      The covariance matrix between bands.
            */
            Pattern(int i, double a, std::vector<double> mv, boost::numeric::ublas::matrix<double> cm);

            /*!
              \brief Copy constructor.

              \param rhs The right-hand-side copy that would be used to copy from.
            */
            Pattern( const Pattern& rhs);

            ~Pattern();

            /*! \brief Returns the Mahalanobis distance between two patterns */
            double getMahalanobisDistance(Pattern const * const p) const;

            /*!
               \brief Returns the Bhattacharyya distance between two patterns
               \note Returns std::numeric_limits< double >::max() on errors.
             */
            double getBhattacharyyaDistance(Pattern const * const p) const;

            /*! \brief Return true if two clusters are equal. */
            bool operator==( const Pattern& rhs) const;

            // overload
            Pattern& operator=( const Pattern& rhs );

            // overload (by m_area comparison)
            bool operator<(const Pattern& rhs) const;

            /*!
              \brief Reset to initial state.
            */
            void reset();

            int m_id;                                                     //!< The id of the region of the pattern.
            Pattern* m_myCluster;                                         //!< The associated cluster of this pattern (optional).
            double m_area;                                                //!< The area of all regions inside a pattern.
            double m_covarianceMatrixDet;     //!< The covariance matrix determinant.
            std::vector<double> m_meanVector;                             //!< The vector of mean values, 1 value per band;
            boost::numeric::ublas::matrix<double> m_covarianceMatrix;     //!< The covariance matrix between bands.
            boost::numeric::ublas::matrix<double> m_covarianceInversion;  //!< The inversion of covariance matrix between bands.

          protected :

            // Variables used by the getBhattacharyyaDistance method
            mutable unsigned int m_getBhattacharyyaDistance_nBands;
            mutable unsigned int m_getBhattacharyyaDistance_bandIdx;
            mutable double m_getBhattacharyyaDistance_covsMegeDet;
            mutable double m_getBhattacharyyaDistance_distanceValue;
            mutable boost::numeric::ublas::matrix<double> m_getBhattacharyyaDistance_meansDif;
            mutable boost::numeric::ublas::matrix<double> m_getBhattacharyyaDistance_covsMege;
            mutable boost::numeric::ublas::matrix<double> m_getBhattacharyyaDistance_covsMegeInv;
            mutable boost::numeric::ublas::matrix<double> m_getBhattacharyyaDistance_distanceTerm1;
        };

          /*!
          \brief The parameters passed to the fill regions thread entry.
        */
        class FillRegionsThreadEntryParams
        {
          public :
            //! Pointer to the mutex.
            std::mutex* m_globalMutexPtr;

            //! Pointer to the condition variable mutex.
            std::mutex* m_condVarMutexPtr;

            //! Pointer to the condition variable.
            std::condition_variable* m_condVarPtr;

            //! Pointer to the input raster sync.
            te::rst::RasterSynchronizer* m_inputRasterSyncPtr;

            std::vector<te::gm::Polygon*> const * m_inputPolygonsPtr;

            //! Pointer to the input raster bands do be processed.
            std::vector< unsigned int > const * m_inputRasterBandsPtr;

            //! Pointer to the output regions container.
            std::multimap< double, Pattern >* m_outputRegionsPtr;

            //! Pointer to variable pointing the next polygon index to process.
            std::size_t* m_nextInputPolIdx2ProcessPtr;

            //! Pointer to variable pointing the current number of running threads.
            unsigned int* m_runningThreadsCounterPtr;

            //! Pointer to variable pointing the variable to enable or disable the thread internal progress interface.
            bool m_enableProgress;

            //! Pointer to variable pointing the variable to allow the process to continue.
            bool *m_continueProcessingFlagPtr;

            FillRegionsThreadEntryParams() {};

            ~FillRegionsThreadEntryParams() {};
        };

        bool m_isInitialized;                                             //!< True if this instance is initialized.
        ClassifierISOSegStrategy::Parameters m_parameters;                //!< Internal execution parameters.

        double getThreshold(const double acceptanceThreshold, const unsigned nBands) const;

        /*!
          \brief Fill regions thread entry.
          \param paramsPtr A pointer to the thread parameters.
          \note Regions with non-invertable covariance matrix will have zero determinants
          \note Regions IDs have the same value as the input polygons indexes
        */
        static void fillRegionsThreadEntry(FillRegionsThreadEntryParams* paramsPtr);

        /*!
          \brief Print a matrix to std::out.
        */
        static void printMatrix(const boost::numeric::ublas::matrix<double>& matrix);
    };

    /*!
      \class ClassifierISOSegStrategyFactory

      \brief Raster ISOSeg Classifier strategy factory.

      \note Factory key: RegionGrowing
    */
    class TERPEXPORT ClassifierISOSegStrategyFactory : public ClassifierStrategyFactory
    {
      public:

        ClassifierISOSegStrategyFactory();

        ~ClassifierISOSegStrategyFactory();

        //overload
        te::rp::ClassifierStrategy* build();
    };

  } // end namespace rp
}   // end namespace te

#endif // __TERRALIB_RP_INTERNAL_CLASSIFIERISOSEGSTRATEGY_H