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

#include <qgsdistancearea.h>

Public Member Functions
	QgsDistanceArea ()

	QgsDistanceArea (const QgsDistanceArea &other)

	~QgsDistanceArea ()

Qgis::AreaUnit	areaUnits () const
	Returns the units of area for areal calculations made by this object.

double	bearing (const QgsPointXY &p1, const QgsPointXY &p2) const
	Computes the bearing (in radians) between two points.

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.

double	convertAreaMeasurement (double area, Qgis::AreaUnit toUnits) const
	Takes an area measurement calculated by this QgsDistanceArea object and converts it to a different areal unit.

double	convertLengthMeasurement (double length, Qgis::DistanceUnit toUnits) const
	Takes a length measurement calculated by this QgsDistanceArea object and converts it to a different distance unit.

QString	ellipsoid () const
	Returns ellipsoid's acronym.

QgsCoordinateReferenceSystem	ellipsoidCrs () const
	Returns the ellipsoid (destination) spatial reference system.

double	ellipsoidInverseFlattening () const
	Returns ellipsoid's inverse flattening.

double	ellipsoidSemiMajor () const
	Returns the ellipsoid's semi major axis.

double	ellipsoidSemiMinor () const
	Returns ellipsoid's semi minor axis.

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.

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

Qgis::DistanceUnit	lengthUnits () const
	Returns the units of distance for length calculations made by this object.

double	measureArea (const QgsGeometry &geometry) const
	Measures the area of a geometry.

double	measureLength (const QgsGeometry &geometry) const
	Measures the length of a geometry.

double	measureLine (const QgsPointXY &p1, const QgsPointXY &p2) const
	Measures the distance between two points.

double	measureLine (const QVector< QgsPointXY > &points) const
	Measures the length of a line with multiple segments.

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.

double	measurePerimeter (const QgsGeometry &geometry) const
	Measures the perimeter of a polygon geometry.

double	measurePolygon (const QVector< QgsPointXY > &points) const
	Measures the area of the polygon described by a set of points.

QgsDistanceArea &	operator= (const QgsDistanceArea &other)

bool	setEllipsoid (const QString &ellipsoid)
	Sets the ellipsoid by its acronym.

bool	setEllipsoid (double semiMajor, double semiMinor)
	Sets ellipsoid by supplied radii.

void	setSourceCrs (const QgsCoordinateReferenceSystem &crs, const QgsCoordinateTransformContext &context)
	Sets source spatial reference system crs.

QgsCoordinateReferenceSystem	sourceCrs () const
	Returns the source spatial reference system.

QgsGeometry	splitGeometryAtAntimeridian (const QgsGeometry &geometry) const
	Splits a (Multi)LineString geometry at the antimeridian (longitude +/- 180 degrees).

bool	willUseEllipsoid () const
	Returns whether calculations will use the ellipsoid.

Static Public Member Functions
static QString	formatArea (double area, int decimals, Qgis::AreaUnit unit, bool keepBaseUnit=false)
	Returns an area formatted as a friendly string.

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

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 ( )

Definition at line 44 of file qgsdistancearea.cpp.

◆ ~QgsDistanceArea()

QgsDistanceArea::~QgsDistanceArea ( )

default

◆ QgsDistanceArea() [2/2]

QgsDistanceArea::QgsDistanceArea ( const QgsDistanceArea & other )

Definition at line 57 of file qgsdistancearea.cpp.

Member Function Documentation

◆ areaUnits()

Qgis::AreaUnit QgsDistanceArea::areaUnits ( ) const

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

See also: lengthUnits()

Definition at line 785 of file qgsdistancearea.cpp.

◆ bearing()

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

Computes the bearing (in radians) between two points.

Exceptions

QgsCsException on invalid input coordinates

Definition at line 824 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.

Definition at line 430 of file qgsdistancearea.cpp.

◆ convertAreaMeasurement()

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

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

Parameters

area	area 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().
toUnits	area unit to convert measurement to

Returns: converted area

See also: convertLengthMeasurement()

Definition at line 973 of file qgsdistancearea.cpp.

◆ convertLengthMeasurement()

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

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

Parameters

length	length 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().
toUnits	distance unit to convert measurement to

Returns: converted distance

See also: convertAreaMeasurement()

Definition at line 959 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 116 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 88 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 141 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 124 of file qgsdistancearea.h.

◆ ellipsoidSemiMinor()

double QgsDistanceArea::ellipsoidSemiMinor ( ) const

inline

Returns ellipsoid's semi minor axis.

See also: ellipsoid(); ellipsoidSemiMajor(); ellipsoidInverseFlattening()

Definition at line 132 of file qgsdistancearea.h.

◆ formatArea()

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

static

Returns an area formatted as a friendly string.

Parameters

area	area to format
decimals	number of decimal places to show
unit	unit of area
keepBaseUnit	set 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()

Definition at line 954 of file qgsdistancearea.cpp.

◆ formatDistance()

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

static

Returns an distance formatted as a friendly string.

Parameters

distance	distance to format
decimals	number of decimal places to show
unit	unit of distance
keepBaseUnit	set to `false` to allow conversion of large distances to more suitable units, e.g., meters to kilometers

Returns: formatted distance string

See also: formatArea()

Definition at line 949 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 662 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

p1	Starting point, in ellipsoidCrs()
p2	Ending point, in ellipsoidCrs()
fractionAlongLine	will 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 446 of file qgsdistancearea.cpp.

◆ lengthUnits()

Qgis::DistanceUnit QgsDistanceArea::lengthUnits ( ) const

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

See also: areaUnits()

Definition at line 780 of file qgsdistancearea.cpp.

◆ measureArea()

double QgsDistanceArea::measureArea ( const QgsGeometry & geometry ) const

Measures the area of a geometry.

Parameters

geometry geometry 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()

Exceptions

QgsCsException if a transformation error occurs while calculating the area

Definition at line 212 of file qgsdistancearea.cpp.

◆ measureLength()

double QgsDistanceArea::measureLength ( const QgsGeometry & geometry ) const

Measures the length of a geometry.

Parameters

geometry geometry 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()

Exceptions

QgsCsException if a transformation error occurs while calculating the length

Definition at line 221 of file qgsdistancearea.cpp.

◆ measureLine() [1/2]

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

Measures the distance between two points.

Parameters

p1	start of line
p2	end of line

Returns: distance between points. The units for the returned distance can be retrieved by calling lengthUnits().

Exceptions

QgsCsException if a transformation error occurs while calculating the length

See also: lengthUnits()

Definition at line 352 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

points list of points in line

Returns: length of line. The units for the returned length can be retrieved by calling lengthUnits().

Exceptions

QgsCsException if a transformation error occurs while calculating the length

See also: lengthUnits()

Definition at line 306 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

p1	start point [can be Cartesian or Geographic]
distance	must be in meters
azimuth	azimuth in radians, clockwise from North
projectedPoint	calculated projected point

Returns: distance in mapUnits

See also: sourceCrs(); computeSpheroidProject()

Note: The input Point must be in the coordinate reference system being used

Definition at line 391 of file qgsdistancearea.cpp.

◆ measurePerimeter()

double QgsDistanceArea::measurePerimeter ( const QgsGeometry & geometry ) const

Measures the perimeter of a polygon geometry.

Parameters

geometry geometry 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()

Exceptions

QgsCsException if a transformation error occurs while calculating the perimeter

Definition at line 230 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.

Exceptions

QgsCsException if a transformation error occurs while calculating the area.

Definition at line 806 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()

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 80 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 535 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()

Definition at line 78 of file qgsdistancearea.cpp.

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

/build/qgis-3.41.0+git20241122+3440c17df1d+99sid/src/core/qgsdistancearea.h
/build/qgis-3.41.0+git20241122+3440c17df1d+99sid/src/core/qgsdistancearea.cpp

Public Member Functions

Static Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ QgsDistanceArea() [1/2]

◆ ~QgsDistanceArea()

◆ QgsDistanceArea() [2/2]

Member Function Documentation

◆ areaUnits()

◆ bearing()

◆ computeSpheroidProject()

◆ convertAreaMeasurement()

◆ convertLengthMeasurement()

◆ ellipsoid()

◆ ellipsoidCrs()

◆ ellipsoidInverseFlattening()

◆ ellipsoidSemiMajor()

◆ ellipsoidSemiMinor()

◆ formatArea()

◆ formatDistance()

◆ geodesicLine()

◆ latitudeGeodesicCrossesAntimeridian()

◆ lengthUnits()

◆ measureArea()

◆ measureLength()

◆ measureLine() [1/2]

◆ measureLine() [2/2]

◆ measureLineProjected()

◆ measurePerimeter()

◆ measurePolygon()

◆ operator=()

◆ setEllipsoid() [1/2]

◆ setEllipsoid() [2/2]

◆ setSourceCrs()

◆ sourceCrs()

◆ splitGeometryAtAntimeridian()

◆ willUseEllipsoid()