or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

advanced-features.mdconfiguration.mdcontainer.mdcore-indexing.mdcustom-storage.mdindex.mdutilities.md
tile.json

tessl/pypi-rtree

R-Tree spatial index for Python GIS

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/rtree@1.4.x

To install, run

npx @tessl/cli install tessl/pypi-rtree@1.4.0

index.mddocs/

Rtree

Rtree provides Python bindings to libspatialindex for spatial indexing operations. It enables efficient storage and querying of spatial data using R-Tree data structures, supporting advanced features like nearest neighbor search, intersection queries, bulk operations, and custom storage implementations.

Package Information

  • Package Name: rtree
  • Language: Python
  • Installation: pip install rtree

Core Imports

import rtree
from rtree import index

Common import patterns:

from rtree.index import Index, Rtree, Property
from rtree.exceptions import RTreeError

Import constants for configuration:

from rtree.index import RT_RTree, RT_MVRTree, RT_TPRTree
from rtree.index import RT_Linear, RT_Quadratic, RT_Star
from rtree.index import RT_Memory, RT_Disk, RT_Custom

Basic Usage

from rtree import index

# Create a new spatial index
idx = index.Index()

# Insert some spatial objects
idx.insert(0, (0, 0, 1, 1))  # id, (minx, miny, maxx, maxy)
idx.insert(1, (0.5, 0.5, 1.5, 1.5))
idx.insert(2, (1, 1, 2, 2))

# Query for intersections
hits = list(idx.intersection((0.5, 0.5, 1.5, 1.5)))
print(hits)  # [0, 1, 2]

# Find nearest neighbors
nearest = list(idx.nearest((0.25, 0.25), 2))
print(nearest)  # [0, 1]

# Store objects with spatial data
idx_with_objects = index.Index()
idx_with_objects.insert(0, (0, 0, 1, 1), obj="First polygon")
idx_with_objects.insert(1, (2, 2, 3, 3), obj="Second polygon")

# Query with objects
for hit in idx_with_objects.intersection((0, 0, 1, 1), objects=True):
    print(f"ID: {hit.id}, Object: {hit.object}, Bounds: {hit.bounds}")

Architecture

Rtree's architecture consists of several key components:

  • Index Class: Main spatial index implementation supporting R-Tree, MVR-Tree, and TPR-Tree variants
  • Property Class: Configuration object for index properties and performance tuning
  • Item Class: Container for query results that includes ID, stored object, and bounding box
  • Storage Backends: Support for memory-based, disk-based, and custom storage implementations
  • Query Engine: Efficient spatial queries including intersection, containment, nearest neighbor, and counting

The library serves as a bridge between Python's ecosystem and high-performance spatial indexing operations with cross-platform compatibility.

Capabilities

Core Indexing Operations

Fundamental spatial indexing functionality including inserting, deleting, and querying spatial data. Supports intersection queries, containment tests, nearest neighbor search, and counting operations.

def insert(id: int, coordinates: Any, obj: object = None) -> None: ...
def delete(id: int, coordinates: Any) -> None: ...
def intersection(coordinates: Any, objects: bool | Literal["raw"] = False) -> Iterator: ...
def nearest(coordinates: Any, num_results: int = 1, objects: bool | Literal["raw"] = False) -> Iterator: ...
def count(coordinates: Any) -> int: ...

Core Indexing Operations

Advanced Features

Advanced spatial indexing capabilities including bulk operations with NumPy integration, custom storage implementations, TPR-Tree temporal indexing, object-oriented containers, and set operations between indexes.

def intersection_v(mins, maxs): ...
def nearest_v(mins, maxs, *, num_results=1, max_dists=None, strict=False, return_max_dists=False): ...
class ICustomStorage: ...
class RtreeContainer: ...
def __and__(other: Index) -> Index: ...
def __or__(other: Index) -> Index: ...

Advanced Features

Configuration and Properties

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.

class Property:
    def __init__(handle=None, owned: bool = True, **kwargs: Any) -> None: ...
    type: int  # RT_RTree, RT_MVRTree, RT_TPRTree
    variant: int  # RT_Linear, RT_Quadratic, RT_Star
    dimension: int
    storage: int  # RT_Memory, RT_Disk, RT_Custom

Configuration and Properties

Utilities and Support

Utility functions for library management, exception handling, coordinate format conversion, and serialization support.

def load() -> ctypes.CDLL: ...
def get_include() -> str: ...
class RTreeError(Exception): ...
def interleave(deinterleaved: Sequence[float]) -> list[float]: ...
def deinterleave(interleaved: Sequence[object]) -> list[object]: ...

Utilities and Support

Types

class Index:
    def __init__(self, *args: Any, **kwargs: Any) -> None: ...
    interleaved: bool
    properties: Property
    bounds: list[float]
    result_limit: int
    result_offset: int

Rtree = Index  # Alias for backward compatibility

class Item:
    id: int
    object: object
    bounds: list[float]
    bbox: list[float]

class Property:
    type: int
    variant: int
    dimension: int
    storage: int
    pagesize: int
    index_capacity: int
    leaf_capacity: int
    overwrite: bool
    writethrough: bool
    fill_factor: float

class RTreeError(Exception):
    pass

class InvalidHandleException(Exception):
    pass

class RtreeContainer:
    def __init__(self, *args: Any, **kwargs: Any) -> None: ...
    def insert(self, obj: object, coordinates: Any) -> None: ...
    def delete(self, obj: object, coordinates: Any) -> None: ...
    def intersection(self, coordinates: Any, bbox: bool = False) -> Iterator: ...
    def nearest(self, coordinates: Any, num_results: int = 1, bbox: bool = True) -> Iterator: ...

# Constants
RT_RTree: int      # = 0
RT_MVRTree: int    # = 1  
RT_TPRTree: int    # = 2

RT_Linear: int     # = 0
RT_Quadratic: int  # = 1
RT_Star: int       # = 2

RT_Memory: int     # = 0
RT_Disk: int       # = 1
RT_Custom: int     # = 2