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
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 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.
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 otherwise QgsPoint.project() will be called after QgsUnitTypes.fromUnitToUnitFactor() has been applied to the distance
Measures 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.
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
New in version 2.14.
- Return type
-
bearing
(self, p1: QgsPointXY, p2: QgsPointXY) → float¶ Computes the bearing (in radians) between two points.
- 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. 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
- 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
See also
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
See also
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
See also
- Return type
str
-
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: 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
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
New in version 2.16.
-
lengthUnits
(self) → QgsUnitTypes.DistanceUnit¶ Returns the units of distance for length calculations made by this object.
See also
New in version 2.14.
- 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
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
See also
See also
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
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 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
projectedPoint – calculated projected point
- Return type
Tuple[float, QgsPointXY]
- Returns
distance in mapUnits
See also
See also
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
See also
See also
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 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
New in version 2.2.
- Parameters
crs (QgsCoordinateReferenceSystem) –
context (QgsCoordinateTransformContext) –
-
sourceCrs
(self) → QgsCoordinateReferenceSystem¶ Returns the source spatial reference system.
See also
- 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
New in version 2.14.
- Return type
bool
-