Line data    Source code

       1             : /******************************************************************************
       2             :  *
       3             :  * Project:  OpenGIS Simple Features Reference Implementation
       4             :  * Purpose:  The OGRSurface class.
       5             :  * Author:   Frank Warmerdam, warmerdam@pobox.com
       6             :  *
       7             :  ******************************************************************************
       8             :  * Copyright (c) 1999, Frank Warmerdam
       9             :  *
      10             :  * SPDX-License-Identifier: MIT
      11             :  ****************************************************************************/
      12             : 
      13             : #include "cpl_port.h"
      14             : #include "ogr_geometry.h"
      15             : #include "ogr_p.h"
      16             : 
      17             : /**
      18             :  * \fn double OGRSurface::get_Area() const;
      19             :  *
      20             :  * \brief Get the area of the surface object.
      21             :  *
      22             :  * The returned area is a 2D Cartesian (planar) area in square units of the
      23             :  * spatial reference system in use, so potentially "square degrees" for a
      24             :  * geometry expressed in a geographic SRS.
      25             :  *
      26             :  * For polygons the area is computed as the area of the outer ring less
      27             :  * the area of all internal rings.
      28             :  *
      29             :  * This method relates to the SFCOM ISurface::get_Area() method.
      30             :  *
      31             :  * @return the area of the geometry in square units of the spatial reference
      32             :  * system in use.
      33             :  *
      34             :  * @see get_GeodesicArea() for an alternative method returning areas
      35             :  * computed on the ellipsoid, an in square meters.
      36             :  */
      37             : 
      38             : /**
      39             :  * \fn double OGRSurface::get_GeodesicArea(const OGRSpatialReference* poSRSOverride = nullptr) const;
      40             :  *
      41             :  * \brief Get the area of the surface object, considered as a surface on the
      42             :  * underlying ellipsoid of the SRS attached to the geometry.
      43             :  *
      44             :  * The returned area will always be in square meters, and assumes that
      45             :  * polygon edges describe geodesic lines on the ellipsoid.
      46             :  *
      47             :  * <a href="https://geographiclib.sourceforge.io/html/python/geodesics.html">Geodesics</a>
      48             :  * follow the shortest route on the surface of the ellipsoid.
      49             :  *
      50             :  * If the geometry' SRS is not a geographic one, geometries are reprojected to
      51             :  * the underlying geographic SRS of the geometry' SRS.
      52             :  * OGRSpatialReference::GetDataAxisToSRSAxisMapping() is honored.
      53             :  *
      54             :  * For polygons the area is computed as the area of the outer ring less
      55             :  * the area of all internal rings.
      56             :  *
      57             :  * Note that geometries with circular arcs will be linearized in their original
      58             :  * coordinate space first, so the resulting geodesic area will be an
      59             :  * approximation.
      60             :  *
      61             :  * @param poSRSOverride If not null, overrides OGRGeometry::getSpatialReference()
      62             :  * @return the area of the geometry in square meters, or a negative value in case
      63             :  * of error.
      64             :  *
      65             :  * @see get_Area() for an alternative method returning areas computed in
      66             :  * 2D Cartesian space.
      67             :  *
      68             :  * @since GDAL 3.9
      69             :  */
      70             : 
      71             : /**
      72             :  * \brief This method relates to the SFCOM
      73             :  * ISurface::get_PointOnSurface() method.
      74             :  *
      75             :  * NOTE: Only implemented when GEOS included in build.
      76             :  *
      77             :  * @param poPoint point to be set with an internal point.
      78             :  *
      79             :  * @return OGRERR_NONE if it succeeds or OGRERR_FAILURE otherwise.
      80             :  */
      81           0 : OGRErr OGRSurface::PointOnSurface(OGRPoint *poPoint) const
      82             : {
      83           0 :     return PointOnSurfaceInternal(poPoint);
      84             : }
      85             : 
      86             : /************************************************************************/
      87             : /*                           get_Length()                               */
      88             : /************************************************************************/
      89             : 
      90             : /**
      91             :  * \fn double OGRSurface::get_Length() const;
      92             :  *
      93             :  * \brief Get the length of the surface.
      94             :  *
      95             :  * The length is computed as the sum of the lengths of all members
      96             :  * in this collection (including inner rings).
      97             :  *
      98             :  * @return the length of the geometry in meters.
      99             :  *
     100             :  * @see get_GeodesicLength() for an alternative method returning lengths
     101             :  * computed on the ellipsoid, and in meters.
     102             :  *
     103             :  * @since GDAL 3.10
     104             :  */
     105             : 
     106             : /************************************************************************/
     107             : /*                        get_GeodesicLength()                          */
     108             : /************************************************************************/
     109             : 
     110             : /**
     111             :  * \fn double OGRSurface::get_GeodesicLength(const OGRSpatialReference *poSRSOverride) const;
     112             :  *
     113             :  * \brief Get the length of the surface, where curve edges are geodesic lines
     114             :  * on the underlying ellipsoid of the SRS attached to the geometry.
     115             :  *
     116             :  * The returned length will always be in meters.
     117             :  *
     118             :  * Note that geometries with circular arcs will be linearized in their original
     119             :  * coordinate space first, so the resulting geodesic length will be an
     120             :  * approximation.
     121             :  *
     122             :  * The length is computed as the sum of the lengths of all members
     123             :  * in this collection (including inner rings).
     124             :  *
     125             :  * @note No warning will be issued if a member of the collection does not
     126             :  *       support the get_GeodesicLength method.
     127             :  *
     128             :  * @param poSRSOverride If not null, overrides OGRGeometry::getSpatialReference()
     129             :  * @return the length of the geometry in meters, or a negative value in case
     130             :  * of error.
     131             :  *
     132             :  * @see get_Length() for an alternative method returning lengths computed in
     133             :  * 2D Cartesian space.
     134             :  *
     135             :  * @since GDAL 3.10
     136             :  */
     137             : 
     138             : /************************************************************************/
     139             : /*                          CastToPolygon()                             */
     140             : /************************************************************************/
     141             : 
     142             : /*! @cond Doxygen_Suppress */
     143             : /**
     144             :  * \brief Cast to polygon
     145             :  *
     146             :  * The passed in geometry is consumed and a new one returned (or NULL in case
     147             :  * of failure)
     148             :  *
     149             :  * @param poSurface the input geometry - ownership is passed to the method.
     150             :  * @return new geometry.
     151             :  */
     152             : 
     153       52215 : OGRPolygon *OGRSurface::CastToPolygon(OGRSurface *poSurface)
     154             : {
     155       52215 :     OGRSurfaceCasterToPolygon pfn = poSurface->GetCasterToPolygon();
     156       52215 :     return pfn(poSurface);
     157             : }
     158             : 
     159             : /************************************************************************/
     160             : /*                          CastToCurvePolygon()                        */
     161             : /************************************************************************/
     162             : 
     163             : /**
     164             :  * \brief Cast to curve polygon
     165             :  *
     166             :  * The passed in geometry is consumed and a new one returned (or NULL in case
     167             :  * of failure)
     168             :  *
     169             :  * @param poSurface the input geometry - ownership is passed to the method.
     170             :  * @return new geometry.
     171             :  */
     172             : 
     173          21 : OGRCurvePolygon *OGRSurface::CastToCurvePolygon(OGRSurface *poSurface)
     174             : {
     175          21 :     OGRSurfaceCasterToCurvePolygon pfn = poSurface->GetCasterToCurvePolygon();
     176          21 :     return pfn(poSurface);
     177             : }
     178             : 
     179             : /*! @endcond */