Update documentation

qgis · Feb 16, 2018 · 35d0f57 · 35d0f57
1 parent d91bd45
commit 35d0f57
Show file tree

Hide file tree

Showing 8 changed files with 64 additions and 20 deletions.
diff --git a/python/core/geometry/qgscircle.sip.in b/python/core/geometry/qgscircle.sip.in
@@ -42,7 +42,9 @@ Constructs a circle by defining all the members.
     static QgsCircle from2Points( const QgsPoint &pt1, const QgsPoint &pt2 );
 %Docstring
 Constructs a circle by 2 points on the circle.
-The center point can have z and m values which are the result from the midpoint operation between ``pt1`` and ``pt2``.
+The center point can have m value which is the result from the midpoint
+operation between ``pt1`` and ``pt2``. Z dimension is also supported and
+is retrieved from the first 3D point amongst ``pt1`` and ``pt2``.
 The radius is calculated from the 2D distance between ``pt1`` and ``pt2``.
 The azimuth is the angle between ``pt1`` and ``pt2``.
 
@@ -53,7 +55,9 @@ The azimuth is the angle between ``pt1`` and ``pt2``.
     static QgsCircle from3Points( const QgsPoint &pt1, const QgsPoint &pt2, const QgsPoint &pt3, double epsilon = 1E-8 );
 %Docstring
 Constructs a circle by 3 points on the circle.
-Z and m values are dropped for the center point.
+M value is dropped for the center point.
+Z dimension is supported and is retrieved from the first 3D point
+amongst ``pt1``, ``pt2`` and ``pt3``.
 The azimuth always takes the default value.
 If the points are colinear an empty circle is returned.
 
@@ -106,7 +110,9 @@ The azimuth always takes the default value.
     static QgsCircle fromExtent( const QgsPoint &pt1, const QgsPoint &pt2 );
 %Docstring
 Constructs a circle by an extent (aka bounding box / :py:class:`QgsRectangle`).
-The center point can have z and m values which are the result from the midpoint operation between ``pt1`` and ``pt2``.
+The center point can have m value which is the result from the midpoint
+operation between ``pt1`` and ``pt2``. Z dimension is also supported and
+is retrieved from the first 3D point amongst ``pt1`` and ``pt2``.
 Axes are calculated from the 2D distance between ``pt1`` and ``pt2``.
 The azimuth always takes the default value.
 

diff --git a/python/core/geometry/qgsellipse.sip.in b/python/core/geometry/qgsellipse.sip.in
@@ -47,7 +47,9 @@ Constructs an ellipse by defining all the members.
     static QgsEllipse fromFoci( const QgsPoint &pt1, const QgsPoint &pt2, const QgsPoint &pt3 );
 %Docstring
 Constructs an ellipse by foci (``pt1`` and ``pt2``) and a point ``pt3``.
-The center point can have z and m values which are the result from the midpoint operation between ``pt1`` and ``pt2``.
+The center point can have m value which is the result from the midpoint
+operation between ``pt1`` and ``pt2``. Z dimension is also supported and
+is retrieved from the first 3D point amongst ``pt1`` and ``pt2``.
 Axes are calculated from the 2D distance with the third point ``pt3``.
 The azimuth is the angle between ``pt1`` and ``pt2``.
 
@@ -59,7 +61,9 @@ The azimuth is the angle between ``pt1`` and ``pt2``.
     static QgsEllipse fromExtent( const QgsPoint &pt1, const QgsPoint &pt2 );
 %Docstring
 Constructs an ellipse by an extent (aka bounding box / :py:class:`QgsRectangle`).
-The center point can have z and m values which are the result from the midpoint operation between ``pt1`` and ``pt2``.
+The center point can have m value which is the result from the midpoint
+operation between ``pt1`` and ``pt2``. Z dimension is also supported and
+is retrieved from the first 3D point amongst ``pt1`` and ``pt2``.
 Axes are calculated from the 2D distance between ``pt1`` and ``pt2``.
 The azimuth always takes the default value.
 
@@ -70,7 +74,9 @@ The azimuth always takes the default value.
     static QgsEllipse fromCenterPoint( const QgsPoint &ptc, const QgsPoint &pt1 );
 %Docstring
 Constructs an ellipse by a center point and a another point.
-The center point keeps z and m values from ``ptc``.
+The center point keeps m value from ``ptc``. Z dimension is also
+supported and is retrieved from the first 3D point amongst ``ptc`` and
+``pt1``.
 Axes are calculated from the 2D distance between ``ptc`` and ``pt1``.
 The azimuth always takes the default value.
 
@@ -81,7 +87,9 @@ The azimuth always takes the default value.
     static QgsEllipse fromCenter2Points( const QgsPoint &ptc, const QgsPoint &pt1, const QgsPoint &pt2 );
 %Docstring
 Constructs an ellipse by a central point and two other points.
-The center point keeps z and m values from ``ptc``.
+The center point keeps m value from ``ptc``. Z dimension is also
+supported and is retrieved from the first 3D point amongst ``ptc``,
+``pt1`` and ``pt2``.
 Axes are calculated from the 2D distance between ``ptc`` and ``pt1`` and ``pt2``.
 The azimuth is the angle between ``ptc`` and ``pt1``.
 

diff --git a/python/core/geometry/qgsgeometryutils.sip.in b/python/core/geometry/qgsgeometryutils.sip.in
@@ -89,7 +89,9 @@ Returns the squared distance between a point and a line.
 
     static bool lineIntersection( const QgsPoint &p1, QgsVector v1, const QgsPoint &p2, QgsVector v2, QgsPoint &intersection /Out/ );
 %Docstring
- Compute the intersection between two lines
+Computes the intersection between two lines. Z dimension is
+supported and is retrieved from the first 3D point amongst ``p1`` and
+``p2``.
 
 :param p1: Point on the first line
 :param v1: Direction vector of the first line
@@ -219,7 +221,9 @@ Calculates angle of a circular string part defined by pt1, pt2, pt3
 
     static bool segmentMidPoint( const QgsPoint &p1, const QgsPoint &p2, QgsPoint &result /Out/, double radius, const QgsPoint &mousePos );
 %Docstring
-Calculates midpoint on circle passing through p1 and p2, closest to given coordinate
+Calculates midpoint on circle passing through p1 and p2, closest to
+given coordinate. Z dimension is supported and is retrieved from the
+first 3D point amongst ``p1`` and ``p2``.
 %End
 
     static double circleTangentDirection( const QgsPoint &tangentPoint, const QgsPoint &cp1, const QgsPoint &cp2, const QgsPoint &cp3 );
@@ -397,6 +401,8 @@ A Z dimension is added to ``point`` if one of the point in the list
 :param point: The point to update with Z dimension and value.
 
 :return: true if the point is updated, false otherwise
+
+.. versionadded:: 3.0
 %End
 
 

diff --git a/python/core/geometry/qgstriangle.sip.in b/python/core/geometry/qgstriangle.sip.in
@@ -378,7 +378,8 @@ Example:
 
     QgsPoint inscribedCenter() const;
 %Docstring
-Center of the inscribed circle of the triangle.
+Center of the inscribed circle of the triangle. Z dimension is
+supported and is retrieved from the first 3D point amongst vertexes.
 
 :return: The center of the inscribed circle of the triangle.
 An empty point is returned for empty triangle.

diff --git a/src/core/geometry/qgscircle.h b/src/core/geometry/qgscircle.h
@@ -54,7 +54,9 @@ class CORE_EXPORT QgsCircle : public QgsEllipse
 
     /**
      * Constructs a circle by 2 points on the circle.
-     * The center point can have z and m values which are the result from the midpoint operation between \a pt1 and \a pt2.
+     * The center point can have m value which is the result from the midpoint
+     * operation between \a pt1 and \a pt2. Z dimension is also supported and
+     * is retrieved from the first 3D point amongst \a pt1 and \a pt2.
      * The radius is calculated from the 2D distance between \a pt1 and \a pt2.
      * The azimuth is the angle between \a pt1 and \a pt2.
      * \param pt1 First point.
@@ -64,7 +66,9 @@ class CORE_EXPORT QgsCircle : public QgsEllipse
 
     /**
      * Constructs a circle by 3 points on the circle.
-     * Z and m values are dropped for the center point.
+     * M value is dropped for the center point.
+     * Z dimension is supported and is retrieved from the first 3D point
+     * amongst \a pt1, \a pt2 and \a pt3.
      * The azimuth always takes the default value.
      * If the points are colinear an empty circle is returned.
      * \param pt1 First point.
@@ -113,7 +117,9 @@ class CORE_EXPORT QgsCircle : public QgsEllipse
 
     /**
      * Constructs a circle by an extent (aka bounding box / QgsRectangle).
-     * The center point can have z and m values which are the result from the midpoint operation between \a pt1 and \a pt2.
+     * The center point can have m value which is the result from the midpoint
+     * operation between \a pt1 and \a pt2. Z dimension is also supported and
+     * is retrieved from the first 3D point amongst \a pt1 and \a pt2.
      * Axes are calculated from the 2D distance between \a pt1 and \a pt2.
      * The azimuth always takes the default value.
      * \param pt1 First corner.

diff --git a/src/core/geometry/qgsellipse.h b/src/core/geometry/qgsellipse.h
@@ -59,7 +59,9 @@ class CORE_EXPORT QgsEllipse
 
     /**
      * Constructs an ellipse by foci (\a pt1 and \a pt2) and a point \a pt3.
-     * The center point can have z and m values which are the result from the midpoint operation between \a pt1 and \a pt2.
+     * The center point can have m value which is the result from the midpoint
+     * operation between \a pt1 and \a pt2. Z dimension is also supported and
+     * is retrieved from the first 3D point amongst \a pt1 and \a pt2.
      * Axes are calculated from the 2D distance with the third point \a pt3.
      * The azimuth is the angle between \a pt1 and \a pt2.
      * \param pt1 First focus.
@@ -70,7 +72,9 @@ class CORE_EXPORT QgsEllipse
 
     /**
      * Constructs an ellipse by an extent (aka bounding box / QgsRectangle).
-     * The center point can have z and m values which are the result from the midpoint operation between \a pt1 and \a pt2.
+     * The center point can have m value which is the result from the midpoint
+     * operation between \a pt1 and \a pt2. Z dimension is also supported and
+     * is retrieved from the first 3D point amongst \a pt1 and \a pt2.
      * Axes are calculated from the 2D distance between \a pt1 and \a pt2.
      * The azimuth always takes the default value.
      * \param pt1 First corner.
@@ -80,7 +84,9 @@ class CORE_EXPORT QgsEllipse
 
     /**
      * Constructs an ellipse by a center point and a another point.
-     * The center point keeps z and m values from \a ptc.
+     * The center point keeps m value from \a ptc. Z dimension is also
+     * supported and is retrieved from the first 3D point amongst \a ptc and
+     * \a pt1.
      * Axes are calculated from the 2D distance between \a ptc and \a pt1.
      * The azimuth always takes the default value.
      * \param ptc Center point.
@@ -90,7 +96,9 @@ class CORE_EXPORT QgsEllipse
 
     /**
      * Constructs an ellipse by a central point and two other points.
-     * The center point keeps z and m values from \a ptc.
+     * The center point keeps m value from \a ptc. Z dimension is also
+     * supported and is retrieved from the first 3D point amongst \a ptc,
+     * \a pt1 and \a pt2.
      * Axes are calculated from the 2D distance between \a ptc and \a pt1 and \a pt2.
      * The azimuth is the angle between \a ptc and \a pt1.
      * \param ptc Center point.

diff --git a/src/core/geometry/qgsgeometryutils.h b/src/core/geometry/qgsgeometryutils.h
@@ -90,7 +90,9 @@ class CORE_EXPORT QgsGeometryUtils
     static double sqrDistToLine( double ptX, double ptY, double x1, double y1, double x2, double y2, double &minDistX SIP_OUT, double &minDistY SIP_OUT, double epsilon );
 
     /**
-     * \brief Compute the intersection between two lines
+     * Computes the intersection between two lines. Z dimension is
+     * supported and is retrieved from the first 3D point amongst \a p1 and
+     * \a p2.
      * \param p1 Point on the first line
      * \param v1 Direction vector of the first line
      * \param p2 Point on the second line
@@ -225,7 +227,11 @@ class CORE_EXPORT QgsGeometryUtils
     //! Calculates angle of a circular string part defined by pt1, pt2, pt3
     static double sweepAngle( double centerX, double centerY, double x1, double y1, double x2, double y2, double x3, double y3 );
 
-    //! Calculates midpoint on circle passing through p1 and p2, closest to given coordinate
+    /**
+     * Calculates midpoint on circle passing through p1 and p2, closest to
+     * given coordinate. Z dimension is supported and is retrieved from the
+     * first 3D point amongst \a p1 and \a p2.
+     */
     static bool segmentMidPoint( const QgsPoint &p1, const QgsPoint &p2, QgsPoint &result SIP_OUT, double radius, const QgsPoint &mousePos );
 
     //! Calculates the direction angle of a circle tangent (clockwise from north in radians)
@@ -417,6 +423,8 @@ class CORE_EXPORT QgsGeometryUtils
      * \param points List of points in which a 3D point is searched.
      * \param point The point to update with Z dimension and value.
      * \returns true if the point is updated, false otherwise
+     *
+     * \since QGIS 3.0
      */
     static bool setZValueFromPoints( const QgsPointSequence &points, QgsPoint &point );
 

diff --git a/src/core/geometry/qgstriangle.h b/src/core/geometry/qgstriangle.h
@@ -351,7 +351,8 @@ class CORE_EXPORT QgsTriangle : public QgsPolygon
     QgsCircle circumscribedCircle() const;
 
     /**
-     * Center of the inscribed circle of the triangle.
+     * Center of the inscribed circle of the triangle. Z dimension is
+     * supported and is retrieved from the first 3D point amongst vertexes.
      * \returns The center of the inscribed circle of the triangle.
      * An empty point is returned for empty triangle.
      * * Example: