Class Documentation

class rtree.index.Index(*args, **kwargs)

An R-Tree, MVR-Tree, or TPR-Tree indexing object

__init__(*args, **kwargs)

Creates a new index

Parameters:

• filename – The first argument in the constructor is assumed to be a filename determining that a file-based storage for the index should be used. If the first argument is not of type basestring, it is then assumed to be an instance of ICustomStorage or derived class. If the first argument is neither of type basestring nor an instance of ICustomStorage, it is then assumed to be an input index item stream.
• stream –

  If the first argument in the constructor is not of type basestring, it is assumed to be an iterable stream of data that will raise a StopIteration. It must be in the form defined by the interleaved attribute of the index. The following example would assume interleaved is False:

  (id, (minx, maxx, miny, maxy, minz, maxz, ..., ..., mink, maxk), object)
  

  The object can be None, but you must put a place holder of None there.

• storage – If the first argument in the constructor is an instance of ICustomStorage then the given custom storage is used.
• interleaved – True or False, defaults to True. This parameter determines the coordinate order for all methods that take in coordinates.
• properties – An index.Property object This object sets both the creation and instantiation properties for the object and they are passed down into libspatialindex. A few properties are curried from instantiation parameters for you like pagesize and overwrite to ensure compatibility with previous versions of the library. All other properties must be set on the object.

Warning

The coordinate ordering for all functions are sensitive the the index’s interleaved data member. If interleaved is False, the coordinates must be in the form [xmin, xmax, ymin, ymax, ..., ..., kmin, kmax]. If interleaved is True, the coordinates must be in the form [xmin, ymin, ..., kmin, xmax, ymax, ..., kmax].

A basic example

>>> from rtree import index
>>> p = index.Property()

>>> idx = index.Index(properties=p)
>>> idx  
<rtree.index.Index object at 0x...>

Insert an item into the index:

>>> idx.insert(4321, (34.3776829412, 26.7375853734, 49.3776829412, 41.7375853734), obj=42)

Query:

>>> hits = idx.intersection((0, 0, 60, 60), objects=True)
>>> for i in hits:
...     if i.id == 4321:
...         i.object
...         i.bbox
42
[34.3776829412, 26.737585373400002, 49.3776829412, 41.737585373400002]

Using custom serializers

>>> import simplejson
>>> class JSONIndex(index.Index):
...     dumps = staticmethod(simplejson.dumps)
...     loads = staticmethod(simplejson.loads)

>>> json_idx = JSONIndex()
>>> json_idx.insert(1, (0, 1, 0, 1), {"nums": [23, 45], "letters": "abcd"})
>>> list(json_idx.nearest((0, 0), 1, objects="raw"))
[{'letters': 'abcd', 'nums': [23, 45]}]

insert(id, coordinates, obj=None)

Inserts an item into the index with the given coordinates.

Parameters:

• id – long integer A long integer that is the identifier for this index entry. IDs need not be unique to be inserted into the index, and it is up to the user to ensure they are unique if this is a requirement.
• coordinates – sequence or array This may be an object that satisfies the numpy array protocol, providing the index’s dimension * 2 coordinate pairs representing the mink and maxk coordinates in each dimension defining the bounds of the query window.
• obj – a pickleable object. If not None, this object will be stored in the index with the id.

The following example inserts an entry into the index with id 4321, and the object it stores with that id is the number 42. The coordinate ordering in this instance is the default (interleaved=True) ordering:

>>> from rtree import index
>>> idx = index.Index()
>>> idx.insert(4321, (34.3776829412, 26.7375853734, 49.3776829412, 41.7375853734), obj=42)

intersection(coordinates, objects=False)

Return ids or objects in the index that intersect the given coordinates.

Parameters:

• coordinates – sequence or array This may be an object that satisfies the numpy array protocol, providing the index’s dimension * 2 coordinate pairs representing the mink and maxk coordinates in each dimension defining the bounds of the query window.
• objects – True or False or ‘raw’ If True, the intersection method will return index objects that were pickled when they were stored with each index entry, as well as the id and bounds of the index entries. If ‘raw’, the objects will be returned without the rtree.index.Item wrapper.

The following example queries the index for any objects any objects that were stored in the index intersect the bounds given in the coordinates:

>>> from rtree import index
>>> idx = index.Index()
>>> idx.insert(4321, (34.3776829412, 26.7375853734, 49.3776829412, 41.7375853734), obj=42)

>>> hits = list(idx.intersection((0, 0, 60, 60), objects=True))
>>> [(item.object, item.bbox) for item in hits if item.id == 4321]
[(42, [34.3776829412, 26.737585373400002, 49.3776829412, 41.737585373400002])]

If the rtree.index.Item wrapper is not used, it is faster to request the ‘raw’ objects:

>>> list(idx.intersection((0, 0, 60, 60), objects="raw"))
[42]

nearest(coordinates, num_results=1, objects=False)

Returns the k-nearest objects to the given coordinates.

Parameters:

• coordinates – sequence or array This may be an object that satisfies the numpy array protocol, providing the index’s dimension * 2 coordinate pairs representing the mink and maxk coordinates in each dimension defining the bounds of the query window.
• num_results – integer The number of results to return nearest to the given coordinates. If two index entries are equidistant, both are returned. This property means that num_results may return more items than specified
• objects – True / False / ‘raw’ If True, the nearest method will return index objects that were pickled when they were stored with each index entry, as well as the id and bounds of the index entries. If ‘raw’, it will return the object as entered into the database without the rtree.index.Item wrapper.

Example of finding the three items nearest to this one:

>>> from rtree import index
>>> idx = index.Index()
>>> idx.insert(4321, (34.37, 26.73, 49.37, 41.73), obj=42)
>>> hits = idx.nearest((0, 0, 10, 10), 3, objects=True)

delete(id, coordinates)

Deletes items from the index with the given 'id' within the specified coordinates.

Parameters:

• id – long integer A long integer that is the identifier for this index entry. IDs need not be unique to be inserted into the index, and it is up to the user to ensure they are unique if this is a requirement.
• coordinates – sequence or array Dimension * 2 coordinate pairs, representing the min and max coordinates in each dimension of the item to be deleted from the index. Their ordering will depend on the index’s interleaved data member. These are not the coordinates of a space containing the item, but those of the item itself. Together with the id parameter, they determine which item will be deleted. This may be an object that satisfies the numpy array protocol.

Example:

>>> from rtree import index
>>> idx = index.Index()
>>> idx.delete(4321, (34.3776829412, 26.7375853734, 49.3776829412, 41.7375853734) )

bounds

Returns the bounds of the index

Parameters:coordinate_interleaved – If True, the coordinates are turned in the form [xmin, ymin, ..., kmin, xmax, ymax, ..., kmax], otherwise they are returned as [xmin, xmax, ymin, ymax, ..., ..., kmin, kmax]. If not specified, the interleaved member of the index is used, which defaults to True.

count(coordinates)

Return number of objects that intersect the given coordinates.

Parameters:coordinates – sequence or array This may be an object that satisfies the numpy array protocol, providing the index’s dimension * 2 coordinate pairs representing the mink and maxk coordinates in each dimension defining the bounds of the query window.

The following example queries the index for any objects any objects that were stored in the index intersect the bounds given in the coordinates:

>>> from rtree import index
>>> idx = index.Index()
>>> idx.insert(4321, (34.3776829412, 26.7375853734, 49.3776829412, 41.7375853734), obj=42)

>>> idx.count((0, 0, 60, 60))
1

close()

Force a flush of the index to storage. Renders index inaccessible.

dumps()

dumps(obj, protocol=0) – Return a string containing an object in pickle format.

See the Pickler docstring for the meaning of optional argument proto.

loads()

loads(string) – Load a pickle from the given string

class rtree.index.Property(handle=None, owned=True)

An index property object is a container that contains a number of settable index properties. Many of these properties must be set at index creation times, while others can be used to adjust performance or behavior.

buffering_capacity

Buffering capacity

custom_storage_callbacks

Callbacks for custom storage

custom_storage_callbacks_size

Size of callbacks for custom storage

dat_extension

Extension for .dat file

dimension

Index dimension. Must be greater than 0, though a dimension of 1 might have undefined behavior.

filename

Index filename for disk storage

fill_factor

Index node fill factor before branching

idx_extension

Extension for .idx file

index_capacity

Index capacity

index_id

First node index id

index_pool_capacity

Index pool capacity

leaf_capacity

Leaf capacity

near_minimum_overlap_factor

Overlap factor for MVRTrees

overwrite

Overwrite existing index files

pagesize

The pagesize when disk storage is used. It is ideal to ensure that your index entries fit within a single page for best performance.

point_pool_capacity

Point pool capacity

region_pool_capacity

Region pool capacity

reinsert_factor

Reinsert factor

split_distribution_factor

Split distribution factor

storage

Index storage. One of RT_Disk, RT_Memory or RT_Custom. If a filename is passed as the first parameter to :class:index.Index, RT_Disk is assumed. If a CustomStorage instance is passed, RT_Custom is assumed. Otherwise, RT_Memory is the default.

tight_mbr

Uses tight bounding rectangles

tpr_horizon

TPR horizon

type

Index type. Valid index type values are RT_RTree, RT_MVTree, or RT_TPRTree. Only RT_RTree (the default) is practically supported at this time.

variant

Index variant. Valid index variant values are RT_Linear, RT_Quadratic, and RT_Star

writethrough

Write through caching

class rtree.index.Item(loads, handle, owned=False)

A container for index entries

__init__(loads, handle, owned=False)

There should be no reason to instantiate these yourself. Items are created automatically when you call rtree.index.Index.intersection() (or other index querying methods) with objects=True given the parameters of the function.

bbox

Returns the bounding box of the index entry