rms-opus

Release	Test Status	Documentation	Coverage

PyPI	Python	Downloads	License

Issues	Pull requests	Activity

Introduction

OPUS is the Outer Planets Unified Search tool of the Ring-Moon Systems Node of NASA's Planetary Data System. It lets a researcher search the Ring-Moon Systems Node's archive by what an observation is -- when it was taken, what instrument took it, what it was pointed at, what ring or surface geometry it covers -- and then retrieve the matching data files. A public instance runs at opus.pds-rings.seti.org.

This distribution holds everything that instance is made of: the pipeline that reads PDS3 volumes and PDS4 bundles and populates the search database, the Django application that serves the web interface and the public API, and the log analyzer that reports on how the site is used. It is published so that the Ring-Moon Systems Node can deploy it and so that the software behind a public archive is inspectable, not because OPUS is a library to build on: the packages carry no API stability guarantees.

Features

• Search by metadata, not by file name -- observation time, target, instrument, wavelength, ring and surface geometry, and hundreds of other fields.
• A public HTTP API returning JSON, CSV or HTML, documented in the API guide, with stable per-observation identifiers meant to stay valid indefinitely.
• An import pipeline that reads PDS3 and PDS4 archives, computes every metadata field, and writes the whole database in one piece: nothing a run produces becomes visible until the run succeeds.
• A schema-driven database -- every table, column, search widget and tooltip comes from checked-in JSON, so adding a metadata field is a schema change rather than a migration.
• A cart and bulk download, building ZIP or TAR archives of the products a search selected.
• A log analyzer that turns Apache access logs into per-session reports of what users actually did.

Installation

rms-opus requires Python 3.12 or later and MySQL 8.0.19 or later. It also needs the MySQL client development headers, because its MySQL driver has no Linux wheel and is compiled during the install:

sudo apt-get install pkg-config default-libmysqlclient-dev build-essential

Then:

pip install rms-opus

OPUS reads one TOML configuration file and has no default location for it: the OPUS_CONFIG environment variable must name the file in the environment of every OPUS process. The installation writes the template to start from, with a comment on every key:

opus_config_template                          # writes ./opus.toml.template
install -m 600 opus.toml.template opus.toml   # then fill in every <PLACEHOLDER>
export OPUS_CONFIG=$PWD/opus.toml

Running the import pipeline needs the PDS holdings mounted. memcached and its pymemcache client are optional and are not installed by pip install rms-opus -- without them OPUS falls back to Django's per-process local-memory cache. The deployment guide covers both.

Quick Start

Import a volume into a fresh database:

export OPUS_CONFIG=/path/to/opus.toml
opus_import --do-it-all COISS_2002

Serve the site against it, from a checkout:

python manage.py migrate     # Django's own tables; OPUS's come from the import
python manage.py runserver   # then open http://127.0.0.1:8000/opus/

From a pip install there is no manage.py; opus_manage is the same program, and OPUS_CONFIG stays the only variable it needs:

opus_manage migrate
opus_manage runserver

Ask the public API how many Cassini ISS observations of Pan there are:

curl 'https://opus.pds-rings.seti.org/opus/api/meta/result_count.json?target=Pan&instrument=Cassini+ISS'

Summarize a day of access logs:

opus_log_analyzer --batch /var/log/apache2/access_log-2026-08-01

Each command has a --help describing the rest of its surface.

Documentation

The full documentation is at rms-opus.readthedocs.io: the public web API guide for people querying an OPUS server, and the developer guide for people working on OPUS itself.

To build it locally, install the docs extra and run Sphinx:

pip install -e ".[docs]"
cd docs && make html

Contributing

See CONTRIBUTING.md, and the code of conduct it points at.

License

Apache License 2.0. See LICENSE.

Supported by BrowserStack

Thanks to BrowserStack for their support of this open-source project.