eomatch.add_asset.generate_missing_assets

eomatch.add_asset.generate_missing_assets#

eomatch.add_asset.generate_missing_assets(items: Iterable[Any], asset_key: str, output_path: Callable[[Any], str], generate: Callable[[Any, str], Any], add_asset: Callable[[...], bool], asset_href: Callable[[Any, str], str] | None = None, media_type: str | None = None, title: str | None = None, roles: List[str] | None = None, overwrite: bool = False, return_values: bool = False, raise_error: bool = False) → Any[source]#

Generate and register asset_key for every item in items that doesn’t already have it.

For each MatchupEvent or Matchup in items missing asset_key on its .assets (or every item, if overwrite is True):

  1. output_path(item) gives the local file path to generate the asset at.

  2. generate(item, path) is called to produce that file; its return value is ignored, so callers whose generator function returns something (e.g. a matplotlib figure to close) can just do that inline in the callable passed here.

  3. asset_href(item, path), if given, computes the href to register from path — e.g. relative to the item’s own directory, for a portable link. Defaults to path itself when not given.

  4. add_asset(item, asset_key, href, media_type=media_type, title=title, roles=roles) registers it — pass a bound method such as add_matchup_asset() or add_event_asset().

A failure raised by any of the above for one item is logged and that item is skipped, rather than aborting the whole run.

Example — generating a matchup thumbnail with a user-provided plotting function:

from eomatch.add_asset import generate_missing_assets

def make_thumbnail(matchup, path):
    fig = build_preview(matchup, output_path=path)
    plt.close(fig)

n = generate_missing_assets(
    items=[mu for event in cat.get_events() for mu in (event.matchup_set or [])],
    asset_key="thumbnail",
    output_path=lambda mu: f"/data/thumbnails/{mu.stac_id}.png",
    generate=make_thumbnail,
    add_asset=cat.add_matchup_asset,
    media_type="image/png",
    roles=["thumbnail"],
)
Parameters:

  • items – MatchupEvent or Matchup instances to process.

  • asset_key – asset key to check for and register, e.g. "thumbnail".

  • output_path – given an item, returns the local file path to generate the asset at.

  • generate – given (item, output_path), writes the asset file. Return value ignored.

  • add_asset – bound method used to register the generated file as an asset, e.g. add_matchup_asset() or add_event_asset().

  • asset_href – given (item, output_path), returns the href to register — use this when the file must be written to one location but linked to from the STAC item with a different (typically relative) path. Defaults to registering output_path unchanged.

  • media_type – MIME type passed through to add_asset; auto-detected if None.

  • title – title passed through to add_asset; defaults to the filename.

  • roles – STAC asset roles passed through to add_asset, e.g. ["thumbnail"].

  • overwrite – if True, regenerate and re-register even when asset_key is already present.

  • return_values – if True, return the values returned by generate for each successfully generated item rather than the count.

  • raise_error – if True, raise errors instead of catching them in a try statement

Returns:

number of assets successfully generated and registered, or a list of generate return values when return_values is True.