Building a custom AerEO plugin

AerEO plugins are plain Python functions — no base classes, no inheritance, no framework API to learn. You register them under the aereo.plugins entry-point group and AerEO discovers them automatically.

In this chapter we build to_db, a tiny processor that converts Sentinel-1 linear backscatter to decibels, package it as a real installable plugin, and run it in an extraction job — reusing the Sentinel-1 setup from the previous chapter.

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.

Installing the demo plugin¶

The demo plugin ships inside the aereo repository at examples/plugins/aereo_demo_plugin. The next cell installs it straight from GitHub (inside a repo checkout, pip install -e examples/plugins/aereo_demo_plugin does the same).

The plugin: one function, one entry point¶

This is the entire processor:

"""Demo processor plugin: convert SAR backscatter to decibels."""

import numpy as np
import xarray as xr
from pydantic import ConfigDict, validate_call


@validate_call(config=ConfigDict(arbitrary_types_allowed=True))
def to_db(ds: xr.Dataset, clip_min: float = 1e-6) -> xr.Dataset:
    """Convert linear backscatter (e.g. Sentinel-1 vv/vh) to decibels.

    Values at or below ``clip_min`` are clipped before the log to avoid
    ``-inf`` in the output.
    """
    return 10.0 * np.log10(ds.clip(min=clip_min))

And its registration in the package’s pyproject.toml. The process_ prefix tells AerEO this is a processor stage (search_, read_, reproject_, write_, task_builder_ work the same way):

[project.entry-points."aereo.plugins"]
process_to_db = "aereo_demo_plugin.processors:to_db"

The contract is just the signature: a processor takes an xr.Dataset and returns one. It can be used as preprocess (before reprojection) or postprocess (after). The arbitrary_types_allowed config is needed because xr.Dataset is not a Pydantic-native type.

Discovery: the plugin is now in the registry¶

Once the package is installed, AerEO finds it via entry points — no imports, no wiring. AereoRegistry can also introspect the plugin’s parameters, which is how config files get validated:

Config files used in this chapter¶

The next cell downloads job_sentinel1.yaml (the Sentinel-1 job from the previous chapter), job_sentinel1-db.yaml, and the Chocón AOI. The second config inherits the first and adds our plugin as postprocess — Hydra instantiates it by dotted path, exactly like the built-in stages:

defaults:
  - job_sentinel1
  - _self_

name: sentinel1_db
output_uri: /tmp/aereo_extraction_s1_db

# The to_db processor comes from the demo plugin package
# (examples/plugins/aereo_demo_plugin), registered via entry points.
postprocess:
  - _target_: aereo_demo_plugin.processors.to_db
    _partial_: true

Loading the job¶

ExtractionJob.load_from_config() parses the YAML with Hydra, resolves every _target_ callable — including aereo_demo_plugin.processors.to_db — and validates the resulting ExtractionJob.

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.

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¶

Each task runs read -> reproject -> postprocess -> write, where postprocess is now our to_db plugin: the GeoTIFFs come out in decibels, converted after reprojection to the Major TOM grid.

Visualizing results¶

Same scene as the Sentinel-1 chapter, but note the colorbar: values are now in dB. The plugin ran inside the pipeline — no notebook-side postprocessing involved.

Alternative: skip packaging, pass the function directly¶

Entry points make a plugin discoverable and shareable. But for quick experiments you don’t even need a package — any function can be passed straight to the job:

from aereo.pipeline import ExtractionJob
from aereo_demo_plugin.processors import to_db

job = ExtractionJob(
    name="s1_db_inline",
    grid_dist=10_000,
    output_uri="/tmp/aereo_s1_db_inline",
    search=search_stac,
    read=read_odc_stac,
    postprocess=[to_db],   # <- just a function
    write=write_geotiff,
    target_aoi=aoi,
)

Package it when you want to share it; keep it inline while you iterate. See Build a Plugin for the full stage-by-stage reference.