GTFilter.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/geometry/GTFilter.h

  \brief 2D Geometric transformation outliers remotion filter.
*/

#ifndef __TERRALIB_GEOMETRY_INTERNAL_GTFILTER_H
#define __TERRALIB_GEOMETRY_INTERNAL_GTFILTER_H

// TerraLib
#include "Config.h"
#include "GTParameters.h"
#include "GeometricTransformation.h"

// STL
#include <map>
#include <memory>
#include <vector>
#include <thread>
#include <mutex>

namespace te
{
  namespace gm
  {
    /*!
      \class GTFilter
      
      \brief 2D Geometric transformation tie-points filter (outliers remotion).
    */
    class TEGEOMEXPORT GTFilter
    {
      public:
        
        /*! \brief RANSAC integer counter type. */
        typedef unsigned long int RansacIntegerCounterT;
        
        /*! \brief RANSAC floating point counter type. */
        typedef long double RansacFloatCounterT;

        /*!
          \enum RansacAreaRestrictionType
          \brief Spatial relations between geometric objects.
        */
        enum RANSACAreaRestrictionType
        {
          RANSAC_NO_AREA_REST = 0,  /*!< No area restriction. */
          RANSAC_BBOX_AREA_REST = 1,  /*!< Preference will be given to tie-points groups with bigger bounding-box areas. */
          RANSAC_CHULL_AREA_REST = 2  /*!< Preference will be given to tie-points groups with bigger convex hull areas. */
        };

        /*! \brief Default constructor. */
        GTFilter();

        /*! \brief Destructor. */
        ~GTFilter();

        /*!
          \brief Apply a RANSAC based outliers remotion strategy.

          \param transfName             Transformation name (see te::gm::GTFactory dictionary for reference).
          \param inputParams            Input transformation parameters.
          \param allowedMaxDirectMapError      The maximum allowed direct mapping error.
          \param allowedMaxInverseMapError     The maximum allowed inverse mapping error.
          \param maxIterations          The maximum number of iterations (Use 0-zero to let this number be automatically found).
          \param enableMultiThread      Enable multi-threaded processing (good for multi-processor or multi-core systems).
          \param outTransf              The generated output transformation (with the base mininum required tie-points set).
          \param tiePointsWeights       Optional tie-points weights (only positive values) or an empty vector if no weights must be used.
          \param outTiePoints           The filtered output tie-points (non-outliers) in agreenment with the generated transformation.
          \param areaRestT              RANSAC area restriction type.

          \return true if OK, false on errors.

          \note Reference: Martin A. Fischler and Robert C. Bolles, Random Sample Consensus: A Paradigm for Model Fitting with Applications to Image Analysis and Automated Cartography, Communications of the ACM archive, Volume 24, Issue 6 (June 1981).
        */
        bool applyRansac(const std::string& transfName,
                         const GTParameters& inputParams,
                         const double allowedMaxDirectMapError,
                         const double allowedMaxInverseMapError,
                         const RansacIntegerCounterT& maxIterations,
                         const bool enableMultiThread,
                         const RANSACAreaRestrictionType areaRestT,
                         const std::vector< double >& tiePointsWeights,
                         std::vector< te::gm::GTParameters::TiePoint >& outTiePoints,
                         std::unique_ptr< GeometricTransformation >& outTransf
                         );

      protected:

        /*!
          \class RansacSetData

          \brief Parameters used by the GTFilter::applyRansacThreadEntry method.
        */
        class RansacSetData
        {
          public:

            double m_maxDirectMapError;
            double m_maxInverseMapError;
            double m_area1;
            double m_area2;
            GTParameters m_transformationParams;
            std::vector< te::gm::GTParameters::TiePoint > m_tiePoins;

            RansacSetData();
            ~RansacSetData();
        };

        /*!
          \class ApplyRansacThreadEntryThreadParams

          \brief Parameters used by the GTFilter::applyRansacThreadEntry method.
        */
        class ApplyRansacThreadEntryThreadParams
        {
          public:

            std::string m_transfName;
            GTParameters const* m_inputGTParamsPtr;
            double m_allowedMaxDirectMapError;
            double m_allowedMaxInverseMapError;
            bool m_useDynamicIterationsNumber;
            RansacIntegerCounterT* m_dynamicMaxIterationsPtr;
            RansacIntegerCounterT* m_dynamicMaxConsLowQualityIterationsPtr;
            RansacIntegerCounterT* m_dynamicMaxConsInvalidIterationsPtr;
            RansacIntegerCounterT m_procsNumber;
            bool* m_returnValuePtr;
            std::mutex* m_mutexPtr;
            bool* m_keepRunningFlagPtr;
            std::map< double, GTParameters::TiePoint > const* m_tpsMapPtr; //!< A map from accumulated probabilities (normalized between 0 and 1) to tie-points data.
            RansacSetData* m_bestSetDataPtr;
            double* m_maxFoundGlobalItDMapErrorPtr;
            double* m_maxFoundGlobalItIMapErrorPtr;
            RANSACAreaRestrictionType m_areaRestT;
            RansacIntegerCounterT* m_globalIterationsCounterPtr;
            RansacIntegerCounterT* m_globalConsecutiveLowQualitySetsCounterPtr;
            RansacIntegerCounterT* m_globalConsInvalidIterationsCounterPtr;

            ApplyRansacThreadEntryThreadParams();

            ~ApplyRansacThreadEntryThreadParams();

          private :

            ApplyRansacThreadEntryThreadParams( const ApplyRansacThreadEntryThreadParams& other );

            const ApplyRansacThreadEntryThreadParams& operator=(
              const ApplyRansacThreadEntryThreadParams& other );
        };

        /*!
          \brief Returns the tie-points convex hull area.
          \param area1 GTParameters::TiePoint::first area.
          \param area2 GTParameters::TiePoint::second area.
          \param tiePoints Tie points.
        */
        static void getTPsConvexHullArea(
          const std::vector<GTParameters::TiePoint>& tiePoints,
          double& area1, double& area2 );

        /*! 
          \brief Surf locator thread entry.

          \param paramsPtr A pointer to the thread parameters.
        */
        static void applyRansacThreadEntry(te::gm::GTFilter::ApplyRansacThreadEntryThreadParams* paramsPtr);

        /*!
          \brief Returns the number of expected iterations to be performed.
          \param goodTPNumber Number of good tie-points.
          \param totalTPNumber Total number of tie-points.
          \param modelRequiredTPNumber Model minimum required tie-points.
          \return The number of expected iterations to be performed.
        */
        static RansacIntegerCounterT getExcpectedIterationsNumber(
          const unsigned int goodTPNumber,
          const unsigned int totalTPNumber,
          const unsigned int modelRequiredTPNumber );

    };

  } // end namespace gm
}   // end namespace te

#endif  // __TERRALIB_GEOMETRY_INTERNAL_GTFILTER_H