threejs-geometry

# Three.js Geometry ## When to Use - You need to create or optimize geometry in Three.js. - The task involves built-in shapes, custom `BufferGeometry`, vertices, or instanced rendering. - You are working on mesh structure rather than scene setup or materials alone. ## Quick Start ```javascript import * as THREE from "three"; // Built-in geometry const box = new THREE.BoxGeometry(1, 1, 1); const sphere = new THREE.SphereGeometry(0.5, 32, 32); const plane = new THREE.PlaneGeometry(10, 10); // Create mesh const material = new THREE.MeshStandardMaterial({ color: 0x00ff00 }); const mesh = new THREE.Mesh(box, material); scene.add(mesh); ``` ## Built-in Geometries ### Basic Shapes ```javascript // 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 ```javascript // 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 ```javascript // 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 ```javascript 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 ```javascript 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 ```javascript // 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 ```javascript 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) ```javascript // 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 ```javascript // 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 ```javascript // 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 ```javascript // 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. ```javascript 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 ```javascript // Update single instance const matrix = new THREE.Matrix4(); instancedMesh.getMatrixAt(index, matrix); // Modify matrix... instancedMesh.setMatrixAt(index, matrix);