QGIS API Documentation
3.0.2-Girona (307d082)
|
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... | |
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... | |
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... | |
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 41 of file qgsdistancearea.cpp.
QgsUnitTypes::AreaUnit QgsDistanceArea::areaUnits | ( | ) | const |
Returns the units of area for areal calculations made by this object.
Definition at line 462 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 510 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 393 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 824 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 810 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 102 of file qgsdistancearea.h.
|
inline |
Returns ellipsoid's inverse flattening.
The inverse flattening is calculated with invf = a/(a-b).
Definition at line 127 of file qgsdistancearea.h.
|
inline |
Returns the ellipsoid's semi major axis.
Definition at line 110 of file qgsdistancearea.h.
|
inline |
Returns ellipsoid's semi minor axis.
Definition at line 118 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 805 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 800 of file qgsdistancearea.cpp.
QgsUnitTypes::DistanceUnit QgsDistanceArea::lengthUnits | ( | ) | const |
Returns the units of distance for length calculations made by this object.
Definition at line 457 of file qgsdistancearea.cpp.
double QgsDistanceArea::measureArea | ( | const QgsGeometry & | geometry | ) | const |
Measures the area of a geometry.
geometry | geometry to measure |
Definition at line 180 of file qgsdistancearea.cpp.
double QgsDistanceArea::measureLength | ( | const QgsGeometry & | geometry | ) | const |
Measures the length of a geometry.
geometry | geometry to measure |
Definition at line 189 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 270 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 312 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 347 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 198 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 483 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.
Definition at line 63 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.
Definition at line 87 of file qgsdistancearea.cpp.
void QgsDistanceArea::setSourceCrs | ( | const QgsCoordinateReferenceSystem & | crs, |
const QgsCoordinateTransformContext & | context | ||
) |
Sets source spatial reference system crs.
Definition at line 57 of file qgsdistancearea.cpp.
|
inline |
Returns the source spatial reference system.
Definition at line 75 of file qgsdistancearea.h.
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 52 of file qgsdistancearea.cpp.