Class: QgsCoordinateTransform

class qgis.core.QgsCoordinateTransform

Bases: sip.wrapper

Default constructor, creates an invalid QgsCoordinateTransform.

QgsCoordinateTransform(source: QgsCoordinateReferenceSystem, destination: QgsCoordinateReferenceSystem, context: QgsCoordinateTransformContext) 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.

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.

New in version 3.0.

QgsCoordinateTransform(source: QgsCoordinateReferenceSystem, destination: QgsCoordinateReferenceSystem, project: QgsProject) 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())

New in version 3.0.

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

New in version 3.0.

QgsCoordinateTransform(o: QgsCoordinateTransform) Copy constructor

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.

See also

QgsCoordinateTransformContext

Methods

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.

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.

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:

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.

Attributes

ForwardTransform

ReverseTransform

ForwardTransform = 0
ReverseTransform = 1
class TransformDirection

Bases: int

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

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

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.

New in version 3.0.

isShortCircuited(self) → bool

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

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.

New in version 3.0.

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

setContext(self, context: QgsCoordinateTransformContext)

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

See also

context()

New in version 3.0.

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: QgsCoordinateTransform.TransformDirection = QgsCoordinateTransform.ForwardTransform) → 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 (QgsCoordinateTransform.TransformDirection = QgsCoordinateTransform.ForwardTransform) – transform direction (defaults to ForwardTransform)

Returns

transformed point

transform(self, x: float, y: float, direction: QgsCoordinateTransform.TransformDirection = QgsCoordinateTransform.ForwardTransform) -> 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

transform(self, rectangle: QgsRectangle, direction: QgsCoordinateTransform.TransformDirection = QgsCoordinateTransform.ForwardTransform) -> 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

transformBoundingBox(self, rectangle: QgsRectangle, direction: QgsCoordinateTransform.TransformDirection = QgsCoordinateTransform.ForwardTransform, 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 (QgsCoordinateTransform.TransformDirection = QgsCoordinateTransform.ForwardTransform) – 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

transformCoords(self, numPoint: int, direction: QgsCoordinateTransform.TransformDirection = QgsCoordinateTransform.ForwardTransform) → 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 (QgsCoordinateTransform.TransformDirection = QgsCoordinateTransform.ForwardTransform) – transform direction (defaults to ForwardTransform)

Return type

Tuple[float, float, float]

transformInPlace(self, direction: QgsCoordinateTransform.TransformDirection = QgsCoordinateTransform.ForwardTransform) → 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 (QgsCoordinateTransform.TransformDirection = QgsCoordinateTransform.ForwardTransform) – transform direction (defaults to ForwardTransform)

Return type

Tuple[float, float, float]

transformPolygon(self, polygon: QPolygonF, direction: QgsCoordinateTransform.TransformDirection = QgsCoordinateTransform.ForwardTransform)

Transforms a polygon to the destination coordinate system.

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

  • direction (QgsCoordinateTransform.TransformDirection = QgsCoordinateTransform.ForwardTransform) – transform direction (defaults to forward transformation)