add an explanation

(cherry picked from commit 04c3c01)
qgis · Jun 19, 2020 · f6fca0c · f6fca0c
1 parent 286a062
commit f6fca0c
Show file tree

Hide file tree

Showing 3 changed files with 29 additions and 2 deletions.
diff --git a/python/core/auto_generated/geometry/qgsgeometry.sip.in b/python/core/auto_generated/geometry/qgsgeometry.sip.in
@@ -859,11 +859,20 @@ Splits this geometry according to a given line.
 Splits this geometry according to a given line.
 
 :param splitLine: the line that splits the geometry
-\param[out] newGeometries list of new geometries that have been created with the split
+\param[out] newGeometries list of new geometries that have been created with the ``splitLine``. If the geometry is 3D, a linear interpolation of the z value is performed on the geometry at split points, see example.
 :param topological: ``True`` if topological editing is enabled
 \param[out] topologyTestPoints points that need to be tested for topological completeness in the dataset
 
 :return: OperationResult a result code: success or reason of failure
+
+* Example:
+.. code-block:: python
+
+      geometry = QgsGeometry.fromWkt('CompoundCurveZ ((2749546.2003820720128715 1262904.45356595050543547 100, 2749557.82053794478997588 1262920.05570670193992555 200))')
+      split_line = [QgsPoint(2749544.19, 1262914.79), QgsPoint(2749557.64, 1262897.30)]
+      result, new_geometries, point_xy = geometry.splitGeometry(split_line, False)
+      print(geometry.asWkt(2))
+      > LineStringZ (2749549.12 1262908.38 125.14, 2749557.82 1262920.06 200)
 %End
 
     OperationResult reshapeGeometry( const QgsLineString &reshapeLineString );

diff --git a/src/core/geometry/qgsgeometry.cpp b/src/core/geometry/qgsgeometry.cpp
@@ -829,6 +829,15 @@ QgsGeometry::OperationResult QgsGeometry::splitGeometry( const QgsPointSequence
 
   QVector<QgsGeometry > newGeoms;
   QgsLineString splitLineString( splitLine );
+
+  /**
+   * QGIS uses GEOS algorithm to split geometries.
+   * Using 3D points in GEOS will returns an interpolation value which is the
+   * mean between geometries.
+   * On the contrary, in our logic, the interpolation is a linear interpolation
+   * on the split point. By dropping Z/M value, GEOS will returns the expected
+   * result. See https://github.com/qgis/QGIS/issues/33489
+   */
   splitLineString.dropZValue();
   splitLineString.dropMValue();
 

diff --git a/src/core/geometry/qgsgeometry.h b/src/core/geometry/qgsgeometry.h
@@ -888,10 +888,19 @@ class CORE_EXPORT QgsGeometry
     /**
      * Splits this geometry according to a given line.
      * \param splitLine the line that splits the geometry
-     * \param[out] newGeometries list of new geometries that have been created with the split
+     * \param[out] newGeometries list of new geometries that have been created with the ``splitLine``. If the geometry is 3D, a linear interpolation of the z value is performed on the geometry at split points, see example.
      * \param topological TRUE if topological editing is enabled
      * \param[out] topologyTestPoints points that need to be tested for topological completeness in the dataset
      * \returns OperationResult a result code: success or reason of failure
+     *
+     * * Example:
+     * \code{.py}
+     *  geometry = QgsGeometry.fromWkt('CompoundCurveZ ((2749546.2003820720128715 1262904.45356595050543547 100, 2749557.82053794478997588 1262920.05570670193992555 200))')
+     *  split_line = [QgsPoint(2749544.19, 1262914.79), QgsPoint(2749557.64, 1262897.30)]
+     *  result, new_geometries, point_xy = geometry.splitGeometry(split_line, False)
+     *  print(geometry.asWkt(2))
+     *  > LineStringZ (2749549.12 1262908.38 125.14, 2749557.82 1262920.06 200)
+     * \endcode
      */
     OperationResult splitGeometry( const QgsPointSequence &splitLine, QVector<QgsGeometry> &newGeometries SIP_OUT, bool topological, QgsPointSequence &topologyTestPoints SIP_OUT );