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, QGis::UnitType toUnits) const
	Takes a length measurement calculated by this QgsDistanceArea object and converts it to a different distance unit. More...

void	convertMeasurement (double &measure, QGis::UnitType &measureUnits, QGis::UnitType displayUnits, bool isArea) const
	Helper for conversion between physical units. 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...

QGis::UnitType	lengthUnits () const
	Returns the units of distance for length calculations made by this object. More...

Q_DECL_DEPRECATED double	measure (const QgsGeometry *geometry) const
	General measurement (line distance or polygon area) 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 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, QGis::UnitType &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	measurePolygon (const QList< QgsPoint > &points) const
	measures polygon area More...

QgsDistanceArea &	operator= (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...

Q_DECL_DEPRECATED long	sourceCrs () const
	returns 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, QGis::UnitType unit, bool keepBaseUnit=false)
	Returns an distance formatted as a friendly string. More...

static Q_DECL_DEPRECATED QString	textUnit (double value, int decimals, QGis::UnitType u, bool isArea, bool keepBaseUnit=false)
	Returns a measurement 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.

calculations are done on ellipsoid
it's possible to pass points/features in any CRS, coordinates are transformed
two options how to use it
- use measure() takes QgsGeometry as a parameter and calculates distance or area
- use directly measureLine(), measurePolygon() which take list of QgsPoints (both cases transform the coordinates from source CRS to the ellipse coords)
returned values are in meters resp. square meters

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 65 of file qgsdistancearea.cpp.

◆ QgsDistanceArea() [2/2]

QgsDistanceArea::QgsDistanceArea ( const QgsDistanceArea & origDA )

Copy constructor.

Definition at line 59 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 539 of file qgsdistancearea.cpp.

◆ bearing()

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

compute bearing - in radians

Definition at line 681 of file qgsdistancearea.cpp.

◆ computeAreaInit()

void QgsDistanceArea::computeAreaInit ( )

protected

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

Definition at line 854 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 788 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 706 of file qgsdistancearea.cpp.

◆ computeDistanceFlat()

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

protected

uses flat / planimetric / Euclidean distance

Definition at line 783 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 889 of file qgsdistancearea.cpp.

◆ computePolygonFlatArea()

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

protected

Definition at line 978 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

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

Returns: converted area

See also: convertLengthMeasurement()

Note: added in QGIS 2.14

Definition at line 1412 of file qgsdistancearea.cpp.

◆ convertLengthMeasurement()

double QgsDistanceArea::convertLengthMeasurement	(	double	length,
		QGis::UnitType	toUnits
	)		const

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().
toUnits	distance unit to convert measurement to

Returns: converted distance

See also: convertAreaMeasurement()

Note: added in QGIS 2.14

Definition at line 1398 of file qgsdistancearea.cpp.

◆ convertMeasurement()

void QgsDistanceArea::convertMeasurement	(	double &	measure,
		QGis::UnitType &	measureUnits,
		QGis::UnitType	displayUnits,
		bool	isArea
	)		const

Helper for conversion between physical units.

Definition at line 1367 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 126 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 133 of file qgsdistancearea.h.

◆ ellipsoidSemiMajor()

double QgsDistanceArea::ellipsoidSemiMajor ( ) const

inline

returns ellipsoid's semi major axis

Definition at line 129 of file qgsdistancearea.h.

◆ ellipsoidSemiMinor()

double QgsDistanceArea::ellipsoidSemiMinor ( ) const

inline

returns ellipsoid's semi minor axis

Definition at line 131 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

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, eg square meters to square kilometers

Returns: formatted area string

Note: added in QGIS 2.14

See also: formatDistance()

Definition at line 1232 of file qgsdistancearea.cpp.

◆ formatDistance()

QString QgsDistanceArea::formatDistance	(	double	distance,
		int	decimals,
		QGis::UnitType	unit,
		bool	keepBaseUnit = `false`
	)

static

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, eg meters to kilometers

Returns: formatted distance string

Note: added in QGIS 2.16

See also: formatArea()

Definition at line 1129 of file qgsdistancearea.cpp.

◆ geographic()

bool QgsDistanceArea::geographic ( ) const

inline

What sort of coordinate system is being used?

Definition at line 99 of file qgsdistancearea.h.

◆ lengthUnits()

QGis::UnitType 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 534 of file qgsdistancearea.cpp.

◆ measure()

double QgsDistanceArea::measure ( const QgsGeometry * geometry ) const

General measurement (line distance or polygon area)

Deprecated:: use measureArea() or measureLength() methods instead, as this method is unpredictable for geometry collections

Definition at line 350 of file qgsdistancearea.cpp.

◆ measureArea()

double QgsDistanceArea::measureArea ( const QgsGeometry * geometry ) const

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().

Note: added in QGIS 2.12

See also: measureLength(); measurePerimeter(); areaUnits()

Definition at line 359 of file qgsdistancearea.cpp.

◆ measureLength()

double QgsDistanceArea::measureLength ( const QgsGeometry * geometry ) const

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().

Note: added in QGIS 2.12

See also: lengthUnits(); measureArea(); measurePerimeter()

Definition at line 368 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

points list 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 449 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

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: lengthUnits()

Definition at line 491 of file qgsdistancearea.cpp.

◆ measureLine() [3/3]

double QgsDistanceArea::measureLine	(	const QgsPoint &	p1,
		const QgsPoint &	p2,
		QGis::UnitType &	units
	)		const

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

Parameters

p1	start of line
p2	end of line
units	will 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 497 of file qgsdistancearea.cpp.

◆ measurePerimeter()

double QgsDistanceArea::measurePerimeter ( const QgsGeometry * geometry ) const

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().

Note: added in QGIS 2.12

See also: lengthUnits(); measureArea(); measurePerimeter()

Definition at line 377 of file qgsdistancearea.cpp.

◆ measurePolygon() [1/2]

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

measures polygon area

Definition at line 654 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 545 of file qgsdistancearea.cpp.

◆ operator=()

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

Assignment operator.

Definition at line 71 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 124 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 257 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 97 of file qgsdistancearea.cpp.

◆ setSourceAuthId()

void QgsDistanceArea::setSourceAuthId ( const QString & authid )

sets source spatial reference system by authid

Definition at line 118 of file qgsdistancearea.cpp.

◆ setSourceCrs() [1/2]

void QgsDistanceArea::setSourceCrs ( long srsid )

sets source spatial reference system (by QGIS CRS)

Definition at line 107 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

Definition at line 113 of file qgsdistancearea.cpp.

◆ sourceCrs()

Q_DECL_DEPRECATED long QgsDistanceArea::sourceCrs ( ) const

inline

returns source spatial reference system

Deprecated:: use sourceCrsId() instead

Definition at line 90 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 96 of file qgsdistancearea.h.

◆ textUnit()

QString QgsDistanceArea::textUnit	(	double	value,
		int	decimals,
		QGis::UnitType	u,
		bool	isArea,
		bool	keepBaseUnit = `false`
	)

static

Returns a measurement formatted as a friendly string.

Parameters

value	value of measurement
decimals	number of decimal places to show
u	unit of measurement
isArea	set to true if measurement is an area measurement
keepBaseUnit	set to false to allow conversion of large distances to more suitable units, eg meters to kilometers

Returns: formatted measurement string

Deprecated:: use formatDistance() or formatArea() instead

Definition at line 999 of file qgsdistancearea.cpp.

◆ 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 102 of file qgsdistancearea.cpp.

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

/tmp/buildd/qgis-2.18.21+99unstable/src/core/qgsdistancearea.h
/tmp/buildd/qgis-2.18.21+99unstable/src/core/qgsdistancearea.cpp

Public Member Functions

Static Public Member Functions

Protected Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ QgsDistanceArea() [1/2]

◆ ~QgsDistanceArea()

◆ QgsDistanceArea() [2/2]

Member Function Documentation

◆ areaUnits()

◆ bearing()

◆ computeAreaInit()

◆ computeDistance()

◆ computeDistanceBearing()

◆ computeDistanceFlat()

◆ computePolygonArea()

◆ computePolygonFlatArea()

◆ convertAreaMeasurement()

◆ convertLengthMeasurement()

◆ convertMeasurement()

◆ ellipsoid()

◆ ellipsoidalEnabled()

◆ ellipsoidInverseFlattening()

◆ ellipsoidSemiMajor()

◆ ellipsoidSemiMinor()

◆ formatArea()

◆ formatDistance()

◆ geographic()

◆ lengthUnits()

◆ measure()

◆ measureArea()

◆ measureLength()

◆ measureLine() [1/3]

◆ measureLine() [2/3]

◆ measureLine() [3/3]

◆ measurePerimeter()

◆ measurePolygon() [1/2]

◆ measurePolygon() [2/2]

◆ operator=()

◆ setEllipsoid() [1/2]

◆ setEllipsoid() [2/2]

◆ setEllipsoidalMode()

◆ setSourceAuthId()

◆ setSourceCrs() [1/2]

◆ setSourceCrs() [2/2]

◆ sourceCrs()

◆ sourceCrsId()

◆ textUnit()

◆ willUseEllipsoid()