Improve Pyorbital documentation!

[adybbroe]

Pyorbital is very limited documented. For instance it is not clear from the documentation what definitions are used for angles (lons, lats, azimuths etc). -180 to 180 or 0-360.

[simonrp84]

[jumping in here as I saw it on slack]
On this subject, we should also be clear what the azimuth is relative to. I've seen 4 versions:

1. 0 degrees = Satellite is North of observer.
2. 0 degrees = Satellite is South of observer.
3. 0 degrees = Observer is North of satellite.
4. 0 degrees = Observer is South of satellite.

1+4 and 2+3 may seem duplicates, but that's not the case if, say, the satellite is to the East of the observer. In that case, 1) would give an azimuth of 90 and 4) would give an azimuth of -90!

[simonrp84]

Coming back to this issue:
pyorbital.orbital.get_observer_look and pyorbital.astronomy.get_alt_az use different definitions of the angles for azimuth.

The former is returning a value of 180 degrees when the observer is North of the satellite. The latter is returning 0 degrees when the observer is North of the sun.

This is not necessarily wrong, but the documentation should explicitly state what's going on here so that there's no confusion. As an aside, it'd be nice to have a get_view_geometry or something to calculate the azimuth and zenith from the perspective of the satellite - similar to how it's done for the solar geometry but the opposite of what's done for the observer angles.

This comment is partially a reminder in case I have the time to update the docs myself, but no guarantee that'll be soon!

[gerritholl]

Related (closed) issue: #28