Class: QgsDistanceArea

class qgis.core.QgsDistanceArea

Bases: sip.wrapper

Constructor

QgsDistanceArea(QgsDistanceArea)

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

Methods

areaUnits

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

bearing

Computes the bearing (in radians) between two points.

computeSpheroidProject

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

convertAreaMeasurement

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

convertLengthMeasurement

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

ellipsoid

Returns ellipsoid's acronym.

ellipsoidCrs

Returns the ellipsoid (destination) spatial reference system.

ellipsoidInverseFlattening

Returns ellipsoid's inverse flattening.

ellipsoidSemiMajor

Returns the ellipsoid's semi major axis.

ellipsoidSemiMinor

Returns ellipsoid's semi minor axis.

formatArea

Returns an area formatted as a friendly string.

formatDistance

Returns an distance formatted as a friendly string.

geodesicLine

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

latitudeGeodesicCrossesAntimeridian

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

lengthUnits

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

measureArea

Measures the area of a geometry.

measureLength

Measures the length of a geometry.

measureLine

Measures the length of a line with multiple segments.

measureLineProjected

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

measurePerimeter

Measures the perimeter of a polygon geometry.

measurePolygon

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

setEllipsoid

Sets the ellipsoid by its acronym.

setSourceCrs

Sets source spatial reference system crs.

sourceCrs

Returns the source spatial reference system.

splitGeometryAtAntimeridian

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

willUseEllipsoid

Returns whether calculations will use the ellipsoid.

areaUnits(self) QgsUnitTypes.AreaUnit

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

See also

lengthUnits()

New in version 2.14.

Return type

QgsUnitTypes.AreaUnit

bearing(self, p1: QgsPointXY, p2: QgsPointXY) float

Computes the bearing (in radians) between two points.

Parameters
Return type

float

computeSpheroidProject(self, p1: QgsPointXY, distance: float = 1, azimuth: float = M_PI_2) QgsPointXY

Given a location, an azimuth and a distance, computes the location of the projected point. Based on Vincenty’s formula for the geodetic direct problem as described in “Geocentric Datum of Australia Technical Manual”, Chapter 4.

Parameters
  • p1 (QgsPointXY) –

    • location of first geographic (latitude/longitude) point as degrees.

  • distance (float = 1) –

    • distance in meters.

  • azimuth (float = M_PI_2) –

    • azimuth in radians, clockwise from North

Return type

QgsPointXY

Returns

p2 - location of projected point as longitude/latitude.

Note

code (and documentation) taken from rttopo project https://git.osgeo.org/gogs/rttopo/librttopo

  • spheroid_project.spheroid_project(…)

  • Valid bounds checking for degrees (latitude=+- 85.05115) is based values used for

-> ‘WGS84 Web Mercator (Auxiliary Sphere)’ calculations –> latitudes outside these bounds cause the calculations to become unstable and can return invalid results

New in version 3.0.

convertAreaMeasurement(self, area: float, toUnits: QgsUnitTypes.AreaUnit) float

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

Parameters
  • area (float) – 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 (QgsUnitTypes.AreaUnit) – area unit to convert measurement to

Return type

float

Returns

converted area

New in version 2.14.

convertLengthMeasurement(self, length: float, toUnits: QgsUnitTypes.DistanceUnit) float

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

Parameters
  • length (float) – 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 (QgsUnitTypes.DistanceUnit) – distance unit to convert measurement to

Return type

float

Returns

converted distance

New in version 2.14.

ellipsoid(self) str

Returns ellipsoid’s acronym. Calculations will only use the ellipsoid if a valid ellipsoid has been set.

See also

setEllipsoid()

See also

ellipsoidCrs()

Return type

str

ellipsoidCrs(self) QgsCoordinateReferenceSystem

Returns the ellipsoid (destination) spatial reference system.

See also

sourceCrs()

See also

ellipsoid()

New in version 3.6.

Return type

QgsCoordinateReferenceSystem

ellipsoidInverseFlattening(self) float

Returns ellipsoid’s inverse flattening. The inverse flattening is calculated with invf = a/(a-b).

See also

ellipsoid()

Return type

float

ellipsoidSemiMajor(self) float

Returns the ellipsoid’s semi major axis.

See also

ellipsoid()

Return type

float

ellipsoidSemiMinor(self) float

Returns ellipsoid’s semi minor axis.

See also

ellipsoid()

Return type

float

formatArea(area: float, decimals: int, unit: QgsUnitTypes.AreaUnit, keepBaseUnit: bool = False) str

Returns an area formatted as a friendly string.

Parameters
  • area (float) – area to format

  • decimals (int) – number of decimal places to show

  • unit (QgsUnitTypes.AreaUnit) – unit of area

  • keepBaseUnit (bool = False) – set to False to allow conversion of large areas to more suitable units, e.g., square meters to square kilometers

Return type

str

Returns

formatted area string

See also

formatDistance()

New in version 2.14.

formatDistance(distance: float, decimals: int, unit: QgsUnitTypes.DistanceUnit, keepBaseUnit: bool = False) str

Returns an distance formatted as a friendly string.

Parameters
  • distance (float) – distance to format

  • decimals (int) – number of decimal places to show

  • unit (QgsUnitTypes.DistanceUnit) – unit of distance

  • keepBaseUnit (bool = False) – set to False to allow conversion of large distances to more suitable units, e.g., meters to kilometers

Return type

str

Returns

formatted distance string

See also

formatArea()

New in version 2.16.

geodesicLine(self, p1: QgsPointXY, p2: QgsPointXY, interval: float, breakLine: bool = False) object

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.

New in version 3.6.

Parameters
Return type

object

latitudeGeodesicCrossesAntimeridian(self, p1: QgsPointXY, p2: QgsPointXY) Tuple[float, float]

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

Tuple[float, float]

Returns

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

New in version 3.6.

lengthUnits(self) QgsUnitTypes.DistanceUnit

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

See also

areaUnits()

New in version 2.14.

Return type

QgsUnitTypes.DistanceUnit

measureArea(self, geometry: QgsGeometry) float

Measures the area of a geometry.

Parameters

geometry (QgsGeometry) – geometry to measure

Return type

float

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

See also

areaUnits()

New in version 2.12.

measureLength(self, geometry: QgsGeometry) float

Measures the length of a geometry.

Parameters

geometry (QgsGeometry) – geometry to measure

Return type

float

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

See also

measureArea()

New in version 2.12.

measureLine(self, points: Iterable[QgsPointXY]) float

Measures the length of a line with multiple segments.

Parameters

points (Iterable[QgsPointXY]) – list of points in line

Returns

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

See also

lengthUnits()

measureLine(self, p1: QgsPointXY, p2: QgsPointXY) -> float Measures the distance between two points.

Parameters
  • p1 – start of line

  • p2 – end of line

Return type

float

Returns

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

See also

lengthUnits()

measureLineProjected(self, p1: QgsPointXY, distance: float = 1, azimuth: float = M_PI_2) Tuple[float, QgsPointXY]

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 (QgsPointXY) – start point [can be Cartesian or Geographic]

  • distance (float = 1) – must be in meters

  • azimuth (float = M_PI_2) –

    • azimuth in radians, clockwise from North

Return type

Tuple[float, QgsPointXY]

Returns

  • distance in mapUnits

  • projectedPoint: calculated projected point

See also

sourceCrs()

Note

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

New in version 3.0.

measurePerimeter(self, geometry: QgsGeometry) float

Measures the perimeter of a polygon geometry.

Parameters

geometry (QgsGeometry) – geometry to measure

Return type

float

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

See also

measureArea()

New in version 2.12.

measurePolygon(self, points: Iterable[QgsPointXY]) float

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

Parameters

points (Iterable[QgsPointXY]) –

Return type

float

setEllipsoid(self, ellipsoid: str) bool

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

setEllipsoid(self, semiMajor: float, semiMinor: float) -> bool Sets ellipsoid by supplied radii. Calculations will only use the ellipsoid if a valid ellipsoid been set.

Return type

bool

Returns

True if ellipsoid was successfully set

See also

ellipsoid()

Parameters

ellipsoid (str) –

setSourceCrs(self, crs: QgsCoordinateReferenceSystem, context: QgsCoordinateTransformContext)

Sets source spatial reference system crs.

See also

sourceCrs()

New in version 2.2.

Parameters
sourceCrs(self) QgsCoordinateReferenceSystem

Returns the source spatial reference system.

See also

setSourceCrs()

See also

ellipsoidCrs()

Return type

QgsCoordinateReferenceSystem

splitGeometryAtAntimeridian(self, geometry: QgsGeometry) QgsGeometry

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.

New in version 3.6.

Parameters

geometry (QgsGeometry) –

Return type

QgsGeometry

willUseEllipsoid(self) bool

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

See also

ellipsoid()

New in version 2.14.

Return type

bool