Add confetti.shapesFromImage method to create confetti from image source

README.md

@@ -123,6 +123,62 @@ confetti({
 });
 ```
 
+### `confetti.shapesFromImage({ src, scalar?, sprites? })` → `Promise<Array<Shape>>`
+
+You can also create confetti from images! The same caveats apply as for `confetti.shapeFromText`.
+
+The options for this method are:
+- `options` _`Object`_:
+  - `src` _`String`_: the URL of the image to render. This must be "origin-clean", which means you may get problems if the image is hosted at a different origin. If the resource can be fetched cross-origin, you can do something like `URL.createObjectURL(await (await fetch(src)).blob())`, or if all else fails, data URIs will always work.
+  - `scalar` _`Number, optional, default: 1`_: a scale value relative to the default size of 10px. It should typically match the `scalar` value in the confetti options. If the source image is not a square, this will apply to the width rather than the height (e.g. rendering a 50x20 image at a scalar of `2` will render a 20x8 confetti). If multiple sprites with different widths are used, the resulting width will be the width of the largest sprite.
+  - `sprites` _`Array<Object>, optional`_. If present, this will be used to cut out individual regions from the image; if omitted, the entire image will be used. Each element of `sprites` has the following properties:
+    - `x` _`Number`_: the x position within the image to start rendering from.
+    - `y` _`Number`_: the y position within the image to start rendering from.
+    - `width` _`Number`_: the width within the image to render.
+    - `height` _`Number`_: the height within the image to render.
+
+```javascript
+const scalar = 2;
+
+const shapes = await confetti.shapesFromImage({
+  src: 'data:image/gif;base64,R0lGODlhBQAFAIABAP8AAAAAACH5BAEKAAEALAAAAAAFAAUAAAIIjA+RwKxuUigAOw',
+  scalar,
+});
+
+confetti({ shapes, scalar });
+```
+
+#### Using a spritesheet
+
+```javascript
+const spritesheetSvg = `<svg width="100" height="100" viewBox="0 0 100 100" xmlns="http://www.w3.org/2000/svg">
+  <defs><polygon id="bow" points="0,0 0,25 30,0 30,25"/></defs>
+  <use href="#bow" x="0" y="0" fill="red"/>
+  <use href="#bow" x="35" y="0" fill="cyan"/>
+  <use href="#bow" x="0" y="30" fill="orange"/>
+  <use href="#bow" x="35" y="30" fill="fuchsia"/>
+</svg>`;
+
+const src = `data:image/svg+xml,${encodeURIComponent(spritesheetSvg)}`;
+
+const scalar = 2;
+
+const origins = [
+  { x: 0, y: 0 },
+  { x: 35, y: 0 },
+  { x: 0, y: 30 },
+  { x: 35, y: 30 },
+];
+
+const shapes = await confetti.shapesFromImage({
+  src,
+  scalar,
+  sprites: origins.map((origin) => ({ width: 30, height: 25, ...origin })),
+});
+
+confetti({ shapes, scalar });
+```
+
 ### `confetti.create(canvas, [globalOptions])` → `function`
 
 This method creates an instance of the `confetti` function that uses a custom canvas. This is useful if you want to limit the area on your page in which confetti appear. By default, this method will not modify the canvas in any way (other than drawing to it).

index.html

@@ -565,6 +565,54 @@ <h2><a href="#emoji" id="emoji" class="anchor">Emoji</a></h2>
     </div>
   </div>
 
+  <div class="container">
+    <div class="group" data-name="image">
+      <div class="flex-rows">
+        <div class="left">
+          <h2><a href="#image" id="image" class="anchor">Image</a></h2>
+          <button class="run">
+            Run
+            <span class="icon">
+              <svg class="icon">
+                <use xlink:href="#run"></use>
+              </svg>
+            </span>
+          </button>
+        </div>
+        <div class="description">
+          <p>
+            Don't fancy using emoji? You can use any image you want!
+          </p>
+        </div>
+      </div>
+      <div class="editor"></div>
+    </div>
+  </div>
+
+  <div class="container">
+    <div class="group" data-name="spritesheet">
+      <div class="flex-rows">
+        <div class="left">
+          <h2><a href="#spritesheet" id="spritesheet" class="anchor">Spritesheet</a></h2>
+          <button class="run">
+            Run
+            <span class="icon">
+              <svg class="icon">
+                <use xlink:href="#run"></use>
+              </svg>
+            </span>
+          </button>
+        </div>
+        <div class="description">
+          <p>
+            You can even cut out multiple images from a single spritesheet!
+          </p>
+        </div>
+      </div>
+      <div class="editor"></div>
+    </div>
+  </div>
+
   <div class="container">
     <div class="group" data-name="custom">
       <div class="flex-rows">
@@ -923,6 +971,52 @@ <h2><a href="#custom-canvas" id="custom-canvas" class="anchor">Custom Canvas</a>
         setTimeout(shoot, 0);
         setTimeout(shoot, 100);
         setTimeout(shoot, 200);
+      },
+      image: function image() {
+        async function run() {
+          const scalar = 2;
+
+          const shapes = await confetti.shapesFromImage({
+            src: 'data:image/gif;base64,R0lGODlhBQAFAIABAP8AAAAAACH5BAEKAAEALAAAAAAFAAUAAAIIjA+RwKxuUigAOw',
+            scalar,
+          });
+
+          confetti({ shapes, scalar });
+        }
+
+        run();
+      },
+      spritesheet: function spritesheet() {
+        const spritesheetSvg = `<svg width="100" height="100" viewBox="0 0 100 100" xmlns="http://www.w3.org/2000/svg">
+  <defs><polygon id="bow" points="0,0 0,25 30,0 30,25"/></defs>
+  <use href="#bow" x="0" y="0" fill="red"/>
+  <use href="#bow" x="35" y="0" fill="cyan"/>
+  <use href="#bow" x="0" y="30" fill="orange"/>
+  <use href="#bow" x="35" y="30" fill="fuchsia"/>
+</svg>`;
+
+        const src = `data:image/svg+xml,${encodeURIComponent(spritesheetSvg)}`;
+
+        const scalar = 2;
+
+        const origins = [
+          { x: 0, y: 0 },
+          { x: 35, y: 0 },
+          { x: 0, y: 30 },
+          { x: 35, y: 30 },
+        ];
+
+        async function run() {
+          const shapes = await confetti.shapesFromImage({
+            src,
+            scalar,
+            sprites: origins.map((origin) => ({ width: 30, height: 25, ...origin })),
+          });
+
+          confetti({ shapes, scalar });
+        }
+
+        run();
       }
     };
 

src/confetti.js

@@ -857,6 +857,39 @@
     };
   }
 
+  function shapesFromImage(imageData) {
+    var scalar = imageData.scalar != null ? imageData.scalar : 1;
+    var size = 10 * scalar;
+
+    var img = new Image();
+    img.src = imageData.src;
+
+    return promise(function (resolve) {
+      img.addEventListener('load', function() {
+        var sprites = imageData.sprites != null
+          ? imageData.sprites
+          : [{ x: 0, y: 0, width: img.naturalWidth, height: img.naturalHeight }];
+
+        var baselineWidth = Math.max.apply(null, sprites.map(function(rect) { return rect.width; }));
+
+        resolve(sprites.map(function(sprite) {
+          var width = size * sprite.width / baselineWidth;
+          var height = size * sprite.height / baselineWidth;
+          var scale = 1 / scalar;
+
+          var canvas = new OffscreenCanvas(width, height);
+          canvas.getContext('2d').drawImage(img, sprite.x, sprite.y, sprite.width, sprite.height, 0, 0, width, height);
+
+          return {
+            type: 'bitmap',
+            bitmap: canvas.transferToImageBitmap(),
+            matrix: [scale, 0, 0, scale, -width * scale / 2, -height * scale / 2]
+          };
+        }));
+      });
+    });
+  }
+
   module.exports = function() {
     return getDefaultFire().apply(this, arguments);
   };
@@ -866,6 +899,7 @@
   module.exports.create = confettiCannon;
   module.exports.shapeFromPath = shapeFromPath;
   module.exports.shapeFromText = shapeFromText;
+  module.exports.shapesFromImage = shapesFromImage;
 }((function () {
   if (typeof window !== 'undefined') {
     return window;

test/index.test.js

@@ -816,6 +816,74 @@ test('[text] shoots confetti of an emoji shape', async t => {
   t.is(t.context.image.hash(), 'cPpcSrcCjdC');
 });
 
+const shapeFromImageImage = async (page, args) => {
+  const { base64png, ...shape } = await page.evaluate(`
+    Promise.resolve().then(async () => {
+      const [{ bitmap, ...shape }] = await confetti.shapesFromImage(${JSON.stringify(args)});
+
+      const canvas = document.createElement('canvas');
+      canvas.width = bitmap.width;
+      canvas.height = bitmap.height;
+      const ctx = canvas.getContext('2d');
+      ctx.drawImage(bitmap, 0, 0, bitmap.width, bitmap.height);
+
+      return {
+        ...shape,
+        base64png: canvas.toDataURL('image/png')
+      };
+    });
+  `);
+
+  return {
+    ...shape,
+    buffer: base64ToBuffer(base64png)
+  };
+};
+
+test('[image] shapesFromImage renders an image', async t => {
+  const page = t.context.page = await fixturePage();
+
+  const { buffer, ...shape } = await shapeFromImageImage(page, { src: 'data:image/gif;base64,R0lGODlhBQAFAIABAP8AAAAAACH5BAEKAAEALAAAAAAFAAUAAAIIjA+RwKxuUigAOw', scalar: 2 });
+
+  t.context.buffer = buffer;
+  t.context.image = await readImage(buffer);
+
+  t.deepEqual({
+    hash: t.context.image.hash(),
+    ...shape
+  }, {
+    type: 'bitmap',
+    matrix: [0.5, 0, 0, 0.5, -5, -5],
+    hash: '80anMEa00G0'
+  });
+});
+
+// this test renders a black canvas in a headless browser
+// but works fine when it is not headless
+// eslint-disable-next-line ava/no-skip-test
+test('[image] shoots confetti of an image', async t => {
+  const page = t.context.page = await fixturePage();
+
+  await page.evaluate(`Promise.resolve().then(async () => {
+    window.__image = (await confetti.shapesFromImage({ src: 'data:image/gif;base64,R0lGODlhBQAFAIABAP8AAAAAACH5BAEKAAEALAAAAAAFAAUAAAIIjA+RwKxuUigAOw', scalar: 2 }))[0];
+  })`);
+
+  // these parameters should create an image
+  // that is the same every time
+  t.context.buffer = await confettiImage(page, {
+    startVelocity: 0,
+    gravity: 0,
+    scalar: 10,
+    flat: 1,
+    ticks: 1000,
+    // eslint-disable-next-line no-undef
+    shapes: [() => __image]
+  });
+  t.context.image = await readImage(t.context.buffer);
+
+  t.is(t.context.image.hash(), '9D_pL$p_Sr_');
+});
+
 /*
  * Custom canvas
  */
@@ -1247,3 +1315,9 @@ test('[esm] exposed confetti method has a `shapeFromText` property', async t =>
 
   t.is(await page.evaluate(`typeof confettiAlias.shapeFromText`), 'function');
 });
+
+test('[esm] exposed confetti method has a `shapesFromImage` property', async t => {
+  const page = t.context.page = await fixturePage('fixtures/page.module.html');
+
+  t.is(await page.evaluate(`typeof confettiAlias.shapesFromImage`), 'function');
+});