Sentinel-2 L2A extraction with AerEO

This chapter walks through a complete AerEO extraction pipeline for Sentinel-2 L2A imagery.

AerEO is built around the ExtractionJob. A job declaratively combines a search provider, a reader, optional preprocess/reproject/postprocess steps, a writer, and a grid definition that splits the area of interest (AOI) into independent tasks. By keeping all of this in a YAML config, the same job can be reproduced from a notebook, the command line, or an AWS Lambda handler.

Environment setup¶

The first cell installs AerEO and any required plugins. If you are reading the rendered book or running on Binder, where the environment is already prepared, pip will report that the requirements are satisfied and skip the download.

Config files used in this chapter¶

The next cell downloads two files:

1. job_sentinel2.yaml — the AerEO job configuration.

2. chocon.geojson — the AOI over Argentina’s Chocón region.

Keeping configuration outside the notebook makes the pipeline reusable and version-controllable. Here is the full YAML we are loading:

# Common vars reused in the config
target_bands: [red, nir]
aoi_path: config/aoi/chocon.geojson

name: sentinel2_sample
grid_dist: 10_000
grid_cells_margin: 10
target_aoi: ${aoi_path}
output_uri: /tmp/aereo_extraction
overwrite: false

search:
  _target_: aereo.builtins.search_stac
  _partial_: true
  stac_api_url: "https://earth-search.aws.element84.com/v1"
  collections:
    sentinel-2-l2a: ${target_bands}
  intersects: ${aoi_path}
  start_datetime: "2024-01-01T00:00:00Z"
  end_datetime: "2024-01-10T23:59:59Z"

read:
  _partial_: true
  _target_: aereo.builtins.read_odc_stac
write:
  _target_: aereo.builtins.write.write_geotiff

Key fields:

• target_aoi — path to the AOI GeoJSON.

• grid_dist — spacing of the MajorTOM grid used to split the AOI into cells (10 km here).

• search.collections — STAC collection and bands to retrieve.

• read and write — plugin callables that load assets and save GeoTIFFs.

Loading the job¶

ExtractionJob.load_from_config() parses the YAML with Hydra, resolves every _target_ callable, and validates the resulting ExtractionJob. The config_name argument is the YAML filename without extension, and config_dir is the folder that contains it.

A job is a declarative bundle of pipeline steps. Once loaded, the same job can be searched, can have tasks built from it, and can be executed.

Search and task building¶

job.search() calls the configured search provider and returns a GeoDataFrame of matched assets. This is a separate step from execution: it only discovers what data is available, without reading or writing anything.

job.build_tasks(assets) turns those assets into a list of ExtractionTask objects. Each task groups the assets needed for one grid cell and time slice, so the work can be parallelised later.

The executor¶

AerEO separates what to run (the tasks) from how to run them. LocalExecutor runs tasks on the local machine. The workers argument controls parallelism, and use_threads=True uses a threading backend, which is a good default for I/O-bound COG readers.

Running the extraction¶

job.execute(tasks, executor=...) hands the prepared tasks to the executor. The executor runs each task independently; inside every task AerEO performs the pipeline:

read -> preprocess -> reproject -> postprocess -> write

The returned object is a GeoDataFrame of artifacts — one row per output GeoTIFF with its metadata, CRS, and footprint.

Visualizing results¶

plot_artifact_patches renders the extracted patches over the AOI. The stretch="percentile" option improves contrast by clipping to a percentile range.