https://github.com/hexogen/kdtree
PHP K-D Tree implementation with file system binary index
https://github.com/hexogen/kdtree
algorithms cache data-structures index kd-tree multidimensionality search-algorithm
Last synced: about 1 month ago
JSON representation
PHP K-D Tree implementation with file system binary index
- Host: GitHub
- URL: https://github.com/hexogen/kdtree
- Owner: hexogen
- License: mit
- Created: 2016-12-18T05:21:46.000Z (about 9 years ago)
- Default Branch: master
- Last Pushed: 2024-10-14T13:06:10.000Z (over 1 year ago)
- Last Synced: 2025-10-10T07:03:43.420Z (5 months ago)
- Topics: algorithms, cache, data-structures, index, kd-tree, multidimensionality, search-algorithm
- Language: PHP
- Homepage:
- Size: 1.05 MB
- Stars: 21
- Watchers: 1
- Forks: 3
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: .github/CONTRIBUTING.md
- License: LICENSE.md
- Code of conduct: .github/CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# K-D Tree
[![Latest Version on Packagist][ico-version]][link-packagist]
[![Build Status][ico-tests]][link-tests]
[![codecov][ico-codecov]][link-codecov]
[![Software License][ico-license]](LICENSE.md)
[![Total Downloads][ico-downloads]][link-downloads]
PHP multidimensional K-D Tree implementation.
To receive all benefits from K-D Tree, use file system implementation(FSKDTree). FSKDTree stores tree in binary format and uses lazy loading while traversing through nodes. Current approach provides much higher performance compared
to deserialization.
## Install
Via Composer
``` bash
$ composer require hexogen/kdtree
```
## Usage
### Tree creation
``` php
//Item container with 2 dimensional points
$itemList = new ItemList(2);
//Adding 2 - dimension items to the list
$itemList->addItem(new Item(1, [1.2, 4.3]));
$itemList->addItem(new Item(2, [1.3, 3.4]));
$itemList->addItem(new Item(3, [4.5, 1.2]));
$itemList->addItem(new Item(4, [5.2, 3.5]));
$itemList->addItem(new Item(5, [2.1, 3.6]));
//Building tree with given item list
$tree = new KDTree($itemList);
```
### Searching nearest items to the given point
``` php
//Creating search engine with custom algorithm (currently Nearest Search)
$searcher = new NearestSearch($tree);
//Retrieving a result ItemInterface[] array with given size (currently 2)
$result = $searcher->search(new Point([1.25, 3.5]), 2);
echo $result[0]->getId(); // 2
echo $result[0]->getNthDimension(0); // 1.3
echo $result[0]->getNthDimension(1); // 3.4
echo $result[1]->getId(); // 1
echo $result[1]->getNthDimension(0); // 1.2
echo $result[1]->getNthDimension(1); // 4.3
```
### Persist tree to a binary file
``` php
//Init tree writer
$persister = new FSTreePersister('/path/to/dir');
//Save the tree to /path/to/dir/treeName.bin
$persister->convert($tree, 'treeName.bin');
```
### File system version of the tree
``` php
//ItemInterface factory
$itemFactory = new ItemFactory();
//Then init new instance of file system version of the tree
$fsTree = new FSKDTree('/path/to/dir/treeName.bin', $itemFactory);
//Now use fs kdtree to search
$fsSearcher = new NearestSearch($fsTree);
//Retrieving a result ItemInterface[] array with given size (currently 2)
$result = $fsSearcher->search(new Point([1.25, 3.5]), 2);
echo $result[0]->getId(); // 2
echo $result[1]->getId(); // 1
```
## Change log
Please see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently.
## Testing
``` bash
$ composer test
```
## Contributing
Please see [CONTRIBUTING](.github/CONTRIBUTING.md) and [CONDUCT](CONDUCT.md) for details.
## Security
If you discover any security related issues, please email volodymyrbas@gmail.com instead of using the issue tracker.
## Credits
- [Volodymyr Basarab][link-author]
- [All Contributors][link-contributors]
## License
The MIT License (MIT). Please see [License File](LICENSE.md) for more information.
[ico-version]: https://img.shields.io/packagist/v/hexogen/kdtree.svg?style=flat-square
[ico-tests]: https://img.shields.io/github/actions/workflow/status/hexogen/kdtree/tests.yml?branch=master
[ico-codecov]: https://codecov.io/gh/hexogen/kdtree/graph/badge.svg?token=176L4UA0Y1
[ico-license]: https://img.shields.io/badge/license-MIT-brightgreen.svg?style=flat-square
[ico-downloads]: https://img.shields.io/packagist/dt/hexogen/kdtree.svg?style=flat-square
[link-packagist]: https://packagist.org/packages/hexogen/kdtree
[link-tests]: https://github.com/hexogen/kdtree/actions?query=workflow%3ATests
[link-codecov]: https://codecov.io/gh/hexogen/kdtree
[link-downloads]: https://packagist.org/packages/hexogen/kdtree
[link-author]: https://github.com/hexogen
[link-contributors]: ../../contributors