Class: QgsCoordinateTransformContext¶
-
class
qgis.core.
QgsCoordinateTransformContext
¶ Bases:
sip.wrapper
Constructor for QgsCoordinateTransformContext.
QgsCoordinateTransformContext(rhs:
QgsCoordinateTransformContext
) Copy constructorContains 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.See also
See also
Methods
Adds a new
coordinateOperationProjString
to use when projecting coordinates from the specifiedsourceCrs
to the specifieddestinationCrs
.Adds a new
sourceTransform
anddestinationTransform
to use when projecting coordinates from the specifiedsourceCrs
to the specifieddestinationCrs
.Returns
True
if approximate “ballpark” transforms may be used when transforming between asource
anddestination
CRS pair, in the case that the preferred coordinate operation fails (such as when coordinates from outside a required grid shift file are transformed).Returns the Proj coordinate operation string to use when transforming from the specified
source
CRS todestination
CRS.Returns the pair of source and destination datum transforms to use for a transform from the specified
source
CRS todestination
CRS.Clears all stored transform information from the context.
Returns the stored mapping for source to destination CRS pairs to associated coordinate operation to use (as a proj string).
Returns
True
if the context has a valid coordinate operation to use when transforming from the specifiedsource
CRS todestination
CRS.Returns
True
if the coordinate operation returned by calculateCoordinateOperation() for thesource
todestination
pair must be inverted.Reads the context’s state from application settings.
Reads the context’s state from a DOM
element
.Removes the coordinate operation for the specified
sourceCrs
anddestinationCrs
.Removes the source to destination datum transform pair for the specified
sourceCrs
anddestinationCrs
.Returns the stored mapping for source to destination CRS pairs to associated datum transforms to use.
Write the context’s state to application settings.
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 specifiedsourceCrs
to the specifieddestinationCrs
.coordinateOperationProjString
should be set to a valid Proj coordinate operation string. IfcoordinateOperationProjString
is empty, then the default Proj operation will be used when transforming between the coordinate reference systems.If
allowFallback
isTrue
(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 existingsourceCrs
anddestinationCrs
pair are added with a differentallowFallback
value, that value will replace the existing one (i.e. each combination ofsourceCrs
anddestinationCrs
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.See also
See also
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
sourceCrs (QgsCoordinateReferenceSystem) –
destinationCrs (QgsCoordinateReferenceSystem) –
coordinateOperationProjString (str) –
allowFallback (bool = True) –
- Return type
bool
-
addSourceDestinationDatumTransform
(self, sourceCrs: QgsCoordinateReferenceSystem, destinationCrs: QgsCoordinateReferenceSystem, sourceTransformId: int, destinationTransformId: int) → bool¶ Adds a new
sourceTransform
anddestinationTransform
to use when projecting coordinates from the specifiedsourceCrs
to the specifieddestinationCrs
.If either
sourceTransformId
ordestinationTransformId
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.See also
Deprecated since version Has: no effect on builds based on Proj 6.0 or later, use addCoordinateOperation() instead.
- Parameters
sourceCrs (QgsCoordinateReferenceSystem) –
destinationCrs (QgsCoordinateReferenceSystem) –
sourceTransformId (int) –
destinationTransformId (int) –
- Return type
bool
-
allowFallbackTransform
(self, source: QgsCoordinateReferenceSystem, destination: QgsCoordinateReferenceSystem) → bool¶ Returns
True
if approximate “ballpark” transforms may be used when transforming between asource
anddestination
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
source (QgsCoordinateReferenceSystem) –
destination (QgsCoordinateReferenceSystem) –
- 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 todestination
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
source (QgsCoordinateReferenceSystem) –
destination (QgsCoordinateReferenceSystem) –
- 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 todestination
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
source (QgsCoordinateReferenceSystem) –
destination (QgsCoordinateReferenceSystem) –
- Return type
-
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 :py:func:`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.
See also
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 specifiedsource
CRS todestination
CRS.Note
source and destination are reversible.
- Parameters
source (QgsCoordinateReferenceSystem) –
destination (QgsCoordinateReferenceSystem) –
- Return type
bool
-
mustReverseCoordinateOperation
(self, source: QgsCoordinateReferenceSystem, destination: QgsCoordinateReferenceSystem) → bool¶ Returns
True
if the coordinate operation returned by calculateCoordinateOperation() for thesource
todestination
pair must be inverted.New in version 3.10.2.
- Parameters
source (QgsCoordinateReferenceSystem) –
destination (QgsCoordinateReferenceSystem) –
- Return type
bool
-
readSettings
(self)¶ Reads the context’s state from application settings.
See also
-
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 casemissingTransforms
will be filled with missing datum transform strings.See also
- Parameters
element (QDomElement) –
context (QgsReadWriteContext) –
- Return type
Tuple[bool, List[str]]
-
removeCoordinateOperation
(self, sourceCrs: QgsCoordinateReferenceSystem, destinationCrs: QgsCoordinateReferenceSystem)¶ Removes the coordinate operation for the specified
sourceCrs
anddestinationCrs
.New in version 3.8.
- Parameters
sourceCrs (QgsCoordinateReferenceSystem) –
destinationCrs (QgsCoordinateReferenceSystem) –
-
removeSourceDestinationDatumTransform
(self, sourceCrs: QgsCoordinateReferenceSystem, destinationCrs: QgsCoordinateReferenceSystem)¶ Removes the source to destination datum transform pair for the specified
sourceCrs
anddestinationCrs
.See also
Deprecated since version Use: removeCoordinateOperation() instead
- Parameters
sourceCrs (QgsCoordinateReferenceSystem) –
destinationCrs (QgsCoordinateReferenceSystem) –
-
sourceDestinationDatumTransforms
(self) → object¶ Returns the stored mapping for source to destination CRS pairs to associated datum transforms to use. The map keys will be :py:func:`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.
See also
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
-
writeXml
(self, element: QDomElement, context: QgsReadWriteContext)¶ Writes the context’s state to a DOM
element
.See also
- Parameters
element (QDomElement) –
context (QgsReadWriteContext) –
-