[needs-docs][api] Rename QgsDistanceArea methods to change "date line"

to "antimeridian" Because the date line =/= +/-180 degree longitude, which is what we were incorrectly using it to mean.
qgis · Jan 11, 2019 · 021f5ea · 021f5ea
1 parent a8bd12c
commit 021f5ea
Show file tree

Hide file tree

Showing 4 changed files with 97 additions and 97 deletions.
diff --git a/python/core/auto_generated/qgsdistancearea.sip.in b/python/core/auto_generated/qgsdistancearea.sip.in
@@ -384,17 +384,17 @@ The ``interval`` parameter gives the maximum distance between points on the comp
 This argument is always specified in meters. A shorter distance results in a denser line,
 at the cost of extra computing time.
 
-If the geodesic line crosses the international date line and ``breakLine`` is true, then
-the line will be split into two parts, broken at the date line. In this case the function
-will return two lines, corresponding to the portions at either side of the date line.
+If the geodesic line crosses the antimeridian (+/- 180 degrees longitude) and ``breakLine`` is true, then
+the line will be split into two parts, broken at the antimeridian. In this case the function
+will return two lines, corresponding to the portions at either side of the antimeridian.
 
 .. versionadded:: 3.6
 %End
 
-    double latitudeGeodesicCrossesDateLine( const QgsPointXY &p1, const QgsPointXY &p2, double &fractionAlongLine /Out/ ) const;
+    double latitudeGeodesicCrossesAntimeridian( const QgsPointXY &p1, const QgsPointXY &p2, double &fractionAlongLine /Out/ ) const;
 %Docstring
 Calculates the latitude at which the geodesic line joining ``p1`` and ``p2`` crosses
-the international date line (longitude +/- 180 degrees).
+the antimeridian (longitude +/- 180 degrees).
 
 The ellipsoid settings defined on this QgsDistanceArea object will be used during the calculations.
 
@@ -404,21 +404,21 @@ will also be in this same CRS.
 :param p1: Starting point, in ellipsoidCrs()
 :param p2: Ending point, in ellipsoidCrs()
 
-:return: - the latitude at which the geodesic crosses the date line
-         - fractionAlongLine:  will be set to the fraction along the geodesic line joining ``p1`` to ``p2`` at which the date line crossing occurs.
+:return: - the latitude at which the geodesic crosses the antimeridian
+         - fractionAlongLine:  will be set to the fraction along the geodesic line joining ``p1`` to ``p2`` at which the antimeridian crossing occurs.
 
-.. seealso:: :py:func:`breakGeometryAtDateLine`
+.. seealso:: :py:func:`breakGeometryAtAntimeridian`
 
 
 .. versionadded:: 3.6
 %End
 
-    QgsGeometry splitGeometryAtDateLine( const QgsGeometry &geometry ) const;
+    QgsGeometry splitGeometryAtAntimeridian( const QgsGeometry &geometry ) const;
 %Docstring
-Splits a (Multi)LineString ``geometry`` at the international date line (longitude +/- 180 degrees).
+Splits a (Multi)LineString ``geometry`` at the antimeridian (longitude +/- 180 degrees).
 The returned geometry will always be a multi-part geometry.
 
-Whenever line segments in the input geometry cross the international date line, they will be
+Whenever line segments in the input geometry cross the antimeridian, they will be
 split into two segments, with the latitude of the breakpoint being determined using a geodesic
 line connecting the points either side of this segment.
 
@@ -428,13 +428,13 @@ The ellipsoid settings defined on this QgsDistanceArea object will be used durin
 will also be in this same CRS.
 
 If ``geometry`` contains M or Z values, these will be linearly interpolated for the new vertices
-created at the date line.
+created at the antimeridian.
 
 .. note::
 
    Non-(Multi)LineString geometries will be returned unchanged.
 
-.. seealso:: :py:func:`latitudeGeodesicCrossesDateLine`
+.. seealso:: :py:func:`latitudeGeodesicCrossesAntimeridian`
 
 .. versionadded:: 3.6
 %End

diff --git a/src/core/qgsdistancearea.cpp b/src/core/qgsdistancearea.cpp
@@ -457,7 +457,7 @@ QgsPointXY QgsDistanceArea::computeSpheroidProject(
   return QgsPointXY( RAD2DEG( lambda2 ), RAD2DEG( lat2 ) );
 }
 
-double QgsDistanceArea::latitudeGeodesicCrossesDateLine( const QgsPointXY &pp1, const QgsPointXY &pp2, double &fractionAlongLine ) const
+double QgsDistanceArea::latitudeGeodesicCrossesAntimeridian( const QgsPointXY &pp1, const QgsPointXY &pp2, double &fractionAlongLine ) const
 {
   QgsPointXY p1 = pp1;
   QgsPointXY p2 = pp2;
@@ -487,7 +487,7 @@ double QgsDistanceArea::latitudeGeodesicCrossesDateLine( const QgsPointXY &pp1,
 
   int iterations = 0;
   double t = 0;
-  // iterate until our intersection candidate is within ~1 mm of the date line (or too many iterations happened)
+  // iterate until our intersection candidate is within ~1 mm of the antimeridian (or too many iterations happened)
   while ( std::fabs( lon - 180.0 ) > 0.00000001 && iterations < 100 )
   {
     if ( iterations > 0 && std::fabs( p2x - p1x ) > 5 )
@@ -516,7 +516,7 @@ double QgsDistanceArea::latitudeGeodesicCrossesDateLine( const QgsPointXY &pp1,
       intersectionDist *= ( 180.0 - p1x ) / ( lon - p1x );
     }
 
-    // now work out the point on the geodesic this far from p1 - this becomes our new candidate for crossing the date line
+    // now work out the point on the geodesic this far from p1 - this becomes our new candidate for crossing the antimeridian
 
     geod_position( &line, intersectionDist, &lat, &lon, &t );
     // we don't want to wrap longitudes > 180 around)
@@ -533,7 +533,7 @@ double QgsDistanceArea::latitudeGeodesicCrossesDateLine( const QgsPointXY &pp1,
   return lat;
 }
 
-QgsGeometry QgsDistanceArea::splitGeometryAtDateLine( const QgsGeometry &geometry ) const
+QgsGeometry QgsDistanceArea::splitGeometryAtAntimeridian( const QgsGeometry &geometry ) const
 {
   if ( QgsWkbTypes::geometryType( geometry.wkbType() ) != QgsWkbTypes::LineGeometry )
     return geometry;
@@ -585,14 +585,14 @@ QgsGeometry QgsDistanceArea::splitGeometryAtDateLine( const QgsGeometry &geometr
         lat = y;
         mCoordTransform.transformInPlace( lon, lat, z );
 
-        //test if we crossed the dateline in this segment
+        //test if we crossed the antimeridian in this segment
         if ( i > 0 && ( ( prevLon < -120 && lon > 120 ) || ( prevLon > 120 && lon  < -120 ) ) )
         {
           // we did!
           // when crossing the antimeridian, we need to calculate the latitude
           // at which the geodesic intersects the antimeridian
           double fract = 0;
-          double lat180 = latitudeGeodesicCrossesDateLine( QgsPointXY( prevLon, prevLat ), QgsPointXY( lon, lat ), fract );
+          double lat180 = latitudeGeodesicCrossesAntimeridian( QgsPointXY( prevLon, prevLat ), QgsPointXY( lon, lat ), fract );
           if ( line->is3D() )
           {
             z = prevZ + ( p.z() - prevZ ) * fract;
@@ -711,11 +711,11 @@ QVector< QVector<QgsPointXY> > QgsDistanceArea::geodesicLine( const QgsPointXY &
 
     if ( breakLine && ( ( prevLon < -120 && lon > 120 ) || ( prevLon > 120 && lon < -120 ) ) )
     {
-      // when breaking the geodesic at the date line, we need to calculate the latitude
-      // at which the geodesic intersects the date line, and add points to both line segments at this latitude
-      // on the date line.
+      // when breaking the geodesic at the antimeridian, we need to calculate the latitude
+      // at which the geodesic intersects the antimeridian, and add points to both line segments at this latitude
+      // on the antimeridian.
       double fraction;
-      double lat180 = latitudeGeodesicCrossesDateLine( QgsPointXY( prevLon, prevLat ), QgsPointXY( lon, lat ), fraction );
+      double lat180 = latitudeGeodesicCrossesAntimeridian( QgsPointXY( prevLon, prevLat ), QgsPointXY( lon, lat ), fraction );
 
       try
       {

diff --git a/src/core/qgsdistancearea.h b/src/core/qgsdistancearea.h
@@ -311,17 +311,17 @@ class CORE_EXPORT QgsDistanceArea
      * This argument is always specified in meters. A shorter distance results in a denser line,
      * at the cost of extra computing time.
      *
-     * If the geodesic line crosses the international date line and \a breakLine is true, then
-     * the line will be split into two parts, broken at the date line. In this case the function
-     * will return two lines, corresponding to the portions at either side of the date line.
+     * If the geodesic line crosses the antimeridian (+/- 180 degrees longitude) and \a breakLine is true, then
+     * the line will be split into two parts, broken at the antimeridian. In this case the function
+     * will return two lines, corresponding to the portions at either side of the antimeridian.
      *
      * \since QGIS 3.6
      */
     QVector<QVector<QgsPointXY> > geodesicLine( const QgsPointXY &p1, const QgsPointXY &p2, double interval, bool breakLine = false ) const;
 
     /**
      * Calculates the latitude at which the geodesic line joining \a p1 and \a p2 crosses
-     * the international date line (longitude +/- 180 degrees).
+     * the antimeridian (longitude +/- 180 degrees).
      *
      * The ellipsoid settings defined on this QgsDistanceArea object will be used during the calculations.
      *
@@ -330,20 +330,20 @@ class CORE_EXPORT QgsDistanceArea
      *
      * \param p1 Starting point, in ellipsoidCrs()
      * \param p2 Ending point, in ellipsoidCrs()
-     * \param fractionAlongLine will be set to the fraction along the geodesic line joining \a p1 to \a p2 at which the date line crossing occurs.
+     * \param fractionAlongLine will be set to the fraction along the geodesic line joining \a p1 to \a p2 at which the antimeridian crossing occurs.
      *
-     * \returns the latitude at which the geodesic crosses the date line
-     * \see breakGeometryAtDateLine()
+     * \returns the latitude at which the geodesic crosses the antimeridian
+     * \see breakGeometryAtAntimeridian()
      *
      * \since QGIS 3.6
      */
-    double latitudeGeodesicCrossesDateLine( const QgsPointXY &p1, const QgsPointXY &p2, double &fractionAlongLine SIP_OUT ) const;
+    double latitudeGeodesicCrossesAntimeridian( const QgsPointXY &p1, const QgsPointXY &p2, double &fractionAlongLine SIP_OUT ) const;
 
     /**
-     * Splits a (Multi)LineString \a geometry at the international date line (longitude +/- 180 degrees).
+     * Splits a (Multi)LineString \a geometry at the antimeridian (longitude +/- 180 degrees).
      * The returned geometry will always be a multi-part geometry.
      *
-     * Whenever line segments in the input geometry cross the international date line, they will be
+     * Whenever line segments in the input geometry cross the antimeridian, they will be
      * split into two segments, with the latitude of the breakpoint being determined using a geodesic
      * line connecting the points either side of this segment.
      *
@@ -353,14 +353,14 @@ class CORE_EXPORT QgsDistanceArea
      * will also be in this same CRS.
      *
      * If \a geometry contains M or Z values, these will be linearly interpolated for the new vertices
-     * created at the date line.
+     * created at the antimeridian.
      *
      * \note Non-(Multi)LineString geometries will be returned unchanged.
      *
-     * \see latitudeGeodesicCrossesDateLine()
+     * \see latitudeGeodesicCrossesAntimeridian()
      * \since QGIS 3.6
      */
-    QgsGeometry splitGeometryAtDateLine( const QgsGeometry &geometry ) const;
+    QgsGeometry splitGeometryAtAntimeridian( const QgsGeometry &geometry ) const;
 
   private: