Skip to content
Permalink
Browse files

Expand QgsCoordinateTransform docs

  • Loading branch information
nyalldawson committed Dec 23, 2017
1 parent 1e06abb commit 87b8a370e9e1418afe8bc94554bf11a5f085f063
Showing with 40 additions and 0 deletions.
  1. +20 −0 python/core/qgscoordinatetransform.sip
  2. +20 −0 src/core/qgscoordinatetransform.h
@@ -62,6 +62,16 @@ The ``context`` argument specifies the context under which the transform
will be applied, and is used for calculating necessary datum transforms
to utilize.

Python scripts should generally use the constructor variant which accepts
a QgsProject instance instead of this constructor.

\warning Do NOT use an empty/default constructed QgsCoordinateTransformContext()
object when creating QgsCoordinateTransform objects. This prevents correct
datum transform handling and may result in inaccurate transformations. Always
ensure that the QgsCoordinateTransformContext object is correctly retrieved
based on the current code context, or use the constructor variant which
accepts a QgsProject argument instead.

.. versionadded:: 3.0
%End

@@ -76,6 +86,16 @@ given ``project``.
No reference to ``project`` is stored or utilized outside of the constructor,
and it is used to retrieve the project's transform context only.

Python scripts should utilise the QgsProject.instance() project
instance when creating QgsCoordinateTransform. This will ensure
that any datum transforms defined in the project will be
correctly respected during coordinate transforms. E.g.

.. code-block:: python

transform = QgsCoordinateTransform(QgsCoordinateReferenceSystem("EPSG:3111"),
QgsCoordinateReferenceSystem("EPSG:4326"), QgsProject.instance())

.. versionadded:: 3.0
%End

@@ -84,6 +84,16 @@ class CORE_EXPORT QgsCoordinateTransform
* will be applied, and is used for calculating necessary datum transforms
* to utilize.
*
* Python scripts should generally use the constructor variant which accepts
* a QgsProject instance instead of this constructor.
*
* \warning Do NOT use an empty/default constructed QgsCoordinateTransformContext()
* object when creating QgsCoordinateTransform objects. This prevents correct
* datum transform handling and may result in inaccurate transformations. Always
* ensure that the QgsCoordinateTransformContext object is correctly retrieved
* based on the current code context, or use the constructor variant which
* accepts a QgsProject argument instead.
*
* \since QGIS 3.0
*/
explicit QgsCoordinateTransform( const QgsCoordinateReferenceSystem &source,
@@ -98,6 +108,16 @@ class CORE_EXPORT QgsCoordinateTransform
* No reference to \a project is stored or utilized outside of the constructor,
* and it is used to retrieve the project's transform context only.
*
* Python scripts should utilise the QgsProject.instance() project
* instance when creating QgsCoordinateTransform. This will ensure
* that any datum transforms defined in the project will be
* correctly respected during coordinate transforms. E.g.
*
* \code{.py}
* transform = QgsCoordinateTransform(QgsCoordinateReferenceSystem("EPSG:3111"),
* QgsCoordinateReferenceSystem("EPSG:4326"), QgsProject.instance())
* \endcode
*
* \since QGIS 3.0
*/
explicit QgsCoordinateTransform( const QgsCoordinateReferenceSystem &source,

0 comments on commit 87b8a37

Please sign in to comment.
You can’t perform that action at this time.