Configuration

EOMatch reads all runtime parameters from YAML configuration files. The system uses three layers, each merged on top of the previous:

package defaults          (eomatch/etc/default_config.yaml — do not edit)
     ↓
user config               (~/.config/eomatch/user_config.yaml)
     ↓
per-run override          (passed via --config on any CLI command)

You only need to supply the keys you want to override — everything else falls back to the package defaults.

Initialising the user config

Run eomatch-init once after installation to create your user config:

eomatch-init

This writes a fully-commented template to ~/.config/eomatch/user_config.yaml. Running it again is safe — it will not overwrite an existing file unless you delete it first.

EOMatch also initialises the config automatically on first import, so the file will exist even if you never call eomatch-init explicitly.

Config file sections

STAC catalogue (matchup_catalogue)

Controls where eomatch stores and reads its catalogue. Used by every CLI command and by MatchupCatalogue directly.

matchup_catalogue:
  path: /data/my_catalogue   # root directory for the catalogue on disk
  id: matchup-catalogue      # STAC catalogue ID
  description: Matchup catalogue

path can be omitted from the user config and passed at run time instead (--path on the CLI, or as a constructor argument in Python).

Satellite finder settings

These flat keys are used by Sat2SatMUFinder and the eomatch-find command. They are most naturally placed in a per-run --config file alongside matchup_catalogue.path, though you can set defaults for platforms and collections in your user config if you always work with the same sensor pair.

# Which satellites and collections to match — order must correspond.
platforms: Sentinel-2A, Landsat-9
collections: S2_MSI_L1C, LANDSAT_C2L1

# Search time window (format: "YYYY-MM-DD HH:MM:SS").
start_time: "2023-01-01 00:00:00"
end_time:   "2023-12-31 23:59:59"

# Spatial filter — omit or leave blank to search globally.
min_lat: 45.0
max_lat: 55.0
min_lon: -5.0
max_lon: 10.0

Orbit crossover detection is handled by orbitx. The NetCDF path is resolved in the following priority order:

Option A — per-combo NetCDF files (recommended when working with multiple satellite pairs). Keys use the platform-aware combo ID format produced by _matchup_collection_id():

orbitx_netcdf_files:
  LANDSAT_C2L1-Landsat-9-vs-S2_MSI_L1C-S2A: /path/to/LS9_S2A.nc
  LANDSAT_C2L1-Landsat-8-vs-S2_MSI_L1C-S2B: /path/to/LS8_S2B.nc

Option B — single pre-computed NetCDF (flat fallback; used when no per-combo entry is found in orbitx_netcdf_files):

orbitx_netcdf_path: /path/to/crossovers.nc

Option C — run orbitx from scratch (used when neither A nor B is set):

propagation_sampling_interval: 30     # satellite position step (seconds)
interpolation_sampling_interval: 1    # crossover refinement step (seconds)
space_diff_threshold: 100.0           # max cross-track distance (km)
time_diff_threshold: 1800             # max time difference (seconds)
check_before: false
check_after: false
has_land_ocean_mask: false
custom_satellites:                    # blank for standard TLEs
dump_orbit: false

Scientific dataset reading (read)

Controls how BuildMUDT reads products via eoio. The package defaults request no bands (meas: []) so you must configure this section to get any data out of return_matchup_dataset().

read:
  defaults:
    vars_sel:
      meas: []       # band selection — list of band IDs, or "rgb" sentinel
      aux: []        # auxiliary variables
    read_params:
      use_chunks: false
      metadata_level: true
      save_extracted: false
    processors: {}

  # Per-collection overrides — merged on top of defaults above.
  collections:
    LANDSAT_C2L1:
      vars_sel:
        meas: [B2, B3, B4, B5]
    S2_MSI_L1C:
      vars_sel:
        meas: [B02, B03, B04, B8A]

vars_sel and processors are replaced wholesale at each level; read_params keys are merged individually so you can override a single parameter without losing the rest.

Preview reading (preview.read)

Controls how BuildMUPreview reads products when generating preview images. Kept separate from read so that lightweight preview reads do not affect scientific dataset builds.

The package default requests only the RGB bands with metadata disabled. The "rgb" sentinel is resolved by eoio to the natural-colour bands for each collection (B02/B03/B04 for S2, B2/B3/B4 for Landsat).

preview:
  read:
    defaults:
      vars_sel:
        meas: rgb     # must be a string, not a list
        aux: []
      read_params:
        use_chunks: false
        metadata_level: false
        save_extracted: false
      processors: {}
    collections: {}

Per-run config files

All CLI commands accept --config PATH to load an additional YAML file on top of your user config. This is the recommended way to supply run-specific settings (time range, platforms, catalogue path) without modifying your persistent user config:

eomatch-find --config my_run.yaml
eomatch-download --config my_run.yaml
eomatch-preview /data/my_catalogue/catalog.json --config my_run.yaml

A minimal per-run file typically looks like:

platforms: Sentinel-2A, Landsat-9
collections: S2_MSI_L1C, LANDSAT_C2L1
start_time: "2023-06-01 00:00:00"
end_time:   "2023-06-30 23:59:59"
orbitx_netcdf_path: /data/orbitx/2023_S2A_LS9.nc

matchup_catalogue:
  path: /data/my_catalogue

See example/find_and_catalogue.yaml in the repository for a fully annotated example.

Configuring from Python

Pass a path or a dict directly to EOMatchContext:

from eomatch import EOMatchContext

# Load from a YAML file (merged on top of user config)
ctx = EOMatchContext("my_run.yaml")

# Or pass overrides as a dict
ctx = EOMatchContext({
    "platforms": "Sentinel-2A, Landsat-9",
    "collections": "S2_MSI_L1C, LANDSAT_C2L1",
    "matchup_catalogue": {"path": "/data/my_catalogue"},
})