QGIS API Documentation
3.17.0Master (fba5093f18)

A general purpose distance and area calculator, capable of performing ellipsoid based calculations. More...
#include <qgsdistancearea.h>
Public Member Functions  
QgsDistanceArea ()  
Constructor. More...  
QgsUnitTypes::AreaUnit  areaUnits () const 
Returns the units of area for areal calculations made by this object. More...  
double  bearing (const QgsPointXY &p1, const QgsPointXY &p2) const 
Computes the bearing (in radians) between two points. More...  
QgsPointXY  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. More...  
double  convertAreaMeasurement (double area, QgsUnitTypes::AreaUnit toUnits) const 
Takes an area measurement calculated by this QgsDistanceArea object and converts it to a different areal unit. More...  
double  convertLengthMeasurement (double length, QgsUnitTypes::DistanceUnit toUnits) const 
Takes a length measurement calculated by this QgsDistanceArea object and converts it to a different distance unit. More...  
QString  ellipsoid () const 
Returns ellipsoid's acronym. More...  
QgsCoordinateReferenceSystem  ellipsoidCrs () const 
Returns the ellipsoid (destination) spatial reference system. More...  
double  ellipsoidInverseFlattening () const 
Returns ellipsoid's inverse flattening. More...  
double  ellipsoidSemiMajor () const 
Returns the ellipsoid's semi major axis. More...  
double  ellipsoidSemiMinor () const 
Returns ellipsoid's semi minor axis. More...  
QVector< QVector< QgsPointXY > >  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. More...  
double  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). More...  
QgsUnitTypes::DistanceUnit  lengthUnits () const 
Returns the units of distance for length calculations made by this object. More...  
double  measureArea (const QgsGeometry &geometry) const 
Measures the area of a geometry. More...  
double  measureLength (const QgsGeometry &geometry) const 
Measures the length of a geometry. More...  
double  measureLine (const QVector< QgsPointXY > &points) const 
Measures the length of a line with multiple segments. More...  
double  measureLine (const QgsPointXY &p1, const QgsPointXY &p2) const 
Measures the distance between two points. More...  
double  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. More...  
double  measurePerimeter (const QgsGeometry &geometry) const 
Measures the perimeter of a polygon geometry. More...  
double  measurePolygon (const QVector< QgsPointXY > &points) const 
Measures the area of the polygon described by a set of points. More...  
bool  setEllipsoid (const QString &ellipsoid) 
Sets the ellipsoid by its acronym. More...  
bool  setEllipsoid (double semiMajor, double semiMinor) 
Sets ellipsoid by supplied radii. More...  
void  setSourceCrs (const QgsCoordinateReferenceSystem &crs, const QgsCoordinateTransformContext &context) 
Sets source spatial reference system crs. More...  
QgsCoordinateReferenceSystem  sourceCrs () const 
Returns the source spatial reference system. More...  
QgsGeometry  splitGeometryAtAntimeridian (const QgsGeometry &geometry) const 
Splits a (Multi)LineString geometry at the antimeridian (longitude +/ 180 degrees). More...  
bool  willUseEllipsoid () const 
Returns whether calculations will use the ellipsoid. More...  
Static Public Member Functions  
static QString  formatArea (double area, int decimals, QgsUnitTypes::AreaUnit unit, bool keepBaseUnit=false) 
Returns an area formatted as a friendly string. More...  
static QString  formatDistance (double distance, int decimals, QgsUnitTypes::DistanceUnit unit, bool keepBaseUnit=false) 
Returns an distance formatted as a friendly string. More...  
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().
Definition at line 49 of file qgsdistancearea.h.
QgsDistanceArea::QgsDistanceArea  (  ) 
Constructor.
Definition at line 44 of file qgsdistancearea.cpp.
QgsUnitTypes::AreaUnit QgsDistanceArea::areaUnits  (  )  const 
Returns the units of area for areal calculations made by this object.
Definition at line 794 of file qgsdistancearea.cpp.
double QgsDistanceArea::bearing  (  const QgsPointXY &  p1, 
const QgsPointXY &  p2  
)  const 
Computes the bearing (in radians) between two points.
Definition at line 842 of file qgsdistancearea.cpp.
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.
Based on Vincenty's formula for the geodetic direct problem as described in "Geocentric Datum of Australia Technical Manual", Chapter 4.
p1   location of first geographic (latitude/longitude) point as degrees. 
distance   distance in meters. 
azimuth   azimuth in radians, clockwise from North 
Definition at line 396 of file qgsdistancearea.cpp.
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.
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 
Definition at line 1156 of file qgsdistancearea.cpp.
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.
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 
Definition at line 1142 of file qgsdistancearea.cpp.

inline 
Returns ellipsoid's acronym.
Calculations will only use the ellipsoid if a valid ellipsoid has been set.
Definition at line 112 of file qgsdistancearea.h.

inline 
Returns the ellipsoid (destination) spatial reference system.
Definition at line 84 of file qgsdistancearea.h.

inline 
Returns ellipsoid's inverse flattening.
The inverse flattening is calculated with invf = a/(ab).
Definition at line 137 of file qgsdistancearea.h.

inline 
Returns the ellipsoid's semi major axis.
Definition at line 120 of file qgsdistancearea.h.

inline 
Returns ellipsoid's semi minor axis.
Definition at line 128 of file qgsdistancearea.h.

static 
Returns an area formatted as a friendly string.
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 
Definition at line 1137 of file qgsdistancearea.cpp.

static 
Returns an distance formatted as a friendly string.
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 
Definition at line 1132 of file qgsdistancearea.cpp.
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.
Definition at line 673 of file qgsdistancearea.cpp.
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).
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.
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. 
Definition at line 460 of file qgsdistancearea.cpp.
QgsUnitTypes::DistanceUnit QgsDistanceArea::lengthUnits  (  )  const 
Returns the units of distance for length calculations made by this object.
Definition at line 789 of file qgsdistancearea.cpp.
double QgsDistanceArea::measureArea  (  const QgsGeometry &  geometry  )  const 
Measures the area of a geometry.
geometry  geometry to measure 
Definition at line 183 of file qgsdistancearea.cpp.
double QgsDistanceArea::measureLength  (  const QgsGeometry &  geometry  )  const 
Measures the length of a geometry.
geometry  geometry to measure 
Definition at line 192 of file qgsdistancearea.cpp.
double QgsDistanceArea::measureLine  (  const QVector< QgsPointXY > &  points  )  const 
Measures the length of a line with multiple segments.
points  list of points in line 
Definition at line 273 of file qgsdistancearea.cpp.
double QgsDistanceArea::measureLine  (  const QgsPointXY &  p1, 
const QgsPointXY &  p2  
)  const 
Measures the distance between two points.
p1  start of line 
p2  end of line 
Definition at line 315 of file qgsdistancearea.cpp.
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.
p1  start point [can be Cartesian or Geographic] 
distance  must be in meters 
azimuth   azimuth in radians, clockwise from North 
projectedPoint  calculated projected point 
Definition at line 350 of file qgsdistancearea.cpp.
double QgsDistanceArea::measurePerimeter  (  const QgsGeometry &  geometry  )  const 
Measures the perimeter of a polygon geometry.
geometry  geometry to measure 
Definition at line 201 of file qgsdistancearea.cpp.
double QgsDistanceArea::measurePolygon  (  const QVector< QgsPointXY > &  points  )  const 
Measures the area of the polygon described by a set of points.
Definition at line 815 of file qgsdistancearea.cpp.
bool QgsDistanceArea::setEllipsoid  (  const QString &  ellipsoid  ) 
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.
true
if ellipsoid was successfully set Definition at line 66 of file qgsdistancearea.cpp.
bool QgsDistanceArea::setEllipsoid  (  double  semiMajor, 
double  semiMinor  
) 
Sets ellipsoid by supplied radii.
Calculations will only use the ellipsoid if a valid ellipsoid been set.
true
if ellipsoid was successfully set Definition at line 90 of file qgsdistancearea.cpp.
void QgsDistanceArea::setSourceCrs  (  const QgsCoordinateReferenceSystem &  crs, 
const QgsCoordinateTransformContext &  context  
) 
Sets source spatial reference system crs.
Definition at line 60 of file qgsdistancearea.cpp.

inline 
Returns the source spatial reference system.
Definition at line 76 of file qgsdistancearea.h.
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 multipart 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.
Definition at line 546 of file qgsdistancearea.cpp.
bool QgsDistanceArea::willUseEllipsoid  (  )  const 
Returns whether calculations will use the ellipsoid.
Calculations will only use the ellipsoid if a valid ellipsoid() has been set.
Definition at line 55 of file qgsdistancearea.cpp.