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
or, with conda:
conda install -c conda-forge planetarypy
The conda package bundles the SPICE support (spiceypy, scipy) that pip keeps
behind the [spice] extra, since conda has no extras mechanism.
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.
1 maintainer
Release files for planetarypy 0.84.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| planetarypy-0.84.1.tar.gz | 358.9 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| planetarypy-0.84.1-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 627.5 kB
Release files / planetarypy-0.84.1.tar.gz
| Download URL | planetarypy-0.84.1.tar.gz |
|---|---|
| Size | 358.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
df2d25e7754706d72ed4579612020e284b771eaba6845bfb9f01baae6620878a
|
|
BLAKE2b-256 checksum How to use checksums |
f58cafa57997ed6ebc4cd0e5243764684151cfa5e68db49b505ef319b8a14788
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.2
|
Release files / planetarypy-0.84.1-py3-none-any.whl
| Download URL | planetarypy-0.84.1-py3-none-any.whl |
|---|---|
| Size | 268.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
9fec397566eddc859c3929da56e2b6d741da2c04415afd5bc8ebfcf27a0a9a48
|
|
BLAKE2b-256 checksum How to use checksums |
a403ea2117d26c37c1c6549886a0073262e42d3316979e805ddccb130a3e3877
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.2
|
