MaxLikelihood.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/classification/MaxLikelihood.h

  \brief A maximum likelihood estimation strategy for classification (a.k.a. MaxVer in portuguese).
*/

#ifndef __TERRALIB_CLASSIFICATION_INTERNAL_MAXLIKELIHOOD_H
#define __TERRALIB_CLASSIFICATION_INTERNAL_MAXLIKELIHOOD_H

// TerraLib
#include "../common/AbstractParameters.h"
#include "../common/MatrixUtils.h"
#include "../common/progress/TaskProgress.h"
#include "Adaptors.h"
#include "Config.h"
#include "Exception.h"

// STL
#include <vector>
#include <memory>

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

namespace te
{
  namespace cl
  {
    /*!
      \class MaxLikelihood
      \brief A maximum likelihood estimation strategy for classification (a.k.a. MaxVer in portuguese).
      \note Reference: Erthal, G.J.; Frery, A.C. Segmentação de imagens multiespectrais pelo algoritmo ICM:integração ao ambiente SPRING. In: Simpósio Brasileiro de Computação Gráfica eProcessamento de Imagens-SIBGRAP, 6., Recife, 1993. Comunicações. Recife:SBC/UFPe, 1993. p. 33-36.

    */

    class TECLEXPORT MaxLikelihood
    {
      public:

        /*!
          \class Parameters
          \brief Classifier Parameters
        */
        class TECLEXPORT Parameters : public te::common::AbstractParameters
        {
          public:

            Parameters();

            ~Parameters();

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

            //overload
            void reset();

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

      public:

        MaxLikelihood();

        ~MaxLikelihood();

        /*!
          \brief Initialize this classifier instance with new parameters.
          \param params New initialization parameters.
        */
        bool initialize(const Parameters& params);

        /*!
          \brief Train this classifier instance using the initialization parameters and the suppied train data.
          \param samples Train data samples.
          \param attributesIndices The attributes indexes to processe from the iterated train data.
          \param sampleLabels The sample lables for each iterated train data element.
          \param enableProgressInterface Enable/disable the use of a proress interfece.
        */
        bool train( const InputAdaptor< double >& samples,
                   const std::vector<unsigned int>& attributesIndices,
                   const std::vector<unsigned int>& sampleLabels,
                   const bool enableProgressInterface);

        /*!
          \brief Classify an input iterated data and save the result on the output iterated data.
          \param input Input data to be classified.
          \param attributesIndices The attributes indexes to processe from the iterated train data.
          \param inputNoDataValues A vector of no-data values for each attribute dimension or an empty vector if no-data values are not used.
          \param output Output classified data.
          \param outputIndex The output attribute index.
          \param outputNoDataValue A output label value to use when dealing with input no-data.
          \param enableProgressInterface Enable/disable the use of a proress interfece.
        */
        bool classify( const InputAdaptor< double >& input,
                      const std::vector<unsigned int>& attributesIndices,
                      const std::vector< double >& inputNoDataValues,
                      OutputAdaptor< unsigned int >& output,
                      const unsigned int outputIndex,
                      const unsigned int outputNoDataValue,
                      const bool enableProgressInterface);
        
        /*!
          \brief Get the current classes covariance matrixes.
          \param covMatrixes A vector to return the current classes covariance matrixes.
          \return true if ok, false on errors.
        */
        bool getCovMatrixes(  std::vector< boost::numeric::ublas::matrix< double > >& covMatrixes ) const;
        
        /*!
          \brief Get the current classes inverse covariance matrixes.
          \param invCovMatrixes A vector to return the current classes inverse covariance matrixes.
          \return true if ok, false on errors.
        */
        bool getInverseCovMatrixes(  std::vector< boost::numeric::ublas::matrix< double > >& invCovMatrixes ) const;        
        
        /*!
          \brief Get the current classes means.
          \param classesMeans A vector to return the current classes means.
          \return true if ok, false on errors.
        */
        bool getMeans( std::vector< std::vector< double > >& classesMeans ) const;
        
        /*!
          \brief Get the current classes labels.
          \param classesMeans A vector to return the current classes labels.
          \return true if ok, false on errors.
        */
        bool getLables( std::vector<unsigned int>& classLabels ) const;        

      protected:

        bool m_isInitialized;                              //!< True if this instance is initialized.
        Parameters m_parameters;                           //!< Internal execution parameters.
        std::vector< std::vector< double > > m_classesMeans; //!< Classes means;
        std::vector< boost::numeric::ublas::matrix< double > > m_classesCovarianceMatrixes; //!< Classes covariance matrixes.
        std::vector< boost::numeric::ublas::matrix< double > > m_classesCovarianceInvMatrixes; //!< Classes covariance inverse matrixes.
        std::vector<unsigned int> m_classLabels; //!< class labels
        std::vector< double > m_classesOptizedMaxLikelihoodDiscriminantTerm;  //!< An optimized portion of the MaxLikelihood discriminant function.

        /*! \brief Reset this instance to its initial state */
        void reset();

    };
  } // end namespace cl
}  // end namespace te

#endif // __TERRALIB_CLASSIFICATION_INTERNAL_MAXLIKELIHOOD_H