Hint

You can run this notebook in a live session with .

Crunch

Crunching as defined in eodag is a way to filter the EO products contained in a SearchResult object. Several filters are available and further described in this document.

A SearchResult has a crunch() method that requires a filter instance as an argument, itself initialized with a dictionary that contains the required parameters. According to the filter used, some more kwargs may need to be passed to crunch(). The filters return a list of EOProducts.

Setup

Results obtained from a search of Sentinel 2 Level-1C products over France in March 2021 are loaded in a SearchResult.

from eodag import EODataAccessGateway
dag = EODataAccessGateway()
search_results = dag.deserialize("data/crunch_search_results.geojson")
print(f"This SearchResult stores {len(search_results)} products.")

This SearchResult stores 50 products.

The original search geometry is used throughout the notebook as long as with its representation as a a shapely object which is easier to map with folium.

original_search_geometry = {"lonmin": 1, "latmin": 45, "lonmax": 5, "latmax": 47}

import shapely

search_geometry = shapely.geometry.box(
    original_search_geometry["lonmin"],
    original_search_geometry["latmin"],
    original_search_geometry["lonmax"],
    original_search_geometry["latmax"],
)

# To create interactive maps
import folium

def create_search_result_map(search_results, extent):
    """Small utility to create an interactive map with folium
    that displays an extent in red and EO Producs in blue"""
    fmap = folium.Map([46, 3], zoom_start=6)
    folium.GeoJson(
        extent,
        style_function=lambda x: dict(color="red")
    ).add_to(fmap)
    folium.GeoJson(
        search_results
    ).add_to(fmap)
    return fmap

Filter by start and end date

FilterDate allows to filter out products that are older than a start date (optional) or more recent than an end date (optional).

This cruncher can also be called directly using SearchResult.filter_date().

from eodag.crunch import FilterDate

filtered_products = search_results.crunch(
    FilterDate(dict(start="2021-03-25", end="2021-03-29"))
)
print(f"{len(search_results) - len(filtered_products)} products were filtered out by the date filter.")

21 products were filtered out by the date filter.

Filter by geometry

FilterOverlap allows to filter out products that:

• whose overlap area with a geometry is less than a percentage of their area

• are not within a geometry

• do not contain a geometry

• do not intersect with a geometry

To execute a FilterOverlap, its instance must be created by passing a dictionary with either:

• minimum_overlap set to a number between 0 and 100. within, contains and intersects cannot be used in that case.

• One of within, contains and intersects (they are mutually exclusive) set to True. minimum_overlap cannot be used in that case.

Additionally, a geometry (shapely geometry, bounding box as a dictionary or a list) must be passed through the geometry parameter.

The examples below show how FilterOverlap filter out products. The original products will be displayed in blue and the filtered products in green.

This cruncher can also be called directly using SearchResult.filter_overlap().

from eodag.crunch import FilterOverlap

All the products are displayed on the next map. As it can be observed, they all intersect with the search geometry.

create_search_result_map(search_results, search_geometry)

Make this Notebook Trusted to load map: File -> Trust Notebook

The next two examples show how minimum_overlap affects the filter, with its value (i.e. percentage) set to 10 and 50%.

filtered_products = search_results.crunch(
    FilterOverlap(dict(minimum_overlap=10)),
    geometry=search_geometry
)
print(f"{len(search_results) - len(filtered_products)} products were filtered out by the geometry filter.")

19 products were filtered out by the geometry filter.

fmap = create_search_result_map(search_results, search_geometry)
# Create a layer that represents the search area in green
folium.GeoJson(
    filtered_products,
    style_function=lambda x: dict(color="green")
).add_to(fmap)
fmap

Make this Notebook Trusted to load map: File -> Trust Notebook