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.See also
See also
QgsCoordinateTransform() Default constructor, creates an invalid QgsCoordinateTransform.
QgsCoordinateTransform(source:
QgsCoordinateReferenceSystem
, destination:QgsCoordinateReferenceSystem
, context:QgsCoordinateTransformContext
, flags: Union[Qgis.CoordinateTransformationFlags, Qgis.CoordinateTransformationFlag] = Qgis.CoordinateTransformationFlags()) Constructs aQgsCoordinateTransform
to transform from thesource
todestination
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 theQgsCoordinateTransformContext
object is correctly retrieved based on the current code context, or use the constructor variant which accepts aQgsProject
argument instead.New in version 3.0.
QgsCoordinateTransform(source:
QgsCoordinateReferenceSystem
, destination:QgsCoordinateReferenceSystem
, project:QgsProject
, flags: Union[Qgis.CoordinateTransformationFlags, Qgis.CoordinateTransformationFlag] = Qgis.CoordinateTransformationFlags()) Constructs aQgsCoordinateTransform
to transform from thesource
todestination
coordinate reference system, when used with the givenproject
.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 creatingQgsCoordinateTransform
. 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.New in version 3.0.
QgsCoordinateTransform(source:
QgsCoordinateReferenceSystem
, destination:QgsCoordinateReferenceSystem
, sourceDatumTransformId: int, destinationDatumTransformId: int) Constructs aQgsCoordinateTransform
to transform from thesource
todestination
coordinate reference system, with the specified datum transforms (seeQgsDatumTransform
).Deprecated since version will: be removed in QGIS 4.0. Use the constructor with a
QgsCoordinateTransformContext
argument instead.New in version 3.0.
QgsCoordinateTransform(o:
QgsCoordinateTransform
) Copy constructorEnums
Bases:
enum.IntEnum
Methods
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).
Returns the context in which the coordinate transform will be calculated.
Returns a Proj string representing the coordinate operation which will be used to transform coordinates.
Returns the destination coordinate reference system, which the transform will transform coordinates to.
Returns the ID of the datum transform to use when projecting to the destination CRS.
Sets whether the default fallback operation handler is disabled for this transform instance.
Returns
True
if a fallback operation occurred for the most recent transform.Returns the transform details representing the coordinate operation which is being used to transform coordinates.
Clears the internal cache used to initialize
QgsCoordinateTransform
objects.Returns
True
if the transform short circuits because the source and destination are equivalent.Returns
True
if it is theoretically possible to transform betweensource
anddestination
CRSes.Returns
True
if the coordinate transform is valid, ie both the source and destination CRS have been set and are valid.Computes an estimated conversion factor between source and destination units:
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).
Sets whether approximate "ballpark" results are appropriate for this coordinate transform.
Sets the
context
in which the coordinate transform should be calculated.Sets a Proj string representing the coordinate
operation
which will be used to transform coordinates.Sets the destination coordinate reference system.
Sets the
datumId
ID of the datum transform to use when projecting to the destination CRS.Sets the source coordinate reference system.
Sets the
datumId
ID of the datum transform to use when projecting from the source CRS.Returns the source coordinate reference system, which the transform will transform coordinates from.
Returns the ID of the datum transform to use when projecting from the source CRS.
Transform the point from the source CRS to the destination CRS.
Transforms a rectangle from the source CRS to the destination CRS.
Transform an array of coordinates to the destination CRS.
Transforms an array of x, y and z double coordinates in place, from the source CRS to the destination CRS.
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)
- 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.
See also
New in version 3.12.
- Return type:
bool
- context(self) QgsCoordinateTransformContext ¶
Returns the context in which the coordinate transform will be calculated.
See also
New in version 3.4.
- Return type:
- 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 theQgsCoordinateTransform
’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 theinstantiatedCoordinateOperationDetails()
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()
ordestinationDatumTransformId()
methods should be used instead.See also
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
See also
- Return type:
- 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 tosetDestinationDatumTransformId()
.See also
See also
See also
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 testingfallbackOperationOccurred()
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
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.
See also
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()
ordestinationDatumTransformId()
methods should be used instead.See also
New in version 3.10.2.
- Return type:
- 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
- isTransformationPossible(source: QgsCoordinateReferenceSystem, destination: QgsCoordinateReferenceSystem) bool ¶
Returns
True
if it is theoretically possible to transform betweensource
anddestination
CRSes.For example, will return
False
ifsource
anddestination
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 matchingQgsCoordinateTransform
fails (e.g. due to missing grid shift files on the system).New in version 3.26.
- Parameters:
source (QgsCoordinateReferenceSystem) –
destination (QgsCoordinateReferenceSystem) –
- 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
- 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 toTrue
, this setting will be ignored and fallback transformations will always be permitted.See also
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 toTrue
. 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
isTrue
, 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
isFalse
(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
isTrue
, then this setting overridesallowFallbackTransforms()
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
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()
orsetDestinationDatumTransformId()
methods should be used instead.See also
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
See also
- 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.See also
See also
See also
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
See also
- 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.See also
See also
See also
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
See also
- Return type:
- 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 tosetSourceDatumTransformId()
.See also
See also
See also
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
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
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
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:
- Returns:
transformed rectangle
- 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:
- Returns:
rectangle in destination CRS
- 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)
- 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)
- 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)