Rename QgsGeometry::fromPolyline as QgsGeometry::fromPolylineXY

and add new QgsGeometry::fromPolyline which uses QgsPoint

We want to encourage people not to use the QgsPointXY method, as it drops
Z/M values. So it's moved across to a different name to make way
for a new QgsGeometry::fromPolyline which uses a QgsPoint list
instead of QgsPointXY, thus keeping Z/M values intact.

Similarly, QgsPolyline now is a list of QgsPoint (keeping z/m values)
and the old 2d QgsPolyline type was renamed to QgsPolylineXY.

Making the QgsPoint method the "preferred" method and making linestrings
just as easy to create from z/m dimensioned points as 2d points is
important to push people to write code which does not discard
these important dimensions.

As a bonus, the QgsPoint methods are more efficient anyway, since
they don't require creation of a temporary list.

doc/api_break.dox

@@ -1283,6 +1283,9 @@ empty geometry collection)
 - isGeosEmpty() was removed. Use isEmpty() instead.
 - reshapeGeometry() expects QgsLineString as a parameter instead of a list of 2D points (so that it can support 3D geometries)
 - vertexAt() now returns a QgsPoint (previously QgsPointV2) instead of a QgsPointXY (previously QgsPoint)
+- fromPolyline() now requires a list of QgsPoint objects, instead of QgsPointXY 2d points. A new method fromPolylineXY was
+added which uses the old list of 2d QgsPointXY objects. Using the newer method with QgsPoint is greatly preferred, as it
+maintains Z or M dimensions from the input points and is more efficient.
 
 
 QgsGeometryAnalyzer        {#qgis_api_break_3_0_QgsGeometryAnalyzer}
@@ -1891,6 +1894,13 @@ plugins calling this method will need to be updated.
 plugins calling this method will need to be updated.
 
 
+QgsPolyline        {#qgis_api_break_3_0_QgsPolyline}
+-----------
+
+- QgsPolyline now consists of a list of QgsPoint, instead of 2d QgsPointXY objects. The 2d polyline variant has
+been renamed to QgsPolylineXY
+
+
 QgsProject        {#qgis_api_break_3_0_QgsProject}
 ----------
 

python/core/geometry/qgsgeometry.sip

@@ -15,7 +15,9 @@
 
 
 
-typedef QVector<QgsPointXY> QgsPolyline;
+typedef QVector<QgsPointXY> QgsPolylineXY;
+
+typedef QVector<QgsPoint> QgsPolyline;
 
 typedef QVector<QVector<QgsPointXY>> QgsPolygon;
 
@@ -122,11 +124,35 @@ Creates a new geometry from a QgsPointXY object
 Creates a new geometry from a QgsMultiPoint object
  :rtype: QgsGeometry
 %End
+
+    static QgsGeometry fromPolylineXY( const QgsPolylineXY &polyline );
+%Docstring
+ Creates a new LineString geometry from a list of QgsPointXY points.
+
+ Using fromPolyline() is preferred, as fromPolyline() is more efficient
+ and will respect any Z or M dimensions present in the input points.
+
+.. note::
+
+   In QGIS 2.x this method was available as fromPolyline().
+
+.. versionadded:: 3.0
+.. seealso:: fromPolyline()
+ :rtype: QgsGeometry
+%End
+
     static QgsGeometry fromPolyline( const QgsPolyline &polyline );
 %Docstring
-Creates a new geometry from a QgsPolyline object
+ Creates a new LineString geometry from a list of QgsPoint points.
+
+ This method will respect any Z or M dimensions present in the input points.
+ E.g. if input points are PointZ type, the resultant linestring will be
+ a LineStringZ type.
+
+.. versionadded:: 3.0
  :rtype: QgsGeometry
 %End
+
     static QgsGeometry fromMultiPolyline( const QgsMultiPolyline &multiline );
 %Docstring
 Creates a new geometry from a QgsMultiPolyline object
@@ -1065,11 +1091,11 @@ Returns an extruded version of this geometry.
  :rtype: QgsPointXY
 %End
 
-    QgsPolyline asPolyline() const;
+    QgsPolylineXY asPolyline() const;
 %Docstring
  Returns contents of the geometry as a polyline
  if wkbType is WKBLineString, otherwise an empty list
- :rtype: QgsPolyline
+ :rtype: QgsPolylineXY
 %End
 
     QgsPolygon asPolygon() const;
@@ -1343,13 +1369,13 @@ Returns an extruded version of this geometry.
  :rtype: QgsGeometry
 %End
 
-    static QgsPolyline createPolylineFromQPolygonF( const QPolygonF &polygon ) /Factory/;
+    static QgsPolylineXY createPolylineFromQPolygonF( const QPolygonF &polygon ) /Factory/;
 %Docstring
- Creates a QgsPolyline from a QPolygonF.
+ Creates a QgsPolylineXY from a QPolygonF.
  \param polygon source polygon
- :return: QgsPolyline
+ :return: QgsPolylineXY
 .. seealso:: createPolygonFromQPolygonF
- :rtype: QgsPolyline
+ :rtype: QgsPolylineXY
 %End
 
     static QgsPolygon createPolygonFromQPolygonF( const QPolygonF &polygon ) /Factory/;
@@ -1365,7 +1391,7 @@ Returns an extruded version of this geometry.
     static bool compare( PyObject *obj1, PyObject *obj2, double epsilon = 4 * DBL_EPSILON );
 %Docstring
  Compares two geometry objects for equality within a specified tolerance.
- The objects can be of type QgsPolyline, QgsPolygon or QgsMultiPolygon.
+ The objects can be of type QgsPolylineXY, QgsPolygon or QgsMultiPolygon.
  The 2 types should match.
  \param p1 first geometry object
  \param p2 second geometry object
@@ -1402,10 +1428,10 @@ Returns an extruded version of this geometry.
                sipCanConvertToType( a0, sipType_QVector_0100QgsPointXY, SIP_NOT_NONE ) &&
                sipCanConvertToType( a1, sipType_QVector_0100QgsPointXY, SIP_NOT_NONE ) )
           {
-            QgsPolyline *p0;
-            QgsPolyline *p1;
-            p0 = reinterpret_cast<QgsPolyline *>( sipConvertToType( a0, sipType_QVector_0100QgsPointXY, 0, SIP_NOT_NONE, &state0, &sipIsErr ) );
-            p1 = reinterpret_cast<QgsPolyline *>( sipConvertToType( a1, sipType_QVector_0100QgsPointXY, 0, SIP_NOT_NONE, &state1, &sipIsErr ) );
+            QgsPolylineXY *p0;
+            QgsPolylineXY *p1;
+            p0 = reinterpret_cast<QgsPolylineXY *>( sipConvertToType( a0, sipType_QVector_0100QgsPointXY, 0, SIP_NOT_NONE, &state0, &sipIsErr ) );
+            p1 = reinterpret_cast<QgsPolylineXY *>( sipConvertToType( a1, sipType_QVector_0100QgsPointXY, 0, SIP_NOT_NONE, &state1, &sipIsErr ) );
             if ( sipIsErr )
             {
               sipReleaseType( p0, sipType_QVector_0100QgsPointXY, state0 );

python/plugins/processing/algs/qgis/Gridify.py

@@ -91,7 +91,7 @@ def processFeature(self, feature, feedback):
                     feedback.reportError(self.tr('Failed to gridify feature with FID {0}').format(feature.id()))
                     newGeom = None
                 else:
-                    newGeom = QgsGeometry.fromPolyline(points)
+                    newGeom = QgsGeometry.fromPolylineXY(points)
             elif geomType == QgsWkbTypes.MultiLineString:
                 polyline = []
                 for line in geom.asMultiPolyline():

python/plugins/processing/algs/qgis/HubDistanceLines.py

@@ -146,7 +146,7 @@ def processAlgorithm(self, parameters, context, feedback):
             feat = QgsFeature()
             feat.setAttributes(attributes)
 
-            feat.setGeometry(QgsGeometry.fromPolyline([src, closest]))
+            feat.setGeometry(QgsGeometry.fromPolylineXY([src, closest]))
 
             sink.addFeature(feat, QgsFeatureSink.FastInsert)
             feedback.setProgress(int(current * total))

python/plugins/processing/algs/qgis/ShortestPathLayerToPoint.py

@@ -260,7 +260,7 @@ def processAlgorithm(self, parameters, context, feedback):
             route.append(snappedPoints[i])
             route.reverse()
 
-            geom = QgsGeometry.fromPolyline(route)
+            geom = QgsGeometry.fromPolylineXY(route)
             feat.setGeometry(geom)
             feat['start'] = points[i].toString()
             feat['end'] = endPoint.toString()

python/plugins/processing/algs/qgis/ShortestPathPointToLayer.py

@@ -260,7 +260,7 @@ def processAlgorithm(self, parameters, context, feedback):
             route.append(snappedPoints[0])
             route.reverse()
 
-            geom = QgsGeometry.fromPolyline(route)
+            geom = QgsGeometry.fromPolylineXY(route)
             feat.setGeometry(geom)
             feat['start'] = startPoint.toString()
             feat['end'] = points[i].toString()

python/plugins/processing/algs/qgis/ShortestPathPointToPoint.py

@@ -234,7 +234,7 @@ def processAlgorithm(self, parameters, context, feedback):
         route.reverse()
 
         feedback.pushInfo(self.tr('Writing results...'))
-        geom = QgsGeometry.fromPolyline(route)
+        geom = QgsGeometry.fromPolylineXY(route)
         feat = QgsFeature()
         feat.setFields(fields)
         feat['start'] = startPoint.toString()

src/analysis/interpolation/DualEdgeTriangulation.cpp

@@ -3060,10 +3060,10 @@ bool DualEdgeTriangulation::saveTriangulation( QgsFeatureSink *sink, QgsFeedback
       //geometry
       QgsPoint *p1 = mPointVector[currentEdge->getPoint()];
       QgsPoint *p2 = mPointVector[mHalfEdge[currentEdge->getDual()]->getPoint()];
-      QgsPolyline lineGeom;
+      QgsPolylineXY lineGeom;
       lineGeom.push_back( QgsPointXY( p1->x(), p1->y() ) );
       lineGeom.push_back( QgsPointXY( p2->x(), p2->y() ) );
-      edgeLineFeature.setGeometry( QgsGeometry::fromPolyline( lineGeom ) );
+      edgeLineFeature.setGeometry( QgsGeometry::fromPolylineXY( lineGeom ) );
       edgeLineFeature.initAttributes( 1 );
 
       //attributes

src/analysis/network/qgsvectorlayerdirector.cpp

@@ -175,7 +175,7 @@ void QgsVectorLayerDirector::makeGraph( QgsGraphBuilderInterface *builder, const
     {
       QgsPointXY pt1, pt2;
       bool isFirstPoint = true;
-      QgsPolyline::iterator pointIt;
+      QgsPolylineXY::iterator pointIt;
       for ( pointIt = mplIt->begin(); pointIt != mplIt->end(); ++pointIt )
       {
         pt2 = ct.transform( *pointIt );
@@ -319,7 +319,7 @@ void QgsVectorLayerDirector::makeGraph( QgsGraphBuilderInterface *builder, const
       QgsPointXY pt1, pt2;
 
       bool isFirstPoint = true;
-      QgsPolyline::iterator pointIt;
+      QgsPolylineXY::iterator pointIt;
       for ( pointIt = mplIt->begin(); pointIt != mplIt->end(); ++pointIt )
       {
         pt2 = ct.transform( *pointIt );

src/app/nodetool/qgsnodetool.cpp

@@ -800,9 +800,9 @@ void QgsNodeTool::mouseMoveNotDragging( QgsMapMouseEvent *e )
     else
     {
       // straight edge
-      QgsPolyline points;
+      QgsPolylineXY points;
       points << p0 << p1;
-      mEdgeBand->setToGeometry( QgsGeometry::fromPolyline( points ), nullptr );
+      mEdgeBand->setToGeometry( QgsGeometry::fromPolylineXY( points ), nullptr );
     }
 
     QgsPointXY edgeCenter;
@@ -1757,9 +1757,9 @@ bool QgsNodeTool::matchEdgeCenterTest( const QgsPointLocator::Match &m, const Qg
   {
     // clip line segment to the extent so the mid-point marker is always visible
     QgsGeometry extentGeom = QgsGeometry::fromRect( visible_extent );
-    QgsGeometry lineGeom = QgsGeometry::fromPolyline( QgsPolyline() << p0 << p1 );
+    QgsGeometry lineGeom = QgsGeometry::fromPolylineXY( QgsPolylineXY() << p0 << p1 );
     lineGeom = extentGeom.intersection( lineGeom );
-    QgsPolyline polyline = lineGeom.asPolyline();
+    QgsPolylineXY polyline = lineGeom.asPolyline();
     Q_ASSERT( polyline.count() == 2 );
     p0 = polyline[0];
     p1 = polyline[1];

src/app/qgsmaptooldeletepart.cpp

@@ -152,7 +152,7 @@ QgsGeometry QgsMapToolDeletePart::partUnderPoint( QPoint point, QgsFeatureId &fi
           {
             fid = match.featureId();
             partNum = part;
-            return QgsGeometry::fromPolyline( mline[part] );
+            return QgsGeometry::fromPolylineXY( mline[part] );
           }
           snapVertex -= mline[part].count();
         }

src/app/qgsmaptooloffsetcurve.cpp

@@ -434,7 +434,7 @@ QgsGeometry QgsMapToolOffsetCurve::linestringFromPolygon( const QgsGeometry &fea
       if ( vertex < currentVertex )
       {
         //found, return ring
-        return QgsGeometry::fromPolyline( *polyIt );
+        return QgsGeometry::fromPolylineXY( *polyIt );
       }
     }
   }
@@ -468,7 +468,7 @@ QgsGeometry QgsMapToolOffsetCurve::convertToSingleLine( const QgsGeometry &geom,
       currentVertex += it->size();
       if ( vertex < currentVertex )
       {
-        return QgsGeometry::fromPolyline( *it );
+        return QgsGeometry::fromPolylineXY( *it );
       }
     }
   }

src/app/qgsmaptoolselectutils.cpp

@@ -185,11 +185,11 @@ QgsFeatureIds QgsMapToolSelectUtils::getMatchingFeatures( QgsMapCanvas *canvas,
       QgsPolygon poly( selectGeomTrans.asPolygon() );
       if ( poly.size() == 1 && poly.at( 0 ).size() == 5 )
       {
-        const QgsPolyline &ringIn = poly.at( 0 );
+        const QgsPolylineXY &ringIn = poly.at( 0 );
 
         QgsPolygon newpoly( 1 );
         newpoly[0].resize( 41 );
-        QgsPolyline &ringOut = newpoly[0];
+        QgsPolylineXY &ringOut = newpoly[0];
 
         ringOut[ 0 ] = ringIn.at( 0 );
 

src/app/qgsmaptoolsimplify.cpp

@@ -142,7 +142,7 @@ int QgsMapToolSimplify::vertexCount( const QgsGeometry &g ) const
       int count = 0;
       if ( g.isMultipart() )
       {
-        Q_FOREACH ( const QgsPolyline &polyline, g.asMultiPolyline() )
+        Q_FOREACH ( const QgsPolylineXY &polyline, g.asMultiPolyline() )
           count += polyline.count();
       }
       else
@@ -155,12 +155,12 @@ int QgsMapToolSimplify::vertexCount( const QgsGeometry &g ) const
       if ( g.isMultipart() )
       {
         Q_FOREACH ( const QgsPolygon &polygon, g.asMultiPolygon() )
-          Q_FOREACH ( const QgsPolyline &ring, polygon )
+          Q_FOREACH ( const QgsPolylineXY &ring, polygon )
             count += ring.count();
       }
       else
       {
-        Q_FOREACH ( const QgsPolyline &ring, g.asPolygon() )
+        Q_FOREACH ( const QgsPolylineXY &ring, g.asPolygon() )
           count += ring.count();
       }
       return count;

src/core/composer/qgscomposermapgrid.cpp

@@ -567,23 +567,23 @@ void QgsComposerMapGrid::calculateCrsTransformLines()
     QList< QPair< double, QPolygonF > >::const_iterator yGridIt = mTransformedYLines.constBegin();
     for ( ; yGridIt != mTransformedYLines.constEnd(); ++yGridIt )
     {
-      QgsPolyline yLine;
+      QgsPolylineXY yLine;
       for ( int i = 0; i < ( *yGridIt ).second.size(); ++i )
       {
         yLine.append( QgsPointXY( ( *yGridIt ).second.at( i ).x(), ( *yGridIt ).second.at( i ).y() ) );
       }
-      yLines << QgsGeometry::fromPolyline( yLine );
+      yLines << QgsGeometry::fromPolylineXY( yLine );
     }
     QList< QgsGeometry > xLines;
     QList< QPair< double, QPolygonF > >::const_iterator xGridIt = mTransformedXLines.constBegin();
     for ( ; xGridIt != mTransformedXLines.constEnd(); ++xGridIt )
     {
-      QgsPolyline xLine;
+      QgsPolylineXY xLine;
       for ( int i = 0; i < ( *xGridIt ).second.size(); ++i )
       {
         xLine.append( QgsPointXY( ( *xGridIt ).second.at( i ).x(), ( *xGridIt ).second.at( i ).y() ) );
       }
-      xLines << QgsGeometry::fromPolyline( xLine );
+      xLines << QgsGeometry::fromPolylineXY( xLine );
     }
 
     //now, loop through geometries and calculate intersection points