#algorithms #spatial #geometry #grid #data-structures


Flat spatial partitionning algorithms and data structures

8 releases

new 0.3.5 Aug 5, 2020
0.3.4 Aug 4, 2020
0.3.1 Jul 31, 2020
0.2.0 Jul 18, 2020
0.1.3 May 26, 2020

#121 in Algorithms

Download history 41/week @ 2020-05-21 34/week @ 2020-05-28 19/week @ 2020-06-04 17/week @ 2020-06-11 17/week @ 2020-06-18 5/week @ 2020-06-25 12/week @ 2020-07-02 17/week @ 2020-07-09 18/week @ 2020-07-16 18/week @ 2020-07-23 155/week @ 2020-07-30

117 downloads per month

MIT license

1.5K SLoC


Build Status Crates.io Docs.rs

flat_spatial is a crate dedicated to dynamic spatial partitioning structures that are not based on trees (which are recursive) but on simple flat structures such as a grid/hashmap of cells.
Using grids or other flat structures makes for very fast updates (constant time) and even fast queries, provided the cell size is adapted to the problem.


The idea of a dense grid is to have an array of cells which store the positions of the inserted objects.
Performing queries is as simple as looking up which cells are affected and returning their associated objects.
Since it's so simple, the dense grid supports dynamic capabilities such as position update or object removal based on handles (using slotmap).

It is recommended to have queries roughly the same size as the cell size.


The SparseGrid is very similar to the DenseGrid, only that it uses a HashMap of cells instead of a vector. That way, unused space has zero overhead and no reallocation is necessary when points get out of the boundary, only when the HashMap runs out of space.

On the flip side, this makes queries/maintaining slightly slower since positions need to be hashed to find the corresponding cell.


Here's some basic benchmarks of densegrid vs rstar's r-trees using criterion:

The first one adds 100'000 random points on a 500x500 square and perform n random queries of radius 5.

denseGridN means the structure is a DenseGrid where cells are of size N.

Time is shown per query, lower is better:

query benchmark

The second benchmark tries to change the position of n objects in a 500x500 square.

For an r-tree, it means building it up from scratch.
For a DenseGrid, set_position is used on all handles with a new random position then maintain() is called.

Time is shown per object, lower is better:

maintain benchmark

Note: In both benchmarks, r-trees and densegrids are linear in number of objects/queries. That's why it makes sense to show the average time per object/per query.


Here is a very basic example of densegrid:

fn main() {
    use flat_spatial::DenseGrid;
    let mut g: DenseGrid<()> = DenseGrid::new(10);
    let a = g.insert([3.0, 3.0], ());
    let _b = g.insert([12.0, -8.0], ());
    let around: Vec<_> = g.query_around([2.0, 2.0], 5.0)
                          .map(|(id, _pos)| id)
    assert_eq!(vec![a], around);