|
| ![NPM](https://camo.githubusercontent.com/928876cef179b8330168af4ec1d41ef7ce7afcc1f5af4092a728aeec6527e3d2/68747470733a2f2f6e6f6465692e636f2f6e706d2f71756164747265652d6c69622e706e673f6d696e693d74727565)
| quadtree-lib |
![quatree gif](https://raw.githubusercontent.com/raulanatol/quadtree-lib/master/assets/quadtree.gif)
Quadtree-lib is an easy to use, developer friendly quadtree library which contains many helper methods to add, remove, iterate, filter, simulate collisions over 2d elements and more.
If you are already familiar with quadtrees, then you should perfectly understand how to use this library.
Otherwise, there are many online articles (wikipedia does the job) which explain the advantages of using the quadtree datastructure in certain situations.
Here is a small demo of the library in action.
Setup
Using npm
From the command line :
npm install quadtree-lib
Then in your javascript file :
Quadtree = require("quadtree-lib")
Using Bower
bower install quadtree-lib
Using gulp
Clone the git repository, run
git clone https://github.com/elbywan/quadtree-lib
- To build the library, run
gulp
. - To run the performance tests, run
gulp perf
.
Usage
Init
First step is to initialize a new Quadtree object.
var quadtree = new Quadtree({
width: 500,
height: 500,
maxElements: 5 //Optional
})
width
and height
are mandatory attributes.
maxElements
(default 1) is the maximum number of elements contained in a leaf before it
splits into child trees.
Adding elements
Elements must be objects, with coordinates set.
Optionally, you can pass a boolean argument which, if set to True, will remove/push the object into the quadtree each time its coordinates or dimensions are set (ex: item.x = ... or item.width = ...).
Without this flag, x / y / width / height properties should not be changed after insertion.
quadtree.push({
x: 10, //Mandatory
y: 10, //Mandatory
width: 1, //Optional, defaults to 1
height: 2 //Optional, defaults to 1
}, true) //Optional, defaults to false
Removing elements
Removes an item by reference.
quadtree.remove(item)
Filtering the tree
Filters the quadtree and returns a clone containing only the elements determined by a predicate function.
var filtered = quadtree.filter(function(element){
return element.x > 50
})
Opposite: quadtree.reject
Retrieve colliding elements
Gets every element that collides with the parameter 2d object.
var colliding = quadtree.colliding({
x: 10,
y: 10,
width: 5, //Optional
height: 5 //Optional
})
The default collision function is a basic bounding box algorithm. You can change it by providing a function as a second argument.
var colliding = quadtree.colliding({
x: 10,
y: 10
}, function(element1, element2){
return //Place collision algorithm here
})
Retrieve by properties
Gets every element that match the parameter properties.
quadtree.push({x: 0, y: 0, animal: 'rabbit'})
var match = quadtree.where({
animal: 'rabbit'
})
Alias : quadtree.get
Retrieve by predicate
Gets every element that validate the given predicate.
quadtree.find(function(element){
return element.color === 'red' //Example
})
Iterate over the elements
quadtree.each(function(element){
console.log(element.color)
})
Visit the tree nodes
Visits each node of the quadtree. (meaning subtrees)
quadtree.visit(function(){
// This function is called once for each node.
//this -> this is always the current node.
console.log(this.contents)
})
Further documentation
You can find the annotated source code here.
Generated with Docco.
License
The MIT License (MIT)
Copyright (c) 2015 Julien Elbaz
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.