QgsCoordinateTransform class

Class for doing transforms between two map coordinate systems.

Contents

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.

Public types

enum TransformDirection { ForwardTransform, ReverseTransform }
Enum used to indicate the direction (forward or inverse) of the transform.

Public static functions

static void invalidateCache()
Clears the internal cache used to initialize QgsCoordinateTransform objects.

Constructors, destructors, conversion operators

QgsCoordinateTransform()
Default constructor, creates an invalid QgsCoordinateTransform.
QgsCoordinateTransform(const QgsCoordinateReferenceSystem& source, const QgsCoordinateReferenceSystem& destination, const QgsCoordinateTransformContext& context) explicit
Constructs a QgsCoordinateTransform to transform from the source to destination coordinate reference system.
QgsCoordinateTransform(const QgsCoordinateReferenceSystem& source, const QgsCoordinateReferenceSystem& destination, const QgsProject* project) explicit
Constructs a QgsCoordinateTransform to transform from the source to destination coordinate reference system, when used with the given project.
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).
QgsCoordinateTransform(const QgsCoordinateTransform& o)
Copy constructor.

Public functions

auto QgsCoordinateTransform(const QgsCoordinateReferenceSystem& source, const QgsCoordinateReferenceSystem& destination) -> Q_DECL_DEPRECATED deprecated explicit
Constructs a QgsCoordinateTransform using QgsCoordinateReferenceSystem objects.
auto context() const -> QgsCoordinateTransformContext
Returns the context in which the coordinate transform will be calculated.
auto destinationCrs() const -> QgsCoordinateReferenceSystem
Returns the destination coordinate reference system, which the transform will transform coordinates to.
auto destinationDatumTransformId() const -> int
Returns the ID of the datum transform to use when projecting to the destination CRS.
auto isShortCircuited() const -> bool
Returns true if the transform short circuits because the source and destination are equivalent.
auto isValid() const -> bool
Returns true if the coordinate transform is valid, ie both the source and destination CRS have been set and are valid.
auto operator=(const QgsCoordinateTransform& o) -> QgsCoordinateTransform&
Assignment operator.
auto scaleFactor(const QgsRectangle& referenceExtent) const -> double
Computes an estimated conversion factor between source and destination units:
void setContext(const QgsCoordinateTransformContext& context)
Sets the context in which the coordinate transform should be calculated.
void setDestinationCrs(const QgsCoordinateReferenceSystem& crs)
Sets the destination coordinate reference system.
void setDestinationDatumTransformId(int datumId)
Sets the datumId ID of the datum transform to use when projecting to the destination CRS.
void setSourceCrs(const QgsCoordinateReferenceSystem& crs)
Sets the source coordinate reference system.
void setSourceDatumTransformId(int datumId)
Sets the datumId ID of the datum transform to use when projecting from the source CRS.
auto sourceCrs() const -> QgsCoordinateReferenceSystem
Returns the source coordinate reference system, which the transform will transform coordinates from.
auto sourceDatumTransformId() const -> int
Returns the ID of the datum transform to use when projecting from the source CRS.
auto transform(const QgsPointXY& point, TransformDirection direction = ForwardTransform) -> QgsPointXY
Transform the point from the source CRS to the destination CRS.
auto transform(double x, double y, TransformDirection direction = ForwardTransform) const -> QgsPointXY
Transform the point specified by x,y from the source CRS to the destination CRS.
auto transform(const QgsRectangle& rectangle, TransformDirection direction = ForwardTransform) -> QgsRectangle
Transforms a rectangle to the destination CRS.
auto transformBoundingBox(const QgsRectangle& rectangle, TransformDirection direction = ForwardTransform, bool handle180Crossover = false) -> QgsRectangle
Transforms a rectangle from the source CRS to the destination CRS.
void transformCoords(int numPoint, double* x, double* y, double* z, TransformDirection direction = ForwardTransform)
Transform an array of coordinates to the destination CRS.
void transformInPlace(double& x, double& y, double& z, TransformDirection direction = ForwardTransform)
Transforms an array of x, y and z double coordinates in place, from the source CRS to the destination CRS.
void transformInPlace(float& x, float& y, double& z, TransformDirection direction = ForwardTransform) const
Transforms an array of x, y and z float coordinates in place, from the source CRS to the destination CRS.
void transformInPlace(float& x, float& y, float& z, TransformDirection direction = ForwardTransform) const
Transforms an array of x, y and z float coordinates in place, from the source CRS to the destination CRS.
void transformInPlace(QVector<float>& x, QVector<float>& y, QVector<float>& z, TransformDirection direction = ForwardTransform) const
Transforms a vector of x, y and z float coordinates in place, from the source CRS to the destination CRS.
void transformInPlace(QVector<double>& x, QVector<double>& y, QVector<double>& z, TransformDirection direction = ForwardTransform) const
Transforms a vector of x, y and z double coordinates in place, from the source CRS to the destination CRS.
void transformPolygon(QPolygonF& polygon, TransformDirection direction = ForwardTransform)
Transforms a polygon to the destination coordinate system.

Enum documentation

enum QgsCoordinateTransform::TransformDirection

Enum used to indicate the direction (forward or inverse) of the transform.

Enumerators
ForwardTransform

Transform from source to destination CRS.
ReverseTransform

Transform from destination to source CRS.

Function documentation

static void QgsCoordinateTransform::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.

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

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

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

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

Q_DECL_DEPRECATED QgsCoordinateTransform::QgsCoordinateTransform(const QgsCoordinateReferenceSystem& source, const QgsCoordinateReferenceSystem& destination) explicit

Constructs a QgsCoordinateTransform using QgsCoordinateReferenceSystem objects.

Parameters
source source CRS, typically of the layer's coordinate system
destination CRS, typically of the map canvas coordinate system correctly handle the user's datum transform setup. Instead the constructor variant which accepts a QgsCoordinateTransformContext or QgsProject argument should be used instead. It is highly likely that this constructor will be removed in future QGIS versions.

QgsCoordinateTransformContext QgsCoordinateTransform::context() const

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

QgsCoordinateReferenceSystem QgsCoordinateTransform::destinationCrs() const

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

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

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.

double QgsCoordinateTransform::scaleFactor(const QgsRectangle& referenceExtent) const

Computes an estimated conversion factor between source and destination units:

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

sourceUnits * scaleFactor = destinationUnits

void QgsCoordinateTransform::setContext(const QgsCoordinateTransformContext& context)

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

void QgsCoordinateTransform::setDestinationCrs(const QgsCoordinateReferenceSystem& crs)

Sets the destination coordinate reference system.

Parameters
crs CRS to transform coordinates to

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.

void QgsCoordinateTransform::setSourceCrs(const QgsCoordinateReferenceSystem& crs)

Sets the source coordinate reference system.

Parameters
crs CRS to transform coordinates from

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.

QgsCoordinateReferenceSystem QgsCoordinateTransform::sourceCrs() const

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

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

QgsPointXY QgsCoordinateTransform::transform(const QgsPointXY& point, TransformDirection direction = ForwardTransform)

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

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

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

QgsPointXY QgsCoordinateTransform::transform(double x, double y, TransformDirection direction = ForwardTransform) const

Transform the point specified by x,y from the source CRS to the destination 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

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

QgsRectangle QgsCoordinateTransform::transform(const QgsRectangle& rectangle, TransformDirection direction = ForwardTransform)

Transforms a rectangle to the destination CRS.

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

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

QgsRectangle QgsCoordinateTransform::transformBoundingBox(const QgsRectangle& rectangle, TransformDirection direction = ForwardTransform, bool handle180Crossover = false)

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

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

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.

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

Transform an array of coordinates to the destination 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)

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

void QgsCoordinateTransform::transformInPlace(double& x, double& y, double& z, TransformDirection direction = ForwardTransform)

Transforms an array of x, y and z double coordinates in place, from the source CRS to the destination 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)

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

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

Transforms an array of x, y and z float coordinates in place, from the source CRS to the destination 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)

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

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

Transforms an array of x, y and z float coordinates in place, from the source CRS to the destination 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)

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

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

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

Parameters
x vector of x coordinates of points to transform
y vector of y coordinates of points to transform
z vector 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)

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

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

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

Parameters
x vector of x coordinates of points to transform
y vector of y coordinates of points to transform
z vector 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)

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

void QgsCoordinateTransform::transformPolygon(QPolygonF& polygon, TransformDirection direction = ForwardTransform)

Transforms a polygon to the destination coordinate system.

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