Skip to content

Commit e6df492

Browse files
nyalldawsonnyalldawson
committedJul 17, 2016
Add missing docs, refine docs for QgsCoordinateTransform
·
ltr-3_40final-3_0_0
1 parent adafeda commit e6df492

File tree

2 files changed

+195
-91
lines changed

2 files changed

+195
-91
lines changed
 

‎python/core/qgscoordinatetransform.sip

Lines changed: 104 additions & 52 deletions
Original file line numberDiff line numberDiff line change
@@ -98,78 +98,130 @@ class QgsCoordinateTransform
9898
*/
9999
QgsCoordinateReferenceSystem destinationCrs() const;
100100

101-
/** Transform the point from Source Coordinate System to Destination Coordinate System
102-
* If the direction is ForwardTransform then coordinates are transformed from layer CS --> map canvas CS,
103-
* otherwise points are transformed from map canvas CS to layerCS.
104-
* @param point Point to transform
105-
* @param direction TransformDirection (defaults to ForwardTransform)
106-
* @return QgsPoint in Destination Coordinate System
107-
*/
108-
QgsPoint transform( const QgsPoint &point, TransformDirection direction = ForwardTransform ) const throw (QgsCsException);
109-
110-
/** Transform the point specified by x,y from Source Coordinate System to Destination Coordinate System
111-
* If the direction is ForwardTransform then coordinates are transformed from layer CS --> map canvas CS,
112-
* otherwise points are transformed from map canvas CS to layerCS.
113-
* @param x x cordinate of point to transform
101+
/** Transform the point from the source CRS to the destination CRS.
102+
* If the direction is ForwardTransform then coordinates are transformed from source to destination,
103+
* otherwise points are transformed from destination to source CRS.
104+
* @param point point to transform
105+
* @param direction transform direction (defaults to ForwardTransform)
106+
* @return transformed point
107+
*/
108+
QgsPoint transform( const QgsPoint& point, TransformDirection direction = ForwardTransform ) const;
109+
110+
/** Transform the point specified by x,y from the source CRS to the destination CRS.
111+
* If the direction is ForwardTransform then coordinates are transformed from source to destination,
112+
* otherwise points are transformed from destination to source CRS.
113+
* @param x x coordinate of point to transform
114114
* @param y y coordinate of point to transform
115-
* @param direction TransformDirection (defaults to ForwardTransform)
116-
* @return QgsPoint in Destination Coordinate System
115+
* @param direction transform direction (defaults to ForwardTransform)
116+
* @return transformed point
117117
*/
118-
QgsPoint transform( const double x, const double y, TransformDirection direction = ForwardTransform ) const throw (QgsCsException);
118+
QgsPoint transform( const double x, const double y, TransformDirection direction = ForwardTransform ) const;
119119

120-
/** Transforms a QgsRectangle to the dest Coordinate system
121-
* If the direction is ForwardTransform then coordinates are transformed from layer CS --> map canvas CS,
122-
* otherwise points are transformed from map canvas CS to layerCS.
123-
* It assumes that rect is a bounding box, and creates a bounding box
124-
* in the proejcted CS, so that all points in source rectangle is within
125-
* returned rectangle.
120+
/** Transforms a rectangle from the source CRS to the destination CRS.
121+
* If the direction is ForwardTransform then coordinates are transformed from source to destination,
122+
* otherwise points are transformed from destination to source CRS.
123+
* This method assumes that the rectangle is a bounding box, and creates a bounding box
124+
* in the projected CRS, such that all points from the source rectangle are within
125+
* the returned rectangle.
126126
* @param rectangle rectangle to transform
127-
* @param direction TransformDirection (defaults to ForwardTransform)
128-
* @param handle180Crossover set to true if destination crs is geographic and handling of extents crossing the 180 degree
129-
* longitude line is required
130-
* @return QgsRectangle in Destination Coordinate System
127+
* @param direction transform direction (defaults to ForwardTransform)
128+
* @param handle180Crossover set to true if destination CRS is geographic and handling of extents
129+
* crossing the 180 degree longitude line is required
130+
* @return rectangle in destination CRS
131+
*/
132+
QgsRectangle transformBoundingBox( const QgsRectangle& rectangle, TransformDirection direction = ForwardTransform, const bool handle180Crossover = false ) const;
133+
134+
/** Transforms an array of x, y and z double coordinates in place, from the source CRS to the destination CRS.
135+
* If the direction is ForwardTransform then coordinates are transformed from source to destination,
136+
* otherwise points are transformed from destination to source CRS.
137+
* @param x array of x coordinates of points to transform
138+
* @param y array of y coordinates of points to transform
139+
* @param z array of z coordinates of points to transform. The z coordinates of the points
140+
* must represent height relative to the vertical datum of the source CRS (generally ellipsoidal
141+
* heights) and must be expressed in its vertical units (generally meters)
142+
* @param direction transform direction (defaults to ForwardTransform)
131143
*/
132-
QgsRectangle transformBoundingBox( const QgsRectangle &rectangle, TransformDirection direction = ForwardTransform, const bool handle180Crossover = false ) const throw (QgsCsException);
144+
void transformInPlace( double& x, double& y, double &z, TransformDirection direction = ForwardTransform ) const;
133145

134-
// Same as for the other transform() functions, but alters the x
135-
// and y variables in place. The second one works with good old-fashioned
136-
// C style arrays.
137-
void transformInPlace( double& x, double& y, double &z, TransformDirection direction = ForwardTransform ) const throw (QgsCsException);
146+
/** Transforms an array of x, y and z float coordinates in place, from the source CRS to the destination CRS.
147+
* If the direction is ForwardTransform then coordinates are transformed from source to destination,
148+
* otherwise points are transformed from destination to source CRS.
149+
* @param x array of x coordinates of points to transform
150+
* @param y array of y coordinates of points to transform
151+
* @param z array of z coordinates of points to transform. The z coordinates of the points
152+
* must represent height relative to the vertical datum of the source CRS (generally ellipsoidal
153+
* heights) and must be expressed in its vertical units (generally meters)
154+
* @param direction transform direction (defaults to ForwardTransform)
155+
* @note not available in python bindings
156+
*/
157+
//void transformInPlace( float& x, float& y, double &z, TransformDirection direction = ForwardTransform ) const;
138158

139-
// @note not available in python bindings
140-
// void transformInPlace( float& x, float& y, double &z, TransformDirection direction = ForwardTransform ) const;
141-
// @note not available in python bindings
159+
/** Transforms an array of x, y and z float coordinates in place, from the source CRS to the destination CRS.
160+
* If the direction is ForwardTransform then coordinates are transformed from source to destination,
161+
* otherwise points are transformed from destination to source CRS.
162+
* @param x array of x coordinates of points to transform
163+
* @param y array of y coordinates of points to transform
164+
* @param z array of z coordinates of points to transform. The z coordinates of the points
165+
* must represent height relative to the vertical datum of the source CRS (generally ellipsoidal
166+
* heights) and must be expressed in its vertical units (generally meters)
167+
* @param direction transform direction (defaults to ForwardTransform)
168+
* @note not available in python bindings
169+
*/
142170
// void transformInPlace( float& x, float& y, float& z, TransformDirection direction = ForwardTransform ) const;
143-
// @note not available in python bindings
144-
// void transformInPlace( QVector<float>& x, QVector<float>& y, QVector<float>& z,
171+
172+
/** Transforms a vector of x, y and z float coordinates in place, from the source CRS to the destination CRS.
173+
* If the direction is ForwardTransform then coordinates are transformed from source to destination,
174+
* otherwise points are transformed from destination to source CRS.
175+
* @param x vector of x coordinates of points to transform
176+
* @param y vector of y coordinates of points to transform
177+
* @param z vector of z coordinates of points to transform. The z coordinates of the points
178+
* must represent height relative to the vertical datum of the source CRS (generally ellipsoidal
179+
* heights) and must be expressed in its vertical units (generally meters)
180+
* @param direction transform direction (defaults to ForwardTransform)
181+
* @note not available in python bindings
182+
*/
183+
//void transformInPlace( QVector<float>& x, QVector<float>& y, QVector<float>& z,
145184
// TransformDirection direction = ForwardTransform ) const;
146185

147-
//! @note not available in python bindings
148-
// void transformInPlace( QVector<double>& x, QVector<double>& y, QVector<double>& z,
149-
// TransformDirection direction = ForwardTransform ) const;
186+
/** Transforms a vector of x, y and z double coordinates in place, from the source CRS to the destination CRS.
187+
* If the direction is ForwardTransform then coordinates are transformed from source to destination,
188+
* otherwise points are transformed from destination to source CRS.
189+
* @param x vector of x coordinates of points to transform
190+
* @param y vector of y coordinates of points to transform
191+
* @param z vector of z coordinates of points to transform. The z coordinates of the points
192+
* must represent height relative to the vertical datum of the source CRS (generally ellipsoidal
193+
* heights) and must be expressed in its vertical units (generally meters)
194+
* @param direction transform direction (defaults to ForwardTransform)
195+
* @note not available in python bindings
196+
*/
197+
//void transformInPlace( QVector<double>& x, QVector<double>& y, QVector<double>& z,
198+
// TransformDirection direction = ForwardTransform ) const;
150199

200+
/** Transforms a polygon to the destination coordinate system.
201+
* @param polygon polygon to transform (occurs in place)
202+
* @param direction transform direction (defaults to forward transformation)
203+
*/
151204
void transformPolygon( QPolygonF& polygon, TransformDirection direction = ForwardTransform ) const;
152205

153-
/** Transform a QgsRectangle to the dest Coordinate system
154-
* If the direction is ForwardTransform then coordinates are transformed from layer CS --> map canvas CS,
155-
* otherwise points are transformed from map canvas CS to layerCS.
156-
* @param rectangle rect to transform
157-
* @param direction TransformDirection (defaults to ForwardTransform)
158-
* @return QgsRectangle in Destination Coordinate System
206+
/** Transforms a rectangle to the destination CRS.
207+
* If the direction is ForwardTransform then coordinates are transformed from source to destination,
208+
* otherwise points are transformed from destination to source CRS.
209+
* @param rectangle rectangle to transform
210+
* @param direction transform direction (defaults to ForwardTransform)
211+
* @return transformed rectangle
159212
*/
160-
QgsRectangle transform( const QgsRectangle &rectangle, TransformDirection direction = ForwardTransform ) const throw (QgsCsException);
213+
QgsRectangle transform( const QgsRectangle &rectangle, TransformDirection direction = ForwardTransform ) const;
161214

162-
/** Transform an array of coordinates to a different Coordinate System
163-
* If the direction is ForwardTransform then coordinates are transformed from layer CS --> map canvas CS,
164-
* otherwise points are transformed from map canvas CS to layerCS.
215+
/** Transform an array of coordinates to the destination CRS.
216+
* If the direction is ForwardTransform then coordinates are transformed from source to destination,
217+
* otherwise points are transformed from destination to source CRS.
165218
* @param numPoint number of coordinates in arrays
166219
* @param x array of x coordinates to transform
167220
* @param y array of y coordinates to transform
168221
* @param z array of z coordinates to transform
169-
* @param direction TransformDirection (defaults to ForwardTransform)
170-
* @return QgsRectangle in Destination Coordinate System
222+
* @param direction transform direction (defaults to ForwardTransform)
171223
*/
172-
void transformCoords( int numPoint, double *x, double *y, double *z, TransformDirection direction = ForwardTransform ) const throw (QgsCsException);
224+
void transformCoords( int numPoint, double *x, double *y, double *z, TransformDirection direction = ForwardTransform ) const;
173225

174226
/** Returns true if the transform short circuits because the source and destination are equivalent.
175227
*/

‎src/core/qgscoordinatetransform.h

Lines changed: 91 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -123,76 +123,128 @@ class CORE_EXPORT QgsCoordinateTransform
123123
*/
124124
QgsCoordinateReferenceSystem destinationCrs() const;
125125

126-
/** Transform the point from Source Coordinate System to Destination Coordinate System
127-
* If the direction is ForwardTransform then coordinates are transformed from layer CS --> map canvas CS,
128-
* otherwise points are transformed from map canvas CS to layerCS.
129-
* @param point Point to transform
130-
* @param direction TransformDirection (defaults to ForwardTransform)
131-
* @return QgsPoint in Destination Coordinate System
126+
/** Transform the point from the source CRS to the destination CRS.
127+
* If the direction is ForwardTransform then coordinates are transformed from source to destination,
128+
* otherwise points are transformed from destination to source CRS.
129+
* @param point point to transform
130+
* @param direction transform direction (defaults to ForwardTransform)
131+
* @return transformed point
132132
*/
133133
QgsPoint transform( const QgsPoint& point, TransformDirection direction = ForwardTransform ) const;
134134

135-
/** Transform the point specified by x,y from Source Coordinate System to Destination Coordinate System
136-
* If the direction is ForwardTransform then coordinates are transformed from layer CS --> map canvas CS,
137-
* otherwise points are transformed from map canvas CS to layerCS.
138-
* @param x x cordinate of point to transform
135+
/** Transform the point specified by x,y from the source CRS to the destination CRS.
136+
* If the direction is ForwardTransform then coordinates are transformed from source to destination,
137+
* otherwise points are transformed from destination to source CRS.
138+
* @param x x coordinate of point to transform
139139
* @param y y coordinate of point to transform
140-
* @param direction TransformDirection (defaults to ForwardTransform)
141-
* @return QgsPoint in Destination Coordinate System
140+
* @param direction transform direction (defaults to ForwardTransform)
141+
* @return transformed point
142142
*/
143143
QgsPoint transform( const double x, const double y, TransformDirection direction = ForwardTransform ) const;
144144

145-
/** Transforms a QgsRectangle to the desttination coordinate system.
146-
* If the direction is ForwardTransform then coordinates are transformed from layer CS --> map canvas CS,
147-
* otherwise points are transformed from map canvas CS to layerCS.
148-
* It assumes that rect is a bounding box, and creates a bounding box
149-
* in the proejcted CS, so that all points in source rectangle is within
150-
* returned rectangle.
145+
/** Transforms a rectangle from the source CRS to the destination CRS.
146+
* If the direction is ForwardTransform then coordinates are transformed from source to destination,
147+
* otherwise points are transformed from destination to source CRS.
148+
* This method assumes that the rectangle is a bounding box, and creates a bounding box
149+
* in the projected CRS, such that all points from the source rectangle are within
150+
* the returned rectangle.
151151
* @param rectangle rectangle to transform
152-
* @param direction TransformDirection (defaults to ForwardTransform)
153-
* @param handle180Crossover set to true if destination crs is geographic and handling of extents crossing the 180 degree
154-
* longitude line is required
155-
* @return QgsRectangle in Destination Coordinate System
152+
* @param direction transform direction (defaults to ForwardTransform)
153+
* @param handle180Crossover set to true if destination CRS is geographic and handling of extents
154+
* crossing the 180 degree longitude line is required
155+
* @return rectangle in destination CRS
156156
*/
157157
QgsRectangle transformBoundingBox( const QgsRectangle& rectangle, TransformDirection direction = ForwardTransform, const bool handle180Crossover = false ) const;
158158

159-
// Same as for the other transform() functions, but alters the x
160-
// and y variables in place. The second one works with good old-fashioned
161-
// C style arrays.
159+
/** Transforms an array of x, y and z double coordinates in place, from the source CRS to the destination CRS.
160+
* If the direction is ForwardTransform then coordinates are transformed from source to destination,
161+
* otherwise points are transformed from destination to source CRS.
162+
* @param x array of x coordinates of points to transform
163+
* @param y array of y coordinates of points to transform
164+
* @param z array of z coordinates of points to transform. The z coordinates of the points
165+
* must represent height relative to the vertical datum of the source CRS (generally ellipsoidal
166+
* heights) and must be expressed in its vertical units (generally meters)
167+
* @param direction transform direction (defaults to ForwardTransform)
168+
*/
162169
void transformInPlace( double& x, double& y, double &z, TransformDirection direction = ForwardTransform ) const;
163170

164-
//! @note not available in python bindings
171+
/** Transforms an array of x, y and z float coordinates in place, from the source CRS to the destination CRS.
172+
* If the direction is ForwardTransform then coordinates are transformed from source to destination,
173+
* otherwise points are transformed from destination to source CRS.
174+
* @param x array of x coordinates of points to transform
175+
* @param y array of y coordinates of points to transform
176+
* @param z array of z coordinates of points to transform. The z coordinates of the points
177+
* must represent height relative to the vertical datum of the source CRS (generally ellipsoidal
178+
* heights) and must be expressed in its vertical units (generally meters)
179+
* @param direction transform direction (defaults to ForwardTransform)
180+
* @note not available in python bindings
181+
*/
165182
void transformInPlace( float& x, float& y, double &z, TransformDirection direction = ForwardTransform ) const;
166-
//! @note not available in python bindings
183+
184+
/** Transforms an array of x, y and z float coordinates in place, from the source CRS to the destination CRS.
185+
* If the direction is ForwardTransform then coordinates are transformed from source to destination,
186+
* otherwise points are transformed from destination to source CRS.
187+
* @param x array of x coordinates of points to transform
188+
* @param y array of y coordinates of points to transform
189+
* @param z array of z coordinates of points to transform. The z coordinates of the points
190+
* must represent height relative to the vertical datum of the source CRS (generally ellipsoidal
191+
* heights) and must be expressed in its vertical units (generally meters)
192+
* @param direction transform direction (defaults to ForwardTransform)
193+
* @note not available in python bindings
194+
*/
167195
void transformInPlace( float& x, float& y, float& z, TransformDirection direction = ForwardTransform ) const;
168-
//! @note not available in python bindings
196+
197+
/** Transforms a vector of x, y and z float coordinates in place, from the source CRS to the destination CRS.
198+
* If the direction is ForwardTransform then coordinates are transformed from source to destination,
199+
* otherwise points are transformed from destination to source CRS.
200+
* @param x vector of x coordinates of points to transform
201+
* @param y vector of y coordinates of points to transform
202+
* @param z vector of z coordinates of points to transform. The z coordinates of the points
203+
* must represent height relative to the vertical datum of the source CRS (generally ellipsoidal
204+
* heights) and must be expressed in its vertical units (generally meters)
205+
* @param direction transform direction (defaults to ForwardTransform)
206+
* @note not available in python bindings
207+
*/
169208
void transformInPlace( QVector<float>& x, QVector<float>& y, QVector<float>& z,
170209
TransformDirection direction = ForwardTransform ) const;
171210

172-
//! @note not available in python bindings
211+
/** Transforms a vector of x, y and z double coordinates in place, from the source CRS to the destination CRS.
212+
* If the direction is ForwardTransform then coordinates are transformed from source to destination,
213+
* otherwise points are transformed from destination to source CRS.
214+
* @param x vector of x coordinates of points to transform
215+
* @param y vector of y coordinates of points to transform
216+
* @param z vector of z coordinates of points to transform. The z coordinates of the points
217+
* must represent height relative to the vertical datum of the source CRS (generally ellipsoidal
218+
* heights) and must be expressed in its vertical units (generally meters)
219+
* @param direction transform direction (defaults to ForwardTransform)
220+
* @note not available in python bindings
221+
*/
173222
void transformInPlace( QVector<double>& x, QVector<double>& y, QVector<double>& z,
174223
TransformDirection direction = ForwardTransform ) const;
175224

225+
/** Transforms a polygon to the destination coordinate system.
226+
* @param polygon polygon to transform (occurs in place)
227+
* @param direction transform direction (defaults to forward transformation)
228+
*/
176229
void transformPolygon( QPolygonF& polygon, TransformDirection direction = ForwardTransform ) const;
177230

178-
/** Transform a QgsRectangle to the dest Coordinate system
179-
* If the direction is ForwardTransform then coordinates are transformed from layer CS --> map canvas CS,
180-
* otherwise points are transformed from map canvas CS to layerCS.
231+
/** Transforms a rectangle to the destination CRS.
232+
* If the direction is ForwardTransform then coordinates are transformed from source to destination,
233+
* otherwise points are transformed from destination to source CRS.
181234
* @param rectangle rectangle to transform
182-
* @param direction TransformDirection (defaults to ForwardTransform)
183-
* @return QgsRectangle in Destination Coordinate System
235+
* @param direction transform direction (defaults to ForwardTransform)
236+
* @return transformed rectangle
184237
*/
185238
QgsRectangle transform( const QgsRectangle &rectangle, TransformDirection direction = ForwardTransform ) const;
186239

187-
/** Transform an array of coordinates to a different Coordinate System
188-
* If the direction is ForwardTransform then coordinates are transformed from layer CS --> map canvas CS,
189-
* otherwise points are transformed from map canvas CS to layerCS.
240+
/** Transform an array of coordinates to the destination CRS.
241+
* If the direction is ForwardTransform then coordinates are transformed from source to destination,
242+
* otherwise points are transformed from destination to source CRS.
190243
* @param numPoint number of coordinates in arrays
191244
* @param x array of x coordinates to transform
192245
* @param y array of y coordinates to transform
193246
* @param z array of z coordinates to transform
194-
* @param direction TransformDirection (defaults to ForwardTransform)
195-
* @return QgsRectangle in Destination Coordinate System
247+
* @param direction transform direction (defaults to ForwardTransform)
196248
*/
197249
void transformCoords( int numPoint, double *x, double *y, double *z, TransformDirection direction = ForwardTransform ) const;
198250

0 commit comments

Comments
 (0)
Please sign in to comment.