Merge pull request #19 from StellaOrg/df_traversal

More scalable Leaf-vs-Tree traversal

Author: anicusan

Project.toml

@@ -1,10 +1,11 @@
 name = "ImplicitBVH"
 uuid = "932a18dc-bb55-4cd5-bdd6-1368ec9cea29"
+version = "0.7.0"
 authors = ["Andrei Leonard Nicusan <[email protected]> and contributors"]
-version = "0.6.0"
 
 [deps]
 AcceleratedKernels = "6a4ca0a5-0e36-4168-a932-d9be78d558f1"
+Adapt = "79e6a3ab-5dfb-504d-930d-738a2a938a0e"
 ArgCheck = "dce04be8-c92d-5529-be00-80e4d2c0e197"
 Atomix = "a9b6321e-bd34-4604-b9c9-b65b8de01458"
 DocStringExtensions = "ffbed154-4ef7-542d-bbb7-c09d3a79fcae"
@@ -14,6 +15,7 @@ LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"
 
 [compat]
 AcceleratedKernels = "0.4"
+Adapt = "4.4.0"
 ArgCheck = "2"
 Atomix = "0.1, 1"
 DocStringExtensions = "0.9"

README.md

@@ -5,17 +5,16 @@
 [![Docs Stable](https://img.shields.io/badge/docs-stable-blue.svg)](https://stellaorg.github.io/ImplicitBVH.jl/stable)
 [![Docs Dev](https://img.shields.io/badge/docs-dev-blue.svg)](https://stellaorg.github.io/ImplicitBVH.jl/dev)
 [![Build Status](https://github.com/StellaOrg/ImplicitBVH.jl/workflows/CI/badge.svg)](https://github.com/StellaOrg/ImplicitBVH.jl/actions/workflows/ci.yml)
+[![Aqua QA](https://raw.githubusercontent.com/JuliaTesting/Aqua.jl/master/badge.svg)](https://github.com/JuliaTesting/Aqua.jl)
 
 
 # ImplicitBVH.jl
 *High-Performance Cross-Architecture Bounding Volume Hierarchy for Collision Detection and Ray Tracing*
 
-**New in v0.5.0: Ray Tracing and GPU acceleration via [AcceleratedKernels.jl](https://github.com/anicusan/AcceleratedKernels.jl)/[KernelAbstractions.jl](https://github.com/JuliaGPU/KernelAbstractions.jl) targeting all JuliaGPU backends, i.e. Nvidia CUDA, AMD ROCm, Intel oneAPI, Apple Metal.**
-
 It uses an implicit bounding volume hierarchy constructed from an iterable of some geometric
 primitives' (e.g. triangles in a mesh) bounding volumes forming the `ImplicitTree` leaves. The leaves
-and merged nodes above them can have different types - e.g. `BSphere{Float64}` leaves merged into
-larger `BBox{Float64}`.
+and merged nodes above them can have different types - e.g. `BSphere{Float32}` leaves merged into
+larger `BBox{Float32}`.
 
 The initial geometric primitives are sorted according to their Morton-encoded coordinates; the
 unsigned integer type used for the Morton encoding can be chosen between `UInt16`, `UInt32` and `UInt64`.
@@ -51,11 +50,11 @@ traversal = traverse(bvh)
 @show traversal.contacts
 
 # output
-traversal.contacts = [(1, 2), (2, 3), (4, 5)]
+traversal.contacts = Tuple{Int32, Int32}[(1, 2), (2, 3), (4, 5)]
 ```
 
-Using `Float32` bounding spheres for leaves, `Float32` bounding boxes for nodes above, and `UInt32`
-Morton codes:
+Using `Float32` bounding spheres for leaves, `Float32` bounding boxes for nodes above, `UInt32`
+Morton codes and `Int32` indices:
 
 ```julia
 using ImplicitBVH
@@ -71,29 +70,28 @@ bounding_spheres = [
 ]
 
 # Build BVH
-bvh = BVH(bounding_spheres, BBox{Float32}, UInt32)
+options = BVHOptions(index=Int32, morton=DefaultMortonAlgorithm(UInt32))
+bvh = BVH(bounding_spheres, BBox{Float32}, options=options)
 
 # Traverse BVH for contact detection
-traversal = traverse(bvh)
+traversal = traverse(bvh, options=options)
 @show traversal.contacts
 
 # output
 traversal.contacts = [(1, 2), (2, 3), (4, 5)]
 ```
 
-Build BVH up to level 2 and start traversing down from level 3, reusing the previous traversal
-cache:
+Update previous BVH bounding volumes' positions and rebuild BVH *reusing previous memory*:
 
 ```julia
-bvh = BVH(bounding_spheres, BBox{Float32}, UInt32, 2)
-traversal = traverse(bvh, 3, traversal)
-```
+# Use different numbers of threads (on CPUs) and block size (on GPUs)
+options = BVHOptions(num_threads=16, block_size=512)
 
-Update previous BVH bounding volumes' positions and rebuild BVH *reusing previous memory*:
+# ...update bvh.leaves positions in-place, then...
+bvh = BVH(bvh.leaves, BBox{Float32}, cache=bvh, options=options)
 
-```julia
-new_positions = rand(3, 5)
-bvh_rebuilt = BVH(bvh, new_positions)
+# Reuse previous traversal cache memory
+traversal = traverse(bvh, LVTTraversal(), cache=traversal)
 ```
 
 Compute contacts between two different BVH trees (e.g. two different robotic parts):
@@ -115,18 +113,11 @@ bounding_spheres2 = [
 ]
 
 # Build BVHs using bounding boxes for nodes
-bvh1 = BVH(bounding_spheres1, BBox{Float32}, UInt32)
-bvh2 = BVH(bounding_spheres2, BBox{Float32}, UInt32)
+bvh1 = BVH(bounding_spheres1, BBox{Float32})
+bvh2 = BVH(bounding_spheres2, BBox{Float32})
 
 # Traverse BVH for contact detection
-traversal = traverse(
-    bvh1,
-    bvh2,
-    default_start_level(bvh1),
-    default_start_level(bvh2),
-    # previous_traversal_cache,
-    # options=BVHOptions(),
-)
+traversal = traverse(bvh1, bvh2)
 ```
 
 Check out the `benchmark` folder for an example traversing an STL model.
@@ -153,7 +144,7 @@ bounding_spheres = ROCArray([
 ])
 
 # Build BVH
-bvh = BVH(bounding_spheres, BBox{Float32}, UInt32)
+bvh = BVH(bounding_spheres, BBox{Float32})
 
 # Traverse BVH for contact detection
 traversal = traverse(bvh)
@@ -179,7 +170,7 @@ mesh = load("xyzrgb_dragon.obj")
 bounding_spheres = [BSphere{Float32}(tri) for tri in mesh]
 
 # Build BVH
-bvh = BVH(bounding_spheres, BBox{Float32}, UInt32)
+bvh = BVH(bounding_spheres, BBox{Float32})
 
 # Generate some rays
 points = rand(Float32, 3, 1000)

benchmark/Project.toml

@@ -5,7 +5,9 @@ Cthulhu = "f68482b8-f384-11e8-15f7-abe071a5a75f"
 FileIO = "5789e2e9-d7fb-5bc7-8068-2c6fae9b9549"
 ImplicitBVH = "932a18dc-bb55-4cd5-bdd6-1368ec9cea29"
 JET = "c3a54625-cd67-489e-a8e7-0a5a0ff4e31b"
+KernelAbstractions = "63c18a36-062a-441e-b654-da1e3ab1ce7c"
 MeshIO = "7269a6da-0436-5bbc-96c2-40638cbb6118"
+Metal = "dde4c033-4e86-420c-a63e-0dd931031962"
 PProf = "e4faabce-9ead-11e9-39d9-4379958e3056"
 Profile = "9abbd945-dff8-562f-b5e8-e1ebf5ef1b79"
 Revise = "295af30f-e4ad-537b-8983-00126c2a3abe"

benchmark/bvh_build.jl

@@ -18,9 +18,12 @@ using PProf
 
 
 # Types used
-const LeafType = BSphere{Float32}
-const NodeType = BBox{Float32}
+const FloatType = Float32
+const LeafType = BSphere{FloatType}
+const NodeType = BBox{FloatType}
 const MortonType = UInt32
+const IndexType = Int32
+options = BVHOptions(index=IndexType, morton=DefaultMortonAlgorithm(MortonType))
 
 
 # Load mesh and compute bounding spheres for each triangle. Can download mesh from:
@@ -32,21 +35,26 @@ bounding_spheres = [LeafType(tri) for tri in mesh]
 # bounding_spheres = CuArray(bounding_spheres)
 
 # Pre-compile BVH build
-bvh = BVH(bounding_spheres, NodeType, MortonType)
+bvh = BVH(bounding_spheres, NodeType, options=options)
 
 # Benchmark BVH creation including Morton encoding
 println("BVH creation including Morton encoding:")
-display(@benchmark(BVH(bounding_spheres, NodeType, MortonType)))
+display(@benchmark BVH(bounding_spheres, NodeType, options=options))
 
 println("BVH with cached memory reuse:")
-display(@benchmark(BVH(bvh.leaves, NodeType, MortonType, 1, bvh)))
+display(@benchmark BVH(bvh.leaves, NodeType, cache=bvh, options=options))
 
 
-# Collect a pprof profile of the complete build
+# # Collect a pprof profile of the complete build
+# BVH(bvh.leaves, NodeType, options=options)
 # Profile.clear()
-# @profile BVH(bounding_spheres, NodeType, MortonType)
-
-# Export pprof profile and open interactive profiling web interface.
+# @profile begin
+#     for _ in 1:100
+#         BVH(bounding_spheres, NodeType, options=options)
+#     end
+# end
+# 
+# # Export pprof profile and open interactive profiling web interface.
 # pprof(; out="bvh_build.pb.gz")
 
 

benchmark/bvh_contact.jl

@@ -14,11 +14,17 @@ using BenchmarkTools
 using Profile
 using PProf
 
+# using Metal: MtlArray
+
 
 # Types used
-const LeafType = BSphere{Float32}
-const NodeType = BBox{Float32}
+const FloatType = Float32
+const LeafType = BSphere{FloatType}
+const NodeType = BBox{FloatType}
 const MortonType = UInt32
+const IndexType = Int32
+const alg = LVTTraversal()
+options = BVHOptions(index=IndexType, morton=DefaultMortonAlgorithm(MortonType))
 
 
 # Load mesh and compute bounding spheres for each triangle. Can download mesh from:
@@ -28,32 +34,26 @@ display(mesh)
 @show Threads.nthreads()
 
 bounding_spheres = [LeafType(tri) for tri in mesh]
+# bounding_spheres = MtlArray(bounding_spheres)
 
 # Pre-compile BVH traversal
-bvh = BVH(bounding_spheres, NodeType, MortonType)
-@show traversal = traverse(bvh)
-
-# Print algorithmic efficiency
-eff = traversal.num_checks / (length(bounding_spheres) * length(bounding_spheres) / 2)
-println("Did $eff of the total checks needed for brute-force contact detection")
+bvh = BVH(bounding_spheres, NodeType, options=options)
+@show traversal = traverse(bvh, alg)
 
 # Benchmark BVH traversal anew
-println("BVH traversal with dynamic buffer resizing:")
-display(@benchmark(traverse(bvh), samples=100))
+println("BVH traversal:")
+display(@benchmark traverse(bvh, alg))
 
-# Benchmark BVH creation reusing previous cache
-println("BVH traversal without dynamic buffer resizing:")
-display(@benchmark(traverse(bvh, bvh.tree.levels ÷ 2, traversal), samples=100))
 
-# Collect a pprof profile
+# # Collect a pprof profile
 # Profile.clear()
 # @profile begin
-#     for _ in 1:1000
-#         traverse(bvh, bvh.tree.levels ÷ 2, traversal)
+#     for _ in 1:10
+#         traverse(bvh, alg)
 #     end
 # end
-
-# Export pprof profile and open interactive profiling web interface.
+# 
+# # Export pprof profile and open interactive profiling web interface.
 # pprof(; out="bvh_contact.pb.gz")
 
 

benchmark/bvh_contact_pair.jl

@@ -14,13 +14,17 @@ using BenchmarkTools
 using Profile
 using PProf
 
-using CUDA: CuArray
+# using Metal: MtlArray
 
 
 # Types used
-const LeafType = BSphere{Float32}
-const NodeType = BBox{Float32}
+const FloatType = Float32
+const LeafType = BSphere{FloatType}
+const NodeType = BBox{FloatType}
 const MortonType = UInt32
+const IndexType = Int32
+const alg = LVTTraversal()
+options = BVHOptions(index=IndexType, morton=DefaultMortonAlgorithm(MortonType))
 
 
 # Load mesh and compute bounding spheres for each triangle. Can download mesh from:
@@ -30,29 +34,22 @@ display(mesh)
 @show Threads.nthreads()
 
 bounding_spheres = [LeafType(tri) for tri in mesh]
-bounding_spheres = CuArray(bounding_spheres)
+# bounding_spheres = MtlArray(bounding_spheres)
 
 # Pre-compile BVH traversal
-bvh = BVH(bounding_spheres, NodeType, MortonType)
-@show traversal = traverse(bvh, bvh)
+bvh = BVH(bounding_spheres, NodeType, options=options)
+@show traversal = traverse(bvh, bvh, alg)
 
-# Print algorithmic efficiency
-eff = traversal.num_checks / length(bounding_spheres)^2
-println("Did $eff of the total checks needed for brute-force contact detection")
+# Benchmark BVH traversal anew
+println("BVH traversal with dynamic buffer resizing:")
+display(@benchmark traverse(bvh, bvh, alg))
 
-# # Benchmark BVH traversal anew
-# println("BVH traversal with dynamic buffer resizing:")
-# display(@benchmark(traverse(bvh, bvh), samples=100))
-# 
-# # Benchmark BVH creation reusing previous cache
-# println("BVH traversal without dynamic buffer resizing:")
-# display(@benchmark(traverse(bvh, bvh, bvh.tree.levels ÷ 2, bvh.tree.levels ÷ 2, traversal), samples=100))
 
 # Collect a pprof profile
 # Profile.clear()
 # @profile begin
-#     for _ in 1:1000
-#         traverse(bvh, bvh.tree.levels ÷ 2, traversal)
+#     for _ in 1:10
+#         traverse(bvh, bvh, cache=traversal)
 #     end
 # end
 

benchmark/bvh_extended.jl

@@ -0,0 +1,26 @@
+using ImplicitBVH
+using ImplicitBVH: BSphere, BBox
+
+using MeshIO
+using FileIO
+
+using BenchmarkTools
+using Profile
+using PProf
+
+
+# Types used
+const LeafType = BSphere{Float32}
+const NodeType = BBox{Float32}
+options = BVHOptions(index_exemplar=Int32(0), morton=ExtendedMortonAlgorithm(UInt32(0)))
+
+
+# Load mesh and compute bounding spheres for each triangle. Can download mesh from:
+# https://github.com/alecjacobson/common-3d-test-models/blob/master/data/xyzrgb_dragon.obj
+mesh = load(joinpath(@__DIR__, "xyzrgb_dragon.obj"))
+display(mesh)
+
+bounding_spheres = [LeafType(tri) for tri in mesh]
+
+# Pre-compile BVH build
+bvh = BVH(bounding_spheres, NodeType, options=options)