Opened 12 years ago

Closed 10 years ago

#876 closed task (fixed)

Better document ST_Azimuth

Reported by: strk Owned by: robe
Priority: medium Milestone: PostGIS 2.0.4
Component: documentation Version: master
Keywords: Cc:

Description

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

Attachments (1)

st_azimuth.patch (6.9 KB ) - added by michischolz 10 years ago.
Patch of documentation for ST_Azimuth

Download all attachments as: .zip

Change History (13)

comment:1 by robe, 12 years ago

Resolution: fixed
Status: newclosed

comment:2 by wrog, 11 years ago

Resolution: fixed
Status: closedreopened

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

comment:3 by robe, 11 years ago

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.

comment:4 by strk, 11 years ago

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.

comment:5 by pramsey, 10 years ago

Milestone: PostGIS 2.0.0PostGIS 2.0.2

comment:6 by robe, 10 years ago

Milestone: PostGIS 2.0.2PostGIS 2.0.3

comment:7 by michischolz, 10 years ago

Resolution: fixed
Status: reopenedclosed

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.

comment:8 by strk, 10 years ago

Resolution: fixed
Status: closedreopened

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 ?

comment:9 by robe, 10 years ago

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.

comment:10 by strk, 10 years ago

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…

comment:11 by michischolz, 10 years ago

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.

by michischolz, 10 years ago

Attachment: st_azimuth.patch added

Patch of documentation for ST_Azimuth

comment:12 by robe, 10 years ago

Resolution: fixed
Status: reopenedclosed

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

Note: See TracTickets for help on using tickets.