Support shapely geometries / `__geo_interface__` for `intersects`

[TomAugspurger]

As a convenience, it'd be nice to pass a shapely object for intersects in search.

item_a = ...
point = shapely.geometry.shape(item_a).centroid  # a shapely point

search(..., intersects=point)

Internally, pystac-client could convert to the geojson representation.

To generalize a bit more, there's the __geo_interface__: https://gist.github.com/sgillies/2217756. pystac-client might check for that method and call it if it exists, regardless of the type of the object.

Come to think of it, maybe pystac items should implement __geo_interface__ too... (stac-utils/pystac#786)

[matthewhanson]

Currently the dependencies in pystac-client are minimal: requests and pystac. I'm not necessarily against adding additional dependencies, but want to be sure it's worth it. shapely requests the GEOS binaries, so it's a bit more than just another Python library.

On the other hand, I've also been keen on adding calculations of AOI coverage, #105, which also would require shapely which gives another use case for including it.

Unless pystac has some additional use cases that would benefit from a shapely dependency, I'd lean toward adding this to pystac-client if we want to add it.

[TomAugspurger]

A shapely dependency wouldn't be required. In pseudo-code

if hasattr(intersection, "__geo_interface__"):
    intersection = intersection.__geo_interface__

The nice thing about the interface is that the consumer (pystac-client in this case) doesn't have to know anything about the object implementing it.

[matthewhanson]

Ok cool, well then this seems like a fine idea. How do we capture the type information for the intersects arg?

[TomAugspurger]

Well, this is embarrassing. Turns out John implemented a long time ago:

pystac-client/pystac_client/item_search.py

Line 406 in b8ff817

return deepcopy(getattr(value, '__geo_interface__', value))

In [19]: client = pystac_client.Client.open("https://planetarycomputer.microsoft.com/api/stac/v1")

In [20]: p = shapely.geometry.Point(0, 0)

In [21]: search = client.search(collections=["sentine-2-l2a"], intersects=p)

In [22]: search.get_parameters()["intersects"]
Out[22]: {'type': 'Point', 'coordinates': (0.0, 0.0)}

Doesn't seem to be documented though.

[philvarner]

Since this is already supported but not documented, I'm using this issue to tighten up the type definitions and add pydoc