Installation and setup

Supported Python versions

rms-metadata-tools requires Python 3.11 or later and is tested on Python 3.11, 3.12, and 3.13. It runs on Linux, macOS, and Windows.

Prerequisites

The geometry stage computes quantities from SPICE through the rms-oops library. Generating geometry tables therefore requires:

The SPICE kernels for the spacecraft and bodies in your collection, installed where oops can find them. The host’s initialization step (for example oops.hosts.galileo.ssi.initialize()) loads them.
The data volume tree and the project-supplied corrected index files for the collection.

The index stage needs only the PDS3 data labels and the corrected index file; it does not require SPICE.

Installation

The package and its runtime dependencies are published on PyPI as rms-metadata-tools:

pip install rms-metadata-tools

To work from a checkout (recommended when you are adding or modifying a host configuration, since the runnable host scripts live in the source tree):

git clone https://github.com/SETI/rms-metadata-tools.git
cd rms-metadata-tools
python -m venv venv
source venv/bin/activate
pip install -e ".[dev]"

The optional dependency groups are:

dev: Linting, type-checking, test, and documentation tooling (ruff, mypy, pytest, pymarkdownlnt, Sphinx, and others). Includes the docs group.
docs: Sphinx and the extensions needed to build this documentation.
cloud: rms-cloud-tasks and its dependencies, required only to run the distributed *_cloud.py workers (see Distributed (cloud) runs).

Install a group with, for example, pip install -e ".[cloud]".

Environment variables

The programs do not read any environment variable directly. Instead, every path argument is expanded for environment variables before use ($NAME and ${NAME} are both honored, and gs:// / s3:// URI prefixes are preserved). This lets you keep the locations of your trees in the environment and pass them symbolically on the command line.

The conventional variables used throughout this guide and in the host scripts’ examples are:

Variable	Meaning
`RMS_VOLUMES`	Root of the data volume tree (the PDS3 data products and their labels).
`RMS_METADATA`	Root of the metadata tree that holds the project-supplied corrected index files (the input to the index stage).
`RMS_METADATA_TEST`	Root of the output tree in which generated tables and labels are written. Point this at `RMS_METADATA` to write in place.

The test suite additionally reads RMS_METADATA and RMS_VOLUMES at import time (see Environment setup). The check-runner script honors VENV / VENV_PATH to locate the virtual environment.

You are free to use any variable names you like; these are only conventions.

Directory layout

The programs walk a volume tree: a collection directory (named for the PDS volume set, e.g. GO_0xxx) containing one subdirectory per volume (e.g. GO_0017). A typical layout is:

$RMS_VOLUMES/
  GO_0xxx/                     # collection (volume set)
    GO_0017/                   # one volume
      <data products and PDS3 .LBL files, in subdirectories>
    GO_0018/
    ...

$RMS_METADATA/
  GO_0xxx/
    GO_0017/
      GO_0017_index.tab        # project-supplied corrected index + label
      GO_0017_index.lbl
    ...

$RMS_METADATA_TEST/            # output tree (may equal $RMS_METADATA)
  GO_0xxx/
    GO_0017/
      GO_0017_supplemental_index.tab   # written by the index stage
      GO_0017_supplemental_index.lbl
      GO_0017_sky_summary.tab          # written by the geometry stage
      GO_0017_body_summary.tab
      GO_0017_ring_summary.tab
      GO_0017_inventory.csv
      ...
    GO_0999/                           # cumulative output directory
      GO_0999_supplemental_index.tab   # written by the cumulative stage
      ...

A volume is recognized by matching its name against a glob derived from the collection name (GO_0xxx becomes GO_0[0-9][0-9][0-9]). The cumulative stage writes into a dedicated volume-like directory (GO_0999 for Galileo SSI) that is excluded from the per-volume stages.

Running the programs

The package does not install console scripts. Each collection has its own set of runnable entry-point scripts in its host directory under src/metadata_tools/hosts/<HOST>/. Because those scripts import their configuration as top-level modules (import host_config, import index_config, import geometry_config), they resolve only when the current working directory is the host directory. Always cd into the host directory first:

cd src/metadata_tools/hosts/GO_0xxx
python GO_0xxx_index.py "$RMS_VOLUMES/GO_0xxx/" "$RMS_METADATA/GO_0xxx/" \
    "$RMS_METADATA_TEST/GO_0xxx/"

A quick smoke test that generates one image’s worth of metadata for a single volume is shown in Examples.