How do I add a custom shape like a polygon to rtree?

Implement the Geometry interface with intersection and distance methods, then use the search method with a custom intersects function, as detailed in the 'Search with a custom geometry' section of the README.

rtree vs JTS: which is better for Java spatial indexing?

rtree excels in immutable, reactive indexing with thread safety, ideal for concurrent applications, while JTS offers more comprehensive geometry operations but lacks built-in reactive support. Choose based on your need for streaming and concurrency.

How to bulk load data into rtree for faster setup?

Use the STR bulk loading feature by configuring the RTree builder, which can speed up index creation by 10x for static datasets, as explained in the features and benchmark sections.

Does rtree support 3D spatial data?

No, rtree is limited to 2D geometries like points and rectangles; for 3D indexing, you would need to extend the library or consider alternative solutions.

What's the best way to reduce memory usage in rtree?

Use single-precision geometries (float) or FlatBuffers serialization to lower memory footprint, but be aware of the performance trade-offs, as mentioned in the memory use and serialization sections.

How to visualize an R-tree as a PNG image?

Call the visualize method on the tree with width and height parameters, then save the output to a file, as demonstrated in the visualization part of the README with example images.

Open-Awesome

rtree

Apache-2.0Java0.12

Immutable in-memory R-tree and R*-tree implementations in Java with a reactive API for spatial indexing.

GitHub

1.1k stars218 forks0 contributors

What is rtree?

rtree is an open-source Java library that implements immutable in-memory R-tree and R*-tree data structures for spatial indexing. It allows developers to efficiently store and query 2D geometric data—like points, rectangles, and circles—with support for reactive streams via RxJava. The library solves the problem of fast spatial lookups in applications such as geographic information systems (GIS), gaming, or any domain requiring proximity searches.

Target Audience

Java developers working on applications that require spatial indexing, such as GIS software, location-based services, game engines, or data analytics tools that handle geometric data.

Value Proposition

Developers choose rtree for its combination of immutability (ensuring thread safety), reactive API (enabling efficient streaming of results), and high performance with multiple splitting strategies. It offers a pure Java solution with no external dependencies beyond RxJava, making it lightweight and easy to integrate.

Overview

Immutable in-memory R-tree and R*-tree implementations in Java with reactive api

Use Cases

Best For

Building location-aware applications that need fast proximity searches
Implementing spatial indexes for geographic data like earthquake or map points
Developing game engines requiring efficient 2D collision detection
Creating GIS tools for querying regions with custom geometries
Handling large datasets with STR bulk loading for rapid index creation
Applications needing thread-safe spatial operations due to concurrent access

Not Ideal For

Applications requiring high-frequency updates to the spatial index, as immutability leads to constant tree reconstruction and object creation overhead.
Projects not using RxJava, due to the mandatory reactive API integration adding dependency and learning curve complexity.
Real-time systems with strict latency requirements, where backpressure mechanisms and reactive streams can introduce unpredictable delays.
Environments with extremely limited heap space that cannot tolerate the memory footprint of immutable in-memory structures, despite serialization options.

Pros & Cons

Pros

Immutable Thread Safety

All operations return new tree instances, enabling safe concurrent access without locks, as emphasized in the README's design philosophy.

Reactive Stream Integration

Search results are delivered as RxJava Observables, supporting backpressure and lazy evaluation for efficient data handling, with examples in the documentation.

Flexible Splitting Strategies

Offers Guttman's quadratic split, R*-tree heuristics, and customizable splitters, allowing optimization for different datasets like earthquake locations.

Fast Bulk Loading

STR bulk loading accelerates index creation by 10x for large or static datasets, as highlighted in the features and benchmarks.

Cons

RxJava Dependency Lock-in

Tight coupling with RxJava forces projects to adopt reactive programming, adding complexity and an external dependency not suitable for all codebases.

Mutable Operation Overhead

Immutable design means every insert or delete creates a new tree, leading to performance and memory inefficiencies in write-heavy scenarios, as noted in the O(n) worst-case complexity.

Serialization Performance Penalty

FlatBuffers serialization reduces memory usage but makes searches up to 10x slower, a trade-off explicitly admitted in the README's benchmark notes.

Frequently Asked Questions

Related Projects

RxJava

RxJava – Reactive Extensions for the JVM – a library for composing asynchronous and event-based programs using observable sequences for the Java VM.

Stars48,289

Forks7,589

Last commit7 days ago

VarInt

a fast, scalable, multi-language and extensible build system

Stars25,348

Forks4,449

Last commit12 hours ago

caffeine

A high performance caching library for Java

Stars17,624

Forks1,685