QgsDistanceArea class

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

Contents

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

Public static functions

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

Constructors, destructors, conversion operators

QgsDistanceArea()
Constructor.

Public functions

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

Function documentation

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

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

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

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

QgsUnitTypes::AreaUnit QgsDistanceArea::areaUnits() const

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

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.

Based on Vincenty's formula for the geodetic direct problem as described in "Geocentric Datum of Australia Technical Manual", Chapter 4.

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

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

QString QgsDistanceArea::ellipsoid() const

Returns ellipsoid's acronym.

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

QgsCoordinateReferenceSystem QgsDistanceArea::ellipsoidCrs() const

Returns the ellipsoid (destination) spatial reference system.

double QgsDistanceArea::ellipsoidInverseFlattening() const

Returns ellipsoid's inverse flattening.

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

double QgsDistanceArea::ellipsoidSemiMajor() const

Returns the ellipsoid's semi major axis.

double QgsDistanceArea::ellipsoidSemiMinor() const

Returns ellipsoid's semi minor axis.

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.

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

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

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.

QgsUnitTypes::DistanceUnit QgsDistanceArea::lengthUnits() const

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

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

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

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

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

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

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

bool QgsDistanceArea::setEllipsoid(const QString& ellipsoid)

Sets the ellipsoid by its acronym.

Returns true if ellipsoid was successfully set

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

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

Sets ellipsoid by supplied radii.

Returns true if ellipsoid was successfully set

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

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

Sets source spatial reference system crs.

QgsCoordinateReferenceSystem QgsDistanceArea::sourceCrs() const

Returns the source spatial reference system.

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.

bool QgsDistanceArea::willUseEllipsoid() const

Returns whether calculations will use the ellipsoid.

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