Class: QgsCoordinateTransform

class qgis.core.QgsCoordinateTransform

Bases: sip.wrapper

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.

QgsCoordinateTransform() Default constructor, creates an invalid QgsCoordinateTransform.

QgsCoordinateTransform(source: QgsCoordinateReferenceSystem, destination: QgsCoordinateReferenceSystem, context: QgsCoordinateTransformContext, flags: Union[Qgis.CoordinateTransformationFlags, Qgis.CoordinateTransformationFlag] = Qgis.CoordinateTransformationFlags()) 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.

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.

QgsCoordinateTransform(source: QgsCoordinateReferenceSystem, destination: QgsCoordinateReferenceSystem, project: QgsProject, flags: Union[Qgis.CoordinateTransformationFlags, Qgis.CoordinateTransformationFlag] = Qgis.CoordinateTransformationFlags()) 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.

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

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.

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

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

QgsCoordinateTransform(o: QgsCoordinateTransform) Copy constructor

Enums

TransformDirection

Bases: enum.IntEnum

Methods

allowFallbackTransforms

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).

context

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

coordinateOperation

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

destinationCrs

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

destinationDatumTransformId

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

disableFallbackOperationHandler

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

fallbackOperationOccurred

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

instantiatedCoordinateOperationDetails

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

invalidateCache

Clears the internal cache used to initialize QgsCoordinateTransform objects.

isShortCircuited

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

isTransformationPossible

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

isValid

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

scaleFactor

Computes an estimated conversion factor between source and destination units:

setAllowFallbackTransforms

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).

setBallparkTransformsAreAppropriate

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

setContext

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

setCoordinateOperation

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

setDestinationCrs

Sets the destination coordinate reference system.

setDestinationDatumTransformId

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

setSourceCrs

Sets the source coordinate reference system.

setSourceDatumTransformId

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

sourceCrs

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

sourceDatumTransformId

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

transform

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

transformBoundingBox

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

transformCoords

Transform an array of coordinates to the destination CRS.

transformInPlace

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

transformPolygon

Transforms a polygon to the destination coordinate system.

class TransformDirection(value)

Bases: enum.IntEnum

Indicates the direction (forward or inverse) of a transform.

New in version 3.22.

  • ForwardTransform: Forward transform (from source to destination)

  • ReverseTransform: Reverse/inverse transform (from destination to source)

baseClass

alias of Qgis

allowFallbackTransforms(self) bool

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.

New in version 3.12.

Return type:

bool

context(self) QgsCoordinateTransformContext

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

See also

setContext()

New in version 3.4.

Return type:

QgsCoordinateTransformContext

coordinateOperation(self) str

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.

Note

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.

New in version 3.8.

Return type:

str

destinationCrs(self) QgsCoordinateReferenceSystem

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

See also

sourceCrs()

Return type:

QgsCoordinateReferenceSystem

destinationDatumTransformId(self) int

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().

Deprecated since version Unused: on builds based on Proj 6.0 or later

Return type:

int

disableFallbackOperationHandler(self, disabled: bool)

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.

New in version 3.12.

Parameters:

disabled (bool) –

fallbackOperationOccurred(self) bool

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.

New in version 3.12.

Return type:

bool

instantiatedCoordinateOperationDetails(self) QgsDatumTransform.TransformDetails

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.

New in version 3.10.2.

Return type:

QgsDatumTransform.TransformDetails

invalidateCache()

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.

isShortCircuited(self) bool

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

Return type:

bool

isTransformationPossible(source: QgsCoordinateReferenceSystem, destination: QgsCoordinateReferenceSystem) bool

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).

New in version 3.26.

Parameters:
Return type:

bool

isValid(self) bool

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

Return type:

bool

scaleFactor(self, referenceExtent: QgsRectangle) float

Computes an estimated conversion factor between source and destination units:

sourceUnits * scaleFactor = destinationUnits

Parameters:

referenceExtent (QgsRectangle) – A reference extent based on which to perform the computation

New in version 3.4.

Return type:

float

setAllowFallbackTransforms(self, allowed: bool)

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.

New in version 3.12.

Parameters:

allowed (bool) –

setBallparkTransformsAreAppropriate(self, appropriate: bool)

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.

New in version 3.12.

Parameters:

appropriate (bool) –

setContext(self, context: QgsCoordinateTransformContext)

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

See also

context()

Parameters:

context (QgsCoordinateTransformContext) –

setCoordinateOperation(self, operation: str)

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.

New in version 3.8.

Parameters:

operation (str) –

setDestinationCrs(self, crs: QgsCoordinateReferenceSystem)

Sets the destination coordinate reference system.

Parameters:

crs (QgsCoordinateReferenceSystem) – CRS to transform coordinates to

See also

destinationCrs()

See also

setSourceCrs()

setDestinationDatumTransformId(self, datumId: int)

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.

Deprecated since version Unused: on builds based on Proj 6.0 or later

Parameters:

datumId (int) –

setSourceCrs(self, crs: QgsCoordinateReferenceSystem)

Sets the source coordinate reference system.

Parameters:

crs (QgsCoordinateReferenceSystem) – CRS to transform coordinates from

See also

sourceCrs()

setSourceDatumTransformId(self, datumId: int)

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.

Deprecated since version Unused: on builds based on Proj 6.0 or later

Parameters:

datumId (int) –

sourceCrs(self) QgsCoordinateReferenceSystem

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

See also

setSourceCrs()

See also

destinationCrs()

Return type:

QgsCoordinateReferenceSystem

sourceDatumTransformId(self) int

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().

Deprecated since version Unused: on builds based on Proj 6.0 or later

Return type:

int

transform(self, point: QgsPointXY, direction: Qgis.TransformDirection = Qgis.TransformDirection.Forward) QgsPointXY

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:
  • point (QgsPointXY) – point to transform

  • direction (Qgis.TransformDirection = Qgis.TransformDirection.Forward) – transform direction (defaults to ForwardTransform)

Returns:

transformed point

Raises:

QgsCsException – if the transformation fails

transform(self, x: float, y: float, direction: Qgis.TransformDirection = Qgis.TransformDirection.Forward) -> QgsPointXY 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:
  • x – x coordinate of point to transform

  • y – y coordinate of point to transform

  • direction – transform direction (defaults to ForwardTransform)

Returns:

transformed point

Raises:

QgsCsException – if the transformation fails

transform(self, point: QgsVector3D, direction: Qgis.TransformDirection = Qgis.TransformDirection.Forward) -> QgsVector3D 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:
  • point – coordinates of point to transform

  • direction – transform direction (defaults to ForwardTransform)

Returns:

transformed point

Raises:

QgsCsException – if the transformation fails

New in version 3.18.

transform(self, rectangle: QgsRectangle, direction: Qgis.TransformDirection = Qgis.TransformDirection.Forward) -> QgsRectangle 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:
  • rectangle – rectangle to transform

  • direction – transform direction (defaults to ForwardTransform)

Return type:

QgsPointXY

Returns:

transformed rectangle

Raises:

QgsCsException – if the transformation fails

transformBoundingBox(self, rectangle: QgsRectangle, direction: Qgis.TransformDirection = Qgis.TransformDirection.Forward, handle180Crossover: bool = False) QgsRectangle

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:
  • rectangle (QgsRectangle) – rectangle to transform

  • direction (Qgis.TransformDirection = Qgis.TransformDirection.Forward) – transform direction (defaults to ForwardTransform)

  • handle180Crossover (bool = False) – set to True if destination CRS is geographic and handling of extents crossing the 180 degree longitude line is required

Return type:

QgsRectangle

Returns:

rectangle in destination CRS

Raises:

QgsCsException – if the transformation fails

transformCoords(self, numPoint: int, direction: Qgis.TransformDirection = Qgis.TransformDirection.Forward) Tuple[float, float, float]

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:
  • numPoint (int) – number of coordinates in arrays

  • x – array of x coordinates to transform

  • y – array of y coordinates to transform

  • z – array of z coordinates to transform

  • direction (Qgis.TransformDirection = Qgis.TransformDirection.Forward) – transform direction (defaults to ForwardTransform)

Raises:

QgsCsException – if the transformation fails

Return type:

Tuple[float, float, float]

transformInPlace(self, direction: Qgis.TransformDirection = Qgis.TransformDirection.Forward) Tuple[float, float, float]

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:
  • x – array of x coordinates of points to transform

  • y – array of y coordinates of points to transform

  • z – array 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)

  • direction (Qgis.TransformDirection = Qgis.TransformDirection.Forward) – transform direction (defaults to ForwardTransform)

Raises:

QgsCsException – if the transformation fails

Return type:

Tuple[float, float, float]

transformPolygon(self, polygon: QPolygonF, direction: Qgis.TransformDirection = Qgis.TransformDirection.Forward)

Transforms a polygon to the destination coordinate system.

Parameters:
  • polygon (QPolygonF) – polygon to transform (occurs in place)

  • direction (Qgis.TransformDirection = Qgis.TransformDirection.Forward) – transform direction (defaults to forward transformation)

Raises:

QgsCsException – if the transformation fails