Subgroup: other
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 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. 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. 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) 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. willUseEllipsoid
Returns whether calculations will use the ellipsoid. Attributes
-
areaUnits
(self) → QgsUnitTypes.AreaUnit¶ Returns the units of area for areal calculations made by this object.
New in version 2.14.
See also
-
bearing
(self, p1: QgsPointXY, p2: QgsPointXY) → float¶ Computes the bearing (in radians) between two points.
-
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 –
- 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.
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.
- p1 –
-
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 – 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(). :param toUnits: area unit to convert measurement to
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 – 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(). :param toUnits: distance unit to convert measurement to
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
-
ellipsoidInverseFlattening
(self) → float¶ Returns ellipsoid’s inverse flattening. The inverse flattening is calculated with invf = a/(a-b).
See also
See also
See also
-
ellipsoidSemiMajor
(self) → float¶ Returns the ellipsoid’s semi major axis.
See also
See also
See also
-
ellipsoidSemiMinor
(self) → float¶ Returns ellipsoid’s semi minor axis.
See also
See also
See also
-
formatArea
(area: float, decimals: int, unit: QgsUnitTypes.AreaUnit, keepBaseUnit: bool = False) → str¶ 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 New in version 2.14.
See also
-
formatDistance
(distance: float, decimals: int, unit: QgsUnitTypes.DistanceUnit, keepBaseUnit: bool = False) → str¶ 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 New in version 2.16.
See also
-
lengthUnits
(self) → QgsUnitTypes.DistanceUnit¶ Returns the units of distance for length calculations made by this object.
See also
New in version 2.14.
-
measureArea
(self, geometry: QgsGeometry) → float¶ 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().
New in version 2.12.
See also
See also
See also
-
measureLength
(self, geometry: QgsGeometry) → float¶ 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().
New in version 2.12.
See also
See also
See also
-
measureLine
(self, points: Iterable[QgsPointXY]) → float¶ 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(). See also
measureLine(self, p1: QgsPointXY, p2: QgsPointXY) -> float 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().
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 – 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
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 – 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().
New in version 2.12.
See also
See also
See also
-
measurePolygon
(self, points: Iterable[QgsPointXY]) → float¶ Measures the area of the polygon described by a set of points.
-
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.
Returns: true if ellipsoid was successfully set See also
See also
-
setSourceCrs
(self, crs: QgsCoordinateReferenceSystem, context: QgsCoordinateTransformContext)¶ Sets source spatial reference system
crs
.New in version 2.2.
See also
-
sourceCrs
(self) → QgsCoordinateReferenceSystem¶ Returns the source spatial reference system.
See also
-
willUseEllipsoid
(self) → bool¶ Returns whether calculations will use the ellipsoid. Calculations will only use the ellipsoid if a valid ellipsoid() has been set.
New in version 2.14.
See also
-