Add moon phase calculations

doc/source/api.rst

@@ -0,0 +1,25 @@
+
+API
+---
+
+Orbital computations
+~~~~~~~~~~~~~~~~~~~~
+
+.. automodule:: pyorbital.orbital
+   :members:
+   :undoc-members:
+
+TLE handling
+~~~~~~~~~~~~
+
+.. automodule:: pyorbital.tlefile
+   :members:
+   :undoc-members:
+
+Astronomical computations
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. automodule:: pyorbital.astronomy
+   :members:
+   :undoc-members:
+

doc/source/astronomy.rst

@@ -0,0 +1,12 @@
+Computing astronomical parameters
+---------------------------------
+The astronomy module enables computation of certain parameters of interest for
+satellite remote sensing for instance the Sun-zenith angle:
+
+    >>> from pyorbital import astronomy
+    >>> from datetime import datetime
+    >>> utc_time = datetime(2012, 5, 15, 15, 45)
+    >>> lon, lat = 12, 56
+    >>> astronomy.sun_zenith_angle(utc_time, lon, lat)
+    62.685986438071602
+

doc/source/conf.py

@@ -22,14 +22,16 @@
 sys.path.insert(0, os.path.abspath('../../pyorbital'))
 from pyorbital.version import __version__
 
-# -- General configuration -----------------------------------------------------
+# -- General configuration -----------------------------------------------
 
 # If your documentation needs a minimal Sphinx version, state it here.
 #needs_sphinx = '1.0'
 
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.coverage']
+#extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.coverage', "sphinxtogithub"]
+extensions = [
+    'sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.coverage']
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['.templates']
@@ -45,7 +47,7 @@
 
 # General information about the project.
 project = u'pyorbital'
-copyright = u'2012-2015, The Pytroll crew'
+copyright = u'2012-2016, The Pytroll crew'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
@@ -91,7 +93,7 @@
 #modindex_common_prefix = []
 
 
-# -- Options for HTML output ---------------------------------------------------
+# -- Options for HTML output ---------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
@@ -124,7 +126,7 @@
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['.static']
+html_static_path = ['../_static']
 
 # If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
 # using the given strftime format.
@@ -171,7 +173,7 @@
 htmlhelp_basename = 'pyorbitaldoc'
 
 
-# -- Options for LaTeX output --------------------------------------------------
+# -- Options for LaTeX output --------------------------------------------
 
 # The paper size ('letter' or 'a4').
 #latex_paper_size = 'letter'
@@ -210,7 +212,7 @@
 #latex_domain_indices = True
 
 
-# -- Options for manual page output --------------------------------------------
+# -- Options for manual page output --------------------------------------
 
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).

doc/source/index.rst

@@ -21,16 +21,8 @@ TLE files
 ---------
 Pyorbital has a module for parsing NORAD TLE-files
 
-    >>> from pyorbital import tlefile
-    >>> tle = tlefile.read('noaa 18', '/path/to/my/tle_file.txt')
-    >>> tle.inclination
-    99.043499999999995
 
-If no path is given pyorbital tries to read the earth observation TLE-files from celestrak.com
-
-Computing satellite postion
----------------------------
-The orbital module enables computation of satellite position and velocity at a specific time:
+.. _github: http://github.com/pytroll/pyorbital
 
     >>> from pyorbital.orbital import Orbital
     >>> from datetime import datetime
@@ -71,49 +63,21 @@ If we take a TLE from one week earlier we get a slightly different result:
     (104.1539184988462, 79.328272480878141, 838.81555967963391)
 
 
+>>>>>>> master
 
-Computing astronomical parameters
----------------------------------
-The astronomy module enables computation of certain parameters of interest for satellite remote sensing for instance the Sun-zenith angle:
-
-    >>> from pyorbital import astronomy
-    >>> from datetime import datetime
-    >>> utc_time = datetime(2012, 5, 15, 15, 45)
-    >>> lon, lat = 12, 56
-    >>> astronomy.sun_zenith_angle(utc_time, lon, lat)
-    62.685986438071602
-
-API
----
-
-Orbital computations
-~~~~~~~~~~~~~~~~~~~~
-
-.. automodule:: pyorbital.orbital
-   :members:
-   :undoc-members:
-
-TLE handling
-~~~~~~~~~~~~
-
-.. automodule:: pyorbital.tlefile
-   :members:
-   :undoc-members:
-
-Astronomical computations
-~~~~~~~~~~~~~~~~~~~~~~~~~
-
-.. automodule:: pyorbital.astronomy
-   :members:
-   :undoc-members:
+.. toctree::
+   :maxdepth: 2
 
+   tle
+   satellite_position
+   astronomy
+   moon_calculations
+   api
+
 
-.. Contents:
-   .. toctree::
-      :maxdepth: 2
-   Indices and tables
-   ==================
-   * :ref:`genindex`
-   * :ref:`modindex`
-   * :ref:`search`
+Indices and tables
+==================
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
 

doc/source/moon_calculations.rst

@@ -0,0 +1,81 @@
+Moon phase and position with Pyorbital
+======================================
+
+It is possible to calculate the phase and position of the moon at any given
+time in the past or future. This is done by an implementation of the
+astronimical methods described at Stjaernhimlen_. The calculations have been
+compared to the pyephem library, and deviations are small, see below.
+
+
+Computing the phase of the moon
+-------------------------------
+
+  >>> from datetime import datetime
+  >>> from pyorbital.moon_phase import moon_phase
+  >>> time_t = datetime(2011, 12, 1, 12)
+  >>> print moon_phase(time_t)
+  0.409752921579
+
+It works also with datetime sequences:
+
+  >>> import numpy as np
+  >>> from pyorbital.moon_phase import moon_phase
+  >>> time_t = np.arange('2005-02', '2005-03', dtype='datetime64[D]')
+  >>> print moon_phase(time_t)
+  [  6.36537786e-01   5.32201222e-01   4.23413367e-01   3.15141455e-01
+     2.13350898e-01   1.24769455e-01   5.62102473e-02   1.34598103e-02
+     4.68042562e-05   1.64235364e-02   5.99725484e-02   1.25824054e-01
+     2.08064456e-01   3.00824090e-01   3.98939205e-01   4.98161316e-01
+     5.95059508e-01   6.86787971e-01   7.70852355e-01   8.44942289e-01
+     9.06852663e-01   9.54487201e-01   9.85925226e-01   9.99530703e-01
+     9.94086558e-01   9.68941138e-01   9.24152715e-01   8.60612554e-01]
+
+
+Computing the position of the moon
+----------------------------------
+
+  >>> from datetime import datetime
+  >>> from pyorbital import planets
+  >>> time_t = datetime(2016, 7, 30, 0, 0)
+  >>> moon = planets.Moon(time_t)
+  >>> lon = 20.0
+  >>> lat = 65.0
+  >>> rasc, decl, alt, azi = moon.topocentric_position(lon, lat)
+  >>> print alt, azi
+  6.33389454706 61.6795817556
+
+And for an array of longitudes and latitudes:
+
+  >>> import numpy as np
+  >>> lons = np.arange(100).reshape(10,10)
+  >>> lats = np.arange(100).reshape(10,10) * 0.9
+  >>> rasc, decl, alt, azi = moon.topocentric_position(lons, lats)
+  >>> print alt.shape
+  (10, 10)
+  >>> print alt[4,8]
+  14.9564426346
+
+
+Accuracy
+--------
+
+In lack of an absolute truth or reference the moon calclations with Pyorbital
+have been compared to pyephem. There are indeed deviations, but for the moon
+phase they are in general rather small. See image below, where we compare the
+moon phase over 416 days starting from December 1st 2015. As seen from the
+figure the deviations are within 0.3 %.
+
+  .. image:: _static/moonphase_compare.png
+
+For moon height and azimuth differences are larger, as seen from the figures
+below. We have calculated the position of the moon relative to the City of
+Norrköping, Sweden, over four months from March 7, 2012. The deviations are
+within 4 degrees for the height, and within 9 degrees for the azimuth.
+
+
+  .. image:: _static/moonheight_compare.png
+  .. image:: _static/moonazimuth_compare.png
+
+
+
+.. _`Stjaernhimlen`:   http://www.stjarnhimlen.se/comp/ppcomp.html

doc/source/satellite_position.rst

@@ -0,0 +1,17 @@
+
+Computing satellite postion
+---------------------------
+The orbital module enables computation of satellite position and velocity at a
+specific time:
+
+    >>> from pyorbital.orbital import Orbital
+    >>> from datetime import datetime
+    >>> orb = Orbital("noaa 18")
+    >>> now = datetime.utcnow()
+    >>> # Get normalized position and velocity of the satellite:
+    >>> orb.get_position(now)
+    ([0.57529384846822862, 0.77384005228105424, 0.59301408257897559],
+    [0.031846489698768146, 0.021287993461926374, -0.05854106186659274])
+    >>> # Get longitude, latitude and altitude of the satellite:
+    >>> orb.get_lonlatalt(now)
+    (-1.1625895579622014, 0.55402132517640568, 847.89381184656702)

doc/source/tle.rst

@@ -0,0 +1,12 @@
+TLE files
+---------
+Pyorbital has a module for parsing NORAD TLE-files
+
+    >>> from pyorbital import tlefile
+    >>> tle = tlefile.read('noaa 18', '/path/to/my/tle_file.txt')
+    >>> tle.inclination
+    99.043499999999995
+
+If no path is given pyorbital tries to read the earth observation TLE-files
+from celestrak.com
+