thfrei / perfect-freehand

Draw perfect pressure-sensitive freehand lines.

Draw perfect pressure-sensitive freehand lines.

🔗 Curious? Try out a demo.

💅 Designer? Check out the Figma Plugin.

🕊 Flutterer? There's now a dart version of this library, too.

💕 Love this library? Consider becoming a sponsor.

Table of Contents

• Installation
• Usage
• Documentation
• Community
• Author

Installation

npm install perfect-freehand

or

yarn add perfect-freehand

Introduction

This package exports a function named getStroke that will generate the points for a polygon based on an array of points.

To do this work, getStroke first creates a set of spline points (red) based on the input points (grey) and then creates outline points (blue). You can render the result any way you like, using whichever technology you prefer.

Usage

To use this library, import the getStroke function and pass it an array of input points, such as those recorded from a user's mouse movement. The getStroke function will return a new array of outline points. These outline points will form a polygon (called a "stroke") that surrounds the input points.

import { getStroke } from 'perfect-freehand'

const inputPoints = [
  [0, 0],
  [10, 5],
  [20, 8],
  // ...
]

const outlinePoints = getStroke(inputPoints)

You then can render your stroke points using your technology of choice. See the Rendering section for examples in SVG and HTML Canvas.

You can customize the appearance of the stroke shape by passing getStroke a second parameter: an options object containing one or more options. See the Options section for a full list of available options.

const stroke = getStroke(myPoints, {
  size: 32,
  thinning: 0.7,
})

The appearance of a stroke is effected by the pressure associated with each input point. By default, the getStroke function will simulate pressure based on the distance between input points.

To use real pressure, such as that from a pen or stylus, provide the pressure as the third number for each input point, and set the simulatePressure option to false.

const inputPoints = [
  [0, 0, 0.5],
  [10, 5, 0.7],
  [20, 8, 0.8],
  // ...
]

const outlinePoints = getStroke(inputPoints, {
  simulatePressure: false,
})

In addition to providing points as an array of arrays, you may also provide your points as an array of objects as show in the example below. In both cases, the value for pressure is optional (it will default to .5).

const inputPoints = [
  { x: 0, y: 0, pressure: 0.5 },
  { x: 10, y: 5, pressure: 0.7 },
  { x: 20, y: 8, pressure: 0.8 },
  // ...
]

const outlinePoints = getStroke(inputPoints, {
  simulatePressure: false,
})

Note: Internally, the getStroke function will convert your object points to array points, which will have an effect on performance. If you're using this library ambitiously and want to format your points as objects, consider modifying this library's getStrokeOutlinePoints to use the object syntax instead (e.g. replacing all [0] with .x, [1] with .y, and [2] with .pressure).

Example

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) {
    e.target.setPointerCapture(e.pointerId)
    setPoints([[e.pageX, e.pageY, e.pressure]])
  }

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

  const stroke = getStroke(points, {
    size: 16,
    thinning: 0.5,
    smoothing: 0.5,
    streamline: 0.5,
  })

  const pathData = getSvgPathFromStroke(stroke)

  return (
    <svg
      onPointerDown={handlePointerDown}
      onPointerMove={handlePointerMove}
      style={{ touchAction: 'none' }}
    >
      {points && <path d={pathData} />}
    </svg>
  )
}

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

Documentation

Options

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

Property	Type	Default	Description
size	number	8	The base size (diameter) of the stroke.
thinning	number	.5	The effect of pressure on the stroke's size.
smoothing	number	.5	How much to soften the stroke's edges.
streamline	number	.5	How much to streamline the stroke.
simulatePressure	boolean	true	Whether to simulate pressure based on velocity.
easing	function	t => t	An easing function to apply to each point's pressure.
start	{ }		Tapering options for the start of the line.
end	{ }		Tapering options for the end of the line.
last	boolean	true	Whether the stroke is complete.

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:

Property	Type	Default	Description
cap	boolean	true	Whether to draw a cap.
taper	number	0	The distance to taper.
easing	function	t => t	An easing function for the tapering effect.

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,
  simulatePressure: true,
  last: true,
  start: {
    cap: true,
    taper: 0,
    easing: (t) => t,
  },
  end: {
    cap: true,
    taper: 0,
    easing: (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.

Other Exports

For advanced usage, the library also exports smaller functions that getStroke uses to generate its outline points.

getStrokePoints

A function that accepts an array of points (formatted either as [x, y, pressure] or { x: number, y: number, pressure: number}) and (optionally) an options object. Returns a set of adjusted points as { point, pressure, vector, distance, runningLength }. The path's total length will be the runningLength of the last point in the array.

import { getStrokePoints } from 'perfect-freehand'
import samplePoints from "./samplePoints.json'

const strokePoints = getStrokePoints(samplePoints)

getOutlinePoints

A function that accepts an array of points (formatted as { point, pressure, vector, distance, runningLength }, i.e. the output of getStrokePoints) and (optionally) an options object, and returns an array of points ([x, y]) defining the outline of a pressure-sensitive stroke.

import { getStrokePoints, getOutlinePoints } from 'perfect-freehand'
import samplePoints from "./samplePoints.json'

const strokePoints = getStrokePoints(samplePoints)

const outlinePoints = getOutlinePoints(strokePoints)

Note: Internally, the getStroke function passes the result of getStrokePoints to getStrokeOutlinePoints, just as shown in this example. This means that, in this example, the result of myOutlinePoints will be the same as if the samplePoints array had been passed to getStroke.

StrokeOptions

A TypeScript type for the options object. Useful if you're defining your options outside of the getStroke function.

import { StrokeOptions, getStroke } from 'perfect-freehand'

const options: StrokeOptions = {
  size: 16,
}

const stroke = getStroke(options)

Tips & Tricks

Freehand Anything

While this library was designed for rendering the types of input points generated by the movement of a human hand, you can pass any set of points into the library's functions. For example, here's what you get when running Feather Icons through getStroke.

Rendering

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 run your input points through getStroke, then pass the result to getSvgPathFromStroke.

const outlinePoints = getStroke(inputPoints)

const pathData = getSvgPathFromStroke(outlinePoints)

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

<path d={pathData} />

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

const myPath = new Path2D(pathData)

ctx.fill(myPath)

Flattening

By default, the polygon's paths include self-crossings. You may wish to remove these crossings and render a stroke as a "flattened" polygon. To do this, install the polygon-clipping package and use the following function together with the getSvgPathFromStroke.

import polygonClipping from 'polygon-clipping'

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

  const d = []

  faces.forEach((face) =>
    face.forEach((points) => {
      d.push(getSvgPathFromStroke(points))
    })
  )

  return d.join(' ')
}

Development & Contributions

To work on this library:

• clone this repo
• run yarn in the folder root to install dependencies
• run yarn start to start the local development server

The development server is located at packages/dev. The library and its tests are located at packages/perfect-freehand.

Pull requests are very welcome!

Community

Support

Need help? Please open an issue for support.

Discussion

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

License

• MIT
• ...but if you're using perfect-freehand in a commercial product, consider becoming a sponsor. 💰

Author

• @steveruizok