教程¶
本教程演示如何利用 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> 但是还是有用的。考虑到自己受到警告。现在去用它做一些酷的事情。
将索引序列化为文件¶
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”_