mirror of
https://github.com/qgis/QGIS.git
synced 2025-10-31 00:06:02 -04:00
418 lines
14 KiB
Plaintext
418 lines
14 KiB
Plaintext
/************************************************************************
|
|
* This file has been generated automatically from *
|
|
* *
|
|
* src/core/qgsdistancearea.h *
|
|
* *
|
|
* Do not edit manually ! Edit header and run scripts/sipify.py again *
|
|
************************************************************************/
|
|
|
|
|
|
|
|
|
|
class QgsDistanceArea
|
|
{
|
|
%Docstring(signature="appended")
|
|
A general purpose distance and area calculator, capable of performing ellipsoid based calculations.
|
|
|
|
Measurements can either be performed on existing :py:class:`QgsGeometry` objects, or using
|
|
lists of points.
|
|
|
|
If a valid :py:func:`~ellipsoid` has been set for the :py:class:`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 :py:func:`~willUseEllipsoid`.
|
|
|
|
In order to perform accurate calculations, the source coordinate reference system
|
|
of all measured geometries must first be specified using :py:func:`~setSourceCrs`.
|
|
|
|
Usually, the measurements returned by :py:class:`QgsDistanceArea` are in meters. If no valid
|
|
ellipsoid is set, then the units may not be meters. The units can be retrieved
|
|
by calling :py:func:`~lengthUnits` and :py:func:`~areaUnits`.
|
|
|
|
Internally, the GeographicLib library is used to calculate all ellipsoid based measurements.
|
|
%End
|
|
|
|
%TypeHeaderCode
|
|
#include "qgsdistancearea.h"
|
|
%End
|
|
public:
|
|
|
|
QgsDistanceArea();
|
|
~QgsDistanceArea();
|
|
|
|
QgsDistanceArea( const QgsDistanceArea &other );
|
|
|
|
bool willUseEllipsoid() const;
|
|
%Docstring
|
|
Returns whether calculations will use the ellipsoid. Calculations will only use the
|
|
ellipsoid if a valid :py:func:`~QgsDistanceArea.ellipsoid` has been set.
|
|
|
|
.. seealso:: :py:func:`ellipsoid`
|
|
%End
|
|
|
|
void setSourceCrs( const QgsCoordinateReferenceSystem &crs, const QgsCoordinateTransformContext &context );
|
|
%Docstring
|
|
Sets source spatial reference system ``crs``.
|
|
|
|
.. seealso:: :py:func:`sourceCrs`
|
|
%End
|
|
|
|
QgsCoordinateReferenceSystem sourceCrs() const;
|
|
%Docstring
|
|
Returns the source spatial reference system.
|
|
|
|
.. seealso:: :py:func:`setSourceCrs`
|
|
|
|
.. seealso:: :py:func:`ellipsoidCrs`
|
|
%End
|
|
|
|
QgsCoordinateReferenceSystem ellipsoidCrs() const;
|
|
%Docstring
|
|
Returns the ellipsoid (destination) spatial reference system.
|
|
|
|
.. seealso:: :py:func:`sourceCrs`
|
|
|
|
.. seealso:: :py:func:`ellipsoid`
|
|
|
|
.. versionadded:: 3.6
|
|
%End
|
|
|
|
bool setEllipsoid( const QString &ellipsoid );
|
|
%Docstring
|
|
Sets the ``ellipsoid`` by its acronym. Known ellipsoid acronyms can be
|
|
retrieved using :py:func:`QgsEllipsoidUtils.acronyms()`.
|
|
Calculations will only use the ellipsoid if a valid ellipsoid has been set.
|
|
|
|
:return: ``True`` if ellipsoid was successfully set
|
|
|
|
.. seealso:: :py:func:`ellipsoid`
|
|
|
|
.. seealso:: :py:func:`willUseEllipsoid`
|
|
%End
|
|
|
|
bool setEllipsoid( double semiMajor, double semiMinor );
|
|
%Docstring
|
|
Sets ellipsoid by supplied radii. Calculations will only use the ellipsoid if
|
|
a valid ellipsoid been set.
|
|
|
|
:return: ``True`` if ellipsoid was successfully set
|
|
|
|
.. seealso:: :py:func:`ellipsoid`
|
|
|
|
.. seealso:: :py:func:`willUseEllipsoid`
|
|
%End
|
|
|
|
QString ellipsoid() const;
|
|
%Docstring
|
|
Returns ellipsoid's acronym. Calculations will only use the
|
|
ellipsoid if a valid ellipsoid has been set.
|
|
|
|
.. seealso:: :py:func:`setEllipsoid`
|
|
|
|
.. seealso:: :py:func:`willUseEllipsoid`
|
|
|
|
.. seealso:: :py:func:`ellipsoidCrs`
|
|
%End
|
|
|
|
double ellipsoidSemiMajor() const;
|
|
%Docstring
|
|
Returns the ellipsoid's semi major axis.
|
|
|
|
.. seealso:: :py:func:`ellipsoid`
|
|
|
|
.. seealso:: :py:func:`ellipsoidSemiMinor`
|
|
|
|
.. seealso:: :py:func:`ellipsoidInverseFlattening`
|
|
%End
|
|
|
|
double ellipsoidSemiMinor() const;
|
|
%Docstring
|
|
Returns ellipsoid's semi minor axis.
|
|
|
|
.. seealso:: :py:func:`ellipsoid`
|
|
|
|
.. seealso:: :py:func:`ellipsoidSemiMajor`
|
|
|
|
.. seealso:: :py:func:`ellipsoidInverseFlattening`
|
|
%End
|
|
|
|
double ellipsoidInverseFlattening() const;
|
|
%Docstring
|
|
Returns ellipsoid's inverse flattening.
|
|
The inverse flattening is calculated with invf = a/(a-b).
|
|
|
|
.. seealso:: :py:func:`ellipsoid`
|
|
|
|
.. seealso:: :py:func:`ellipsoidSemiMajor`
|
|
|
|
.. seealso:: :py:func:`ellipsoidSemiMinor`
|
|
%End
|
|
|
|
double measureArea( const QgsGeometry &geometry ) const;
|
|
%Docstring
|
|
Measures the area of a geometry.
|
|
|
|
:param geometry: geometry to measure
|
|
|
|
:return: area of geometry. For geometry collections, non surface geometries will be ignored. The units for the
|
|
returned area can be retrieved by calling :py:func:`~QgsDistanceArea.areaUnits`.
|
|
|
|
.. seealso:: :py:func:`measureLength`
|
|
|
|
.. seealso:: :py:func:`measurePerimeter`
|
|
|
|
.. seealso:: :py:func:`areaUnits`
|
|
%End
|
|
|
|
double measureLength( const QgsGeometry &geometry ) const;
|
|
%Docstring
|
|
Measures the length of a geometry.
|
|
|
|
:param geometry: geometry to measure
|
|
|
|
:return: length of geometry. For geometry collections, non curve geometries will be ignored. The units for the
|
|
returned distance can be retrieved by calling :py:func:`~QgsDistanceArea.lengthUnits`.
|
|
|
|
.. seealso:: :py:func:`lengthUnits`
|
|
|
|
.. seealso:: :py:func:`measureArea`
|
|
|
|
.. seealso:: :py:func:`measurePerimeter`
|
|
%End
|
|
|
|
double measurePerimeter( const QgsGeometry &geometry ) const;
|
|
%Docstring
|
|
Measures the perimeter of a polygon geometry.
|
|
|
|
:param geometry: geometry to measure
|
|
|
|
:return: perimeter of geometry. For geometry collections, any non-polygon geometries will be ignored. The units for the
|
|
returned perimeter can be retrieved by calling :py:func:`~QgsDistanceArea.lengthUnits`.
|
|
|
|
.. seealso:: :py:func:`lengthUnits`
|
|
|
|
.. seealso:: :py:func:`measureArea`
|
|
|
|
.. seealso:: :py:func:`measurePerimeter`
|
|
%End
|
|
|
|
double measureLine( const QVector<QgsPointXY> &points ) const;
|
|
%Docstring
|
|
Measures the length of a line with multiple segments.
|
|
|
|
:param points: list of points in line
|
|
|
|
:return: length of line. The units for the returned length can be retrieved by calling :py:func:`~QgsDistanceArea.lengthUnits`.
|
|
|
|
.. seealso:: :py:func:`lengthUnits`
|
|
%End
|
|
|
|
double measureLine( const QgsPointXY &p1, const QgsPointXY &p2 ) const;
|
|
%Docstring
|
|
Measures the distance between two points.
|
|
|
|
:param p1: start of line
|
|
:param p2: end of line
|
|
|
|
:return: distance between points. The units for the returned distance can be retrieved by calling :py:func:`~QgsDistanceArea.lengthUnits`.
|
|
|
|
.. seealso:: :py:func:`lengthUnits`
|
|
%End
|
|
|
|
double measureLineProjected( const QgsPointXY &p1, double distance = 1, double azimuth = M_PI_2, QgsPointXY *projectedPoint /Out/ = 0 ) const;
|
|
%Docstring
|
|
Calculates the distance from one point with distance in meters and azimuth (direction)
|
|
When the :py:func:`~QgsDistanceArea.sourceCrs` is geographic, :py:func:`~QgsDistanceArea.computeSpheroidProject` will be called
|
|
otherwise :py:func:`QgsPoint.project()` will be called after :py:func:`QgsUnitTypes.fromUnitToUnitFactor()` has been applied to the distance
|
|
|
|
:param p1: start point [can be Cartesian or Geographic]
|
|
:param distance: must be in meters
|
|
:param azimuth: azimuth in radians, clockwise from North
|
|
|
|
:return: - distance in mapUnits
|
|
- projectedPoint: calculated projected point
|
|
|
|
.. seealso:: :py:func:`sourceCrs`
|
|
|
|
.. seealso:: :py:func:`computeSpheroidProject`
|
|
|
|
.. note::
|
|
|
|
The input Point must be in the coordinate reference system being used
|
|
%End
|
|
|
|
Qgis::DistanceUnit lengthUnits() const;
|
|
%Docstring
|
|
Returns the units of distance for length calculations made by this object.
|
|
|
|
.. seealso:: :py:func:`areaUnits`
|
|
%End
|
|
|
|
Qgis::AreaUnit areaUnits() const;
|
|
%Docstring
|
|
Returns the units of area for areal calculations made by this object.
|
|
|
|
.. seealso:: :py:func:`lengthUnits`
|
|
%End
|
|
|
|
double measurePolygon( const QVector<QgsPointXY> &points ) const;
|
|
%Docstring
|
|
Measures the area of the polygon described by a set of points.
|
|
%End
|
|
|
|
double bearing( const QgsPointXY &p1, const QgsPointXY &p2 ) const throw( QgsCsException );
|
|
%Docstring
|
|
Computes the bearing (in radians) between two points.
|
|
|
|
:raises QgsCsException: on invalid input coordinates
|
|
%End
|
|
|
|
static QString formatDistance( double distance, int decimals, Qgis::DistanceUnit unit, bool keepBaseUnit = false );
|
|
%Docstring
|
|
Returns an distance formatted as a friendly string.
|
|
|
|
:param distance: distance to format
|
|
:param decimals: number of decimal places to show
|
|
:param unit: unit of distance
|
|
:param keepBaseUnit: set to ``False`` to allow conversion of large distances to more suitable units, e.g., meters to
|
|
kilometers
|
|
|
|
:return: formatted distance string
|
|
|
|
.. seealso:: :py:func:`formatArea`
|
|
%End
|
|
|
|
static QString formatArea( double area, int decimals, Qgis::AreaUnit unit, bool keepBaseUnit = false );
|
|
%Docstring
|
|
Returns an area formatted as a friendly string.
|
|
|
|
:param area: area to format
|
|
:param decimals: number of decimal places to show
|
|
:param unit: unit of area
|
|
:param keepBaseUnit: set to ``False`` to allow conversion of large areas to more suitable units, e.g., square meters to
|
|
square kilometers
|
|
|
|
:return: formatted area string
|
|
|
|
.. seealso:: :py:func:`formatDistance`
|
|
%End
|
|
|
|
double convertLengthMeasurement( double length, Qgis::DistanceUnit toUnits ) const;
|
|
%Docstring
|
|
Takes a length measurement calculated by this QgsDistanceArea object and converts it to a
|
|
different distance unit.
|
|
|
|
:param 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 :py:func:`~QgsDistanceArea.lengthUnits`.
|
|
:param toUnits: distance unit to convert measurement to
|
|
|
|
:return: converted distance
|
|
|
|
.. seealso:: :py:func:`convertAreaMeasurement`
|
|
%End
|
|
|
|
double convertAreaMeasurement( double area, Qgis::AreaUnit toUnits ) const;
|
|
%Docstring
|
|
Takes an area measurement calculated by this QgsDistanceArea object and converts it to a
|
|
different areal unit.
|
|
|
|
:param 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 :py:func:`~QgsDistanceArea.areaUnits`.
|
|
:param toUnits: area unit to convert measurement to
|
|
|
|
:return: converted area
|
|
|
|
.. seealso:: :py:func:`convertLengthMeasurement`
|
|
%End
|
|
|
|
QgsPointXY computeSpheroidProject( const QgsPointXY &p1, double distance = 1, double azimuth = M_PI_2 ) const;
|
|
%Docstring
|
|
Given a location, an azimuth and a distance, computes the
|
|
location of the projected point.
|
|
|
|
:param p1: location of first geographic (latitude/longitude) point as degrees.
|
|
:param distance: distance in meters.
|
|
:param azimuth: azimuth in radians, clockwise from North
|
|
|
|
:return: p2 - location of projected point as longitude/latitude.
|
|
%End
|
|
|
|
QVector<QVector<QgsPointXY> > geodesicLine( const QgsPointXY &p1, const QgsPointXY &p2, double interval, bool breakLine = false ) const;
|
|
%Docstring
|
|
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 :py:func:`~QgsDistanceArea.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.
|
|
|
|
.. versionadded:: 3.6
|
|
%End
|
|
|
|
double latitudeGeodesicCrossesAntimeridian( const QgsPointXY &p1, const QgsPointXY &p2, double &fractionAlongLine /Out/ ) const;
|
|
%Docstring
|
|
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 :py:func:`~QgsDistanceArea.ellipsoidCrs` of this QgsDistanceArea object. The returned latitude
|
|
will also be in this same CRS.
|
|
|
|
:param p1: Starting point, in :py:func:`~QgsDistanceArea.ellipsoidCrs`
|
|
:param p2: Ending point, in :py:func:`~QgsDistanceArea.ellipsoidCrs`
|
|
|
|
:return: - the latitude at which the geodesic crosses the antimeridian
|
|
- fractionAlongLine: the fraction along the geodesic line joining ``p1`` to ``p2`` at which the antimeridian crossing occurs.
|
|
|
|
.. seealso:: :py:func:`splitGeometryAtAntimeridian`
|
|
|
|
.. versionadded:: 3.6
|
|
%End
|
|
|
|
QgsGeometry splitGeometryAtAntimeridian( const QgsGeometry &geometry ) const;
|
|
%Docstring
|
|
Splits a (Multi)LineString ``geometry`` at the antimeridian (longitude +/- 180 degrees).
|
|
The returned geometry will always be a multi-part 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 :py:func:`~QgsDistanceArea.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.
|
|
|
|
.. note::
|
|
|
|
Non-(Multi)LineString geometries will be returned unchanged.
|
|
|
|
.. seealso:: :py:func:`latitudeGeodesicCrossesAntimeridian`
|
|
|
|
.. versionadded:: 3.6
|
|
%End
|
|
|
|
};
|
|
|
|
|
|
/************************************************************************
|
|
* This file has been generated automatically from *
|
|
* *
|
|
* src/core/qgsdistancearea.h *
|
|
* *
|
|
* Do not edit manually ! Edit header and run scripts/sipify.py again *
|
|
************************************************************************/
|