flexy-bend

A Three.js library that bends BufferGeometry along Bezier curves.

Demo

Try the interactive demo →

Install

npm install flexy-bend

Usage

import * as flexy from 'flexy-bend';
import * as THREE from 'three';

const R = 3;
const curve = new THREE.CubicBezierCurve3(
    new THREE.Vector3(R, 0, 0),
    new THREE.Vector3(R, R * 0.55, 0),
    new THREE.Vector3(R * 0.45, R, 0),
    new THREE.Vector3(0, R, 0)
);

// A vector perpendicular to the plane the curve lies on.
// For a curve in the XY plane, this is the Z axis.
const orientation = new THREE.Vector3(0, 0, 1);

flexy.bend({
    THREE,
    curve,
    orientation,
    bufferGeometry: mesh.geometry,
    axis: 'x', // the axis the geometry is elongated along
});

API

bend(options)

Bends a BufferGeometry along a CubicBezierCurve3.

| Option | Type | Required | Description | |---|---|---|---| | THREE | Library | ✓ | Your THREE.js instance | | curve | CubicBezierCurve3 | ✓ | The curve to bend along | | bufferGeometry | BufferGeometry | ✓ | The geometry to deform | | axis | 'x' \| 'y' \| 'z' | ✓ | The axis the geometry is elongated along | | orientation | Vector3 | | A vector perpendicular to the curve's plane | | quaternion | Quaternion | | Alternative to orientation | | mode | 'fit' \| 'preserve' \| 'tile' | | Controls how geometry length relates to curve length. Defaults to 'fit'. See below. | | orbit | number | | Fractional shift along the curve. In 'preserve': shifts from center (0.5 toward end, -0.5 toward start). In 'tile': shifts the tiling start position. No effect in 'fit'. Defaults to 0. |

mode values

| Value | Behaviour | |---|---| | 'fit' | The geometry is scaled (stretched or compressed) to exactly fill the full arc length of the curve. | | 'preserve' | The geometry keeps its world-space length. It is centered on the curve and shifted by orbit. t is clamped to [0, 1] — the geometry never bends past the curve endpoints. | | 'tile' | The geometry keeps its world-space length. When the geometry is longer than the curve, t wraps with modulo so the curve pattern repeats across the excess. orbit shifts the tiling start position. |

getPointToFaceNormalMap(options)

Raycasts a uniform grid from a rectangular region onto a mesh surface, returning a hashmap from grid points to { normal, point } pairs on the surface. Used as input for wrap().

wrap(options)

Conforms a geometry to a curved surface by looking up the face normal at each vertex's projected position and rotating the vertex to align with it.

shear(options)

Applies a Gaussian shear deformation centered at the midpoint of the geometry. Within each cross-section, vertices are displaced along shearAxis in proportion to their distance from the shear-axis center, with a bell-curve falloff from the geometry's center toward its ends.

| Option | Type | Required | Description | |---|---|---|---| | THREE | Library | ✓ | Your THREE.js instance | | bufferGeometry | BufferGeometry | ✓ | The geometry to deform | | amplitude | number | ✓ | Maximum displacement at the center cross-section | | axis | 'x' \| 'y' \| 'z' | | The elongation axis. Defaults to 'x' | | shearAxis | 'x' \| 'y' \| 'z' | | The displacement axis (must differ from axis). Defaults to 'z' | | sigma | number | | Gaussian spread in world units. Defaults to geometryLength / 4 |

wave(options)

Applies an arbitrary scalar displacement to a subset of vertices selected by a predicate. The displacement function receives the two coordinates in the plane perpendicular to the displacement axis.

| Option | Type | Required | Description | |---|---|---|---| | THREE | Library | ✓ | Your THREE.js instance | | bufferGeometry | BufferGeometry | ✓ | The geometry to deform | | predicate | (x, y, z) => boolean | ✓ | Selects which vertices to affect | | fn | (u, v) => number | ✓ | Returns the displacement amount. For axis='y': fn(x, z); axis='x': fn(y, z); axis='z': fn(x, y) | | axis | 'x' \| 'y' \| 'z' | | The displacement axis. Defaults to 'y' |

How it works

1. Start with a box geometry

2. Define a curve to bend along

3. Normalize each vertex along the bend axis

Each coordinate on the bend axis is mapped to a parameter t ∈ [0, 1] on the curve. The leftmost vertices map to t = 0, the rightmost to t = 1.

4. Sample tangent lines at each parameter

5. Compute orthogonal vectors

For each tangent, compute a perpendicular vector (shown in purple) using the cross product with the reference normal.

6. Rotate to match the original cross-section angle

The orthogonal is rotated around the tangent axis by the angle atan2(z, y) — the angle the original vertex makes in the cross-section plane.

The resulting rotated vectors:

7. Scale to the original cross-section distance

Each rotated vector is scaled to match the original vertex's distance from the bend axis.

8. Final result

The new vertex position is curvePoint(t) + scaledOrthogonal.

The relationship between the curve and the bent geometry:

Development

npm run dev      # start dev server at localhost:5151
npm run build    # build the library (dist/) and demo site (docs/)