mirror of
https://github.com/qgis/QGIS.git
synced 2025-02-25 00:58:06 -05:00
e46875b9b6
these are always gracefully caught Avoids some unwanted "unhandled exception" message boxes which can pop up while moving the mouse around outside of the valid bounds of the current map projection
451 lines
14 KiB
Plaintext
451 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.pl 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();
|
|
%Docstring
|
|
Constructor
|
|
%End
|
|
~QgsDistanceArea();
|
|
|
|
QgsDistanceArea( const QgsDistanceArea &other );
|
|
%Docstring
|
|
Copy constructor
|
|
%End
|
|
|
|
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`
|
|
|
|
.. versionadded:: 2.14
|
|
%End
|
|
|
|
void setSourceCrs( const QgsCoordinateReferenceSystem &crs, const QgsCoordinateTransformContext &context );
|
|
%Docstring
|
|
Sets source spatial reference system ``crs``.
|
|
|
|
.. seealso:: :py:func:`sourceCrs`
|
|
|
|
.. versionadded:: 2.2
|
|
%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`
|
|
|
|
.. versionadded:: 2.12
|
|
%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`
|
|
|
|
.. versionadded:: 2.12
|
|
%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`
|
|
|
|
.. versionadded:: 2.12
|
|
%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
|
|
|
|
.. versionadded:: 3.0
|
|
%End
|
|
|
|
QgsUnitTypes::DistanceUnit lengthUnits() const;
|
|
%Docstring
|
|
Returns the units of distance for length calculations made by this object.
|
|
|
|
.. seealso:: :py:func:`areaUnits`
|
|
|
|
.. versionadded:: 2.14
|
|
%End
|
|
|
|
QgsUnitTypes::AreaUnit areaUnits() const;
|
|
%Docstring
|
|
Returns the units of area for areal calculations made by this object.
|
|
|
|
.. seealso:: :py:func:`lengthUnits`
|
|
|
|
.. versionadded:: 2.14
|
|
%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, QgsUnitTypes::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`
|
|
|
|
.. versionadded:: 2.16
|
|
%End
|
|
|
|
static QString formatArea( double area, int decimals, QgsUnitTypes::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`
|
|
|
|
.. versionadded:: 2.14
|
|
%End
|
|
|
|
double convertLengthMeasurement( double length, QgsUnitTypes::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`
|
|
|
|
.. versionadded:: 2.14
|
|
%End
|
|
|
|
double convertAreaMeasurement( double area, QgsUnitTypes::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`
|
|
|
|
.. versionadded:: 2.14
|
|
%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.
|
|
|
|
.. versionadded:: 3.0
|
|
%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: will be set to 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.pl again *
|
|
************************************************************************/
|