Flubber

https://veltman.github.io/flubber/
Admin
Flubber provides best-guess methods for smoothly interpolating between 2-D shapes, enabling smooth...
Tokens:3,680
Snippets:33
Trust Score:9.7
Update:6 months ago
Show doc for...
Tokens:
Raw
### Install Flubber via NPM

Source: https://veltman.github.io/flubber

Install Flubber using NPM for use in Node.js projects or modern JavaScript build systems.

```bash
npm install flubber
```

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

### Flubber interpolate() Usage

Source: https://veltman.github.io/flubber

Demonstrates how to use the `flubber.interpolate` function to get shape interpolators.

```javascript
var interpolator = flubber.interpolate(triangle, octagon);

interpolator(0); // returns an SVG triangle path string
interpolator(0.5); // returns something halfway between the triangle and the octagon
interpolator(1); // returns an SVG octagon path string
```

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

### Import Flubber in ES6

Source: https://veltman.github.io/flubber

Import the `interpolate` function from Flubber for use in ES6 projects.

```javascript
import { interpolate } from "flubber"
```

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

### Import Flubber in Node.js (CommonJS)

Source: https://veltman.github.io/flubber

Require the Flubber library in Node.js projects using the CommonJS module system.

```javascript
var flubber = require("flubber"); // Node classic
```

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

### flubber.fromRect

Source: https://veltman.github.io/flubber

Generates an interpolator function to smoothly transition a rectangle into another shape.

```APIDOC
## flubber.fromRect(x, y, width, height, toShape[, options])

### Description
Generates an interpolator function to smoothly transform a rectangle (defined by its upper-left corner `[x, y]`, `width`, and `height`) into a specified `toShape`.

### Method
`flubber.fromRect`

### Parameters
#### Path Parameters
- **x** (number) - Required - The x-coordinate of the rectangle's upper-left corner.
- **y** (number) - Required - The y-coordinate of the rectangle's upper-left corner.
- **width** (number) - Required - The width of the rectangle.
- **height** (number) - Required - The height of the rectangle.
- **toShape** (string | Array<Array<number>>) - Required - The ending shape, either an SVG path string or an array of [x, y] points.
- **options** (object) - Optional - Configuration options, same as `flubber.interpolate`.

### Request Example
```javascript
var interpolator = flubber.fromRect(10, 50, 100, 200, "M200,200 L300,200 L250,300Z");

// Get the shape halfway between the rectangle and the triangle
var midShape = interpolator(0.5);
```

### Response
Returns a function that accepts a single argument `t` (a number between 0 and 1) and returns the interpolated shape, transitioning from a rectangle to `toShape`.
```

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

### flubber.toPathString

Source: https://veltman.github.io/flubber

Converts an array of points to an SVG path string.

```APIDOC
## flubber.toPathString(ring)

### Description
A helper function for converting an array of points to an SVG path string.
```

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

### Convert points to SVG path string

Source: https://veltman.github.io/flubber

Converts an array of coordinate points into a standard SVG path string.

```javascript
flubber.toPathString([[1, 1], [2, 1], [1.5, 2]]);
// Returns "M1,1L2,1L1.5,2Z"
```

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

### flubber.fromCircle

Source: https://veltman.github.io/flubber

Generates an interpolator function to smoothly transition a circle into another shape.

```APIDOC
## flubber.fromCircle(x, y, r, toShape[, options])

### Description
Generates an interpolator function to smoothly transform a circle (defined by its center `[x, y]` and radius `r`) into a specified `toShape`.

### Method
`flubber.fromCircle`

### Parameters
#### Path Parameters
- **x** (number) - Required - The x-coordinate of the circle's center.
- **y** (number) - Required - The y-coordinate of the circle's center.
- **r** (number) - Required - The radius of the circle.
- **toShape** (string | Array<Array<number>>) - Required - The ending shape, either an SVG path string or an array of [x, y] points.
- **options** (object) - Optional - Configuration options, same as `flubber.interpolate`.

### Request Example
```javascript
var interpolator = flubber.fromCircle(100, 100, 50, "M200,200 L300,200 L250,300Z");

// Get the shape halfway between the circle and the triangle
var midShape = interpolator(0.5);
```

### Response
Returns a function that accepts a single argument `t` (a number between 0 and 1) and returns the interpolated shape, transitioning from a circle to `toShape`.
```

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

### flubber.combine

Source: https://veltman.github.io/flubber

Interpolates between multiple shapes and a single shape.

```APIDOC
## flubber.combine(fromShapeList, toShape[, options])

### Description
Reverse of the separate() method; interpolates from multiple shapes into a single shape.
```

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

### Animate Shape with requestAnimationFrame

Source: https://veltman.github.io/flubber

Animate shape changes using `requestAnimationFrame` and Flubber's interpolator function without D3.

```javascript
// Mixing and matching input types is OK
var triangle = "M1,0 L2,2 L0,2 Z",
    pentagon = [[0, 0], [2, 0], [2, 1], [1, 2], [0, 1]];

var interpolator = flubber.interpolate(triangle, pentagon);

requestAnimationFrame(draw);

function draw(time) {
    var t = howFarAlongTheAnimationIsOnAScaleOfZeroToOne(time);
    myPathElement.setAttribute("d", interpolator(t));
    if (t < 1) {
        requestAnimationFrame(draw);
    }
}
```

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

### flubber.toRect

Source: https://veltman.github.io/flubber

Generates an interpolator function to smoothly transition a shape into a rectangle.

```APIDOC
## flubber.toRect(fromShape, x, y, width, height[, options])

### Description
Generates an interpolator function to smoothly transform a given shape into a rectangle defined by its upper-left corner `[x, y]` and its `width` and `height`.

### Method
`flubber.toRect`

### Parameters
#### Path Parameters
- **fromShape** (string | Array<Array<number>>) - Required - The starting shape, either an SVG path string or an array of [x, y] points.
- **x** (number) - Required - The x-coordinate of the rectangle's upper-left corner.
- **y** (number) - Required - The y-coordinate of the rectangle's upper-left corner.
- **width** (number) - Required - The width of the rectangle.
- **height** (number) - Required - The height of the rectangle.
- **options** (object) - Optional - Configuration options, same as `flubber.interpolate`.

### Request Example
```javascript
var triangle = "M100,100 L200,100 L150,200Z";

var interpolator = flubber.toRect(triangle, 10, 50, 100, 200);

// Get the shape halfway between the triangle and the rectangle
var midShape = interpolator(0.5);
```

### Response
Returns a function that accepts a single argument `t` (a number between 0 and 1) and returns the interpolated shape, transitioning from `fromShape` to a rectangle.
```

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

### Define Shapes as Path String and Ring

Source: https://veltman.github.io/flubber

Flubber accepts shapes as either SVG path strings or arrays of [x, y] points (rings).

```javascript
"M100,100 L200,100 L150,200Z" // A triangle as a path string
```

```javascript
[[100, 100], [200, 100], [150, 200]] // A triangle as a ring
```

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

### flubber.splitPathString

Source: https://veltman.github.io/flubber

Splits a complex SVG path string into an array of single-shape path strings.

```APIDOC
## flubber.splitPathString(pathString)

### Description
A helper function for splitting an SVG path string that might contain multiple shapes into an array of one-shape path strings.
```

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

### flubber.toCircle

Source: https://veltman.github.io/flubber

Generates an interpolator function to smoothly transition a shape into a circle.

```APIDOC
## flubber.toCircle(fromShape, x, y, r[, options])

### Description
Generates an interpolator function to smoothly transform a given shape into a circle centered at `[x, y]` with radius `r`.

### Method
`flubber.toCircle`

### Parameters
#### Path Parameters
- **fromShape** (string | Array<Array<number>>) - Required - The starting shape, either an SVG path string or an array of [x, y] points.
- **x** (number) - Required - The x-coordinate of the circle's center.
- **y** (number) - Required - The y-coordinate of the circle's center.
- **r** (number) - Required - The radius of the circle.
- **options** (object) - Optional - Configuration options, same as `flubber.interpolate`.

### Request Example
```javascript
var triangle = "M100,100 L200,100 L150,200Z";

var interpolator = flubber.toCircle(triangle, 100, 100, 50);

// Get the shape halfway between the triangle and the circle
var midShape = interpolator(0.5);
```

### Response
Returns a function that accepts a single argument `t` (a number between 0 and 1) and returns the interpolated shape, transitioning from `fromShape` to a circle.
```

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

### Animate Shape with D3

Source: https://veltman.github.io/flubber

Use Flubber's `interpolate` function with D3 transitions to animate SVG path data.

```javascript
var triangle = [[1, 0], [2, 2], [0, 2]],
    pentagon = [[0, 0], [2, 0], [2, 1], [1, 2], [0, 1]];

var interpolator = flubber.interpolate(triangle, pentagon);

d3.select("path")
    .transition()
    .attrTween("d", function(){ return interpolator; });
```

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

### Separate single shape into a combined interpolator

Source: https://veltman.github.io/flubber

Setting the single option to true returns a single interpolator function that combines shapes into one path.

```javascript
// returns a single interpolator function
var combinedInterpolator = flubber.separate(triangle, [square, otherSquare], { single: true });

// This one path element will be two squares at the end
d3.select("path")
    .transition()
    .attrTween("d", function() { return combinedInterpolator; });
```

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

### flubber.interpolate

Source: https://veltman.github.io/flubber

Generates an interpolator function to smoothly transition between two shapes. Shapes can be SVG path strings or arrays of [x, y] points.

```APIDOC
## flubber.interpolate(fromShape, toShape [, options])

### Description
Generates an interpolator function that takes a value `t` from 0 to 1 and returns the in-between shape. This is useful for animating between two arbitrary shapes.

### Method
`flubber.interpolate`

### Parameters
#### Path Parameters
- **fromShape** (string | Array<Array<number>>) - Required - The starting shape, either an SVG path string or an array of [x, y] points.
- **toShape** (string | Array<Array<number>>) - Required - The ending shape, either an SVG path string or an array of [x, y] points.
- **options** (object) - Optional - Configuration options for the interpolation.
  - **string** (boolean) - Optional - Whether to output results as an SVG path string or an array of points. Defaults to `true`.
  - **maxSegmentLength** (number | boolean) - Optional - Controls the smoothness of the animation. Lower values result in smoother animations at the cost of performance. Set to `false` or `Infinity` for no smoothing. Defaults to `10`.

### Request Example
```javascript
var triangle = "M100,100 L200,100 L150,200Z";
var pentagon = [[0, 0], [2, 0], [2, 1], [1, 2], [0, 1]];

var interpolator = flubber.interpolate(triangle, pentagon);

// Get the shape at 50% of the animation
var midShape = interpolator(0.5);
```

### Response
Returns a function that accepts a single argument `t` (a number between 0 and 1) and returns the interpolated shape.
```

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

### Flubber toCircle() Usage

Source: https://veltman.github.io/flubber

Use `flubber.toCircle` to create an interpolator that transforms a shape into a circle.

```javascript
var interpolator = flubber.toCircle(triangle, 100, 100, 10);

interpolator(0); // returns an SVG triangle path string
interpolator(0.5); // returns something halfway between the triangle and the circle
interpolator(1); // returns a circle path string centered at 100, 100 with a radius of 10
```

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

### flubber.interpolateAll

Source: https://veltman.github.io/flubber

Interpolates between two arrays of shapes of the same length.

```APIDOC
## flubber.interpolateAll(fromShapeList, toShapeList[, options])

### Description
Expects two arrays of shapes of the same length and matches them up in order.
```

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

### flubber.separate

Source: https://veltman.github.io/flubber

Interpolates between a single shape and multiple shapes by breaking the source shape into pieces.

```APIDOC
## flubber.separate(fromShape, toShapeList[, options])

### Description
Interpolates between a single shape and multiple shapes. It breaks the source shape into pieces to animate between the two sets.

### Parameters
- **fromShape** (string/ring) - Required - A ring or SVG path string.
- **toShapeList** (array) - Required - An array of rings or SVG path strings.
- **options** (object) - Optional - Same as interpolate() options, with an additional 'single' boolean property (defaults to false).
```

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

### Separate single shape into multiple interpolators

Source: https://veltman.github.io/flubber

Use flubber.separate to break a single shape into multiple pieces for animation. Returns an array of interpolator functions.

```javascript
// returns an array of two interpolator functions
var interpolators = flubber.separate(triangle, [square, otherSquare]);

d3.selectAll("path")
    .data(interpolators)
    .transition()
    .attrTween("d", function(interpolator) { return interpolator; });
```

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

### Split SVG path string into individual shapes

Source: https://veltman.github.io/flubber

Splits a complex SVG path string containing multiple shapes into an array of individual path strings.

```javascript
flubber.splitPathString("M1,1 L2,1 L1.5,2Z M3,3 L4,3 L3.5,4 Z");
// Returns ["M1,1 L2,1 L1.5,2Z", "M3,3 L4,3 L3.5,4 Z"]
```

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

### Flubber toRect() Usage

Source: https://veltman.github.io/flubber

Use `flubber.toRect` to create an interpolator that transforms a shape into a rectangle.

```javascript
var interpolator = flubber.toRect(triangle, 10, 50, 100, 200);

interpolator(0); // returns an SVG triangle path string
interpolator(0.5); // returns something halfway between the triangle and the rectangle
interpolator(1); // returns a rectangle path string from [10, 50] in the upper left to [110, 250] in the lower right
```
Tokens:
Raw