Subgroup: Coordinate

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

Signals

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.

destinationCrs(self) → QgsCoordinateReferenceSystem

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

See also

sourceCrs()

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

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.

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.

scaleFactor(self, referenceExtent: QgsRectangle) → float

Computes an estimated conversion factor between source and destination units:

sourceUnits * scaleFactor = destinationUnits

Parameters:referenceExtent – A reference extent based on which to perform the computation

New in version 3.4.

setContext(self, context: QgsCoordinateTransformContext)

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

See also

context()

New in version 3.0.

setDestinationCrs(self, crs: QgsCoordinateReferenceSystem)

Sets the destination coordinate reference system.

Parameters:crs – 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.

setSourceCrs(self, crs: QgsCoordinateReferenceSystem)

Sets the source coordinate reference system.

Parameters:crs – 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.

sourceCrs(self) → QgsCoordinateReferenceSystem

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

See also

setSourceCrs()

See also

destinationCrs()

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

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 – point to transform
  • direction – 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)
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 – rectangle to transform
  • direction – transform direction (defaults to ForwardTransform)
  • handle180Crossover – set to true if destination CRS is geographic and handling of extents crossing the 180 degree longitude line is required
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 – 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 – transform direction (defaults to ForwardTransform)
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 – transform direction (defaults to ForwardTransform)
transformPolygon(self, polygon: QPolygonF, direction: QgsCoordinateTransform.TransformDirection = QgsCoordinateTransform.ForwardTransform)

Transforms a polygon to the destination coordinate system.

Parameters:
  • polygon – polygon to transform (occurs in place)
  • direction – transform direction (defaults to forward transformation)