THREE-CSGMesh

Project Introduction: THREE-CSGMesh

THREE-CSGMesh is a project characterized by the conversion of Constructive Solid Geometry (CSG) into a usable format for modern THREE.js applications. Originally developed by Evan Wallace, this project has been reworked for THREE.js by a developer known as "thrax." Both versions are distributed under the MIT license, which ensures that users can freely use and modify the software.

What is CSG?

Constructive Solid Geometry, or CSG, is a modeling technique used primarily in 3D computer graphics. It allows users to create complex surfaces or objects by using simpler objects and combining them using Boolean operations. These operations include:

• Union: Combines two shapes into one.
• Intersection: Creates a new shape from overlapping parts of two shapes.
• Subtraction: Removes the shape of one object from another.

These operations are implemented using a data structure called a BSP (Binary Space Partitioning) tree, which organizes 3D objects in a way that makes these calculations efficient.

How Does THREE-CSGMesh Work?

THREE-CSGMesh makes use of CSG techniques to perform operations on 3D geometries. This allows developers to create complex models in a programmatic way. By changing the order and type of these operations, users can achieve a wide range of effects. For instance, you might start with a cube and a sphere and use these operations to create a new, complex shape.

Running Demos

Several demos are available to showcase the capabilities of THREE-CSGMesh:

1. Basic Demo: Provides a simple example of the union, intersection, and subtraction operations. Demo Link

2. Shiny Demo: Aesthetic improvements and slightly more complex geometries are demonstrated. Demo Link

3. Complex Demo: This demo illustrates a text mesh cut into a complex mesh with an intermediate object. Demo Link

4. Material and Vertex Color Demo: Demonstrates the use of multiple material groups and color channels. Demo Link

Example Usage

Minimal Example:

Here is a simple way to subtract one mesh from another:

import {CSG} from "three-csg.js"
scene.add(CSG.toMesh(CSG.subtract(CSG.fromMesh(a), CSG.fromMesh(b)), a.material))

Detailed Example:

This is a step-by-step guide to using the library:

1. Create Two Box Meshes:

   let meshA = new THREE.Mesh(new THREE.BoxGeometry(1, 1, 1));
   let meshB = new THREE.Mesh(new THREE.BoxGeometry(1, 1, 1));
   meshB.position.add(new THREE.Vector3(0.5, 0.5, 0.5));
   meshA.updateMatrix();
   meshB.updateMatrix();
   

2. Create BSP Trees:

   let bspA = CSG.fromMesh(meshA);
   let bspB = CSG.fromMesh(meshB);
   

3. Perform Subtraction:

   let bspResult = bspA.subtract(bspB);
   

4. Get the Resulting Mesh:

   let meshResult = CSG.toMesh(bspResult, meshA.matrix, meshA.material);
   

This example outlines how to use THREE-CSGMesh to perform a subtraction operation, showcasing the practical use of CSG in THREE.js. By following these steps, developers can manipulate 3D geometries with precision, making THREE-CSGMesh a valuable tool for anyone working within the realm of 3D modeling and graphics.