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

1. Clone the repository:

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

2. Create and activate a virtual environment (recommended):

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

3. Install the required packages:

   pip install -r requirements.txt

4. 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.