Class: QgsDistanceArea¶
- class qgis.core.QgsDistanceArea¶
Bases:
sip.wrapper
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 theQgsDistanceArea
, 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 callingwillUseEllipsoid()
.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 callinglengthUnits()
andareaUnits()
.Internally, the GeographicLib library is used to calculate all ellipsoid based measurements.
QgsDistanceArea() Constructor
QgsDistanceArea(other:
QgsDistanceArea
) Copy constructorMethods
Returns the units of area for areal calculations made by this object.
Computes the bearing (in radians) between two points.
Given a location, an azimuth and a distance, computes the location of the projected point.
Takes an area measurement calculated by this
QgsDistanceArea
object and converts it to a different areal unit.Takes a length measurement calculated by this
QgsDistanceArea
object and converts it to a different distance unit.Returns ellipsoid's acronym.
Returns the ellipsoid (destination) spatial reference system.
Returns ellipsoid's inverse flattening.
Returns the ellipsoid's semi major axis.
Returns ellipsoid's semi minor axis.
Returns an area formatted as a friendly string.
Returns an distance formatted as a friendly string.
Calculates the geodesic line between
p1
andp2
, which represents the shortest path on the ellipsoid between these two points.Calculates the latitude at which the geodesic line joining
p1
andp2
crosses the antimeridian (longitude +/- 180 degrees).Returns the units of distance for length calculations made by this object.
Measures the area of a geometry.
Measures the length of a geometry.
Measures the length of a line with multiple segments.
Calculates the distance from one point with distance in meters and azimuth (direction) When the
sourceCrs()
is geographic,computeSpheroidProject()
will be called otherwiseQgsPoint.project()
will be called afterQgsUnitTypes.fromUnitToUnitFactor()
has been applied to the distanceMeasures the perimeter of a polygon geometry.
Measures the area of the polygon described by a set of points.
Sets the
ellipsoid
by its acronym.Sets source spatial reference system
crs
.Returns the source spatial reference system.
Splits a (Multi)LineString
geometry
at the antimeridian (longitude +/- 180 degrees).Returns whether calculations will use the ellipsoid.
- areaUnits(self) Qgis.AreaUnit ¶
Returns the units of area for areal calculations made by this object.
See also
- Return type:
- bearing(self, p1: QgsPointXY, p2: QgsPointXY) float ¶
Computes the bearing (in radians) between two points.
- Raises:
QgsCsException – on invalid input coordinates
- Parameters:
p1 (QgsPointXY) –
p2 (QgsPointXY) –
- 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.
- 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:
- Returns:
p2 - location of projected point as longitude/latitude.
- convertAreaMeasurement(self, area: float, toUnits: Qgis.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 (Qgis.AreaUnit) – area unit to convert measurement to
- Return type:
float
- Returns:
converted area
See also
- convertLengthMeasurement(self, length: float, toUnits: Qgis.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 (Qgis.DistanceUnit) – distance unit to convert measurement to
- Return type:
float
- Returns:
converted distance
See also
- ellipsoid(self) str ¶
Returns ellipsoid’s acronym. Calculations will only use the ellipsoid if a valid ellipsoid has been set.
See also
See also
See also
- Return type:
str
- ellipsoidCrs(self) QgsCoordinateReferenceSystem ¶
Returns the ellipsoid (destination) spatial reference system.
See also
See also
New in version 3.6.
- Return type:
- ellipsoidInverseFlattening(self) float ¶
Returns ellipsoid’s inverse flattening. The inverse flattening is calculated with invf = a/(a-b).
See also
See also
See also
- Return type:
float
- ellipsoidSemiMajor(self) float ¶
Returns the ellipsoid’s semi major axis.
See also
See also
See also
- Return type:
float
- ellipsoidSemiMinor(self) float ¶
Returns ellipsoid’s semi minor axis.
See also
See also
See also
- Return type:
float
- formatArea(area: float, decimals: int, unit: Qgis.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 (Qgis.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(distance: float, decimals: int, unit: Qgis.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 (Qgis.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
- geodesicLine(self, p1: QgsPointXY, p2: QgsPointXY, interval: float, breakLine: bool = False) object ¶
Calculates the geodesic line between
p1
andp2
, 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
andp2
must be in thesourceCrs()
of thisQgsDistanceArea
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
isTrue
, 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:
p1 (QgsPointXY) –
p2 (QgsPointXY) –
interval (float) –
breakLine (bool = False) –
- Return type:
object
- latitudeGeodesicCrossesAntimeridian(self, p1: QgsPointXY, p2: QgsPointXY) Tuple[float, float] ¶
Calculates the latitude at which the geodesic line joining
p1
andp2
crosses the antimeridian (longitude +/- 180 degrees).The ellipsoid settings defined on this
QgsDistanceArea
object will be used during the calculations.p1
andp2
must be in theellipsoidCrs()
of thisQgsDistanceArea
object. The returned latitude will also be in this same CRS.- Parameters:
p1 (QgsPointXY) – Starting point, in
ellipsoidCrs()
p2 (QgsPointXY) – Ending point, in
ellipsoidCrs()
- 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
top2
at which the antimeridian crossing occurs.
See also
New in version 3.6.
- lengthUnits(self) Qgis.DistanceUnit ¶
Returns the units of distance for length calculations made by this object.
See also
- Return type:
- 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
See also
See also
- 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
See also
See also
- 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
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
- 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 otherwiseQgsPoint.project()
will be called afterQgsUnitTypes.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
See also
Note
The input Point must be in the coordinate reference system being used
- 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
See also
See also
- 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 usingQgsEllipsoidUtils.acronyms()
. Calculations will only use the ellipsoid if a valid ellipsoid has been set.- Returns:
True
if ellipsoid was successfully set
See also
See also
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
See also
- Parameters:
ellipsoid (str) –
- setSourceCrs(self, crs: QgsCoordinateReferenceSystem, context: QgsCoordinateTransformContext)¶
Sets source spatial reference system
crs
.See also
- Parameters:
crs (QgsCoordinateReferenceSystem) –
context (QgsCoordinateTransformContext) –
- sourceCrs(self) QgsCoordinateReferenceSystem ¶
Returns the source spatial reference system.
See also
See also
- Return type:
- 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 thesourceCrs()
of thisQgsDistanceArea
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:
- 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
- Return type:
bool