Class: QgsCoordinateTransformContext

class qgis.core.QgsCoordinateTransformContext

Bases: sip.wrapper

Contains information about the context in which a coordinate transform is executed.

The context stores various information regarding which coordinate operations should be used when transforming points from a source to destination coordinate reference system.

Note

QgsCoordinateTransformContext objects are thread safe for read and write.

Note

QgsCoordinateTransformContext objects are implicitly shared.

New in version 3.0.

QgsCoordinateTransformContext() Constructor for QgsCoordinateTransformContext.

QgsCoordinateTransformContext(rhs: QgsCoordinateTransformContext) Copy constructor

Methods

addCoordinateOperation

Adds a new coordinateOperationProjString to use when projecting coordinates from the specified sourceCrs to the specified destinationCrs.

addSourceDestinationDatumTransform

Adds a new sourceTransform and destinationTransform to use when projecting coordinates from the specified sourceCrs to the specified destinationCrs.

allowFallbackTransform

Returns True if approximate "ballpark" transforms may be used when transforming between a source and destination CRS pair, in the case that the preferred coordinate operation fails (such as when coordinates from outside a required grid shift file are transformed).

calculateCoordinateOperation

Returns the Proj coordinate operation string to use when transforming from the specified source CRS to destination CRS.

calculateDatumTransforms

Returns the pair of source and destination datum transforms to use for a transform from the specified source CRS to destination CRS.

clear

Clears all stored transform information from the context.

coordinateOperations

Returns the stored mapping for source to destination CRS pairs to associated coordinate operation to use (as a proj string).

hasTransform

Returns True if the context has a valid coordinate operation to use when transforming from the specified source CRS to destination CRS.

mustReverseCoordinateOperation

Returns True if the coordinate operation returned by calculateCoordinateOperation() for the source to destination pair must be inverted.

readSettings

Reads the context's state from application settings.

readXml

Reads the context's state from a DOM element.

removeCoordinateOperation

Removes the coordinate operation for the specified sourceCrs and destinationCrs.

removeSourceDestinationDatumTransform

Removes the source to destination datum transform pair for the specified sourceCrs and destinationCrs.

sourceDestinationDatumTransforms

Returns the stored mapping for source to destination CRS pairs to associated datum transforms to use.

writeSettings

Write the context's state to application settings.

writeXml

Writes the context's state to a DOM element.

addCoordinateOperation(self, sourceCrs: QgsCoordinateReferenceSystem, destinationCrs: QgsCoordinateReferenceSystem, coordinateOperationProjString: str, allowFallback: bool = True) bool

Adds a new coordinateOperationProjString to use when projecting coordinates from the specified sourceCrs to the specified destinationCrs.

coordinateOperationProjString should be set to a valid Proj coordinate operation string. If coordinateOperationProjString is empty, then the default Proj operation will be used when transforming between the coordinate reference systems.

If allowFallback is True (since QGIS 3.12), then “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 QgsCoordinateTransform.fallbackOperationOccurred() for further details. Note that if an existing sourceCrs and destinationCrs pair are added with a different allowFallback value, that value will replace the existing one (i.e. each combination of sourceCrs and destinationCrs must be unique).

Warning

coordinateOperationProjString MUST be a proj string which has been normalized for visualization, and must be constructed so that coordinates are always input and output with x/y coordinate ordering. (Proj strings output by utilities such as projinfo will NOT automatically normalize the axis order!).

Returns True if the new coordinate operation was added successfully.

Note

Requires Proj 6.0 or later. Builds based on earlier Proj versions will ignore this setting, and the deprecated addSourceDestinationDatumTransform() method must be used instead.

New in version 3.8.

Parameters:
Return type:

bool

addSourceDestinationDatumTransform(self, sourceCrs: QgsCoordinateReferenceSystem, destinationCrs: QgsCoordinateReferenceSystem, sourceTransformId: int, destinationTransformId: int) bool

Adds a new sourceTransform and destinationTransform to use when projecting coordinates from the specified sourceCrs to the specified destinationCrs.

If either sourceTransformId or destinationTransformId is -1, then no datum transform is required for transformations for that source or destination.

Returns True if the new transform pair was added successfully.

Deprecated since version Has: no effect on builds based on Proj 6.0 or later, use addCoordinateOperation() instead.

Parameters:
Return type:

bool

allowFallbackTransform(self, source: QgsCoordinateReferenceSystem, destination: QgsCoordinateReferenceSystem) bool

Returns True if approximate “ballpark” transforms may be used when transforming between a source and destination CRS pair, in the case that the preferred coordinate operation fails (such as when coordinates from outside a required grid shift file are transformed). See QgsCoordinateTransform.fallbackOperationOccurred() for further details.

New in version 3.12.

Parameters:
Return type:

bool

calculateCoordinateOperation(self, source: QgsCoordinateReferenceSystem, destination: QgsCoordinateReferenceSystem) str

Returns the Proj coordinate operation string to use when transforming from the specified source CRS to destination CRS.

Returns an empty string if no specific coordinate operation is set for the source to destination pair, in which case the default Proj coordinate operation should be used.

Note

source and destination are reversible.

Note

Requires Proj 6.0 or later. Builds based on earlier Proj versions will always return an empty string, and the deprecated calculateDatumTransforms() method should be used instead.

Warning

Always check the result of mustReverseCoordinateOperation() in order to determine if the proj coordinate operation string returned by this method corresponds to the reverse operation, and must be manually flipped when calculating coordinate transforms.

New in version 3.8.

Parameters:
Return type:

str

calculateDatumTransforms(self, source: QgsCoordinateReferenceSystem, destination: QgsCoordinateReferenceSystem) QgsDatumTransform.TransformPair

Returns the pair of source and destination datum transforms to use for a transform from the specified source CRS to destination CRS.

Returns an ID of -1 if a datum transform should not be used for the source or destination.

Note

source and destination are reversible.

Deprecated since version Has: no effect on builds based on Proj 6.0 or later. Use calculateCoordinateOperation() instead.

Parameters:
Return type:

QgsDatumTransform.TransformPair

clear(self)

Clears all stored transform information from the context.

coordinateOperations(self) object

Returns the stored mapping for source to destination CRS pairs to associated coordinate operation to use (as a proj string). The map keys will be QgsCoordinateReferenceSystems.authid()s.

Warning

This method should not be used to calculate the corresponding coordinate operation to use for a coordinate transform. Instead, always use calculateCoordinateOperation() to determine this.

Note

Requires Proj 6.0 or later. Builds based on earlier Proj versions will always return an empty list, and the deprecated sourceDestinationDatumTransforms() method must be used instead.

New in version 3.8.

Return type:

object

hasTransform(self, source: QgsCoordinateReferenceSystem, destination: QgsCoordinateReferenceSystem) bool

Returns True if the context has a valid coordinate operation to use when transforming from the specified source CRS to destination CRS.

Note

source and destination are reversible.

Parameters:
Return type:

bool

mustReverseCoordinateOperation(self, source: QgsCoordinateReferenceSystem, destination: QgsCoordinateReferenceSystem) bool

Returns True if the coordinate operation returned by calculateCoordinateOperation() for the source to destination pair must be inverted.

New in version 3.10.2.

Parameters:
Return type:

bool

readSettings(self)

Reads the context’s state from application settings.

See also

readSettings()

readXml(self, element: QDomElement, context: QgsReadWriteContext) Tuple[bool, List[str]]

Reads the context’s state from a DOM element.

Returns False if transforms stored in the XML are not available. In this case missingTransforms will be filled with missing datum transform strings.

See also

writeXml()

Parameters:
Return type:

Tuple[bool, List[str]]

removeCoordinateOperation(self, sourceCrs: QgsCoordinateReferenceSystem, destinationCrs: QgsCoordinateReferenceSystem)

Removes the coordinate operation for the specified sourceCrs and destinationCrs.

New in version 3.8.

Parameters:
removeSourceDestinationDatumTransform(self, sourceCrs: QgsCoordinateReferenceSystem, destinationCrs: QgsCoordinateReferenceSystem)

Removes the source to destination datum transform pair for the specified sourceCrs and destinationCrs.

Deprecated since version Use: removeCoordinateOperation() instead

Parameters:
sourceDestinationDatumTransforms(self) object

Returns the stored mapping for source to destination CRS pairs to associated datum transforms to use. The map keys will be QgsCoordinateReferenceSystems.authid()s.

If either the source transform ID or destination transform ID is -1, then no datum transform is required for transformations for that source or destination.

Warning

This method should not be used to calculate the corresponding datum transforms to use for a coordinate transform. Instead, always use calculateDatumTransforms() to determine this.

Deprecated since version Has: no effect on builds based on Proj 6.0 or later, use coordinateOperations() instead.

Return type:

object

writeSettings(self)

Write the context’s state to application settings.

See also

writeSettings()

writeXml(self, element: QDomElement, context: QgsReadWriteContext)

Writes the context’s state to a DOM element.

See also

readXml()

Parameters: