tessl/pypi-rtree

R-Tree spatial index for Python GIS

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

Rtree

Name: tessl/pypi-rtree
Author: tessl

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

Container Interface

High-level container for storing Python objects with spatial coordinates, providing automatic ID management and object-centric operations.

class RtreeContainer:
    def __init__(self, *args, **kwargs): ...
    def insert(self, obj, coordinates): ...
    def delete(self, obj): ...

Container Interface

Custom Storage Framework

Interface and base classes for implementing custom storage backends, enabling integration with databases, cloud storage, or specialized data structures.

class ICustomStorage:
    NoError = 0
    InvalidPageError = 1
    def registerCallbacks(self, properties): ...

Custom Storage Framework

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

Install with Tessl CLI