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.

[michischolz]

Hey. Nothing more frustrating than a partly correctly documented function with wrong figures. Then it's better to leave out the figures at all. My patch fixes these fancy figures including arrows Further I corrected and cleaned the documentation and replaced "clockwise from down-to-up" with simply "clockwise" because that's all we need to know about in which direction to calculate the angle.

[strk]

The ticket needs to remain open until the patch is committed. About "down-to-up", it's needed to determine where the counter starts. Which side is an azimuth of 0 ? Is horizontal 90 and 270 or 0 and 180 ?

[robe]

strk,

Can we apply the patch. Sorry I'm really directionally challenged (my pain intellectual Achilles heel). So If what he has looks okay to you apply or I can apply.

[strk]

robe: you decide, you're the doc master. I'm fine as long as the "on-the-clock" numbers are there (they are, but the "clock" reference has been removed which I think makes it harder to read). I confirm the "down to up" part was broken in that 12 on the clock is 0, so it starts from the top, not the bottom…

[michischolz]

Ok, I see the "down-to-up"-issue. It is rather "up-to-down" in this case. I think if we add a reference to the geographic-azimuth-convention ("true north-based azimuth" as strk mentioned ​http://en.wikipedia.org/wiki/Azimuth#Navigation) it should be clear that 0 is north and with "clockwise" you know how to count. I can update the patch accordingly.

[michischolz]

Patch of documentation for ST_Azimuth

[robe]

diagram looks prettier. ​http://postgis.net/docs/manual-2.0/ST_Azimuth.html Applied to 2.0 at r11615 2.1 at r11616 2.2 (trunk) at r11617