🐍 Python package for NAIF WebGeoCalc API

In december 2018, JPL/NAIF announced an experimental API RESTful interface for their new WebGeoCalc server (which make online SPICE calculations). Documentation and JavaScript examples are already available.

This package provides a Python interface to make SPICE calculations through this API.

⚠️ Caution

WebGeoCalc is not design to handle heavy calculation. If you need to make intensive queries, use Spiceypy or SpiceMiner package with locally hosted kernels.

📦 Install

With pip:

$ pip install webgeocalc

With mamba/conda (on conda-forge):

$ mamba install -c conda-forge webgeocalc

🚀 Usage

>>> from webgeocalc import API

>>> API.url
'https://wgc2.jpl.nasa.gov:8443/webgeocalc/api'

>>> API.kernel_sets() # /kernel-sets
[<KernelSetDetails> Solar System Kernels (id: 1),
 ...
 <KernelSetDetails> Cassini Huygens (id: 5),
 ...
 <KernelSetDetails> SPICE Class -- Binary PCK Lesson Kernels (Earth) (id: 39)]

>>> API.bodies(5) # /kernel-sets/{kernelSetId}/bodies
[<BodyData> CASSINI (id: -82),
 ...
 <BodyData> SOLAR SYSTEM BARYCENTER (id: 0)]

>>> API.frames('Cassini Huygens') # /kernel-sets/{kernelSetId}/frames
[<FrameData> CASSINI_SATURN_SKR4N_LOCK (id: -82982),
 ...
 <FrameData> ITRF93 (id: 13000)]

>>> API.instruments('Cassini Huygens') # /kernel-set/{kernelSetId}/instruments
[<InstrumentData> CASSINI_CIRS_RAD (id: -82898),
 ...
 <InstrumentData> CASSINI_SRU-A (id: -82001)]

Prepare calculation payload:

>>> from webgeocalc import Calculation

>>> calc = Calculation(
    kernels = 'Cassini Huygens',
    times = '2012-10-19T08:24:00.000',
    calculation_type = 'STATE_VECTOR',
    target = 'CASSINI',
    observer = 'SATURN',
    reference_frame = 'IAU_SATURN',
    aberration_correction = 'NONE',
    state_representation = 'PLANETOGRAPHIC',
)

>>> calc.payload
{'kernels': [{'type': 'KERNEL_SET', 'id': 5}],
 'times': ['2012-10-19T08:24:00.000'],
 'calculationType': 'STATE_VECTOR',
 'target': 'CASSINI',
 'observer': 'SATURN',
 'referenceFrame': 'IAU_SATURN',
 'aberrationCorrection': 'NONE',
 'stateRepresentation': 'PLANETOGRAPHIC',
 'timeSystem': 'UTC',
 'timeFormat': 'CALENDAR'}

Run calculation:

>>> calc.run()
[Calculation submitted] Status: LOADING_KERNELS (id: 19fd1c05-3bfe-47c7-bd16-28612249ae89)
[Calculation update] Status: COMPLETE (id: 19fd1c05-3bfe-47c7-bd16-28612249ae89)
{'DATE': '2012-10-19 08:24:00.000000 UTC',
 'LONGITUDE': 46.18900522,
 'LATITUDE': 21.26337134,
 'ALTITUDE': 694259.8921163,
 'D_LONGITUDE_DT': 0.00888655,
 'D_LATITUDE_DT': -0.00031533,
 'D_ALTITUDE_DT': 4.77080305,
 'SPEED': 109.34997994,
 'TIME_AT_TARGET': '2012-10-19 08:24:00.000000 UTC',
 'LIGHT_TIME': 2.51438831}

>>> from webgeocalc import AngularSeparation

More details can be found in the docs and in the Jupyter Notebooks.

⚙️ Command Line Interface (cli)

The webgeocalc API can be call directly from the command line interface:

$ wgc-kernels --all
 - Solar System Kernels: (id: 1)
...
 - Cassini Huygens: (id: 5)
...
 - SPICE Class -- Binary PCK Lesson Kernels (Earth): (id: 39)

$ wgc-instruments 'Cassini Huygens' --name ISS
 - CASSINI_ISS_WAC_RAD: (id: -82369)
 - CASSINI_ISS_NAC_RAD: (id: -82368)
 - CASSINI_ISS_WAC: (id: -82361)
 - CASSINI_ISS_NAC: (id: -82360)

$ wgc-state-vector --kernels 5 \
                   --times 2012-10-19T09:00:00 \
                   --target CASSINI \
                   --observer SATURN \
                   --reference_frame IAU_SATURN
API status:
[Calculation submit] Status: COMPLETE (id: 041bf912-178f-4450-b787-12a49c8a3101)

Results:
DATE:
> 2012-10-19 09:00:00.000000 UTC
DISTANCE:
> 764142.63776247
SPEED:
> 111.54765899
X:
> 298292.85744169
Y:
> -651606.58468976
Z:
> 265224.81187627
D_X_DT:
> -98.8032491
D_Y_DT:
> -51.73211296
D_Z_DT:
> -2.1416539
TIME_AT_TARGET:
> 2012-10-19 08:59:57.451094 UTC
LIGHT_TIME:
> 2.54890548

More examples can be found in here.

🧪 Local development and testing

Setup:

pip install -e .
pip install -r tests/requirements.txt -r docs/requirements.txt

Linter:

flake8 setup.py docs/conf.py tests/ webgeocalc/
pylint webgeocalc/ tests/*.py

Pytest:

pytest --cov=webgeocalc/ tests/
pytest --nbval-lax examples/

Docs:

sphinx-build docs docs/_build --color -W -bhtml
sphinx-build docs docs/_build --color -W -bdoctest

📣 Disclaimer

This project is not supported or endorsed by either JPL, NAIF or NASA. The code is provided "as is", use at your own risk.