Image Navigation

Introduction

RMS-NAV is a spacecraft image navigation system designed to analyze images from various space missions and determine precise positional offsets. This guide explains how to use the primary command-line interface exposed by the nav_offset script to navigate images and generate results, and how to invoke the cloud-tasks variant for queue-driven processing.

Purpose of the System

The primary purpose of RMS-NAV is to determine the precise pointing of spacecraft instruments by comparing the observed images with theoretical models of what should appear in the field of view. This process, known as “navigation,” is crucial for:

  1. Validating and correcting spacecraft pointing information

  2. Ensuring accurate scientific interpretations of the imagery

  3. Creating properly annotated and labeled images for analysis

  4. Supporting mission planning and operations

The system works by:

  1. Reading spacecraft imagery and metadata

  2. Generating theoretical models of stars, planets, moons, and rings

  3. Correlating the observed features with the theoretical models

  4. Calculating the offset between the expected and actual pointing

  5. Producing annotated images and data files with the results

Supported Missions

RMS-NAV currently supports multiple instruments, organized by dataset names you will pass on the command line. Dataset names are case-insensitive and map to instrument-specific handlers. The complete set is:

  • coiss and coiss_pds3 — Cassini Imaging Science Subsystem (all volumes)

  • coiss_cruise and coiss_cruise_pds3 — Cassini Imaging Science Subsystem (Cruise volumes 1001-1009)

  • coiss_saturn and coiss_saturn_pds3 — Cassini Imaging Science Subsystem (Saturn volumes 2001-2116)

  • gossi and gossi_pds3 — Galileo Solid State Imager

  • nhlorri and nhlorri_pds3 — New Horizons Long Range Reconnaissance Imager

  • vgiss and vgiss_pds3 — Voyager Imaging Science Subsystem

  • sim — simulated images

Installation and Setup

See Overview for package installation with pip or pipx.

Environment Setup

In addition to installing the package, the following external resources are needed at runtime.

SPICE kernels. Download the SPICE kernels required for your mission and set SPICE_PATH to the directory that contains them:

export SPICE_PATH=/path/to/your/spice/kernels

PDS3 holdings. For PDS3 datasets (all currently supported missions), set PDS3_HOLDINGS_DIR to the root of a PDS3 holdings tree (or pass --pds3-holdings-root on the command line):

export PDS3_HOLDINGS_DIR=/path/to/your/pds3/data

The holdings tree follows the layout used by the PDS Ring-Moon Systems Node:

$PDS3_HOLDINGS_DIR/
    volumes/
        <volume_set>/
            <volume>/
                <data directories>/
    metadata/
        <volume_set>/
            <volume>/
                <volume>_index.lbl
                <volume>_index.tab

Remote holdings are supported: PDS3_HOLDINGS_DIR and --pds3-holdings-root accept any URL understood by filecache.FCPath (for example https://pds-rings.seti.org/holdings).

Configuration System

RMS-NAV uses a hierarchical YAML-based configuration system. For detailed information about the configuration system, including its structure, default YAML files, and how to override settings using configuration files and command-line options, see Configuration.

Command-Line Interface

Basic Usage

The main entry point for RMS-NAV is the nav_offset script installed via pyproject.toml. The basic syntax is:

nav_offset DATASET_NAME [options]

Where DATASET_NAME is one of the supported names listed in the “Supported Missions” section. Names are case-insensitive (for example, COISS and coiss are equivalent).

Command-Line Arguments

The command-line interface groups options by purpose. Environment options control configuration sources and output roots. Navigation options select which models or techniques to run. Output options determine whether to write artifacts locally or to produce a cloud-tasks description instead of processing. Dataset selection options are provided by each dataset type: PDS3 datasets expose volume and image filters. A single profiling toggle is available for performance analysis.

Environment options

  • --config-file PATH (repeatable): one or more configuration file paths to override defaults. See Configuration for details.

  • --pds3-holdings-root PATH: root directory or URL for PDS3 holdings, overriding both the PDS3_HOLDINGS_DIR environment variable and any corresponding configuration setting.

  • --nav-results-root PATH: root directory or URL where navigation results will be written, overriding both the NAV_RESULTS_ROOT environment variable and any corresponding configuration setting.

Output options

  • --output-cloud-tasks-file PATH: write a JSON file describing tasks for all selected images suitable for a cloud-tasks queue, and exit without performing navigation.

  • --dry-run: print the images that would be processed without performing navigation.

  • --no-write-output-files: perform navigation but do not write any output files.

Dataset selection (PDS3 datasets)

For PDS3 datasets (coiss, coiss_pds3, coiss_cruise, coiss_cruise_pds3, coiss_saturn, coiss_saturn_pds3, gossi, gossi_pds3, nhlorri, nhlorri_pds3, vgiss, vgiss_pds3), the following options control which images are selected. All filters combine with logical AND, and explicit lists restrict the search domain before range filters to improve performance.

  • img_name (positional, repeatable): specific image name(s) to process.

  • --first-image-num N: minimum image number (inclusive).

  • --last-image-num N: maximum image number (inclusive).

  • --volumes NAME[,NAME...] (repeatable): one or more complete PDS3 volume names; you may pass comma-separated values or specify the option multiple times.

  • --first-volume NAME: starting PDS3 volume; only that volume and chronologically later ones are processed.

  • --last-volume NAME: ending PDS3 volume; only that volume and chronologically earlier ones are processed.

  • --image-filespec-csv FILE (repeatable): CSV file(s) containing PDS3 file specifications; files must include a header column named Primary File Spec or primaryfilespec.

  • --image-file-list FILE (repeatable): file(s) containing file specifications or names, one per line; lines beginning with # are ignored.

  • --choose-random-images N: choose a random subset of N images that meet the other criteria.

Miscellaneous

  • --profile / --no-profile: enable or disable runtime profiling (default is disabled).

Logging options

All four options accept a standard log-level string (DEBUG, INFO, WARNING, ERROR, or CRITICAL) and override the corresponding general.* configuration key for that run. For full details and the config-file equivalents see Configuration.

  • --log-level-main-console LEVEL: stdout level for the main logger (overrides general.log_level_main_console; default INFO).

  • --log-level-main-file LEVEL: logfile level for the main logger written to $NAV_RESULTS_ROOT/logs/nav_offset/ (overrides general.log_level_main_file; default INFO).

  • --log-level-image-console LEVEL: stdout level for the image logger, active only while each image is being processed (overrides general.log_level_image_console; default INFO).

  • --log-level-image-file LEVEL: level for the per-image logfile written to $NAV_RESULTS_ROOT/logs/{results_path_stub}.log (overrides general.log_level_image_file; default INFO).

Example Commands

To process a single Cassini image by specifying its name explicitly and using the default navigation technique:

nav_offset coiss N1234567890

To process Voyager images within a single PDS3 volume:

nav_offset vgiss --volumes VGISS_5101

To process a New Horizons image list found in a CSV from PDS using the correlate_all technique:

nav_offset nhlorri --image-filespec-csv /path/to/nhlorri.csv --nav-techniques correlate_all

To choose ten random Cassini images between two volumes and perform a dry run:

nav_offset coiss --first-volume COISS_2001 --last-volume COISS_2010 --choose-random-images 10 --dry-run

To generate a cloud-tasks JSON file for images across two Voyager volumes without processing:

nav_offset vgiss --volumes VGISS_5101 --volumes VGISS_5102 --output-cloud-tasks-file tasks.json

Cloud-tasks entry point

Queue-driven processing is supported by nav_offset_cloud_tasks. This variant reads tasks from a queue and processes each batch of files described by the task payload. It accepts the same environment options used to derive configuration and results roots and does not include dataset selection flags because the task provides the list of files. Invoke it with:

nav_offset_cloud_tasks [--config-file PATH] [--nav-results-root PATH]

Cloud-tasks JSON schema

The file produced by --output-cloud-tasks-file is a JSON array of task objects. Each task is:

{
    "task_id": "<dataset_name>-<label_file_name>-<index>",
    "data": {
        "dataset_name": "<dataset_name>",
        "arguments": {
            "nav_models": ["bodies", "rings", "stars"],
            "nav_techniques": ["correlate_all"]
        },
        "files": [
            {
                "image_file_url": "<path or URL to image file>",
                "label_file_url": "<path or URL to label file>",
                "results_path_stub": "<relative stub used to name outputs>",
                "index_file_row": {"<column>": "<value>", "...": "..."},
                "extra_params": {"<key>": "<value>"}
            }
        ]
    }
}

Fields:

  • task_id: unique string identifier built from the dataset name, the first image’s label filename, and the enumeration index.

  • data.dataset_name: one of the supported dataset names.

  • data.arguments: an object with optional keys nav_models and nav_techniques (each a list of strings, or null).

  • data.files: one or more file descriptors with required fields image_file_url, label_file_url, and results_path_stub, and optional index_file_row (metadata from the source index file, may be null) and extra_params (arbitrary key/value dictionary forwarded to the task implementation; optional, may be null or omitted).

Inputs and Outputs

Input Files

The primary input to RMS-NAV is spacecraft imagery. The system supports:

  • PDS3 formatted image files (.IMG)

  • Associated metadata (labels, SPICE kernels)

The system requires access to:

  1. The raw image data

  2. SPICE kernels for the appropriate mission and time period

  3. Configuration settings (optional, defaults are provided)

Output Files

RMS-NAV generates two types of output files:

Metadata Files (*_metadata.json)

These JSON files contain the navigation results, including:

  • The calculated pointing offset (dv, du)

  • Uncertainty estimates (sigma_v, sigma_u)

  • Confidence scores

  • Metadata about the navigation process

  • Status information (success, error, etc.)

  • Technique-specific metadata

  • Timestamps

Summary PNG Files (*_summary.png)

These are annotated images showing:

  • The original image data

  • Overlaid model features (stars, rings, bodies)

  • Text annotations

  • Scale information

  • Navigation offset information

Interpreting Results

The key information in the results is:

  1. Offset Values: The u,v pixel offsets that should be applied to the nominal pointing to match the observed features

  2. Correlation Quality: How well the models matched the observed features

  3. Annotations: Identifications of specific features in the image

  4. Status: Whether the navigation was successful, and if not, why

Simulated Images

RMS-NAV supports simulated images created with the nav_create_simulated_image GUI. Simulated images share the same navigation pipeline as real images; they are selected by passing the sim dataset name and a path to the JSON parameter file on the command line:

nav_offset sim /path/to/simulated_image.json

For a full description of the GUI, the JSON parameter file structure, and every supported field, see Simulated Images.

Ring Navigation Model

The ring navigation model generates theoretical brightness profiles for planetary ring edges. Two configuration options in config_05_rings.yaml control whether ring pixels that lie in shadow are excluded from the model before navigation is performed.

Planet shadow removal

When a planet casts a shadow across part of its own ring system, those ring arcs appear dark in the image. If the model still shows those arcs as bright, the navigator will try to align a bright model against a dark image region, which introduces a systematic pointing error.

The rings.remove_planet_shadow option (default true) instructs the ring model to zero out all ring pixels that fall inside the planet’s own shadow:

rings:
  remove_planet_shadow: true   # default

When active, the ring model logs the number of masked pixels at INFO level:

Planet shadow removal: 1284 pixel(s) inside SATURN shadow will be masked

If the shadow geometry cannot be computed for a particular observation (for example, because the illumination geometry is degenerate), a warning is logged and the full unmasked ring model is used instead. Navigation proceeds normally; no output files are suppressed.

To disable shadow removal entirely – for example, to compare navigation quality with and without the mask – set the option to false in a --config-file override:

rings:
  remove_planet_shadow: false

Body shadow removal (future)

The rings.remove_body_shadows option (default false) is reserved for a future enhancement that will remove ring pixels shadowed by moons. Setting it to true has no effect in the current release.

rings:
  remove_body_shadows: false   # default; not yet implemented

Troubleshooting

Common Issues

If SPICE kernels are missing, ensure that all required kernels are available and that environment variables and configuration files point to valid paths. For PDS3 inputs, verify the files conform to expected formats. In cases where no features are found or correlations are weak, check image quality, adjust the selected models or techniques, or limit processing to images known to contain suitable features. Use --dry-run to validate selection criteria without performing full processing.

Getting Help

If you encounter persistent issues:

Review logs for detailed errors, consult the developer documentation for architectural context, and provide the command line, log snippets, and representative input data when asking for support.