Skip to content

Commit

Permalink
[needs-docs][api] Rename QgsDistanceArea methods to change "date line"
Browse files Browse the repository at this point in the history 
to "antimeridian"

Because the date line =/= +/-180 degree longitude, which is what
we were incorrectly using it to mean.
  • Loading branch information
@nyalldawson
nyalldawson committed Jan 11, 2019
1 parent a8bd12c commit 021f5ea
Show file tree
Hide file tree
Showing 4 changed files with 97 additions and 97 deletions.
26 changes: 13 additions & 13 deletions python/core/auto_generated/qgsdistancearea.sip.in
View file
Expand Up @@ -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.

Expand All @@ -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.

Expand All @@ -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
Expand Down
20 changes: 10 additions & 10 deletions src/core/qgsdistancearea.cpp
View file
Expand Up @@ -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;
Expand Down Expand Up @@ -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 )
Expand Down Expand Up @@ -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)
Expand All @@ -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;
Expand Down Expand Up @@ -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;
Expand Down Expand Up @@ -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
{
Expand Down
26 changes: 13 additions & 13 deletions src/core/qgsdistancearea.h
View file
Expand Up @@ -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.
*
Expand All @@ -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.
*
Expand All @@ -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:

Expand Down

0 comments on commit 021f5ea

Please sign in to comment.