Better document ST_Azimuth

[strk]

It ain't clear from docs how the return from azumuth is computed. Would be nice to have an example picture too.

angle is computed clockwise from down-to-up: on the clock: 12=0; 3=PI/2; 6=PI; 9=3PI/4

[robe]

Improved at r7011

 http://www.postgis.org/documentation/manual-svn/ST_Azimuth.html

[wrog]

Docs are still partially wrong and the diagram is wrong.

Returns the angle in radians from the horizontal of the vector defined by pointA and pointB.

should be

Returns the angle in radians clockwise from the vertical of the vector at pointA pointing in the direction of pointB.

Also, the gray line in the diagram should be pointing upwards from the center, not to the right, and it might also help if the yellow arc had an arrow pointing clockwise

The "clock" portion of the description is, at least, correct.

(...the problem is, I believe most people would expect this function to behave as diagrammed, with 3 o'clock being zero degress and 12 o'clock being pi/2, or at least that's the way we were all taught in math classes back in high school -- or at least that's the way US schools do it. I've never before seen a from-the-vertical convention for 2D angles; is this a European convention? or did somebody just goof when coding this function in the first place...)

[robe]

wrog,

Your explanation sounds fine to strk. I have too much of a headache thinking about azimuth to have an opinion on the matter. You want to provide a patch for the documentation and we'll apply it? The image was generated with wkt in html/image_src/st_azimuth* files so a bit tricky to add arrows. We can accept an alternative image even if not wkt format -- just keep around the same size.

[strk]

I think the vertical angle comes from true north based navigation systems:  http://en.wikipedia.org/wiki/Azimuth#Navigation

<< Today, the reference plane for an azimuth in a general navigational context is typically true north, measured as a 0° azimuth >>

Would be nice to keep WKT for the image.