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}\]
-
classmethod
-
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.
License and Copyright Notice¶
Copyright © 2019, Georgia Tech Research Corporation
AABBTree is open source and freely available under the terms of the MIT license.
License
MIT License
Copyright (c) 2019 Georgia Tech Research Corporation
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.