cdgugler/shatter.js

JavaScript Image Shattering

Shatter.js

Shatter.js provides simple image shattering by dividing an image (DOM Image element) by an array of coordinates.

It also includes a generator, to generate a random set of coordinates based on a Voronoi diagram. The resulting array of images represents a 'shattered' version of the original image.

Install

npm install @cdgugler/shatter

Usage

Shatter

import { Shatter } from '@cdgugler/shatter';
const shattered = new Shatter('/img/square.png');

// Set up an array of 'pieces'
// Each piece is an array of [x, y] coordinates
shattered.setPieces([
    [
        [0, 0],
        [50, 0],
        [50, 100],
        [0, 100],
    ],
    [
        [50, 0],
        [100, 0],
        [100, 100],
        [50, 100],
    ],
]);

// .shatter() returns a Promise due to the
// image.src being asynchronous
let result = await shattered.shatter();

// result is an array of image pieces consisting of
// { image: DOMImageElement, x: xOffset, y: yOffset }
result.forEach((res, i) => {
    container.appendChild(res.image);
});

Examples

To run examples, clone repository and run:

npm install
npm run buildexample
npx http-server examples/

API

Constructor

new Shatter(url) - optional url of image to load. If not set, must use .setImage(image).

Methods

Name	Description
setImage(image)	Provide a DOM Image element to shatter. Will override any image loaded from constructor.
setPieces(pieces)	Provide an array of segments/pieces to split the image into. Each 'piece' is an array of [x,y] coordinates.
shatter()	Split the image using the provided coordinates. Returns a Promise that resolves with an array of 'shattered' objects containing the resulting images and additional data

Shattered Object

Shatter.shatter() returns an array of objects that contain images and x, y coordinates for each piece.

• result[i].image - The image segment as a DOM Image element
• result[i].x - X-offset
• result[i].y - Y-offset

Generators

You might not want to manually come up with all the pieces with their individual x & y coordinates to shatter an image.

Included is one generator, which uses d3-voronoi behind the scenes to split an image into somewhat random pieces.

To use the generator, call it with an options object consisting of the height and width of the image, and the number of pieces to generate.

import { VoronoiPieces } from '@cdgugler/shatter';

const voropieces = VoronoiPieces({
    height: original.height,
    width: original.width,
    numPieces: num,
});

Then pass the result into the .setPieces() method on Shatter.

Tests

npm run test - run unit tests

npm run e2e - run end to end tests

Live Demo

See my post about the project.

License

• MIT license

shatter.js's Issues

Ability to select number of segments to split image into in Phaser example.

Add text input.

Button to clear all shattered objects from DOM example

Add a button, simple as that.

No documentation

Ability to select number of segments to split image into in DOM example.

Add text input for DOM example.

Join the pieces back?

Is there any way we can put the pieces back?

Does not work reliably (or at all) in Firefox and IE 11

Because of this reason: http://stackoverflow.com/questions/4776670/should-setting-an-image-src-to-data-url-be-available-immediately

shatter.js sets the src and expects the image to be ready to use directly afterwards. That's not the case, yielding blank images.

I've not found a quick hack to keep the synchronous way of shatter.js, the only working solution to this seems to be to use callbacks as described in the playing it save part of the stackoverflow post.

examples broken?

Hi, I was looking to use shatter.js for a project, but I can't tell from the examples on the site if it fits my need. Can you take a look at the site and confirm that the interactive examples are working as expected? When I go to this page, I am unable to type anything in the "number of pieces" input box for unknown reasons-- so I used the dev console to change the input box's value to 1 programmatically and clicked "Create another," but then the page starts glitching and jumping without any other apparent result. Likewise, the Phase Example just links to a black box.

Am I doing something wrong?

Thanks.

Upgrade Phaser in Phaser example.

Empty shatter images on iOS

img src of resulting image is empty on iOs devices

Add DOM Example

Add particle emitter containing split image to Phaser Example

Add debug mode

Should be able to visibly see how image will be split, or was split.
Add to examples.

Move helper methods to prototype

Shatter on click (DOM example)

Add canvas example