Warp Grid

This package allows you to create a complex grid and distort it, taking the concept of a Coons patch and applying it to a grid system, meaning the grid is not bounded by four straight lines, but by four cubic Bézier curves. This allows you to create some very strange an interesting grids that would be very difficult to generate with traditional graphics software.

There is an editor which allows you to generate and manipulate a grid, giving access to all the configuration available.

The package provides a set of powerful configuration options to define the grid including variable- or fixed-width/height columns and gutters, control over distribution of rows and columns using Bézier easing, and access to different types of interpolation, as well as the option to provide your own interpolation.

Its API gives you access to information about the grid's metrics: its bounds, rows, columns, gutters and cells. It is designed to be recursive, so that the metrics for an individual grid-cell can be used as bounds for a completely different grid, allowing for nested grids.

This package does not handle any rendering itself, but provides you with all the information about the grid that you need to render the grid using SVG, Canvas or anything else you like.

If you just want to generate a coons-patch, you can use the lower level package coons-patch.

Install package

pnpm add warp-grid
# or
npm add warp-grid
# or
yarn add warp-grid

Package Documentation (TypeDoc generated).

This package is written in TypeScript and exports its types.

Quick-start

The basic workflow is that you supply bounds representing the edges of boundaries of your grid, and a grid configuration object describing the grid you'd like to map onto those bounds. In return you receive an object with information about the grid, and an API to allow you to get information about the grid. This means no expensive calculations are done up front, and calculations are only performed as and when you need them.

import warpGrid from 'warp-grid'

// Define bounding (cubic Bézier) curves for the patch
const boundingCurves = {
  top: {
    startPoint: { x: 0, y: 0 },
    endPoint: { x: 100, y: 0 },
    controlPoint1: { x: 10, y: -10 },
    controlPoint2: { x: 90, y: -10 },
  },
  bottom: {
    startPoint: { x: 0, y: 100 },
    endPoint: { x: 100, y: 100 },
    controlPoint1: { x: -10, y: 110 },
    controlPoint2: { x: 110, y: 110 },
  },
  left: {
    startPoint: { x: 0, y: 0 },
    endPoint: { x: 0, y: 100 },
    controlPoint1: { x: -10, y: -10 },
    controlPoint2: { x: -10, y: 110 },
  },
  right: {
    startPoint: { x: 100, y: 0 },
    endPoint: { x: 100, y: 100 },
    controlPoint1: { x: 110, y: -10 },
    controlPoint2: { x: 110, y: 110 },
  },
}

// Define a 10 x 5 grid with gutters
const gridDefinition = {
  columns: 10
  rows: 5,
  gutters: 2
}

const grid = warpGrid(
  boundingCurves,
  gridDefinition
)

// Get a point on the patch at the provided horizontal and vertical ratios (0–1 inclusive)
const point = warpGrid.getPoint(0.5, 0.75)

// Get an Array containing all the curves along the x-axis.
const curvesXAxis = warpGrid.getLinesXAxis()

// Get an Array containing all the curves along the y-axis.
const curvesXAxis = warpGrid.getLinesYAxis()

// Get an Array containing all the curves along the both the x- and y-axis.
const curves = warpGrid.getLines()

// Get an array of points representing every point on the grid where lines intersect.
const intersections = warpGrid.getIntersections()

// Get the bounds for the grid-square at the supplied coordinates
const bounds = warpGrid.getCellBounds(3, 8)

// Get an array containing the bounds for every grid-square
const allBounds = getAllCellBounds()

Usage

Primitives

There are a number of data types that are used by the package to describe aspects of the grid:

Points look like this:

const point = {
  x: 34,
  y: 44
}

All curves are represented by cubic Bézier curves:

const curve = {
  startPoint: {
    x: 0,
    y: 0
  },
  controlPoint1: {
    x: 0,
    y: 33
  },
  controlPoint2: {
    x: 0,
    y: 66
  },
  endPoint: {
    x: 0,
    y: 100
  }
}

Bounding curves look like this, where each item is curve.

const boundingCurves = {
  top: { … },
  bottom: { … },
  left: { … },
  right: { … }
}

Bounding curves

To generate a grid you must provide a set of four bounding curves (top, left, bottom and right) in the form of four cubic Bézier curves. A cubic Bézier curve describes a straight-line or curve using a start point (startPoint), an end point (endPoint) and two other control points(controlPoint1 and controlPoint2). Each point has an x and y coordinate.

At minimum you must supply start and end points for each curve. If you do not supply controlPoint1 it will be set to the same coordinates as the start point, and if you do not supply controlPoint2 it will be set to the same coordinates as the end point. Setting both control points to the same values as the start and end point will result in a straight line. You also need to ensure that the four curves meet at the corners.

You will probably be expecting the end of each curve to be the start of the next, however in keeping with the math involved in generating a coons-patch this is not the case. The top and bottom curves run left to right, and left and right curves run top to bottom, so this means that:

• the startPoint of the top curve must share the same coordinates with the startPoint of the left curve.
• the endPoint of the top curve must share the same coordinates with the startPoint of the right curve.
• the startPoint of the bottom curve must share the same coordinates with the end point of the left curve.
• the endPoint of the bottom curve must share the same coordinates with the endPoint of the right curve.

         top
      -------->
left |         | right
     ↓ ------> ↓
       bottom

Note that when you are getting cell bounds back from the API, both getCellBounds and getAllCellBounds accept a config object which has a makeBoundsCurvesSequential key. If this is set to true, the order of the bounding curves is made sequential:

         top
     ↑ ------->
left |         | right
      <------- ↓
       bottom

Grid definition

The grid definition is an object describing the grid you are modelling. It will be merged with a set of defaults.

Before going any further it is important to understand how the grid handles columns, rows and gutters. Individual step values can either be numbers, in which case the values are treated as relative values to each other, or absolute values (in the form of pixel-strings with the format '{number}px', for example '48px'). The grid calculations will favour gutters, rows and columns with absolute values, with steps and gutters with relative values sharing the remaining available space. It is important to remember that the length of each side of the grid is independent. The grid will first calculate the length of each side, allow space for all the steps and gutters with absolute values, then share out the remaining space amongst the other steps and gutters. This allows for some pretty interesting layouts.

Under the hood, gutters are just steps with isGutter set to true. By using objects for step values you can control individual gutter sizes (see below),

Columns and Rows

columns and rows define the number of columns and rows in the grid. A grid has a minimum of one row and one column. The generic name for columns and rows used in the following docs and in the codebase is steps.

These fields can be one of the following:

1. An integer, in which case that integer will represent the number of columns or rows. For example columns: 2, will result in a grid with two columns.

2. An array of integers or pixel strings or objects, in which case the steps will each have those absolute or relative value, or if objects will have the absolute or relative value provided by the object's value property. To tell the grid to treat an item as a gutter, set isGutter to true. You can mix integers, string and objects.

{
  columns: [
    2,
    `30px`,
    1
  ],
  rows: [
    1,
    `10px`,
    {
      value: 2,
      isGutter: true,
    },
    5,
    5
  ],
  …
}

Gutters

gutter describes the width of horizontal gutters and the height of vertical gutters. Gutters are the spaces between the grid cells. If gutter is a number, it describes both horizontal and vertical gutters. If it is an array of two numbers, the first number describes the horizontal gutter and the second number describes the vertical gutter. Like columns and rows, gutters can either be relative or absolute pixel-numbers, for example: 3, or 3px.

As outlined above, there is an additional way to add gutters without using the gutters property. You can add them to the rows or columns arrays, using an object with a value property, but also adding an isGutter property set to true: ({ value: 2. isGutter: true}). This allows you to define gutters of different widths/heights in the same way you can define columns or rows of different widths/heights.

{
  gutter: [
    2,
    `10px`
  ],
  …
}

You can add multiple steps with isGutter set to true, and you can have these beside one-another if you want. If you use steps with isGutter set to true alongside the gutter property, the gutter property will act as a default, and gutters of that value will be added between any steps that do not already have at least one gutter between them. They will have no effect on steps with isGutter set to true.

### Interpolations

A lot of the work done by the package involves interpolation. The grid also supports configuration params that change how it performs these interpolations.

interpolationStrategy

interpolationStrategy changes the algorithm used to interpolate the position of points along a curve. These algorithms are used in calculating the location of points within the bounds. This value can be either a string, a function, or a tuple of two functions.

If it's a string it can be either even (the default) or linear. linear is a simple form of interpolation that results in a distribution that is affected by the amount of curvature of the bounds. even uses a more complex approach and usually results in more evenly distributed results. However this comes at the cost of performance.

Alternatively a single factory function, or a tuple of two factory functions (one for each axis) can be supplied.

{
  lineStrategy: `even`,
  …
}

These functions comprise of a factory function that accepts a configuration object and returns an interpolation function. The factory function is called internally using config from the grid definition object.

Factory functions for both linear and even interpolation are exported by this package:

• interpolatePointOnCurveEvenlySpacedFactory
• interpolatePointOnCurveLinearFactory

If you use your own interpolation factory function it should have the following signature.

(config: {precision: number, bezierEasing: BézierEasing}) => (t: number, curve: Curve): Point

##### Factory

• config is an object with a precision key that can be used to control the precision of interpolation, and bezierEasing which is an object with bezierEasing values for modifying distribution for each axis. If your interpolation function doesn't require any configuration you can just use an empty function.

Interpolation function

• t is the ratio along the axis (0–1 inclusive).
• curve is a cubic Bézier curve along which the interpolation will be used.

lineStrategy

lineStrategy controls how the grid lines are interpolated and can either be straightLines or curves. The lines returned from getCurves, getCurvesXAxis and getCurvesYAxis, and the bounds returned from getCellBounds and getAllCellBounds are always represented by cubic Bézier curves, however if the lineStrategy is straightLines (the default), the calculations are significantly simplified and all lines will be straight (controlPoint1 will be the same as the startPoint, and controlPoint2 will be the same as endPoint) For more accurate calculations choose curves which will draw curved cubic Bézier curves at the expense of performance.

{
  lineStrategy: `curves`,
  …
}

precision

If you choose to use a line strategy of even, this parameter controls how precise the interpolation is. Higher values are more memory-intensive but more accurate. The default value is 20. With linear this will have no effect.

{
  precision: 5
  …
}

bezierEasing

The grid provides a very powerful way of controlling the distribution of lines along each access using bezierEasing. Bézier easing is widely used for animation as a way of providing easing to a changing value. Instead of applying easing to an animation, here it is applied to the interpolation of points along an axis. bezierEasing is implemented internally by first creating an easing function, and then passing a value (in the range of 0–1) to it. The easing function requires four values (each from 0–1). The first two values represent the position of the first control point (x, y) and the last two values represent the position of the second control point. So the value for bezierEasing will look like this:

{
  bezierEasing: {
    u: [0, 0, 1, 1]
    v: [0, 0, 1, 1]
  }
  …
}

The easiest way to understand what effect the different values have is to play with the editor.

Here is a full example of a grid definition:

{
  columns: 8,
  rows: [10, 5, 20, 5, 10],
  gutters: [5, 3],
  interpolationStrategy: `even`,
  lineStrategy: 'curves',
  precision: 30,
  bezierEasing: {
    u: [0, 0.5, 1, 1]
    v: [0, 0, 0.3, 1]
  }
}

Return value

The return value is a warp grid object representing the grid and providing an API to interrogate it.

{
  model: {
    columns,
    rows,
    boundingCurves
  },
  getPoint,
  getLinesXAxis,
  getLinesYAxis,
  getLines,
  getIntersections,
  getCurves,
  getCellBounds,
  getAllCellBounds,
}

Model object

model provides access to the resolved configuration data that was used to generate the patch. The configuration data is not the same as the data you passed in, but is instead the internal representation of that data.

• columns contains an array of column values. This will always be made up of objects, regardless of how you supplied them.
• rows contains an array of row values. This will always be made up of objects, regardless of how you supplied them.
• boundingCurves contains the bounding curves object that was passed in.

API

Important note

One of the powerful features of this package is that a grid cell can itself be used as bounds for another grid. To achieve this, the bounding curves returned from getCellBounds and getAllCellBounds follow the same pattern as the bounding curves used to define the grid, meaning the top and bottom curves run left-to-right and the left and right curves run top-to-bottom.

• getPoint(u, v) returns the point on the grid at the supplied u and v ratios.Both u and v should be a number from 0–1 inclusive. For example, a u of 0 and a v of 0 would return a point in the top left corner. An u of 1and a v of 1 would return a point in the bottom right corner (remember that the top and bottom boundary curves run from left-to-right and the left and right boundary curves run from top to bottom).

• getLinesXAxis() returns an array representing all the curves for each step along the x-axis. This includes curves for all left and right edges.

• getLinesYAxis() returns an array representing all the curves for each step along the y-axis. This includes curves for all top and bottom edges.

• getLines() returns an object with xAxis and yAxis keys, each of which contains an array representing all the curves for each step along that axis.

• getIntersections() returns an array of points, one for every point at which an x-axis line intersects with a y-axis line.

• getCellBounds(rowIdx, columnIdx) returns a set of bounding curves for the cell at the supplied row and column. Row and column are zero-based. You can pass an optional config object as the third argument. See the docs for more information.

• getAllCellBounds() returns an array of bounding curves for all the cells in the grid. See the docs for additional config parameters. You can pass an optional config object as the third argument. See the docs for more information.

Dependencies

This project has four dependencies:

• coons-patch to calculate points on a surface defined by Bézier curves.
• fast-memoize for memoization.
• bezier-easing for creating Bézier-easing functions.
• matrix-js for matrix math

## Thanks

Thanks to pomax for his help (and code) for curve fitting (which is much more complex than it might seem). His A Primer on Bézier Curves is a thing of wonder.

Maintenance

Install

pnpm install

Build

pnpm run build # Build once
pnpm run build-watch # Build and watch for changes

Preview build

pnpm run preview

Generate docs

pnpm run docs

View the generated docs

pnpm run docs-view

Run unit tests

Unit tests use vitest.

pnpm run test # Run tests once
pnpm run test-watch # Run tests and watch for changes
pnpm run test-coverage # Run tests and output a coverage report
pnpm run test-snapshot # Regenerate snapshots

Lint

pnpm run lint-prettier
pnpm run lint-eslint

Linking

To link into the local version of coons-patch for local testing run:

pnpm run link

To unlink (and install the package from npm):

pnpm run unlink

Release

Releases are via semantic-release and executed on CI via Github actions.

The following steps are run as part of the actions pipeline

• Code is linted
• Unit tests are run
• TypeScript is compiled to JavaScript
• Package is released (if previous stages all pass)