ST_Project() doc update

[pcreso]

As per a list discussion with Paul Ramsey, some clarification in the ST_Project() function docs.

The current docs describe an int azimuth as input to determine the direction to propagate a line to fit the output point to. In fact it is the starting direction of a great-circle arc with varying bearing.

Current text:

Name

ST_Project — Returns a POINT projected from a start point using a distance in meters and bearing (azimuth) in radians. Synopsis

geography ST_Project(geography g1, float distance, float azimuth); Description

Returns a POINT projected from a start point using an azimuth (bearing) measured in radians and distance measured in meters.

Distance, azimuth and projection are all aspects of the same operation, describing (or in the case of projection, constructing) the relationship between two points on the world.

The azimuth is sometimes called the heading or the bearing in navigation. It is measured relative to true north (azimuth zero). East is azimuth 90 (pi/2), south is azimuth 180 (pi), west is azimuth 270 (pi*1.5).

The distance is given in meters.

Proposed text

Name

ST_Project — Returns a POINT projected from a start point on a great circle arc using a distance in meters and initial bearing (azimuth) in radians.

Synopsis

geography ST_Project(geography g1, float distance, float azimuth);

Description

Returns a POINT projected along a great circle from a start point using an azimuth (bearing) of the start of the arc measured in radians and distance measured in meters.

Distance, azimuth and projection are all aspects of the same operation, describing (or in the case of projection, constructing) the relationship between two points on the world.

The azimuth is sometimes called the heading or the bearing in navigation. It is measured relative to true north (azimuth zero). East is azimuth 90 (pi/2), south is azimuth 180 (pi), west is azimuth 270 (pi*1.5). This specifies the start azimuth, the actual direction of the line varies along the arc of the great circle line.

The distance is given in meters.

[Mike Taves]

Be aware that the term 'great circle' applies only to spheres, while 'geodesic' applies to both sphere and spheroids.

Also, as the docs have changed since this ticket was submitted, see the SVN version: ​http://postgis.net/docs/manual-dev/ST_Project.html

[pramsey]

Good enough at r13846