GeometricTransformation.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/GeometricTransformation.h
 
  \brief 2D Geometric transformation base class.
*/
 
#ifndef __TERRALIB_GEOMETRY_INTERNAL_GEOMETRICTRANSFORMATION_H
#define __TERRALIB_GEOMETRY_INTERNAL_GEOMETRICTRANSFORMATION_H
 
// TerraLib
#include "Config.h"
#include "GTParameters.h"
 
// STL
#include <cassert>
 
// Boost
#include <boost/noncopyable.hpp>
 
namespace te
{
  namespace gm
  {
// Forward declaration
    class GTFilter;
    class GTParameters;
 
    struct Coord2D;
 
    /*!
      \class GeometricTransformation
 
      \brief 2D Geometric transformation base class.
 
      \ingroup geometry
    */
    class TEGEOMEXPORT GeometricTransformation : public boost::noncopyable
    {
      friend class GTFilter;
 
      public:
 
        /*! \brief Virtual destructor. */
        virtual ~GeometricTransformation();
 
        /*!
          \brief Returns the current transformation name.
 
          \return The current transformation name.
        */
        virtual const std::string& getName() const = 0;
 
        /*!
          \brief Verifies if the supplied parameters already has a valid transformation.
 
          \param params Transformation parameters.
 
          \return true if a transformation is already defined, false otherwise.
        */
        virtual bool isValid(const GTParameters& params) const = 0;
 
        /*!
          \brief Tells if the current instance has a valid transformation.
 
          \return true if a transformation is already defined, false otherwise.
        */
        bool isValid() const
        {
          return isValid(m_internalParameters);
        }
 
        /*!
          \brief Initialize the current transformation following the new supplied parameters.
 
          \param newparams The new parameters.
 
          \return true if OK, false on errors.
        */
        bool initialize(const GTParameters& newParameters);
 
        /*!
          \brief Returns a reference of the current internal transformation parameters.
          
          \return A reference of the current internal transformation parameters.
        */
        const GTParameters& getParameters() const
        {
          return m_internalParameters;
        }
 
        /*!
          \brief Direct mapping (from pt1 space into pt2 space).
 
          \param params Transformation parameters.
          \param pt1X   pt1 X coordinate.
          \param pt1Y   pt1 Y coordinate.
          \param pt2X   pt2 X coordinate.
          \param pt2Y   pt2 Y coordinate.
        */
        virtual void directMap(const GTParameters& params,
                               const double& pt1X,
                               const double& pt1Y,
                               double& pt2X,
                               double& pt2Y) const = 0;
 
        /*!
          \brief Direct mapping ( from pt1 space into pt2 space ).
 
          \param pt1X pt1 X coordinate.
          \param pt1Y pt1 Y coordinate.
          \param pt2X pt2 X coordinate.
          \param pt2Y pt2 Y coordinate.
        */
        void directMap(const double& pt1X,
                       const double& pt1Y,
                       double& pt2X,
                       double& pt2Y) const
        {
          assert(isValid(m_internalParameters));
 
          directMap(m_internalParameters, pt1X, pt1Y, pt2X, pt2Y);
        }
 
        /*!
          \brief Direct mapping (from pt1 space into pt2 space).
 
          \param params Transformation parameters.
          \param pt1    pt1 coordinate.
          \param pt2    pt2 coordinate.
        */
        void directMap(const GTParameters& params, const Coord2D& pt1, Coord2D& pt2) const
        {
          directMap(params, pt1.x, pt1.y, pt2.x, pt2.y);
        }
 
        /*!
          \brief Direct mapping (from pt1 space into pt2 space).
 
          \param pt1 pt1 coordinate.
          \param pt2 pt2 coordinate.
        */
        void directMap(const Coord2D& pt1, Coord2D& pt2) const
        {
          assert(isValid(m_internalParameters));
 
          directMap(m_internalParameters, pt1.x, pt1.y, pt2.x, pt2.y);
        }
 
        /*!
          \brief Inverse mapping (from pt2 space into pt1 space).
 
          \param params Transformation parameters.
          \param pt1X pt1 X coordinate.
          \param pt1Y pt1 Y coordinate.
          \param pt2X pt2 X coordinate.
          \param pt2Y pt2 Y coordinate.
        */
        virtual void inverseMap(const GTParameters& params,
                                const double& pt2X,
                                const double& pt2Y,
                                double& pt1X,
                                double& pt1Y) const = 0;
 
        /*!
          \brief Inverse mapping (from pt2 space into pt1 space).
 
          \param pt1X pt1 X coordinate.
          \param pt1Y pt1 Y coordinate.
          \param pt2X pt2 X coordinate.
          \param pt2Y pt2 Y coordinate.
        */
        void inverseMap(const double& pt2X,
                        const double& pt2Y,
                        double& pt1X,
                        double& pt1Y) const
        {
          assert(isValid(m_internalParameters));
 
          inverseMap(m_internalParameters, pt2X, pt2Y, pt1X, pt1Y);
        }
 
        /*!
          \brief Inverse mapping ( from pt2 space into pt1 space ).
 
          \param params Transformation parameters.
          \param pt2    pt2 coordinate.
          \param pt1    pt1 coordinate.
        */
        void inverseMap(const GTParameters& params, const Coord2D& pt2, Coord2D& pt1) const
        {
          inverseMap(params, pt2.x, pt2.y, pt1.x, pt1.y);
        }
 
        /*!
          \brief Inverse mapping (from pt2 space into pt1 space).
 
          \param pt2 pt2 coordinate.
          \param pt1 pt1 coordinate.
        */
        void inverseMap(const Coord2D& pt2, Coord2D& pt1) const
        {
          assert(isValid(m_internalParameters));
 
          inverseMap(m_internalParameters, pt2.x, pt2.y, pt1.x, pt1.y);
        }
 
        /*!
          \brief Calculates maximum direct mapping error for the supplied parameters.
 
          \param params Transformation parameters.
 
          \return The maximum direct mapping error for the supplied parameters.
        */
        double getMaxDirectMappingError(const GTParameters& params) const;
 
        /*!
          \brief Calculates the current transformation maximum direct mapping error.
 
          \return The current maximum direct mapping error.
        */
        double getMaxDirectMappingError() const
        {
          return getMaxDirectMappingError(m_internalParameters);
        }
 
        /*!
          \brief Calculates maximum inverse mapping error for the supplied parameters.
 
          \param params Transformation parameters.
 
          \return The maximum inverse mapping error for the supplied parameters.
        */
        double getMaxInverseMappingError(const GTParameters& params) const;
 
        /*!
          \brief Calculates the current transformation maximum inverse mapping error.
 
          \return The current maximum inverse mapping error.
        */
        double getMaxInverseMappingError() const
        {
          return getMaxInverseMappingError( m_internalParameters );
        }
        
        /*!
          \brief Calculates root mean square direct mapping error for the supplied tie-points using the supplied parameters.
          
          \param tiePoints The tie-points.
 
          \param params Transformation parameters.
 
          \return The root mean square error.
        */
        double getDirectMapRMSE( const std::vector< GTParameters::TiePoint >& tiePoints, 
          const GTParameters& params ) const;        
 
        /*!
          \brief Calculates root mean square direct mapping error for the supplied parameters.
 
          \param params Transformation parameters.
 
          \return The root mean square error.
        */
        double getDirectMapRMSE( const GTParameters& params ) const
        {
          return getDirectMapRMSE( params.m_tiePoints, params );
        }
        
        /*!
          \brief Calculates root mean square direct mapping error for the supplied tie-points.
          
          \param tiePoints The tie-points.
 
          \return The root mean square error.
        */
        double getDirectMapRMSE( const std::vector< GTParameters::TiePoint >& tiePoints ) const
        {
          return getDirectMapRMSE( tiePoints, m_internalParameters );
        }
 
        /*!
          \brief Calculates root mean square direct mapping error.
 
          \return The root mean square error.
        */
        double getDirectMapRMSE() const
        {
          return getDirectMapRMSE( m_internalParameters );
        }
        
        /*!
          \brief Calculates root mean square inverse mapping error for the supplied tie-points using the supplied parameters.
          
          \param tiePoints The tie-points.
 
          \param params Transformation parameters.
 
          \return The root mean square error.
        */
        double getInverseMapRMSE( const std::vector< GTParameters::TiePoint >& tiePoints,
          const GTParameters& params ) const;        
 
        /*!
          \brief Calculates root mean square inverse mapping error for the supplied parameters.
 
          \param params Transformation parameters.
 
          \return The root mean square error.
        */
        double getInverseMapRMSE( const GTParameters& params ) const
        {
          return getInverseMapRMSE( params.m_tiePoints, params );
        }
        
        /*!
          \brief Calculates root mean square inverse mapping error for the supplied tie-points.
          
          \param tiePoints The tie-points.
 
          \return The root mean square error.
        */
        double getInverseMapRMSE( const std::vector< GTParameters::TiePoint >& tiePoints ) const
        {
          return getInverseMapRMSE( tiePoints, m_internalParameters );
        }
 
        /*!
          \brief Calculates root mean square inverse mapping error.
 
          \return The root mean square error.
        */
        double getInverseMapRMSE() const
        {
          return getInverseMapRMSE( m_internalParameters );
        }
 
        /*!
          \brief Calculates the direct mapping error for the supplied tie-point.
 
          \param tiePoint The tie-point.
 
          \param params Transformation parameters.
 
          \return The current maximum direct mapping error.
        */
        double getDirectMappingError(const GTParameters::TiePoint& tiePoint, const GTParameters& params) const;
 
        /*!
          \brief Calculates the direct mapping error for the supplied tie-point.
 
          \param tiePoint The tie-point.
 
          \return The current direct mapping error.
        */
        double getDirectMappingError( const GTParameters::TiePoint& tiePoint ) const
        {
          return getDirectMappingError( tiePoint, m_internalParameters );
        }
 
        /*!
          \brief Calculates the inverse mapping error for the supplied tie-point.
 
          \param tiePoint The tie-point.
 
          \param params Transformation parameters.
 
          \return The current maximum inverse mapping error.
        */
        double getInverseMappingError( const GTParameters::TiePoint& tiePoint, const GTParameters& params ) const;
 
        /*!
          \brief Calculates the inverse mapping error for the supplied tie-point.
 
          \param tiePoint The tie-point.
 
          \return The current inverse mapping error.
        */
        double getInverseMappingError( const GTParameters::TiePoint& tiePoint ) const
        {
          return getInverseMappingError( tiePoint, m_internalParameters );
        }
 
        /*!
          \brief Returns the minimum number of required tie-points for the current transformation.
 
          \return The minimum number of required tie-points for the current transformation.
        */
        virtual unsigned int getMinRequiredTiePoints() const = 0;
 
        /*!
          \brief Creat a clone copy of this instance.
          
          \return A clone copy of this instance (the caller of this method must take the ownership of the returned object and delete it when appropriate.
        */
        virtual GeometricTransformation* clone() const = 0;
 
      protected:
 
        /*! \brief Default constructor. */
        GeometricTransformation();
 
        /*!
          \brief Calculate the transformation parameters following the new supplied tie-points.
 
          \param params Transformation parameters.
 
          \return true if OK, false on errors.
        */
        virtual bool computeParameters( GTParameters& params ) const = 0;
 
      protected:
 
        GTParameters m_internalParameters;  //!< The current internal parameters.
    };
 
  } // end namespace gm
}   // end namespace te
 
#endif  // __TERRALIB_GEOMETRY_INTERNAL_GEOMETRICTRANSFORMATION_H