============= 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: .. code-block:: yaml 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: .. code-block:: yaml 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: .. code-block:: yaml 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``: .. code-block:: bash nav_offset coiss N1234567890 --config-file /path/to/special_config.yaml You can specify multiple configuration files, and they will be loaded in order: .. code-block:: bash 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.