docs: Clarification of STRTree documentation

[kannes]

I would like to (slightly) improve the documentation for the STRTree.

http://shapely.readthedocs.io/en/stable/manual.html#str-packed-r-tree says

Shapely provides an interface to the query-only GEOS R-tree packed using the Sort-Tile-Recursive algorithm. Pass a list of geometry objects to the STRtree constructor to create an R-tree that you can query with another geometric object.

The example then shows two queries that return Geometry objects.

I was hoping I could use STRTree just like the rtree module: passing index numbers to be able to match geometries to (Fiona) features but that seems not to be the case. STRTree simply takes a list of Geometry objects and on a query, returns the intersecting Geometry objects it knows about. There is no order or indices. Is that correct?

If so, I would just add one sentences about what the query method returns. For class descriptions (e.g. Point) the attributes are presented in prose, but if this should get a new .. method:: entry, just say so. :)

[sgillies]

@kannes we're not flexible right now about what gets stored, but we do store the geometry object as well as all its attributes. You can add attributes to a geometry object after it has been created because these geometry objects store their attributes in a __dict__ member (geom.myattr gets read as geom.__dict__['myattr']). We're not going to change this behavior of Shapely any time soon, so the following code should work at least until a hypothetical Shapely 2.0:

>>> from shapely.strtree import STRtree
>>> from shapely.geometry import Point
>>> pt = Point(0.0, 0.0)
>>> pt.name = 'foo'
>>> tree = STRtree([pt])
>>> tree.query(Point(1.0, 1.0).buffer(2.0))
[<shapely.geometry.point.Point object at 0x109254208>]
>>> results = tree.query(Point(1.0, 1.0).buffer(2.0))
>>> respt = results[0]
>>> respt
<shapely.geometry.point.Point object at 0x109254208>
>>> respt.name
'foo'

There is some related discussion in #615.

[kannes]

Thanks, I will update this

[kannes]

Done!

[edit: removed screwed up git mess]

A graphical representation of the example geometries and query geometry would be great to further show how it returns geometries whose extents intersect.

Not sure if I should suggest using deepcopy to avoid mutating the original objects.

[kannes]

#623 thanks to QGIS's @Nathanw

[Rubix982]

@kannes, should this issue be closed?

[kannes]

Oh yes, thank you!

[jorisvandenbossche]

@kannes note that the snippet above with setting an attribute on the geometry object (#618 (comment)) will no longer work in the upcoming Shapely 2.0 release. But there is now an alternative for this, i.e. query_items to get the enumeration index (or a custom index if that was stored when creating the tree), see #1112. This will be included in Shapely 1.8 (for which there is already a pre-release available on PyPI).

[Rubix982]

@jorisvandenbossche I think this should be mentioned in the changelogs for the upcoming alpha release for 1.8, right?

[jorisvandenbossche]

The STRtree changes are mentioned here:

https://github.com/Toblerity/Shapely/blob/9a761739aea19823fcead4391ef043edafa74db6/CHANGES.txt#L19-L24

[kannes]

That's great news, thanks!