planetarypy

Python tools for planetary science data access.

Archive reachability

Every registered PDS index URL is probed every six hours. Badges are live — they reflect the archives right now, not whenever this page was published. Full table, including which individual indexes are failing: STATUS.md.

Note for users of v0.32 and earlier (nbplanetary): This version (0.50+) is a ground-up rewrite with a new API. If you need functionality from the previous version, it remains available at github.com/michaelaye/nbplanetary. Features from nbplanetary will be reintegrated over time.

• Free software: BSD-3 license
• Documentation: https://michaelaye.github.io/planetarypy/
• Part of the PlanetaryPy Organisation.

Installation

pip install planetarypy

Instrument packages

As of 0.82.0, the MRO HiRISE and CTX processing code ships separately. It was removed from core and now lives in its own distributions, so each instrument versions independently and a core install stays slim:

pip install planetarypy[hirise]      # or: pip install planetarypy-hirise
pip install planetarypy[ctx]         # or: pip install planetarypy-ctx
pip install planetarypy[instruments] # both

Import paths are unchanged — from planetarypy.instruments.mro.hirise import get_browse keeps working once the package is installed — and the CLI verbs each package provides (hibrowse, hiedr, himos, hitif, ctxqv, ctx-migrate) reappear under their own sections in plp --help.

Index and catalog access for both instruments stays in core and needs no extra install: pds.get_index("mro.ctx.edr"), fetch_product("mro.hirise.edr", ...), plp indexes peek mro.hirise.edr and obsid tab-completion all work from pip install planetarypy alone. What moved out is the processing — browse and EDR download helpers, the JP2→GeoTIFF converter, the ISIS mosaic and calibration pipelines.

Features

PDS Index Retrieval

90+ PDS cumulative index files, auto-downloaded and cached as Parquet:

from planetarypy import pds

df = pds.get_index("mro.ctx.edr")       # 164,103 CTX images as DataFrame
df = pds.get_index("cassini.iss.index")  # 407,299 Cassini ISS images

PDS Catalog

65 missions, 2042 product types from the entire PDS archive:

from planetarypy.catalog import list_missions, list_products, fetch_product

list_missions()              # ['apollo', 'cassini', 'dawn', ...]
list_products("mro.ctx")     # ['edr']

# Download any product by ID
fetch_product("mro.ctx.edr", "P02_001916_2221_XI_42N027W")

Direct data access for 58 product types across 29 instruments on 15 missions.

SPICE Kernels

37 archived missions with date-filtered kernel subsets:

from planetarypy.spice import archived_kernels as ak

mk = ak.get_metakernel_and_files("mro", start="2024-01-01", stop="2024-01-31")

Command-Line Interface

plp fetch mro.ctx.edr P02_001916_2221_XI_42N027W   # download a product
plp indexes peek mro.hirise.edr                     # inspect an index
plp catalog build                                   # build catalog DB

With the instrument packages installed (see above), their verbs join the same app:

plp hibrowse PSP_003092_0985_RED    # HiRISE browse JPEG   [planetarypy-hirise]
plp hiedr PSP_003092_0985_RED       # HiRISE EDR channels  [planetarypy-hirise]
plp hitif ESP_081720_2650_RED.JP2   # JP2 → IAU GeoTIFF    [planetarypy-hirise]
plp ctxqv J05_046771_1950           # CTX quickview        [planetarypy-ctx]

General scope

First and foremost this package provides support in working with planetary science data.

With working we mean:

• locating
• retrieving
• reading
• further processing

of data.

Locating

This library manages, via its PDS tools, 90+ PDS3 index files per instrument that can be used for identifying data of interest. These index files are automatically downloaded and converted to the very performant (and cloud-ready) parquet file format. Parquet is able to store advanced datatypes like nan-capable integer and full datetime objects, as opposed to HDF5.

The PDS Catalog module provides a searchable database of 65 missions, 2042 product types, built from the pdr-tests repository into a local DuckDB database.

Retrieving

The interface to getting data is via fetch_product() based on a dotted product key and a PDS product ID. Files are cached locally — subsequent calls for the same product are no-ops. On success, a DownloadedProduct dataclass is returned bundling everything the caller typically needs: the local folder, the absolute paths of every file written, and a convenience pointer to the PDS label file.

from planetarypy.catalog import fetch_product

result = fetch_product("mro.ctx.edr", "P02_001916_2221_XI_42N027W")

result.local_dir   # PosixPath('.../mro/ctx/edr/P02_001916_2221_XI_42N027W')
result.files       # [PosixPath('.../*.IMG'), PosixPath('.../*.LBL')]
result.label_file  # PosixPath('.../*.LBL')  (or None if no label)
result.product_id  # 'P02_001916_2221_XI_42N027W'  (canonical, post-normalization)

Direct data access is currently supported for 58 product types across 29 instruments on 15 missions, resolved via PDS cumulative index files.

Reading

DownloadedProduct.files and .label_file give you ready-to-open paths; .local_dir is there for tools that want a folder. The Planetary Data Reader (pdr) can be used to read most PDS3 and PDS4 products into memory.

Further processing

In the future, additional frequently used procedures will be added to this library, e.g.

• frequently used GDAL/rasterio procedures
• frequently used SPICE operations, e.g. surface illumination on a given body

Project History

This project evolved through several iterations, each building on lessons learned.

Origins: planetarypy (2015-2020)

The original planetarypy was a private collection of planetary science tools created by K.-Michael Aye, inspired by the organizational approach of astropy. Key features included NASA factsheet parsing, PDS index tools for Cassini ISS and MRO CTX, SPICE kernel management, and Mars-specific image processing.

Evolution: nbplanetary (2021-2025)

The project was rewritten using nbdev (notebook-driven development), significantly expanding to include full instrument modules (CTX, HiRISE, UVIS, CISS, Diviner), ISIS integration via kalasiris, Dask-based parallel processing, and CLI tools.

Current Focus (2025-present)

The current planetarypy represents a deliberate refocusing on core functionality. Rather than maintaining all features, the goal is to provide fewer features that work reliably and are well-documented. Advanced features from previous iterations may be reintroduced as the core stabilizes.

See CHANGELOG.md for detailed version history.

Development Installation

git clone https://github.com/planetarypy/planetarypy.git
cd planetarypy
pip install -e ".[dev]"

Contributing

Feedback, issues, and contributions are always gratefully welcomed. See the Contributing Guide for details on how to help and set up a development environment.