three-mesh-bvh: eine BVH-Implementierung für Raycasting und räumliche Abfragen in three.js
gkjohnson/three-mesh-bvh bietet eine praxistaugliche Open-Source-Implementierung mit stabiler Einsatzbarkeit für reale Anwendungsfälle.
Auf einen Blick
- Was ist das?
- Eine Bibliothek, die Bounding-Volume-Hierarchien für three.js-Geometrien aufbaut, um Raycasting zu beschleunigen und räumliche Abfragen wie Kugelschnittpunkte und Nächstpunkt-Tests zu unterstützen.
- Für wen ist es gedacht?
- Die MIT-Lizenz erlaubt die Nutzung, Vervielfältigung, Änderung, Zusammenführung, Veröffentlichung, Verteilung, Unterlizenzierung und den Verkauf von Kopien, sofern der Urheberrechtshinweis enthalten ist. Der Lizenztext erwähnt keine Unterstützung, Garantie oder Wartungspflichten; die Software wird 'wie besehen' bereitgestellt.
- Darf ich es kommerziell nutzen?
- Ja. MIT ist eine freizügige Lizenz: Sie dürfen darauf aufbauende Software nutzen, verändern und verkaufen, solange Sie die Urheberrechts- und Lizenzhinweise beibehalten.
- Wird es noch gepflegt?
- Ja. Die letzten Commits kamen vor 6 Tagen.
- In welcher Sprache ist es geschrieben?
- Hauptsächlich JavaScript, laut der Sprachstatistik von GitHub.
Die Antworten beruhen auf den GitHub-Daten des Projekts (zuletzt abgeglichen am 14. September 2026) und auf unserer Analyse. Sie sind keine Rechtsberatung.
TIEFGEHENDE OPEN-SOURCE-ANALYSE
Bounding-Volume-Hierarchien für three.js-Meshes
three-mesh-bvh ist eine JavaScript-Bibliothek, die eine Bounding-Volume-Hierarchie (BVH) für three.js-BufferGeometry-Objekte konstruiert. Das README beschreibt sie als eine Möglichkeit, Raycasting zu beschleunigen und räumliche Abfragen gegen Meshes zu ermöglichen. Das Hauptbeispiel zeigt 500 Strahlen, die mit 60 Bildern pro Sekunde gegen ein Modell mit 80.000 Polygonen geworfen werden. Eine BVH organisiert die Geometrie in einem Baum von Bounding-Volumes, sodass Strahlschnitttests große Teile des Meshes überspringen können, die den Strahl nicht schneiden. Das Projekt enthält einen Link zum Wikipedia-Artikel über Bounding-Volume-Hierarchien für Leser, die mit der Technik nicht vertraut sind.
Verwendung der vorgefertigten Erweiterungsfunktionen
Das README zeigt zwei Möglichkeiten, die Bibliothek zu verwenden. Die erste patcht three.js-Prototypen mit Funktionen wie computeBoundsTree und acceleratedRaycast und ruft dann computeBoundsTree auf einer Geometrie auf, um eine BVH zu generieren. Die zweite konstruiert manuell eine MeshBVH und weist sie der boundsTree-Eigenschaft der Geometrie zu. Danach funktioniert Raycasting über three.js' Raycaster mit der beschleunigten Funktion. Das README weist auch darauf hin, dass das Setzen von raycaster.firstHitOnly auf true die Raycast-Funktion dazu bringt, einen schnelleren 'raycastFirst'-Pfad zu verwenden.
Spezialisierte BVHs für Punkte, Linien und andere Primitive
Über Dreiecksnetze hinaus bietet die Bibliothek PointsBVH, LineBVH, LineLoopBVH und LineSegmentsBVH für THREE.Points-, THREE.Line-, THREE.LineLoop- und THREE.LineSegments-Geometrien. Diese können verwendet werden, indem eine type-Option an computeBoundsTree übergeben oder die Klasse direkt konstruiert wird. Jeder BVH-Typ implementiert eine Kern-API einschließlich shapecast und raycastObject3D für seinen Primitive-Typ. Das README stellt fest, dass einige Funktionen wie Webworker-Generierung und Serialisierung für diese spezialisierten BVHs derzeit nicht unterstützt werden.
Direkte Abfrage der BVH
Für Anwendungen, die mehr Kontrolle benötigen, kann die MeshBVH-Instanz direkt abgefragt werden. Das Beispiel im README verwendet bvh.raycastFirst(ray), um den ersten Treffer zu erhalten, und bvh.intersectsSphere(sphere), um Kugelschnittpunkte zu testen. Abfragen arbeiten im lokalen Geometrie-Raum, daher müssen Strahl oder Kugel mit der inversen Weltmatrix des Meshes transformiert werden, und Ergebnisse wie hit.point müssen zurück in den Weltraum transformiert werden. Das README warnt, dass bei Verwendung des eingebauten Raycastings von three.js Ergebnisse automatisch in Weltkoordinaten umgewandelt werden.
Serialisierung und asynchrone Generierung
Die Bibliothek unterstützt das Serialisieren einer BVH in eine kompakte Form und das spätere Deserialisieren mit MeshBVH.serialize und MeshBVH.deserialize. Für große Geometrien ist eine asynchrone Generierung über GenerateMeshBVHWorker verfügbar, das aus dem Unterpfad 'three-mesh-bvh/worker' exportiert wird. Eine parallele Variante, ParallelMeshBVHWorker, verwendet SharedArrayBuffer, wenn verfügbar, und fällt andernfalls auf den Single-Thread-Worker zurück. Das README empfiehlt, dass Geometrie, die an den parallelen Worker übergeben wird, position- und index-Arrays haben sollte, die von SharedArrayBuffer unterstützt werden, um Pufferkopien zu vermeiden.
Bekannte Einschränkungen und Stolpersteine
Das README listet mehrere Einschränkungen auf. Die Bounding-Hierarchie ist nicht dynamisch, daher können Morph-Ziele und geskinnete Meshes sie nicht verwenden; nur direkte Änderungen der Vertex-Positionen gefolgt von einem refit-Aufruf werden unterstützt. Die Geometrie darf keine Interleaved-Index-Pufferattribute haben. Für jede Geometriegruppe wird eine separate BVH-Wurzel generiert, was die Leistung bei Geometrien mit vielen Gruppen beeinträchtigen kann, und Dreiecke, die aus Gruppen ausgeschlossen sind, werden nicht in die BVH aufgenommen. Für sehr große oder außermittige Geometrie empfiehlt das README, mit BufferGeometry.center() zu zentrieren, um Probleme mit der Gleitkommapräzision zu reduzieren.
Beispiele und Ökosystem
Das README verlinkt auf eine breite Palette von Live-Beispielen, darunter Raycasting, geskinnte Geometrie, Punktwolken-Schnittpunkte, Linien-Schnittpunkte, Form-Schnittpunkte, SDF-Generierung, WebWorker-Generierung und einen BVH-Options-Inspektor. Es gibt auch Werkzeugbeispiele wie Bildhauen, Entfernungsvergleich, Dreiecksmalen, Lasso-Auswahl, beschnittene Kanten und Voxelisierung, sowie Spielbeispiele für Kugelphysik und Spielerbewegung und Path-Tracing-Demos. Das Projekt listet mehrere externe Projekte auf, die es verwenden, darunter three-gpu-pathtracer und three-bvh-csg, sowie eine Reihe von Unternehmen und Projekten, die es unterstützen, wie Threekit, Matterport, Flux und andere.
Konkrete Einsatzgrenze und Erstprüfung
Die Wahl zwischen prototypischen Erweiterungen und direkter MeshBVH-Abfrage hängt vom benötigten Kontrollgrad ab. Bei vielen Dreiecken hilft der Baum, unnötige Tests früh zu verwerfen; bei Änderungen an Vertex-Positionen muss refit eingeplant werden. Morph-Ziele und geskinnte Meshes sind laut README nicht für eine dynamische Hierarchie geeignet. Wer Geometrie mit vielen Gruppen oder großen Koordinaten verarbeitet, muss diese Datenform vor der Nutzung einordnen.
Was der konkrete Datenpfad offenlegt Für die Praxis sind auch die Nebenpfade relevant. MeshBVH kann serialisiert und später deserialisiert werden, während GenerateMeshBVHWorker den Aufbau großer Geometrien in einen Worker verlagert. ParallelMeshBVHWorker setzt SharedArrayBuffer voraus und fällt sonst auf einen einzelnen Worker zurück. Bei PointsBVH und den Linienvarianten nennt das README Einschränkungen bei Worker-Erzeugung und Serialisierung. Diese Unterschiede sprechen für eine Prüfung des konkreten Primitive-Typs, bevor eine gemeinsame Abstraktion gebaut wird. three-mesh-bvh ist damit eine Geometrie- und Abfragebibliothek für three.js, aber kein allgemeiner Ersatz für eine Szenenverwaltung oder eine dynamische Physiksimulation.
Redaktionelles Fazit
Die MIT-Lizenz erlaubt die Nutzung, Vervielfältigung, Änderung, Zusammenführung, Veröffentlichung, Verteilung, Unterlizenzierung und den Verkauf von Kopien, sofern der Urheberrechtshinweis enthalten ist. Der Lizenztext erwähnt keine Unterstützung, Garantie oder Wartungspflichten; die Software wird 'wie besehen' bereitgestellt.
Community-Notizen