Welcome to AABBTree!

AABBTree is a pure Python implementation of a static d-dimensional axis aligned bounding box (AABB) tree. It is heavily based on Introductory Guide to AABB Tree Collision Dectection from Azure From The Trenches.

Installation

AABBTree is available through PyPI and can be installed by running:

pip install aabb

To test that the package installed properly, run:

python -c "import aabb"

Alternatively, the package can be installed from source by downloading the latest release from the AABBTree repository on GitHub. Extract the source and, from the top-level directory, run:

pip install -e .

The --user flag may be needed, depending on permissions.

Example

The following example shows how to build an AABB tree and test for overlap:

>>> from aabb import AABB, AABBTree
>>> tree = AABBTree()
>>> aabb1 = AABB([(0, 0), (0, 0)])
>>> aabb2 = AABB([(-1, 1), (-1, 1)])
>>> aabb3 = AABB([(4, 5), (2, 3)])
>>> tree.add(aabb1, 'box 1')
>>> tree.does_overlap(aabb2)
True
>>> tree.overlap_values(aabb2)
['box 1']
>>> tree.does_overlap(aabb3)
False
>>> tree.add(aabb3)
>>> print(tree)
AABB: [(0, 5), (0, 3)]
Value: None
Left:
  AABB: [(0, 0), (0, 0)]
  Value: box 1
  Left: None
  Right: None
Right:
  AABB: [(4, 5), (2, 3)]
  Value: None
  Left: None
  Right: None

API

class aabb.AABB(limits=None)[source]

Bases: object

Axis aligned bounding box (AABB)

The AABB is a d-dimensional box.

Parameters:limits (iterable, optional) –

The limits of the box. These should be specified in the following manner:

limits = [(xmin, xmax), (ymin, ymax), (zmin, zmax), ...]

The default value is None.
classmethod merge(aabb1, aabb2)[source]

Merge AABB

Find the AABB of the union of AABBs.

Parameters:
  • aabb1 (AABB) – An AABB
  • aabb2 (AABB) – An AABB
Returns:

An AABB that contains both of the inputs
Return type:

AABB
overlaps(aabb)[source]

Determine if two AABBs overlap

Parameters:aabb (AABB) – The AABB to check for overlap
Returns:Flag set to true if the two AABBs overlap
Return type:bool
perimeter

Perimeter of AABB

The perimeter \(p_n\) of an AABB with side lengths \(l_1, ..., l_n\) is:

\[\begin{split}\begin{align} p_1 &= 0 \\ p_2 &= 2 (l_1 + l_2) \\ p_3 &= 2 (l_1 l_2 + l_2 l_3 + l_1 l_3) \\ p_n &= 2 \sum_{i=1}^n \prod_{j=1\neq i}^n l_j \end{align}\end{split}\]
class aabb.AABBTree(aabb=None, value=None, left=None, right=None)[source]

Bases: object

Python Implementation of the AABB Tree

This is a pure Python implementation of the static d-dimensional AABB tree. It is heavily based on Introductory Guide to AABB Tree Collision Dectection from Azure From The Trenches.

Parameters:
  • aabb (AABB) – An AABB
  • value – The value associated with the AABB
  • left (AABBTree, optional) – The left branch of the tree
  • right (AABBTree, optional) – The right branch of the tree
add(aabb, value=None)[source]

Add node to tree

This function inserts a node into the AABB tree.

Parameters:
  • aabb (AABB) – The AABB to add.
  • value – The value associated with the AABB. Defaults to None.
does_overlap(aabb)[source]

Check for overlap

This function checks if the limits overlap any leaf nodes in the tree. It returns true if there is an overlap.

Parameters:aabb (AABB) – The AABB to check.
Returns:True if overlaps with a leaf node of tree.
Return type:bool
overlap_values(aabb)[source]

Get values of overlapping AABBs

This function gets the value field of each overlapping AABB.

Parameters:aabb (AABB) – The AABB to check.
Returns:Value fields of each node that overlaps.
Return type:list
is_leaf

returns True if is leaf node

Type:bool

Contributing

Contributions to the project are welcome. Please visit the AABBTree repository to clone the source files, create a pull request, and submit issues.

Indices and tables