kdbush

What is kdbush?

kdbush is a high-performance JavaScript library for creating and querying static spatial indexes using a k-d tree. It is particularly useful for handling large sets of 2D points and performing fast nearest neighbor searches.

What are kdbush's main functionalities?

Creating a spatial index

This feature allows you to create a spatial index from an array of 2D points. The index can then be used for efficient spatial queries.

const KDBush = require('kdbush');
const points = [
  [20, 30],
  [40, 50],
  [10, 15],
  [25, 35]
];
const index = new KDBush(points);

Performing a range search

This feature allows you to perform a range search on the spatial index. The `range` method returns all points within the specified bounding box.

const KDBush = require('kdbush');
const points = [
  [20, 30],
  [40, 50],
  [10, 15],
  [25, 35]
];
const index = new KDBush(points);
const results = index.range(10, 10, 30, 40);

Performing a nearest neighbor search

This feature allows you to perform a nearest neighbor search on the spatial index. The `within` method returns all points within a specified radius from a given point.

const KDBush = require('kdbush');
const points = [
  [20, 30],
  [40, 50],
  [10, 15],
  [25, 35]
];
const index = new KDBush(points);
const nearest = index.within(20, 30, 10);

Other packages similar to kdbush

rbush

rbush is a high-performance JavaScript library for 2D spatial indexing of points and rectangles using an R-tree. It is similar to kdbush but uses an R-tree data structure, which can be more efficient for certain types of spatial queries, especially when dealing with rectangles.

geokdbush

geokdbush is a geospatial extension of kdbush that adds support for geographic coordinates (latitude and longitude). It provides similar functionality to kdbush but is specifically designed for geospatial data, making it more suitable for applications involving geographic information.

flatbush

flatbush is a fast static spatial index for 2D points and rectangles, similar to kdbush. It uses a flat R-tree data structure and is optimized for read-heavy workloads. It can be more efficient than kdbush for certain types of spatial queries, particularly when dealing with large datasets.

README

kdbush

A very fast static spatial index for 2D points based on a flat KD-tree. Compared to RBush:

• points only — no rectangles
• static — you can't add/remove items
• indexing is 5-8 times faster

var index = kdbush(points);              // make an index
var ids1 = index.range(10, 10, 20, 20);  // bbox search - minX, minY, maxX, maxY
var ids2 = index.within(10, 10, 5);      // radius search - x, y, radius

Install

Install using NPM (npm install kdbush) or Yarn (yarn add kdbush), then:

// import as a ES module
import kdbush from 'kdbush';

// or require in Node / Browserify
const kdbush = require('kdbush');

Or use a browser build directly:

<script src="https://unpkg.com/kdbush@2.0.0/kdbush.min.js"></script>

API

kdbush(points[, getX, getY, nodeSize, arrayType])

Creates an index from the given points.

• points: Input array of points.
• getX, getY: Functions to get x and y from an input point. By default, it assumes [x, y] format.
• nodeSize: Size of the KD-tree node, 64 by default. Higher means faster indexing but slower search, and vise versa.
• arrayType: Array type to use for storing indices and coordinate values. Array by default, but if your coordinates are integer values, Int32Array makes things a bit faster.

var index = kdbush(points, (p) => p.x, (p) => p.y, 64, Int32Array);

range(minX, minY, maxX, maxY)

Finds all items within the given bounding box and returns an array of indices that refer to the items in the original points input array.

var results = index.range(10, 10, 20, 20).map((id) => points[id]);

within(x, y, radius)

Finds all items within a given radius from the query point and returns an array of indices.

var results = index.within(10, 10, 5).map((id) => points[id]);