perfect-freehand

The getStroke function returns an array of points representing the outline of a stroke. To render these points in an SVG, you can use a helper function to convert the points into an SVG path data string. This string can then be used in an <path d={pathData} /> element.

const average = (a, b) => (a + b) / 2

function getSvgPathFromStroke(points, closed = true) {
  const len = points.length

  if (len < 4) {
    return ``
  }

  let a = points[0]
  let b = points[1]
  const c = points[2]

  let result = `M${a[0].toFixed(2)},${a[1].toFixed(2)} Q${b[0].toFixed(
    2
  )},${b[1].toFixed(2)} ${average(b[0], c[0]).toFixed(2)},${average(
    b[1],
    c[1]
  ).toFixed(2)} T`

  for (let i = 2, max = len - 1; i < max; i++) {
    a = points[i]
    b = points[i + 1]
    result += `${average(a[0], b[0]).toFixed(2)},${average(
      a[1], b[1]
    ).toFixed(2)} `
  }

  if (closed) {
    result += 'Z'
  }

  return result
}

// Usage:
const outlinePoints = getStroke(inputPoints)
const pathData = getSvgPathFromStroke(outlinePoints)

You can customize the stroke appearance using a StrokeOptions object passed as the second argument to getStroke.

Main Options:

• size (number, default: 8): The base diameter of the stroke.
• thinning (number, default: .5): The effect of pressure on size. Set to 0 for a steady line, or a negative number to make the stroke thinner with pressure.
• smoothing (number, default: .5): How much to soften edges.
• streamline (number, default: .5): How much to streamline the stroke.
• simulatePressure (boolean, default: true): Whether to simulate pressure based on velocity.
• easing (function, default: t => t): An easing function applied to each point's pressure.
• last (boolean, default: true): If true, the end is drawn at the last input point.
• start / end (object): Tapering options for the start or end of the line.

Tapering Options (start and end):

• cap (boolean, default: true): Whether to draw a cap. (Note: cap has no effect if taper is > 0).
• taper (number | boolean, default: 0): The distance to taper. If true, the taper covers the total length of the stroke.
• easing (function, default: t => t): Easing function for the tapering effect.

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

The getStroke function generates an array of outline points for a polygon based on an array of input points. These points can be provided as an array of arrays [x, y, pressure] or an array of objects { x, y, pressure }.

By default, pressure is simulated based on velocity. To use real pressure from a stylus, provide the pressure as the third value in the point array and set simulatePressure: false in the options.

import { getStroke } from 'perfect-freehand'

// Using array of arrays with simulated pressure
const inputPoints = [
  [0, 0],
  [10, 5],
  [20, 8],
]
const outlinePoints = getStroke(inputPoints)

// Using array of arrays with real pressure
const realPressurePoints = [
  [0, 0, 0.5],
  [10, 5, 0.7],
  [20, 8, 0.8],
]
const outlinePointsReal = getStroke(realPressurePoints, {
  simulatePressure: false,
})

// Using array of objects
const objectPoints = [
  { x: 0, y: 0, pressure: 0.5 },
  { x: 10, y: 5, pressure: 0.7 },
  { x: 20, y: 8, pressure: 0.8 },
]
const outlinePointsObj = getStroke(objectPoints, {
  simulatePressure: false,
})

The getStroke function is the primary API for generating an array of points that describe a polygon surrounding a set of input points. This polygon can be used to render pressure-sensitive, smoothed strokes.

Input points can be provided as an array of arrays [x, y, pressure] or an array of objects { x, y, pressure }. The pressure property is optional.

Options