Package: nontree
nontreeA python package for n-tree 2D data structures similar to and including quadtree, with mapping to payload dataExplore the docs »Report Bug·Request FeatureTable of ContentsAbout The ProjectGetting StartedPrerequisitesInstallationDemoUsageData TypesConstructing A TreeMapAdding Data Points To A TreeMapCollision DetectionContributingTestingLicenseProject LinksAbout The ProjectThis package implements quadtree-like data structures in the classesNonTree,QuadTreeandBiTree.
More precisely speaking,point-region (PR) quadtreesand variants thereof are implemented.
It also provides the classTreeMapto map points from the tree to arbitrary payload data, with a dictionary-like interface.A point-region quadtree is a recursive data structure to contain points that lie on a two dimensional surface.
It allows for efficient collision detection between the containend points and an area.
Thus it can answer the question "Which points are within that rectangular area?".In comparision to looping over all points and comparing the location of each point with the rectangular boundaries,
a quadtree delivers the answer inO(log(n)) instead ofO(n).This implementation also provides methods for circular collision detection.An exemplary application could be to test elements on a map of a 2D game, before rendering each frame, whether they are in the screen area and thus must be drawn,
or if the time of drawing them can be saved due to them not beeing in a visible area anyway.For more information about quadtrees in general, see theWikipedia article.
Or more specifically theparagraphabout point region quadtrees.A quadtree (4-tree) is split into 4 subtrees, if its bucket capacity is full and additional points are added. Thus, it's area gets split into 4 quadrants.
The points then are stored in the subtrees, until they are at capacity and get split as well.
That's the well known quadtree data structure.
This package also implements two unusual variants thereof: The non-tree (9-tree) and the alternating bi-tree (2-tree).The quadtree splits each tree into 9 segments in a 3 by 3 grid.
Due to reduced nesting depth, the retrieval of colliding points can be faster on a densely populated surface.The bitree splits each tree in only 2 segments, alternatingly horizontally or vertically.
This tends to result in a higher nesting depth. But at each level, only two instead of four or nine subtrees have to be considered.
Thus it can be faster on a very sparsely populated surface.The classTreeMapinternally contains aNonTree(the default) or aQuadTreeorBiTree.
It maps the points of the tree to payload data. This allows the retrieval of objects that lie in the searched area.If no payload data is needed, and only the bare points are of interest, the tree classes can be used directly.Additionally, a modulevisualizeexists, to plot a graph of the layout of a tree with the help ofmatplotlib.Getting StartedInstall the package, import a module, and call a function.PrerequisitesThis is a package for python3 (>=3.10). Slightly older versions of python3 might work, but are entirely untested.The package has no mandatory dependencies of other external packages, but it optionally can make use of the follwing, if present:matplotlibto plot graphs of the tree layout, such as the one shown above.
It is used by the modulevisualize.numbato speed up (jit-compile) some of the calculations for circular collision detection.
It gets detected/used automatically, without need for configuration or passing options.InstallationYou can get the raw files from the git repository:gitclonehttps://github.com/iehgit/nontree.gitIt's easier to install the package withpip:pipinstallnontreeDemoTo see that the package has been installed and is accessible, you could plot a demo graph, if you also havematplotlibavailable:>>>fromnontreeimportvisualize>>>visualize.plot_demo()>>>Or you could simply construct a TreeMap, set a datapoint, and get back its data:>>>fromnontree.TreeMapimportTreeMap>>>tree_map=TreeMap((0,0,100,100))>>>tree_map[(50,50)]='Hello World!'>>>tree_map[(50,50)]'Hello World!'>>>UsageData TypesPoints are defined as tuples in the shape of (x, y).Data points are defined as tuples in the shape of (point, data), i.e. ((x, y), data), with data beeing any arbitrary object.Rectangular areas are defined as tuples in the shape of (x, y, width, height), or anything that can be indexed in the same way.
This allows the use ofpygame.Rect.Circular areas are defined as tuples in the shape of (x, y, radius).Constructing A TreeMapATreeMapcan be constructed like this, with a rectangle as its first parameter to specify its surface:fromnontree.TreeMapimportTreeMaptree_map=TreeMap((0,0,100,100))Per default, it contains aNonTree. To specify the tree type, you can use the keyword argumentmode, like this:fromnontree.TreeMapimportTreeMaptree_map_foo=TreeMap((0,0,100,100),mode=9)# NonTreetree_map_bar=TreeMap((0,0,100,100),mode=4)# QuadTreetree_map_baz=TreeMap((0,0,100,100),mode=2)# BiTreeAdding Data Points To A TreeMapTo add multiple data points:fromnontree.TreeMapimportTreeMapa_lot_of_datapoints=[((2,3),'dog'),((17,80),'cat'),((45,13),'fish'),((99,77),'rat')]tree_map=TreeMap((0,0,100,100))tree_map.add_datapoints(a_lot_of_datapoints)To add a single data point, the dict-like interface is convenient:fromnontree.TreeMapimportTreeMaptree_map=TreeMap((0,0,100,100))tree_map[(55,89)]='goat'Collision DetectionTo query the data within an rectangular area of the surface, you can use the methodget_rect, which takes a rectangle as its parameter:fromnontree.TreeMapimportTreeMapa_lot_of_datapoints=[((2,3),'dog'),((17,80),'cat'),((45,13),'fish'),((99,77),'rat')]tree_map=TreeMap((0,0,100,100))tree_map.add_datapoints(a_lot_of_datapoints)tree_map[(55,89)]='goat'result=tree_map.get_rect((4,4,80,80))print(result)Output of the above:['fish', 'cat']For more details, please refer to theDocumentation.ContributingContributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make aregreatly appreciated.If you have a suggestion that would make this better, please fork the repo and create a pull request. Please make sure that all unit tests still pass after any changes.Fork the ProjectCreate your Feature Branch (git checkout -b feature/AmazingFeature)Commit your Changes (git commit -m 'Add some AmazingFeature')Push to the Branch (git push origin feature/AmazingFeature)Open a Pull RequestYou can also simply open an issue with the tag "enhancement".TestingTo run the unit tests:cdtestsPYTHONPATH=../srcpython3utest.pyThe output should look roughly similar to this:......................................
-------------------------------------------------------------------------------
Ran 38 tests in 0.308s

PASSED (successes=38)LicenseDistributed under the MIT License. SeeLICENSEfor more information.Project LinksGithubPyPIAPI documentation