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             :  * \fn OGRErr OGRSurface::PointOnSurface( OGRPoint * poPoint ) const;
      73             :  *
      74             :  * \brief This method relates to the SFCOM
      75             :  * ISurface::get_PointOnSurface() method.
      76             :  *
      77             :  * NOTE: Only implemented when GEOS included in build.
      78             :  *
      79             :  * @param poPoint point to be set with an internal point.
      80             :  *
      81             :  * @return OGRERR_NONE if it succeeds or OGRERR_FAILURE otherwise.
      82             :  */
      83             : 
      84             : /************************************************************************/
      85             : /*                           get_Length()                               */
      86             : /************************************************************************/
      87             : 
      88             : /**
      89             :  * \fn double OGRSurface::get_Length() const;
      90             :  *
      91             :  * \brief Get the length of the surface.
      92             :  *
      93             :  * The length is computed as the sum of the lengths of all members
      94             :  * in this collection (including inner rings).
      95             :  *
      96             :  * @return the length of the geometry in meters.
      97             :  *
      98             :  * @see get_GeodesicLength() for an alternative method returning lengths
      99             :  * computed on the ellipsoid, and in meters.
     100             :  *
     101             :  * @since GDAL 3.10
     102             :  */
     103             : 
     104             : /************************************************************************/
     105             : /*                        get_GeodesicLength()                          */
     106             : /************************************************************************/
     107             : 
     108             : /**
     109             :  * \fn double OGRSurface::get_GeodesicLength(const OGRSpatialReference *poSRSOverride) const;
     110             :  *
     111             :  * \brief Get the length of the surface, where curve edges are geodesic lines
     112             :  * on the underlying ellipsoid of the SRS attached to the geometry.
     113             :  *
     114             :  * The returned length will always be in meters.
     115             :  *
     116             :  * Note that geometries with circular arcs will be linearized in their original
     117             :  * coordinate space first, so the resulting geodesic length will be an
     118             :  * approximation.
     119             :  *
     120             :  * The length is computed as the sum of the lengths of all members
     121             :  * in this collection (including inner rings).
     122             :  *
     123             :  * @note No warning will be issued if a member of the collection does not
     124             :  *       support the get_GeodesicLength method.
     125             :  *
     126             :  * @param poSRSOverride If not null, overrides OGRGeometry::getSpatialReference()
     127             :  * @return the length of the geometry in meters, or a negative value in case
     128             :  * of error.
     129             :  *
     130             :  * @see get_Length() for an alternative method returning lengths computed in
     131             :  * 2D Cartesian space.
     132             :  *
     133             :  * @since GDAL 3.10
     134             :  */
     135             : 
     136             : /************************************************************************/
     137             : /*                          CastToPolygon()                             */
     138             : /************************************************************************/
     139             : 
     140             : /*! @cond Doxygen_Suppress */
     141             : /**
     142             :  * \brief Cast to polygon
     143             :  *
     144             :  * The passed in geometry is consumed and a new one returned (or NULL in case
     145             :  * of failure)
     146             :  *
     147             :  * @param poSurface the input geometry - ownership is passed to the method.
     148             :  * @return new geometry.
     149             :  */
     150             : 
     151       52343 : OGRPolygon *OGRSurface::CastToPolygon(OGRSurface *poSurface)
     152             : {
     153       52343 :     OGRSurfaceCasterToPolygon pfn = poSurface->GetCasterToPolygon();
     154       52343 :     return pfn(poSurface);
     155             : }
     156             : 
     157             : /************************************************************************/
     158             : /*                          CastToCurvePolygon()                        */
     159             : /************************************************************************/
     160             : 
     161             : /**
     162             :  * \brief Cast to curve polygon
     163             :  *
     164             :  * The passed in geometry is consumed and a new one returned (or NULL in case
     165             :  * of failure)
     166             :  *
     167             :  * @param poSurface the input geometry - ownership is passed to the method.
     168             :  * @return new geometry.
     169             :  */
     170             : 
     171          20 : OGRCurvePolygon *OGRSurface::CastToCurvePolygon(OGRSurface *poSurface)
     172             : {
     173          20 :     OGRSurfaceCasterToCurvePolygon pfn = poSurface->GetCasterToCurvePolygon();
     174          20 :     return pfn(poSurface);
     175             : }
     176             : 
     177             : /*! @endcond */