Perfect Freehand

https://github.com/steveruizok/perfect-freehand
Admin
Perfect Freehand is a TypeScript library that generates pressure-sensitive freehand strokes by...
Tokens:35,841
Snippets:238
Trust Score:10
License:MIT
Update:1 week ago
Show doc for...
Tokens:
Raw
### Install perfect-freehand with yarn

Source: https://github.com/steveruizok/perfect-freehand/blob/main/README.md

Use this command to install the library using the yarn package manager.

```bash
yarn add perfect-freehand
```

--------------------------------

### Install perfect-freehand with npm

Source: https://github.com/steveruizok/perfect-freehand/blob/main/README.md

Use this command to install the library using the npm package manager.

```bash
npm install perfect-freehand
```

--------------------------------

### Configure getStroke options

Source: https://github.com/steveruizok/perfect-freehand/blob/main/README.md

Example usage of the getStroke function with a full configuration object.

```js
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,
  },
})
```

--------------------------------

### Streaming / incremental usage pattern

Source: https://github.com/steveruizok/perfect-freehand/blob/main/_autodocs/index.md

Demonstrates how to use the perfect-freehand library to accumulate raw input points while drawing and convert them incrementally. The example shows how to use getStrokePoints and getStrokeOutlinePoints for live preview and finalization.

```APIDOC
## Streaming / incremental usage pattern

### Description
Because the pipeline is split, consumers can accumulate raw input points while drawing and convert incrementally. This example shows how to use getStrokePoints and getStrokeOutlinePoints for live preview and finalization.

### Usage Example
```ts
import { getStrokePoints, getStrokeOutlinePoints } from 'perfect-freehand'

let inputPoints: number[][] = []

function onPointerMove(x: number, y: number, pressure?: number) {
  inputPoints.push(pressure === undefined ? [x, y] : [x, y, pressure])
  // live preview: treat as unfinished stroke
  const stroke = getStrokeOutlinePoints(getStrokePoints(inputPoints, { last: false }))
  render(stroke)
}

function onPointerUp() {
  // finalize: draw the end exactly at the last input point
  const stroke = getStrokeOutlinePoints(getStrokePoints(inputPoints, { last: true }))
  render(stroke)
}
```

### Notes
- The library is a client-side geometry library with no HTTP/RPC routes or servers.
- Functions return [] or clamped values instead of throwing errors.
```

--------------------------------

### Handling empty or degenerate cases

Source: https://github.com/steveruizok/perfect-freehand/blob/main/_autodocs/api-reference/getStrokeOutlinePoints.md

Examples of how the function gracefully handles empty inputs, negative sizes, and single-point strokes without throwing exceptions.

```ts
import { getStrokePoints, getStrokeOutlinePoints } from 'perfect-freehand'

// Empty stroke points -> [] (no exception)
getStrokeOutlinePoints([])

// Negative size -> [] (no exception)
getStrokeOutlinePoints(strokePoints, { size: -4 })

// A single StrokePoint -> a dot (13-point circle)
getStrokeOutlinePoints(getStrokePoints([[100, 100]]))
```

--------------------------------

### Object-form input with explicit options

Source: https://github.com/steveruizok/perfect-freehand/blob/main/_autodocs/api-reference/getStrokePoints.md

Accepts input points as objects with optional pressure, and passes options streamline, size, and last. Only these three options take effect; others like thinning, smoothing, easing, simulatePressure, start, and end are ignored here and only apply when passed to getStrokeOutlinePoints.

```ts
import { getStrokePoints } from 'perfect-freehand'

const strokePoints = getStrokePoints(
  [
    { x: 0, y: 0 },
    { x: 10, y: 5, pressure: 0.5 },
    { x: 20, y: 8 },
  ],
  {
    streamline: 0.5,
    size: 16,
    last: true, // keep the final point exactly at the last input position
  }
)
```

--------------------------------

### Options destructuring with defaults for getStrokeOutlinePoints

Source: https://github.com/steveruizok/perfect-freehand/blob/main/_autodocs/api-reference/getStrokeOutlinePoints.md

Shows the default values for the options consumed by getStrokeOutlinePoints, including size, smoothing, thinning, simulatePressure, easing, start, end, and last. The start and end sub-options have their own defaults for cap, taper, and easing.

```typescript
const {
  size = 16,
  smoothing = 0.5,
  thinning = 0.5,
  simulatePressure: shouldSimulatePressure = true,
  easing = (t) => t,
  start = {},
  end = {},
  last: isComplete = false,
} = options

const { cap: capStart = true, easing: taperStartEase = (t) => t * (2 - t) } = start
const { cap: capEnd = true, easing: taperEndEase = (t) => --t * t * t + 1 } = end
```

--------------------------------

### Streaming incremental stroke drawing with getStrokePoints and getStrokeOutlinePoints

Source: https://github.com/steveruizok/perfect-freehand/blob/main/_autodocs/index.md

Use this pattern to accumulate raw input points during pointer movement and convert them incrementally. The example shows a live preview with `last: false` and finalization with `last: true` to draw the stroke end exactly at the last input point.

```TypeScript
import { getStrokePoints, getStrokeOutlinePoints } from 'perfect-freehand'

let inputPoints: number[][] = []

function onPointerMove(x: number, y: number, pressure?: number) {
  inputPoints.push(pressure === undefined ? [x, y] : [x, y, pressure])
  // live preview: treat as unfinished stroke
  const stroke = getStrokeOutlinePoints(getStrokePoints(inputPoints, { last: false }))
  render(stroke)
}

function onPointerUp() {
  // finalize: draw the end exactly at the last input point
  const stroke = getStrokeOutlinePoints(getStrokePoints(inputPoints, { last: true }))
  render(stroke)
}
```

--------------------------------

### Rendering the outline in SVG

Source: https://github.com/steveruizok/perfect-freehand/blob/main/_autodocs/api-reference/getStroke.md

A helper function getSvgPathFromStroke converts outline points to an SVG path string, and an example usage with getStroke.

```typescript
import { getStroke } from 'perfect-freehand'

const average = (a: number[], b: number[]) => [(a[0] + b[0]) / 2, (a[1] + b[1]) / 2]

function getSvgPathFromStroke(points: number[][], closed = true): string {
  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, c)[0].toFixed(2)},${average(b, c)[1].toFixed(2)} T`

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

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

const outlinePoints = getStroke(inputPoints, { size: 16, thinning: 0.5 })
const pathData = getSvgPathFromStroke(outlinePoints)
// pass pathData to an SVG <path d={...}/> or new Path2D(pathData)
```

--------------------------------

### Error-tolerant / edge-case handling

Source: https://github.com/steveruizok/perfect-freehand/blob/main/_autodocs/api-reference/getStroke.md

Shows a safeStroke wrapper that guards against empty input and non-positive size, plus examples of single-point and coincident-point handling.

```typescript
import { getStroke } from 'perfect-freehand'

function safeStroke(points: number[][]): [number, number][] {
  // Empty input returns [] — no exception
  if (points.length === 0) return []

  // Negative or zero size returns [] (checked in getStrokeOutlinePoints)
  if (points.length > 0) {
    return getStroke(points, { size: Math.max(0.01, 16) })
  }
  return getStroke(points)
}

// A single point produces a dot (circle of 13 points) instead of a line
const dot = getStroke([[100, 100]])

// Two coincident points are handled (deduplicated inside getStrokePoints)
const degenerate = getStroke([
  [1, 1],
  [1, 1],
])
```

--------------------------------

### Taper strength radius calculation

Source: https://github.com/steveruizok/perfect-freehand/blob/main/_autodocs/configuration.md

Applies the taper strength to the radius, clamping the result to MIN_RADIUS. The strength is the minimum of the start and end taper strengths.

```typescript
radius = Math.max(MIN_RADIUS, radius * Math.min(taperStartStrength, taperEndStrength))
```

--------------------------------

### Render SVG path data in an SVG path element

Source: https://github.com/steveruizok/perfect-freehand/blob/main/README.md

Example of passing the SVG path data string to an SVG path element's d attribute.

```jsx
<path d={pathData} />
```

--------------------------------

### Project CLI Commands

Source: https://github.com/steveruizok/perfect-freehand/blob/main/CLAUDE.md

A collection of common commands for managing dependencies, running tests, building the library, and maintaining code quality.

```bash
# Install dependencies (uses yarn workspaces)
yarn

# Start development server (runs both dev app and library watch)
yarn start

# Run all tests
yarn test

# Run tests in watch mode
yarn test:watch

# Run a single test file
yarn test packages/perfect-freehand/src/test/getStroke.spec.ts

# Run benchmarks
yarn bench

# Build the library
yarn build:packages

# Lint the library
cd packages/perfect-freehand && yarn lint

# Format code with Prettier
yarn format

# Check formatting without making changes
yarn format:check

# Generate API documentation
cd packages/perfect-freehand && yarn docs
```

--------------------------------

### Basic usage with getStrokePoints

Source: https://github.com/steveruizok/perfect-freehand/blob/main/_autodocs/api-reference/getStrokeOutlinePoints.md

Demonstrates the standard workflow of generating stroke points followed by outline points.

```ts
import { getStrokePoints, getStrokeOutlinePoints } from 'perfect-freehand'

const strokePoints = getStrokePoints(inputPoints)
const outlinePoints = getStrokeOutlinePoints(strokePoints)
// identical to getStroke(inputPoints)
```

--------------------------------

### Live-drawing preview pattern

Source: https://github.com/steveruizok/perfect-freehand/blob/main/_autodocs/api-reference/getStrokePoints.md

Shows an incremental approach for live drawing: use last: false for in-progress previews and last: true on pointer-up to finalize. Both functions are re-run as points accumulate.

```ts
import { getStrokePoints, getStrokeOutlinePoints } from 'perfect-freehand'

// Incremental: re-run stages as points accumulate.
// Pass last: false for the in-progress preview, last: true on pointer-up.
function preview(points: number[][]) {
  const strokePoints = getStrokePoints(points, { last: false })
  return getStrokeOutlinePoints(strokePoints, { last: false })
}

function finalize(points: number[][]) {
  const strokePoints = getStrokePoints(points, { last: true })
  return getStrokeOutlinePoints(strokePoints, { last: true })
}
```

--------------------------------

### Source entry point (src/index.ts)

Source: https://github.com/steveruizok/perfect-freehand/blob/main/_autodocs/index.md

The main entry point of the library, re-exporting the getStroke function and other modules.

```typescript
import { getStroke } from './getStroke'

export default getStroke

export * from './getStrokeOutlinePoints'
export * from './getStrokePoints'
export * from './getStroke'
export * from './types'
```

--------------------------------

### Using points as an array of objects

Source: https://github.com/steveruizok/perfect-freehand/blob/main/README.md

Points can be provided as an array of objects with x, y, and optional pressure properties.

```js
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,
})
```

--------------------------------

### Configured stroke with options

Source: https://github.com/steveruizok/perfect-freehand/blob/main/_autodocs/api-reference/getStroke.md

Shows a fully configured getStroke call with size, thinning, smoothing, streamline, easing, simulatePressure, last, and start/end cap options.

```typescript
import { getStroke } from 'perfect-freehand'

const stroke = getStroke(points, {
  size: 32,
  thinning: 0.7,
  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,
  },
})
```

--------------------------------

### Sample points JSON array

Source: https://github.com/steveruizok/perfect-freehand/blob/main/tutorial/script.md

A JSON file containing an array of points (x and y positions) similar to those recorded from a user drawing with a mouse or trackpad.

```json
{
  "points": [
    [47.671875, 179.84375],
    [48.1171875, 179.8515625]
    //...
  ]
}
```

--------------------------------

### Using real pressure with array points

Source: https://github.com/steveruizok/perfect-freehand/blob/main/README.md

Provide pressure as the third number in each input point and set simulatePressure to false to use real stylus pressure.

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

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

--------------------------------

### Use getSvgPathFromStroke with getStroke

Source: https://github.com/steveruizok/perfect-freehand/blob/main/README.md

Shows how to obtain the outline points from input points using getStroke and then convert them to SVG path data with getSvgPathFromStroke.

```javascript
const outlinePoints = getStroke(inputPoints)

const pathData = getSvgPathFromStroke(outlinePoints)
```

--------------------------------

### Basic usage of getStroke

Source: https://github.com/steveruizok/perfect-freehand/blob/main/README.md

Import the getStroke function and pass an array of input points to generate an array of outline points.

```js
import { getStroke } from 'perfect-freehand'

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

const outlinePoints = getStroke(inputPoints)
```

--------------------------------

### Simplify points

Source: https://github.com/steveruizok/perfect-freehand/blob/main/tutorial/script.md

Imports the simplify helper and simplifies the points array.

```javascript
import { simplify } from './helpers'

points = simplify(points)
```

--------------------------------

### Incremental drawing with last

Source: https://github.com/steveruizok/perfect-freehand/blob/main/_autodocs/api-reference/getStroke.md

Shows how to use getStroke with last: false for preview and last: true for the final stroke in a live drawing scenario.

```typescript
import { getStroke } from 'perfect-freehand'

let points: number[][] = []
function onMove(x: number, y: number) {
  points.push([x, y])
  renderOutline(getStroke(points, { last: false })) // preview
}
function onUp() {
  renderOutline(getStroke(points, { last: true })) // final
}
```

--------------------------------

### Import points from JSON

Source: https://github.com/steveruizok/perfect-freehand/blob/main/tutorial/script.md

In the JavaScript file, the points are imported from the sample JSON file.

```javascript
import points from './sample.json'
```

--------------------------------

### Feeding the next stage (equivalent to getStroke)

Source: https://github.com/steveruizok/perfect-freehand/blob/main/_autodocs/api-reference/getStrokePoints.md

Shows how to pass the result of getStrokePoints to getStrokeOutlinePoints, producing the same result as calling getStroke directly.

```ts
import { getStrokePoints, getStrokeOutlinePoints } from 'perfect-freehand'

const strokePoints = getStrokePoints(samplePoints)
const outlinePoints = getStrokeOutlinePoints(strokePoints)
// Same result as: getStroke(samplePoints)
```

--------------------------------

### getStrokePoints(inputPoints, options?)

Source: https://github.com/steveruizok/perfect-freehand/blob/main/_autodocs/api-reference/getStrokePoints.md

Converts raw input points into processed stroke points. Accepts points as tuples [x, y, pressure?] or objects {x, y, pressure?}. Options streamline, size, and last affect the output; other options are ignored.

```APIDOC
## getStrokePoints(inputPoints, options?)

### Description
Converts raw input points into processed stroke points. Accepts points as tuples [x, y, pressure?] or objects {x, y, pressure?}. Options streamline, size, and last affect the output; other options are ignored.

### Method
Function

### Signature
```ts
getStrokePoints(inputPoints: InputPoint[], options?: StrokeOptions): StrokePoint[]
```

### Parameters
#### inputPoints
- Type: Array of tuples [number, number, number?] or objects {x: number, y: number, pressure?: number}
- Required: Yes
- Description: The raw input points to process.

#### options (optional)
- Type: StrokeOptions
- Description: Options that affect the stroke point calculation. Only `streamline`, `size`, and `last` take effect. Other options (`thinning`, `smoothing`, `easing`, `simulatePressure`, `start`, `end`) are ignored.

### Options
- **streamline** (number) - Optional - The amount of streamlining to apply.
- **size** (number) - Optional - The size of the stroke.
- **last** (boolean) - Optional - If true, keep the final point exactly at the last input position.

### Return Value
Returns an array of stroke points, each with the following properties:
- **point** (number[]) - The [x, y] coordinates of the point.
- **pressure** (number) - The pressure at the point.
- **vector** (number[]) - The direction vector from the previous point.
- **distance** (number) - The distance from the previous point.
- **runningLength** (number) - The cumulative length of the stroke up to this point.

### Throws / Rejects
Never throws. Empty input, degenerate inputs (coincident points, single points), and missing pressures are handled internally.

### Examples

#### Basic conversion
```ts
import { getStrokePoints } from 'perfect-freehand'

const inputPoints = [
  [0, 0, 0.5],
  [10, 5, 0.6],
  [20, 8, 0.8],
  [30, 12, 0.7],
]

const strokePoints = getStrokePoints(inputPoints)

// Total line length is the last element's runningLength
const totalLength = strokePoints[strokePoints.length - 1].runningLength

// Each entry exposes the values used by the outline stage
for (const sp of strokePoints) {
  console.log(sp.point, sp.pressure, sp.vector, sp.distance, sp.runningLength)
}
```

#### Object-form input with explicit options
```ts
import { getStrokePoints } from 'perfect-freehand'

const strokePoints = getStrokePoints(
  [
    { x: 0, y: 0 },
    { x: 10, y: 5, pressure: 0.5 },
    { x: 20, y: 8 },
  ],
  {
    streamline: 0.5,
    size: 16,
    last: true, // keep the final point exactly at the last input position
  }
)
```

Note: only `streamline`, `size`, and `last` take effect in this function. If you pass `thinning`, `smoothing`, `easing`, `simulatePressure`, `start`, or `end`, they are ignored here and only apply when the results are passed to `getStrokeOutlinePoints`.

#### Feeding the next stage (equivalent to `getStroke`)
```ts
import { getStrokePoints, getStrokeOutlinePoints } from 'perfect-freehand'

const strokePoints = getStrokePoints(samplePoints)
const outlinePoints = getStrokeOutlinePoints(strokePoints)
// Same result as: getStroke(samplePoints)
```

#### Live-drawing preview pattern
```ts
import { getStrokePoints, getStrokeOutlinePoints } from 'perfect-freehand'

// Incremental: re-run stages as points accumulate.
// Pass last: false for the in-progress preview, last: true on pointer-up.
function preview(points: number[][]) {
  const strokePoints = getStrokePoints(points, { last: false })
  return getStrokeOutlinePoints(strokePoints, { last: false })
}

function finalize(points: number[][]) {
  const strokePoints = getStrokePoints(points, { last: true })
  return getStrokeOutlinePoints(strokePoints, { last: true })
}
```
```

--------------------------------

### Full-length taper with taper: true

Source: https://github.com/steveruizok/perfect-freehand/blob/main/_autodocs/api-reference/getStrokeOutlinePoints.md

Illustrates using a boolean true for the taper option to apply a taper over the entire length of the stroke.

```ts
const outlinePoints = getStrokeOutlinePoints(strokePoints, {
  start: { taper: true },
  end: { taper: true },
})
```

--------------------------------

### Render SVG path data with HTML Canvas Path2D

Source: https://github.com/steveruizok/perfect-freehand/blob/main/README.md

Shows how to use the SVG path data string with a Path2D constructor and fill it on a canvas context.

```javascript
const myPath = new Path2D(pathData)

ctx.fill(myPath)
```

--------------------------------

### Create SVG path data string

Source: https://github.com/steveruizok/perfect-freehand/blob/main/tutorial/script.md

Uses the points to create a string of SVG path data by joining 'M' with the first point and 'L' with the rest.

```javascript
const pathData = ['M', points[0], 'L', points.slice(1)].join(' ')
```

--------------------------------

### Configure streamline

Source: https://github.com/steveruizok/perfect-freehand/blob/main/tutorial/script.md

Control the low-pass filter strength to smooth out noisy input points.

```js
const stroke = getStroke(sample.points, {
  size: 16,
  thinning: 0.5,
  streamline: 0,
})
```

```js
const stroke = getStroke(sample.points, {
  size: 16,
  thinning: 0.5,
  streamline: 1,
})
```

--------------------------------

### Apply positive thinning

Source: https://github.com/steveruizok/perfect-freehand/blob/main/tutorial/script.md

Set a positive thinning value to increase the pressure effect on width.

```js
const stroke = getStroke(sample.points, {
  size: 16,
  thinning: 0.9,
})
```

--------------------------------

### Points as objects with real pressure

Source: https://github.com/steveruizok/perfect-freehand/blob/main/_autodocs/api-reference/getStroke.md

Uses object-form points with pressure values and sets simulatePressure: false to preserve real stylus pressure.

```typescript
import getStroke from 'perfect-freehand'

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

// simulatePressure: false keeps the real stylus pressure values
const outlinePoints = getStroke(inputPoints, {
  simulatePressure: false,
})
```

--------------------------------

### getStroke(points, options?)

Source: https://github.com/steveruizok/perfect-freehand/blob/main/_autodocs/api-reference/getStroke.md

Computes a closed polygon outline around the given input points. Accepts an array of points (as tuples or objects with x, y, pressure) and an optional StrokeOptions object. Returns an array of [x, y] points in winding order.

```APIDOC
## getStroke(points, options?)

### Description
Computes a closed polygon outline around the given input points. Accepts an array of points (as tuples or objects with x, y, pressure) and an optional StrokeOptions object. Returns an array of [x, y] points in winding order.

### Signature
```ts
export function getStroke(
  points: (number[] | { x: number; y: number; pressure?: number })[],
  options: StrokeOptions = {} as StrokeOptions
): Vec2[]
```

### Parameters
- **points** (array of number[] or { x, y, pressure? }) - Required - Input points to generate the stroke outline. Can be tuples like [x, y] or objects with x, y, and optional pressure.
- **options** (StrokeOptions) - Optional - Configuration options for the stroke. Defaults to {}.

### Return Value
- **Vec2[]** - An array of [x, y] points describing a closed polygon that surrounds the input points, in winding order: left side, end cap, right side (reversed), start cap.

### Behavior Notes
- The function never throws. Empty points array yields []. A size <= 0 option yields [] (checked inside getStrokeOutlinePoints).
- All StrokeOptions are honored, including streamline, smoothing, thinning, easing, simulatePressure, start, end, and last.
- Passing object-form points incurs a conversion to arrays inside getStrokePoints, which has a performance cost compared to tuple-form points.

### Examples

#### Basic usage
```ts
import { getStroke } from 'perfect-freehand'

const inputPoints = [
  [0, 0],
  [10, 5],
  [20, 8],
  [30, 12],
  [40, 11],
]

const outlinePoints: [number, number][] = getStroke(inputPoints)
// outlinePoints forms a closed polygon around the input line
```

#### Points as objects with real pressure
```ts
import getStroke from 'perfect-freehand'

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

// simulatePressure: false keeps the real stylus pressure values
const outlinePoints = getStroke(inputPoints, {
  simulatePressure: false,
})
```

#### Configured stroke
```ts
import { getStroke } from 'perfect-freehand'

const stroke = getStroke(points, {
  size: 32,
  thinning: 0.7,
  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,
  },
})
```

#### Rendering the outline in SVG
A common consumer-side helper (shown in the package README) turns the outline into an SVG path:

```ts
import { getStroke } from 'perfect-freehand'

const average = (a: number[], b: number[]) => [(a[0] + b[0]) / 2, (a[1] + b[1]) / 2]

function getSvgPathFromStroke(points: number[][], closed = true): string {
  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, c)[0].toFixed(2)},${average(b, c)[1].toFixed(2)} T`

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

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

const outlinePoints = getStroke(inputPoints, { size: 16, thinning: 0.5 })
const pathData = getSvgPathFromStroke(outlinePoints)
// pass pathData to an SVG <path d={...}/> or new Path2D(pathData)
```

#### Error-tolerant / edge-case handling
The library never throws, so "error handling" consists of guarding your own input and observing the documented degradations:

```ts
import { getStroke } from 'perfect-freehand'

function safeStroke(points: number[][]): [number, number][] {
  // Empty input returns [] — no exception
  if (points.length === 0) return []

  // Negative or zero size returns [] (checked in getStrokeOutlinePoints)
  if (points.length > 0) {
    return getStroke(points, { size: Math.max(0.01, 16) })
  }
  return getStroke(points)
}

// A single point produces a dot (circle of 13 points) instead of a line
const dot = getStroke([[100, 100]])

// Two coincident points are handled (deduplicated inside getStrokePoints)
const degenerate = getStroke([
  [1, 1],
  [1, 1],
])
```

#### Incremental drawing with `last`
For live drawing, call `getStroke` (or the split stages) repeatedly as points arrive; when the stroke completes, pass `last: true` so the end of the line lands exactly on the last input point instead of slightly behind it (see [getStrokePoints.md](./getStrokePoints.md) and [configuration.md](../configuration.md)).

```ts
import { getStroke } from 'perfect-freehand'

let points: number[][] = []
function onMove(x: number, y: number) {
  points.push([x, y])
  renderOutline(getStroke(points, { last: false })) // preview
}
function onUp() {
  renderOutline(getStroke(points, { last: true })) // final
}
```
```

--------------------------------

### getStroke(inputPoints, options?)

Source: https://github.com/steveruizok/perfect-freehand/blob/main/README.md

The getStroke function takes an array of input points and returns an array of outline points forming a stroke polygon. It accepts optional options to customize the stroke appearance and pressure simulation.

```APIDOC
## getStroke(inputPoints, options?)

### Description
Generates an array of outline points that form a stroke polygon surrounding the given input points. The stroke appearance can be customized via options, and pressure can be simulated or provided explicitly.

### Method
Function call

### Endpoint
Not applicable (SDK function)

### Parameters
#### inputPoints (Array<Array<number> | Object>) - Required
An array of input points. Each point can be an array of [x, y, pressure?] or an object with x, y, and optional pressure properties. Pressure defaults to 0.5 if not provided.

#### options (Object) - Optional
An options object to customize the stroke. Supported options include:
- **size** (number) - The stroke size.
- **thinning** (number) - The thinning factor.
- **simulatePressure** (boolean) - When false, uses real pressure from input points; when true (default), simulates pressure based on distance.

### Request Example
```js
import { getStroke } from 'perfect-freehand'

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

const outlinePoints = getStroke(inputPoints)
```

### Response
#### Success Response
Returns an array of outline points (array of [x, y] pairs) that form the stroke polygon.

#### Response Example
```js
const outlinePoints = [
  [0, 0],
  [10, 5],
  [20, 8],
]
```
```

--------------------------------

### Import styles for perfect-freehand

Source: https://github.com/steveruizok/perfect-freehand/blob/main/_autodocs/index.md

Shows the two valid import styles: default import of getStroke and named imports of functions and types.

```TypeScript
import getStroke from 'perfect-freehand'
import { getStroke, getStrokePoints, getStrokeOutlinePoints } from 'perfect-freehand'
import type { StrokeOptions, StrokePoint, Vec2 } from 'perfect-freehand'
```

--------------------------------

### Create SVG path data

Source: https://github.com/steveruizok/perfect-freehand/blob/main/tutorial/script.md

Construct the path data string by closing the path with a Z command.

```js
const pathData = ['M', first, 'L', rest, 'Z'].join(' ')
```

--------------------------------

### simulatePressure function implementation

Source: https://github.com/steveruizok/perfect-freehand/blob/main/_autodocs/api-reference/internals.md

Simulates pressure for a point based on previous pressure, distance, and size. Returns a value in [0, 1]. Fast movement drives pressure toward the previous value; slow movement reduces it. RATE_OF_PRESSURE_CHANGE is 0.275.

```TypeScript
export function simulatePressure(
  prevPressure: number,
  distance: number,
  size: number
): number {
  // Speed of change - how fast should the pressure be changing?
  const sp = min(1, distance / size)
  // Rate of change - how much of a change is there?
  const rp = min(1, 1 - sp)
  // Accelerate the pressure
  return min(
    1,
    prevPressure + (rp - prevPressure) * (sp * RATE_OF_PRESSURE_CHANGE)
  )
}
```

--------------------------------

### SVG element with full-window inline styles

Source: https://github.com/steveruizok/perfect-freehand/blob/main/tutorial/script.md

The starter HTML includes an SVG element with inline styles that make it take up the whole window.

```html
<svg
  id="svg"
  style="position: fixed; top: 0; left: 0; width: 100%; height: 100%;"
></svg>
```

--------------------------------

### Create curved path data

Source: https://github.com/steveruizok/perfect-freehand/blob/main/tutorial/script.md

Creates path data that connects points by quadratic curves instead of straight lines.

```javascript
const pathData = points
  .slice(1)
  .reduce(
    (acc, point, i, arr) => {
      const next = arr[i + 1]
      if (!next) return acc
      acc.push(point, [(point[0] + next[0]) / 2, (point[1] + next[1]) / 2])
      return acc
    },
    ['M', points[0], 'Q']
  )
  .join(' ')
```

--------------------------------

### Configure stroke size

Source: https://github.com/steveruizok/perfect-freehand/blob/main/tutorial/script.md

Adjust the thickness of the stroke by passing a size property in the options object.

```js
const stroke = getStroke(sample.points, {
  size: 16,
})
```

--------------------------------

### Basic conversion with getStrokePoints

Source: https://github.com/steveruizok/perfect-freehand/blob/main/_autodocs/api-reference/getStrokePoints.md

Converts an array of input points (each with x, y, and pressure) into stroke points. The last element's runningLength gives the total line length. Each stroke point exposes point, pressure, vector, distance, and runningLength.

```ts
import { getStrokePoints } from 'perfect-freehand'

const inputPoints = [
  [0, 0, 0.5],
  [10, 5, 0.6],
  [20, 8, 0.8],
  [30, 12, 0.7],
]

const strokePoints = getStrokePoints(inputPoints)

// Total line length is the last element's runningLength
const totalLength = strokePoints[strokePoints.length - 1].runningLength

// Each entry exposes the values used by the outline stage
for (const sp of strokePoints) {
  console.log(sp.point, sp.pressure, sp.vector, sp.distance, sp.runningLength)
}
```

--------------------------------

### Apply negative thinning

Source: https://github.com/steveruizok/perfect-freehand/blob/main/tutorial/script.md

Set a negative thinning value to decrease the pressure effect on width.

```js
const stroke = getStroke(sample.points, {
  size: 16,
  thinning: -0.9,
})
```

--------------------------------

### Complete basic path rendering

Source: https://github.com/steveruizok/perfect-freehand/blob/main/tutorial/script.md

The full JavaScript code that imports points, creates path data, creates an SVG path element, sets attributes, and appends it to the SVG. Note the stroke-width is 4 in this version.

```javascript
import points from './sample.json'

const pathData = ['M', points[0], 'L', points.slice(1)].join(' ')

const path = document.createElementNS('http://www.w3.org/2000/svg', 'path')

path.setAttribute('d', pathData)
path.setAttribute('fill', 'none')
path.setAttribute('stroke', 'black')
path.setAttribute('stroke-width', '4')

document.getElementById('svg').appendChild(path)
```

--------------------------------

### Set path attributes

Source: https://github.com/steveruizok/perfect-freehand/blob/main/tutorial/script.md

Assigns the path data and basic attributes: fill, stroke, and stroke width.

```javascript
path.setAttribute('d', pathData)
path.setAttribute('fill', 'none')
path.setAttribute('stroke', 'black')
path.setAttribute('stroke-width', '2')
```

--------------------------------

### Specifying outline-only options

Source: https://github.com/steveruizok/perfect-freehand/blob/main/_autodocs/api-reference/getStrokeOutlinePoints.md

Shows how to customize the stroke outline using specific options like thinning, smoothing, and custom easing functions.

```ts
import { getStrokePoints, getStrokeOutlinePoints } from 'perfect-freehand'

const strokePoints = getStrokePoints(inputPoints, { streamline: 0.6 })

const outlinePoints = getStrokeOutlinePoints(strokePoints, {
  size: 24,
  thinning: 0.7,
  smoothing: 0.5,
  easing: (t) => t,
  simulatePressure: false, // use real pressure from the stroke points
  last: true,
  start: {
    cap: false,
    taper: 20,
    easing: (t) => t * (2 - t),
  },
  end: {
    cap: false,
    taper: true, // full-length taper at the end
    easing: (t) => --t * t * t + 1,
  },
})
```

--------------------------------

### Generate a basic stroke

Source: https://github.com/steveruizok/perfect-freehand/blob/main/tutorial/script.md

Create a stroke by passing an array of points into the getStroke function.

```js
const stroke = getStroke(sample.points)
```

--------------------------------

### Create SVG path element

Source: https://github.com/steveruizok/perfect-freehand/blob/main/tutorial/script.md

Creates an SVG path element using the SVG namespace.

```javascript
const path = document.createElementNS('http://www.w3.org/2000/svg', 'path')
```

--------------------------------

### Basic usage of getStroke

Source: https://github.com/steveruizok/perfect-freehand/blob/main/_autodocs/api-reference/getStroke.md

Imports getStroke and computes an outline for a simple array of point tuples. The result is a closed polygon around the input line.

```typescript
import { getStroke } from 'perfect-freehand'

const inputPoints = [
  [0, 0],
  [10, 5],
  [20, 8],
  [30, 12],
  [40, 11],
]

const outlinePoints: [number, number][] = getStroke(inputPoints)
// outlinePoints forms a closed polygon around the input line
```

--------------------------------

### getStroke

Source: https://github.com/steveruizok/perfect-freehand/blob/main/README.md

The main function to generate a stroke outline from an array of input points. It accepts an array of points and an optional options object, returning an array of outline points.

```APIDOC
## getStroke

### Description
Generates a pressure-sensitive stroke outline from an array of input points. The function accepts an array of points (formatted as [x, y, pressure] or { x, y, pressure }) and an optional options object, returning an array of outline points.

### Method
Function call

### Endpoint
Not applicable (SDK function)

### Parameters
#### Input Points
- **points** (Array) - Required - An array of points, each formatted as [x, y, pressure] or { x: number, y: number, pressure: number }.

#### Options (optional)
- **size** (number) - Optional - Default: 8 - The base size (diameter) of the stroke.
- **thinning** (number) - Optional - Default: 0.5 - The effect of pressure on the stroke's size.
- **smoothing** (number) - Optional - Default: 0.5 - How much to soften the stroke's edges.
- **streamline** (number) - Optional - Default: 0.5 - How much to streamline the stroke.
- **simulatePressure** (boolean) - Optional - Default: true - Whether to simulate pressure based on velocity.
- **easing** (function) - Optional - Default: t => t - An easing function to apply to each point's pressure.
- **start** (object) - Optional - Tapering options for the start of the line.
- **end** (object) - Optional - Tapering options for the end of the line.
- **last** (boolean) - Optional - Default: true - Whether the stroke is complete.

#### start and end options
- **cap** (boolean) - Optional - Default: true - Whether to draw a cap.
- **taper** (number or boolean) - Optional - Default: 0 - The distance to taper. If set to true, the taper will be the total length of the stroke.
- **easing** (function) - Optional - Default: t => t - An easing function for the tapering effect.

### Request Example
```js
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,
  },
})
```

### Response
#### Success Response
Returns an array of outline points (each as [x, y]).

#### Response Example
Not provided in source.
```

--------------------------------

### getStroke(points, options)

Source: https://github.com/steveruizok/perfect-freehand/blob/main/_autodocs/api-reference/getStroke.md

The primary function of the perfect-freehand package. It takes an array of points and an optional options object, and returns an array of 2D vectors representing the stroke outline.

```APIDOC
## getStroke(points, options)

### Description
The primary function of the perfect-freehand package. It takes an array of points and an optional options object, and returns an array of 2D vectors representing the stroke outline.

### Signature
```ts
export function getStroke(
  points: (number[] | { x: number; y: number; pressure?: number })[],
  options: StrokeOptions = {} as StrokeOptions
): Vec2[]
```

### Parameters
- **points** ((number[] | { x: number; y: number; pressure?: number })[]) - Required - An array of points, formatted either as [x, y, pressure] tuples or as { x, y, pressure? } objects. Pressure is optional in both forms and defaults to 0.5 (per-point default is 0.25 for the first point). Extra tuple members beyond index 2 are ignored by the algorithm.
- **options** (StrokeOptions) - Optional - An options object. Each property is optional; defaults are applied inside the two pipeline stages.

### Return Value
- **Vec2[]** - An array of 2D vectors representing the stroke outline.

### Types
```ts
type Vec2 = [number, number]

interface StrokeOptions {
  size?: number
  thinning?: number
  smoothing?: number
  streamline?: number
  easing?: (pressure: number) => number
  simulatePressure?: boolean
  start?: {
    cap?: boolean
    taper?: number | boolean
    easing?: (distance: number) => number
  }
  end?: {
    cap?: boolean
    taper?: number | boolean
    easing?: (distance: number) => number
  }
  last?: boolean
}
```
```

--------------------------------

### getStrokePoints Options

Source: https://github.com/steveruizok/perfect-freehand/blob/main/_autodocs/api-reference/getStrokePoints.md

Describes the options consumed by the getStrokePoints function, including streamline, size, and last, with their defaults and effects.

```APIDOC
## getStrokePoints Options

### Description
Options that affect the behavior of the getStrokePoints function. The defaults are streamline = 0.5, size = 16, last = false.

### Options

| Option | Default | Effect |
|--------|---------|--------|
| streamline | 0.5 | Interpolation factor between consecutive points. The per-step interpolation t is computed as t = MIN_STREAMLINE_T + (1 - streamline) * STREAMLINE_T_RANGE (0.15 + (1 - streamline) * 0.85). Higher streamline moves new points closer to the previous point (smoother); streamline: 0 gives t = 1 (no interpolation). |
| size | 16 | The base size (diameter) of the stroke in pixels. Used for two purposes here: the minimum-length filter (points are skipped until runningLength >= size) and as the spacing for the interpolated 2-point case. |
| last | false | Whether the points form a completed stroke. When true, the final output point is the actual last input point; when false, it is an interpolated point that lands slightly before the last input ("slightly behind it"). |

### Source Defaults
```ts
const { streamline = 0.5, size = 16, last: isComplete = false } = options
```
```

--------------------------------

### Customizing stroke appearance

Source: https://github.com/steveruizok/perfect-freehand/blob/main/README.md

Pass an options object as the second parameter to getStroke to customize the stroke shape.

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

--------------------------------

### Configure smoothing

Source: https://github.com/steveruizok/perfect-freehand/blob/main/tutorial/script.md

Control the density of points along the polygon edges to adjust jaggedness.

```js
const stroke = getStroke(sample.points, {
  size: 16,
  thinning: 0.5,
  streamline: 0.5,
  smoothing: 0,
})
```

```js
const stroke = getStroke(sample.points, {
  size: 16,
  thinning: 0.5,
  streamline: 0.5,
  smoothing: 1,
})
```

--------------------------------

### getStroke function implementation

Source: https://github.com/steveruizok/perfect-freehand/blob/main/_autodocs/api-reference/getStroke.md

The complete implementation of getStroke, which is a thin wrapper that calls getStrokeOutlinePoints(getStrokePoints(points, options), options).

```typescript
export function getStroke(
  points: (number[] | { x: number; y: number; pressure?: number })[],
  options: StrokeOptions = {} as StrokeOptions
): Vec2[] {
  return getStrokeOutlinePoints(getStrokePoints(points, options), options)
}
```

--------------------------------

### Generate quadratic curve path data

Source: https://github.com/steveruizok/perfect-freehand/blob/main/tutorial/script.md

Use a reduce function to convert stroke points into a series of quadratic curves for a smoother SVG path.

```js
const pathData = stroke
  .reduce(
    (acc, [x0, y0], i, arr) => {
      if (i === arr.length - 1) return acc
      const [x1, y1] = arr[i + 1]
      return acc.concat(` ${x0},${y0} ${(x0 + x1) / 2},${(y0 + y1) / 2}`)
    },
    ['M ', `${stroke[0][0]},${stroke[0][1]}`, ' Q']
  )
  .concat('Z')
  .join('')
```
Tokens:
Raw