diff --git a/.gitignore b/.gitignore index e43b0f9..dd36545 100644 --- a/.gitignore +++ b/.gitignore @@ -1 +1,3 @@ .DS_Store +.playwright-cli/ + diff --git a/api-reference/go/datasets/Datapoints.Query.mdx b/api-reference/go/datasets/Datapoints.Query.mdx index 7e0bd77..d7a7501 100644 --- a/api-reference/go/datasets/Datapoints.Query.mdx +++ b/api-reference/go/datasets/Datapoints.Query.mdx @@ -37,7 +37,7 @@ The output sequence can be transformed into a typed `proto.Message` using [Colle Optional, if not specified the query will return all results found globally. - Specify a geographical extent with an explicit spatial filter mode and coordinate system. + Specify a geographical extent with an explicit [spatial filter mode](/datasets/query/filter-by-location#spatial-filter-modes) and coordinate system. Restrict the query to specific dataset collections by collection object. diff --git a/api-reference/go/datasets/Datapoints.QueryInto.mdx b/api-reference/go/datasets/Datapoints.QueryInto.mdx index 7ae3ecc..34821d7 100644 --- a/api-reference/go/datasets/Datapoints.QueryInto.mdx +++ b/api-reference/go/datasets/Datapoints.QueryInto.mdx @@ -40,7 +40,7 @@ QueryInto is a convenience function for [Query](/api-reference/go/datasets/Datap Optional, if not specified the query will return all results found globally. - Specify a geographical extent with an explicit spatial filter mode and coordinate system. + Specify a geographical extent with an explicit [spatial filter mode](/datasets/query/filter-by-location#spatial-filter-modes) and coordinate system. Restrict the query to specific dataset collections by collection object. diff --git a/api-reference/go/datasets/Datapoints.QueryPage.mdx b/api-reference/go/datasets/Datapoints.QueryPage.mdx index df88651..1413955 100644 --- a/api-reference/go/datasets/Datapoints.QueryPage.mdx +++ b/api-reference/go/datasets/Datapoints.QueryPage.mdx @@ -34,7 +34,7 @@ Use `QueryPage` when you need manual pagination. Use [`Datapoints.Query`](/api-r Specify the geographical extent to query. - Specify a geographical extent with an explicit spatial filter mode and coordinate system. + Specify a geographical extent with an explicit [spatial filter mode](/datasets/query/filter-by-location#spatial-filter-modes) and coordinate system. Restrict the query to specific dataset collections by collection object. diff --git a/api-reference/python/tilebox.datasets/Collection.query.mdx b/api-reference/python/tilebox.datasets/Collection.query.mdx index 15ad00b..d93ff41 100644 --- a/api-reference/python/tilebox.datasets/Collection.query.mdx +++ b/api-reference/python/tilebox.datasets/Collection.query.mdx @@ -40,7 +40,7 @@ If no data exists for the requested time or interval, an empty `xarray.Dataset` - Optional spatial filter. Use this for spatial queries in spatio-temporal datasets. + Optional spatial filter for spatio-temporal datasets. Pass a geometry to use the default intersection behavior, or configure a [spatial filter mode](/datasets/query/filter-by-location#spatial-filter-modes). diff --git a/api-reference/python/tilebox.datasets/Dataset.query.mdx b/api-reference/python/tilebox.datasets/Dataset.query.mdx index f097776..10d965e 100644 --- a/api-reference/python/tilebox.datasets/Dataset.query.mdx +++ b/api-reference/python/tilebox.datasets/Dataset.query.mdx @@ -44,7 +44,7 @@ If no data matches the filters, an empty `xarray.Dataset` is returned. - Optional spatial filter. Use this for spatial queries in spatio-temporal datasets. + Optional spatial filter for spatio-temporal datasets. Pass a geometry to use the default intersection behavior, or configure a [spatial filter mode](/datasets/query/filter-by-location#spatial-filter-modes). diff --git a/assets/datasets/queries/intersection-mode-contains-dark.png b/assets/datasets/queries/intersection-mode-contains-dark.png deleted file mode 100644 index 1564add..0000000 Binary files a/assets/datasets/queries/intersection-mode-contains-dark.png and /dev/null differ diff --git a/assets/datasets/queries/intersection-mode-contains-light.png b/assets/datasets/queries/intersection-mode-contains-light.png deleted file mode 100644 index 8daf4ed..0000000 Binary files a/assets/datasets/queries/intersection-mode-contains-light.png and /dev/null differ diff --git a/assets/datasets/queries/intersection-mode-intersects-dark.png b/assets/datasets/queries/intersection-mode-intersects-dark.png deleted file mode 100644 index 7e6bd84..0000000 Binary files a/assets/datasets/queries/intersection-mode-intersects-dark.png and /dev/null differ diff --git a/assets/datasets/queries/intersection-mode-intersects-light.png b/assets/datasets/queries/intersection-mode-intersects-light.png deleted file mode 100644 index f417188..0000000 Binary files a/assets/datasets/queries/intersection-mode-intersects-light.png and /dev/null differ diff --git a/assets/datasets/queries/spatial-filter-modes-dark.png b/assets/datasets/queries/spatial-filter-modes-dark.png new file mode 100644 index 0000000..82bde74 Binary files /dev/null and b/assets/datasets/queries/spatial-filter-modes-dark.png differ diff --git a/assets/datasets/queries/spatial-filter-modes-light.png b/assets/datasets/queries/spatial-filter-modes-light.png new file mode 100644 index 0000000..242ce49 Binary files /dev/null and b/assets/datasets/queries/spatial-filter-modes-light.png differ diff --git a/datasets/query/filter-by-location.mdx b/datasets/query/filter-by-location.mdx index ce68cca..1ecaefb 100644 --- a/datasets/query/filter-by-location.mdx +++ b/datasets/query/filter-by-location.mdx @@ -78,24 +78,24 @@ if err != nil { ``` -## Intersection mode +## Spatial filter modes -By default, queries return all datapoints that intersect with the specified geometry. You can alter this behavior to return only datapoints fully contained within the geometry. Tilebox supports this by allowing you to specify a mode for the spatial filter. +The spatial filter mode controls the relationship between the filter geometry and each returned datapoint geometry. Containment mode names identify which geometry contains the other. - - - Query results with intersects mode - Query results with intersects mode - - - Query results with contains mode - Query results with contains mode - - +| Mode | Relationship | +| --- | --- | +| `intersects` | The datapoint geometry intersects the filter geometry | +| `filter_contains_geometry` | The filter geometry contains the datapoint geometry | +| `geometry_contains_filter` | The datapoint geometry contains the filter geometry | + + + Examples of intersects, filter contains geometry, and geometry contains filter modes + Examples of intersects, filter contains geometry, and geometry contains filter modes + ### Intersects -The `intersects` mode is the default for spatial queries. It matches all datapoints whose geometries intersect with the query geometry. +The `intersects` mode is the default for spatial queries. It matches all datapoints whose geometries intersect with the filter geometry. ```python Python @@ -138,9 +138,9 @@ if err != nil { There are 27 Sentinel-2A granules intersecting the area of Colorado on April 2nd, 2025 ``` -### Contains +### Filter contains geometry -The `contains` mode matches all datapoints whose geometries are fully contained within the query geometry. +The `filter_contains_geometry` mode matches datapoints whose geometries are fully contained within the filter geometry. ```python Python @@ -150,7 +150,7 @@ area = Polygon( # area roughly covering the state of Colorado data = collection.query( temporal_extent=("2025-04-01", "2025-05-02"), - spatial_extent={"geometry": area, "mode": "contains"}, + spatial_extent={"geometry": area, "mode": "filter_contains_geometry"}, ) print(f"There are {data.sizes['time']} Sentinel-2A granules fully contained within the area of Colorado on April 2nd, 2025") ``` @@ -169,7 +169,7 @@ err = client.Datapoints.QueryInto(ctx, datasets.WithTemporalExtent(query.NewTimeInterval(startDate, endDate)), datasets.WithSpatialExtentFilter(&query.SpatialFilter{ Geometry: area, - Mode: datasetsv1.SpatialFilterMode_SPATIAL_FILTER_MODE_CONTAINS, + Mode: datasetsv1.SpatialFilterMode_SPATIAL_FILTER_MODE_FILTER_CONTAINS_GEOMETRY, }), ) if err != nil { @@ -182,6 +182,45 @@ if err != nil { There are 16 Sentinel-2A granules fully contained within the area of Colorado on April 2nd, 2025 ``` +### Geometry contains filter + +The `geometry_contains_filter` mode matches datapoints whose geometries fully contain the filter geometry. For example, a small filter geometry within Colorado can match a datapoint whose geometry covers the entire state. + + +```python Python +area = Polygon( # a small area around Denver + ((-105.1, 39.8), (-105.1, 39.6), (-104.8, 39.6), (-104.8, 39.8), (-105.1, 39.8)), +) + +data = collection.query( + temporal_extent=("2025-04-01", "2025-05-02"), + spatial_extent={"geometry": area, "mode": "geometry_contains_filter"}, +) +``` +```go Go +startDate := time.Date(2025, 4, 2, 0, 0, 0, 0, time.UTC) +endDate := time.Date(2025, 5, 2, 0, 0, 0, 0, time.UTC) +area := orb.Polygon{ // a small area around Denver + {{-105.1, 39.8}, {-105.1, 39.6}, {-104.8, 39.6}, {-104.8, 39.8}, {-105.1, 39.8}}, +} + +var datapoints []*examplesv1.Sentinel2Msi +err = client.Datapoints.QueryInto(ctx, + dataset.ID, + &datapoints, + datasets.WithCollectionIDs(collection.ID), + datasets.WithTemporalExtent(query.NewTimeInterval(startDate, endDate)), + datasets.WithSpatialExtentFilter(&query.SpatialFilter{ + Geometry: area, + Mode: datasetsv1.SpatialFilterMode_SPATIAL_FILTER_MODE_GEOMETRY_CONTAINS_FILTER, + }), +) +if err != nil { + log.Fatalf("Failed to query datapoints: %v", err) +} +``` + + ## Antimeridian Crossings In many applications, geometries that cross the antimeridian cause issues. Since such geometries are common in satellite