Preliminary fix for #387: documenting “spktype21”

requirements.txt

@@ -11,4 +11,5 @@ python-dateutil>=2.5.0
 pytz
 sphinx==1.7.2
 https://github.com/brandon-rhodes/assay/archive/master.zip
+https://github.com/whiskie14142/spktype21/archive/master.zip
 -e .

skyfield/documentation/planets.rst

@@ -215,3 +215,98 @@ at the completion of a ``with`` statement:
 .. testcleanup::
 
    __import__('skyfield.tests.fixes').tests.fixes.teardown()
+
+.. _third-party-ephemerides:
+
+Third-party libraries for other ephemeris formats
+=================================================
+
+If you generate an ephemeris with a tool like NASA’s
+`HORIZONS <https://ssd.jpl.nasa.gov/horizons.cgi>`_ system,
+it might be in a format not yet natively supported by Skyfield.
+The first obstacle to opening the ephemeris
+might be its lack of a recognized suffix:
+
+.. testcode::
+
+    load('wld23593.15')
+
+.. testoutput::
+
+    Traceback (most recent call last):
+      ...
+    ValueError: Skyfield does not know how to open a file named 'wld23593.15'
+
+A workaround for the unusual filename extension
+is to open the file manually using Skyfield’s JPL ephemeris support.
+The next obstacle, however, will be a lack of support
+for Type 21 ephemerides in Skyfield:
+
+.. testcode::
+
+    from skyfield.jpllib import SpiceKernel
+    kernel = SpiceKernel('wld23593.15')
+
+.. testoutput::
+
+    Traceback (most recent call last):
+      ...
+    ValueError: SPK data type 21 not yet supported
+
+Older files with a similar format
+might instead generate the complaint
+“SPK data type 1 not yet supported.”
+
+Happily, thanks to Shushi Uetsuki,
+a pair of third-party libraries exist
+that offer preliminary support for Type 1 and Type 21 ephemerides!
+
+* https://pypi.org/project/spktype01/
+* https://pypi.org/project/spktype21/
+
+Their documentation already includes examples of generating raw coordinates,
+but many Skyfield users will want to use them
+in conjunction with standard Skyfield methods like ``observe()``.
+To integrate them with the rest of Skyfield,
+you will want to define a new vector function class
+that calls the third-party module to generate coordinates:
+
+.. testcode::
+
+    from skyfield.constants import AU_KM
+    from skyfield.vectorlib import VectorFunction
+    from spktype21 import SPKType21
+
+    t = ts.utc(2020, 6, 9)
+
+    eph = load('de421.bsp')
+    earth = eph['earth']
+
+    class Type21Object(VectorFunction):
+        def __init__(self, kernel, target):
+            self.kernel = kernel
+            self.center = 0
+            self.target = target
+
+        def _at(self, t):
+            k = self.kernel
+            r, v = k.compute_type21(0, self.target, t.whole, t.tdb_fraction)
+            return r / AU_KM, v / AU_KM, None, None
+
+    kernel = SPKType21.open('wld23593.15')
+    chiron = Type21Object(kernel, 2002060)
+
+    ra, dec, distance = earth.at(t).observe(chiron).radec()
+    print(ra)
+    print(dec)
+
+.. testoutput::
+
+    00h 27m 38.99s
+    +05deg 57' 08.9"
+
+Hopefully this third-party support
+for Type 1 and Type 23 SPK ephemeris segments
+will be sufficient for projects that need them,
+until there is time for a Skyfield contributor
+to integrate such support into Skyfield itself.

skyfield/documentation/positions.rst

@@ -111,8 +111,8 @@ or else by generating a whole series of positions.
 
 **The planets**
   The eight planets and Pluto are all supported,
-  thanks to the excellent work of the Jet Propulsion Laboratory (JPL)
-  and Skyfield’s support for their major solar system ephemerides.
+  thanks to the excellent work of the Jet Propulsion Laboratory (JPL).
+  Skyfield supports their major solar system ephemerides.
   :doc:`Read more <planets>`
 
   .. testcode::
@@ -146,6 +146,14 @@ or else by generating a whole series of positions.
     astrometric = boston.at(t).observe(mars)
     apparent = boston.at(t).observe(mars).apparent()
 
+**Small Solar System objects**
+  Work is underway to support comets and asteroids.
+  In the meantime,
+  any Type 1 or Type 21 ephemerides you generate
+  using NASA’s `HORIZONS <https://ssd.jpl.nasa.gov/horizons.cgi>`_ system
+  are supported through third-party libraries;
+  for details, see :ref:`third-party-ephemerides`.
+
 **The stars**
   Stars and other fixed objects with catalog coordinates
   are able to generate their current astrometric position

skyfield/jpllib.py

@@ -186,7 +186,7 @@ class SPICESegment(VectorFunction):
             return object.__new__(ChebyshevPosition)
         if spk_segment.data_type == 3:
             return object.__new__(ChebyshevPositionVelocity)
-        raise ValueError('SPK data type {0} not yet supported segment'
+        raise ValueError('SPK data type {0} not yet supported'
                          .format(spk_segment.data_type))
 
     def __init__(self, ephemeris, spk_segment):