Skip to content

fastquadtree.pyqtree.Index

Pyqtree-compatible spatial index with improved performance.

This class provides the same interface as pyqtree.Index but is backed by a high-performance Rust implementation. Based on benchmarks, this provides an overall performance boost of approximately 10x compared to the original pure-Python implementation.

For new projects not requiring pyqtree compatibility, consider using RectQuadTreeObjects for more control and better performance.

Parameters:

Name Type Description Default
bbox Iterable[SupportsFloat] | None

Coordinate system bounding box as (xmin, ymin, xmax, ymax).

 None
x float | int | None

X center coordinate (alternative to bbox).

 None
y float | int | None

Y center coordinate (alternative to bbox).

 None
width float | int | None

Width from center (alternative to bbox).

 None
height float | int | None

Height from center (alternative to bbox).

 None
max_items int

Maximum items per quad before splitting (default: 10).

 MAX_ITEMS
max_depth int

Maximum nesting levels (default: 20).

 MAX_DEPTH
Note

Either bbox or all of (x, y, width, height) must be provided.

Example 
from fastquadtree.pyqtree import Index

spindex = Index(bbox=(0, 0, 100, 100))
spindex.insert('duck', (50, 30, 53, 60))
spindex.insert('cookie', (10, 20, 15, 25))
spindex.insert('python', (40, 50, 95, 90))
results = spindex.intersect((51, 51, 86, 86))
print(sorted(results))  # ['duck', 'python']

Initialize the spatial index.

Specify either a bounding box or center point with dimensions.

Parameters:

Name Type Description Default
bbox Iterable[SupportsFloat] | None

Bounding box as (xmin, ymin, xmax, ymax).

 None
x float | int | None

X center coordinate (alternative to bbox).

 None
y float | int | None

Y center coordinate (alternative to bbox).

 None
width float | int | None

Distance from x center to edges (alternative to bbox).

 None
height float | int | None

Distance from y center to edges (alternative to bbox).

 None
max_items int

Maximum items per quad before splitting (default: 10).

 MAX_ITEMS
max_depth int

Maximum nesting levels (default: 20).

 MAX_DEPTH

Raises:

Type Description
ValueError

If neither bbox nor (x, y, width, height) are provided.

insert(item, bbox)

Insert an item with its bounding box.

Parameters:

Name Type Description Default
item Any

Item to insert (will be returned by intersect queries).

 required
bbox Iterable[SupportsFloat]

Spatial bounding box as (xmin, ymin, xmax, ymax).

 required

remove(item, bbox)

Remove an item from the index.

Parameters:

Name Type Description Default
item Any

Item to remove (must match the inserted item).

 required
bbox Iterable[SupportsFloat]

Bounding box as (xmin, ymin, xmax, ymax) (must match insertion).

 required
Note

Both parameters must exactly match those used during insertion.

intersect(bbox)

Query items that intersect with a bounding box.

Parameters:

Name Type Description Default
bbox Iterable[SupportsFloat]

Query bounding box as (xmin, ymin, xmax, ymax).

 required

Returns:

Type Description
list

List of items whose bounding boxes intersect the query box.