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

  \brief Utility functions for the Geometry Module.
*/

#ifndef __TERRALIB_GEOMETRY_INTERNAL_GEOMUTILS_H
#define __TERRALIB_GEOMETRY_INTERNAL_GEOMUTILS_H

// TerraLib
#include "../sam/rtree.h"
#include "Config.h"
#include "Coord2D.h"
#include "Enums.h"
#include "Point.h"

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

namespace te
{
  namespace gm
  {
// Forward declarations
    class Envelope;
    class Geometry;
    class Polygon;
    class LineString;
    class Line;
    
    /*!
    \struct TopologyValidationError

    \brief This struct contains informations about GEOS TopologyValidationError
    */
    struct TopologyValidationError
    {
      public:

        Coord2D     m_coordinate;
        std::string m_message;
    };

    /*!
    \struct DistanceOrderFunctor

    \brief This struct is used sorts a vector of points by distance.
    */
    struct DistanceOrderFunctor
    {
      te::gm::Point _reference;
      DistanceOrderFunctor(const te::gm::Point& reference)
      {
        _reference = reference;
      }

      bool operator()(const te::gm::Point& p1, const te::gm::Point& p2) const
      {
        double distance1 = p1.distance(&_reference);
        double distance2 = p2.distance(&_reference);

        if (distance1 < distance2)
          return true;

        return false;
      }
    };

    /*!
      \brief It returns the number of measurements or axes needed to describe a position in a coordinate system.

      It returns:
      <ul>
      <li>2 for a coordinate with x, y;</li>
      <li>3 for a coordinate with x, y and z or x, y and m;</li>
      <li>4 for a coordinate with x, y, z and m.</li>
      </ul>

      \param t The geomeytric type.

      \return The number of measurements or axes needed to describe a position in a coordinate system.
    */
    inline int GetCoordDimension(GeomType t)
    {
      if(t & 0x100)   // may be z (0x300), m (0x700) or zm (0x800)
      {
        if(t & 0x800) // it must be zm
          return 4;

        return 3; // it can be z (gType & 0x300) or m (gType & 0x700)
      }

      return 2;
    }

    /*!
      \brief It creates a Geometry (a polygon) from the given envelope.

      \param e    The envelope to extract the coordinates. Don't call with a NULL envelope.
      \param srid The Spatial Reference System ID to be associated to the polygon.

      \return A polygon (in counter-clock-wise) with rectangle coordinates: [(MINX, MINY), (MAXX, MINY), (MAXX, MAXY), (MINX, MAXY), (MINX, MINY)].

      \note The caller of this method will take the ownership of the returned geometry.
    */
    TEGEOMEXPORT Geometry* GetGeomFromEnvelope(const Envelope* const e, int srid);

    /*!
      \brief It returns the union of a geometry vector.

      \param items  Vector of itens that represents a group.

      \return Union of the geometry.
    */
    TEGEOMEXPORT std::unique_ptr<te::gm::Geometry> GetGeometryUnion(const std::vector<te::gm::Geometry*>& geomVec);
    
    /*!
      \brief It returns if two geometries satisfy a given spatial relation.
     
      \param g1 The first geometry
      \param g2 The second geometry
      \param r  A given spatial relation to be tested
      
      \return It returns true if the given two geometries satisfy the spatial relation. Otherwise, it returns false.  

      \exception Exception It throws an exception if the spatial relation is not valid or if the test can not be evaluated.
    */
    TEGEOMEXPORT bool SatisfySpatialRelation(const Geometry* g1, const Geometry* g2, SpatialRelation relation);

    /*!
      \brief  Finds the correspondent smallest box that allows a box to be cut in blocks of a given size
     
      \param env     Reference envelope
      \param bWidth  Block width
      \param bHeight Block height
      
      \return It returns a adjusted envelope
    */
    TEGEOMEXPORT Envelope AdjustToCut(const Envelope & env, double bWidth, double bHeight);

    /* \brief It checks if one object intersects another object. */
    template<class T1, class T2> bool Intersects(const T1& o1, const T2& o2);

    /* \brief Specialized function that checks if point intersects envelope. */
    template<> TEGEOMEXPORT bool Intersects(const te::gm::Point& point, const te::gm::Envelope& e);

    /*!
      \brief Make the line interpolation to find a target
     
      \param line LineString to make the interpolation
      \param initial Initial value
      \param final Final value
      \param target Target value
      
      \return It returns a target Coord2D in the line.
    */
    TEGEOMEXPORT Coord2D* locateAlong(const LineString* line, double initial, double final, double target);
    
    /*!
    \brief It will get a GeometryCollection and distribute in a vector.

    \param g      Input GeometryCollection.
    \param geoms  Output Geometry Vector.

    \note If the geomSource is not a te::gm::GeometryCollectionType it will return vector with the input geometry.
    */
    TEGEOMEXPORT void Multi2Single(const te::gm::Geometry* g, std::vector<te::gm::Geometry*>& geoms);

    /*!
    \brief It will fix geometries with self-intersection.

    \param g Input Geometry to fix.
    
    \return a vector of geometries.

    \note It will not check if the geometry is invalid.

    \exception Exception It throws an exception if the geometry is not Polygon or MultiPolygon.
    */
    TEGEOMEXPORT std::vector<te::gm::Geometry*> FixSelfIntersection(const te::gm::Geometry* g);

    /*!
    \brief Provides an efficient method of unioning a collection of Polygonal geometries.
    This algorithm is faster and likely more robust than the simple iterated approach of repeatedly unioning each polygon to a result geometry.

    \param polygonVector A vector of polygons.

    \return a Geometry containing the union.
    */
    TEGEOMEXPORT te::gm::Geometry* CascadedPolygonUnion(const std::vector<te::gm::Polygon*>& polygonVector);

    /*!
    \brief It will get the union of the input geometries.

    \param geom   Input Geometry.

    \return a Geometry containing the union.

    \note If no input geometries were provided, an EMPTY POINTER  is returned.
    */
    TEGEOMEXPORT te::gm::Geometry* UnaryUnion(te::gm::Geometry* geom);

    /*!
    \brief Compute the the closest points of two geometries.

    \param geomA   Input Geometry A.
    \param geomB   Input Geometry B.
    \param coordA  Output coord on Geometry A.
    \param coordB  Output coord on Geometry B.

    */
    TEGEOMEXPORT void ClosestPoints(te::gm::Geometry* geomA, te::gm::Geometry* geomB, 
                                    te::gm::Coord2D& coordA, te::gm::Coord2D& coordB);

    TEGEOMEXPORT te::gm::Line* GetIntersectionLine(te::gm::Geometry* geom, te::gm::Coord2D coord);

    TEGEOMEXPORT double GetAngle(te::gm::Coord2D coordA, te::gm::Coord2D coordB);

    TEGEOMEXPORT bool Rotate(te::gm::Coord2D pr, te::gm::LineString* l, double angle, te::gm::LineString* lOut);

    TEGEOMEXPORT bool AdjustSegment(te::gm::Point* P0, te::gm::Point* P1, double d0, te::gm::Coord2D& P0out, te::gm::Coord2D& P1out);

  /*!
    \brief It will get a list of polygons formed by the polygonization.

    \param g      Input Polygon.
    \param pols   Output Polygon Vector.
    */
    TEGEOMEXPORT void Polygonizer(te::gm::Geometry* g, std::vector<te::gm::Polygon*>& pols);

    /*!
    \brief It check geometry validity using GEOS.

    \param geom  Geometry that will be verified.
    \param error TopologyValidationError struct.

    \return True if geometry is valid.
    */
    TEGEOMEXPORT bool CheckValidity(const te::gm::Geometry* geom, te::gm::TopologyValidationError& error);

    /*!
    \brief Get/create a valid version of the geometry given. If the geometry is a polygon or multi polygon, self intersections /
           inconsistencies are fixed. Otherwise the geometry is returned.

    \param geom
    \return a geometry
    */
    TEGEOMEXPORT te::gm::Geometry* Validate(te::gm::Geometry* geom);

    /*!
    \brief Add all line strings from the polygon given to the vector given.

    \param polygon polygon from which to extract line strings
    \param pAdd A reference to a vector of geometries.
    */
    TEGEOMEXPORT void AddPolygon(te::gm::Polygon* polygon, std::vector<te::gm::Geometry*>& pAdd);

    /*!
    \brief Add the linestring given to the vector.

    \param linestring line string
    \param pAdd A reference to a vector of geometries.
    */
    TEGEOMEXPORT void AddLineString(te::gm::LineString* lineString, std::vector<te::gm::Geometry*>& pAdd);

    /*!
    \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.
    */
    TEGEOMEXPORT double PerpendicularDistance(const te::gm::Point& first, const te::gm::Point& last, te::gm::Point& pin, Point& pinter);

    /*!
    \brief Prepares the geometry A with intersection points in geometry B.

    \param geom_A Geometry used to be inserted new points of intersection.
    \param geom_B Geometry used to intersects with Geometry A.

    \return A new geometry based on geometry A with intersection points in geometry B.
    */
    TEGEOMEXPORT te::gm::Geometry* PrepareGeometriesToIntersection(te::gm::Geometry* geom_A, te::gm::Geometry* geom_B);

    /*!
    \brief Prepares the Polygon A with intersection points in Polygon B.

    \param mpol_A MultiPolygon used to be inserted new points of intersection.
    \param mpol_B MultiPolygon used to intersects with Polygon A.

    \return A new geometry based on MultiPolygon A with intersection points in MultiPolygon B.
    */
    TEGEOMEXPORT te::gm::Geometry* PrepareGeometriesToIntersection(const te::gm::MultiPolygon& mpol_A, const te::gm::MultiPolygon& mpol_B);

    /*!
    \brief Prepares the Polygon A with intersection points in Polygon B.

    \param pol_A Polygon used to be inserted new points of intersection.
    \param pol_B Polygon used to intersects with Polygon A.

    \return A new geometry based on polygon A with intersection points in polygon B.
    */
    TEGEOMEXPORT te::gm::Geometry* PrepareGeometriesToIntersection(const te::gm::Polygon& pol_A, const te::gm::Polygon& pol_B);

    /*!
    \brief Prepares the LineString A with intersection points in LineString B.

    \param ls_A LineString used to be inserted new points of intersection.
    \param ls_B LineString used to intersects with LineString A.

    \return A new LineString based on LineString A with intersection points in LineString B.
    */
    TEGEOMEXPORT te::gm::LineString* PrepareGeometriesToIntersection(const te::gm::LineString& ls_A, const te::gm::LineString& ls_B);

    /*!
    \brief Snaps a LinearRing based on a set of LineString.

    \param rtree  The R-tree contains the candidates envelopes as reference to snap.
    \param referenceSegments  A vector of LineString that is used as reference to snap.
    \param linearRingToSnap A LinearRing that will be snapped.

    \return A new snapped LinearRing.
    */
    TEGEOMEXPORT te::gm::LinearRing* SnapLineToPoints(const te::sam::rtree::Index<std::size_t, 8>& rtree,
                                                      const std::vector<te::gm::LineString>& referenceSegments,
                                                      const te::gm::LinearRing& linearRingToSnap);

    /*!
    \brief Add intersection points in a LinearRing based on a Vector of LineString as reference.

    \param rtree  The R-tree contains the candidates envelopes as reference to snap.
    \param candidateSegments  A vector of LineString that is used as reference to snap.
    \param lr_Reference A LinearRing that will be added new points of intersection.
    \param usePerpendicularDistance True if the new points are added by perpendicular distance algorithm.

    \return
    */
    TEGEOMEXPORT te::gm::LinearRing* AddIntersectionPoints(const te::sam::rtree::Index<std::size_t, 8>& rtree,
                                                                  const std::vector<te::gm::LineString>& candidateSegments,
                                                                  const te::gm::LinearRing& lr_Reference,
                                                                  const bool& usePerpendicularDistance = false);

    /*!
    \brief Gets a vector of LineString reference points including intersection points using GEOS operators.

    \param lsReference LineString used as reference.
    \param candidates A Vector of LineString used to intersects the lsReference.

    \return A vector of LineString reference points including intersection points using GEOS operators.
    */
    TEGEOMEXPORT std::vector<te::gm::Point> GetIntersectionPointsByOperators(const te::gm::LineString& lsReference, const std::vector<te::gm::LineString>& candidates);

    /*!
    \brief Gets a vector of LineString reference points including intersection points using perpendicular distance.

    \param lsReference LineString used as reference.
    \param candidates A Vector of LineString used to intersects the lsReference.

    \return A vector of LineString reference points including intersection points using perpendicular distance.
    */
    TEGEOMEXPORT std::vector<te::gm::Point> GetIntersectionPointsByPerpendicularDistance(const te::gm::LineString& lsReference, const std::vector<te::gm::LineString>& candidates);

    /*!
    \brief Creates a LineString between the given startCoord and endCoord with the given number of intermediate coordinates.

    \param startCoord The first coordinate of the line
    \param endCoord The last coordinate of the line
    \param srid The srid of the line
    \param numberOfIntermediateCoords The number of intermediate coordinates of the line

    \return A LineString between startCoord and endCoord with the given number of intermediate coordinates
    */
    TEGEOMEXPORT te::gm::LineString CreateLine(const te::gm::Coord2D& startCoord, const te::gm::Coord2D& endCoord, const int& srid, const int& numberOfIntermediateCoords);

    /*!
    \brief Creates a Polygon from the given envelope and with the given number of intermediate coordinates in each of its four borders lines.

    \param box The envelope from which the polygon will be created
    \param srid The srid of the polygon
    \param numberOfIntermediateCoords The number of intermediate coordinates of each border line

    \return A LineString between startCoord and endCoord with the given number of intermediate coordinates in each border line
    */
    TEGEOMEXPORT te::gm::Polygon CreatePolygon(const te::gm::Envelope& box, const int& srid, const int& numberOfIntermediateCoords);

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

#endif  // __TERRALIB_GEOMETRY_INTERNAL_GEOMUTILS_H