QGIS API Documentation  3.7.0-Master (284f5d5)
Public Types | Public Member Functions | Static Public Member Functions | List of all members
QgsCoordinateTransform Class Reference

Class for doing transforms between two map coordinate systems. More...

#include <qgscoordinatetransform.h>

Public Types

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

Public Member Functions

 QgsCoordinateTransform ()
 Default constructor, creates an invalid QgsCoordinateTransform. More...
 
 QgsCoordinateTransform (const QgsCoordinateReferenceSystem &source, const QgsCoordinateReferenceSystem &destination, const QgsCoordinateTransformContext &context)
 Constructs a QgsCoordinateTransform to transform from the source to destination coordinate reference system. More...
 
 QgsCoordinateTransform (const QgsCoordinateReferenceSystem &source, const QgsCoordinateReferenceSystem &destination, const QgsProject *project)
 Constructs a QgsCoordinateTransform to transform from the source to destination coordinate reference system, when used with the given project. More...
 
 QgsCoordinateTransform (const QgsCoordinateReferenceSystem &source, const QgsCoordinateReferenceSystem &destination, int sourceDatumTransformId, int destinationDatumTransformId)
 Constructs a QgsCoordinateTransform to transform from the source to destination coordinate reference system, with the specified datum transforms (see QgsDatumTransform). More...
 
 QgsCoordinateTransform (const QgsCoordinateTransform &o)
 Copy constructor. More...
 
 ~QgsCoordinateTransform ()
 
QgsCoordinateTransformContext context () const
 Returns the context in which the coordinate transform will be calculated. More...
 
QgsCoordinateReferenceSystem destinationCrs () const
 Returns the destination coordinate reference system, which the transform will transform coordinates to. More...
 
int destinationDatumTransformId () const
 Returns the ID of the datum transform to use when projecting to the destination CRS. More...
 
bool isShortCircuited () const
 Returns true if the transform short circuits because the source and destination are equivalent. More...
 
bool isValid () const
 Returns true if the coordinate transform is valid, ie both the source and destination CRS have been set and are valid. More...
 
QgsCoordinateTransformoperator= (const QgsCoordinateTransform &o)
 Assignment operator. More...
 
double scaleFactor (const QgsRectangle &referenceExtent) const
 Computes an estimated conversion factor between source and destination units: More...
 
void setContext (const QgsCoordinateTransformContext &context)
 Sets the context in which the coordinate transform should be calculated. More...
 
void setDestinationCrs (const QgsCoordinateReferenceSystem &crs)
 Sets the destination coordinate reference system. More...
 
void setDestinationDatumTransformId (int datumId)
 Sets the datumId ID of the datum transform to use when projecting to the destination CRS. More...
 
void setSourceCrs (const QgsCoordinateReferenceSystem &crs)
 Sets the source coordinate reference system. More...
 
void setSourceDatumTransformId (int datumId)
 Sets the datumId ID of the datum transform to use when projecting from the source CRS. More...
 
QgsCoordinateReferenceSystem sourceCrs () const
 Returns the source coordinate reference system, which the transform will transform coordinates from. More...
 
int sourceDatumTransformId () const
 Returns the ID of the datum transform to use when projecting from the source CRS. More...
 
QgsPointXY transform (const QgsPointXY &point, TransformDirection direction=ForwardTransform) const SIP_THROW(QgsCsException)
 Transform the point from the source CRS to the destination CRS. More...
 
QgsPointXY transform (double x, double y, TransformDirection direction=ForwardTransform) const
 Transform the point specified by x,y from the source CRS to the destination CRS. More...
 
QgsRectangle transform (const QgsRectangle &rectangle, TransformDirection direction=ForwardTransform) const SIP_THROW(QgsCsException)
 Transforms a rectangle to the destination CRS. More...
 
QgsRectangle transformBoundingBox (const QgsRectangle &rectangle, TransformDirection direction=ForwardTransform, bool handle180Crossover=false) const SIP_THROW(QgsCsException)
 Transforms a rectangle from the source CRS to the destination CRS. More...
 
void transformCoords (int numPoint, double *x, double *y, double *z, TransformDirection direction=ForwardTransform) const SIP_THROW(QgsCsException)
 Transform an array of coordinates to the destination CRS. More...
 
void transformInPlace (double &x, double &y, double &z, TransformDirection direction=ForwardTransform) const SIP_THROW(QgsCsException)
 Transforms an array of x, y and z double coordinates in place, from the source CRS to the destination CRS. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
void transformPolygon (QPolygonF &polygon, TransformDirection direction=ForwardTransform) const SIP_THROW(QgsCsException)
 Transforms a polygon to the destination coordinate system. More...
 

Static Public Member Functions

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

Detailed Description

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.
See also
QgsDatumTransform
QgsCoordinateTransformContext

Definition at line 52 of file qgscoordinatetransform.h.

Member Enumeration Documentation

◆ TransformDirection

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

Enumerator
ForwardTransform 

Transform from source to destination CRS.

ReverseTransform 

Transform from destination to source CRS.

Definition at line 58 of file qgscoordinatetransform.h.

Constructor & Destructor Documentation

◆ QgsCoordinateTransform() [1/5]

QgsCoordinateTransform::QgsCoordinateTransform ( )

Default constructor, creates an invalid QgsCoordinateTransform.

Definition at line 50 of file qgscoordinatetransform.cpp.

◆ QgsCoordinateTransform() [2/5]

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.

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 the QgsCoordinateTransformContext object is correctly retrieved based on the current code context, or use the constructor variant which accepts a QgsProject argument instead.
Since
QGIS 3.0

Definition at line 55 of file qgscoordinatetransform.cpp.

◆ QgsCoordinateTransform() [3/5]

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.

Since
QGIS 3.0

Definition at line 73 of file qgscoordinatetransform.cpp.

◆ QgsCoordinateTransform() [4/5]

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

Since
QGIS 3.0

Definition at line 92 of file qgscoordinatetransform.cpp.

◆ QgsCoordinateTransform() [5/5]

QgsCoordinateTransform::QgsCoordinateTransform ( const QgsCoordinateTransform o)

Copy constructor.

Definition at line 109 of file qgscoordinatetransform.cpp.

◆ ~QgsCoordinateTransform()

QgsCoordinateTransform::~QgsCoordinateTransform ( )

Definition at line 128 of file qgscoordinatetransform.cpp.

Member Function Documentation

◆ context()

QgsCoordinateTransformContext QgsCoordinateTransform::context ( ) const

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

See also
setContext()
Since
QGIS 3.4

Definition at line 177 of file qgscoordinatetransform.cpp.

◆ destinationCrs()

QgsCoordinateReferenceSystem QgsCoordinateTransform::destinationCrs ( ) const

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

See also
setDestinationCrs()
sourceCrs()

Definition at line 187 of file qgscoordinatetransform.cpp.

◆ destinationDatumTransformId()

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

See also
QgsDatumTransform
setDestinationDatumTransformId()
sourceDatumTransformId()

Definition at line 820 of file qgscoordinatetransform.cpp.

◆ invalidateCache()

void QgsCoordinateTransform::invalidateCache ( )
static

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.

Since
QGIS 3.0

Definition at line 831 of file qgscoordinatetransform.cpp.

◆ isShortCircuited()

bool QgsCoordinateTransform::isShortCircuited ( ) const

Returns true if the transform short circuits because the source and destination are equivalent.

Definition at line 750 of file qgscoordinatetransform.cpp.

◆ isValid()

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.

Since
QGIS 3.0

Definition at line 745 of file qgscoordinatetransform.cpp.

◆ operator=()

QgsCoordinateTransform & QgsCoordinateTransform::operator= ( const QgsCoordinateTransform o)

Assignment operator.

Definition at line 118 of file qgscoordinatetransform.cpp.

◆ scaleFactor()

double QgsCoordinateTransform::scaleFactor ( const QgsRectangle referenceExtent) const

Computes an estimated conversion factor between source and destination units:

sourceUnits * scaleFactor = destinationUnits

Parameters
referenceExtentA reference extent based on which to perform the computation
Since
QGIS 3.4

Definition at line 838 of file qgscoordinatetransform.cpp.

◆ setContext()

void QgsCoordinateTransform::setContext ( const QgsCoordinateTransformContext context)

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

See also
context()
Since
QGIS 3.0

Definition at line 159 of file qgscoordinatetransform.cpp.

◆ setDestinationCrs()

void QgsCoordinateTransform::setDestinationCrs ( const QgsCoordinateReferenceSystem crs)

Sets the destination coordinate reference system.

Parameters
crsCRS to transform coordinates to
See also
destinationCrs()
setSourceCrs()

Definition at line 144 of file qgscoordinatetransform.cpp.

◆ setDestinationDatumTransformId()

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.

See also
QgsDatumTransform
destinationDatumTransformId()
setSourceDatumTransformId()

Definition at line 825 of file qgscoordinatetransform.cpp.

◆ setSourceCrs()

void QgsCoordinateTransform::setSourceCrs ( const QgsCoordinateReferenceSystem crs)

Sets the source coordinate reference system.

Parameters
crsCRS to transform coordinates from
See also
sourceCrs()
setDestinationCrs()

Definition at line 130 of file qgscoordinatetransform.cpp.

◆ setSourceDatumTransformId()

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.

See also
QgsDatumTransform
sourceDatumTransformId()
setDestinationDatumTransformId()

Definition at line 814 of file qgscoordinatetransform.cpp.

◆ sourceCrs()

QgsCoordinateReferenceSystem QgsCoordinateTransform::sourceCrs ( ) const

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

See also
setSourceCrs()
destinationCrs()

Definition at line 182 of file qgscoordinatetransform.cpp.

◆ sourceDatumTransformId()

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

See also
QgsDatumTransform
setSourceDatumTransformId()
destinationDatumTransformId()

Definition at line 809 of file qgscoordinatetransform.cpp.

◆ transform() [1/3]

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

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
pointpoint to transform
directiontransform direction (defaults to ForwardTransform)
Returns
transformed point

Definition at line 192 of file qgscoordinatetransform.cpp.

◆ transform() [2/3]

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

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
xx coordinate of point to transform
yy coordinate of point to transform
directiontransform direction (defaults to ForwardTransform)
Returns
transformed point

Definition at line 216 of file qgscoordinatetransform.cpp.

◆ transform() [3/3]

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

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
rectanglerectangle to transform
directiontransform direction (defaults to ForwardTransform)
Returns
transformed rectangle

Definition at line 230 of file qgscoordinatetransform.cpp.

◆ transformBoundingBox()

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

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
rectanglerectangle to transform
directiontransform direction (defaults to ForwardTransform)
handle180Crossoverset to true if destination CRS is geographic and handling of extents crossing the 180 degree longitude line is required
Returns
rectangle in destination CRS

Definition at line 460 of file qgscoordinatetransform.cpp.

◆ transformCoords()

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

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
numPointnumber of coordinates in arrays
xarray of x coordinates to transform
yarray of y coordinates to transform
zarray of z coordinates to transform
directiontransform direction (defaults to ForwardTransform)

Definition at line 580 of file qgscoordinatetransform.cpp.

◆ transformInPlace() [1/5]

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

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
xarray of x coordinates of points to transform
yarray of y coordinates of points to transform
zarray 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)
directiontransform direction (defaults to ForwardTransform)

Definition at line 266 of file qgscoordinatetransform.cpp.

◆ transformInPlace() [2/5]

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.

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

Parameters
xarray of x coordinates of points to transform
yarray of y coordinates of points to transform
zarray 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)
directiontransform direction (defaults to ForwardTransform)
Note
not available in Python bindings

Definition at line 287 of file qgscoordinatetransform.cpp.

◆ transformInPlace() [3/5]

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.

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

Parameters
xarray of x coordinates of points to transform
yarray of y coordinates of points to transform
zarray 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)
directiontransform direction (defaults to ForwardTransform)
Note
not available in Python bindings

Definition at line 296 of file qgscoordinatetransform.cpp.

◆ transformInPlace() [4/5]

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.

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

Parameters
xvector of x coordinates of points to transform
yvector of y coordinates of points to transform
zvector 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)
directiontransform direction (defaults to ForwardTransform)
Note
not available in Python bindings

Definition at line 399 of file qgscoordinatetransform.cpp.

◆ transformInPlace() [5/5]

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.

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

Parameters
xvector of x coordinates of points to transform
yvector of y coordinates of points to transform
zvector 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)
directiontransform direction (defaults to ForwardTransform)
Note
not available in Python bindings

Definition at line 371 of file qgscoordinatetransform.cpp.

◆ transformPolygon()

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

Transforms a polygon to the destination coordinate system.

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

Definition at line 323 of file qgscoordinatetransform.cpp.


The documentation for this class was generated from the following files: