Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/tidwall/rtree
An R-tree implementation for Go
https://github.com/tidwall/rtree
Last synced: about 2 months ago
JSON representation
An R-tree implementation for Go
- Host: GitHub
- URL: https://github.com/tidwall/rtree
- Owner: tidwall
- License: mit
- Created: 2018-07-27T17:09:34.000Z (about 6 years ago)
- Default Branch: master
- Last Pushed: 2023-05-04T15:28:50.000Z (over 1 year ago)
- Last Synced: 2024-07-27T03:09:16.412Z (about 2 months ago)
- Language: Go
- Homepage:
- Size: 694 KB
- Stars: 299
- Watchers: 7
- Forks: 28
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- my-awesome - tidwall/rtree - 08 star:0.3k fork:0.0k An R-tree implementation for Go (Go)
README
# rtree
[](https://godoc.org/github.com/tidwall/rtree)
This package provides an in-memory R-Tree implementation for Go. It's designed
for [Tile38](https://github.com/tidwall/tile38) and is optimized for fast rect
inserts and replacements.
## Usage
### Installing
To start using rtree, install Go and run `go get`:
```sh
$ go get -u github.com/tidwall/rtree
```
### Basic operations
```go
// create a 2D RTree
var tr rtree.RTree
// insert a point
tr.Insert([2]float64{-112.0078, 33.4373}, [2]float64{-112.0078, 33.4373}, "PHX")
// insert a rect
tr.Insert([2]float64{10, 10}, [2]float64{20, 20}, "rect")
// search
tr.Search([2]float64{-112.1, 33.4}, [2]float64{-112.0, 33.5},
func(min, max [2]float64, data interface{}) bool {
println(data.(string)) // prints "PHX"
},
)
// delete
tr.Delete([2]float64{-112.0078, 33.4373}, [2]float64{-112.0078, 33.4373}, "PHX")
```
### Support for Generics (Go 1.18+)
```go
// create a 2D RTree
var tr rtree.RTreeG[string]
// insert a point
tr.Insert([2]float64{-112.0078, 33.4373}, [2]float64{-112.0078, 33.4373}, "PHX")
// insert a rect
tr.Insert([2]float64{10, 10}, [2]float64{20, 20}, "rect")
// search
tr.Search([2]float64{-112.1, 33.4}, [2]float64{-112.0, 33.5},
func(min, max [2]float64, data string) bool {
println(data) // prints "PHX"
},
)
// delete
tr.Delete([2]float64{-112.0078, 33.4373}, [2]float64{-112.0078, 33.4373}, "PHX")
```
### Support for generic numeric types, like int, float32, etc.
```go
// create a 2D RTree
var tr rtree.RTreeGN[float32, string]
// insert a point
tr.Insert([2]float32{-112.0078, 33.4373}, [2]float32{-112.0078, 33.4373}, "PHX")
// insert a rect
tr.Insert([2]float32{10, 10}, [2]float32{20, 20}, "rect")
// search
tr.Search([2]float32{-112.1, 33.4}, [2]float32{-112.0, 33.5},
func(min, max [2]float32, data string) bool {
println(data) // prints "PHX"
},
)
// delete
tr.Delete([2]float32{-112.0078, 33.4373}, [2]float32{-112.0078, 33.4373}, "PHX")
```
## Algorithms
This implementation is a variant of the original paper:
[R-TREES. A DYNAMIC INDEX STRUCTURE FOR SPATIAL SEARCHING](https://www.cs.princeton.edu/courses/archive/fall08/cos597B/papers/rtrees.pdf)
### Inserting
Similar to the original paper. From the root to the leaf, the rects which will incur the least enlargment are chosen. Ties go to rects with the smallest area.
Added to this implementation: when a rect does not incur any enlargement at all, it's chosen immediately and without further checks on other rects in the same node. Also added is all child rectangles in every node are ordered by their minimum x value. This can dramatically speed up searching for intersecting rectangles on most modern hardware.
### Deleting
A target rect is searched for from root to the leaf, and if found it's deleted. When there are no more child rects in a node, that node is immedately removed from the tree.
### Searching
Same as the original algorithm.
### Splitting
This is a custom algorithm. It attempts to minimize intensive operations such as pre-sorting the children and comparing overlaps & area sizes. The desire is to do simple single axis distance calculations each child only once, with a target 50/50 chance that the child might be moved in-memory.
When a rect has reached it's max number of entries it's largest axis is calculated and the rect is split into two smaller rects, named `left` and `right`.
Each child rects is then evaluated to determine which smaller rect it should be placed into.
Two values, `min-dist` and `max-dist`, are calcuated for each child.
- `min-dist` is the distance from the parent's minumum value of it's largest axis to the child's minumum value of the parent largest axis.
- `max-dist` is the distance from the parent's maximum value of it's largest axis to the child's maximum value of the parent largest axis.
When the `min-dist` is less than `max-dist` then the child is placed into the `left` rect.
When the `max-dist` is less than `min-dist` then the child is placed into the `right` rect.
When the `min-dist` is equal to `max-dist` then the child is placed into an `equal` bucket until all of the children are evaluated.
Each `equal` rect is then one-by-one placed in either `left` or `right`, whichever has less children.
Finally, sort all the rects in the parent node of the split rect by their
minimum x value.
## License
rtree source code is available under the MIT License.