{"id":13534451,"url":"https://github.com/gkjohnson/three-bvh-csg","last_synced_at":"2025-11-13T22:53:04.218Z","repository":{"id":36970142,"uuid":"493750303","full_name":"gkjohnson/three-bvh-csg","owner":"gkjohnson","description":"A flexible, memory compact, fast and dynamic CSG implementation on top of three-mesh-bvh","archived":false,"fork":false,"pushed_at":"2025-09-05T15:55:32.000Z","size":1277,"stargazers_count":776,"open_issues_count":47,"forks_count":61,"subscribers_count":31,"default_branch":"main","last_synced_at":"2025-09-05T17:42:33.374Z","etag":null,"topics":["3d-printing","computational-solid-geometry","construction","constructive-solid-geometry","csg","game-development","geometry","graphics","three","three-mesh-bvh","threejs","webgl"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/gkjohnson.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":"gkjohnson","patreon":null,"open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"otechie":null,"custom":null}},"created_at":"2022-05-18T16:54:25.000Z","updated_at":"2025-09-05T15:55:15.000Z","dependencies_parsed_at":"2023-10-14T23:55:03.229Z","dependency_job_id":"25317f9a-5293-48ef-917e-a68b1344fff1","html_url":"https://github.com/gkjohnson/three-bvh-csg","commit_stats":{"total_commits":326,"total_committers":4,"mean_commits":81.5,"dds":"0.036809815950920255","last_synced_commit":"f3e742c264f879b3a9e620ce2750927095683f2a"},"previous_names":[],"tags_count":16,"template":false,"template_full_name":null,"purl":"pkg:github/gkjohnson/three-bvh-csg","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gkjohnson%2Fthree-bvh-csg","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gkjohnson%2Fthree-bvh-csg/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gkjohnson%2Fthree-bvh-csg/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gkjohnson%2Fthree-bvh-csg/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gkjohnson","download_url":"https://codeload.github.com/gkjohnson/three-bvh-csg/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gkjohnson%2Fthree-bvh-csg/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":284304462,"owners_count":26982161,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-11-13T02:00:06.582Z","response_time":61,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["3d-printing","computational-solid-geometry","construction","constructive-solid-geometry","csg","game-development","geometry","graphics","three","three-mesh-bvh","threejs","webgl"],"created_at":"2024-08-01T07:01:33.342Z","updated_at":"2025-11-13T22:53:04.208Z","avatar_url":"https://github.com/gkjohnson.png","language":"JavaScript","funding_links":["https://github.com/sponsors/gkjohnson","https://github.com/sponsors/gkjohnson/"],"categories":["4. 高级功能插件","Graphics","Constructive Solid Geometry","JavaScript","Specialty Topics"],"sub_categories":["Svelte","Visual Animation Editor","Geometry"],"readme":"# three-bvh-csg\n\n[![npm version](https://img.shields.io/npm/v/three-bvh-csg.svg?style=flat-square)](https://www.npmjs.com/package/three-bvh-csg)\n[![build](https://img.shields.io/github/actions/workflow/status/gkjohnson/three-bvh-csg/node.js.yml?style=flat-square\u0026label=build\u0026branch=main)](https://github.com/gkjohnson/three-bvh-csg/actions)\n[![github](https://flat.badgen.net/badge/icon/github?icon=github\u0026label)](https://github.com/gkjohnson/three-bvh-csg/)\n[![twitter](https://flat.badgen.net/badge/twitter/@garrettkjohnson/?icon\u0026label)](https://twitter.com/garrettkjohnson)\n[![sponsors](https://img.shields.io/github/sponsors/gkjohnson?style=flat-square\u0026color=1da1f2)](https://github.com/sponsors/gkjohnson/)\n\n![](./docs/csg-banner.png)\n\nAn _experimental, in progress_, flexible, memory compact, fast and dynamic [Constructive Solid Geometry](https://en.wikipedia.org/wiki/Constructive_solid_geometry) implementation on top of [three-mesh-bvh](https://github.com/gkjohnson/three-mesh-bvh). More than 100 times faster than other BSP-based three.js CSG libraries in complex cases. Contributions welcome!\n\n\u003e **Note**\n\u003e All brush geometry must be [two-manifold](https://help.autodesk.com/view/MAYAUL/2026/ENU/?guid=GUID-8E97CEF7-1CFE-4838-B4B7-59F526E21AB2) - or water tight with no triangle interpenetration.\n\n\u003e **Warning**\n\u003e Due to numerical precision and corner cases resulting geometry may not be correctly completely two-manifold.\n\nSee projects like [Manifold CAD](https://github.com/elalish/manifold) for CAD operations with more robust numercial solutions.\n\n# Roadmap / Help Wanted\n\n- Fix triangle splitting / missing triangle issues [#73](https://github.com/gkjohnson/three-bvh-csg/issues/73) [#68](https://github.com/gkjohnson/three-bvh-csg/issues/68)\n- Polygon splitting \u0026 triangulation [#51](https://github.com/gkjohnson/three-bvh-csg/issues/51)\n- Worker Support [#14](https://github.com/gkjohnson/three-bvh-csg/issues/14)\n\n[And more!](https://github.com/gkjohnson/three-bvh-csg/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22)\n\n# Examples\n\n[Simple CSG](https://gkjohnson.github.io/three-bvh-csg/examples/bundle/simple.html)\n\n[Complex Model CSG](https://gkjohnson.github.io/three-bvh-csg/examples/bundle/geometry.html)\n\n[Hollow Operations](https://gkjohnson.github.io/three-bvh-csg/examples/bundle/hollow.html)\n\n[Multi Material CSG](https://gkjohnson.github.io/three-bvh-csg/examples/bundle/multimaterial.html)\n\n[Multi Operation CSG](https://gkjohnson.github.io/three-bvh-csg/examples/bundle/multiop.html)\n\n[Hierarchical Operations](https://gkjohnson.github.io/three-bvh-csg/examples/bundle/hierarchy.html)\n\n# Use\n\n```js\nimport { SUBTRACTION, Brush, Evaluator } from 'three-bvh-csg';\nimport { MeshStandardMaterial, Mesh, SphereGeometry, BoxGeometry } from 'three';\n\nconst brush1 = new Brush( new SphereGeometry() );\nbrush1.updateMatrixWorld();\n\nconst brush2 = new Brush( new BoxGeometry() );\nbrush2.position.y = 0.5;\nbrush2.updateMatrixWorld();\n\nconst evaluator = new Evaluator();\nconst result = evaluator.evaluate( brush1, brush2, SUBTRACTION );\n\n// render the result!\n```\n\n# API\n\n## Constants\n\n### CSGOperations\n\nCSG operations enums for use with `Evaluator`.\n\n```js\nADDITION              // A ∪ B\nSUBTRACTION           // A - B\nREVERSE_SUBTRACTION   // B - A\nDIFFERENCE            // A ⊕ B\nINTERSECTION          // A ∩ B\n\n// \"Hollow\" operations are non-solid and result in simply removing the geometry\n// within Brush B from brush A. For these operations Brush A can be non-manifold\n// but it is still required that Brush B be a water-tight, two-manifold mesh.\nHOLLOW_SUBTRACTION    // A - B\nHOLLOW_INTERSECTION   // A ∩ B\n```\n\n## Brush\n\n_extends THREE.Mesh_\n\nAn object with the same interface as `THREE.Mesh` but used to evaluate CSG operations. Once a brush is created the geometry should not be modified.\n\n\u003e **Note**\n\u003e\n\u003e It is recommended to remove groups from a geometry before creating a brush if multi-material support is not required.\n\n## Operation\n\n_extends Brush_\n\nThis is an extension of the `Brush` class. With this class is possible to create a mesh and pass the CSG Operation constant to define which operation computes on the mesh. The result is a Mesh whose effect is defined from the operation selected. You can see how it works in the _hierarchy_ example.\n\n### .operation\n\n```js\noperation = ADDITION : CSGOperation\n```\n\nThe operation to perform on the next brush in processing chain when running `Evaluater.evaluateHierarchy`.\n\n### .insertBefore\n\n```js\ninsertBefore( brush : Brush )\n```\n\nInserts the brush before the operation element that calls the method, in the list of the children of the operation's parent.\n\n### .insertAfter\n\n```js\ninsertAfter( brush : Brush )\n```\n\nInserts the brush after the operation element that calls the method, in the list of the children of the operation's parent.\n\n## OperationGroup\n\n_extends THREE.Group_\n\nA class with the same interface as `THREE.Group` but used to group a list of Operation mesh through the `.add` method inherited from the THREE.Group class. You can create a group starting from single Operation meshes as in the _hierarchy_ example.\n\n## Evaluator\n\n### .useGroups\n\n```js\nuseGroups = true : Boolean\n```\n\nWhether to use geometry groups when processing the geometry. If geometry groups are used then a material array and groups will be assigned to the target `Brush` after processing. If groups are disabled then a single coherent piece of geometry with no groups will be produced.\n\n### .consolidateGroups\n\n```js\nconsolidateGroups = true : Boolean\n```\n\nIf true then any group in the final geometry that shares a common material with another group will be merged into one to reduce the number of draw calls required by the resulting mesh.\n\n### .evaluate\n\n```js\nevaluate(\n\tbrushA : Brush,\n\tbrushB : Brush,\n\toperation : CSGOperation,\n\ttarget = null : Brush | Mesh\n) : Brush | Mesh\n\n// or\n\nevaluate(\n\tbrushA : Brush,\n\tbrushB : Brush,\n\toperations : Array\u003cCSGOperation\u003e,\n\ttargets : Array\u003cBrush | Mesh\u003e\n) : Array\u003cBrush | Mesh\u003e\n```\n\nPerforms the given `operation` on `brushA` with `brushB`. If no target is provided then a new `Brush` will be created with the new geometry. Otherwise the provided Brush will be _modified in place_ and geometry disposed or marked for update as needed.\n\nIf arrays are provided for the \"targets\" and \"operations\" arguments then multiple results from different operations can be produced at once with minimal additional overhead.\n\n\n### .evaluateHierarchy\n\n```js\nevaluateHierarchy(\n  root: Operation,\n  target = null : Brush | Mesh\n) : Brush | Mesh\n```\n\nThe method gets as parameters a root, an Operation mesh and a target if it is provided, otherwise, a new `Brush` will be created.\nFirst sets the `updateMatrixWolrd` of the root to true then calls the traverse function with the root parameter to `evaluate` the mesh and its children.\n\n```js\nevaluate( brush, child, child.operation );\n```\n\nIn this case, the arguments passed to `evaluate` is the `root` as `brushA`, the child as `brushB` and the `child.operation` as the operation to apply to the mesh.\n\n## OperationDebugData\n\nThis class is used in the constructor of the Evaluator class. When the Evaluator is defined the constructor creates a debug property of type OperationDebugData and it is used to set the debug context, that is `addEdge` and `addIntersectionTriangles` to, for example, an EdgesHelper or a TriangleHelper.\n\n### .enabled\n\n```js\nenabled = false : Boolean\n```\n\nWhether to collect the debug data during CSG operations which has a performance a memory cost.\n\n### .intersectionEdges\n\n```js\nintersectionEdges = [] : Line3\n```\n\nA list of edges formed by intersecting triangles during the CSG process.\n\n\u003c!--\n## EvaluatorWorker\n\n_extends Evaluator_\n\n### .evaluate\n\nTODO\n\n### .evaluateHierarchy\n\nTODO\n--\u003e\n\n## GridMaterial\n\n_extends THREE.MeshPhongMaterial_\n\nA material with the same interface as `THREE.MeshPhongMaterial`. It adds a stylized grid on the mesh for more easily visualizing mesh topology and measurements.\n\n### .enableGrid\n\n```js\nenableGrid = true : Boolean\n```\n\nSets the visibility of the grid on the mesh.\n\n\n## HalfEdgeMap\n\nTODO\n\n### constructor\n\n```js\nconstructor( geometry : BufferGeometry = null )\n```\n\n### .getSiblingTriangleIndex\n\n```js\ngetSiblingTriangleIndex( triIndex : Number, edgeIndex : 0 | 1 | 2 ) : Number\n```\n\n### .getSiblingEdgeIndex\n\n```js\ngetSiblingEdgeIndex( triIndex : Number, edgeIndex : 0 | 1 | 2 ) : Number\n```\n\n### .updateFrom\n\n```js\nupdateFrom( geometry : BufferGeometry ) : void\n```\n\n## PointsHelper\n\n_extends THREE.InstancedMesh_\n\nHelper class for generating spheres to display.\n\n### .setPoints\n\n```js\nsetPoints( points : Vector3[] ) : void;\n```\n\nSets the points, passed as Vector3, and visualizes them as spheres.\n\n\n## EdgesHelper\n\n_extends THREE.LineSegments_\n\nHelper class for generating a line to display the provided edges.\n\n### .setEdges\n\n```js\nsetEdges( edges : Line3[] ) : void\n```\n\nSets the list of lines to be visualized.\n\n## HalfEdgeMapHelper\n\n_extends EdgesHelper_\n\nThis is a helper class that takes the `HalfEdgeMap` object and visualizes the connectivity between triangles.\n\n### .setHalfEdges\n\n```js\nsetHalfEdges( geometry : Geometry, halfEdges : HalfEdgeMap ) : void\n```\n\nSets the half edge map to visualize along with the associated geometry.\n\n## TriangleSetHelper\n\n_extends THREE.Group_\n\nHelper class for displaying a set of triangles. In the _Simple CSG_ example is possible to enable/disable the visibility of the triangles helper via `displayTriangleIntersections` checkbox.\n\nThe helper is composed of two meshes, one is a mesh with a MeshPhongMaterial and the other is a mesh with a LineBasicMaterial.\n\n### .setTriangles\n\n```js\nsetTriangles( triangles:  Triangle[] ) : void\n```\n\nSets the geometry of the mesh and the line with the position of the triangles passed as a parameter of the method.\n\n## Functions\n\n### computeMeshVolume\n\n```js\ncomputeMeshVolume( mesh : Mesh | BufferGeometry ) : Number\n```\n\nComputes the volume of the given mesh in world space. The world matrix is expected to be updated before calling this function.\n\n# Gotchas\n- All geometry are expected to have all attributes being used and of the same type.\n- Geometry on a Brush should be unique and not be modified after being set.\n- All geometry must be [two-manifold](https://knowledge.autodesk.com/support/maya-lt/learn-explore/caas/CloudHelp/cloudhelp/2015/ENU/MayaLT/files/Polygons-overview-Twomanifold-vs--nonmanifold-polygonal-geometry-htm.html) - or water tight with no triangle interpenetration.\n- CSG results use `Geometry.drawRange` to help maintain performance which can cause three.js exporters to fail to export the geometry correctly. It is necessary to convert the geometry to remove the use of draw range before exporting with three.js exporters.\n\n# References\n- [Godot CSG](https://github.com/godotengine/godot/blob/master/modules/csg/csg.cpp)\n- RealtimeCSG ([Overview](https://www.youtube.com/watch?v=uqaiUMuGlRc), [GDC Presentation](https://www.youtube.com/watch?v=Iqmg4gblreo))\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgkjohnson%2Fthree-bvh-csg","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgkjohnson%2Fthree-bvh-csg","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgkjohnson%2Fthree-bvh-csg/lists"}