GeometryFunctions.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/GeometryFunctions.h

  \brief A list of common used Geometry functions for the Geometry Module.
*/

#ifndef __TERRALIB_GEOMETRY_INTERNAL_GEOMETRYFUNCTIONS_H
#define __TERRALIB_GEOMETRY_INTERNAL_GEOMETRYFUNCTIONS_H

// TerraLib
#include "Config.h"
#include "CommonDataStructures.h"
#include "Point.h"

#include <vector>

namespace te
{
  namespace gm
  {
// Forward declarations
    struct Coord2D;
    class Envelope;
    class Geometry;
    class LineString;
    class Point;
   
    class TEGEOMEXPORT Distance
    {

    public:

      /*!
      \brief Checks if a coordinate (x1, x2) is exactly equal to the coordinate (x2, y2)

      \param x1   The X of the first coordinate
      \param y1   The Y of the first coordinate
      \param x2   The X of the second coordinate
      \param y2   The Y of the second coordinate

      \return TRUE if the points are equal. FALSE otherwise
      */
      static bool IsEqual(double x1, double y1, double x2, double y2);

      /*!
      \brief Checks if a coordinate c1 is exactly equal to the coordinate c2

      \param c1   The first coordinate
      \param c2   The second coordinate

      \return TRUE if the points are equal. FALSE otherwise
      */
      static bool IsEqual(const te::gm::Coord2D& c1, const te::gm::Coord2D& c2);

      /*!
      \brief Checks if a point p1 is exactly equal to the point p2

      \param p1   The first point
      \param p2   The second point

      \return TRUE if the points are equal. FALSE otherwise
      */
      static bool IsEqual(const te::gm::Point& p1, const te::gm::Point& p2);

      /*!
      \brief Calculates the distance between c1 and c2

      \param c1   The first coordinate
      \param c2   The second coordinate

      \return The distance between the given coordinates
      */
      static double CalculateDistance(const te::gm::Coord2D& c1, const te::gm::Coord2D& c2);

      /*!
      \brief Calculates the squared distance between c1 and c2, that is, the distance calculation without the final square root step. This is particularly useful when we just need to compare distance values, and not know the distance itself.

      \param c1   The first coordinate
      \param c2   The second coordinate

      \return The squared distance between the given coordinates
      */
      static double CalculateSquaredDistance(const te::gm::Coord2D& c1, const te::gm::Coord2D& c2);

      /*!
      \brief Calculates the squared distance between p1 and p2, that is, the distance calculation without the final square root step. This is particularly useful when we just need to compare distance values, and not know the distance itself.

      \param c1   The first point
      \param c2   The second point

      \return The squared distance between the given coordinates
      */
      static double CalculateSquaredDistance(const te::gm::Point& p1, const te::gm::Point& p2);

      /*!
      \brief Checks in an optimized way if the given coordinates are within the given distance. The optimization is achieved by avoiding the calculation of the square root

      \param c1   The first coordinate
      \param c2   The second coordinate
      \param distance   The distance to be considered

      \return TRUE if the coordinates are within the given distance. FALSE otherwise
      */
      static bool IsWithinDistance(const te::gm::Coord2D& c1, const te::gm::Coord2D& c2, double distance);

      /*!
      \brief Checks in an optimized way if the given coordinates are within the given distance. The optimization is achieved by avoiding the calculation of the square root

      \param p1   The first point
      \param p2   The second point
      \param distance   The distance to be considered

      \return TRUE if the coordinates are within the given distance. FALSE otherwise
      */
      static bool IsWithinDistance(const te::gm::Point& p1, const te::gm::Point& p2, double distance);

      /*!
      \brief Checks if the given coordToCheck lies within the line

      \param coordToCheck The coordinate to be checked
      \param c1 First coordinate of the line segment
      \param c2 Last coordinate of the line segment
      \return TRUE if the coordinate lies within the segment. FALSE otherwise
      */
      static bool IsOnLine(const te::gm::Coord2D& coordToCheck, const te::gm::Coord2D& c1, const te::gm::Coord2D& c2);

      /*!
      \brief Calculate the perpendicular squared  distance of a point in a segment.

      \param first The first segment coordinate.
      \param last The last segment coordinate.
      \param pin The coordinate to be calculated.
      \param pinter A intern coordinate calculated based on pin projected intersection with the segment.

      \return The perpendicular distance.
      */
      static double PerpendicularSquaredDistance(const te::gm::Coord2D& first, const te::gm::Coord2D& last, const te::gm::Coord2D& pin, te::gm::Coord2D& projectedCoordinate, bool& isOnSegment);

      /*!
      \brief Calculate the perpendicular squared distance of a point in a segment.

      \param first The first segment point.
      \param last The last segment point.
      \param pin The point to be calculated.
      \param pinter A intern point calculated based on pin projected intersection with the segment.

      \return The perpendicular distance.
      */
      static double PerpendicularSquaredDistance(const te::gm::Point& first, const te::gm::Point& last, const te::gm::Point& pin, Point& projectedPoint, bool& isOnSegment);

      /*!
      \brief Calculate the perpendicular distance of a point in a segment.

      \param first The first segment coordinate.
      \param last The last segment coordinate.
      \param pin The coordinate to be calculated.
      \param pinter A intern coordinate calculated based on pin projected intersection with the segment.

      \return The perpendicular distance.
      */
      static double PerpendicularDistance(const te::gm::Coord2D& first, const te::gm::Coord2D& last, const te::gm::Coord2D& pin, te::gm::Coord2D& projectedCoordinate, bool& isOnSegment);

      /*!
      \brief Calculate the perpendicular distance of a point in a segment.

      \param first The first segment point.
      \param last The last segment point.
      \param pin The point to be calculated.
      \param pinter A intern point calculated based on pin projected intersection with the segment.

      \return The perpendicular distance.
      */
      static double PerpendicularDistance(const te::gm::Point& first, const te::gm::Point& last, const te::gm::Point& pin, te::gm::Point& projectedPoint, bool& isOnSegment);

      /*!
      \brief Detects and adds all the coordinates from given geometryVector which projected coordinates lies within any segment of the geometries and is within the given 'distance'

      \param geometryVector The geometryVector to be processed.
      \param distance The distance to be considered for the projected coordinates

      \return The processed geometryVector
      */
      static te::gm::GeometryVector AddProjectedCoordinates(const te::gm::GeometryVectorConst& geometryVector, double distance, bool& wasChanged);
    };

    class TEGEOMEXPORT SpatialIndex
    {
    public:

      static void getCoordinates(const te::gm::Geometry* geometry, std::vector<te::gm::Coord2D>& vecCoords);
      static void populateCoordinateIndex(const te::gm::Geometry* geometry, te::gm::KdTreeSingle& spatialIndex);
      static void populateCoordinateIndex(const te::gm::GeometryVectorConst& geometryVector, te::gm::KdTreeSingle& spatialIndex);

    protected:

      static void buildIndex(const std::vector<te::gm::Coord2D>& vecCoords, te::gm::KdTreeSingle& spatialIndex);
    };

    /*!
      \struct CoordDistanceOrderFunctor

      \brief This local struct is used sorts a vector of coordinates by distance.
      */
    struct CoordDistanceOrderFunctor
    {
      te::gm::Coord2D m_reference;

      CoordDistanceOrderFunctor(const te::gm::Coord2D& reference)
        : m_reference(reference)
      {
      }

      bool operator()(const te::gm::Coord2D& c1, const te::gm::Coord2D& c2) const
      {
        double distance1 = te::gm::Distance::CalculateSquaredDistance(m_reference, c1);
        double distance2 = te::gm::Distance::CalculateSquaredDistance(m_reference, c2);

        if (distance1 < distance2)
          return true;

        return false;
      }
    };

    /*!
      \struct PointDistanceOrderFunctor

      \brief This local struct is used sorts a vector of points by distance.
      */
    struct PointDistanceOrderFunctor
    {
      te::gm::Point m_reference;

      PointDistanceOrderFunctor(const te::gm::Point& reference)
        : m_reference(reference)
      {

      }

      bool operator()(const te::gm::Point& p1, const te::gm::Point& p2) const
      {
        double distance1 = te::gm::Distance::CalculateSquaredDistance(m_reference, p1);
        double distance2 = te::gm::Distance::CalculateSquaredDistance(m_reference, p2);

        if (distance1 < distance2)
          return true;

        return false;
      }
    };


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

#endif  // __TERRALIB_GEOMETRY_INTERNAL_GEOMETRYFUNCTIONS_H