{"id":13426421,"url":"https://github.com/mourner/rbush","last_synced_at":"2025-05-13T16:06:16.246Z","repository":{"id":9312197,"uuid":"11153124","full_name":"mourner/rbush","owner":"mourner","description":"RBush — a high-performance JavaScript R-tree-based 2D spatial index for points and rectangles","archived":false,"fork":false,"pushed_at":"2024-09-24T09:18:11.000Z","size":485,"stargazers_count":2544,"open_issues_count":11,"forks_count":247,"subscribers_count":51,"default_branch":"main","last_synced_at":"2025-04-08T08:10:48.558Z","etag":null,"topics":["algorithm","computational-geometry","javascript","r-tree","spatial-index"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mourner.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2013-07-03T14:42:59.000Z","updated_at":"2025-04-08T07:28:00.000Z","dependencies_parsed_at":"2023-12-15T22:00:51.813Z","dependency_job_id":"d8f92258-c337-4683-b470-248d43a418cb","html_url":"https://github.com/mourner/rbush","commit_stats":{"total_commits":283,"total_committers":18,"mean_commits":"15.722222222222221","dds":"0.16607773851590102","last_synced_commit":"df39bd9774c7ee3680872aa33d95ecae0c100f0a"},"previous_names":[],"tags_count":18,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mourner%2Frbush","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mourner%2Frbush/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mourner%2Frbush/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mourner%2Frbush/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mourner","download_url":"https://codeload.github.com/mourner/rbush/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250496991,"owners_count":21440231,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["algorithm","computational-geometry","javascript","r-tree","spatial-index"],"created_at":"2024-07-31T00:01:34.114Z","updated_at":"2025-04-23T20:37:31.700Z","avatar_url":"https://github.com/mourner.png","language":"JavaScript","readme":"RBush\n=====\n\nRBush is a high-performance JavaScript library for 2D **spatial indexing** of points and rectangles.\nIt's based on an optimized **R-tree** data structure with **bulk insertion** support.\n\n*Spatial index* is a special data structure for points and rectangles\nthat allows you to perform queries like \"all items within this bounding box\" very efficiently\n(e.g. hundreds of times faster than looping over all items).\nIt's most commonly used in maps and data visualizations.\n\n[![Node](https://github.com/mourner/rbush/actions/workflows/node.yml/badge.svg)](https://github.com/mourner/rbush/actions/workflows/node.yml)\n[![](https://img.shields.io/badge/simply-awesome-brightgreen.svg)](https://github.com/mourner/projects)\n![](https://img.shields.io/bundlephobia/minzip/rbush)\n\n## Demos\n\nThe demos contain visualization of trees generated from 50k bulk-loaded random points.\nOpen web console to see benchmarks;\nclick on buttons to insert or remove items;\nclick to perform search under the cursor.\n\n* [randomly clustered data](http://mourner.github.io/rbush/viz/viz-cluster.html)\n* [uniformly distributed random data](http://mourner.github.io/rbush/viz/viz-uniform.html)\n\n## Usage\n\n### Installing RBush\n\nInstall with NPM: `npm install rbush`, then import as a module:\n\n```js\nimport RBush from 'rbush';\n```\n\nOr use as a module directly in the browser with [jsDelivr](https://www.jsdelivr.com/esm):\n\n```html\n\u003cscript type=\"module\"\u003e\n    import RBush from 'https://cdn.jsdelivr.net/npm/rbush/+esm';\n\u003c/script\u003e\n```\n\nAlternatively, there's a browser bundle with an `RBush` global variable:\n\n```html\n\u003cscript src=\"https://cdn.jsdelivr.net/npm/rbush\"\u003e\u003c/script\u003e\n```\n\n### Creating a Tree\n\n```js\nconst tree = new RBush();\n```\n\nAn optional argument to `RBush` defines the maximum number of entries in a tree node.\n`9` (used by default) is a reasonable choice for most applications.\nHigher value means faster insertion and slower search, and vice versa.\n\n```js\nconst tree = new RBush(16);\n```\n\n### Adding Data\n\nInsert an item:\n\n```js\nconst item = {\n    minX: 20,\n    minY: 40,\n    maxX: 30,\n    maxY: 50,\n    foo: 'bar'\n};\ntree.insert(item);\n```\n\n### Removing Data\n\nRemove a previously inserted item:\n\n```js\ntree.remove(item);\n```\n\nBy default, RBush removes objects by reference.\nHowever, you can pass a custom `equals` function to compare by value for removal,\nwhich is useful when you only have a copy of the object you need removed (e.g. loaded from server):\n\n```js\ntree.remove(itemCopy, (a, b) =\u003e {\n    return a.id === b.id;\n});\n```\n\nRemove all items:\n\n```js\ntree.clear();\n```\n\n### Data Format\n\nBy default, RBush assumes the format of data points to be an object\nwith `minX`, `minY`, `maxX` and `maxY` properties.\nYou can customize this by overriding `toBBox`, `compareMinX` and `compareMinY` methods like this:\n\n```js\nclass MyRBush extends RBush {\n    toBBox([x, y]) { return {minX: x, minY: y, maxX: x, maxY: y}; }\n    compareMinX(a, b) { return a.x - b.x; }\n    compareMinY(a, b) { return a.y - b.y; }\n}\nconst tree = new MyRBush();\ntree.insert([20, 50]); // accepts [x, y] points\n```\n\nIf you're indexing a static list of points (you don't need to add/remove points after indexing), you should use [kdbush](https://github.com/mourner/kdbush) which performs point indexing 5-8x faster than RBush.\n\n### Bulk-Inserting Data\n\nBulk-insert the given data into the tree:\n\n```js\ntree.load([item1, item2, ...]);\n```\n\nBulk insertion is usually ~2-3 times faster than inserting items one by one.\nAfter bulk loading (bulk insertion into an empty tree),\nsubsequent query performance is also ~20-30% better.\n\nNote that when you do bulk insertion into an existing tree,\nit bulk-loads the given data into a separate tree\nand inserts the smaller tree into the larger tree.\nThis means that bulk insertion works very well for clustered data\n(where items in one update are close to each other),\nbut makes query performance worse if the data is scattered.\n\n### Search\n\n```js\nconst result = tree.search({\n    minX: 40,\n    minY: 20,\n    maxX: 80,\n    maxY: 70\n});\n```\n\nReturns an array of data items (points or rectangles) that the given bounding box intersects.\n\nNote that the `search` method accepts a bounding box in `{minX, minY, maxX, maxY}` format\nregardless of the data format.\n\n```js\nconst allItems = tree.all();\n```\n\nReturns all items of the tree.\n\n### Collisions\n\n```js\nconst result = tree.collides({minX: 40, minY: 20, maxX: 80, maxY: 70});\n```\n\nReturns `true` if there are any items intersecting the given bounding box, otherwise `false`.\n\n\n### Export and Import\n\n```js\n// export data as JSON object\nconst treeData = tree.toJSON();\n\n// import previously exported data\nconst tree = rbush(9).fromJSON(treeData);\n```\n\nImporting and exporting as JSON allows you to use RBush on both the server (using Node.js) and the browser combined,\ne.g. first indexing the data on the server and and then importing the resulting tree data on the client for searching.\n\nNote that the `nodeSize` option passed to the constructor must be the same in both trees for export/import to work properly.\n\n### K-Nearest Neighbors\n\nFor \"_k_ nearest neighbors around a point\" type of queries for RBush,\ncheck out [rbush-knn](https://github.com/mourner/rbush-knn).\n\n## Performance\n\nThe following sample performance test was done by generating\nrandom uniformly distributed rectangles of ~0.01% area and setting `maxEntries` to `16`\n(see `debug/perf.js` script).\nPerformed with Node.js v6.2.2 on a Retina Macbook Pro 15 (mid-2012).\n\nTest                         | RBush  | [old RTree](https://github.com/imbcmdth/RTree) | Improvement\n---------------------------- | ------ | ------ | ----\ninsert 1M items one by one   | 3.18s  | 7.83s  | 2.5x\n1000 searches of 0.01% area  | 0.03s  | 0.93s  | 30x\n1000 searches of 1% area     | 0.35s  | 2.27s  | 6.5x\n1000 searches of 10% area    | 2.18s  | 9.53s  | 4.4x\nremove 1000 items one by one | 0.02s  | 1.18s  | 50x\nbulk-insert 1M items         | 1.25s  | n/a    | 6.7x\n\n## Algorithms Used\n\n* single insertion: non-recursive R-tree insertion with overlap minimizing split routine from R\\*-tree (split is very effective in JS, while other R\\*-tree modifications like reinsertion on overflow and overlap minimizing subtree search are too slow and not worth it)\n* single deletion: non-recursive R-tree deletion using depth-first tree traversal with free-at-empty strategy (entries in underflowed nodes are not reinserted, instead underflowed nodes are kept in the tree and deleted only when empty, which is a good compromise of query vs removal performance)\n* bulk loading: OMT algorithm (Overlap Minimizing Top-down Bulk Loading) combined with Floyd–Rivest selection algorithm\n* bulk insertion: STLT algorithm (Small-Tree-Large-Tree)\n* search: standard non-recursive R-tree search\n\n## Papers\n\n* [R-trees: a Dynamic Index Structure For Spatial Searching](http://www-db.deis.unibo.it/courses/SI-LS/papers/Gut84.pdf)\n* [The R*-tree: An Efficient and Robust Access Method for Points and Rectangles+](http://dbs.mathematik.uni-marburg.de/publications/myPapers/1990/BKSS90.pdf)\n* [OMT: Overlap Minimizing Top-down Bulk Loading Algorithm for R-tree](http://ftp.informatik.rwth-aachen.de/Publications/CEUR-WS/Vol-74/files/FORUM_18.pdf)\n* [Bulk Insertions into R-Trees Using the Small-Tree-Large-Tree Approach](http://www.cs.arizona.edu/~bkmoon/papers/dke06-bulk.pdf)\n* [R-Trees: Theory and Applications (book)](http://www.apress.com/9781852339777)\n\n## Development\n\n```bash\nnpm ci       # install dependencies\nnpm test     # lint the code and run tests\nnpm run perf # run performance benchmarks\nnpm run cov  # report test coverage\n```\n\n## Compatibility\n\nRBush v4+ is published as a ES module and no longer supports CommonJS environments. It works universally in modern browsers, but you can transpile the code on your end to support IE11.\n","funding_links":[],"categories":["JavaScript","👨‍💻 JavaScript Libraries","\u003e 1K ⭐️","Geometric Algebra"],"sub_categories":["Data Processing","Collision Detection"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmourner%2Frbush","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmourner%2Frbush","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmourner%2Frbush/lists"}