Three.js - Geometries

Three.js - Geometries

Geometries are the building blocks of any 3D object, defining its shape and structure through a collection of vertices, faces, and other data. Three.js provides a rich set of built-in geometries that make it easy to create common shapes, from simple planes to complex knots.

All standard geometries in Three.js are built upon the highly optimized BufferGeometry class, which stores data like vertex positions, face indices, normals, and UVs in efficient data buffers.

Common Built-in Geometries

Geometry	Description
BoxGeometry	Creates a rectangular prism (a box). Parameters define its width, height, and depth, as well as optional segments for each axis.
SphereGeometry	Creates a sphere. Parameters define its radius, and the number of horizontal (widthSegments) and vertical (heightSegments) segments, which control its smoothness.
PlaneGeometry	Creates a simple 2D flat plane. Useful for floors, walls, or as a base for textures.
CylinderGeometry	Creates a cylinder. You can specify different top and bottom radii (radiusTop, radiusBottom) to create cone shapes as well.
TorusGeometry	Creates a torus (a donut shape). Defined by the radius of the torus and the tube radius.
TorusKnotGeometry	Creates a more complex, knotted torus shape. Great for creating interesting abstract forms.
CircleGeometry	Creates a simple, flat, 2D circle. Useful for UI elements or simple shapes.
TextGeometry	[Advanced] Creates 3D text from a font file. Requires loading a special JSON font file and is part of the Three.js addons.

Code Example: Creating a Scene with Multiple Geometries

import * as THREE from 'three';

// Scene setup (camera, renderer, etc.) is assumed
const scene = new THREE.Scene();

// Create a material to share among the meshes
const material = new THREE.MeshStandardMaterial({
    color: 0x00ff00,
    roughness: 0.5
});

// 1. Box Geometry
const boxGeometry = new THREE.BoxGeometry(1, 1, 1);
const cube = new THREE.Mesh(boxGeometry, material);
cube.position.x = -2;
scene.add(cube);

// 2. Sphere Geometry (with more segments for smoothness)
const sphereGeometry = new THREE.SphereGeometry(0.7, 32, 32);
const sphere = new THREE.Mesh(sphereGeometry, material);
sphere.position.x = 0;
scene.add(sphere);

// 3. Torus Geometry
const torusGeometry = new THREE.TorusGeometry(0.5, 0.2, 16, 100);
const torus = new THREE.Mesh(torusGeometry, material);
torus.position.x = 2;
scene.add(torus);

Performance and Best Practices

• Segments Matter: The number of segments in a geometry (e.g., widthSegments in SphereGeometry) directly impacts performance. A high-poly model looks smooth but is computationally expensive. Use lower segment counts for objects that are far away or less important.
• Instancing: If you need to render many identical objects (e.g., a forest of trees), use InstancedMesh instead of creating thousands of individual Mesh objects. This dramatically improves performance by reducing draw calls.
• BufferGeometry: For maximum performance or custom shapes, you can work directly with BufferGeometry to define your own vertices and attributes. This is an advanced topic but is the key to creating highly optimized and unique 3D models programmatically.
• Cleanup: When you are finished with a geometry and it is no longer in the scene, call geometry.dispose() to free up its memory from the GPU.

To explore all available geometries and their parameters, check out the official Three.js documentation.