{"id":17680738,"url":"https://github.com/elbywan/quadtree-lib","last_synced_at":"2025-10-07T06:14:07.244Z","repository":{"id":58246081,"uuid":"43415313","full_name":"elbywan/quadtree-lib","owner":"elbywan","description":"Efficient quadtrees library written in CoffeeScript.","archived":false,"fork":false,"pushed_at":"2024-02-26T20:58:50.000Z","size":1781,"stargazers_count":45,"open_issues_count":1,"forks_count":5,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-05-06T00:04:55.439Z","etag":null,"topics":["2d","coffeescript","colliding-elements","collision-detection","datastructure","datastructures","quad-tree","quadtree","quadtree-lib","tree-structure","typescript","umd"],"latest_commit_sha":null,"homepage":null,"language":"CoffeeScript","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/elbywan.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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":"2015-09-30T06:12:23.000Z","updated_at":"2024-06-18T18:41:17.718Z","dependencies_parsed_at":"2024-02-07T21:35:39.504Z","dependency_job_id":"10f74166-6463-479b-ab44-4554144e5448","html_url":"https://github.com/elbywan/quadtree-lib","commit_stats":{"total_commits":88,"total_committers":4,"mean_commits":22.0,"dds":0.125,"last_synced_commit":"2597ae049ca50be54adbcb73d3b5ca7e7ae566e7"},"previous_names":[],"tags_count":13,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elbywan%2Fquadtree-lib","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elbywan%2Fquadtree-lib/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elbywan%2Fquadtree-lib/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elbywan%2Fquadtree-lib/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/elbywan","download_url":"https://codeload.github.com/elbywan/quadtree-lib/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248860006,"owners_count":21173344,"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":["2d","coffeescript","colliding-elements","collision-detection","datastructure","datastructures","quad-tree","quadtree","quadtree-lib","tree-structure","typescript","umd"],"created_at":"2024-10-24T09:08:43.970Z","updated_at":"2025-10-07T06:14:02.167Z","avatar_url":"https://github.com/elbywan.png","language":"CoffeeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003e\n    quadtree-lib\u003cbr\u003e\n\t\u003cbr\u003e\n\t\u003ca href=\"http://elbywan.github.io/quadtree-lib/demo/collisions/collisions.html\" target=\"_blank\"\u003e\n\t\t\u003cimg alt=\"quatree gif\" src=\"http://elbywan.github.io/quadtree-lib/assets/quadtree.gif\" width=\"120px\"/\u003e\n\t\u003c/a\u003e\u003cbr\u003e\n\t\u003ca href=\"https://travis-ci.org/elbywan/quadtree-lib\" target=\"_blank\" style=\"margin-right: 10px\"\u003e\n\t\t\u003cimg alt=\"Build Status\" src=\"https://travis-ci.org/elbywan/quadtree-lib.svg?branch=master\"/\u003e\n\t\u003c/a\u003e\n\t\u003ca href=\"https://coveralls.io/github/elbywan/quadtree-lib?branch=master\" target=\"_blank\" style=\"margin-right: 10px\"\u003e\n\t\t\u003cimg alt=\"Coverage Status\" src=\"https://coveralls.io/repos/github/elbywan/quadtree-lib/badge.svg?branch=master\"/\u003e\n\t\u003c/a\u003e\n\t\u003ca href=\"https://www.npmjs.com/package/quadtree-lib\" target=\"_blank\"\u003e\n\t\t\u003cimg alt=\"npm version\" src=\"https://badge.fury.io/js/quadtree-lib.svg\"/\u003e\n\t\u003c/a\u003e\n\u003c/h1\u003e\n\u003ch4 align=\"center\"\u003e\n\tQuadtree-lib is an easy to use, developer friendly quadtree library which\n\tcontains many helper methods to add, remove, iterate, filter, simulate\n\tcollisions over 2d elements and more.\n\u003c/h4\u003e\n\nIf you are already familiar with quadtrees, then you should perfectly understand\nhow to use this library.\n\nOtherwise, there are many online articles\n([wikipedia does the job](https://en.wikipedia.org/wiki/Quadtree)) which explain\nthe advantages of using the quadtree datastructure in certain situations.\n\nIf you want to see the library in action :\n- [Collision demo](http://elbywan.github.io/quadtree-lib/demo/collisions/collisions.html)\n- [Movement demo](http://elbywan.github.io/quadtree-lib/demo/movement/movement.html)\n- [Mass demo](http://elbywan.github.io/quadtree-lib/demo/basic/basic.html)\n\n## Setup\n\n### Using npm / yarn\n\nFrom the command line :\n\n`npm install quadtree-lib` or `yarn add quadtree-lib`\n\n### Using bower\n\n`bower install quadtree-lib`\n\n### Using gulp\n\nIn your favorite terminal :\n\n```bash\n# 1°clone the repo\ngit clone https://github.com/elbywan/quadtree-lib\n# 2° change dir\ncd quadtree-lib\n# 3° build the library\ngulp\n# 4° build the documentation\ngulp doc\n# 5° run performance tests\ngulp perf\n# 6° profit\n```\n\n## Usage\n\n### Import\n\n**This library is bundled in UMD format.**\n\nExamples :\n\n- Import using commonjs :\n```javascript\nQuadtree = require(\"quadtree-lib\")\n```\n\n- Import globally with a script tag :\n```html\n\u003cscript src=\"path/to/quadtree-lib.min.js\"\u003e\u003c/script\u003e\n```\n\n### Init\n\nFirst step is to initialize a new Quadtree object.\n\n```javascript\nvar quadtree = new Quadtree({\n    width: 500,\n    height: 500,\n    maxElements: 5 //Optional\n})\n```\n\n`width` and `height` are mandatory attributes.\n\n`maxElements` (default 1) is the maximum number of elements contained in a leaf before it\nsplits into child trees.\n\n### For typescript users\n\nA set of declaration files (.d.ts) is included, which means that you have access to auto-completion and embedded documentation in your favorite IDE.\n\nIf you are using the library **globally** with a `\u003cscript\u003e` tag, add the following declaration import :\n```typescript\n/// \u003creference types=\"quadtree-lib\" /\u003e\n```\n\nOtherwise, if you are using the **commonjs** way :\n```typescript\nimport * as Quadtree from \"quadtree-lib\"\n```\n\n### Adding elements\n\nElements must be objects, with coordinates set.\n\nOptionally, you can pass a boolean argument which, if set to `true`, will\nremove/push the object into the quadtree each time its coordinates or dimensions\nare set *(ex: item.x = ... or item.width = ...)*.\n\n*Without this flag, x / y / width / height properties should* **not** *be\nchanged  after insertion.*\n\n```javascript\nquadtree.push({\n    x: 10,      //Mandatory\n    y: 10,      //Mandatory\n    width: 1,   //Optional, defaults to 1\n    height: 2   //Optional, defaults to 1\n}, true) //Optional, defaults to false\n```\n\nTo insert an array of elements, use the **pushAll** method which is faster than inserting each element with push.\n\n```javascript\nquadtree.pushAll([\n    {x: 1, y: 1},\n    {x: 2, y: 2}\n    // ... //\n])\n```\n\n### Removing elements\n\nRemoves an item by reference.\n\n```javascript\nquadtree.remove(item)\n```\n\n### Clearing the tree\n\nRemoves the tree contents and restores it to pristine state.\n\n```javascript\nquatree.clear()\n```\n\n### Filtering the tree\n\nFilters the quadtree and returns a **clone** containing only the elements\ndetermined by a predicate function.\n\n```javascript\nvar filtered = quadtree.filter(function(element){\n    return element.x \u003e 50\n})\n```\n\n*Opposite: quadtree.reject*\n\n### Retrieve colliding elements\n\nGets every element that collides with the parameter 2d object.\n\n```javascript\nvar colliding = quadtree.colliding({\n    x: 10,\n    y: 10,\n    width: 5, //Optional\n    height: 5 //Optional\n})\n```\n\nThe default collision function is a basic bounding box algorithm.\nYou can change it by providing a function as a second argument.\n\n```javascript\nvar colliding = quadtree.colliding({\n    x: 10,\n    y: 10\n}, function(element1, element2){\n    return // Place collision algorithm here //\n})\n\n```\n\n### Perform an action on colliding elements\n\nPerforms an action on every element that collides with the parameter 2d object.\n\n```javascript\nonCollision({\n    x: 10,\n    y: 20\n}, function(item) {\n    /* Action on colliding item */\n\n    // As with all iterative methods, modifying the quadtree or its contents is discouraged. //\n}, function(element1, element2){\n    /* Optional custom collision algorithm */\n    return // Place predicate here //\n})\n```\n\n### Retrieve by properties\n\nGets every element that match the parameter properties.\n\n```javascript\nquadtree.push({x: 0, y: 0, animal: 'rabbit'})\nvar match = quadtree.where({\n    animal: 'rabbit'\n})\n```\n\n*Alias : quadtree.get*\n\n### Retrieve by predicate\n\nGets every element that validate the given predicate.\n\n```javascript\nquadtree.find(function(element){\n    return element.color === 'red' //Example\n})\n```\n\n### Iterate over the elements\n\nPerforms an action on each element of the Quadtree (breadth first traversal).\n\n```javascript\nquadtree.each(function(element){\n    console.log(element.color)\n\n    // As with all iterative methods, modifying the quadtree or its contents is discouraged. //\n})\n```\n\n*Like some other data structures, it is strongly discouraged to update Quadtree elements (especially coordinates / dimensions) or the Quadtree itself while iterating on it.*\n\n### Visit the tree nodes\n\nVisits each node of the quadtree. (meaning subtrees)\n\n```javascript\nquadtree.visit(function(){\n    // This function is called once for each node.\n    // *this* is a pointer to the current node.\n    console.log(this.contents)\n\n    // As with all iterative methods, modifying the quadtree or its contents is discouraged. //\n})\n```\n\n### Pretty print\n\nOutputs the tree and its contents in an eye friendly format.\n\n```javascript\nvar quadtree = new Quadtree({\n  width: 10,\n  height: 10,\n  maxElements: 1\n});\n\nvar elementArray = [\n  element0 = {\n    x: 0,\n    y: 0,\n    toString: function() {\n      return 0;\n    }\n  }, element1 = {\n    x: 3,\n    y: 3,\n    toString: function() {\n      return 1;\n    }\n  }\n];\n\nquadtree.pushAll(elementArray);\n\nconsole.log(quadtree.pretty());\n```\n\nConsole output :\n\n```\n| ROOT\n| ------------\n└──┐\n   | NW\n   | ------------\n   └──┐\n      | SE\n      | ------------\n      | * Leaf content *\n      |   1\n      | NW\n      | ------------\n      | * Leaf content *\n      |   0\n```\n\n\n## Further documentation\n\nYou can find the annotated source code [here](http://elbywan.github.io/quadtree-lib/).\n\n*Generated with Docco.*\n\n## License\n\n#### The MIT License (MIT)\n\nCopyright (c) 2015 Julien Elbaz\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Felbywan%2Fquadtree-lib","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Felbywan%2Fquadtree-lib","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Felbywan%2Fquadtree-lib/lists"}