QGIS API Documentation  2.99.0-Master (e077efd)
Public Member Functions | Static Public Member Functions | Protected Member Functions | List of all members
QgsDistanceArea Class Reference

General purpose distance and area calculator. More...

#include <qgsdistancearea.h>

Public Member Functions

 QgsDistanceArea ()
 Constructor. More...
 
 QgsDistanceArea (const QgsDistanceArea &origDA)
 Copy constructor. More...
 
 ~QgsDistanceArea ()
 Destructor. More...
 
QgsUnitTypes::AreaUnit areaUnits () const
 Returns the units of area for areal calculations made by this object. More...
 
double bearing (const QgsPoint &p1, const QgsPoint &p2) const
 compute bearing - in radians 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...
 
bool ellipsoidalEnabled () const
 Returns whether ellipsoidal calculations are enabled. More...
 
double ellipsoidInverseFlattening () const
 returns ellipsoid's inverse flattening More...
 
double ellipsoidSemiMajor () const
 returns ellipsoid's semi major axis More...
 
double ellipsoidSemiMinor () const
 returns ellipsoid's semi minor axis More...
 
bool geographic () const
 What sort of coordinate system is being used? 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 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 measureLength (const QgsGeometry &geometry) const
 Measures the length of a geometry. More...
 
double measureLine (const QList< QgsPoint > &points) const
 Measures the length of a line with multiple segments. More...
 
double measureLine (const QgsPoint &p1, const QgsPoint &p2) const
 Measures length of a line with one segment. More...
 
double measureLine (const QgsPoint &p1, const QgsPoint &p2, QgsUnitTypes::DistanceUnit &units) const
 Measures length of line with one segment and returns units of distance. More...
 
double measurePerimeter (const QgsGeometry *geometry) const
 Measures the perimeter of a polygon geometry. More...
 
double measurePerimeter (const QgsGeometry &geometry) const
 Measures the perimeter of a polygon geometry. More...
 
double measurePolygon (const QList< QgsPoint > &points) const
 measures polygon area More...
 
QgsDistanceAreaoperator= (const QgsDistanceArea &origDA)
 Assignment operator. More...
 
bool setEllipsoid (const QString &ellipsoid)
 Sets ellipsoid by its acronym. More...
 
bool setEllipsoid (double semiMajor, double semiMinor)
 Sets ellipsoid by supplied radii. More...
 
void setEllipsoidalMode (bool flag)
 Sets whether coordinates must be projected to ellipsoid before measuring. More...
 
void setSourceAuthId (const QString &authid)
 sets source spatial reference system by authid More...
 
void setSourceCrs (long srsid)
 sets source spatial reference system (by QGIS CRS) More...
 
void setSourceCrs (const QgsCoordinateReferenceSystem &srcCRS)
 Sets source spatial reference system (by QGIS CRS) More...
 
QgsCoordinateReferenceSystem sourceCrs () const
 Returns the source spatial reference system. More...
 
long sourceCrsId () const
 Returns the QgsCoordinateReferenceSystem::srsid() for the CRS used during calculations. 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...
 

Protected Member Functions

void computeAreaInit ()
 precalculates some values (must be called always when changing ellipsoid) More...
 
double computeDistance (const QList< QgsPoint > &points) const
 calculate distance with given coordinates (does not do a transform anymore) More...
 
double computeDistanceBearing (const QgsPoint &p1, const QgsPoint &p2, double *course1=nullptr, double *course2=nullptr) const
 calculates distance from two points on ellipsoid based on inverse Vincenty's formulae More...
 
double computeDistanceFlat (const QgsPoint &p1, const QgsPoint &p2) const
 uses flat / planimetric / Euclidean distance More...
 
double computePolygonArea (const QList< QgsPoint > &points) const
 calculates area of polygon on ellipsoid algorithm has been taken from GRASS: gis/area_poly1.c More...
 
double computePolygonFlatArea (const QList< QgsPoint > &points) const
 
QgsConstWkbPtr measurePolygon (QgsConstWkbPtr feature, double *area, double *perimeter, bool hasZptr=false) const
 measures polygon area and perimeter, vertices are extracted from WKB More...
 

Detailed Description

General purpose distance and area calculator.

Definition at line 38 of file qgsdistancearea.h.

Constructor & Destructor Documentation

§ QgsDistanceArea() [1/2]

QgsDistanceArea::QgsDistanceArea ( )

Constructor.

Definition at line 48 of file qgsdistancearea.cpp.

§ ~QgsDistanceArea()

QgsDistanceArea::~QgsDistanceArea ( )

Destructor.

Definition at line 63 of file qgsdistancearea.cpp.

§ QgsDistanceArea() [2/2]

QgsDistanceArea::QgsDistanceArea ( const QgsDistanceArea origDA)

Copy constructor.

Definition at line 58 of file qgsdistancearea.cpp.

Member Function Documentation

§ areaUnits()

QgsUnitTypes::AreaUnit QgsDistanceArea::areaUnits ( ) const

Returns the units of area for areal calculations made by this object.

Note
added in QGIS 2.14
See also
lengthUnits()

Definition at line 552 of file qgsdistancearea.cpp.

§ bearing()

double QgsDistanceArea::bearing ( const QgsPoint p1,
const QgsPoint p2 
) const

compute bearing - in radians

Definition at line 694 of file qgsdistancearea.cpp.

§ computeAreaInit()

void QgsDistanceArea::computeAreaInit ( )
protected

precalculates some values (must be called always when changing ellipsoid)

Definition at line 867 of file qgsdistancearea.cpp.

§ computeDistance()

double QgsDistanceArea::computeDistance ( const QList< QgsPoint > &  points) const
protected

calculate distance with given coordinates (does not do a transform anymore)

Definition at line 801 of file qgsdistancearea.cpp.

§ computeDistanceBearing()

double QgsDistanceArea::computeDistanceBearing ( const QgsPoint p1,
const QgsPoint p2,
double *  course1 = nullptr,
double *  course2 = nullptr 
) const
protected

calculates distance from two points on ellipsoid based on inverse Vincenty's formulae

Points p1 and p2 are expected to be in degrees and in currently used ellipsoid

Note
if course1 is not NULL, bearing (in radians) from first point is calculated (the same for course2)
Returns
distance in meters

Definition at line 719 of file qgsdistancearea.cpp.

§ computeDistanceFlat()

double QgsDistanceArea::computeDistanceFlat ( const QgsPoint p1,
const QgsPoint p2 
) const
protected

uses flat / planimetric / Euclidean distance

Definition at line 796 of file qgsdistancearea.cpp.

§ computePolygonArea()

double QgsDistanceArea::computePolygonArea ( const QList< QgsPoint > &  points) const
protected

calculates area of polygon on ellipsoid algorithm has been taken from GRASS: gis/area_poly1.c

Definition at line 902 of file qgsdistancearea.cpp.

§ computePolygonFlatArea()

double QgsDistanceArea::computePolygonFlatArea ( const QList< QgsPoint > &  points) const
protected

Definition at line 965 of file qgsdistancearea.cpp.

§ convertAreaMeasurement()

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.

Parameters
areaarea 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().
toUnitsarea unit to convert measurement to
Returns
converted area
See also
convertLengthMeasurement()
Note
added in QGIS 2.14

Definition at line 1238 of file qgsdistancearea.cpp.

§ convertLengthMeasurement()

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.

Parameters
lengthlength 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().
toUnitsdistance unit to convert measurement to
Returns
converted distance
See also
convertAreaMeasurement()
Note
added in QGIS 2.14

Definition at line 1224 of file qgsdistancearea.cpp.

§ ellipsoid()

QString QgsDistanceArea::ellipsoid ( ) const
inline

Returns ellipsoid's acronym.

Calculations will only use the ellipsoid if ellipsoidalEnabled() is true and an ellipsoid has been set.

See also
setEllipsoid()
ellipsoidalEnabled()
willUseEllipsoid()

Definition at line 127 of file qgsdistancearea.h.

§ ellipsoidalEnabled()

bool QgsDistanceArea::ellipsoidalEnabled ( ) const
inline

Returns whether ellipsoidal calculations are enabled.

See also
willUseEllipsoid()
setEllipsoidalMode()

Definition at line 65 of file qgsdistancearea.h.

§ ellipsoidInverseFlattening()

double QgsDistanceArea::ellipsoidInverseFlattening ( ) const
inline

returns ellipsoid's inverse flattening

Definition at line 134 of file qgsdistancearea.h.

§ ellipsoidSemiMajor()

double QgsDistanceArea::ellipsoidSemiMajor ( ) const
inline

returns ellipsoid's semi major axis

Definition at line 130 of file qgsdistancearea.h.

§ ellipsoidSemiMinor()

double QgsDistanceArea::ellipsoidSemiMinor ( ) const
inline

returns ellipsoid's semi minor axis

Definition at line 132 of file qgsdistancearea.h.

§ formatArea()

QString QgsDistanceArea::formatArea ( double  area,
int  decimals,
QgsUnitTypes::AreaUnit  unit,
bool  keepBaseUnit = false 
)
static

Returns an area formatted as a friendly string.

Parameters
areaarea to format
decimalsnumber of decimal places to show
unitunit of area
keepBaseUnitset to false to allow conversion of large areas to more suitable units, eg square meters to square kilometers
Returns
formatted area string
Note
added in QGIS 2.14
See also
formatDistance()

Definition at line 1089 of file qgsdistancearea.cpp.

§ formatDistance()

QString QgsDistanceArea::formatDistance ( double  distance,
int  decimals,
QgsUnitTypes::DistanceUnit  unit,
bool  keepBaseUnit = false 
)
static

Returns an distance formatted as a friendly string.

Parameters
distancedistance to format
decimalsnumber of decimal places to show
unitunit of distance
keepBaseUnitset to false to allow conversion of large distances to more suitable units, eg meters to kilometers
Returns
formatted distance string
Note
added in QGIS 2.16
See also
formatArea()

Definition at line 986 of file qgsdistancearea.cpp.

§ geographic()

bool QgsDistanceArea::geographic ( ) const
inline

What sort of coordinate system is being used?

Definition at line 100 of file qgsdistancearea.h.

§ lengthUnits()

QgsUnitTypes::DistanceUnit QgsDistanceArea::lengthUnits ( ) const

Returns the units of distance for length calculations made by this object.

Note
added in QGIS 2.14
See also
areaUnits()

Definition at line 547 of file qgsdistancearea.cpp.

§ measureArea() [1/2]

double QgsDistanceArea::measureArea ( const QgsGeometry geometry) const

Measures the area of a geometry.

Parameters
geometrygeometry 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().
Note
added in QGIS 2.12
See also
measureLength()
measurePerimeter()
areaUnits()

Definition at line 346 of file qgsdistancearea.cpp.

§ measureArea() [2/2]

double QgsDistanceArea::measureArea ( const QgsGeometry geometry) const

Measures the area of a geometry.

Parameters
geometrygeometry 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().
Note
added in QGIS 2.12
See also
measureLength()
measurePerimeter()
areaUnits()

Definition at line 355 of file qgsdistancearea.cpp.

§ measureLength() [1/2]

double QgsDistanceArea::measureLength ( const QgsGeometry geometry) const

Measures the length of a geometry.

Parameters
geometrygeometry 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().
Note
added in QGIS 2.12
See also
lengthUnits()
measureArea()
measurePerimeter()

Definition at line 364 of file qgsdistancearea.cpp.

§ measureLength() [2/2]

double QgsDistanceArea::measureLength ( const QgsGeometry geometry) const

Measures the length of a geometry.

Parameters
geometrygeometry 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().
Note
added in QGIS 2.12
See also
lengthUnits()
measureArea()
measurePerimeter()

Definition at line 373 of file qgsdistancearea.cpp.

§ measureLine() [1/3]

double QgsDistanceArea::measureLine ( const QList< QgsPoint > &  points) const

Measures the length of a line with multiple segments.

Parameters
pointslist of points in line
Returns
length of line. The units for the returned length can be retrieved by calling lengthUnits().
See also
lengthUnits()

Definition at line 462 of file qgsdistancearea.cpp.

§ measureLine() [2/3]

double QgsDistanceArea::measureLine ( const QgsPoint p1,
const QgsPoint p2 
) const

Measures length of a line with one segment.

Parameters
p1start of line
p2end of line
Returns
distance between points. The units for the returned distance can be retrieved by calling lengthUnits().
See also
lengthUnits()

Definition at line 504 of file qgsdistancearea.cpp.

§ measureLine() [3/3]

double QgsDistanceArea::measureLine ( const QgsPoint p1,
const QgsPoint p2,
QgsUnitTypes::DistanceUnit units 
) const

Measures length of line with one segment and returns units of distance.

Parameters
p1start of line
p2end of line
unitswill be set to units of measure
Returns
calculated distance between points. Distance units are stored in units parameter.
Note
added in QGIS 2.12

Definition at line 510 of file qgsdistancearea.cpp.

§ measurePerimeter() [1/2]

double QgsDistanceArea::measurePerimeter ( const QgsGeometry geometry) const

Measures the perimeter of a polygon geometry.

Parameters
geometrygeometry 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().
Note
added in QGIS 2.12
See also
lengthUnits()
measureArea()
measurePerimeter()

Definition at line 382 of file qgsdistancearea.cpp.

§ measurePerimeter() [2/2]

double QgsDistanceArea::measurePerimeter ( const QgsGeometry geometry) const

Measures the perimeter of a polygon geometry.

Parameters
geometrygeometry 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().
Note
added in QGIS 2.12
See also
lengthUnits()
measureArea()
measurePerimeter()

Definition at line 390 of file qgsdistancearea.cpp.

§ measurePolygon() [1/2]

double QgsDistanceArea::measurePolygon ( const QList< QgsPoint > &  points) const

measures polygon area

Definition at line 667 of file qgsdistancearea.cpp.

§ measurePolygon() [2/2]

QgsConstWkbPtr QgsDistanceArea::measurePolygon ( QgsConstWkbPtr  feature,
double *  area,
double *  perimeter,
bool  hasZptr = false 
) const
protected

measures polygon area and perimeter, vertices are extracted from WKB

Definition at line 558 of file qgsdistancearea.cpp.

§ operator=()

QgsDistanceArea & QgsDistanceArea::operator= ( const QgsDistanceArea origDA)

Assignment operator.

Definition at line 68 of file qgsdistancearea.cpp.

§ setEllipsoid() [1/2]

bool QgsDistanceArea::setEllipsoid ( const QString &  ellipsoid)

Sets ellipsoid by its acronym.

Calculations will only use the ellipsoid if both the ellipsoid has been set and ellipsoidalEnabled() is true.

Returns
true if ellipsoid was successfully set
See also
ellipsoid()
setEllipsoidalMode()
willUseEllipsoid()

Definition at line 120 of file qgsdistancearea.cpp.

§ setEllipsoid() [2/2]

bool QgsDistanceArea::setEllipsoid ( double  semiMajor,
double  semiMinor 
)

Sets ellipsoid by supplied radii.

Calculations will only use the ellipsoid if both the ellipsoid has been set and ellipsoidalEnabled() is true.

Returns
true if ellipsoid was successfully set
See also
ellipsoid()
setEllipsoidalMode()
willUseEllipsoid()

Definition at line 253 of file qgsdistancearea.cpp.

§ setEllipsoidalMode()

void QgsDistanceArea::setEllipsoidalMode ( bool  flag)

Sets whether coordinates must be projected to ellipsoid before measuring.

Note
for calculations to use the ellipsoid, both the ellipsoid mode must be true and an ellipse must be set
See also
setEllipsoid()
willUseEllipsoid()

Definition at line 93 of file qgsdistancearea.cpp.

§ setSourceAuthId()

void QgsDistanceArea::setSourceAuthId ( const QString &  authid)

sets source spatial reference system by authid

Definition at line 114 of file qgsdistancearea.cpp.

§ setSourceCrs() [1/2]

void QgsDistanceArea::setSourceCrs ( long  srsid)

sets source spatial reference system (by QGIS CRS)

Definition at line 103 of file qgsdistancearea.cpp.

§ setSourceCrs() [2/2]

void QgsDistanceArea::setSourceCrs ( const QgsCoordinateReferenceSystem srcCRS)

Sets source spatial reference system (by QGIS CRS)

Note
: missing in Python bindings in QGIS < 2.2
See also
sourceCrs()

Definition at line 109 of file qgsdistancearea.cpp.

§ sourceCrs()

QgsCoordinateReferenceSystem QgsDistanceArea::sourceCrs ( ) const
inline

Returns the source spatial reference system.

See also
setSourceCrs()

Definition at line 91 of file qgsdistancearea.h.

§ sourceCrsId()

long QgsDistanceArea::sourceCrsId ( ) const
inline

Returns the QgsCoordinateReferenceSystem::srsid() for the CRS used during calculations.

See also
setSourceCrs()
Note
added in QGIS 2.14

Definition at line 97 of file qgsdistancearea.h.

§ willUseEllipsoid()

bool QgsDistanceArea::willUseEllipsoid ( ) const

Returns whether calculations will use the ellipsoid.

Calculations will only use the ellipsoid if ellipsoidalEnabled() is true and an ellipsoid has been set.

Note
added in QGIS 2.14
See also
ellipsoidalEnabled()
ellipsoid()

Definition at line 98 of file qgsdistancearea.cpp.


The documentation for this class was generated from the following files: