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 "CommonDataStructures.h"
#include "Enums.h"
 
// STL
#include <memory>
#include <set>
#include <vector>
 
namespace te
{
  namespace gm
  {
// Forward declarations
    class Curve;
    class Envelope;
    class Geometry;
    class GeometryPtr;
    class Point;
    class Polygon;
    class Line;
    class LinearRing;
    class LineString;
    class MultiLineString;
 
    struct Coord2D;
    
    /*!
      \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 returns the name of 2D geometry subclass.
 
    The name of the 2D geometry subclass may be one of the following:
    <ul>
    <li>Geometry            </li>
    <li>Point               </li>
    <li>LineString          </li>
    <li>Polygon             </li>
    <li>MultiPoint          </li>
    <li>MultiLineString     </li>
    <li>MultiPolygon        </li>
    <li>GeometryCollection  </li>
    <li>CircularString      </li>
    <li>CompoundCurve       </li>
    <li>CurvePolygon        </li>
    <li>MultiSurface        </li>
    </ul>
 
    \return The name of the geometry subclass type ide.
    */
    TEGEOMEXPORT const std::string Get2DGeometryType(const te::gm::GeomType& type);
 
    /*!
    \brief It returns the 2D geometry subclass type identifier.
 
    <ul>
    <li>GeometryType            = 0</li>
    <li>PointType               = 1</li>
    <li>LineStringType          = 2</li>
    <li>PolygonType             = 3</li>
    <li>MultiPointType          = 4</li>
    <li>MultiLineStringType     = 5</li>
    <li>MultiPolygonType        = 6</li>
    <li>GeometryCollectionType  = 7</li>
    <li>CircularStringType      = 8</li>
    <li>CompoundCurveType       = 9</li>
    <li>CurvePolygonType        = 10</li>
    <li>MultiSurfaceType        = 12</li>
    </ul>
 
    \return The 2D geometry subclass type identifier
 
    \note Please, see GeomType enumeration for possible return values.
 
    \note TerraLib extended method.
    */
    TEGEOMEXPORT GeomType Get2DGeomTypeId(const te::gm::GeomType& type);
 
    /*!
    \brief Creates an envelope that fits the given coordinates. It makes all the adjustments needed to return a valid envelope
 
    \param x1   The coordinate X of the first point
    \param y1   The coordinate Y of the first point
    \param x2   The coordinate X of the second point
    \param y2   The coordinate Y of the second point
 
    \return A valid envelope containing the two given points
    */
    TEGEOMEXPORT te::gm::Envelope CreateEnvelope(double x1, double y1, double x2, double y2);
 
    /*!
    \brief Creates an envelope that fits the given coordinates. It makes all the adjustments needed to return a valid envelope
 
    \param p1   The first point
    \param p2   The second point
 
    \return A valid envelope containing the two given points
    */
    TEGEOMEXPORT te::gm::Envelope CreateEnvelope(const te::gm::Point& p1, const te::gm::Point& p2);
 
    /*!
    \brief Creates an envelope by expanding the dimension of the given coordinate using the given extension.
           The extension value will be used to expand the envelope in the four directions.
           The result envelope will have width = (2 * extension) and height = (2 * extension)
 
    \param coord      The reference coordinate
    \param extension  The extension to expand the the envelope
 
    \return A valid envelope
    */
    TEGEOMEXPORT te::gm::Envelope CreateEnvelope(const te::gm::Coord2D& coord, double extension);
 
    /*!
      \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.
      \param tolerance Tolerance value to be used in geometric operations
 
      \return Union of the geometry.
    */
    TEGEOMEXPORT std::unique_ptr<te::gm::Geometry> GetGeometryUnion(const te::gm::GeometryVectorConst& geomVec, double tolerance = 0.000000001);
    
    /*!
      \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 Tests if the given relation matrix matches with the given relation pattern. This pattern is based on the Dimensionally Extended nine-Intersection Model (DE-9IM)
 
      \param relation The relation matrix to be checked
      \param relationPattern The pattern to be match
 
      \return It returns TRUE if the given relation matches the given relationPattern. 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 RelationMatches(const std::string& relation, const std::string& relationPattern);
 
    /*!
      \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 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.
    \note The caller of this method must take the ownership of the returned geometries and delete then when appropriate.
    */
    TEGEOMEXPORT void Multi2Single(const te::gm::Geometry* g, std::vector<te::gm::Geometry*>& geoms);
 
    /*!
    \brief It will get geometry and return the related GeometryCollection type.
 
    \param g      Input Geometry.
 
    \return The related GeometryCollection type or a nullptr if an error has occurred.
 
    \note The caller of this method must take the ownership of the returned geometries and delete then when appropriate.
    \note If the input geomtry is a geometry collection it will be clonned and returned.
 
    */
    TEGEOMEXPORT te::gm::Geometry* Single2Multi(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 Provides an efficient method of unioning a collection of geometries.
    This algorithm is faster and likely more robust than the simple iterated approach of repeatedly unioning each polygon to a result geometry.
 
    \param vecGeometries A vector of geometries.
 
    \return a Geometry containing the union.
    */
    TEGEOMEXPORT te::gm::Geometry* CascadedUnion(const std::vector<te::gm::Geometry*>& vecGeometries);
 
    /*!
    \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 will get a list of polygons formed by the polygonization.
 
    \param g      Input Polygon.
    \param pols   Output Polygon Vector.
    */
    TEGEOMEXPORT void Polygonizer(const te::gm::GeometryVector& vecInput, te::gm::GeometryVector& vecOutput);
 
    /*!
    \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, te::gm::GeometryVector& 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, te::gm::GeometryVector& pAdd);
 
    /*!
    \brief Prepares the geometry A with intersection points in geometry B.
 
    \param geom_A Geometry used to be inserted new points of intersection.
    \param geomB The geometry to be used to intersect with Geometry B.
    \param wasChanged This is an output value to inform if the geometry has been changed or not during the prepare
    \param tolerance Tolerance value to be used in geometric operations
 
    \return A new geometry based on geometry A with intersection points in geometry B.
    */
    TEGEOMEXPORT te::gm::Geometry* PrepareGeometriesToIntersection(const te::gm::Geometry* geom_A, te::gm::Geometry* geomB, 
      bool& wasChanged, double tolerance = 0.000000001);
 
    TEGEOMEXPORT te::gm::Geometry* PrepareGeometriesToIntersection(const te::gm::Geometry* geom_A, te::gm::Geometry* geomB, 
      bool checkValidityAndFix, bool& wasChanged, double tolerance = 0.000000001);
 
    /*!
    \brief Prepares the geometry A with intersection points in geometry B.
 
    \param geom_A Geometry used to be inserted new points of intersection.
    \param vecGeomB The list of Geometries used to intersects with Geometry A.
    \param wasChanged This is an output value to inform if the geometry has been changed or not during the prepare
    \param tolerance Tolerance value to be used in geometric operations
 
    \return A new geometry based on geometry A with intersection points in geometry B.
    */
    TEGEOMEXPORT te::gm::Geometry* PrepareGeometriesToIntersection(const te::gm::Geometry* geom_A, const te::gm::GeometryVector& vecGeomB,
      bool& wasChanged, double tolerance = 0.000000001);
 
    TEGEOMEXPORT te::gm::Geometry* PrepareGeometriesToIntersection(const te::gm::Geometry* geom_A, const te::gm::GeometryVector& vecGeomB, 
      bool checkValidityAndFix, bool& wasChanged, double tolerance = 0.000000001);
 
    /*!
    \brief Prepares the geometries vector to be used in overlay operations.
    \description It has two steps: 1 - Tries to snap the existing coordinates to make them be exactly the same if the are within the given tolerance;
                 2 - It breaks crossing segments in the intersection coordinates, sometimes gerating new coordinates in both segments
 
    \param vecGeometries The vector to be prepared.
    \param wasChanged This is an output value to inform if the geometry has been changed or not during the prepare
    \param tolerance Tolerance value to be used in geometric operations
 
    \return A new geometry vector prepared to overlay operations.
    */
    TEGEOMEXPORT te::gm::GeometryVector PrepareGeometriesToIntersection(const te::gm::GeometryVectorConst& vecGeometries,
      bool& wasChanged, double tolerance = 0.000000001);
 
    /*!
    \brief Prepares the MultiLineString A with intersection points in MultiLineString B.
 
    \param mline_A MultiLineString used to be inserted new points of intersection.
    \param rtree Rtree indexing all the segments that must be used in the prepare algorithm.
    \param vecRtreeSegments All the segments indexed in the rtree
    \param wasChanged This is an output value to inform if the geometry has been changed or not during the prepare
    \param tolerance Tolerance value to be used in geometric operations
 
    \return A new MultiLineString based on MultiLineString A with intersection points in MultiLineString B.
    */
    TEGEOMEXPORT te::gm::MultiLineString* PrepareGeometriesToIntersection(const te::gm::MultiLineString& mline_A, const te::sam::rtree::Index<std::size_t, 8>& rtree, 
      std::vector<te::gm::LineString>& vecRtreeSegments, bool& wasChanged, double tolerance = 0.000000001);
 
    /*!
    \brief Prepares the LineString A with intersection points in LineString B.
 
    \param ls_A LineString used to be inserted new points of intersection.
    \param rtree Rtree indexing all the segments that must be used in the prepare algorithm.
    \param vecRtreeSegments All the segments indexed in the rtree
    \param wasChanged This is an output value to inform if the geometry has been changed or not during the prepare
    \param tolerance Tolerance value to be used in geometric operations
 
    \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::sam::rtree::Index<std::size_t, 8>& rtree, 
      std::vector<te::gm::LineString>& vecRtreeSegments, bool& wasChanged, double tolerance = 0.000000001);
 
    /*!
    \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 setIndexesIgnored A set of indexes of candidates that had must be ignored in the processing. This set is used for optimization purposes
    \param wasChanged This is an output value to inform if the geometry has been changed or not during the prepare
    \param linearRingToSnap A LinearRing that will be snapped.
    \param tolerance Tolerance value to be used in geometric operations
 
    \return A new snapped LinearRing.
    */
    TEGEOMEXPORT LineString* SnapLineToPoints(const te::sam::rtree::Index<std::size_t, 8>& rtree,
                                              const std::vector<te::gm::LineString>& referenceSegments,
                                              const std::set<std::size_t>& setIndexesIgnored,
                                              const te::gm::LineString& linearRingToSnap, bool& wasChanged,
                                              double tolerance = 0.000000001);
 
    /*!
    \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 setIndexesIgnored A set of indexes of candidates that had must be ignored in the processing. This set is used for optimization purposes
    \param wasChanged This is an output value to inform if the geometry has been changed or not during the prepare
    \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.
    \param tolerance Tolerance value to be used in geometric operations
 
    \return
    */
    TEGEOMEXPORT LineString* AddIntersectionPoints(const te::sam::rtree::Index<std::size_t, 8>& rtree,
                                                                  const std::vector<te::gm::LineString>& candidateSegments,
                                                                  const std::set<std::size_t>& setIndexesIgnored,
                                                                  const te::gm::LineString& lr_Reference,
                                                                  const bool& usePerpendicularDistance = false,
                                                                  double tolerance = 0.000000001);
 
    /*!
    \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.
    \param tolerance Tolerance value to be used in geometric operations
 
    \return A vector of LineString reference points including intersection points using GEOS operators.
    */
    TEGEOMEXPORT std::vector<te::gm::Coord2D> GetIntersectionPointsByOperators(const te::gm::LineString& lsReference, const std::vector<te::gm::LineString>& candidates, double tolerance = 0.000000001);
 
    /*!
    \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.
    \param tolerance Tolerance value to be used in geometric operations
 
    \return A vector of LineString reference points including intersection points using perpendicular distance.
    */
    TEGEOMEXPORT std::vector<te::gm::Coord2D> GetIntersectionPointsByPerpendicularDistance(const te::gm::LineString& lsReference, const std::vector<te::gm::LineString>& candidates, double tolerance = 0.000000001);
 
    /*!
    \brief Get the vector of MultLineStrings that compose the Geometry
 
    \param geometry Used to get lineStrings.
 
    return A vector of MultiLineString based on geometry parameter.
    */
    TEGEOMEXPORT std::vector<MultiLineString *> GetAsMultiLineStringVector(const te::gm::Geometry& geometry);
 
 
    /*!
    \brief A geometry is built based on a Vector of MultiLineString and the origin geometry type.
 
    \param multiLineStringVector A vector of multiLineString that have all lines of a Geometry.
 
    return A geometry built based on a Vector of MultiLineString and the origin geometry type.
    */
    TEGEOMEXPORT  te::gm::Geometry* MultiLineToDefinedType(const std::vector<te::gm::MultiLineString*>& multiLineStringVector,
                                                           te::gm::GeomType geometryType);
 
    /*!
    \brief Get the LineStrings that compose the Geometry
 
    \param geometry Used to get lineStrings.
 
    return A LineString based on parameter geometry.
    */
    TEGEOMEXPORT te::gm::GeomType GetMultiLineStringType(const te::gm::Geometry& geometry);
 
    /*!
    \brief Verifies if the geomType is a collection type.
 
    \param geomType enum te::gm::GeomType.
 
    return True if the geomType is a collection type.
    */
    TEGEOMEXPORT bool IsMultiType(te::gm::GeomType geomType);
 
    /*!
    \brief Get the simple type of GeomType.
 
    \param geomType enum te::gm::GeomType.
 
    return A simple type of GeomType.
    */
    TEGEOMEXPORT te::gm::GeomType GetSimpleType(te::gm::GeomType geomType);
 
    /*!
    \brief Get the collection type of GeomType.
 
    \param geomType enum te::gm::GeomType.
 
    return A collection type of GeomType.
    */
    TEGEOMEXPORT te::gm::GeomType GetMultiType(te::gm::GeomType geomType);
 
    /*!
    \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);
 
    /*!
    \brief Creates a parallel line from the given line. Here will use the distance for offset between the original line and the parallel.
 
    \param line Original line
    \param distance for offset between the original line and the parallel. Left will be positive and right will be negative
 
    \return A LineString between startCoord and endCoord with the given number of intermediate coordinates in each border line
    */
    TEGEOMEXPORT te::gm::LineString* ParallelLine(const te::gm::LineString* line, double distance);
 
    /*!
    \brief Checks if the given point in within the given polygon or multipolygon geometry
 
    \param coord The coord to be checked
    \param geometry The Polygon or Multipolygon to be used as reference
 
    \return TRUE if the point is within the polygon. FALSE otherwise
    */
    TEGEOMEXPORT bool IsPointOnPolygon(const te::gm::Coord2D& coord, const te::gm::Geometry* geometry);
 
    /*!
    \brief As geos Explanation: An interior point is guaranteed to lie in the interior of the Geometry, if it possible to calculate such a point exactly. 
           Otherwise, the point may lie on the boundary of the geometry.
 
    \param geometry The input geometry
 
    \return An interior point inside the given Geometry, if possible.
    */
    TEGEOMEXPORT te::gm::Coord2D GetInteriorPoint(const te::gm::Geometry* geometry);
 
 
    /*!
    \brief Normalizes and filters the given geometry based on the given simple type.
    \description If the given geometry if already from the given simple type, it will clone the geometry and return it.
                 If the geometry is from the multi type related to the single, it will clone the geometry and return it.
                 If the geometry is a collection, it will search for geometries from the given single type and multi type, and return them in a collection related to the given type.
 
    \param geometry The geometry to be analysed
    \param singleGeometryType The base single type to be used as filter
 
    \return The normalized geometry based onthe given singleGeometryType. Null if this given type could not be found in the given geometry.
    */
    TEGEOMEXPORT te::gm::Geometry* NormalizeGeometryByType(const te::gm::Geometry* geometry, te::gm::GeomType singleGeometryType);
 
    /*!
    \brief Returns the appropriate precision to be used by spatial operations that adjust geometric data from other geometric systems
 
    \param srid The id of the SRS (Spatial Reference System)
 
    \return The precision appropriate to the given srid
    */
    TEGEOMEXPORT double GetAppropriatePrecision(int srid);
 
    /*!
    \brief Clips the given geometry to the given clipArea
 
    \param geometry The geometry to be clipped
    \param clipArea The clipping area
 
    \return The clipped geometry
    */
    TEGEOMEXPORT te::gm::Geometry* ClipGeometry(const te::gm::Geometry* geometry, const te::gm::Envelope& clipArea);
 
    /*!
    \brief Checks if the geometry is null or empty
 
    \param geometry The geometry to be checked
 
    \return The result of the check. TRUE if the geometry is null or empty. FALSE otherwise
    */
    TEGEOMEXPORT bool IsNullOrEmpty(const te::gm::GeometryPtr& geometry);
 
    /*!
    \brief Checks if the geometry is null or empty
 
    \param geometry The geometry to be checked
 
    \return The result of the check. TRUE if the geometry is null or empty. FALSE otherwise
    */
    TEGEOMEXPORT bool IsNullOrEmpty(const te::gm::Geometry* geometry);
 
    /*!
    \brief Creates a polygon from the given curve
 
    \param curve The curve to be used to create a polygon
 
    \return The created polygon
    */
    TEGEOMEXPORT te::gm::GeometryPtr CreatePolygon(const te::gm::Curve* curve);
 
 
    /*!
    \brief Checks if a LinearRing is in Counter-clockwise orientation
 
    \param curve The LinearRing to be checked
 
    \return TRUE if the given LinearRing is in Counter-clockwise orientation. FALSE otherwise
    */
    TEGEOMEXPORT bool isCCW(const te::gm::LinearRing* ring);
 
    /*!
    \brief Calculates the area of the given geometry. If the geometry is from dimension 0 or 1, it returns 0
 
    \param geometry The geometry to be analysed
 
    \return The area of the geometry or 0 if the dimension of the geometry is 0 or 1
    */
    TEGEOMEXPORT double GetArea(const te::gm::Geometry* geometry);
    
    /*!
    \brief Creates a geometry collection based on the given geometryVector
 
    \param geometryVector The input geometry vector
 
    \return A geometry collection containing all the grometries from the geometry vector
    */
    TEGEOMEXPORT te::gm::GeometryPtr CreateCollectionFromGeometryVector(const te::gm::GeometryVector& geometryVector);
 
    //!< Adapts a non const geometry vector to a const geometry vector. No geometry copy is made
    TEGEOMEXPORT te::gm::GeometryVectorConst ToConstVector(const te::gm::GeometryVector& vecGeometries);
 
    /*!
    \brief Splits the given 'inputGeometry' (must be an area) using the given 'bladeLineGeometry' (must be a line)
 
    \param inputGeometry The input geometry to be splitted
    \param inputGeometry The line to be used to split the input geoemtry
 
    \return The splitted geometry. Throws an exception if an error occur
    */
    TEGEOMEXPORT std::vector<te::gm::Geometry*> SplitGeometry(const te::gm::Geometry* inputGeometry, const te::gm::Geometry* bladeLineGeometry);
 
    /*!
    \brief Returns true if the given type has M dimension.
 
    \param geomType enum te::gm::GeomType.
 
    \return Returns true if the given type has M dimension.
    */
    TEGEOMEXPORT bool HasMDim(te::gm::GeomType geomType);
 
    /*!
    \brief Returns true if the given type has Z dimension.
 
    \param geomType enum te::gm::GeomType.
 
    \return Returns true if the given type has Z dimension.
    */
    TEGEOMEXPORT bool HasZDim(te::gm::GeomType geomType);
 
    /*!
      \brief Converts the given geometry to the given geometry type.
      \param inGeomPtr Input geometry pointer.
      \param targetGeomType Target geometry type.
      \param outputGeomsPtrsVec A vector of converted geometries or, if the conversion is not possible, an empty vector is returned.
      \note The caller must take the ownership of the returned objects.
    */
    TEGEOMEXPORT void ConvertGeometryType(
      te::gm::Geometry const * const  inGeomPtr,
      const te::gm::GeomType targetGeomType,
      te::gm::GeometryVector& outputGeomsPtrsVec );
 
    /*!
      \brief Converts the given geometries set to the given geometry type.
      \param vecGeometries Input geometries vector.
      \param targetGeomType Target geometry type.
      \param outputGeomsPtrsVec A vector of converted geometries or, if the conversion is not possible, an empty vector is returned.
      \note The caller must take the ownership of the returned objects.
    */
    template< typename GeometryTypeT >
    void ConvertGeometryType(
      const std::vector< GeometryTypeT* >& vecGeometries,
      te::gm::GeomType geomType,
      te::gm::GeometryVector& outputGeomsPtrsVec )
    {
      outputGeomsPtrsVec.clear();
      const std::size_t vecGeometriesSize = vecGeometries.size();
 
      for (std::size_t vecGeometriesIdx = 0; vecGeometriesIdx <
        vecGeometriesSize; ++vecGeometriesIdx )
      {
        te::gm::GeometryVector currentResult;
        ConvertGeometryType(
          vecGeometries.at( vecGeometriesIdx ), geomType,
          currentResult );
 
        outputGeomsPtrsVec.insert(outputGeomsPtrsVec.end(),
          currentResult.begin(), currentResult.end());
      }
    }
 
  } // end namespace gm
}   // end namespace te
 
#endif  // __TERRALIB_GEOMETRY_INTERNAL_GEOMUTILS_H