Metadata-Version: 2.4
Name: discrete_ndtree
Version: 0.2.3
Summary: N-Dimensional Dtree (e.g. Quadtree, Octree) with limited resolution.
Author: Kay Richter
License-Expression: Apache-2.0
License-File: LICENSE
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Project-URL: source, https://github.com/KayRichter/nim-dtree
Requires-Python: >=3.7
Description-Content-Type: text/markdown

# discrete_ndtree

This package provides N-Dimensional trees (e.g. Quadtree, Octree) with a limited smallest node size.
Opposed to normal ND-Trees, nearby coordinates may access the same cell.
Example usecases:
- occupancy maps for 2D and 3D
- canvas for images without borders
- timeline of daily temperatures


## Usage

```python
from discrete_ndtree import DTree


# create a quadtree with a smallest cell size of 0.5
quad_tree = DTree(2, 0.5)

# reading and writing cells can be done using the subscript operator
# the default cell content is `None`
assert quad_tree[0.0, 0.0] is None
quad_tree[0.0, 0.0] = "value"
assert quad_tree[0.0, 0.0] == "value"

# since the cell size is limited, other nearby coordinates may access the same cell
assert quad_tree[0.4, 0.4] == "value"

# by default the corner of the root of the tree is at the coordinate origin
# a different point can be set using the `anchor` parameter
quad_tree = DTree(2, 0.5, anchor=[0.2, 0.2])
quad_tree[0.0, 0.0] = "value"
assert quad_tree[0.4, 0.4] is None  # coordinate is a different cell now

# also the default value for all cells can be changed
quad_tree = DTree(2, 0.5, default=0)
assert quad_tree[0.0, 0.0] == 0

# it is also possible to get ranges of cells from the tree
# note that the results includes both ends of the slice
assert quad_tree[0.1:0.9, 0.1:0.9] == [[0, 0], [0, 0]]
```


## Installation

Precompiled wheels are available for Linux (glibc and musl), macOS, and Windows:

```bash
pip install discrete-ndtree
```

The wheels ship with dimensions 1-4 precompiled.
Other dimensions are compiled on demand (see [More dimensions](#more-dimensions)).

## More dimensions

Dimensions 1-4 are precompiled; any other dimension is compiled on first use:

```python
from discrete_ndtree import DTree

six_dim_tree = DTree(6, 1.0, anchor=[1.0, -2.0, 3.0, -4.0, 5.0, -6.0], default=False)
assert six_dim_tree[0.0, 0.0, 0.0, 0.0, 0.0, 0.0] == False
```

The first construction of a tree with an uncompiled dimension compiles a
`nim_dtree_dim_<dims>.so` (`.pyd` on Windows) into the `discrete_ndtree` package
directory, so that directory must be writable.
This requires a working [Nim compiler](https://nim-lang.org/) (>= 2.2.4) and
the `nimpy` and `msgpack4nim` packages:

```bash
nimble install nimpy msgpack4nim
```

Nim and the nimble package manager can be installed using [choosenim](https://github.com/nim-lang/choosenim)
To compile dimensions ahead of time, or to bundle several dimensions into one
binary, use `compile_dimensions`:

```python
from discrete_ndtree import discrete_ndtree

discrete_ndtree.compile_dimensions([6])  # or e.g. [5, 6, 7]
```

More low level access to the trees is not recommended, but available through
```python
from discrete_ndtree import discrete_ndtree
```
