Skip to content
Permalink
Browse files
Expand on QgsPoint/QgsPointXY documentation to clarify when each
class should be used

Fixes #43598
  • Loading branch information
nyalldawson committed Jun 8, 2021
1 parent f4477b2 commit ae83444c9f0c5ce8056ac7b282d6fb1dedc43ad4
@@ -15,6 +15,17 @@ class QgsPoint: QgsAbstractGeometry
%Docstring(signature="appended")
Point geometry type, with support for z-dimension and m-values.

A :py:class:`QgsPoint` represents a 2, 3 or 4-dimensional position, with X and Y and optional
Z or M coordinates. Since it supports these additional dimensions, :py:class:`QgsPoint` is
used as the low-level storage of geometry coordinates throughout QGIS.

In some scenarios it is preferable to use the :py:class:`QgsPointXY` class instead, which is
lighter and has smaller memory requirements compared to :py:class:`QgsPoint`. See the :py:class:`QgsPointXY`
documentation for examples of situations where it is appropriate to use :py:class:`QgsPointXY`
instead of :py:class:`QgsPoint`.

.. seealso:: :py:class:`QgsPointXY`

.. versionadded:: 3.0
%End

@@ -17,9 +17,28 @@ class QgsPointXY
%Docstring(signature="appended")
A class to represent a 2D point.

A :py:class:`QgsPointXY` represents a position with X and Y coordinates.
In most scenarios it is preferable to use a :py:class:`QgsPoint` instead which also
supports Z and M values.
A :py:class:`QgsPointXY` represents a strictly 2-dimensional position, with only X and Y coordinates.
This is a very lightweight class, designed to minimize the memory requirements of storing
millions of points.

In many scenarios it is preferable to use a :py:class:`QgsPoint` instead which also
supports optional Z and M values. :py:class:`QgsPointXY` should only be used for situations where
a point can only EVER be two dimensional.

Some valid use cases for :py:class:`QgsPointXY` include:

- A mouse cursor location
- A coordinate on a purely 2-dimensional rendered map, e.g. a :py:class:`QgsMapCanvas`
- A coordinate in a raster, vector tile, or other purely 2-dimensional layer

Use cases for which :py:class:`QgsPointXY` is NOT a valid choice include:

- Storage of coordinates for a geometry. Since :py:class:`QgsPointXY` is strictly 2-dimensional

it should never be used to store coordinates for vector geometries, as this will involve
a loss of any z or m values present in the geometry.

.. seealso:: :py:class:`QgsPoint`

.. versionadded:: 3.0
%End
@@ -32,6 +32,17 @@
/**
* \ingroup core
* \brief Point geometry type, with support for z-dimension and m-values.
*
* A QgsPoint represents a 2, 3 or 4-dimensional position, with X and Y and optional
* Z or M coordinates. Since it supports these additional dimensions, QgsPoint is
* used as the low-level storage of geometry coordinates throughout QGIS.
*
* In some scenarios it is preferable to use the QgsPointXY class instead, which is
* lighter and has smaller memory requirements compared to QgsPoint. See the QgsPointXY
* documentation for examples of situations where it is appropriate to use QgsPointXY
* instead of QgsPoint.
*
* \see QgsPointXY
* \since QGIS 3.0, (previously QgsPointV2 since QGIS 2.10)
*/
class CORE_EXPORT QgsPoint: public QgsAbstractGeometry
@@ -34,10 +34,28 @@ class QgsPoint;
* \ingroup core
* \brief A class to represent a 2D point.
*
* A QgsPointXY represents a position with X and Y coordinates.
* In most scenarios it is preferable to use a QgsPoint instead which also
* supports Z and M values.
* A QgsPointXY represents a strictly 2-dimensional position, with only X and Y coordinates.
* This is a very lightweight class, designed to minimize the memory requirements of storing
* millions of points.
*
* In many scenarios it is preferable to use a QgsPoint instead which also
* supports optional Z and M values. QgsPointXY should only be used for situations where
* a point can only EVER be two dimensional.
*
* Some valid use cases for QgsPointXY include:
*
* - A mouse cursor location
* - A coordinate on a purely 2-dimensional rendered map, e.g. a QgsMapCanvas
* - A coordinate in a raster, vector tile, or other purely 2-dimensional layer
*
* Use cases for which QgsPointXY is NOT a valid choice include:
*
* - Storage of coordinates for a geometry. Since QgsPointXY is strictly 2-dimensional
*
* it should never be used to store coordinates for vector geometries, as this will involve
* a loss of any z or m values present in the geometry.
*
* \see QgsPoint
* \since QGIS 3.0
*/
class CORE_EXPORT QgsPointXY

0 comments on commit ae83444

Please sign in to comment.