threejs-geometry

$2a

Basic Shapes

// Box - width, height, depth, widthSegments, heightSegments, depthSegments

new THREE.BoxGeometry(1, 1, 1, 1, 1, 1);

// Sphere - radius, widthSegments, heightSegments, phiStart, phiLength, thetaStart, thetaLength

new THREE.SphereGeometry(1, 32, 32);

new THREE.SphereGeometry(1, 32, 32, 0, Math.PI * 2, 0, Math.PI); // Full sphere

new THREE.SphereGeometry(1, 32, 32, 0, Math.PI); // Hemisphere

// Plane - width, height, widthSegments, heightSegments

new THREE.PlaneGeometry(10, 10, 1, 1);

// Circle - radius, segments, thetaStart, thetaLength

new THREE.CircleGeometry(1, 32);

new THREE.CircleGeometry(1, 32, 0, Math.PI); // Semicircle

// Cylinder - radiusTop, radiusBottom, height, radialSegments, heightSegments, openEnded

new THREE.CylinderGeometry(1, 1, 2, 32, 1, false);

new THREE.CylinderGeometry(0, 1, 2, 32); // Cone

new THREE.CylinderGeometry(1, 1, 2, 6); // Hexagonal prism

// Cone - radius, height, radialSegments, heightSegments, openEnded

new THREE.ConeGeometry(1, 2, 32, 1, false);

// Torus - radius, tube, radialSegments, tubularSegments, arc

new THREE.TorusGeometry(1, 0.4, 16, 100);

// TorusKnot - radius, tube, tubularSegments, radialSegments, p, q

new THREE.TorusKnotGeometry(1, 0.4, 100, 16, 2, 3);

// Ring - innerRadius, outerRadius, thetaSegments, phiSegments

new THREE.RingGeometry(0.5, 1, 32, 1);

Advanced Shapes

// Capsule - radius, length, capSegments, radialSegments

new THREE.CapsuleGeometry(0.5, 1, 4, 8);

// Dodecahedron - radius, detail

new THREE.DodecahedronGeometry(1, 0);

// Icosahedron - radius, detail (0 = 20 faces, higher = smoother)

new THREE.IcosahedronGeometry(1, 0);

// Octahedron - radius, detail

new THREE.OctahedronGeometry(1, 0);

// Tetrahedron - radius, detail

new THREE.TetrahedronGeometry(1, 0);

// Polyhedron - vertices, indices, radius, detail

const vertices = [1, 1, 1, -1, -1, 1, -1, 1, -1, 1, -1, -1];

const indices = [2, 1, 0, 0, 3, 2, 1, 3, 0, 2, 3, 1];

new THREE.PolyhedronGeometry(vertices, indices, 1, 0);

Path-Based Shapes

// Lathe - points[], segments, phiStart, phiLength

const points = [

  new THREE.Vector2(0, 0),

  new THREE.Vector2(0.5, 0),

  new THREE.Vector2(0.5, 1),

  new THREE.Vector2(0, 1),

];

new THREE.LatheGeometry(points, 32);

// Extrude - shape, options

const shape = new THREE.Shape();

shape.moveTo(0, 0);

shape.lineTo(1, 0);

shape.lineTo(1, 1);

shape.lineTo(0, 1);

shape.lineTo(0, 0);

const extrudeSettings = {

  steps: 2,

  depth: 1,

  bevelEnabled: true,

  bevelThickness: 0.1,

  bevelSize: 0.1,

  bevelSegments: 3,

};

new THREE.ExtrudeGeometry(shape, extrudeSettings);

// Tube - path, tubularSegments, radius, radialSegments, closed

const curve = new THREE.CatmullRomCurve3([

  new THREE.Vector3(-1, 0, 0),

  new THREE.Vector3(0, 1, 0),

  new THREE.Vector3(1, 0, 0),

]);

new THREE.TubeGeometry(curve, 64, 0.2, 8, false);

Text Geometry

import { FontLoader } from "three/examples/jsm/loaders/FontLoader.js";

import { TextGeometry } from "three/examples/jsm/geometries/TextGeometry.js";

const loader = new FontLoader();

loader.load("fonts/helvetiker_regular.typeface.json", (font) => {

  const geometry = new TextGeometry("Hello", {

    font: font,

    size: 1,

    depth: 0.2, // Was 'height' in older versions

    curveSegments: 12,

    bevelEnabled: true,

    bevelThickness: 0.03,

    bevelSize: 0.02,

    bevelSegments: 5,

  });

  // Center text

  geometry.computeBoundingBox();

  geometry.center();

  const mesh = new THREE.Mesh(geometry, material);

  scene.add(mesh);

});

BufferGeometry

The base class for all geometries. Stores data as typed arrays for GPU efficiency.

Custom BufferGeometry

const geometry = new THREE.BufferGeometry();

// Vertices (3 floats per vertex: x, y, z)

const vertices = new Float32Array([

  -1,

  -1,

  0, // vertex 0

  1,

  -1,

  0, // vertex 1

  1,

  1,

  0, // vertex 2

  -1,

  1,

  0, // vertex 3

]);

geometry.setAttribute("position", new THREE.BufferAttribute(vertices, 3));

// Indices (for indexed geometry - reuse vertices)

const indices = new Uint16Array([

  0,

  1,

  2, // triangle 1

  0,

  2,

  3, // triangle 2

]);

geometry.setIndex(new THREE.BufferAttribute(indices, 1));

// Normals (required for lighting)

const normals = new Float32Array([0, 0, 1, 0, 0, 1, 0, 0, 1, 0, 0, 1]);

geometry.setAttribute("normal", new THREE.BufferAttribute(normals, 3));

// UVs (for texturing)

const uvs = new Float32Array([0, 0, 1, 0, 1, 1, 0, 1]);

geometry.setAttribute("uv", new THREE.BufferAttribute(uvs, 2));

// Colors (per-vertex colors)

const colors = new Float32Array([

  1,

  0,

  0, // red

  0,

  1,

  0, // green

  0,

  0,

  1, // blue

  1,

  1,

  0, // yellow

]);

geometry.setAttribute("color", new THREE.BufferAttribute(colors, 3));

// Use with: material.vertexColors = true

BufferAttribute Types

// Common attribute types

new THREE.BufferAttribute(array, itemSize);

// Typed array options

new Float32Array(count * itemSize); // Positions, normals, UVs

new Uint16Array(count); // Indices (up to 65535 vertices)

new Uint32Array(count); // Indices (larger meshes)

new Uint8Array(count * itemSize); // Colors (0-255 range)

// Item sizes

// Position: 3 (x, y, z)

// Normal: 3 (x, y, z)

// UV: 2 (u, v)

// Color: 3 (r, g, b) or 4 (r, g, b, a)

// Index: 1

Modifying BufferGeometry

const positions = geometry.attributes.position;

// Modify vertex

positions.setXYZ(index, x, y, z);

// Access vertex

const x = positions.getX(index);

const y = positions.getY(index);

const z = positions.getZ(index);

// Flag for GPU update

positions.needsUpdate = true;

// Recompute normals after position changes

geometry.computeVertexNormals();

// Recompute bounding box/sphere after changes

geometry.computeBoundingBox();

geometry.computeBoundingSphere();

Interleaved Buffers (Advanced)

// More efficient memory layout for large meshes

const interleavedBuffer = new THREE.InterleavedBuffer(

  new Float32Array([

    // pos.x, pos.y, pos.z, uv.u, uv.v (repeated per vertex)

    -1, -1, 0, 0, 0, 1, -1, 0, 1, 0, 1, 1, 0, 1, 1, -1, 1, 0, 0, 1,

  ]),

  5, // stride (floats per vertex)

);

geometry.setAttribute(

  "position",

  new THREE.InterleavedBufferAttribute(interleavedBuffer, 3, 0),

); // size 3, offset 0

geometry.setAttribute(

  "uv",

  new THREE.InterleavedBufferAttribute(interleavedBuffer, 2, 3),

); // size 2, offset 3

EdgesGeometry & WireframeGeometry

// Edge lines (only hard edges)

const edges = new THREE.EdgesGeometry(boxGeometry, 15); // 15 = threshold angle

const edgeMesh = new THREE.LineSegments(

  edges,

  new THREE.LineBasicMaterial({ color: 0xffffff }),

);

// Wireframe (all triangles)

const wireframe = new THREE.WireframeGeometry(boxGeometry);

const wireMesh = new THREE.LineSegments(

  wireframe,

  new THREE.LineBasicMaterial({ color: 0xffffff }),

);

Points

// Create point cloud

const geometry = new THREE.BufferGeometry();

const positions = new Float32Array(1000 * 3);

for (let i = 0; i < 1000; i++) {

  positions[i * 3] = (Math.random() - 0.5) * 10;

  positions[i * 3 + 1] = (Math.random() - 0.5) * 10;

  positions[i * 3 + 2] = (Math.random() - 0.5) * 10;

}

geometry.setAttribute("position", new THREE.BufferAttribute(positions, 3));

const material = new THREE.PointsMaterial({

  size: 0.1,

  sizeAttenuation: true, // Size decreases with distance

  color: 0xffffff,

});

const points = new THREE.Points(geometry, material);

scene.add(points);

Lines

// Line (connected points)

const points = [

  new THREE.Vector3(-1, 0, 0),

  new THREE.Vector3(0, 1, 0),

  new THREE.Vector3(1, 0, 0),

];

const geometry = new THREE.BufferGeometry().setFromPoints(points);

const line = new THREE.Line(

  geometry,

  new THREE.LineBasicMaterial({ color: 0xff0000 }),

);

// LineLoop (closed loop)

const loop = new THREE.LineLoop(geometry, material);

// LineSegments (pairs of points)

const segmentsGeometry = new THREE.BufferGeometry();

segmentsGeometry.setAttribute(

  "position",

  new THREE.BufferAttribute(

    new Float32Array([

      -1,

      0,

      0,

      0,

      1,

      0, // segment 1

      0,

      1,

      0,

      1,

      0,

      0, // segment 2

    ]),

    3,

  ),

);

const segments = new THREE.LineSegments(segmentsGeometry, material);

InstancedMesh

Efficiently render many copies of the same geometry.

const geometry = new THREE.BoxGeometry(1, 1, 1);

const material = new THREE.MeshStandardMaterial({ color: 0x00ff00 });

const count = 1000;

const instancedMesh = new THREE.InstancedMesh(geometry, material, count);

// Set transforms for each instance

const dummy = new THREE.Object3D();

const matrix = new THREE.Matrix4();

for (let i = 0; i < count; i++) {

  dummy.position.set(

    (Math.random() - 0.5) * 20,

    (Math.random() - 0.5) * 20,

    (Math.random() - 0.5) * 20,

  );

  dummy.rotation.set(Math.random() * Math.PI, Math.random() * Math.PI, 0);

  dummy.scale.setScalar(0.5 + Math.random());

  dummy.updateMatrix();

  instancedMesh.setMatrixAt(i, dummy.matrix);

}

// Flag for GPU update

instancedMesh.instanceMatrix.needsUpdate = true;

// Optional: per-instance colors

instancedMesh.instanceColor = new THREE.InstancedBufferAttribute(

  new Float32Array(count * 3),

  3,

);

for (let i = 0; i < count; i++) {

  instancedMesh.setColorAt(

    i,

    new THREE.Color(Math.random(), Math.random(), Math.random()),

  );

}

instancedMesh.instanceColor.needsUpdate = true;

scene.add(instancedMesh);

Update Instance at Runtime

// Update single instance

const matrix = new THREE.Matrix4();

instancedMesh.getMatrixAt(index, matrix);

// Modify matrix...

instancedMesh.setMatrixAt(index, matrix);

instancedMesh.instanceMatrix.needsUpdate = true;

// Raycasting with instanced mesh

const intersects = raycaster.intersectObject(instancedMesh);

if (intersects.length > 0) {

  const instanceId = intersects[0].instanceId;

}

InstancedBufferGeometry (Advanced)

For custom per-instance attributes beyond transform/color.

const geometry = new THREE.InstancedBufferGeometry();

geometry.copy(new THREE.BoxGeometry(1, 1, 1));

// Add per-instance attribute

const offsets = new Float32Array(count * 3);

for (let i = 0; i < count; i++) {

  offsets[i * 3] = Math.random() * 10;

  offsets[i * 3 + 1] = Math.random() * 10;

  offsets[i * 3 + 2] = Math.random() * 10;

}

geometry.setAttribute("offset", new THREE.InstancedBufferAttribute(offsets, 3));

// Use in shader

// attribute vec3 offset;

// vec3 transformed = position + offset;

Geometry Utilities

import * as BufferGeometryUtils from "three/examples/jsm/utils/BufferGeometryUtils.js";

// Merge geometries (must have same attributes)

const merged = BufferGeometryUtils.mergeGeometries([geo1, geo2, geo3]);

// Merge with groups (for multi-material)

const merged = BufferGeometryUtils.mergeGeometries([geo1, geo2], true);

// Compute tangents (required for normal maps)

BufferGeometryUtils.computeTangents(geometry);

// Interleave attributes for better performance

const interleaved = BufferGeometryUtils.interleaveAttributes([

  geometry.attributes.position,

  geometry.attributes.normal,

  geometry.attributes.uv,

]);

Common Patterns

Center Geometry

geometry.computeBoundingBox();

geometry.center(); // Move vertices so center is at origin

Scale to Fit

geometry.computeBoundingBox();

const size = new THREE.Vector3();

geometry.boundingBox.getSize(size);

const maxDim = Math.max(size.x, size.y, size.z);

geometry.scale(1 / maxDim, 1 / maxDim, 1 / maxDim);

Clone and Transform

const clone = geometry.clone();

clone.rotateX(Math.PI / 2);

clone.translate(0, 1, 0);

clone.scale(2, 2, 2);

Morph Targets

// Base geometry

const geometry = new THREE.BoxGeometry(1, 1, 1, 4, 4, 4);

// Create morph target

const morphPositions = geometry.attributes.position.array.slice();

for (let i = 0; i < morphPositions.length; i += 3) {

  morphPositions[i] *= 2; // Scale X

  morphPositions[i + 1] *= 0.5; // Squash Y

}

geometry.morphAttributes.position = [

  new THREE.BufferAttribute(new Float32Array(morphPositions), 3),

];

const mesh = new THREE.Mesh(geometry, material);

mesh.morphTargetInfluences[0] = 0.5; // 50% blend

Performance Tips

• Use indexed geometry: Reuse vertices with indices

• Merge static meshes: Reduce draw calls with mergeGeometries

• Use InstancedMesh: For many identical objects

• Choose appropriate segment counts: More segments = smoother but slower

• Dispose unused geometry: geometry.dispose()

// Good segment counts for common uses

new THREE.SphereGeometry(1, 32, 32); // Good quality

new THREE.SphereGeometry(1, 64, 64); // High quality

new THREE.SphereGeometry(1, 16, 16); // Performance mode

// Dispose when done

geometry.dispose();

See Also

• threejs-fundamentals - Scene setup and Object3D

• threejs-materials - Material types for meshes

• threejs-shaders - Custom vertex manipulation