Configuration

RMS-NAV uses a hierarchical YAML-based configuration system that allows you to customize behavior without modifying the source code. Understanding how configuration files are loaded and how to override settings is important for effective use of the system.

Configuration Loading Order

The configuration system loads settings in the following order, with later files overriding earlier ones:

1. Standard Configuration Files: All YAML files in the src/nav/config_files/ directory are loaded in alphabetical order. These files provide default settings for:

   • config_01_general.yaml: General settings including all logging levels

   • config_02_offset.yaml: Offset-finding and star refinement parameters

   • config_03_stars.yaml: Star-model and ring-occlusion parameters

   • config_04_bodies.yaml: Body (planet/moon) rendering parameters

   • config_05_rings.yaml: Ring model parameters

   • config_06_titan.yaml: Titan-specific navigation parameters

   • config_07_bootstrap.yaml: Bootstrap navigation parameters

   • config_10_satellites.yaml: Satellite definitions for each planet

   • config_20_jupiter_rings.yaml: Jupiter ring system parameters

   • config_21_saturn_rings.yaml: Saturn ring system parameters

   • config_22_uranus_rings.yaml: Uranus ring system parameters

   • config_23_neptune_rings.yaml: Neptune ring system parameters

   • config_30_inst_coiss.yaml: Cassini ISS instrument-specific settings

   • config_31_inst_gossi.yaml: Galileo SSI instrument-specific settings

   • config_32_inst_nhlorri.yaml: New Horizons LORRI instrument-specific settings

   • config_33_inst_vgiss.yaml: Voyager ISS instrument-specific settings

   • config_40_sim.yaml: Simulated image settings

   • config_90_backplanes.yaml: Backplane generation settings

   • config_95_pds4.yaml: PDS4 metadata and export settings for generated products, overrides for PDS4 label templates and mapping of internal fields to PDS4 keys

2. User Default Configuration: If present, the file nav_default_config.yaml in the current working directory is loaded. This allows you to set personal defaults that apply to all runs.

3. Command-Line Configuration Files: Any files specified with the --config-file option are loaded in the order specified. These provide the highest priority and can override any previous settings.

Configuration File Structure

Configuration files use YAML format and are organized into sections:

environment:
  nav_results_root: /path/to/results
  pds3_holdings_root: /path/to/pds3

general:
  log_level_model_rings: DEBUG
  log_level_nav_correlate_all: DEBUG

offset:
  correlation_fft_upsample_factor: 128
  star_refinement_enabled: true

bodies:
  min_bounding_box_area: 9
  oversample_maximum: 2

Each section can contain multiple settings. When multiple configuration files define the same setting, the value from the last file loaded takes precedence.

Logging Configuration

All logging levels are set in the general section of config_01_general.yaml. Each key accepts a standard log-level string: DEBUG, INFO, WARNING, ERROR, or CRITICAL.

Main logger (nav_offset – top-level program events):

• general.log_level_main_console (default: INFO): Level for output written to stdout while the program runs.

• general.log_level_main_file (default: INFO): Level for the timestamped logfile written to $NAV_RESULTS_ROOT/logs/nav_offset/.

Image logger (nav_image – per-image processing events, active only while an image is being processed):

• general.log_level_image_console (default: INFO): Level for output written to stdout during image processing.

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

Navigation model loggers:

• general.log_level_model_bodies (default: INFO): Logging level for the body (planet and moon) navigation model.

• general.log_level_model_stars (default: INFO): Logging level for the star navigation model.

• general.log_level_model_rings (default: INFO): Logging level for the ring navigation model.

Navigation technique loggers:

• general.log_level_nav_correlate_all (default: INFO): Logging level for the correlate_all technique, including star refinement.

Annotation:

• general.log_level_annotate (default: ERROR): Logging level for the image annotation step.

Example – enable verbose output for star and ring models while keeping other components at the default level:

general:
  log_level_model_stars: DEBUG
  log_level_model_rings: DEBUG

Creating a User Configuration File

To create your own default configuration:

1. Create a file named nav_default_config.yaml in your working directory

2. Add only the settings you want to override:

   environment:
     nav_results_root: /my/custom/results/path
   
   offset:
     correlation_fft_upsample_factor: 256
   

3. The system will automatically load this file if it exists

Using Command-Line Configuration Overrides

You can override configuration on a per-run basis using --config-file:

nav_offset coiss N1234567890 --config-file /path/to/special_config.yaml

You can specify multiple configuration files, and they will be loaded in order:

nav_offset coiss N1234567890 \
  --config-file base_overrides.yaml \
  --config-file run_specific.yaml

Command-Line Option Overrides

In addition to configuration files, certain command-line options can override configuration settings directly. These options take precedence over all configuration file settings:

Environment Options

• --pds3-holdings-root PATH: Overrides the PDS3_HOLDINGS_DIR environment variable and any environment.pds3_holdings_root configuration setting. This specifies the root directory or URL for PDS3 holdings.

• --nav-results-root PATH: Overrides the NAV_RESULTS_ROOT environment variable and any environment.nav_results_root configuration setting. This specifies the root directory or URL where navigation results will be written.

Navigation Options

• --nav-models LIST: Overrides any default model selection. This is 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: Overrides any default technique selection. This is a comma-separated list of navigation techniques to apply. Valid entries include correlate_all and manual.

Logging Options

All four logging-level options override the corresponding general.* config key for that run. Each accepts a standard log-level string: DEBUG, INFO, WARNING, ERROR, or CRITICAL.

• --log-level-main-console LEVEL: Override general.log_level_main_console – the level at which the main logger writes to stdout.

• --log-level-main-file LEVEL: Override general.log_level_main_file – the level at which the main logger writes to its logfile under $NAV_RESULTS_ROOT/logs/nav_offset/.

• --log-level-image-console LEVEL: Override general.log_level_image_console – the level at which the image logger writes to stdout during image processing.

• --log-level-image-file LEVEL: Override general.log_level_image_file – the level at which the image logger writes to the per-image logfile under $NAV_RESULTS_ROOT/logs/{results_path_stub}.log.

These command-line options provide the highest priority override mechanism, taking precedence over all configuration files, including those specified with --config-file.

Example: Combining Configuration Methods

The following example demonstrates how different configuration methods interact:

1. Default configuration files in src/nav/config_files/ set offset.correlation_fft_upsample_factor: 128

2. User’s nav_default_config.yaml overrides it to 256

3. Command-line --config-file custom.yaml overrides it to 512

4. The final value used is 512

If you also specify --nav-models stars,rings on the command line, this overrides any model selection from configuration files, regardless of what’s in the configuration.