Draw perfect pressure-sensitive freehand lines.

🔗 Try out a demo.

💰 Using this library in a commercial product? Consider becoming a sponsor.

• Installation
• Usage
• Support
• Discussion
• Author

npm install perfect-freehand

or

yarn add perfect-freehand

This package exports a function named getStroke that:

• accepts an array of points and an (optional) options object
• returns a stroke outline as an array of points formatted as [x, y]

import { getStroke } from 'perfect-freehand'

You may format your input points as array or an object. In both cases, the value for pressure is optional (it will default to .5).

getStroke([
  [0, 0, 0],
  [10, 5, 0.5],
  [20, 8, 0.3],
])

getStroke([
  { x: 0, y: 0, pressure: 0 },
  { x: 10, y: 5, pressure: 0.5 },
  { x: 20, y: 8, pressure: 0.3 },
])

The options object is optional, as are each of its properties.

Note: When the last property is true, the line's end will be drawn at the last input point, rather than slightly behind it.

The start and end options accept an object:

Note: The cap property has no effect when taper is more than zero.

getStroke(myPoints, {
  size: 8,
  thinning: 0.5,
  smoothing: 0.5,
  streamline: 0.5,
  easing: (t) => t * t * t,
  simulatePressure: true,
  last: true,
  start: {
    taper: 20,
    easing: (t) => t * t * t,
  },
  end: {
    taper: 20,
    easing: (t) => t * t * t,
  },
})

Tip: To create a stroke with a steady line, set the thinning option to 0.

Tip: To create a stroke that gets thinner with pressure instead of thicker, use a negative number for the thinning option.

While getStroke returns an array of points representing the outline of a stroke, it's up to you to decide how you will render these points.

The function below will turn the points returned by getStroke into SVG path data.

function getSvgPathFromStroke(stroke) {
  if (!stroke.length) return ''

  const d = stroke.reduce(
    (acc, [x0, y0], i, arr) => {
      const [x1, y1] = arr[(i + 1) % arr.length]
      acc.push(x0, y0, (x0 + x1) / 2, (y0 + y1) / 2)
      return acc
    },
    ['M', ...stroke[0], 'Q']
  )

  d.push('Z')
  return d.join(' ')
}

To use this function, first use perfect-freehand to turn your input points into a stroke outline, then pass the result to getSvgPathFromStroke.

import { getStroke } from 'perfect-freehand'

const myStroke = getStroke(myInputPoints)

const pathData = getSvgPathFromStroke(myStroke)

You could then pass this string either to an SVG path element:

<path d={pathData} />

Or, if you are rendering with HTML Canvas, you can pass the result to a Path2D constructor).

const myPath = new Path2D(pathData)
ctx.fill(myPath)

To render a stroke as a "flattened" polygon, add the polygon-clipping package and use the following function together with the getSvgPathFromStroke.

import polygonClipping from 'polygon-clipping'

function getFlatSvgPathFromStroke(stroke) {
  const poly = polygonClipping.union([stroke])

  const d = []

  for (let face of poly) {
    for (let points of face) {
      d.push(getSvgPathFromStroke(points))
    }
  }

  return d.join(' ')
}

Tip: For implementations in Typescript, see the example project included in this repository.

import * as React from 'react'
import { getStroke } from 'perfect-freehand'
import { getSvgPathFromStroke } from './utils'

export default function Example() {
  const [points, setPoints] = React.useState()

  function handlePointerDown(e) {
    setPoints([[e.pageX, e.pageY, e.pressure]])
  }

  function handlePointerMove(e) {
    if (e.buttons === 1) {
      setPoints([...points, [e.pageX, e.pageY, e.pressure]])
    }
  }

  return (
    <svg
      onPointerDown={handlePointerDown}
      onPointerMove={handlePointerMove}
      style={{ touchAction: 'none' }}
    >
      {points && (
        <path
          d={getSvgPathFromStroke(
            getStroke(points, {
              size: 16,
              thinning: 0.5,
              smoothing: 0.5,
              streamline: 0.5,
            })
          )}
        />
      )}
    </svg>
  )
}

A TypeScript type for the options object.

import { StrokeOptions } from 'perfect-freehand'

For advanced usage, the library also exports smaller functions that getStroke uses to generate its SVG data. While you can use getStroke's data to render strokes with an HTML canvas (via the Path2D element) or with SVG paths, these new functions will allow you to create paths in other rendering technologies.

import { strokePoints } from 'perfect-freehand'
const strokePoints = getStrokePoints(rawInputPoints)

Accepts an array of points (formatted either as [x, y, pressure] or { x: number, y: number, pressure: number}) and a streamline value. Returns a set of streamlined points as [x, y, pressure, angle, distance, lengthAtPoint]. The path's total length will be the length of the last point in the array.

Accepts an array of points (formatted as [x, y, pressure, angle, distance, length], i.e. the output of getStrokePoints) and returns an array of points ([x, y]) defining the outline of a pressure-sensitive stroke.

import { getOutlinePoints } from 'perfect-freehand'
const outlinePoints = getOutlinePoints(strokePoints)

Please open an issue for support.

Have an idea or casual question? Visit the discussion page.

• @steveruizok