Unlock custom brushes, natural fill effects and intuitive hatching in p5.js
# p5.brush
p5.brush is a natural drawing library — pencils, charcoal, markers, watercolor fills, hatch patterns, and vector fields.
---
## ⚠️ TWO BUILDS — READ THIS FIRST
p5.brush ships in **two completely different builds**. Before generating any code, identify which build the user is using. Getting this wrong produces broken code.
| | **p5 build** | **Standalone build** |
|---|---|---|
| File | `dist/p5.brush.js` | `dist/brush.js` / `dist/brush.esm.js` |
| Requires | p5.js 2.x | Nothing — browser WebGL2 only |
| Canvas | `createCanvas(w, h, WEBGL)` — p5 creates it | `brush.createCanvas(w, h)` — brush creates it |
| Transforms | p5's `push()`, `pop()`, `translate()`, `rotate()`, `scale()` | `brush.push()`, `brush.pop()`, `brush.translate()`, `brush.rotate()`, `brush.scale()` |
| Angle mode | p5's `angleMode(DEGREES / RADIANS)` | `brush.angleMode(brush.DEGREES / brush.RADIANS)` |
| Seeding | `randomSeed(n)` / `noiseSeed(n)` | `brush.seed(n)` / `brush.noiseSeed(n)` |
| Frame flush | Automatic — p5 handles it | **Must call `brush.render()`** at end of each frame |
| Clear canvas | p5's `background()` | `brush.clear(color?)` |
| Offscreen targets | `brush.load(p5Graphics \| framebuffer)` | `brush.load(htmlCanvas \| offscreenCanvas)` |
**Do not mix these up.** Using p5 functions (`push`, `background`, `randomSeed`, etc.) in a standalone sketch will break silently or throw errors. Using `brush.render()` or `brush.clear()` in a p5 sketch is unnecessary and wrong.
---
## p5 build
### Installation
```html
<script src="https://cdn.jsdelivr.net/npm/[email protected]/lib/p5.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/p5.brush@latest"></script>
```
```js
// ESM — p5 build (default)
import * as brush from 'p5.brush'
// ESM — standalone build (no p5.js required)
import * as brush from 'p5.brush/standalone'
```
### Setup
The brush canvas **must use WEBGL mode**. Drawing resources initialize only when brush needs them after `createCanvas(..., WEBGL)` — **no `brush.load()` needed for the main canvas**. Other sketches on the page can use ordinary 2D canvases without calling any brush APIs.
```js
function setup() {
createCanvas(600, 600, WEBGL)
angleMode(DEGREES) // brush angle APIs follow p5's angleMode
brush.scaleBrushes(3) // scale brushes to canvas size; 3 is a good start for 600×600
}
function draw() {
background("#fffceb")
translate(-width/2, -height/2) // WEBGL origin is center — shift to top-left
brush.set("HB", "#222", 1)
brush.line(50, 50, 550, 550)
}
```
### p5 integration — what hooks automatically
- `push()` / `pop()` — saves and restores brush stroke, fill, and hatch state
- `translate()`, `rotate()`, `scale()` — all p5 transforms apply to brush strokes
- `randomSeed(n)` — seeds both p5 and the brush library
- `noiseSeed(n)` — seeds both p5 noise and the brush library
- `angleMode(mode)` — all brush angle APIs follow p5's current angle mode
**No separate `brush.push()`, `brush.translate()`, or `brush.seed()` calls are needed or exist in this build.**
### Instance mode
```js
const sketch = (p) => {
brush.instance(p) // must be called before setup/draw
p.setup = () => { p.createCanvas(600, 600, p.WEBGL) }
p.draw = () => { ... }
}
new p5(sketch)
```
### Offscreen targets (p5 build)
`brush.load()` is only for redirecting drawing to a secondary surface:
```js
// p5.Graphics
const pg = createGraphics(300, 200, WEBGL)
brush.load(pg)
brush.set("HB", "black", 1)
brush.circle(150, 100, 70)
brush.load() // restore main canvas
image(pg, 20, 20)
// p5.Framebuffer
const fb = createFramebuffer({ width: 300, height: 200 })
fb.draw(() => {
brush.load(fb)
brush.circle(150, 100, 70)
})
brush.load()
image(fb, 20, 240)
```
---
## Standalone build
### Installation
```html
<!-- UMD — exposes global `brush` -->
<script src="path_to/brush.js"></script>
```
```js
// ESM — via npm
import * as brush from 'p5.brush/standalone'
// ESM — local file
import * as brush from './dist/brush.esm.js'
```
### Setup
Use `brush.createCanvas()` — it creates the canvas **and** loads it as the draw target automatically. No separate `brush.load()` needed.
```js
import * as brush from './dist/brush.esm.js'
brush.createCanvas(600, 600, {
parent: document.body,
pixelDensity: window.devicePixelRatio,
})
brush.scaleBrushes(3)
brush.angleMode(brush.DEGREES)
brush.seed(42)
```
`brush.load(canvas)` is only needed if you create the canvas yourself:
```js
const canvas = document.createElement('canvas')
canvas.width = 600; canvas.height = 600
document.body.appendChild(canvas)
brush.load(canvas) // register external canvas as draw target
```
### Frame lifecycle — mandatory
The standalone build does **not** flush or clear automatically. You must do both yourself every frame.
```js
brush.clear('#f5f0e0') // clear to background color
brush.push()
brush.translate(-W/2, -H/2) // WEBGL origin is center — shift to top-left
// ... all drawing calls here ...
brush.pop()
brush.render() // ← REQUIRED: flush compositing to canvas
```
**Forgetting `brush.render()` means nothing appears on screen.**
### Transforms (standalone)
```js
brush.push() // saves transform + brush state
brush.pop() // restores
brush.translate(x, y)
brush.rotate(angle) // angle follows brush.angleMode()
brush.scale(x, y?) // omit y to scale uniformly
```
### Angle mode (standalone)
```js
brush.angleMode(brush.DEGREES) // all angle APIs use degrees
brush.angleMode(brush.RADIANS) // default
```
### Seeding (standalone)
```js
brush.seed(42)
brush.noiseSeed(42)
```
### Standalone example
```js
import * as brush from './dist/brush.esm.js'
const W = 600, H = 600
brush.createCanvas(W, H, { parent: document.body })
brush.scaleBrushes(3)
brush.angleMode(brush.DEGREES)
brush.seed(42)
brush.clear('#f5f0e0')
brush.push()
brush.translate(-W/2, -H/2)
brush.set('HB', '#222', 1)
brush.line(50, 50, 550, 550)
brush.fill('#003c32', 120)
brush.fillBleed(0.15)
brush.noStroke()
brush.circle(300, 300, 120)
brush.pop()
brush.render() // required
```
---
## Shared API (both builds)
Everything below works identically in both builds. The only differences are setup, transforms, angle mode, seeding, frame flush, and clear — all covered above.
### Configuration
- `brush.scaleBrushes(scale)` — Scale all currently registered brushes. Usually necessary to match canvas size. `3` is a good starting point for a 600×600 canvas; confirm visually. Call before adding custom brushes if you only want built-ins scaled.
- `brush.load(target)` — Redirect drawing to a secondary target. In the **p5 build**: pass a `p5.Graphics` (WEBGL) or active `p5.Framebuffer`; call with no args to restore the main canvas. In the **standalone build**: pass an `HTMLCanvasElement` or `OffscreenCanvas`; call again to switch targets.
---
### Stroke Operations
- `brush.set(name, color, weight)` — Set brush name, color (hex string or p5.Color in p5 build; hex/CSS string in standalone), and weight multiplier. Enables stroke.
- `brush.pick(name)` — Change brush type only, keeping current color and weight.
- `brush.stroke(r, g, b)` or `brush.stroke(color)` — Set stroke color. Enables stroke.
- `brush.strokeWeight(weight)` — Set weight multiplier only.
- `brush.noStroke()` — Disable stroke for subsequent shapes.
---
### Fill Operations
Fill simulates watercolor — soft edges, bleed, texture layering.
- `brush.fill(color, opacity)` or `brush.fill(r, g, b, opacity)` — Set fill color. Opacity 0–255. Enables fill.
- `brush.noFill()` — Disable fill.
- `brush.wash(color, opacity)` — Fast solid fill, no watercolor simulation.
- `brush.noWash()` — Disable wash.
- `brush.fillBleed(strength, direction?)` — Edge bleed 0–1. Direction: `"out"` or `"in"`.
- `brush.fillTexture(textureStrength, borderIntensity, scatter?)` — Texture and border, both 0–1. `scatter` (default `true`) enables the sparse scattered polygon layers; set to `false` for a cleaner gradient trim without edge texture noise.
- For better fill performance, group shapes by fill color/opacity so the library can reuse its internal caching.
---
### Hatch Operations
- `brush.hatch(dist, angle, options?)` — Enable hatching. `dist` = spacing in canvas units. `angle` follows current `angleMode()`. Options: `{rand: 0–1, continuous: bool, gradient: 0–1}`.
- `brush.noHatch()` — Disable hatching.
- `brush.hatchStyle(name, color, weight)` — Set brush used for hatching.
- `brush.mass(brushName, color, options?)` — Dry-media, hand-filled hatched fill. Works best with crayon or pastel brushes. `brushName` is always required explicitly. Options: `precision` 0–1, `strength` 0–1, `gradient` 0–1, `outline` bool.
- `brush.noMass()` — Disable massing.
- `brush.hatchArray(polygons)` — Apply current hatch style directly to a `brush.Polygon` or array of polygons.
- `brush.massArray(polygons)` — Apply current mass style to a `brush.Polygon` or array of `brush.Polygon` objects as one combined gesture (array = outer shapes + holes via even-odd logic).
---
### Vector Fields
Built-in fields: `"hand"`, `"curved"`, `"zigzag"`, `"waves"`, `"seabed"`, `"spiral"`, `"columns"`.
- `brush.field(name)` — Activate a named field.
- `brush.noField()` — Deactivate.
- `brush.wiggle(intensity)` — Shorthand for `"hand"` field with given wobble strength.
- `brush.listFields()` — Returns array of all field names.
- `brush.refreshField(t)` — Update field with time value. Call in draw loop for animation.
- `brush.addField(name, fn, options?)` — Custom field. `fn(t, field)` fills a 2D angle grid (degrees by default) and returns it. Pass `{ angleMode: "radians" }` if your generator writes radians.
```js
brush.addField("diagonal", (t, field) => {
for (let col = 0; col < field.length; col++)
for (let row = 0; row < field[0].length; row++)
field[col][row] = 45 + t * 10
return field
})
brush.field("diagonal")
```
---
### Primitives
#### Lines (stroke only)
- `brush.line(x1, y1, x2, y2)`
- `brush.flowLine(x, y, length, dir)` — Follows active vector field. `dir` follows current `angleMode()`.
- `brush.spline(points, curvature?)` — Smooth curve through `[[x,y], [x,y,pressure], ...]`. Curvature 0–1. Returns `brush.Plot` for reuse.
#### Manual strokes (stroke only)
```js
brush.beginStroke("curve", x, y) // or "segments"
brush.move(angle, length, pressure)
brush.endStroke(angle, pressure)
```
#### Shapes (stroke + fill + hatch)
- `brush.rect(x, y, w, h, mode?)` — `mode`: `"corner"` (default) or `"center"`. Returns nothing.
- `brush.circle(x, y, radius, r?)` — `r` = hand-drawn irregularity 0–1. Returns `[plot, offsetX, offsetY]` for reuse.
- `brush.arc(x, y, radius, start, end)` — Stroke only. Angles follow current `angleMode()`. Returns `brush.Plot`, or `null` on zero sweep.
- `brush.polygon(pointsArray)` — Polygon from `[[x,y], ...]`. Not affected by vector fields. Returns `brush.Polygon` for reuse.
- `brush.beginShape(curvature?)` / `brush.vertex(x, y, pressure?)` / `brush.endShape(close?)` — `endShape()` returns `brush.Plot` for reuse.
---
### Primitive-first drawing
Prefer the main drawing primitives (`line`, `flowLine`, `spline`, `rect`, `circle`, `arc`, `polygon`, and `beginShape`/`vertex`/`endShape`) whenever rendering visible geometry. To redraw a shape with another style, call the same main primitive again with the new brush state; do not default to `Polygon.draw()` or `Plot.draw()` in examples. Use `brush.Polygon`/`brush.Plot` methods only when their stored geometry is specifically required, such as inputs to `hatchArray()`/`massArray()` or advanced geometry reuse.
Draw native p5 text and other overlays after all brush geometry for the frame so they remain visibly on top.
### Brush Management
- `brush.box()` — Returns array of all brush names.
- `brush.clip([x1, y1, x2, y2])` — Clip strokes to a rectangle. Transform is captured at call time.
- `brush.noClip()` — Remove clipping.
- `brush.add(name, params)` — Define a custom brush. Use the [Brush Maker](https://acamposuribe.github.io/p5.brush/tools/brush-maker.html) for interactive design.
**`brush.add()` params:**
| Property | Description |
|----------|-------------|
| `type` | `"default"`, `"spray"`, `"marker"`, `"custom"`, `"image"` |
| `weight` | Base thickness in canvas units |
| `scatter` | Sideways spread |
| `sharpness` | Edge softness 0–1 (`"default"` only) |
| `grain` | Texture density (`"default"` only) |
| `opacity` | Mark opacity 0–255 |
| `spacing` | Stamp gap along stroke (1 = no overlap) |
| `pressure` | `[start, end]` or `[start, mid, end]` or `(t) => value` |
| `tip` | `"custom"` type. **p5 build**: `(_m) => { ... }` where `_m` is a `p5.Graphics` — any p5 command works. **Standalone build**: `_m` is a minimal 2D-canvas wrapper — same method names but colors must be a grayscale number or CSS string (no `p5.Color`), and `rotate()` always takes radians. Draw in a 100×100 unit space, origin at centre. Dark = opaque, white = transparent. |
| `image` | `"image"` type: `{ src: "./tip.jpg" }` |
| `rotate` | `"none"`, `"natural"`, `"random"` |
| `markerTip` | `"marker"`, `"custom"`, `"image"` only. Boolean, default `true`. Set `false` to disable soft tip buildup at stroke ends. |
| `noise` | Per-stroke opacity variation. `0` = every stroke identical. `1` = maximum variation. Default `0.3`. |
- Image brushes return a Promise — use `await brush.add(...)` inside `async setup()`.
- Custom brushes do **not** need `await`.
```js
// Custom tip — works in both builds (uses radians, no p5.Color)
brush.add("diamond", {
type: "custom",
weight: 5, scatter: 0.08, opacity: 23, spacing: 0.6,
pressure: [0.5, 1.5, 0.5],
tip: (_m) => { _m.rotate(Math.PI / 4); _m.rect(-1.5, -1.5, 3, 3) },
rotate: "natural",
markerTip: false
})
// Image tip — must await, setup must be async
await brush.add("photo", {
type: "image",
weight: 10, scatter: 2, opacity: 30, spacing: 1.5,
pressure: [1, 0.5],
image: { src: "./tip.jpg" },
rotate: "random",
markerTip: false
})
```
---
### Composing Shapes
Primitives return their geometry — store the return value to apply effects later or reuse the shape:
```js
const frame = brush.polygon([[50,50],[350,50],[350,350],[50,350]]) // returns Polygon
brush.hatch(8, Math.PI / 4)
frame.hatch() // hatch the stored polygon
brush.mass("pastel", "#4b6cb7", { strength: 0.8 })
frame.mass() // mass the same geometry
```
For multiple polygons as one gesture (even-odd hole logic), use `brush.hatchArray(polygons)` or `brush.massArray(polygons)`.
---
### Exposed Classes
#### `brush.Polygon(pointsArray)`
```js
let p = new brush.Polygon([[x1,y1],[x2,y2],[x3,y3]])
p.draw(brushName, color, weight)
p.fill(color, opacity, bleed, texture)
p.wash(color, opacity)
p.hatch(distance, angle, options)
p.mass()
p.intersect(line) // returns [{x,y}, ...]
// Attributes: p.vertices, p.sides
```
#### `brush.Plot(type)`
```js
let plot = new brush.Plot("curve")
plot.addSegment(angle, length, pressure)
plot.endPlot(angle, pressure)
plot.draw(x, y)
plot.fill(x, y)
plot.wash(x, y)
plot.hatch(x, y)
plot.mass(x, y)
plot.rotate(angle)
plot.genPol(x, y) // returns a Polygon
```
#### `brush.Position(x, y)`
```js
let pos = new brush.Position(x, y)
pos.moveTo(dir, length, stepLength) // dir follows current angleMode()
pos.plotTo(plot, length, stepLength, scale)
```
---
## Key Gotchas
### Both builds
- Prefer main drawing primitives for visible shapes; reserve direct `Polygon`/`Plot` methods for array APIs and advanced stored-geometry use.
- Draw text/overlays after brush geometry when they must remain on top.
- The WebGL canvas origin is at the **center**. Use `translate(-width/2, -height/2)` (p5) or `brush.translate(-W/2, -H/2)` (standalone) to work in top-left coordinates.
- `brush.arc()` is stroke-only. `brush.circle()` supports stroke, fill, and hatch.
- `brush.rect()` mode uses strings: `"corner"` or `"center"` — not p5 constants.
- Fill opacity is 0–255, not 0–100.
- `brush.flowLine()` and `brush.hatch()` angles follow the current `angleMode()`.
### p5 build only
- Canvas must be WEBGL: `createCanvas(w, h, WEBGL)`.
- `brush.load()` is not needed for the main canvas — only for `p5.Graphics` / `p5.Framebuffer` targets.
- `randomSeed()` and `noiseSeed()` seed the brush library automatically.
- For image brushes, `setup()` must be `async` and you must `await brush.add(...)`.
### Standalone build only
- **Always call `brush.render()` at the end of every drawing pass** — nothing appears otherwise.
- Use `brush.clear(color?)` to clear, not `background()`.
- Use `brush.push/pop/translate/rotate/scale`, not p5 equivalents.
- Use `brush.angleMode(brush.DEGREES)`, not `angleMode(DEGREES)`.
- Use `brush.seed(n)` and `brush.noiseSeed(n)`, not `randomSeed()`/`noiseSeed()`.
- In custom tip functions, `rotate()` always takes radians and colors must be numbers or CSS strings.