Key takeaways
The
THREE.PlaneGeometryclass in Three.js is used to create flat rectangular surfaces essential for various 3D scenes, such as floors, walls, and backgrounds.The class constructor accepts parameters for width, height, widthSegments, and heightSegments, allowing developers to define the size and detail of the plane geometry.
THREE.PlaneGeometryhas properties liketype,parameters,vertices, and methods such ascomputeBoundingBox(),applyMatrix4(matrix), and rotation/translation methods, enabling manipulation and querying of the geometry.
In Three.js, we use the THREE.PlaneGeometry class to create flat rectangular plane geometries. Flat planes are essential surfaces often required in 3D scenes, such as floors, walls, ceilings, or backgrounds. With the PlaneGeometry class, developers can easily define the plane's dimensions (width and height) and options for subdividing the geometry into smaller segments. This flexibility allows for creating planes with different sizes and levels of detail. Three.js ensures consistency across projects, promoting code readability and maintainability. THREE.PlaneGeometry streamlines the process of generating flat surfaces in Three.js, facilitating the development of 3D scenes with planes of varying sizes and complexities.
The syntax for initializing a plane geometry in Three.js is given below:
const geometry = new THREE.PlaneGeometry( 1, 1 );const material = new THREE.MeshBasicMaterial({color: 0xffff00, side: THREE.DoubleSide});const plane = new THREE.Mesh(geometry, material);scene.add(plane);
The constructor for the THREE.PlaneGeometry takes the following parameters:
width: This defines the width of the plane. It is a numeric value that determines how wide the plane will be. The default value is 1.
height: This defines the height of the plane. It is a numeric value that determines how tall the plane will be. The default value is 1.
widthSegments: This parameter specifies how many segments the width of the plane will be divided into. More segments allow for more detailed geometry. The default value is 1.
heightSegments: This parameter specifies how many segments the height of the plane will be divided into. Like widthSegments, it controls the level of detail. The default value is 1.
After creating a THREE.PlaneGeometry object, it has several properties inherited from the THREE.Geometry class, including:
type: It is the type of geometry object. For PlaneGeometry, this will be "PlaneGeometry".
parameters: It is an object containing the parameters passed when constructing the PlaneGeometry instance, which includes width, height, widthSegments, and heightSegments.
vertices: It is an array containing the points of the geometry. These vertices define the shape of the plane.
faces: It is an array of face definitions that define how the vertices are connected to form triangles in the geometry.
boundingBox: It is an instance of THREE.Box3 representing an axis-aligned bounding box of the geometry, automatically calculated if requested.
boundingSphere: It is an instance of THREE.Sphere representing a bounding sphere that encloses the geometry.
THREE.PlaneGeometry also inherits methods from THREE.Geometry, allowing you to manipulate or query the geometry:
computeBoundingBox(): This calculates and sets the boundingBox property of the geometry, which represents an axis-aligned bounding box.
computeBoundingSphere(): This calculates and sets the boundingSphere property of the geometry, which is a sphere enclosing the geometry.
applyMatrix4(matrix): This applies a transformation matrix to the geometry, affecting the position of its vertices.
rotateX(angle), rotateY(angle), rotateZ(angle): These methods rotate the geometry around the respective axes.
translate(x, y, z): This translates the geometry by a specified amount along the x, y, and z axes.
scale(x, y, z): This scales the geometry by the specified factors along the x, y, and z axes.
Note: Read up on meshes and materials in Three.js.
In this example, we will create a simple Three.js scene with a plane geometry representing a flat surface. The scene will also feature camera controls using the OrbitControls module to enable user interaction to navigate the 3D environment. We will showcase how to dynamically adjust the properties of the plane geometry, such as its width, height, and segmentation, in real time using HTML input elements. We'll set up a control panel with sliders to manipulate these properties, allowing users to interactively modify the plane's appearance.
Note: Click on the "Run" button to get the code executed.
import * as THREE from 'three';
import { OrbitControls } from 'three/examples/jsm/controls/OrbitControls';
// Scene setup
const scene = new THREE.Scene();
const camera = new THREE.PerspectiveCamera(75, window.innerWidth / window.innerHeight, 0.1, 1000);
const renderer = new THREE.WebGLRenderer();
renderer.setSize(window.innerWidth, window.innerHeight);
document.body.appendChild(renderer.domElement);
// Camera controls
const controls = new OrbitControls(camera, renderer.domElement);
camera.position.z = 5;
// Create plane geometry
let geometry = new THREE.PlaneGeometry(2, 2, 10, 10);
const material = new THREE.MeshBasicMaterial({ color: 0x00ff00, wireframe: true });
const plane = new THREE.Mesh(geometry, material);
scene.add(plane);
// Control panel setup
const panel = document.createElement('div');
panel.style.position = 'absolute';
panel.style.top = '10px';
panel.style.left = '10px';
panel.style.padding = '10px';
panel.style.backgroundColor = 'rgba(255, 255, 255, 0.5)';
panel.style.borderRadius = '5px';
panel.innerHTML = `
<div>Width: <input type="range" min="0" max="10" step="0.1" value="2" id="width"></div>
<div>Height: <input type="range" min="0" max="10" step="0.1" value="2" id="height"></div>
<div>Width Segments: <input type="range" min="1" max="50" step="1" value="10" id="widthSegments"></div>
<div>Height Segments: <input type="range" min="1" max="50" step="1" value="10" id="heightSegments"></div>
`;
document.body.appendChild(panel);
// Function to update plane geometry
function updatePlaneGeometry() {
const width = parseFloat(document.getElementById('width').value);
const height = parseFloat(document.getElementById('height').value);
const widthSegments = parseInt(document.getElementById('widthSegments').value);
const heightSegments = parseInt(document.getElementById('heightSegments').value);
geometry.dispose();
geometry = new THREE.PlaneGeometry(width, height, widthSegments, heightSegments);
plane.geometry = geometry;
}
// Event listeners for input changes
document.getElementById('width').addEventListener('input', updatePlaneGeometry);
document.getElementById('height').addEventListener('input', updatePlaneGeometry);
document.getElementById('widthSegments').addEventListener('input', updatePlaneGeometry);
document.getElementById('heightSegments').addEventListener('input', updatePlaneGeometry);
// Render loop
function animate() {
requestAnimationFrame(animate);
controls.update();
renderer.render(scene, camera);
}
animate();
The above code is further divided into following chunks for better explanation:
Line 5: We initialize a new Three.js scene and store it in the variable scene. The scene serves as a container for all the 3D objects, lights, and other elements that will be rendered.
Line 6: We have created a camera using THREE.PerspectiveCamera to project 3D objects onto a 2D plane.
Line 7: A WebGLRenderer is initialized using THREE.WebGLRenderer. This renderer uses WebGL, a web standard for rendering 3D graphics, to display the scene.
Lines 8–9: The setSize() method sets the dimensions of the renderer to match the width and height of the browser window and the renderer's DOM element allows it to render the 3D scene in the browser.
Lines 12–13: We initialize the OrbitControls and bind them to the camera and renderer.
Lines 16–19: We create a plane geometry with specified dimensions and segments and define a basic material with a green wireframe color. We also create a mesh by combining the geometry and material and adding it to the scene.
Lines 22–35: We create a control panel as a <div> element and style it, add HTML input elements for range sliders to adjust the plane geometry's width, height, and segments and append the control panel to the document body.
Lines 38–47: We define a function updatePlaneGeometry() to update the plane geometry based on the input values from the control panel, parse the input values, and create a new plane geometry with the updated parameters. We dispose of the old geometry to free up memory and assign the new geometry to the plane mesh.
Lines 50–53: We add event listeners to the input elements in the control panel to call the updatePlaneGeometry() function whenever the input values change.
Lines 56–59: We define a render loop function animate() using requestAnimationFrame() to continuously update and render the scene. We update the camera controls and render the scene using the WebGLRenderer.
The THREE.PlaneGeometry class is a fundamental tool in Three.js for creating and manipulating flat surfaces in 3D scenes. Its flexible parameters and comprehensive set of properties and methods enable developers to create detailed and customizable plane geometries efficiently. The ability to dynamically update these geometries through user input enhances the interactivity and responsiveness of 3D applications, making it an invaluable component for web-based 3D visualization.
Free Resources