================ 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 :doc:`introduction_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: .. code-block:: bash 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): .. code-block:: bash 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/ / / / metadata/ / / _index.lbl _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 :doc:`introduction_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: .. code-block:: bash 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 :doc:`introduction_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. Navigation options ^^^^^^^^^^^^^^^^^^ * ``--nav-models LIST``: a comma-separated list of model names or patterns to enable. Valid entries include ``stars``, ``rings``, ``titan``, and body-specific entries of the form ``body:NAME`` (glob patterns are allowed). * ``--nav-techniques LIST``: a comma-separated list of navigation techniques to apply. Valid entries include ``correlate_all`` and ``manual``. Note: You should typically use only one technique at a time, as they serve different purposes. 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 :doc:`introduction_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: .. code-block:: bash nav_offset coiss N1234567890 To process Voyager images within a single PDS3 volume: .. code-block:: bash nav_offset vgiss --volumes VGISS_5101 To process a New Horizons image list found in a CSV from PDS using the correlate_all technique: .. code-block:: bash 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: .. code-block:: bash 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: .. code-block:: bash 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: .. code-block:: bash 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: .. code-block:: json { "task_id": "--", "data": { "dataset_name": "", "arguments": { "nav_models": ["bodies", "rings", "stars"], "nav_techniques": ["correlate_all"] }, "files": [ { "image_file_url": "", "label_file_url": "", "results_path_stub": "", "index_file_row": {"": "", "...": "..."}, "extra_params": {"": ""} } ] } } 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: .. code-block:: bash 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 :doc:`user_guide_simulated_images`. Navigation Techniques ===================== RMS-NAV supports two navigation techniques that can be selected using the ``--nav-techniques`` command-line option. You should typically use only one technique at a time, as they serve different purposes. correlate_all ------------- The ``correlate_all`` technique performs automated navigation by correlating the observed image with a combined theoretical model. This is the primary automated navigation method. **How it works:** 1. **Model Combination**: The technique first creates a combined model from all available navigation models (stars, bodies, rings, etc.). For each pixel, it selects the model element with the smallest range (closest to the observer), ensuring proper depth ordering. 2. **Correlation**: It uses a pyramid-based correlation algorithm (KPeaks) to find the best match between the observed image and the combined model. The correlation searches for the offset that maximizes the match quality. 3. **Star Refinement** (optional): If star models are available and star refinement is enabled in the configuration, the technique performs a second pass to refine the offset by precisely locating individual stars in the image. This refinement: - Searches for each star's position using the instrument's point spread function (PSF) - Applies photometric gates to reject non-stellar signal (scale/noise, chi-squared, SNR, position error) - Computes the median offset from all successfully located stars - Removes outliers using a robust statistical method - Updates the final offset with the refined value 4. **Validation**: The technique validates that the computed offset is within the extended field of view margins. If the offset is outside these bounds, the technique fails. **Configuration Options:** The following configuration options in ``config_02_offset.yaml`` control the behavior of ``correlate_all``: * ``offset.correlation_fft_upsample_factor`` (default: 128): The upsampling factor used in the FFT-based correlation. Higher values provide finer sub-pixel resolution but increase computation time. * ``offset.star_refinement_enabled`` (default: true): Whether to enable star-based refinement after the initial correlation. * ``offset.star_refinement_nsigma`` (default: 3): The number of standard deviations used to identify outliers during star refinement. * ``offset.star_refinement_search_limit`` (default: [2.5, 2.5]): The search radius in pixels (v, u) when locating individual stars. * ``offset.star_refinement_max_reduced_chi2`` (default: 10.0): Reject PSF fits with reduced chi-squared above this threshold. A high chi-squared indicates the PSF model cannot describe the data, suggesting a non-stellar source. * ``offset.star_refinement_min_reduced_chi2`` (default: 0.1): Reject PSF fits with reduced chi-squared below this threshold. A value near zero indicates the background polynomial has absorbed the signal (overfitting). * ``offset.star_refinement_min_peak_snr`` (default: 5.0): Reject PSF fits with peak signal-to-noise ratio below this value. Low SNR indicates the fit may have locked onto noise or a non-stellar feature. * ``offset.star_refinement_max_pos_err`` (default: 0.5 pixels): Reject PSF fits where the 1-sigma position uncertainty in either axis exceeds this limit. * ``offset.log_star_refinement_detail`` (default: false): Log all fit metrics and gate thresholds per star at DEBUG level. Useful for diagnosing unexpected rejection behavior. * ``general.log_level_nav_correlate_all`` (default: ``INFO``, from ``config_01_general.yaml``): Logging level for this technique. Accepts ``DEBUG``, ``INFO``, ``WARNING``, ``ERROR``, or ``CRITICAL``. **Star conflict strings from refinement:** Stars that fail a gate receive one of the following ``conflicts`` strings and are excluded from offset statistics: * ``REFINEMENT EDGE``: Star is too close to the image edge for PSF fitting. * ``REFINEMENT FAILED``: PSF optimizer returned no result. * ``REFINEMENT NO STAR``: Fit scale at or below the noise floor; no real signal present. * ``REFINEMENT CHI2 LOW``: Reduced chi-squared below minimum; background polynomial overfit the signal. * ``REFINEMENT CHI2``: Reduced chi-squared above maximum; PSF model cannot describe the data. * ``REFINEMENT SNR``: Peak SNR below minimum. * ``REFINEMENT POS_ERR``: Position uncertainty exceeds the maximum. * ``REFINEMENT OUTLIER``: Passed all photometric gates but identified as a spatial outlier by the robust rejection step. **Star ring-plane occlusion:** Before entering the star model or refinement loop, each star is checked against the ring-plane backplane for the observation's closest planet. Stars whose predicted image position falls within a configured opaque ring annulus receive a ``RING: `` conflict string and are excluded from the star model and refinement. Body intercept (``BODY: ``) takes precedence: if a star is already behind a planet or moon the ring check is skipped. The ring annuli are configured per planet under ``stars.ring_occlusion_radii_km``. Each planet maps to a list of ``[inner_km, outer_km]`` pairs. A star is occluded if the sampled ring-plane radius falls inside any pair for that planet. Planets not listed have no ring occlusion. Example from ``config_03_stars.yaml``: .. code-block:: yaml stars: ring_occlusion_enabled: true ring_occlusion_radii_km: SATURN: - [74490.0, 91980.0] # C ring - [91980.0, 117580.0] # B ring - [122170.0, 136780.0] # A ring (Cassini Division excluded) URANUS: - [41837.0, 51149.0] NEPTUNE: - [40900.0, 62933.0] * ``stars.ring_occlusion_enabled`` (default: true): Master switch. Set to ``false`` to disable ring-plane occlusion for all planets. * ``stars.ring_occlusion_radii_km``: Dict mapping uppercase planet names to lists of ``[inner_km, outer_km]`` annulus pairs. Each pair defines a radial range that is treated as opaque. Multiple pairs per planet allow gaps (e.g., the Cassini Division) to remain transparent. **When to use:** * Use ``correlate_all`` for automated batch processing of images * Best for images with clear features (stars, planetary bodies, or rings) * Suitable for both starfield and body-dominated images * Works well when you need consistent, reproducible results **Output:** The technique produces: * A pixel offset (dv, du) indicating the correction needed * Uncertainty estimates (sigma_v, sigma_u) based on the correlation quality and star refinement * Confidence score (typically 1.0 for successful correlations) * Metadata including correlation quality metrics and star refinement statistics manual ------ The ``manual`` technique provides an interactive graphical interface for manually adjusting the navigation offset. This is useful when automated techniques fail or when expert judgment is needed. **How it works:** 1. **Model Combination**: Like ``correlate_all``, the manual technique first creates a combined model from all available navigation models. 2. **Interactive Dialog**: A PyQt6-based dialog window opens showing: * The observed image (science data) * The combined model overlaid on the image * Pan and zoom controls for detailed inspection * Offset adjustment controls (dv, du spin boxes) * An "Auto" button that runs the same correlation algorithm used by ``correlate_all`` 3. **User Interaction**: The user can: * Pan and zoom to examine details * Manually adjust the offset using spin boxes * Click "Auto" to get an automated correlation result as a starting point * Accept or cancel the navigation 4. **Result**: If the user accepts, the manually specified offset is used. The confidence is set to 1.0, and uncertainty is set to None (since it's a manual determination). **Configuration Options:** The manual technique uses the same correlation settings as ``correlate_all`` when the "Auto" button is clicked: * ``offset.correlation_fft_upsample_factor``: Controls the precision of the auto-correlation **When to use:** * Use ``manual`` when automated techniques fail or produce questionable results * Useful for images with poor quality, unusual features, or edge cases * Helpful for expert review and validation of automated results * Required when running in an environment with a display (X11 or similar) **Requirements:** * Requires a graphical display (X11, Wayland, or similar) * Requires PyQt6 to be installed * Not suitable for headless batch processing environments **Output:** The technique produces: * A pixel offset (dv, du) as specified by the user * Confidence score of 1.0 (user-accepted result) * Uncertainty set to None (manual determination) 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: .. code-block:: yaml rings: remove_planet_shadow: true # default When active, the ring model logs the number of masked pixels at ``INFO`` level: .. code-block:: 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: .. code-block:: yaml 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. .. code-block:: yaml 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.