0
# Configuration and Properties
1
2
Index configuration through the Property class, which controls performance characteristics, storage options, index variants, and spatial dimensions. Many properties must be set at index creation time and cannot be changed later.
3
4
## Capabilities
5
6
### Property Class
7
8
Central configuration object for controlling index behavior and performance.
9
10
```python { .api }
11
class Property:
12
def __init__(self, handle=None, owned: bool = True, **kwargs: Any) -> None:
13
"""
14
Create a property configuration object.
15
16
Parameters:
17
- handle (optional): Internal handle (for advanced use)
18
- owned (bool): Handle ownership flag
19
- **kwargs: Property values to set during initialization
20
21
Returns:
22
None
23
"""
24
25
def initialize_from_dict(self, state: dict[str, Any]) -> None:
26
"""
27
Initialize properties from a dictionary.
28
29
Parameters:
30
- state (dict): Dictionary of property name-value pairs
31
32
Returns:
33
None
34
"""
35
36
def as_dict(self) -> dict[str, Any]:
37
"""
38
Convert properties to a dictionary representation.
39
40
Returns:
41
dict: All property values as key-value pairs
42
"""
43
```
44
45
### Index Types and Variants
46
47
Configure the fundamental index algorithm and splitting strategy.
48
49
```python { .api }
50
class Property:
51
type: int
52
"""
53
Index type selection.
54
55
Values:
56
- RT_RTree (0): Standard R-Tree (default, recommended)
57
- RT_MVRTree (1): Multi-Version R-Tree
58
- RT_TPRTree (2): Time-Parameterized R-Tree for moving objects
59
"""
60
61
variant: int
62
"""
63
Index variant for node splitting algorithm.
64
65
Values:
66
- RT_Linear (0): Linear splitting (fastest)
67
- RT_Quadratic (1): Quadratic splitting (balanced)
68
- RT_Star (2): R*-Tree splitting (best quality, slower)
69
"""
70
```
71
72
Usage example:
73
74
```python
75
from rtree import index
76
77
# Configure R*-Tree with quadratic splitting
78
p = index.Property()
79
p.type = index.RT_RTree
80
p.variant = index.RT_Star
81
82
idx = index.Index(properties=p)
83
```
84
85
### Storage Configuration
86
87
Control how and where index data is stored.
88
89
```python { .api }
90
class Property:
91
storage: int
92
"""
93
Storage backend type.
94
95
Values:
96
- RT_Memory (0): Memory-only storage (default)
97
- RT_Disk (1): File-based storage
98
- RT_Custom (2): Custom storage implementation
99
"""
100
101
filename: str
102
"""
103
Base filename for disk storage (without extension).
104
105
Used when storage = RT_Disk. Index creates .idx and .dat files.
106
"""
107
108
dat_extension: str
109
"""
110
File extension for data files (default: "dat").
111
"""
112
113
idx_extension: str
114
"""
115
File extension for index files (default: "idx").
116
"""
117
118
overwrite: bool
119
"""
120
Whether to overwrite existing files (default: False).
121
122
If False and files exist, opens existing index.
123
If True, creates new index, deleting existing files.
124
"""
125
126
writethrough: bool
127
"""
128
Enable write-through mode for immediate disk writes.
129
130
If True, changes are written immediately to disk.
131
If False, changes may be buffered.
132
"""
133
```
134
135
Usage example:
136
137
```python
138
from rtree import index
139
140
# Configure disk-based storage
141
p = index.Property()
142
p.storage = index.RT_Disk
143
p.filename = "spatial_index"
144
p.overwrite = True
145
p.writethrough = True
146
147
idx = index.Index(properties=p)
148
# Creates spatial_index.idx and spatial_index.dat files
149
```
150
151
### Spatial Dimensions
152
153
Configure the number of spatial dimensions for the index.
154
155
```python { .api }
156
class Property:
157
dimension: int
158
"""
159
Number of spatial dimensions (default: 2).
160
161
Common values:
162
- 2: 2D spatial indexing (x, y coordinates)
163
- 3: 3D spatial indexing (x, y, z coordinates)
164
- Higher: Multi-dimensional indexing
165
166
Note: Must be set before index creation.
167
"""
168
```
169
170
Usage example:
171
172
```python
173
from rtree import index
174
175
# Configure 3D spatial indexing
176
p = index.Property()
177
p.dimension = 3
178
179
idx = index.Index(properties=p)
180
181
# Insert 3D data: (minx, miny, minz, maxx, maxy, maxz)
182
idx.insert(0, (0, 0, 0, 1, 1, 1))
183
```
184
185
### Performance Tuning
186
187
Configure index performance characteristics and memory usage.
188
189
```python { .api }
190
class Property:
191
pagesize: int
192
"""
193
Page size in bytes for disk storage (default: 4096).
194
195
Larger values may improve performance for large datasets.
196
Must be set before index creation.
197
"""
198
199
index_capacity: int
200
"""
201
Maximum number of entries per index node (default: 100).
202
203
Higher values create wider, shallower trees.
204
Lower values create narrower, deeper trees.
205
"""
206
207
leaf_capacity: int
208
"""
209
Maximum number of entries per leaf node (default: 100).
210
211
Affects query performance and storage efficiency.
212
"""
213
214
fill_factor: float
215
"""
216
Target fill factor for nodes (0.0 to 1.0).
217
218
Controls how full nodes should be before splitting.
219
Higher values improve storage efficiency but may hurt performance.
220
"""
221
222
buffering_capacity: int
223
"""
224
Buffer capacity for batched operations.
225
226
Higher values can improve bulk operation performance.
227
"""
228
```
229
230
Usage example:
231
232
```python
233
from rtree import index
234
235
# Performance tuning for large dataset
236
p = index.Property()
237
p.pagesize = 8192 # Larger pages
238
p.index_capacity = 200 # More entries per node
239
p.leaf_capacity = 200 # More entries per leaf
240
p.fill_factor = 0.9 # Pack nodes tightly
241
p.buffering_capacity = 1000 # Large buffer
242
243
idx = index.Index(properties=p)
244
```
245
246
### Memory Pool Configuration
247
248
Configure object pools for memory management optimization.
249
250
```python { .api }
251
class Property:
252
point_pool_capacity: int
253
"""
254
Capacity of the point object pool.
255
256
Pre-allocates point objects to reduce memory allocation overhead.
257
"""
258
259
region_pool_capacity: int
260
"""
261
Capacity of the region object pool.
262
263
Pre-allocates region objects to reduce memory allocation overhead.
264
"""
265
266
index_pool_capacity: int
267
"""
268
Capacity of the index object pool.
269
270
Pre-allocates index node objects.
271
"""
272
273
index_capacity: int
274
"""
275
Maximum number of entries per index node.
276
277
Controls the branching factor of internal nodes.
278
Higher values create wider, shallower trees.
279
"""
280
281
leaf_capacity: int
282
"""
283
Maximum number of entries per leaf node.
284
285
Controls how many data items are stored in each leaf.
286
Affects both query performance and storage efficiency.
287
"""
288
```
289
290
### Advanced Splitting Parameters
291
292
Fine-tune the node splitting algorithms for optimal performance.
293
294
```python { .api }
295
class Property:
296
near_minimum_overlap_factor: int
297
"""
298
Factor for near minimum overlap splitting in R*-Tree.
299
300
Controls the reinsertion strategy in R*-Tree variant.
301
Lower values may improve query performance.
302
"""
303
304
split_distribution_factor: float
305
"""
306
Distribution factor for node splitting (0.0 to 1.0).
307
308
Controls how evenly entries are distributed during splits.
309
0.5 = even distribution, other values bias the distribution.
310
"""
311
312
reinsert_factor: float
313
"""
314
Reinsertion factor for R*-Tree forced reinsertion (0.0 to 1.0).
315
316
Percentage of entries to reinsert during R*-Tree reorganization.
317
"""
318
```
319
320
### R-Tree Quality Control
321
322
Configure geometric and algorithmic quality parameters.
323
324
```python { .api }
325
class Property:
326
tight_mbr: bool
327
"""
328
Use tight minimum bounding rectangles (default: True).
329
330
When True, computes exact bounding boxes.
331
When False, may use loose bounding boxes for performance.
332
"""
333
```
334
335
### Custom Storage Configuration
336
337
Configure custom storage implementations.
338
339
```python { .api }
340
class Property:
341
custom_storage_callbacks: object
342
"""
343
Custom storage callback functions.
344
345
Pointer to callback structure for custom storage implementations.
346
"""
347
348
custom_storage_callbacks_size: int
349
"""
350
Size of custom storage callbacks structure.
351
352
Must match the size of the callback structure.
353
"""
354
```
355
356
### TPR-Tree Temporal Configuration
357
358
Configure temporal parameters for TPR-Tree moving object indexing.
359
360
```python { .api }
361
class Property:
362
tpr_horizon: float
363
"""
364
Time horizon for TPR-Tree trajectory prediction.
365
366
Maximum time into the future for which trajectories are predicted.
367
Only used when type = RT_TPRTree.
368
"""
369
```
370
371
Usage example:
372
373
```python
374
from rtree import index
375
376
# Configure TPR-Tree for moving objects
377
p = index.Property()
378
p.type = index.RT_TPRTree
379
p.tpr_horizon = 100.0
380
p.dimension = 2
381
382
tpr_idx = index.Index(properties=p)
383
```
384
385
### Index Identification
386
387
Assign identifiers to indexes for multi-index scenarios.
388
389
```python { .api }
390
class Property:
391
index_id: int
392
"""
393
Unique identifier for the index.
394
395
Useful when working with multiple indexes or custom storage.
396
"""
397
```
398
399
## Property Management
400
401
### Validation and Consistency
402
403
Properties are validated for consistency and valid ranges:
404
405
```python
406
from rtree import index
407
from rtree.exceptions import RTreeError
408
409
p = index.Property()
410
411
try:
412
p.pagesize = -1000 # Invalid negative value
413
except RTreeError as e:
414
print(f"Invalid property: {e}")
415
416
# Some properties are automatically adjusted for consistency
417
p.index_capacity = 50
418
p.leaf_capacity = 100
419
p.near_minimum_overlap_factor = 75 # May be auto-adjusted if >= min(index_capacity, leaf_capacity)
420
```
421
422
### Property Serialization
423
424
Properties can be serialized and restored:
425
426
```python
427
from rtree import index
428
429
# Create and configure properties
430
p = index.Property()
431
p.dimension = 3
432
p.pagesize = 8192
433
p.index_capacity = 200
434
435
# Serialize to dictionary
436
prop_dict = p.as_dict()
437
print(prop_dict)
438
439
# Restore from dictionary
440
p2 = index.Property()
441
p2.initialize_from_dict(prop_dict)
442
```
443
444
### Common Configuration Patterns
445
446
#### High-Performance Configuration
447
```python
448
from rtree import index
449
450
# Optimized for query performance
451
p = index.Property()
452
p.variant = index.RT_Star # Best splitting quality
453
p.index_capacity = 50 # Smaller nodes for better queries
454
p.leaf_capacity = 50 # Smaller leaves
455
p.buffering_capacity = 10000 # Large buffer
456
p.tight_mbr = True # Exact bounding boxes
457
458
idx = index.Index(properties=p)
459
```
460
461
#### Memory-Efficient Configuration
462
```python
463
from rtree import index
464
465
# Optimized for memory usage
466
p = index.Property()
467
p.variant = index.RT_Linear # Fastest splitting
468
p.index_capacity = 200 # Larger nodes
469
p.leaf_capacity = 200 # Larger leaves
470
p.fill_factor = 0.95 # Pack tightly
471
p.buffering_capacity = 100 # Small buffer
472
473
idx = index.Index(properties=p)
474
```
475
476
#### Disk-Based Large Dataset Configuration
477
```python
478
from rtree import index
479
480
# Optimized for large disk-based datasets
481
p = index.Property()
482
p.storage = index.RT_Disk
483
p.filename = "large_dataset"
484
p.pagesize = 16384 # Large pages
485
p.index_capacity = 500 # Very large nodes
486
p.leaf_capacity = 500 # Very large leaves
487
p.writethrough = False # Buffer writes
488
p.overwrite = True # Clean start
489
490
idx = index.Index(properties=p)
491
```