package trial and error

bartofzo · bartofzo · commit 81a93d6dcdf4 · 2022-11-23T20:48:45.000+01:00
diff --git a/Packages/NativeTrees/README.md b/Packages/NativeTrees/README.md
@@ -1,6 +1,6 @@
-![NativeTrees](NativeTrees.png "NativeTrees")
+![NativeTrees](./Packages/NativeTrees/NativeTrees.png "NativeTrees")
 
-Generic sparse octree and quadtree 
+Generic sparse octree and quadtree
 that store objects together with their axis aligned bounding boxes (AABB's)
 
 Written in C# for Unity's burst compiler and the ECS/DOTS framework.
@@ -11,7 +11,6 @@ Tested with Unity 2021.1.3.11f1
 - Range (AABB overlap)
 - K-Nearest neighbours
 
-
 ### Other features:
 - Implemented as a sparse tree, so only stores nodes that are occupied. Memory usage is therefore relatively low.
   The octree has a max depth of 10 and the quad tree a max depth of 15.
@@ -22,30 +21,36 @@ Tested with Unity 2021.1.3.11f1
 ### Limitations:
 - Objects must be structs (Burst limitation)
 - No remove or update. Tried several approaches but they either left an unbalanced tree or doing a
-full clear and re-insert was faster.
+  full clear and re-insert was faster.
 - No foreach support, we leverage the stack and "struct" delegates, which suits the recursive
-nature of the tree better.
-  
+  nature of the tree better.
+
 - Insertion can only be done on a single thread. Queries ofcourse can be across multiple threads.
 
 ### Future todo's:
 - Frustrum query
 - 'Fat' raycast (virtually expand AABB's of nodes and objects when testing for ray intersections)
 
+## Installation
+
+Using the Unity package manager, choose Addd Package from git URL and enter:
+
+    https://github.com/bartofzo/NativeTrees.git?path=/Packages/NativeTrees
+
 ## Performance
 
-The trees are heaviliy optimized to make use of SIMD instructions. 
+The trees are heaviliy optimized to make use of SIMD instructions.
 Therefore performance is best when used in burst compiled code.
 
-Queries are *very* fast. 
+Queries are *very* fast.
 The raycast never visits more nodes than absolutely neccessary.
 The overlap (and insertion) use a technique where to test in which child nodes AABB's should go, only
 two comparisons are made followed up by some bitwise operations. (See the source for an explanation).
 
 Nearest neighbour is the slowest of the bunch (but still fast) as it has some overhead in keeping track of a priority queue.
 
 Actual performance can vary wildly depending on the structure of your tree and it's
-settings. For the sake of cool stats, here are some numbers on insertion times and raycasts for random points and AABB's, 
+settings. For the sake of cool stats, here are some numbers on insertion times and raycasts for random points and AABB's,
 Single thread burst compiled, maxDepth of 8. These numbers should not be taken too seriously because it's random data
 and the tree will be divided almost equally everywhere, which in most realistic scenarios is not the case.
 
@@ -63,15 +68,139 @@ Run on a MBP 16" i9 2.3 GHz from 2019.
 |500K     |51.00ms    |131.58ms |60.08ms    |164.17ms |0.84ms               |0.45ms
 |1M       |129.03ms   |260.55ms |152.50ms   |301.99ms |1.04ms               |0.55ms
 
+## Usage
+
+There are two samples included that show how to use the octree and quadtree.
+The extension classes provide readymade solutions for AABB only checking. For more complicated
+shapes you must provide your own ray/overlap/distance calculations.
+
+### Insertion
+The objects can be of any unmanaged type, when inserting, an AABB must be provided:
+
+    // Insert a bunch of triangles
+    for (int i = 0; i < tris.Length; i++)
+    {
+        var triangle = tris[i];
+        octree.Insert(triangle, triangle.GetAABB());
+    }
+
+Often times however, it's more efficient to insert Id's that map to something outside of
+the tree (like DOTS entities).
+
+If you know your objects are points, you can insert them faster by using:
+
+    // Insert entities that are 'points'
+    for (int i = 0; i < entities.Length; i++)
+    {
+        var entity = entities[i];
+        octree.InsertPoint(entities[i], positions[i]);
+    }
+
+Note that objects inserted as points only support range and nearest neighbour queries.
+
+### Queries
+
+All of the supported queries use the same pattern which is
+to (ab)use structs as a sort of delegate. This separates collision/intersection
+code from the type of objects, allowing you to insert even primitive types or types from another assembly.
+This turned out to be the most efficent and easiest to implement while keeping things fully compatibly with Unity's Burst compiler.
+
+### Raycast
+
+A raycast query for example, requires you to implement IOctreeRayIntersecter which
+acts as a delegate to determine if a ray intersects with an object that's in the tree.
+
+    public static bool RaycastAABB<T>(this NativeOctree<T> octree, Ray ray, out OctreeRaycastHit<T> hit) where T : unmanaged
+    { 
+      return octree.Raycast<RayAABBIntersecter<T>>(ray, out hit);
+    }
+
+    struct RayAABBIntersecter<T> : IOctreeRayIntersecter<T>
+    {
+      public bool IntersectRay(in PrecomputedRay ray, T obj, AABB objBounds, out float distance)
+      {
+        return objBounds.IntersectsRay(ray, out distance);
+      }
+    }
+
+The example above just tests the ray against the object's bounds. (See NativeOctreeExtensions) But you could go a step further
+and test it against a triangle, a collider and so forth. Note that the tree itself
+does not automatically test for Ray-AABB intersections on the objects, so it's usually a good decision to early exit
+if the ray doesn't exit with the object's bounds since those checks are cheap.
+
+### Nearest Neighbour
+NativeTrees support nearest neighbour queries. You should implement IOctreeNearestVisitor and IOctreeDistanceProvider.
+
+    struct AABBDistanceSquaredProvider<T> : IOctreeDistanceProvider<T> 
+    {
+        // Just return the distance squared to our bounds
+        public float DistanceSquared(float3 point, T obj, AABB bounds) => bounds.DistanceSquared(point);
+    }
+
+    struct OctreeNearestAABBVisitor<T> : IOctreeNearestVisitor<T>
+    {
+        public T nearest;
+        public bool found;
+        
+        public bool OnVist(T obj)
+        {
+            this.found = true;
+            this.nearest = obj;
+            
+            return false; // immediately stop iterating at first hit
+            // if we want the 2nd or 3rd neighbour, we could iterate on and keep track of the count!
+        }
+    }
+
+The extensions classes show an example of these implementation. But only for AABB's.
+If you need more detail on your distance, you can implement your type specific behaviour using these interfaces.
+
+To get the nearest neighbour:
+
+    var visitor = new OctreeNearestAABBVisitor<Entity>();
+    octree.Nearest(point, maxDistance, ref visitor, default(AABBDistanceSquaredProvider<Entity>));
+    Entity nearestEntity = visitor.nearest;
+
+### Range
+
+Here's an example that adds unique objects that overlap with a range to a hashset:
+
+    public static void RangeAABBUnique<T>(this NativeOctree<T> octree, AABB range, NativeParallelHashSet<T> results) 
+      where T : unmanaged, IEquatable<T>
+    {
+        var vistor = new RangeAABBUniqueVisitor<T>()
+        {
+            results = results
+        };
+     
+        octree.Range(range, ref vistor);
+    }
+
+    struct RangeAABBUniqueVisitor<T> : IOctreeRangeVisitor<T> where T : unmanaged, IEquatable<T>
+    {
+        public NativeParallelHashSet<T> results;
+        
+        public bool OnVisit(T obj, AABB objBounds, AABB queryRange)
+        {
+            // check if our object's AABB overlaps with the query AABB
+            if (objBounds.Overlaps(queryRange))
+                results.Add(obj);
+
+            return true; // always keep iterating, we want to catch all objects
+        }
+    }
+
+It's important to note that the query itself iterates all of the objects that are in nodes that overlap with
+the input range. An extra check should be performed to test if the object overlaps.
+Also, if the objects aren't points, it's possible for them to be visited multiple times as they reside in more than one node.
+A hashset can be used to only visit each object once.
+
 ### Support
 Feel free to raise an issue or contact me for any questions.
+The code is free to use in your project(s).
+If this was helpful to you, consider buying me a coffee ;)
 
-### Donate
-The code is free to use in your project(s). 
-If this was helpful to you and you're feeling generous, you can support me with a donation to help me pay for my energy bills and making
-more of these projects in the future ;)
-
-[![paypal](https://www.paypalobjects.com/en_US/i/btn/btn_donateCC_LG.gif)](https://paypal.me/bartofzo?country.x=NL&locale.x=nl_NL)
+https://ko-fi.com/bartofzo
 
 Thank you!
 
diff --git a/Packages/NativeTrees/Runtime/bartofzo.nativetrees.asmdef b/Packages/NativeTrees/Runtime/bartofzo.nativetrees.asmdef
@@ -2,8 +2,8 @@
     "name": "com.bartofzo.nativetrees",
     "rootNamespace": "NativeTrees",
     "references": [
-        "GUID:e0cd26848372d4e5c891c569017e11f1",
-        "GUID:d8b63aba1907145bea998dd612889d6b"
+        "Unity.Collections",
+        "Unity.Mathematics"
     ],
     "includePlatforms": [],
     "excludePlatforms": [],
diff --git a/Packages/NativeTrees/Samples/bartofzo.nativetrees.samples.asmdef b/Packages/NativeTrees/Samples/bartofzo.nativetrees.samples.asmdef
@@ -2,10 +2,10 @@
     "name": "com.bartofzo.nativetrees.samples",
     "rootNamespace": "NativeTrees.Samples",
     "references": [
-        "GUID:2665a8d13d1b3f18800f46e256720795",
-        "GUID:17f495d31df1b4f1c90363273beccc77",
-        "GUID:e0cd26848372d4e5c891c569017e11f1",
-        "GUID:d8b63aba1907145bea998dd612889d6b"
+        "Unity.Burst",
+        "com.bartofzo.nativetrees",
+        "Unity.Collections",
+        "Unity.Mathematics"
     ],
     "includePlatforms": [],
     "excludePlatforms": [],
diff --git a/Packages/NativeTrees/package.json b/Packages/NativeTrees/package.json
@@ -10,5 +10,10 @@
     "spatial partitioning"
   ],
   "category": "Unity",
-  "type": "library"
+  "type": "library",
+  "dependencies": {
+    "com.unity.collections": "",
+    "com.unity.burst": "",
+    "com.unity.mathematics": ""
+  }
 }
diff --git a/Packages/packages-lock.json b/Packages/packages-lock.json
@@ -4,7 +4,11 @@
       "version": "file:NativeTrees",
       "depth": 0,
       "source": "embedded",
-      "dependencies": {}
+      "dependencies": {
+        "com.unity.collections": "",
+        "com.unity.burst": "",
+        "com.unity.mathematics": ""
+      }
     },
     "com.unity.burst": {
       "version": "1.6.6",
diff --git a/README.md b/README.md
@@ -11,7 +11,6 @@ Tested with Unity 2021.1.3.11f1
 - Range (AABB overlap)
 - K-Nearest neighbours
 
-
 ### Other features:
 - Implemented as a sparse tree, so only stores nodes that are occupied. Memory usage is therefore relatively low.
   The octree has a max depth of 10 and the quad tree a max depth of 15.
@@ -32,6 +31,12 @@ nature of the tree better.
 - Frustrum query
 - 'Fat' raycast (virtually expand AABB's of nodes and objects when testing for ray intersections)
 
+## Installation
+
+Using the Unity package manager, choose Addd Package from git URL and enter:
+
+    https://github.com/bartofzo/NativeTrees.git?path=/Packages/NativeTrees
+
 ## Performance
 
 The trees are heaviliy optimized to make use of SIMD instructions. 
@@ -192,8 +197,6 @@ A hashset can be used to only visit each object once.
 
 ### Support
 Feel free to raise an issue or contact me for any questions.
-
-### Donate
 The code is free to use in your project(s). 
 If this was helpful to you, consider buying me a coffee ;)
 
