Curl-Noise

A library that reproduces the mathematical structure and boundary constraints of Curl-Noise for Procedural Fluid Flow

Overview

curl-noise is an implementation for constructing divergence-free 2D / 3D velocity fields in TypeScript, based on the paper Curl-Noise for Procedural Fluid Flow.

Rather than designing the velocity directly, this library defines a potential field ψ and derives the velocity field from it: in 2D, v = (∂ψ/∂y, -∂ψ/∂x), and in 3D, v = ∇ × ψ.

The repository includes the following:

• 3D / 4D Perlin noise implementations
• Centered-difference curl evaluation for 2D / 3D
• Boundary constraints based on signed distance fields
• Rigid motion, vortex particle, and vortex curve primitives
• Assemblers for fields corresponding to figure1 / figure2
• Particle advection, divergence diagnostics, and boundary-normal diagnostics
• SVG / OBJ / JSON string renderers

Quick start

Prerequisites

• Node.js >= 24
• pnpm 10.30.0 or later

Setup

nvm use
corepack enable
pnpm install

Test and build

pnpm test
pnpm build

Minimal example

The following is a minimal example that builds a 2D potential and evaluates the velocity at a single point.

import { figure1Potential2 } from "./src/assemble/figure1-2d";
import { curl2 } from "./src/field/curl2";
import { sdf2 } from "./src/geometry/sdf2";
import { Perlin3 } from "./src/noise/perlin3";

const noise = new Perlin3(1234);
const sdf = sdf2(() => 1);

const psi = figure1Potential2({
  sdf,
  noise,
  d0: 0.5,
  controlCenter: { x: 0, y: 0 },
  controlRadius: 2,
});

const velocity = curl2(psi, { x: 0.25, y: 0.5 }, 0, 1e-4);
console.log(velocity);

If you use tsx, you can save it as examples/minimal.ts and run it like this:

pnpm exec tsx examples/minimal.ts

Architecture

.
├─ docs/           # Normative specs, plans, and README spec
├─ src/
│  ├─ advection/   # RK2/RK4 and particle advection
│  ├─ assemble/    # Field assembly for figure1 / figure2 / moving rigid
│  ├─ boundary/    # Ramp and 2D/3D boundary constraints
│  ├─ core/        # Core types and spec constants
│  ├─ diagnostics/ # Divergence, boundary-normal, and determinism checks
│  ├─ field/       # Finite differences and curl evaluation
│  ├─ geometry/    # SDF, closest-point, and sharp-feature helpers
│  ├─ math/        # Vector and numeric utilities
│  ├─ noise/       # RNG, permutation tables, and Perlin noise
│  ├─ primitives/  # Uniform flow, rigid, and vortex primitives
│  └─ render/      # SVG / OBJ / JSON string rendering
├─ test/           # Tests corresponding to each `src/` module
├─ dist/           # Build outputs
└─ .github/        # CI configuration

License

MIT - see LICENSE.