0
# Container Interface
1
2
High-level container for storing Python objects with spatial coordinates, providing a more Pythonic interface for spatial data management without explicit ID management. The RtreeContainer class automatically handles ID assignment and provides object-centric operations.
3
4
## Capabilities
5
6
### Container Construction
7
8
Create spatial containers for storing Python objects with automatic ID management.
9
10
```python { .api }
11
class RtreeContainer:
12
def __init__(self, *args, **kwargs):
13
"""
14
Create a spatial container for Python objects.
15
16
Parameters:
17
- *args, **kwargs: Same parameters as Index constructor
18
19
The container automatically manages object IDs and provides
20
object-centric spatial operations.
21
"""
22
```
23
24
### Object Insertion
25
26
Insert Python objects with associated spatial coordinates into the container.
27
28
```python { .api }
29
def insert(self, obj, coordinates):
30
"""
31
Insert a Python object with spatial coordinates.
32
33
Parameters:
34
- obj (object): Python object to store
35
- coordinates (sequence): Bounding box as (minx, miny, maxx, maxy)
36
37
The container automatically assigns an internal ID to the object.
38
"""
39
40
def add(self, obj, coordinates):
41
"""Alias for insert method."""
42
```
43
44
### Object Deletion
45
46
Remove Python objects from the container by object reference and coordinates.
47
48
```python { .api }
49
def delete(self, obj, coordinates):
50
"""
51
Delete a Python object from the container.
52
53
Parameters:
54
- obj (object): Object to remove (must be the same object reference)
55
- coordinates (sequence): Bounding box used during insertion
56
57
Uses object identity to locate and remove the object.
58
"""
59
```
60
61
### Spatial Object Queries
62
63
Perform spatial queries that return actual Python objects instead of IDs.
64
65
```python { .api }
66
def intersection(self, coordinates, bbox=False):
67
"""
68
Find objects that intersect with given coordinates.
69
70
Parameters:
71
- coordinates (sequence): Query bounding box
72
- bbox (bool): If True, return (object, bbox) tuples
73
74
Returns:
75
Generator yielding stored objects or (object, bbox) tuples
76
"""
77
78
def nearest(self, coordinates, num_results=1, bbox=False):
79
"""
80
Find nearest objects to given coordinates.
81
82
Parameters:
83
- coordinates (sequence): Query point or bounding box
84
- num_results (int): Number of results to return
85
- bbox (bool): If True, return (object, bbox) tuples
86
87
Returns:
88
Generator yielding stored objects or (object, bbox) tuples
89
"""
90
```
91
92
### Container Management
93
94
Standard Python container operations for object management and introspection.
95
96
```python { .api }
97
def __contains__(self, obj):
98
"""
99
Check if object is stored in container.
100
101
Parameters:
102
- obj (object): Object to check
103
104
Returns:
105
bool: True if object is in container
106
"""
107
108
def __len__(self):
109
"""
110
Get number of unique objects in container.
111
112
Returns:
113
int: Count of stored objects
114
"""
115
116
def __iter__(self):
117
"""
118
Iterate over all stored objects.
119
120
Returns:
121
Iterator yielding stored objects
122
"""
123
```
124
125
### Leaf Node Access
126
127
Access leaf node information with actual stored objects instead of IDs.
128
129
```python { .api }
130
def leaves(self):
131
"""
132
Get leaf node information with actual objects.
133
134
Returns:
135
Generator yielding (node_id, bbox, objects) tuples where
136
objects is a list of actual stored Python objects
137
"""
138
```
139
140
## Usage Examples
141
142
### Basic Container Operations
143
144
```python
145
from rtree.index import RtreeContainer
146
147
# Create container
148
container = RtreeContainer()
149
150
# Insert objects with coordinates
151
buildings = [
152
{"name": "City Hall", "type": "government"},
153
{"name": "Library", "type": "public"},
154
{"name": "Mall", "type": "commercial"}
155
]
156
157
container.insert(buildings[0], (10, 10, 20, 20))
158
container.insert(buildings[1], (15, 15, 25, 25))
159
container.insert(buildings[2], (30, 30, 40, 40))
160
161
# Query operations return actual objects
162
nearby = list(container.intersection((12, 12, 18, 18)))
163
# [{"name": "City Hall", "type": "government"}, {"name": "Library", "type": "public"}]
164
165
closest = list(container.nearest((5, 5, 5, 5), 1))
166
# [{"name": "City Hall", "type": "government"}]
167
```
168
169
### Container with Bounding Box Information
170
171
```python
172
from rtree.index import RtreeContainer
173
174
container = RtreeContainer()
175
176
# Insert objects
177
container.insert({"id": 1, "name": "Park"}, (0, 0, 100, 100))
178
container.insert({"id": 2, "name": "School"}, (50, 50, 150, 150))
179
180
# Get objects with their bounding boxes
181
results = list(container.intersection((25, 25, 75, 75), bbox=True))
182
# [({"id": 1, "name": "Park"}, (0, 0, 100, 100)),
183
# ({"id": 2, "name": "School"}, (50, 50, 150, 150))]
184
185
nearest_with_bbox = list(container.nearest((0, 0, 0, 0), 1, bbox=True))
186
# [({"id": 1, "name": "Park"}, (0, 0, 100, 100))]
187
```
188
189
### Container Membership and Iteration
190
191
```python
192
from rtree.index import RtreeContainer
193
194
container = RtreeContainer()
195
196
# Store various object types
197
objects = [
198
{"type": "point", "coords": [10, 20]},
199
{"type": "line", "length": 50},
200
[1, 2, 3, 4] # Even lists can be stored
201
]
202
203
for i, obj in enumerate(objects):
204
container.insert(obj, (i*10, i*10, (i+1)*10, (i+1)*10))
205
206
# Check membership
207
print(objects[0] in container) # True
208
print({"type": "point", "coords": [10, 20]} in container) # False (different object)
209
210
# Container size
211
print(len(container)) # 3
212
213
# Iterate over all objects
214
for obj in container:
215
print(obj)
216
```
217
218
### Object Deletion
219
220
```python
221
from rtree.index import RtreeContainer
222
223
container = RtreeContainer()
224
225
# Insert objects (keep references)
226
obj1 = {"name": "Building A"}
227
obj2 = {"name": "Building B"}
228
229
container.insert(obj1, (0, 0, 10, 10))
230
container.insert(obj2, (5, 5, 15, 15))
231
232
print(len(container)) # 2
233
234
# Delete by object reference
235
container.delete(obj1, (0, 0, 10, 10))
236
print(len(container)) # 1
237
238
# Remaining object
239
remaining = list(container)
240
print(remaining) # [{"name": "Building B"}]
241
```
242
243
### Custom Object Storage
244
245
```python
246
from rtree.index import RtreeContainer
247
248
class SpatialObject:
249
def __init__(self, name, geometry):
250
self.name = name
251
self.geometry = geometry
252
253
def __repr__(self):
254
return f"SpatialObject('{self.name}')"
255
256
container = RtreeContainer()
257
258
# Store custom objects
259
objects = [
260
SpatialObject("River", "LINESTRING(0 0, 100 100)"),
261
SpatialObject("Lake", "POLYGON((10 10, 20 10, 20 20, 10 20, 10 10))"),
262
SpatialObject("Mountain", "POINT(50 75)")
263
]
264
265
container.insert(objects[0], (0, 0, 100, 100))
266
container.insert(objects[1], (10, 10, 20, 20))
267
container.insert(objects[2], (50, 75, 50, 75))
268
269
# Query returns actual custom objects
270
features = list(container.intersection((15, 15, 60, 60)))
271
for feature in features:
272
print(f"{feature.name}: {feature.geometry}")
273
```
274
275
### Leaf Node Inspection
276
277
```python
278
from rtree.index import RtreeContainer
279
280
container = RtreeContainer()
281
282
# Add several objects
283
for i in range(10):
284
obj = {"id": i, "value": f"object_{i}"}
285
container.insert(obj, (i, i, i+5, i+5))
286
287
# Inspect leaf nodes with actual objects
288
for node_id, bbox, objects in container.leaves():
289
print(f"Node {node_id} (bbox: {bbox}) contains {len(objects)} objects:")
290
for obj in objects:
291
print(f" {obj}")
292
```