/************************************************************************
 * 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 throw( QgsCsException );
%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`

:raises QgsCsException: if a transformation error occurs while
                        calculating the area
%End

    double measureLength( const QgsGeometry &geometry ) const throw( QgsCsException );
%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`

:raises QgsCsException: if a transformation error occurs while
                        calculating the length
%End

    double measurePerimeter( const QgsGeometry &geometry ) const throw( QgsCsException );
%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`

:raises QgsCsException: if a transformation error occurs while
                        calculating the perimeter
%End

    double measureLine( const QVector<QgsPointXY> &points ) const throw( QgsCsException );
%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`.

:raises QgsCsException: if a transformation error occurs while
                        calculating the length

.. seealso:: :py:func:`lengthUnits`
%End

    double measureLine( const QgsPointXY &p1, const QgsPointXY &p2 ) const throw( QgsCsException );
%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`.

:raises QgsCsException: if a transformation error occurs while
                        calculating the length

.. 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 throw( QgsCsException );
%Docstring
Measures the area of the polygon described by a set of points.

:raises QgsCsException: if a transformation error occurs while
                        calculating the area.
%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   *
 ************************************************************************/