QuadTree documentation

Add documentation for quadtree (next up tests, then implementation)

* docs/Data_Structure.rst - add quadtree
* pygorithm/data_structures/quadtree.py - add skeleton, documentation
* tests/test_data_structure.py - add skeleton for quadtree tests

Author: Tjstretchalot

docs/Data_Structure.rst

@@ -41,6 +41,8 @@ Features
         - Check cycle in Undirected Graph (data_structures.graph.CheckCycleUndirectedGraph)
     - **Heap**
         - Heap (data_structures.heap.Heap)
+    - **QuadTree**
+        - QuadTree (data_structures.quadtree.QuadTree)
 
 * Get the code used for any of the implementation
 
@@ -214,3 +216,21 @@ Trie
     -----
     .. autoclass:: Trie
         :members:
+        
+QuadTree
+--------
+
+.. automodule:: pygorithm.data_structures.quadtree
+
+    QuadTreeEntity
+    --------------
+    .. autoclass:: QuadTreeEntity
+        :members:
+        :special_members:
+        
+    QuadTree
+    --------
+    .. autoclass:: QuadTree
+        :members:
+        :special_members:
+    

pygorithm/data_structures/quadtree.py

@@ -9,14 +9,346 @@
 
 from pygorithm.geometry import (vector2, polygon2, rect2)
 
+class QuadTreeEntity(object):
+    """
+    This is the minimum information required for an object to 
+    be usable in a quadtree as an entity. Entities are the 
+    things that you are trying to compare in a quadtree.
+    
+    :ivar aabb: the axis-aligned bounding box of this entity
+    :type aabb: :class:`pygorithm.geometry.rect2.Rect2`
+    """
+    def __init__(self, aabb):
+        """
+        Create a new quad tree entity with the specified aabb
+        
+        :param aabb: axis-aligned bounding box
+        :type aabb: :class:`pygorithm.geometry.rect2.Rect2`
+        """
+        pass
+    
+    def __repr__(self):
+        """
+        Create an unambiguous representation of this entity.
+        
+        Example:
+        
+        .. code-block:: python
+            
+            from pygorithm.geometry import (vector2, rect2)
+            from pygorithm.data_structures import quadtree
+            
+            _ent = quadtree.QuadTreeEntity(rect2.Rect2(5, 5))
+            
+            # prints quadtreeentity(aabb=rect2(width=5, height=5, mincorner=vector2(x=0, y=0)))
+            print(repr(_ent))
+        
+        :returns: unambiguous representation of this quad tree entity
+        :rtype: string
+        """
+        pass
+    
+    def __str__(self):
+        """
+        Create a human readable representation of this entity
+        
+        Example:
+        
+        .. code-block:: python
+            
+            from pygorithm.geometry import (vector2, rect2)
+            from pygorithm.data_structures import quadtree
+            
+            _ent = quadtree.QuadTreeEntity(rect2.Rect2(5, 5))
+            
+            # prints entity(at rect(5x5 at <0, 0>))
+            print(str(_ent))
+        
+        :returns: human readable representation of this entity
+        :rtype: string
+        """
+        pass
+        
 class QuadTree(object):
     """
     A quadtree is a sorting tool for two-dimensional space, most
     commonly used to reduce the number of required collision 
     calculations in a two-dimensional scene. In this context, 
     the scene is stepped without collision detection, then a 
     quadtree is constructed from all of the boundaries
+    
+    .. caution::
+        
+        Just because a quad tree has split does not mean entities will be empty. Any
+        entities which overlay any of the lines of the split will be included in the 
+        parent class of the quadtree.
+    
+    .. tip::
+        
+        It is important to tweak bucket size and depth to the problem, but a common error 
+        is too small a bucket size. It is typically not reasonable to have a bucket size 
+        smaller than 16; A good starting point is 64, then modify as appropriate. Larger
+        buckets reduce the overhead of the quad tree which could easily exceed the improvement
+        from reduced collision checks. The max depth is typically just a sanity check since 
+        depth greater than 4 or 5 would either indicate a badly performing quadtree (too 
+        dense objects, use an r-tree or kd-tree) or a very large world (where an iterative 
+        quadtree implementation would be appropriate).
+    
+    :ivar bucket_size: maximum number objects per bucket (before :py:attr:`.max_depth`)
+    :type bucket_size: int
+    :ivar max_depth: maximum depth of the quadtree 
+    :type max_depth: int
+    :ivar depth: the depth of this node (0 being the topmost)
+    :type depth: int
+    :ivar location: where this quad tree node is situated
+    :type location: :class:`pygorithm.geometry.rect2.Rect2`
+    :ivar entities: the entities in this quad tree and in NO OTHER related quad tree
+    :type entities: list of :class:`.QuadTreeEntity`
+    :ivar children: either None or the 4 :class:`.QuadTree` children of this node
+    :type children: None or list of :class:`.QuadTree`
     """
+    
+    def __init__(self, bucket_size, max_depth, location, depth = 0, entities = None):
+        """
+        Initialize a new quad tree. 
+        
+        .. warning::
+            
+            Passing entities to this quadtree will NOT cause it to split automatically!
+            You must call :py:meth:`.think` for that. This allows for more predictable
+            performance per line.
+            
+        :param bucket_size: the number of entities in this quadtree 
+        :type bucket_size: int
+        :param max_depth: the maximum depth for automatic splitting 
+        :type max_depth: int
+        :param location: where this quadtree is located
+        :type location: :class:`pygorithm.geometry.rect2.Rect2`
+        :param depth: the depth of this node
+        :type depth: int
+        :param entities: the entities to initialize this quadtree with 
+        :type entities: list of :class:`.QuadTreeEntity` or None for empty list
+        """
+        pass
+    
+    def think(self, recursive = False):
+        """
+        Call :py:meth:`.split` if appropriate
+        
+        Split this quad tree if it has not split already and it has more 
+        entities than :py:attr:`.bucket_size` and :py:attr:`.depth` is 
+        less than :py:attr:`.max_depth`.
+        
+        If `recursive` is True, think is called on the :py:attr:`.children` with 
+        recursive set to True after splitting.
+        
+        :param recursive: if `think(True)` should be called on :py:attr:`.children` (if there are any)
+        :type recursive: bool
+        """
+        pass
+    
+    def split(self):
+        """
+        Split this quadtree.
+        
+        .. caution::
+            
+            A call to split will always split the tree or raise an error. Use 
+            :py:meth:`.think` if you want to ensure the quadtree is operating
+            efficiently.
+            
+        .. caution::
+            
+            This function will not respect :py:attr:`.bucket_size` or 
+            :py:attr:`.max_depth`.
+            
+        :raises ValueError: if :py:attr:`.children` is not empty
+        """
+        pass
+    
+    def get_quadrant(self, entity):
+        """
+        Calculate the quadrant that the specified entity belongs to.
+        
+        Quadrants are:
+        
+         - -1: None (it overlaps 2 or more quadrants)
+         -  0: Top-left
+         -  1: Top-right
+         -  2: Bottom-right
+         -  3: Bottom-left
+         
+         .. caution::
+            
+            This function does not verify the entity is contained in this quadtree.
+        
+        This operation takes O(1) time.
+        
+        :param entity: the entity to place
+        :type entity: :class:`.QuadTreeEntity`
+        :returns: quadrant
+        :rtype: int
+        """
+        pass
+    
+    def insert_and_think(self, entity):
+        """
+        Insert the entity into this or the appropriate child.
+        
+        This also acts as thinking (recursively). Using insert_and_think
+        iteratively is slightly less efficient but more predictable performance,
+        whereas initializing with a large number of entities then thinking is slightly
+        faster but may hang. Both may exceed recursion depth if max_depth
+        is too large.
+        
+        :param entity: the entity to insert
+        :type entity: :class:`.QuadTreeEntity`
+        """
+        pass
+        
+    def retrieve_collidables(self, entity, predicate = None):
+        """
+        Find all entities that could collide with the specified entity.
+        
+        .. warning::
+            
+            If entity is, itself, in the quadtree, it will be returned. The 
+            predicate may be used to prevent this using your preferred equality
+            method.
+            
+        The predicate takes 1 positional argument (the entity being considered)
+        and returns `False` if the entity should never be returned, even if it 
+        might collide with the entity. It should return `True` otherwise.
+        
+        :param entity: the entity to find collidables for
+        :type entity: :class:`.QuadTreeEntity`
+        :param predicate: the predicate
+        :type predicate: :class:`types.FunctionType` or None
+        :returns: potential collidables (never `None)
+        :rtype: list of :class:`.QuadTreeEntity`
+        """
+        pass
+        
+    def find_entities_per_depth(self):
+        """
+        Calculate the number of nodes and entities at each depth level in this
+        quad tree. Only returns for depth levels at or equal to this node.
+        
+        This is implemented iteratively. See :py:meth:`.__str__` for usage example.
+        
+        :returns: dict of depth level to (number of nodes, number of entities)
+        :rtype: dict int: (int, int)
+        """
+        pass
+        
+    def sum_entities(self, entities_per_depth=None):
+        """
+        Sum the number of entities in this quad tree and all lower quad trees.
+        
+        If entities_per_depth is not None, that array is used to calculate the sum 
+        of entities rather than traversing the tree.
+        
+        :param entities_per_depth: the result of :py:meth:`.find_entities_per_depth`
+        :type entities_per_depth: `dict int: (int, int)` or None
+        :returns: number of entities in this and child nodes
+        :rtype: int
+        """
+        pass
+        
+    def calculate_avg_ents_per_leaf(self):
+        """
+        Calculate the average number of entities per leaf node on this and child
+        quad trees. 
+        
+        In the ideal case, the average entities per leaf is equal to the bucket size,
+        implying maximum efficiency.
+        
+        This is implemented iteratively. See :py:meth:`.__str__` for usage example.
+        
+        :returns: average number of entities at each leaf node
+        :rtype: :class:`numbers.Number`
+        """
+        pass
+        
+    def calculate_weight_misplaced_ents(self, sum_entities=None):
+        """
+        Calculate a rating for misplaced entities.
+        
+        A misplaced entity is one that is not on a leaf node. That weight is multiplied
+        by 4*remaining maximum depth of that node, to indicate approximately how 
+        many additional calculations are required.
+        
+        The result is then divided by the total number of entities on this node (either
+        calculated using :py:meth:`.sum_entities` or provided) to get the approximate 
+        cost of the misplaced nodes in comparison with the placed nodes. A value greater 
+        than 1 implies a different tree type (such as r-tree or kd-tree) should probably be
+        used.
+        
+        :param sum_entities: the number of entities on this node
+        :type sum_entities: int or None
+        :returns: weight of misplaced entities
+        :rtype: :class:`numbers.Number`
+        """
+        pass
+        
+    def __repr__(self):
+        """
+        Create an unambiguous, recursive representation of this quad tree.
+        
+        Example:
+        
+        .. code-block:: python
+            
+            from pygorithm.geometry import (vector2, rect2)
+            from pygorithm.data_structures import quadtree
+            
+            # create a tree with a up to 2 entities in a bucket that 
+            # can have a depth of up to 5.
+            _tree = quadtree.QuadTree(2, 5, rect2.Rect2(100, 100))
+            
+            # add a few entities to the tree
+            _tree.insert_and_think(quadtree.QuadTreeEntity(rect2.Rect2(2, 2, vector2.Vector2(5, 5))))
+            _tree.insert_and_think(quadtree.QuadTreeEntity(rect2.Rect2(2, 2, vector2.Vector2(95, 5))))
+            
+            # prints quadtree(bucket_size=2, max_depth=5, location=rect2(width=100, height=100, mincorner=vector2(x=0, y=0)), depth=0, entities=[], children=[ quadtree(bucket_size=2, max_depth=5, location=rect2(width=50, height=50, mincorner=vector2(x=0, y=0)), depth=1, entities=[ quadtreeentity(aabb=rect2(width=2, height=2, mincorner=vector2(x=5, y=5))) ], children=[]), quadtree(bucket_size=2, max_depth=5, location=rect2(width=50, height=50, mincorner=vector2(x=50, y=0)), depth=1, entities=[ quadtreeentity(aabb=rect2(width=2, height=2, mincorner=vector2(x=95, y=5))) ], children=[]), quadtree(bucket_size=2, max_depth=5, location=rect2(width=50, height=50, mincorner=vector2(x=50, y=50)), depth=1, entities=[], children=[]), quadtree(bucket_size=2, max_depth=5, location=rect2(width=50, height=50, mincorner=vector2(x=0, y=50)), depth=1, entities=[], children=[]) ])
+            print(repr(_tree))
+        
+        :returns: unambiguous, recursive representation of this quad tree
+        :rtype: string
+        """
+        pass
+    
+    def __str__(self):
+        """
+        Create a human-readable representation of this quad tree
+        
+        .. caution::
+            
+            Because of the complexity of quadtrees it takes a fair amount of calculation to
+            produce something somewhat legible. All returned statistics have paired functions
+        
+        Example:
+        
+        .. code-block:: python
+            
+            from pygorithm.geometry import (vector2, rect2)
+            from pygorithm.data_structures import quadtree
+            
+            # create a tree with a up to 2 entities in a bucket that 
+            # can have a depth of up to 5.
+            _tree = quadtree.QuadTree(2, 5, rect2.Rect2(100, 100))
+            
+            # add a few entities to the tree
+            _tree.insert_and_think(quadtree.QuadTreeEntity(rect2.Rect2(2, 2, vector2.Vector2(5, 5))))
+            _tree.insert_and_think(quadtree.QuadTreeEntity(rect2.Rect2(2, 2, vector2.Vector2(95, 5))))
+            
+            # prints quadtree(at rect(100x100 at <0, 0>) with 0 entities here (2 in total); (nodes, entities) per depth: [ 0: (1, 0), 1: (4, 2) ] (max depth: 5), avg ent/leaf: 0.5 (target 2), misplaced weight = 0 (0 best, >1 bad))
+        
+        :returns: human-readable representation of this quad tree
+        :rtype: string
+        """
+        pass
+        
     @staticmethod
     def get_code():
         """