QGIS API Documentation 3.41.0-Master (fda2aa46e9a)
Loading...
Searching...
No Matches
Public Member Functions | List of all members
QgsCoordinateTransformContext Class Reference
core library

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

#include <qgscoordinatetransformcontext.h>

Public Member Functions

 QgsCoordinateTransformContext ()
 Constructor for QgsCoordinateTransformContext.
 
 QgsCoordinateTransformContext (const QgsCoordinateTransformContext &rhs)
 
 ~QgsCoordinateTransformContext ()
 
bool addCoordinateOperation (const QgsCoordinateReferenceSystem &sourceCrs, const QgsCoordinateReferenceSystem &destinationCrs, const QString &coordinateOperationProjString, bool allowFallback=true)
 Adds a new coordinateOperationProjString to use when projecting coordinates from the specified sourceCrs to the specified destinationCrs.
 
Q_DECL_DEPRECATED bool addSourceDestinationDatumTransform (const QgsCoordinateReferenceSystem &sourceCrs, const QgsCoordinateReferenceSystem &destinationCrs, int sourceTransformId, int destinationTransformId)
 Adds a new sourceTransform and destinationTransform to use when projecting coordinates from the specified sourceCrs to the specified destinationCrs.
 
bool allowFallbackTransform (const QgsCoordinateReferenceSystem &source, const QgsCoordinateReferenceSystem &destination) const
 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).
 
QString calculateCoordinateOperation (const QgsCoordinateReferenceSystem &source, const QgsCoordinateReferenceSystem &destination) const
 Returns the Proj coordinate operation string to use when transforming from the specified source CRS to destination CRS.
 
Q_DECL_DEPRECATED QgsDatumTransform::TransformPair calculateDatumTransforms (const QgsCoordinateReferenceSystem &source, const QgsCoordinateReferenceSystem &destination) const
 Returns the pair of source and destination datum transforms to use for a transform from the specified source CRS to destination CRS.
 
void clear ()
 Clears all stored transform information from the context.
 
QMap< QPair< QString, QString >, QString > coordinateOperations () const
 Returns the stored mapping for source to destination CRS pairs to associated coordinate operation to use (as a proj string).
 
bool hasTransform (const QgsCoordinateReferenceSystem &source, const QgsCoordinateReferenceSystem &destination) const
 Returns true if the context has a valid coordinate operation to use when transforming from the specified source CRS to destination CRS.
 
bool mustReverseCoordinateOperation (const QgsCoordinateReferenceSystem &source, const QgsCoordinateReferenceSystem &destination) const
 Returns true if the coordinate operation returned by calculateCoordinateOperation() for the source to destination pair must be inverted.
 
QgsCoordinateTransformContext & operator= (const QgsCoordinateTransformContext &rhs)
 
bool operator== (const QgsCoordinateTransformContext &rhs) const
 
void readSettings ()
 Reads the context's state from application settings.
 
bool readXml (const QDomElement &element, const QgsReadWriteContext &context, QStringList &missingTransforms)
 Reads the context's state from a DOM element.
 
void removeCoordinateOperation (const QgsCoordinateReferenceSystem &sourceCrs, const QgsCoordinateReferenceSystem &destinationCrs)
 Removes the coordinate operation for the specified sourceCrs and destinationCrs.
 
Q_DECL_DEPRECATED void removeSourceDestinationDatumTransform (const QgsCoordinateReferenceSystem &sourceCrs, const QgsCoordinateReferenceSystem &destinationCrs)
 Removes the source to destination datum transform pair for the specified sourceCrs and destinationCrs.
 
Q_DECL_DEPRECATED QMap< QPair< QString, QString >, QgsDatumTransform::TransformPair > sourceDestinationDatumTransforms () const
 Returns the stored mapping for source to destination CRS pairs to associated datum transforms to use.
 
void writeSettings ()
 Write the context's state to application settings.
 
void writeXml (QDomElement &element, const QgsReadWriteContext &context) const
 Writes the context's state to a DOM element.
 

Detailed Description

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.
QgsCoordinateTransformContext objects are implicitly shared.
See also
QgsDatumTransform
QgsCoordinateTransform

Definition at line 56 of file qgscoordinatetransformcontext.h.

Constructor & Destructor Documentation

◆ QgsCoordinateTransformContext() [1/2]

QgsCoordinateTransformContext::QgsCoordinateTransformContext ( )

Constructor for QgsCoordinateTransformContext.

Definition at line 39 of file qgscoordinatetransformcontext.cpp.

◆ ~QgsCoordinateTransformContext()

QgsCoordinateTransformContext::~QgsCoordinateTransformContext ( )
default

◆ QgsCoordinateTransformContext() [2/2]

QgsCoordinateTransformContext::QgsCoordinateTransformContext ( const QgsCoordinateTransformContext &  rhs)

Definition at line 45 of file qgscoordinatetransformcontext.cpp.

Member Function Documentation

◆ addCoordinateOperation()

bool QgsCoordinateTransformContext::addCoordinateOperation ( const QgsCoordinateReferenceSystem &  sourceCrs,
const QgsCoordinateReferenceSystem &  destinationCrs,
const QString &  coordinateOperationProjString,
bool  allowFallback = true 
)

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.

See also
coordinateOperations()
removeCoordinateOperation()
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.
Since
QGIS 3.8

Definition at line 104 of file qgscoordinatetransformcontext.cpp.

◆ addSourceDestinationDatumTransform()

bool QgsCoordinateTransformContext::addSourceDestinationDatumTransform ( const QgsCoordinateReferenceSystem &  sourceCrs,
const QgsCoordinateReferenceSystem &  destinationCrs,
int  sourceTransformId,
int  destinationTransformId 
)

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.

See also
sourceDestinationDatumTransforms()
removeSourceDestinationDatumTransform()
Deprecated:
QGIS 3.40. Has no effect on builds based on Proj 6.0 or later, use addCoordinateOperation() instead.

Definition at line 95 of file qgscoordinatetransformcontext.cpp.

◆ allowFallbackTransform()

bool QgsCoordinateTransformContext::allowFallbackTransform ( const QgsCoordinateReferenceSystem &  source,
const QgsCoordinateReferenceSystem &  destination 
) const

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.

Since
QGIS 3.12

Definition at line 160 of file qgscoordinatetransformcontext.cpp.

◆ calculateCoordinateOperation()

QString QgsCoordinateTransformContext::calculateCoordinateOperation ( const QgsCoordinateReferenceSystem &  source,
const QgsCoordinateReferenceSystem &  destination 
) const

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.
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.
Since
QGIS 3.8

Definition at line 141 of file qgscoordinatetransformcontext.cpp.

◆ calculateDatumTransforms()

QgsDatumTransform::TransformPair QgsCoordinateTransformContext::calculateDatumTransforms ( const QgsCoordinateReferenceSystem &  source,
const QgsCoordinateReferenceSystem &  destination 
) const

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:
QGIS 3.40. Has no effect on builds based on Proj 6.0 or later. Use calculateCoordinateOperation() instead.

Definition at line 134 of file qgscoordinatetransformcontext.cpp.

◆ clear()

void QgsCoordinateTransformContext::clear ( )

Clears all stored transform information from the context.

Definition at line 68 of file qgscoordinatetransformcontext.cpp.

◆ coordinateOperations()

QMap< QPair< QString, QString >, QString > QgsCoordinateTransformContext::coordinateOperations ( ) const

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.
See also
addCoordinateOperation()
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.
Since
QGIS 3.8

Definition at line 82 of file qgscoordinatetransformcontext.cpp.

◆ hasTransform()

bool QgsCoordinateTransformContext::hasTransform ( const QgsCoordinateReferenceSystem &  source,
const QgsCoordinateReferenceSystem &  destination 
) const

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.

Definition at line 128 of file qgscoordinatetransformcontext.cpp.

◆ mustReverseCoordinateOperation()

bool QgsCoordinateTransformContext::mustReverseCoordinateOperation ( const QgsCoordinateReferenceSystem &  source,
const QgsCoordinateReferenceSystem &  destination 
) const

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

Since
QGIS 3.10.2

Definition at line 176 of file qgscoordinatetransformcontext.cpp.

◆ operator=()

QgsCoordinateTransformContext & QgsCoordinateTransformContext::operator= ( const QgsCoordinateTransformContext &  rhs)

Definition at line 49 of file qgscoordinatetransformcontext.cpp.

◆ operator==()

bool QgsCoordinateTransformContext::operator== ( const QgsCoordinateTransformContext &  rhs) const

Definition at line 55 of file qgscoordinatetransformcontext.cpp.

◆ readSettings()

void QgsCoordinateTransformContext::readSettings ( )

Reads the context's state from application settings.

See also
readSettings()

Definition at line 298 of file qgscoordinatetransformcontext.cpp.

◆ readXml()

bool QgsCoordinateTransformContext::readXml ( const QDomElement &  element,
const QgsReadWriteContext &  context,
QStringList &  missingTransforms 
)

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

Definition at line 200 of file qgscoordinatetransformcontext.cpp.

◆ removeCoordinateOperation()

void QgsCoordinateTransformContext::removeCoordinateOperation ( const QgsCoordinateReferenceSystem &  sourceCrs,
const QgsCoordinateReferenceSystem &  destinationCrs 
)

Removes the coordinate operation for the specified sourceCrs and destinationCrs.

Since
QGIS 3.8

Definition at line 123 of file qgscoordinatetransformcontext.cpp.

◆ removeSourceDestinationDatumTransform()

void QgsCoordinateTransformContext::removeSourceDestinationDatumTransform ( const QgsCoordinateReferenceSystem &  sourceCrs,
const QgsCoordinateReferenceSystem &  destinationCrs 
)

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

See also
addSourceDestinationDatumTransform()
Deprecated:
QGIS 3.40. Use removeCoordinateOperation() instead.

Definition at line 118 of file qgscoordinatetransformcontext.cpp.

◆ sourceDestinationDatumTransforms()

QMap< QPair< QString, QString >, QgsDatumTransform::TransformPair > QgsCoordinateTransformContext::sourceDestinationDatumTransforms ( ) const

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.
See also
addSourceDestinationDatumTransform()
Deprecated:
QGIS 3.40. Has no effect on builds based on Proj 6.0 or later, use coordinateOperations() instead.

Definition at line 77 of file qgscoordinatetransformcontext.cpp.

◆ writeSettings()

void QgsCoordinateTransformContext::writeSettings ( )

Write the context's state to application settings.

See also
writeSettings()

Definition at line 350 of file qgscoordinatetransformcontext.cpp.

◆ writeXml()

void QgsCoordinateTransformContext::writeXml ( QDomElement &  element,
const QgsReadWriteContext &  context 
) const

Writes the context's state to a DOM element.

See also
readXml()

Definition at line 268 of file qgscoordinatetransformcontext.cpp.

The documentation for this class was generated from the following files:
Generated on Sun Nov 10 2024 14:15:43 for QGIS API Documentation by doxygen 1.9.8