@jtechlai/merge-images
v0.0.5
Published
Easily composites images without fiddling with the canvas, and can use webworker rendering threads to improve rendering performance
Downloads
1
Maintainers
Readme
merge-images
Easily composite images, no need to scribble on a canvas, can be used on webWorker
Using a canvas can sometimes be troublesome, especially when you only need to do some relatively simple tasks in the canvas context, like merging several images together. merge-images
abstracts all the repetitive tasks into a single function call.
Images can be overlaid on each other and repositioned. The function returns a Promise, resolving to a base64 URI, Blob, or Blob URL. It supports both the browser and Node.js. When used in a browser, rendering tasks can be assigned to a web worker, improving rendering performance and preventing the main thread from being blocked and unresponsive during rendering.
Install
npm install --save @jtechlai/merge-images
or for quick testing:
<script src="https://unpkg.com/jtechlai/merge-images"></script>
Usage
With the following images:
| body.png
| eyes.png
| mouth.png
|
| -------------------------------------------------- | -------------------------------------------------- | --------------------------------------------------- |
| | | |
You can do:
default use
import mergeImages from "merge-images";
// base64
mergeImages(["/body.png", "/eyes.png", "/mouth.png"]).then((b64) => (document.querySelector("img").src = b64));
// blob
mergeImages(["/body.png", "/eyes.png", "/mouth.png"], { outFormat: "blob" }).then(
(blob) => (/*...blob*/)
);
// {data: ...., type: "image/png"}
// blob url
mergeImages(["/body.png", "/eyes.png", "/mouth.png"], { outFormat: "blob-url" }).then(
(blobUrl) => (document.querySelector("img").src = blobUrl)
);
// blob:https://domain...
And that would update the img
element to show this image:
Positioning
Those source png images were already the right dimensions to be overlaid on top of each other. You can also supply an array of objects with x/y co-ords to manually position each image:
mergeImages([
{ src: 'body.png', x: 0, y: 0 },
{ src: 'eyes.png', x: 32, y: 0 },
{ src: 'mouth.png', x: 16, y: 0 }
])
.then(b64 => ...);
// data:image/png;base64,iVBORw0KGgoAA...
Using the same source images as above would output this:
Opacity
The opacity can also be tweaked on each image.
mergeImages([
{ src: 'body.png' },
{ src: 'eyes.png', opacity: 0.7 },
{ src: 'mouth.png', opacity: 0.3 }
])
.then(b64 => ...);
// data:image/png;base64,iVBORw0KGgoAA...
Dimensions
By default the new image dimensions will be set to the width of the widest source image and the height of the tallest source image. You can manually specify your own dimensions in the options object:
mergeImages(['/body.png', '/eyes.png', '/mouth.png'], {
width: 128,
height: 128
})
.then(b64 => ...);
// data:image/png;base64,iVBORw0KGgoAA...
Which will look like this:
Node.js Usage
Usage in Node.js is the same, however you'll need to also require node-canvas and pass it in via the options object.
const mergeImages = require('merge-images');
const { Canvas, Image } = require('canvas');
mergeImages(['./body.png', './eyes.png', './mouth.png'], {
Canvas: Canvas,
Image: Image
})
.then(b64 => ...);
// data:image/png;base64,iVBORw0KGgoAA...
One thing to note is that you need to provide a valid image source for the node-canvas Image
rather than a DOM Image
. Notice the above example uses a file path, not a relative URL like the other examples. Check the node-canvas docs for more information on valid Image
sources.
webWorker Usage
const mergeImages = require('merge-images');
mergeImages(['./examples/images/body.png', './examples/images/eyes.png', './examples/images/mouth.png'], {
worker: true
})
.then(b64 => ...);
// data:image/png;base64,iVBORw0KGgoAA...
One thing to note is that you need to provide a valid image source for Image
. Note that you need to use a file path, not a relative URL as in the example.
validity: https://xxx.xxx.xxx/images.png
✅
invalidity: ./examples/images/images.png
❌
API
mergeImages(images, [options])
Returns a Promise which resolves to a base64 data URI
images
Type: array
Default: []
Array of valid image sources for new Image()
.
Alternatively an array of objects with x
/y
co-ords and src
property with a valid image source.
options
Type: object
options.format
Type: 'image/png'
| 'image/jpeg'
| 'image/webp'
Default: 'image/png'
A DOMString indicating the image format.
options.quality
Type: number
Default: 0.92
Options: 0 ~ 1
A number between 0 and 1 indicating image quality if the requested format is image/jpeg or image/webp.
options.width
Type: number
Default: undefined
The width in pixels the rendered image should be. Defaults to the width of the widest source image.
options.height
Type: number
Default: undefined
The height in pixels the rendered image should be. Defaults to the height of the tallest source image.
options.background
Type: string
Default: #ffffff
Renders the background of the image. Defaults to #ffffff
background, background is invalid when format
is image/png
options.Canvas
Type: Canvas
Default: undefined
Canvas implementation to be used to allow usage outside of the browser. e.g Node.js with node-canvas.
options.Image
Type: Image
Default: undefined
Image implementation to be used to allow usage outside of the browser. e.g Node.js with node-canvas.
options.worker
Type: boolean
Default: true
Whether or not to use webWorker
for the rendering process, note that you need to use new Worker()
to call the use by yourself, check the examples
catalog for examples.
options.outFormat
Type: "blob" | "blob-url" | "base64"
Default: base64
Output image format, default has "blob" | "blob-url" | "base64"
, use blob
format, need to then convert to img
readable format.
options.crossOrigin
Type: "anonymous" | "use-credentials" | "" | undefined
Default: undefined
The crossOrigin
attribute that Image
instances should use. e.g Anonymous
to support CORS-enabled images.
License
MIT © JTechLai