Preview images

EOMatch can generate side-by-side natural-colour preview images for any Matchup. Previews use a lightweight read configuration separate from the scientific dataset defaults — only the RGB bands are loaded — so they are fast to produce even at full catalogue scale.

Generating a preview in Python

Use preview_matchup() to generate a preview for a single matchup. The function returns a matplotlib.figure.Figure (suitable for inline notebook display) and optionally saves the image to disk:

from eomatch import preview_matchup

fig = preview_matchup(matchup)

fig = preview_matchup(matchup, output_path="preview.png", max_pixels=256)

The figure contains one panel per sensor, labelled with the STAC collection ID (e.g. S2_MSI_L1C, LANDSAT_C2L1). Each panel is a percentile-stretched natural-colour composite derived from the collection’s RGB bands.

Controlling what is read

preview_matchup() accepts collection_read_args with the same semantics as return_matchup_dataset() (see Building collocated datasets):

fig = preview_matchup(
    matchup,
    collection_read_args={
        "S2_MSI_L1C": {"vars_sel": {"meas": ["B04", "B03", "B02"]}},
    },
)

Configuring preview defaults

Preview reads are configured under the preview.read key in the config file, independently of the read section used for scientific datasets. The bundled default requests only the RGB bands with metadata disabled:

preview:
  read:
    defaults:
      vars_sel:
        meas: rgb        # eoio resolves "rgb" to the natural-colour bands per collection
        aux: []
      read_params:
        use_chunks: false
        metadata_level: false
        save_extracted: false
      processors: {}
    collections: {}

The meas: rgb sentinel is resolved by eoio to the appropriate band names for each collection (e.g. B02, B03, B04 for S2_MSI_L1C). Per-collection overrides follow the same merge rules as the main read section (see Configuring read defaults).

Generating thumbnails in bulk

The eomatch-preview command generates thumbnails for every downloaded matchup in a catalogue and registers each as a "thumbnail" STAC asset on the matchup Item. Running the command repeatedly is safe — matchups that already have a thumbnail are skipped automatically.

eomatch-preview /data/my_catalogue/catalog.json

Thumbnails are saved under a thumbnails/ directory inside the catalogue root, mirroring the date hierarchy used by the data/ folder:

catalogue/
├── data/
│   └── Landsat/Landsat-9/LANDSAT_C2L1/2022/05/21/LC09_…
└── thumbnails/
    └── LANDSAT_C2L1-Landsat-9-vs-S2_MSI_L1C-S2A/
        └── 2022/
            └── 05/
                └── 21/
                    └── <matchup-id>_thumbnail.png

Platform is included in the folder name so that matchups between different platform pairs (e.g. Landsat-8 vs Sentinel-2B) are stored separately even when they share the same collection pair.

The thumbnail path is stored as a relative href on the matchup STAC Item so that the catalogue remains self-contained.

Available options:

Flag	Description
CATALOGUE	Path to the root catalog.json (required).
--collections ID [ID …]	Restrict to one sensor pair, e.g. S2_MSI_L1C LANDSAT_C2L1.
--platforms NAME [NAME …]	Restrict to events that include at least one of these platforms.
--start DATETIME	Lower bound on event time (ISO 8601, e.g. 2022-01-01).
--stop DATETIME	Upper bound on event time (ISO 8601, e.g. 2022-12-31).
--bbox LON_MIN LAT_MIN LON_MAX LAT_MAX	Spatial bounding-box filter.
--max-pixels N	Maximum pixel extent in either dimension (default: 512).
--overwrite	Regenerate thumbnails even when one already exists.
--config PATH	YAML config file merged on top of the user config.
--verbose / -v	Enable debug logging.

The same functionality is available as a Python function:

from eomatch.generate_previews import generate_previews

n = generate_previews(
    catalogue_path="/data/my_catalogue/catalog.json",
    collections=["S2_MSI_L1C", "LANDSAT_C2L1"],
    max_pixels=256,
)
print(f"Generated {n} thumbnail(s)")