QGIS API Documentation 3.28.0-Firenze (ed3ad0430f)
Public Member Functions | Static Public Member Functions | Friends | List of all members
QgsCoordinateTransform Class Reference

Class for doing transforms between two map coordinate systems. More...

#include <qgscoordinatetransform.h>

Public Member Functions

 QgsCoordinateTransform ()
 Default constructor, creates an invalid QgsCoordinateTransform. More...
 
 QgsCoordinateTransform (const QgsCoordinateReferenceSystem &source, const QgsCoordinateReferenceSystem &destination, const QgsCoordinateTransformContext &context, Qgis::CoordinateTransformationFlags flags=Qgis::CoordinateTransformationFlags())
 Constructs a QgsCoordinateTransform to transform from the source to destination coordinate reference system. More...
 
 QgsCoordinateTransform (const QgsCoordinateReferenceSystem &source, const QgsCoordinateReferenceSystem &destination, const QgsProject *project, Qgis::CoordinateTransformationFlags flags=Qgis::CoordinateTransformationFlags())
 Constructs a QgsCoordinateTransform to transform from the source to destination coordinate reference system, when used with the given project. More...
 
Q_DECL_DEPRECATED QgsCoordinateTransform (const QgsCoordinateReferenceSystem &source, const QgsCoordinateReferenceSystem &destination, int sourceDatumTransformId, int destinationDatumTransformId)
 Constructs a QgsCoordinateTransform to transform from the source to destination coordinate reference system, with the specified datum transforms (see QgsDatumTransform). More...
 
 QgsCoordinateTransform (const QgsCoordinateTransform &o)
 Copy constructor. More...
 
 ~QgsCoordinateTransform ()
 
bool allowFallbackTransforms () const
 Returns whether "ballpark" fallback transformations will be used in the case that the specified coordinate operation fails (such as when coordinates from outside a required grid shift file are transformed). More...
 
QgsCoordinateTransformContext context () const
 Returns the context in which the coordinate transform will be calculated. More...
 
QString coordinateOperation () const
 Returns a Proj string representing the coordinate operation which will be used to transform coordinates. More...
 
QgsCoordinateReferenceSystem destinationCrs () const
 Returns the destination coordinate reference system, which the transform will transform coordinates to. More...
 
Q_DECL_DEPRECATED int destinationDatumTransformId () const
 Returns the ID of the datum transform to use when projecting to the destination CRS. More...
 
void disableFallbackOperationHandler (bool disabled)
 Sets whether the default fallback operation handler is disabled for this transform instance. More...
 
bool fallbackOperationOccurred () const
 Returns true if a fallback operation occurred for the most recent transform. More...
 
QgsDatumTransform::TransformDetails instantiatedCoordinateOperationDetails () const
 Returns the transform details representing the coordinate operation which is being used to transform coordinates. More...
 
bool isShortCircuited () const
 Returns true if the transform short circuits because the source and destination are equivalent. More...
 
bool isValid () const
 Returns true if the coordinate transform is valid, ie both the source and destination CRS have been set and are valid. More...
 
QgsCoordinateTransformoperator= (const QgsCoordinateTransform &o)
 Assignment operator. More...
 
double scaleFactor (const QgsRectangle &referenceExtent) const
 Computes an estimated conversion factor between source and destination units: More...
 
void setAllowFallbackTransforms (bool allowed)
 Sets whether "ballpark" fallback transformations can be used in the case that the specified coordinate operation fails (such as when coordinates from outside a required grid shift file are transformed). More...
 
void setBallparkTransformsAreAppropriate (bool appropriate)
 Sets whether approximate "ballpark" results are appropriate for this coordinate transform. More...
 
void setContext (const QgsCoordinateTransformContext &context)
 Sets the context in which the coordinate transform should be calculated. More...
 
void setCoordinateOperation (const QString &operation) const
 Sets a Proj string representing the coordinate operation which will be used to transform coordinates. More...
 
void setDestinationCrs (const QgsCoordinateReferenceSystem &crs)
 Sets the destination coordinate reference system. More...
 
Q_DECL_DEPRECATED void setDestinationDatumTransformId (int datumId)
 Sets the datumId ID of the datum transform to use when projecting to the destination CRS. More...
 
void setSourceCrs (const QgsCoordinateReferenceSystem &crs)
 Sets the source coordinate reference system. More...
 
Q_DECL_DEPRECATED void setSourceDatumTransformId (int datumId)
 Sets the datumId ID of the datum transform to use when projecting from the source CRS. More...
 
QgsCoordinateReferenceSystem sourceCrs () const
 Returns the source coordinate reference system, which the transform will transform coordinates from. More...
 
Q_DECL_DEPRECATED int sourceDatumTransformId () const
 Returns the ID of the datum transform to use when projecting from the source CRS. More...
 
QgsPointXY transform (const QgsPointXY &point, Qgis::TransformDirection direction=Qgis::TransformDirection::Forward) const SIP_THROW(QgsCsException)
 Transform the point from the source CRS to the destination CRS. More...
 
QgsRectangle transform (const QgsRectangle &rectangle, Qgis::TransformDirection direction=Qgis::TransformDirection::Forward) const SIP_THROW(QgsCsException)
 Transforms a rectangle to the destination CRS. More...
 
QgsVector3D transform (const QgsVector3D &point, Qgis::TransformDirection direction=Qgis::TransformDirection::Forward) const
 Transform the point specified in 3D coordinates from the source CRS to the destination CRS. More...
 
QgsPointXY transform (double x, double y, Qgis::TransformDirection direction=Qgis::TransformDirection::Forward) const
 Transform the point specified by x,y from the source CRS to the destination CRS. More...
 
QgsRectangle transformBoundingBox (const QgsRectangle &rectangle, Qgis::TransformDirection direction=Qgis::TransformDirection::Forward, bool handle180Crossover=false) const SIP_THROW(QgsCsException)
 Transforms a rectangle from the source CRS to the destination CRS. More...
 
void transformCoords (int numPoint, double *x, double *y, double *z, Qgis::TransformDirection direction=Qgis::TransformDirection::Forward) const SIP_THROW(QgsCsException)
 Transform an array of coordinates to the destination CRS. More...
 
void transformInPlace (double &x, double &y, double &z, Qgis::TransformDirection direction=Qgis::TransformDirection::Forward) const SIP_THROW(QgsCsException)
 Transforms an array of x, y and z double coordinates in place, from the source CRS to the destination CRS. More...
 
void transformInPlace (float &x, float &y, double &z, Qgis::TransformDirection direction=Qgis::TransformDirection::Forward) const
 Transforms an array of x, y and z float coordinates in place, from the source CRS to the destination CRS. More...
 
void transformInPlace (float &x, float &y, float &z, Qgis::TransformDirection direction=Qgis::TransformDirection::Forward) const
 Transforms an array of x, y and z float coordinates in place, from the source CRS to the destination CRS. More...
 
void transformInPlace (QVector< double > &x, QVector< double > &y, QVector< double > &z, Qgis::TransformDirection direction=Qgis::TransformDirection::Forward) const
 Transforms a vector of x, y and z double coordinates in place, from the source CRS to the destination CRS. More...
 
void transformInPlace (QVector< float > &x, QVector< float > &y, QVector< float > &z, Qgis::TransformDirection direction=Qgis::TransformDirection::Forward) const
 Transforms a vector of x, y and z float coordinates in place, from the source CRS to the destination CRS. More...
 
void transformPolygon (QPolygonF &polygon, Qgis::TransformDirection direction=Qgis::TransformDirection::Forward) const SIP_THROW(QgsCsException)
 Transforms a polygon to the destination coordinate system. More...
 

Static Public Member Functions

static void invalidateCache (bool disableCache=false)
 Clears the internal cache used to initialize QgsCoordinateTransform objects. More...
 
static bool isTransformationPossible (const QgsCoordinateReferenceSystem &source, const QgsCoordinateReferenceSystem &destination)
 Returns true if it is theoretically possible to transform between source and destination CRSes. More...
 
static void setCustomCoordinateOperationCreationErrorHandler (const std::function< void(const QgsCoordinateReferenceSystem &sourceCrs, const QgsCoordinateReferenceSystem &destinationCrs, const QString &error)> &handler)
 Sets a custom handler to use when a coordinate transform was required between sourceCrs and destinationCrs, yet the coordinate operation could not be created. More...
 
static void setCustomMissingGridUsedByContextHandler (const std::function< void(const QgsCoordinateReferenceSystem &sourceCrs, const QgsCoordinateReferenceSystem &destinationCrs, const QgsDatumTransform::TransformDetails &desiredOperation)> &handler)
 Sets a custom handler to use when a coordinate operation was specified for use between sourceCrs and destinationCrs by the transform context, yet the coordinate operation could not be created. More...
 
static void setCustomMissingPreferredGridHandler (const std::function< void(const QgsCoordinateReferenceSystem &sourceCrs, const QgsCoordinateReferenceSystem &destinationCrs, const QgsDatumTransform::TransformDetails &preferredOperation, const QgsDatumTransform::TransformDetails &availableOperation)> &handler)
 Sets a custom handler to use when a coordinate transform is created between sourceCrs and destinationCrs, yet a preferred (more accurate?) operation is available which could not be created on the system (e.g. More...
 
static void setCustomMissingRequiredGridHandler (const std::function< void(const QgsCoordinateReferenceSystem &sourceCrs, const QgsCoordinateReferenceSystem &destinationCrs, const QgsDatumTransform::GridDetails &grid)> &handler)
 Sets a custom handler to use when a coordinate transform is created between sourceCrs and destinationCrs, yet the coordinate operation requires a transform grid which is not present on the system. More...
 
static void setDynamicCrsToDynamicCrsWarningHandler (const std::function< void(const QgsCoordinateReferenceSystem &sourceCrs, const QgsCoordinateReferenceSystem &destinationCrs)> &handler)
 Sets a custom handler to use when the desired coordinate operation for use between sourceCrs and destinationCrs is a dynamic CRS to dynamic CRS transform, not currently supported by PROJ. More...
 
static void setFallbackOperationOccurredHandler (const std::function< void(const QgsCoordinateReferenceSystem &sourceCrs, const QgsCoordinateReferenceSystem &destinationCrs, const QString &desiredOperation)> &handler)
 Sets a custom handler to use when the desired coordinate operation for use between sourceCrs and destinationCrs failed and an alternative fallback operation was utilized instead. More...
 

Friends

class QgsProjContext
 
class TestQgsCoordinateTransform
 

Detailed Description

Class for doing transforms between two map coordinate systems.

This class can convert map coordinates to a different coordinate reference system. It is normally associated with a map layer and is used to transform between the layer's coordinate system and the coordinate system of the map canvas, although it can be used in a more general sense to transform coordinates.

When used to transform between a layer and the map canvas, all references to source and destination coordinate systems refer to layer and map canvas respectively. All operations are from the perspective of the layer. For example, a forward transformation transforms coordinates from the layer's coordinate system to the map canvas.

Note
Since QGIS 3.0 QgsCoordinateReferenceSystem objects are implicitly shared.
Warning
Since QGIS 3.20 The QgsCoordinateTransform class can perform time-dependent transformations between a static and dynamic CRS based on either the source OR destination CRS coordinate epoch, however dynamic CRS to dynamic CRS transformations are not currently supported.
See also
QgsDatumTransform
QgsCoordinateTransformContext

Definition at line 57 of file qgscoordinatetransform.h.

Constructor & Destructor Documentation

◆ QgsCoordinateTransform() [1/5]

QgsCoordinateTransform::QgsCoordinateTransform ( )

Default constructor, creates an invalid QgsCoordinateTransform.

Definition at line 57 of file qgscoordinatetransform.cpp.

◆ QgsCoordinateTransform() [2/5]

QgsCoordinateTransform::QgsCoordinateTransform ( const QgsCoordinateReferenceSystem source,
const QgsCoordinateReferenceSystem destination,
const QgsCoordinateTransformContext context,
Qgis::CoordinateTransformationFlags  flags = Qgis::CoordinateTransformationFlags() 
)
explicit

Constructs a QgsCoordinateTransform to transform from the source to destination coordinate reference system.

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.

Since QGIS 3.26 the optional flags argument can be used to specify flags which dictate the behavior of the transformation.

Warning
Since QGIS 3.20 The QgsCoordinateTransform class can perform time-dependent transformations between a static and dynamic CRS based on either the source OR destination CRS coordinate epoch, however dynamic CRS to dynamic CRS transformations are not currently supported.
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

Definition at line 62 of file qgscoordinatetransform.cpp.

◆ QgsCoordinateTransform() [3/5]

QgsCoordinateTransform::QgsCoordinateTransform ( const QgsCoordinateReferenceSystem source,
const QgsCoordinateReferenceSystem destination,
const QgsProject project,
Qgis::CoordinateTransformationFlags  flags = Qgis::CoordinateTransformationFlags() 
)
explicit

Constructs a QgsCoordinateTransform to transform from the source to destination coordinate reference system, when used with the 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 utilize 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.

This class represents a coordinate reference system (CRS).
Class for doing transforms between two map coordinate systems.
static QgsProject * instance()
Returns the QgsProject singleton instance.
Definition: qgsproject.cpp:477

Since QGIS 3.26 the optional flags argument can be used to specify flags which dictate the behavior of the transformation.

Warning
Since QGIS 3.20 The QgsCoordinateTransform class can perform time-dependent transformations between a static and dynamic CRS based on either the source OR destination CRS coordinate epoch, however dynamic CRS to dynamic CRS transformations are not currently supported.
Since
QGIS 3.0

Definition at line 95 of file qgscoordinatetransform.cpp.

◆ QgsCoordinateTransform() [4/5]

QgsCoordinateTransform::QgsCoordinateTransform ( const QgsCoordinateReferenceSystem source,
const QgsCoordinateReferenceSystem destination,
int  sourceDatumTransformId,
int  destinationDatumTransformId 
)
explicit

Constructs a QgsCoordinateTransform to transform from the source to destination coordinate reference system, with the specified datum transforms (see QgsDatumTransform).

Deprecated:
will be removed in QGIS 4.0. Use the constructor with a QgsCoordinateTransformContext argument instead.
Since
QGIS 3.0

Definition at line 128 of file qgscoordinatetransform.cpp.

◆ QgsCoordinateTransform() [5/5]

QgsCoordinateTransform::QgsCoordinateTransform ( const QgsCoordinateTransform o)

Copy constructor.

Definition at line 147 of file qgscoordinatetransform.cpp.

◆ ~QgsCoordinateTransform()

QgsCoordinateTransform::~QgsCoordinateTransform ( )

Definition at line 168 of file qgscoordinatetransform.cpp.

Member Function Documentation

◆ allowFallbackTransforms()

bool QgsCoordinateTransform::allowFallbackTransforms ( ) const

Returns whether "ballpark" fallback transformations will be used in the case that the specified coordinate operation fails (such as when coordinates from outside a required grid shift file are transformed).

See fallbackOperationOccurred() for further details.

Note
Requires Proj 6.0 or later. Builds based on earlier Proj versions will ignore this setting.
See also
setAllowFallbackTransforms()
setBallparkTransformsAreAppropriate()
Since
QGIS 3.12

Definition at line 927 of file qgscoordinatetransform.cpp.

◆ context()

QgsCoordinateTransformContext QgsCoordinateTransform::context ( ) const

Returns the context in which the coordinate transform will be calculated.

See also
setContext()
Since
QGIS 3.4

Definition at line 257 of file qgscoordinatetransform.cpp.

◆ coordinateOperation()

QString QgsCoordinateTransform::coordinateOperation ( ) const

Returns a Proj string representing the coordinate operation which will be used to transform coordinates.

Note
The string returned by this method gives the desired coordinate operation string, based on the state of the QgsCoordinateTransformContext object given in the QgsCoordinateTransform's constructor. It may be an empty string if no explicit coordinate operation is required. In order to determine the ACTUAL coordinate operation which is being used by the transform, use the instantiatedCoordinateOperationDetails() call instead.
Requires Proj 6.0 or later. Builds based on earlier Proj versions will always return an empty string, and the deprecated sourceDatumTransformId() or destinationDatumTransformId() methods should be used instead.
See also
instantiatedCoordinateOperationDetails()
setCoordinateOperation()
Since
QGIS 3.8

Definition at line 903 of file qgscoordinatetransform.cpp.

◆ destinationCrs()

QgsCoordinateReferenceSystem QgsCoordinateTransform::destinationCrs ( ) const

Returns the destination coordinate reference system, which the transform will transform coordinates to.

See also
setDestinationCrs()
sourceCrs()

Definition at line 267 of file qgscoordinatetransform.cpp.

◆ destinationDatumTransformId()

int QgsCoordinateTransform::destinationDatumTransformId ( ) const

Returns the ID of the datum transform to use when projecting to the destination CRS.

This is usually calculated automatically from the transform's QgsCoordinateTransformContext, but can be manually overwritten by a call to setDestinationDatumTransformId().

See also
QgsDatumTransform
setDestinationDatumTransformId()
sourceDatumTransformId()
Deprecated:
Unused on builds based on Proj 6.0 or later

Definition at line 1039 of file qgscoordinatetransform.cpp.

◆ disableFallbackOperationHandler()

void QgsCoordinateTransform::disableFallbackOperationHandler ( bool  disabled)

Sets whether the default fallback operation handler is disabled for this transform instance.

If the default handler is disabled then it is possible to determine whether a fallback operation occurred by testing fallbackOperationOccurred() immediately after a transformation.

Warning
This setting applies to a single instance of a coordinate transform only, and is not copied when a coordinate transform object is copied or assigned.
Note
Requires Proj 6.0 or later. Builds based on earlier Proj versions will never perform fallback operations.
See also
fallbackOperationOccurred()
Since
QGIS 3.12

Definition at line 937 of file qgscoordinatetransform.cpp.

◆ fallbackOperationOccurred()

bool QgsCoordinateTransform::fallbackOperationOccurred ( ) const

Returns true if a fallback operation occurred for the most recent transform.

Note
Requires Proj 6.0 or later. Builds based on earlier Proj versions will never perform fallback operations.
See also
disableFallbackOperationHandler()
Since
QGIS 3.12

Definition at line 942 of file qgscoordinatetransform.cpp.

◆ instantiatedCoordinateOperationDetails()

QgsDatumTransform::TransformDetails QgsCoordinateTransform::instantiatedCoordinateOperationDetails ( ) const

Returns the transform details representing the coordinate operation which is being used to transform coordinates.

This may differ from the result returned by coordinateOperation() if the desired coordinate operation was not successfully instantiated.

Note
Requires Proj 6.0 or later. Builds based on earlier Proj versions will always return an empty result, and the deprecated sourceDatumTransformId() or destinationDatumTransformId() methods should be used instead.
See also
coordinateOperation()
Since
QGIS 3.10.2

Definition at line 908 of file qgscoordinatetransform.cpp.

◆ invalidateCache()

void QgsCoordinateTransform::invalidateCache ( bool  disableCache = false)
static

Clears the internal cache used to initialize QgsCoordinateTransform objects.

This should be called whenever the srs database has been modified in order to ensure that outdated CRS transforms are not created.

If disableCache is true then the inbuilt cache will be completely disabled. This argument is for internal use only.

Since
QGIS 3.0

Definition at line 1054 of file qgscoordinatetransform.cpp.

◆ isShortCircuited()

bool QgsCoordinateTransform::isShortCircuited ( ) const

Returns true if the transform short circuits because the source and destination are equivalent.

Definition at line 898 of file qgscoordinatetransform.cpp.

◆ isTransformationPossible()

bool QgsCoordinateTransform::isTransformationPossible ( const QgsCoordinateReferenceSystem source,
const QgsCoordinateReferenceSystem destination 
)
static

Returns true if it is theoretically possible to transform between source and destination CRSes.

For example, will return false if source and destination relate to different celestial bodies and a transformation between them will never be possible.

Warning
This method tests only if it is theoretically possible to transform between the CRSes, not whether a transform can actually be constructed on the system. It is possible that this method may return true, yet construction of a matching QgsCoordinateTransform fails (e.g. due to missing grid shift files on the system).
Since
QGIS 3.26

Definition at line 170 of file qgscoordinatetransform.cpp.

◆ isValid()

bool QgsCoordinateTransform::isValid ( ) const

Returns true if the coordinate transform is valid, ie both the source and destination CRS have been set and are valid.

Since
QGIS 3.0

Definition at line 893 of file qgscoordinatetransform.cpp.

◆ operator=()

QgsCoordinateTransform & QgsCoordinateTransform::operator= ( const QgsCoordinateTransform o)

Assignment operator.

Definition at line 157 of file qgscoordinatetransform.cpp.

◆ scaleFactor()

double QgsCoordinateTransform::scaleFactor ( const QgsRectangle referenceExtent) const

Computes an estimated conversion factor between source and destination units:

sourceUnits * scaleFactor = destinationUnits

Parameters
referenceExtentA reference extent based on which to perform the computation
Since
QGIS 3.4

Definition at line 1092 of file qgscoordinatetransform.cpp.

◆ setAllowFallbackTransforms()

void QgsCoordinateTransform::setAllowFallbackTransforms ( bool  allowed)

Sets whether "ballpark" fallback transformations can be used in the case that the specified coordinate operation fails (such as when coordinates from outside a required grid shift file are transformed).

See fallbackOperationOccurred() for further details.

Note
Requires Proj 6.0 or later. Builds based on earlier Proj versions will ignore this setting.
Warning
If setBallparkTransformsAreAppropriate() is set to true, this setting will be ignored and fallback transformations will always be permitted.
See also
allowFallbackTransforms()
setBallparkTransformsAreAppropriate()
Since
QGIS 3.12

Definition at line 921 of file qgscoordinatetransform.cpp.

◆ setBallparkTransformsAreAppropriate()

void QgsCoordinateTransform::setBallparkTransformsAreAppropriate ( bool  appropriate)

Sets whether approximate "ballpark" results are appropriate for this coordinate transform.

When a coordinate transform is only being used to generate ballpark results then the appropriate argument should be set to true. This indicates that its perfectable acceptable (and even expected!) for the transform to use fallback coordinate operations in the case that the preferred or user-specified operation fails (such as when coordinates from outside of a grid shift file's extent are transformed).

When appropriate is true, then no warnings will be generated when the transform falls back to a default operation, which may introduce inaccuracies when compared to the default/specified coordinate operation.

This should be set when a transform expects that coordinates outside of the direct area of use while be transformed, e.g. when transforming from a global extent to a CRS with a localized area of use.

If appropriate is false (the default behavior), then transforms MAY STILL fallback to default operations when the preferred or user-specified operation fails, however whenever this occurs a user-visible warning will be generated.

If appropriate is true, then this setting overrides allowFallbackTransforms() and fallback transforms will always be allowed when required.

Warning
This setting applies to a single instance of a coordinate transform only, and is not copied when a coordinate transform object is copied or assigned.
Note
Requires Proj 6.0 or later. Builds based on earlier Proj versions will ignore this setting.
Since
QGIS 3.12

Definition at line 932 of file qgscoordinatetransform.cpp.

◆ setContext()

void QgsCoordinateTransform::setContext ( const QgsCoordinateTransformContext context)

Sets the context in which the coordinate transform should be calculated.

See also
context()
Since
QGIS 3.0

Definition at line 230 of file qgscoordinatetransform.cpp.

◆ setCoordinateOperation()

void QgsCoordinateTransform::setCoordinateOperation ( const QString &  operation) const

Sets a Proj string representing the coordinate operation which will be used to transform coordinates.

Warning
It is the caller's responsibility to ensure that operation is a valid Proj coordinate operation string.
Note
Requires Proj 6.0 or later. Builds based on earlier Proj versions will ignore this setting, and the deprecated setSourceDatumTransformId() or setDestinationDatumTransformId() methods should be used instead.
See also
coordinateOperation()
Since
QGIS 3.8

Definition at line 914 of file qgscoordinatetransform.cpp.

◆ setCustomCoordinateOperationCreationErrorHandler()

void QgsCoordinateTransform::setCustomCoordinateOperationCreationErrorHandler ( const std::function< void(const QgsCoordinateReferenceSystem &sourceCrs, const QgsCoordinateReferenceSystem &destinationCrs, const QString &error)> &  handler)
static

Sets a custom handler to use when a coordinate transform was required between sourceCrs and destinationCrs, yet the coordinate operation could not be created.

The error argument specifies the error message obtained.

See also
setCustomMissingRequiredGridHandler()
setCustomMissingPreferredGridHandler()
setCustomMissingGridUsedByContextHandler()
Note
Not available in Python bindings
Since
QGIS 3.8

Definition at line 1113 of file qgscoordinatetransform.cpp.

◆ setCustomMissingGridUsedByContextHandler()

void QgsCoordinateTransform::setCustomMissingGridUsedByContextHandler ( const std::function< void(const QgsCoordinateReferenceSystem &sourceCrs, const QgsCoordinateReferenceSystem &destinationCrs, const QgsDatumTransform::TransformDetails &desiredOperation)> &  handler)
static

Sets a custom handler to use when a coordinate operation was specified for use between sourceCrs and destinationCrs by the transform context, yet the coordinate operation could not be created.

The desiredOperation argument specifies the desired transform details as specified by the context.

See also
setCustomMissingRequiredGridHandler()
setCustomMissingPreferredGridHandler()
setCustomCoordinateOperationCreationErrorHandler()
Note
Not available in Python bindings
Since
QGIS 3.8

Definition at line 1118 of file qgscoordinatetransform.cpp.

◆ setCustomMissingPreferredGridHandler()

void QgsCoordinateTransform::setCustomMissingPreferredGridHandler ( const std::function< void(const QgsCoordinateReferenceSystem &sourceCrs, const QgsCoordinateReferenceSystem &destinationCrs, const QgsDatumTransform::TransformDetails &preferredOperation, const QgsDatumTransform::TransformDetails &availableOperation)> &  handler)
static

Sets a custom handler to use when a coordinate transform is created between sourceCrs and destinationCrs, yet a preferred (more accurate?) operation is available which could not be created on the system (e.g.

due to missing transform grids).

preferredOperation gives the details of the preferred coordinate operation, and availableOperation gives the details of the actual operation to be used during the transform.

See also
setCustomMissingRequiredGridHandler()
setCustomCoordinateOperationCreationErrorHandler()
setCustomMissingGridUsedByContextHandler()
Note
Not available in Python bindings
Since
QGIS 3.8

Definition at line 1108 of file qgscoordinatetransform.cpp.

◆ setCustomMissingRequiredGridHandler()

void QgsCoordinateTransform::setCustomMissingRequiredGridHandler ( const std::function< void(const QgsCoordinateReferenceSystem &sourceCrs, const QgsCoordinateReferenceSystem &destinationCrs, const QgsDatumTransform::GridDetails &grid)> &  handler)
static

Sets a custom handler to use when a coordinate transform is created between sourceCrs and destinationCrs, yet the coordinate operation requires a transform grid which is not present on the system.

See also
setCustomMissingPreferredGridHandler()
setCustomCoordinateOperationCreationErrorHandler()
setCustomMissingGridUsedByContextHandler()
Note
Not available in Python bindings
Since
QGIS 3.8

Definition at line 1103 of file qgscoordinatetransform.cpp.

◆ setDestinationCrs()

void QgsCoordinateTransform::setDestinationCrs ( const QgsCoordinateReferenceSystem crs)

Sets the destination coordinate reference system.

Parameters
crsCRS to transform coordinates to
See also
destinationCrs()
setSourceCrs()

Definition at line 206 of file qgscoordinatetransform.cpp.

◆ setDestinationDatumTransformId()

void QgsCoordinateTransform::setDestinationDatumTransformId ( int  datumId)

Sets the datumId ID of the datum transform to use when projecting to the destination CRS.

This is usually calculated automatically from the transform's QgsCoordinateTransformContext. Calling this method will overwrite any automatically calculated datum transform.

See also
QgsDatumTransform
destinationDatumTransformId()
setSourceDatumTransformId()
Deprecated:
Unused on builds based on Proj 6.0 or later

Definition at line 1046 of file qgscoordinatetransform.cpp.

◆ setDynamicCrsToDynamicCrsWarningHandler()

void QgsCoordinateTransform::setDynamicCrsToDynamicCrsWarningHandler ( const std::function< void(const QgsCoordinateReferenceSystem &sourceCrs, const QgsCoordinateReferenceSystem &destinationCrs)> &  handler)
static

Sets a custom handler to use when the desired coordinate operation for use between sourceCrs and destinationCrs is a dynamic CRS to dynamic CRS transform, not currently supported by PROJ.

Since
QGIS 3.20

Definition at line 1128 of file qgscoordinatetransform.cpp.

◆ setFallbackOperationOccurredHandler()

void QgsCoordinateTransform::setFallbackOperationOccurredHandler ( const std::function< void(const QgsCoordinateReferenceSystem &sourceCrs, const QgsCoordinateReferenceSystem &destinationCrs, const QString &desiredOperation)> &  handler)
static

Sets a custom handler to use when the desired coordinate operation for use between sourceCrs and destinationCrs failed and an alternative fallback operation was utilized instead.

Since
QGIS 3.10.3

Definition at line 1123 of file qgscoordinatetransform.cpp.

◆ setSourceCrs()

void QgsCoordinateTransform::setSourceCrs ( const QgsCoordinateReferenceSystem crs)

Sets the source coordinate reference system.

Parameters
crsCRS to transform coordinates from
See also
sourceCrs()
setDestinationCrs()

Definition at line 183 of file qgscoordinatetransform.cpp.

◆ setSourceDatumTransformId()

void QgsCoordinateTransform::setSourceDatumTransformId ( int  datumId)

Sets the datumId ID of the datum transform to use when projecting from the source CRS.

This is usually calculated automatically from the transform's QgsCoordinateTransformContext. Calling this method will overwrite any automatically calculated datum transform.

See also
QgsDatumTransform
sourceDatumTransformId()
setDestinationDatumTransformId()
Deprecated:
Unused on builds based on Proj 6.0 or later

Definition at line 1031 of file qgscoordinatetransform.cpp.

◆ sourceCrs()

QgsCoordinateReferenceSystem QgsCoordinateTransform::sourceCrs ( ) const

Returns the source coordinate reference system, which the transform will transform coordinates from.

See also
setSourceCrs()
destinationCrs()

Definition at line 262 of file qgscoordinatetransform.cpp.

◆ sourceDatumTransformId()

int QgsCoordinateTransform::sourceDatumTransformId ( ) const

Returns the ID of the datum transform to use when projecting from the source CRS.

This is usually calculated automatically from the transform's QgsCoordinateTransformContext, but can be manually overwritten by a call to setSourceDatumTransformId().

See also
QgsDatumTransform
setSourceDatumTransformId()
destinationDatumTransformId()
Deprecated:
Unused on builds based on Proj 6.0 or later

Definition at line 1024 of file qgscoordinatetransform.cpp.

◆ transform() [1/4]

QgsPointXY QgsCoordinateTransform::transform ( const QgsPointXY point,
Qgis::TransformDirection  direction = Qgis::TransformDirection::Forward 
) const

Transform the point from the source CRS to the destination CRS.

If the direction is ForwardTransform then coordinates are transformed from source to destination, otherwise points are transformed from destination to source CRS.

Parameters
pointpoint to transform
directiontransform direction (defaults to ForwardTransform)
Returns
transformed point

Definition at line 272 of file qgscoordinatetransform.cpp.

◆ transform() [2/4]

QgsRectangle QgsCoordinateTransform::transform ( const QgsRectangle rectangle,
Qgis::TransformDirection  direction = Qgis::TransformDirection::Forward 
) const

Transforms a rectangle to the destination CRS.

If the direction is ForwardTransform then coordinates are transformed from source to destination, otherwise points are transformed from destination to source CRS.

Parameters
rectanglerectangle to transform
directiontransform direction (defaults to ForwardTransform)
Returns
transformed rectangle

Definition at line 310 of file qgscoordinatetransform.cpp.

◆ transform() [3/4]

QgsVector3D QgsCoordinateTransform::transform ( const QgsVector3D point,
Qgis::TransformDirection  direction = Qgis::TransformDirection::Forward 
) const

Transform the point specified in 3D coordinates from the source CRS to the destination CRS.

If the direction is ForwardTransform then coordinates are transformed from source to destination, otherwise points are transformed from destination to source CRS.

Parameters
pointcoordinates of point to transform
directiontransform direction (defaults to ForwardTransform)
Returns
transformed point
Since
QGIS 3.18

Definition at line 346 of file qgscoordinatetransform.cpp.

◆ transform() [4/4]

QgsPointXY QgsCoordinateTransform::transform ( double  x,
double  y = 0.0,
Qgis::TransformDirection  direction = Qgis::TransformDirection::Forward 
) const

Transform the point specified by x,y from the source CRS to the destination CRS.

If the direction is ForwardTransform then coordinates are transformed from source to destination, otherwise points are transformed from destination to source CRS.

Parameters
xx coordinate of point to transform
yy coordinate of point to transform
directiontransform direction (defaults to ForwardTransform)
Returns
transformed point

Definition at line 296 of file qgscoordinatetransform.cpp.

◆ transformBoundingBox()

QgsRectangle QgsCoordinateTransform::transformBoundingBox ( const QgsRectangle rectangle,
Qgis::TransformDirection  direction = Qgis::TransformDirection::Forward,
bool  handle180Crossover = false 
) const

Transforms a rectangle from the source CRS to the destination CRS.

If the direction is ForwardTransform then coordinates are transformed from source to destination, otherwise points are transformed from destination to source CRS. This method assumes that the rectangle is a bounding box, and creates a bounding box in the projected CRS, such that all points from the source rectangle are within the returned rectangle.

Parameters
rectanglerectangle to transform
directiontransform direction (defaults to ForwardTransform)
handle180Crossoverset to true if destination CRS is geographic and handling of extents crossing the 180 degree longitude line is required
Returns
rectangle in destination CRS

Definition at line 560 of file qgscoordinatetransform.cpp.

◆ transformCoords()

void QgsCoordinateTransform::transformCoords ( int  numPoint,
double *  x,
double *  y,
double *  z,
Qgis::TransformDirection  direction = Qgis::TransformDirection::Forward 
) const

Transform an array of coordinates to the destination CRS.

If the direction is ForwardTransform then coordinates are transformed from source to destination, otherwise points are transformed from destination to source CRS.

Parameters
numPointnumber of coordinates in arrays
xarray of x coordinates to transform
yarray of y coordinates to transform
zarray of z coordinates to transform
directiontransform direction (defaults to ForwardTransform)

Definition at line 705 of file qgscoordinatetransform.cpp.

◆ transformInPlace() [1/5]

void QgsCoordinateTransform::transformInPlace ( double &  x,
double &  y,
double &  z,
Qgis::TransformDirection  direction = Qgis::TransformDirection::Forward 
) const

Transforms an array of x, y and z double coordinates in place, from the source CRS to the destination CRS.

If the direction is ForwardTransform then coordinates are transformed from source to destination, otherwise points are transformed from destination to source CRS.

Parameters
xarray of x coordinates of points to transform
yarray of y coordinates of points to transform
zarray of z coordinates of points to transform. The z coordinates of the points must represent height relative to the vertical datum of the source CRS (generally ellipsoidal heights) and must be expressed in its vertical units (generally meters)
directiontransform direction (defaults to ForwardTransform)

Definition at line 364 of file qgscoordinatetransform.cpp.

◆ transformInPlace() [2/5]

void QgsCoordinateTransform::transformInPlace ( float &  x,
float &  y,
double &  z,
Qgis::TransformDirection  direction = Qgis::TransformDirection::Forward 
) const

Transforms an array of x, y and z float coordinates in place, from the source CRS to the destination CRS.

If the direction is ForwardTransform then coordinates are transformed from source to destination, otherwise points are transformed from destination to source CRS.

Parameters
xarray of x coordinates of points to transform
yarray of y coordinates of points to transform
zarray of z coordinates of points to transform. The z coordinates of the points must represent height relative to the vertical datum of the source CRS (generally ellipsoidal heights) and must be expressed in its vertical units (generally meters)
directiontransform direction (defaults to ForwardTransform)
Note
not available in Python bindings

Definition at line 385 of file qgscoordinatetransform.cpp.

◆ transformInPlace() [3/5]

void QgsCoordinateTransform::transformInPlace ( float &  x,
float &  y,
float &  z,
Qgis::TransformDirection  direction = Qgis::TransformDirection::Forward 
) const

Transforms an array of x, y and z float coordinates in place, from the source CRS to the destination CRS.

If the direction is ForwardTransform then coordinates are transformed from source to destination, otherwise points are transformed from destination to source CRS.

Parameters
xarray of x coordinates of points to transform
yarray of y coordinates of points to transform
zarray of z coordinates of points to transform. The z coordinates of the points must represent height relative to the vertical datum of the source CRS (generally ellipsoidal heights) and must be expressed in its vertical units (generally meters)
directiontransform direction (defaults to ForwardTransform)
Note
not available in Python bindings

Definition at line 394 of file qgscoordinatetransform.cpp.

◆ transformInPlace() [4/5]

void QgsCoordinateTransform::transformInPlace ( QVector< double > &  x,
QVector< double > &  y,
QVector< double > &  z,
Qgis::TransformDirection  direction = Qgis::TransformDirection::Forward 
) const

Transforms a vector of x, y and z double coordinates in place, from the source CRS to the destination CRS.

If the direction is ForwardTransform then coordinates are transformed from source to destination, otherwise points are transformed from destination to source CRS.

Parameters
xvector of x coordinates of points to transform
yvector of y coordinates of points to transform
zvector of z coordinates of points to transform. The z coordinates of the points must represent height relative to the vertical datum of the source CRS (generally ellipsoidal heights) and must be expressed in its vertical units (generally meters)
directiontransform direction (defaults to ForwardTransform)
Note
not available in Python bindings

Definition at line 473 of file qgscoordinatetransform.cpp.

◆ transformInPlace() [5/5]

void QgsCoordinateTransform::transformInPlace ( QVector< float > &  x,
QVector< float > &  y,
QVector< float > &  z,
Qgis::TransformDirection  direction = Qgis::TransformDirection::Forward 
) const

Transforms a vector of x, y and z float coordinates in place, from the source CRS to the destination CRS.

If the direction is ForwardTransform then coordinates are transformed from source to destination, otherwise points are transformed from destination to source CRS.

Parameters
xvector of x coordinates of points to transform
yvector of y coordinates of points to transform
zvector of z coordinates of points to transform. The z coordinates of the points must represent height relative to the vertical datum of the source CRS (generally ellipsoidal heights) and must be expressed in its vertical units (generally meters)
directiontransform direction (defaults to ForwardTransform)
Note
not available in Python bindings

Definition at line 500 of file qgscoordinatetransform.cpp.

◆ transformPolygon()

void QgsCoordinateTransform::transformPolygon ( QPolygonF &  polygon,
Qgis::TransformDirection  direction = Qgis::TransformDirection::Forward 
) const

Transforms a polygon to the destination coordinate system.

Parameters
polygonpolygon to transform (occurs in place)
directiontransform direction (defaults to forward transformation)

Definition at line 421 of file qgscoordinatetransform.cpp.

Friends And Related Function Documentation

◆ QgsProjContext

friend class QgsProjContext
friend

Definition at line 711 of file qgscoordinatetransform.h.

◆ TestQgsCoordinateTransform

friend class TestQgsCoordinateTransform
friend

Definition at line 756 of file qgscoordinatetransform.h.


The documentation for this class was generated from the following files: