Home

Awesome

LibSpatialIndex

CI Coverage Status

LibSpatialIndex.jl is a julia wrapper around the C API of libspatialindex, for spatially indexing kD bounding box data. The Julia library (JLL) package is produced by the script at https://github.com/JuliaPackaging/Yggdrasil/tree/master/L/LibSpatialIndex and the resulting binary artifact is downloaded from https://github.com/JuliaBinaryWrappers/LibSpatialIndex_jll.jl.

Quick Guide

A new RTree with 2 dimensions can be created using this package as follows:

import LibSpatialIndex
rtree = LibSpatialIndex.RTree(2)

Insertion

Items can be inserted using the insert! method, where:

LibSpatialIndex.insert!(rtree, 1, [0.0, 0.0], [1.0, 1.0])
LibSpatialIndex.insert!(rtree, 2, Extexts.Extent(X=(0.0, 2.0), (0.0, 2.0)))

inserts two items,

Queries

Thereafter, you can perform queries on the rtree using either (i) intersects(rtree, minvalues, maxvalues) for all items intersecting the box specified by minvalues and maxvalues, or (ii) knn(rtree, minvalues, maxvalues, k) for the k nearest items in rtree to the box specified by minvalues and maxvalues.

Intersection

So for instance:

LibSpatialIndex.intersects(rtree, [0.0, 0.0], [1.0, 1.0])
LibSpatialIndex.intersects(rtree, Extents.extent(X=(0.0, 1.0), Y=(0.0, 1.0)))

will return the vector [1, 2] on the rtree constructed earlier, to indicate that items with ids 1 and 2 intersects the box specified by [xmin=0.0, ymin=0.0] and [xmax=1.0, ymax=1.0].

Any GeoInterface.jl or Extents.jl compatible object can be used directly instead of defining the Extent manually - the extent will either be detected or calculated.

You can also perform queries on any individual GeoInterface.jl compatible point, so:

LibSpatialIndex.intersects(rtree, (1.0, 1.0))

will return the ids [1, 2] in the rtree constructed earlier, and:

LibSpatialIndex.intersects(rtree, [2.0, 2.0])

will only return the vector [2], because item 1 does not contain the point [2.0, 2.0].

k Nearest Neighbors

For knn queries:

LibSpatialIndex.knn(rtree, [2.0, 2.0], 1)

returns the vector [2] because the item with id 2 is closest to the point [2.0, 2.0], and

sort(LibSpatialIndex.knn(rtree, [2.0, 2.0], 2))

returns the vector [1, 2]. If the value of k exceeds the number of items in the rtree, then fewer than k items will be returned, so:

sort(SI.knn(rtree, [2.0, 2.0], 3))

will return the vector [1, 2].