Geometry¶

The Zonal Stats service takes one GeoJSON Point or Polygon per request. to_aoi gets there from whatever describes the place: a GeoJSON mapping, anything with a __geo_interface__ (a shapely geometry, a GeoDataFrame row), a (lon, lat) tuple or a Site. The endpoints call it for you; call it yourself to check an area of interest before sending it.

geometry ¶

Areas of interest for the Zonal Stats service.

The service accepts one GeoJSON Point (optionally buffered by a radius in metres) or one Polygon per request, and answers with one set of area-weighted statistics. to_aoi turns any reasonable description of a place into exactly that: a GeoJSON geometry or Feature mapping, an object with a __geo_interface__ (a shapely geometry, a GeoDataFrame row, a pystac item), a (lon, lat) tuple, or a MERMAID Site.

from datamermaid import to_aoi

to_aoi((178.4, -18.1), radius=500)
# {'type': 'Point', 'coordinates': [178.4, -18.1], 'radius': 500.0}

to_aoi(site)               # a Site's location
to_aoi(shapely_polygon)    # anything with a __geo_interface__

A MultiPolygon is rejected rather than split into its parts because the service returns one set of statistics per request; the caller decides whether to buffer, dissolve or iterate. LineString, FeatureCollection and GeometryCollection are rejected for the same reason. The returned dict is always fresh, holds plain list[float] coordinates (numpy scalars and tuples are converted) and serialises with json.dumps as it is.

Classes:

Name	Description
`HasGeoInterface`	Anything exposing the `__geo_interface__` protocol.

Functions:

Name	Description
`to_aoi`	Normalise `geometry` into the GeoJSON `Point` or `Polygon` the service accepts.

Attributes:

Name	Type	Description
`AOI_TYPES`
`GeometryLike`	`TypeAlias`

AOI_TYPES `module-attribute` ¶

AOI_TYPES = frozenset({'Point', 'Polygon'})

Position `module-attribute` ¶

Position: TypeAlias = list[float]

GeometryLike `module-attribute` ¶

GeometryLike: TypeAlias = (
    Mapping[str, Any]
    | HasGeoInterface
    | tuple[float, float]
    | Site
)

HasGeoInterface ¶

Bases: Protocol

Anything exposing the __geo_interface__ protocol.

Shapely geometries, GeoDataFrame rows, pystac items and MERMAID Site and Management records all do. The mapping may be a geometry or a Feature wrapping one.

to_aoi ¶

to_aoi(
    geometry: GeometryLike, *, radius: float | None = None
) -> dict[str, Any]

Normalise geometry into the GeoJSON Point or Polygon the service accepts.

Parameters:

Name	Type	Description	Default
`geometry`	`GeometryLike`	A GeoJSON `Point` or `Polygon` mapping, a `Feature` holding one, an object with a `__geo_interface__` (which may itself return a `Feature`), a `(lon, lat)` tuple, or a `Site` with a `location`.	required
`radius`	`float \| None`	Buffer around a `Point`, in metres. Overrides a `radius` already on the input mapping; when omitted, one on the input is kept.	`None`

Returns:

Type	Description
`dict[str, Any]`	A new dict with `type`, `coordinates` (plain `list[float]`
`dict[str, Any]`	positions) and, for a buffered Point, `radius`. It never shares
`dict[str, Any]`	structure with the input and round-trips through `json.dumps`.

Raises:

Type	Description
`TypeError`	If `geometry` is none of the accepted kinds (a string, a list, `None`), or a `__geo_interface__` returns a non-mapping.
`ValueError`	If the geometry type is not `Point` or `Polygon` (a `MultiPolygon`, `LineString`, `FeatureCollection`, ...), a Point is not `[lon, lat]`, a Polygon ring is unclosed or has fewer than four positions, `radius` is given for a Polygon or is negative, or a `Site` has no `location`.

Example

to_aoi({"type": "Point", "coordinates": (178.4, -18.1)}, radius=500)
# {'type': 'Point', 'coordinates': [178.4, -18.1], 'radius': 500.0}