Welcome to the Documentation for RMS-NAV!

Introduction

RMS-NAV is a comprehensive navigation system designed for spacecraft imagery processing. It provides tools to analyze images from various space missions (Cassini, Voyager, Galileo, New Horizons) and determine precise positional offsets by comparing observed images with theoretical models of celestial bodies.

Features

Multi-mission support: Works with Cassini, Voyager, Galileo, and New Horizons imagery
Multiple navigation techniques: Star-based, body-based, and rings-based navigation
Automated offset calculation: Determines precise pointing corrections
Visualization tools: Creates annotated images with identified features
Configurable processing: Customizable parameters for different scenarios
PDS4 bundle generation: Creates PDS4-compliant bundles with labels, metadata, and browse products
Backplane generation: Computes per-pixel geometry products (longitude, latitude, angles, etc.)

Installation

Prerequisites

Python 3.10 or higher
SPICE toolkit and kernels for planetary data
Dependencies listed in requirements.txt

Setup

Clone the repository:

git clone https://github.com/SETI/rms-nav.git
cd rms-nav

Create and activate a virtual environment (recommended):

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

Install the required packages:
```
pip install -r requirements.txt
```
Set up SPICE kernels:
- Download the required SPICE kernels for your mission
- Set the SPICE_PATH environment variable to point to your kernels directory:
```
export SPICE_PATH=/path/to/your/spice/kernels
```

Note: To fix mypy operability with editable pip installs:
export SETUPTOOLS_ENABLE_FEATURES="legacy-editable"

Quick Start

Process a single Cassini image using the installed CLI script:

nav_offset coiss N1234567890 \
  --pds3-holdings-root /path/to/pds3 \
  --nav-results-root /path/to/nav_results

Process all Voyager images within a single PDS3 volume:

nav_offset vgiss \
  --volumes VGISS_5101 \
  --pds3-holdings-root /path/to/pds3 \
  --nav-results-root /path/to/nav_results

Generate backplanes for processed images:

nav_backplanes coiss_saturn \
  --nav-results-root /path/to/nav_results \
  --backplane-results-root /path/to/backplane_results \
  --volumes COISS_2001

Generate PDS4 bundle files:

nav_create_bundle labels coiss_saturn \
  --nav-results-root /path/to/nav_results \
  --backplane-results-root /path/to/backplane_results \
  --bundle-results-root /path/to/bundle_results \
  --volumes COISS_2001

Mosaicing

Reproject a set of ring images and combine them into a mosaic:

nav_mosaic_rings coiss_saturn \
  --volumes COISS_2001 \
  --pds3-holdings-root /path/to/pds3 \
  --nav-results-root /path/to/nav_results \
  --planet SATURN \
  --radius-inner 139500 \
  --radius-outer 140220 \
  --output-dir /path/to/mosaic_results \
  --prefix saturn_fring_2004

Display the resulting mosaic (or any individual reprojection file):

nav_mosaic_display_rings /path/to/mosaic_results/saturn_fring_2004_mosaic.fits

Reproject body images (e.g. Mimas):

nav_mosaic_body coiss_saturn \
  --volumes COISS_2001 \
  --pds3-holdings-root /path/to/pds3 \
  --nav-results-root /path/to/nav_results \
  --body-name MIMAS \
  --output-dir /path/to/mosaic_results \
  --prefix mimas_2004

See the Reprojection user guide for full option references and more examples.

Cloud Tasks variants

Each of the main batch drivers above has a queue-driven counterpart suffixed with _cloud_tasks, which reads file lists from a cloud_tasks queue instead of enumerating the dataset locally:

nav_offset_cloud_tasks — navigation offsets
nav_backplanes_cloud_tasks — backplane generation
nav_create_bundle_cloud_tasks — PDS4 bundle labels pass
nav_mosaic_rings_cloud_tasks / nav_mosaic_body_cloud_tasks — mosaic reprojection pass (mosaic combination is run separately via nav_mosaic <mode> --skip-reproject)

These workers accept only the environment flags needed to locate configuration and results roots; the task payload carries the list of files plus any per-task parameters. Each of nav_offset, nav_backplanes, and nav_mosaic_rings / nav_mosaic_body can produce a ready-to-load task-queue JSON file for its matching worker via --output-cloud-tasks-file PATH. The per-feature user guides document the JSON schema each worker expects:

nav_offset_cloud_tasks: Navigation user guide
nav_backplanes_cloud_tasks: Backplanes user guide
nav_mosaic_rings_cloud_tasks / nav_mosaic_body_cloud_tasks: Reprojection user guide

Documentation

Comprehensive documentation is available in the docs directory. To build the documentation:

cd docs
make html

The built documentation will be available in docs/_build/html.

Contributing

Information on contributing to this package can be found in the Contributing Guide.

Licensing

This code is licensed under the Apache License v2.0.