教程

本教程演示如何利用 Rtree 用于查詢具有可建模為邊界框的空間組件的數據。

創建索引

以下部分描述了 Rtree .

輸入

參考:ref:installing <installation> Rtree 后，您應該能夠打開一個python提示并發出以下命令：

>>> from rtree import index

rtree 被組織為一個包含兩個模塊和兩個主要類的python包- rtree.index.Index 和 rtree.index.Property . 用戶操縱這些類與索引交互。

構造實例

導入索引模塊后，使用默認構造構造一個索引：

>>> idx = index.Index()

注解

雖然默認構造在許多情況下很有用，但如果要操縱索引的構造方式，則需要在創建索引時傳入：py：class：`rtree.index.Property`實例。

創建邊界框

實例化索引后，創建一個可以插入索引的邊界框：：

>>> left, bottom, right, top = (0.0, 0.0, 1.0, 1.0)

注解

所有函數的坐標順序都是敏感的，索引的:py:attr: ' ~rtree.index.Index.interleaved '數據成員。如果:py:attr: ' ~rtree.index.Index.interleaved '為False，則坐標必須為[xmin, xmax, ymin, ymax，…,……、kmin kmax]。如果:py:attr: ' ~rtree.index.Index.interleaved '為真，則坐標必須為[xmin, ymin，…， kmin, xmax, ymax，…,kmax]。

將記錄插入索引

在索引中插入一個條目：：

>>> idx.insert(0, (left, bottom, right, top))

注解

插入到索引中的條目在 id 或插入索引項的邊界框。如果需要保持唯一性，則需要在將條目插入到rtree之前對其進行管理。

注解

插入一個點，即左==右&&上==下，基本上將在索引中插入一個單點條目，而不是復制額外的坐標并插入它們。但是，沒有任何快捷方式可以顯式插入單個點。

查詢索引

查詢索引有三種主要方法。:py:meth: ' rtree.index. index.交集'將返回在給定查詢窗口中*cross*或* include *的索引條目。 rtree.index.Index.intersection()

交叉

給定一個查詢窗口，返回包含在該窗口中的ID:：

>>> list(idx.intersection((1.0, 1.0, 2.0, 2.0)))
[0]

給定一個超出索引中數據邊界的查詢窗口：

>>> list(idx.intersection((1.0000001, 1.0000001, 2.0, 2.0)))
[]

最近的鄰居

下面查找與給定界限最近的1個項。如果多個項目與邊界的距離相等，則返回兩個項目：：

>>> idx.insert(1, (left, bottom, right, top))
>>> list(idx.nearest((1.0000001, 1.0000001, 2.0, 2.0), 1))
[0, 1]

使用rtree作為廉價的空間數據庫

Rtree還支持將任何可以pickle的對象插入索引(在' libspatialindex ' _行話中稱為聚集索引)。下面用給定的id將picklable對象' ' 42 ' '插入索引:

>>> idx.insert(id=id, bounds=(left, bottom, right, top), obj=42)

然后，你可以通過給``objects = True``標志交叉來返回一個對象列表:

>>> [n.object for n in idx.intersection((left, bottom, right, top), objects=True)]
[None, None, 42]

警告

libspatialindex`_的聚簇索引不是設計為數據庫的。您沒有得到任何數據庫聲稱提供的數據完整性保護，但是參閱:`Rtree <home> 但是還是有用的?？紤]到自己受到警告?，F在去用它做一些酷的事情。

將索引序列化為文件

ref:`Rtree <home>中最有用的一個的屬性是能夠將rtree索引序列化到磁盤。其中包括描述的聚集索引 :ref:`here <clustered> ：：

>>> file_idx = index.Rtree('rtree')
>>> file_idx.insert(1, (left, bottom, right, top))
>>> file_idx.insert(2, (left - 1.0, bottom - 1.0, right + 1.0, top + 1.0))
>>> [n for n in file_idx.intersection((left, bottom, right, top))]
[1, 2]

注解

默認情況下，如果文件系統中已存在上例中具有給定名稱“rtree”的索引文件，則它將以追加模式打開而不能重新創建。 您可以使用index屬性的：py：attr：`rtree.index.Property.overwrite`屬性來控制此行為，該屬性可以賦予：py：class：`rtree.index.Index`構造函數。

參見

：ref：`performance`描述了一些可以調整的參數，使基于文件的索引運行得更快一些。 您為參數做出的選擇完全取決于您的使用情況。

修改文件名

Rtree默認使用擴展名`dat`和`idx`作為將索引數據序列化到磁盤時創建的兩個索引文件。 這些文件擴展名可以使用：py：attr：`rtree.index.Property.dat_extension`和：py：attr：`rtree.index.Property.idx_extension`索引屬性進行控制。

>>> p = rtree.index.Property()
>>> p.dat_extension = 'data'
>>> p.idx_extension = 'index'
>>> file_idx = index.Index('rtree', properties = p)

三維索引

從0.5.0版的rtree開始，您可以創建3d（實際上是kd）索引。以下是要存儲在磁盤上的三維索引。持久化索引使用兩個文件（索引文件（.idx）和數據（.dat）文件）存儲在磁盤上。您可以通過在實例化時更改索引的屬性來修改這些文件使用的擴展名。下面創建一個三維索引，該索引作為文件存儲在磁盤上 3d_index.data 和 3d_index.index ：：

>>> from rtree import index
>>> p = index.Property()
>>> p.dimension = 3
>>> p.dat_extension = 'data'
>>> p.idx_extension = 'index'
>>> idx3d = index.Index('3d_index',properties=p)
>>> idx3d.insert(1, (0, 0, 60, 60, 23.0, 42.0))
>>> idx3d.intersection( (-1, -1, 62, 62, 22, 43))
[1L]

ZODB和自定義存儲

https://mail.zope.org/pipermail/zodb-dev/2010-June/013491.html包含一個自定義存儲后端，用于“ZODB”_