QGIS API Documentation 3.28.0-Firenze (ed3ad0430f)
Public Member Functions | Static Public Member Functions | List of all members
QgsDistanceArea Class Reference

A general purpose distance and area calculator, capable of performing ellipsoid based calculations. More...

#include <qgsdistancearea.h>

Public Member Functions

 QgsDistanceArea ()
 Constructor. More...
 
 QgsDistanceArea (const QgsDistanceArea &other)
 Copy constructor. More...
 
 ~QgsDistanceArea ()
 
QgsUnitTypes::AreaUnit areaUnits () const
 Returns the units of area for areal calculations made by this object. More...
 
double bearing (const QgsPointXY &p1, const QgsPointXY &p2) const SIP_THROW(QgsCsException)
 Computes the bearing (in radians) between two points. More...
 
QgsPointXY computeSpheroidProject (const QgsPointXY &p1, double distance=1, double azimuth=M_PI_2) const
 Given a location, an azimuth and a distance, computes the location of the projected point. More...
 
double convertAreaMeasurement (double area, QgsUnitTypes::AreaUnit toUnits) const
 Takes an area measurement calculated by this QgsDistanceArea object and converts it to a different areal unit. More...
 
double convertLengthMeasurement (double length, QgsUnitTypes::DistanceUnit toUnits) const
 Takes a length measurement calculated by this QgsDistanceArea object and converts it to a different distance unit. More...
 
QString ellipsoid () const
 Returns ellipsoid's acronym. More...
 
QgsCoordinateReferenceSystem ellipsoidCrs () const
 Returns the ellipsoid (destination) spatial reference system. More...
 
double ellipsoidInverseFlattening () const
 Returns ellipsoid's inverse flattening. More...
 
double ellipsoidSemiMajor () const
 Returns the ellipsoid's semi major axis. More...
 
double ellipsoidSemiMinor () const
 Returns ellipsoid's semi minor axis. More...
 
QVector< QVector< QgsPointXY > > geodesicLine (const QgsPointXY &p1, const QgsPointXY &p2, double interval, bool breakLine=false) const
 Calculates the geodesic line between p1 and p2, which represents the shortest path on the ellipsoid between these two points. More...
 
double latitudeGeodesicCrossesAntimeridian (const QgsPointXY &p1, const QgsPointXY &p2, double &fractionAlongLine) const
 Calculates the latitude at which the geodesic line joining p1 and p2 crosses the antimeridian (longitude +/- 180 degrees). More...
 
QgsUnitTypes::DistanceUnit lengthUnits () const
 Returns the units of distance for length calculations made by this object. More...
 
double measureArea (const QgsGeometry &geometry) const
 Measures the area of a geometry. More...
 
double measureLength (const QgsGeometry &geometry) const
 Measures the length of a geometry. More...
 
double measureLine (const QgsPointXY &p1, const QgsPointXY &p2) const
 Measures the distance between two points. More...
 
double measureLine (const QVector< QgsPointXY > &points) const
 Measures the length of a line with multiple segments. More...
 
double measureLineProjected (const QgsPointXY &p1, double distance=1, double azimuth=M_PI_2, QgsPointXY *projectedPoint=nullptr) const
 Calculates the distance from one point with distance in meters and azimuth (direction) When the sourceCrs() is geographic, computeSpheroidProject() will be called otherwise QgsPoint.project() will be called after QgsUnitTypes::fromUnitToUnitFactor() has been applied to the distance. More...
 
double measurePerimeter (const QgsGeometry &geometry) const
 Measures the perimeter of a polygon geometry. More...
 
double measurePolygon (const QVector< QgsPointXY > &points) const
 Measures the area of the polygon described by a set of points. More...
 
QgsDistanceAreaoperator= (const QgsDistanceArea &other)
 
bool setEllipsoid (const QString &ellipsoid)
 Sets the ellipsoid by its acronym. More...
 
bool setEllipsoid (double semiMajor, double semiMinor)
 Sets ellipsoid by supplied radii. More...
 
void setSourceCrs (const QgsCoordinateReferenceSystem &crs, const QgsCoordinateTransformContext &context)
 Sets source spatial reference system crs. More...
 
QgsCoordinateReferenceSystem sourceCrs () const
 Returns the source spatial reference system. More...
 
QgsGeometry splitGeometryAtAntimeridian (const QgsGeometry &geometry) const
 Splits a (Multi)LineString geometry at the antimeridian (longitude +/- 180 degrees). More...
 
bool willUseEllipsoid () const
 Returns whether calculations will use the ellipsoid. More...
 

Static Public Member Functions

static QString formatArea (double area, int decimals, QgsUnitTypes::AreaUnit unit, bool keepBaseUnit=false)
 Returns an area formatted as a friendly string. More...
 
static QString formatDistance (double distance, int decimals, QgsUnitTypes::DistanceUnit unit, bool keepBaseUnit=false)
 Returns an distance formatted as a friendly string. More...
 

Detailed Description

A general purpose distance and area calculator, capable of performing ellipsoid based calculations.

Measurements can either be performed on existing QgsGeometry objects, or using lists of points.

If a valid ellipsoid() has been set for the QgsDistanceArea, all calculations will be performed using ellipsoidal algorithms (e.g. using Vincenty's formulas). If no ellipsoid has been set, all calculations will be performed using Cartesian formulas only. The behavior can be determined by calling willUseEllipsoid().

In order to perform accurate calculations, the source coordinate reference system of all measured geometries must first be specified using setSourceCrs().

Usually, the measurements returned by QgsDistanceArea are in meters. If no valid ellipsoid is set, then the units may not be meters. The units can be retrieved by calling lengthUnits() and areaUnits().

Internally, the GeographicLib library is used to calculate all ellipsoid based measurements.

Definition at line 52 of file qgsdistancearea.h.

Constructor & Destructor Documentation

◆ QgsDistanceArea() [1/2]

QgsDistanceArea::QgsDistanceArea ( )

Constructor.

Definition at line 44 of file qgsdistancearea.cpp.

◆ ~QgsDistanceArea()

QgsDistanceArea::~QgsDistanceArea ( )
default

◆ QgsDistanceArea() [2/2]

QgsDistanceArea::QgsDistanceArea ( const QgsDistanceArea other)

Copy constructor.

Definition at line 57 of file qgsdistancearea.cpp.

Member Function Documentation

◆ areaUnits()

QgsUnitTypes::AreaUnit QgsDistanceArea::areaUnits ( ) const

Returns the units of area for areal calculations made by this object.

See also
lengthUnits()
Since
QGIS 2.14

Definition at line 795 of file qgsdistancearea.cpp.

◆ bearing()

double QgsDistanceArea::bearing ( const QgsPointXY p1,
const QgsPointXY p2 
) const

Computes the bearing (in radians) between two points.

Exceptions
QgsCsExceptionon invalid input coordinates

Definition at line 843 of file qgsdistancearea.cpp.

◆ computeSpheroidProject()

QgsPointXY QgsDistanceArea::computeSpheroidProject ( const QgsPointXY p1,
double  distance = 1,
double  azimuth = M_PI_2 
) const

Given a location, an azimuth and a distance, computes the location of the projected point.

Parameters
p1- location of first geographic (latitude/longitude) point as degrees.
distance- distance in meters.
azimuth- azimuth in radians, clockwise from North
Returns
p2 - location of projected point as longitude/latitude.
Since
QGIS 3.0

Definition at line 440 of file qgsdistancearea.cpp.

◆ convertAreaMeasurement()

double QgsDistanceArea::convertAreaMeasurement ( double  area,
QgsUnitTypes::AreaUnit  toUnits 
) const

Takes an area measurement calculated by this QgsDistanceArea object and converts it to a different areal unit.

Parameters
areaarea value calculated by this class to convert. It is assumed that the area was calculated by this class, ie that its unit of area is equal to areaUnits().
toUnitsarea unit to convert measurement to
Returns
converted area
See also
convertLengthMeasurement()
Since
QGIS 2.14

Definition at line 992 of file qgsdistancearea.cpp.

◆ convertLengthMeasurement()

double QgsDistanceArea::convertLengthMeasurement ( double  length,
QgsUnitTypes::DistanceUnit  toUnits 
) const

Takes a length measurement calculated by this QgsDistanceArea object and converts it to a different distance unit.

Parameters
lengthlength value calculated by this class to convert. It is assumed that the length was calculated by this class, ie that its unit of length is equal to lengthUnits().
toUnitsdistance unit to convert measurement to
Returns
converted distance
See also
convertAreaMeasurement()
Since
QGIS 2.14

Definition at line 978 of file qgsdistancearea.cpp.

◆ ellipsoid()

QString QgsDistanceArea::ellipsoid ( ) const
inline

Returns ellipsoid's acronym.

Calculations will only use the ellipsoid if a valid ellipsoid has been set.

See also
setEllipsoid()
willUseEllipsoid()
ellipsoidCrs()

Definition at line 120 of file qgsdistancearea.h.

◆ ellipsoidCrs()

QgsCoordinateReferenceSystem QgsDistanceArea::ellipsoidCrs ( ) const
inline

Returns the ellipsoid (destination) spatial reference system.

See also
sourceCrs()
ellipsoid()
Since
QGIS 3.6

Definition at line 92 of file qgsdistancearea.h.

◆ ellipsoidInverseFlattening()

double QgsDistanceArea::ellipsoidInverseFlattening ( ) const
inline

Returns ellipsoid's inverse flattening.

The inverse flattening is calculated with invf = a/(a-b).

See also
ellipsoid()
ellipsoidSemiMajor()
ellipsoidSemiMinor()

Definition at line 145 of file qgsdistancearea.h.

◆ ellipsoidSemiMajor()

double QgsDistanceArea::ellipsoidSemiMajor ( ) const
inline

Returns the ellipsoid's semi major axis.

See also
ellipsoid()
ellipsoidSemiMinor()
ellipsoidInverseFlattening()

Definition at line 128 of file qgsdistancearea.h.

◆ ellipsoidSemiMinor()

double QgsDistanceArea::ellipsoidSemiMinor ( ) const
inline

Returns ellipsoid's semi minor axis.

See also
ellipsoid()
ellipsoidSemiMajor()
ellipsoidInverseFlattening()

Definition at line 136 of file qgsdistancearea.h.

◆ formatArea()

QString QgsDistanceArea::formatArea ( double  area,
int  decimals,
QgsUnitTypes::AreaUnit  unit,
bool  keepBaseUnit = false 
)
static

Returns an area formatted as a friendly string.

Parameters
areaarea to format
decimalsnumber of decimal places to show
unitunit of area
keepBaseUnitset to false to allow conversion of large areas to more suitable units, e.g., square meters to square kilometers
Returns
formatted area string
See also
formatDistance()
Since
QGIS 2.14

Definition at line 973 of file qgsdistancearea.cpp.

◆ formatDistance()

QString QgsDistanceArea::formatDistance ( double  distance,
int  decimals,
QgsUnitTypes::DistanceUnit  unit,
bool  keepBaseUnit = false 
)
static

Returns an distance formatted as a friendly string.

Parameters
distancedistance to format
decimalsnumber of decimal places to show
unitunit of distance
keepBaseUnitset to false to allow conversion of large distances to more suitable units, e.g., meters to kilometers
Returns
formatted distance string
See also
formatArea()
Since
QGIS 2.16

Definition at line 968 of file qgsdistancearea.cpp.

◆ geodesicLine()

QVector< QVector< QgsPointXY > > QgsDistanceArea::geodesicLine ( const QgsPointXY p1,
const QgsPointXY p2,
double  interval,
bool  breakLine = false 
) const

Calculates the geodesic line between p1 and p2, which represents the shortest path on the ellipsoid between these two points.

The ellipsoid settings defined on this QgsDistanceArea object will be used during the calculations.

p1 and p2 must be in the sourceCrs() of this QgsDistanceArea object. The returned line will also be in this same CRS.

The interval parameter gives the maximum distance between points on the computed line. 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 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.

Since
QGIS 3.6

Definition at line 672 of file qgsdistancearea.cpp.

◆ latitudeGeodesicCrossesAntimeridian()

double QgsDistanceArea::latitudeGeodesicCrossesAntimeridian ( const QgsPointXY p1,
const QgsPointXY p2,
double &  fractionAlongLine 
) const

Calculates the latitude at which the geodesic line joining p1 and p2 crosses the antimeridian (longitude +/- 180 degrees).

The ellipsoid settings defined on this QgsDistanceArea object will be used during the calculations.

p1 and p2 must be in the ellipsoidCrs() of this QgsDistanceArea object. The returned latitude will also be in this same CRS.

Parameters
p1Starting point, in ellipsoidCrs()
p2Ending point, in ellipsoidCrs()
fractionAlongLinewill be set to the fraction along the geodesic line joining p1 to p2 at which the antimeridian crossing occurs.
Returns
the latitude at which the geodesic crosses the antimeridian
See also
splitGeometryAtAntimeridian()
Since
QGIS 3.6

Definition at line 456 of file qgsdistancearea.cpp.

◆ lengthUnits()

QgsUnitTypes::DistanceUnit QgsDistanceArea::lengthUnits ( ) const

Returns the units of distance for length calculations made by this object.

See also
areaUnits()
Since
QGIS 2.14

Definition at line 790 of file qgsdistancearea.cpp.

◆ measureArea()

double QgsDistanceArea::measureArea ( const QgsGeometry geometry) const

Measures the area of a geometry.

Parameters
geometrygeometry to measure
Returns
area of geometry. For geometry collections, non surface geometries will be ignored. The units for the returned area can be retrieved by calling areaUnits().
See also
measureLength()
measurePerimeter()
areaUnits()
Since
QGIS 2.12

Definition at line 208 of file qgsdistancearea.cpp.

◆ measureLength()

double QgsDistanceArea::measureLength ( const QgsGeometry geometry) const

Measures the length of a geometry.

Parameters
geometrygeometry to measure
Returns
length of geometry. For geometry collections, non curve geometries will be ignored. The units for the returned distance can be retrieved by calling lengthUnits().
See also
lengthUnits()
measureArea()
measurePerimeter()
Since
QGIS 2.12

Definition at line 217 of file qgsdistancearea.cpp.

◆ measureLine() [1/2]

double QgsDistanceArea::measureLine ( const QgsPointXY p1,
const QgsPointXY p2 
) const

Measures the distance between two points.

Parameters
p1start of line
p2end of line
Returns
distance between points. The units for the returned distance can be retrieved by calling lengthUnits().
See also
lengthUnits()

Definition at line 354 of file qgsdistancearea.cpp.

◆ measureLine() [2/2]

double QgsDistanceArea::measureLine ( const QVector< QgsPointXY > &  points) const

Measures the length of a line with multiple segments.

Parameters
pointslist of points in line
Returns
length of line. The units for the returned length can be retrieved by calling lengthUnits().
See also
lengthUnits()

Definition at line 298 of file qgsdistancearea.cpp.

◆ measureLineProjected()

double QgsDistanceArea::measureLineProjected ( const QgsPointXY p1,
double  distance = 1,
double  azimuth = M_PI_2,
QgsPointXY projectedPoint = nullptr 
) const

Calculates the distance from one point with distance in meters and azimuth (direction) When the sourceCrs() is geographic, computeSpheroidProject() will be called otherwise QgsPoint.project() will be called after QgsUnitTypes::fromUnitToUnitFactor() has been applied to the distance.

Parameters
p1start point [can be Cartesian or Geographic]
distancemust be in meters
azimuth- azimuth in radians, clockwise from North
projectedPointcalculated projected point
Returns
distance in mapUnits
See also
sourceCrs()
computeSpheroidProject()
Note
The input Point must be in the coordinate reference system being used
Since
QGIS 3.0

Definition at line 401 of file qgsdistancearea.cpp.

◆ measurePerimeter()

double QgsDistanceArea::measurePerimeter ( const QgsGeometry geometry) const

Measures the perimeter of a polygon geometry.

Parameters
geometrygeometry to measure
Returns
perimeter of geometry. For geometry collections, any non-polygon geometries will be ignored. The units for the returned perimeter can be retrieved by calling lengthUnits().
See also
lengthUnits()
measureArea()
measurePerimeter()
Since
QGIS 2.12

Definition at line 226 of file qgsdistancearea.cpp.

◆ measurePolygon()

double QgsDistanceArea::measurePolygon ( const QVector< QgsPointXY > &  points) const

Measures the area of the polygon described by a set of points.

Definition at line 816 of file qgsdistancearea.cpp.

◆ operator=()

QgsDistanceArea & QgsDistanceArea::operator= ( const QgsDistanceArea other)

Definition at line 67 of file qgsdistancearea.cpp.

◆ setEllipsoid() [1/2]

bool QgsDistanceArea::setEllipsoid ( const QString &  ellipsoid)

Sets the ellipsoid by its acronym.

Known ellipsoid acronyms can be retrieved using QgsEllipsoidUtils::acronyms(). Calculations will only use the ellipsoid if a valid ellipsoid has been set.

Returns
true if ellipsoid was successfully set
See also
ellipsoid()
willUseEllipsoid()

Definition at line 89 of file qgsdistancearea.cpp.

◆ setEllipsoid() [2/2]

bool QgsDistanceArea::setEllipsoid ( double  semiMajor,
double  semiMinor 
)

Sets ellipsoid by supplied radii.

Calculations will only use the ellipsoid if a valid ellipsoid been set.

Returns
true if ellipsoid was successfully set
See also
ellipsoid()
willUseEllipsoid()

Definition at line 115 of file qgsdistancearea.cpp.

◆ setSourceCrs()

void QgsDistanceArea::setSourceCrs ( const QgsCoordinateReferenceSystem crs,
const QgsCoordinateTransformContext context 
)

Sets source spatial reference system crs.

See also
sourceCrs()
Since
QGIS 2.2

Definition at line 83 of file qgsdistancearea.cpp.

◆ sourceCrs()

QgsCoordinateReferenceSystem QgsDistanceArea::sourceCrs ( ) const
inline

Returns the source spatial reference system.

See also
setSourceCrs()
ellipsoidCrs()

Definition at line 84 of file qgsdistancearea.h.

◆ splitGeometryAtAntimeridian()

QgsGeometry QgsDistanceArea::splitGeometryAtAntimeridian ( const QgsGeometry geometry) const

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 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.

The ellipsoid settings defined on this QgsDistanceArea object will be used during the calculations.

geometry must be in the sourceCrs() of this QgsDistanceArea object. The returned geometry 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 antimeridian.

Note
Non-(Multi)LineString geometries will be returned unchanged.
See also
latitudeGeodesicCrossesAntimeridian()
Since
QGIS 3.6

Definition at line 545 of file qgsdistancearea.cpp.

◆ willUseEllipsoid()

bool QgsDistanceArea::willUseEllipsoid ( ) const

Returns whether calculations will use the ellipsoid.

Calculations will only use the ellipsoid if a valid ellipsoid() has been set.

See also
ellipsoid()
Since
QGIS 2.14

Definition at line 78 of file qgsdistancearea.cpp.


The documentation for this class was generated from the following files: