DearImage

A class that represents a graphical image.

setup

npm

npm i dear-image

Install optionally to support Node.

npm i canvas

ES module

import DearImage from 'dear-image';

Node

let DearImage = require('dear-image');

browser

<script src="https://unpkg.com/dear-image"></script>

The module is globally available as DearImage.

members

static methods

.isDearImage(value)

Determines whether the passed value is an instance of DearImage.

| argument | description | | ---: | :--- | | value | The value to be checked. |

Returns true if the passed value is an instance of DearImage, false otherwise.

.from(value)

Creates a DearImage instance from the given value.

| argument | description | | ---: | :--- | | value | The value to create from. Supported value types are ImageData, HTMLCanvasElement, OffscreenCanvas, HTMLImageElement and DearImage. |

Returns the created DearImage instance.

let element = document.getElementById('my-image');
let image = DearImage.from(element);
document.body.appendChild(image.toHTMLCanvasElement());

.fromExcept(value)

Creates a DearImage instance from the given value if it's not one.

| argument | description | | ---: | :--- | | value | The value to create from. |

Returns the same or created DearImage instance.

let element = document.getElementById('my-image');
let image = DearImage.fromExcept(element);
let otherImage = DearImage.fromExcept(image);
console.log(otherImage === image); // => true

.loadFrom(value)

Asynchronously loads a DearImage instance from the given value.

| argument | description | | ---: | :--- | | value | The value to load from. Supported value types are String, URL, Buffer, Blob, HTMLImageElement and everything the function .from supports. |

Returns a promise that resolves to the created DearImage instance.

let url = '/path/to/image.jpg';
let image = await DearImage.loadFrom(url);
document.body.appendChild(image.toHTMLCanvasElement());

.loadFromExcept(value)

Asynchronously loads a DearImage instance from the given value if it's not one.

| argument | description | | ---: | :--- | | value | The value to load from. |

Returns a promise that resolves to the same or created DearImage instance.

let url = '/path/to/image.jpg';
let image = await DearImage.loadFrom(url);
let otherImage = await DearImage.loadFromExcept(image);
console.log(otherImage === image); // => true

.blank(sizeX = 0, sizeY = 0)

Creates a DearImage instance without content.

| argument | description | | ---: | :--- | | sizeX | A number as the width of the image. | | sizeY | A number as the height of the image. |

Returns the created DearImage instance.

.solid(fill = 'rgba(0,0,0,0)', sizeX = 0, sizeY = 0)

Creates a DearImage instance with filled content.

| argument | description | | ---: | :--- | | fill | A string as the fill color. | | sizeX | A number as the width of the image. | | sizeY | A number as the height of the image. |

Returns the created DearImage instance.

.loadFontFace(fontFace = {
  family: 'sans-serif',
  style: 'normal',
  variant: 'normal',
  weight: 'normal',
}, source)

Loads a font face.

| argument | description | | ---: | :--- | | fontFace | Either a string as the font family or an object with the font face options. | | fontFace.family | A string as the font family. | | fontFace.style | A string as the font style. | | fontFace.variant | A string as the font variant. | | fontFace.weight | A number or a string as the font weight. | | source | A string as the source path to load from. |

Returns a promise.

.measureText(text, font = {
  family: 'sans-serif',
  size: 10,
  style: 'normal',
  variant: 'normal',
  weight: 'normal',
})

Creates a TextMetrics instance representing the dimensions of the drawn text.

| argument | description | | ---: | :--- | | text | A string as the text. | | font.family | A string as the font family. | | font.size | A number as the font size. | | font.style | A string as the font style. | | font.variant | A string as the font variant. | | font.weight | A number or a string as the font weight. |

Returns the created TextMetrics instance.

.text(text, options = {
  fill: '#000',
  font: {
    family: 'sans-serif',
    size: 10,
    style: 'normal',
    variant: 'normal',
    weight: 'normal',
  },
  padding: 0.28,
})

Creates a DearImage instance with the drawn text.

| argument | description | | ---: | :--- | | text | A string as the text. | | options.fill | A string as the fill color. | | options.font.family | A string as the font family. | | options.font.size | A string as the font size. | | options.font.style | A string as the font style. | | options.font.variant | A string as the font variant. | | options.font.weight | A number or a string as the font weight. | | options.padding | A number as the space around the text. The value is relative to the font size. |

Returns the created DearImage instance.

let fontFace = {family: 'Inconsolata'};
await DearImage.loadFontFace(fontFace, './fonts/Inconsolata.ttf');
let font = {...fontFace, size: 32};
let image = DearImage.text('Hello World', {font});

properties

.sizeX

The size of the image along the x-axis.

let image = DearImage.blank(300, 150);
console.log(image.sizeX); // => 300

.sizeY

The size of the image along the y-axis.

let image = DearImage.blank(300, 150);
console.log(image.sizeY); // => 150

methods

.resize(sizeX = this.sizeX, sizeY = this.sizeY)

Changes the size of the image.

| argument | description | | ---: | :--- | | sizeX | A number as the new width of the image. | | sizeY | A number as the new height of the image. |

Returns the created DearImage instance.

.resizeX(size = this.sizeY, proportionally = false)

Changes the width of the image.

| argument | description | | ---: | :--- | | size | A number as the new width of the image. | | proportionally | If true, the aspect ratio of the image is preserved. |

Returns the created DearImage instance.

.resizeY(size = this.sizeX, proportionally = false)

Changes the height of the image.

| argument | description | | ---: | :--- | | size | A number as the new height of the image. | | proportionally | If true, the aspect ratio of the image is preserved. |

Returns the created DearImage instance.

.crop(startX = 0, startY = 0, sizeX = this.sizeX, sizeY = this.sizeY)

Selects an area from the image.

| argument | description | | ---: | :--- | | startX | A number as the horizontal offset of the area. A positive value indicates the offset from the left of the image. A negative value indicates the offset from the right of the image. | | startY | A number as the vertical offset of the area. A positive value indicates the offset from the top of the image. A negative value indicates the offset from the bottom of the image. | | sizeX | A number as the width of the area. A positive value selects an area from left to right. A negative value selects an area from right to left. | | sizeY | A number as the height of the area. A positive value selects an area from top to bottom. A negative value selects an area from bottom to top. |

Returns the created DearImage instance.

.reframe(sizeX = this.sizeX, sizeY = this.sizeY, alignmentX = 'center', alignmentY = 'center')

Aligns the image inside an area.

| argument | description | | ---: | :--- | | sizeX | A number as the width of the area. | | sizeY | A number as the height of the area. | | alignmentX | A string as the horizontal alignment of the image. Possible values are 'start', 'center' and 'end'. | | alignmentY | A string as the vertical alignment of the image. Possible values are 'start', 'center' and 'end'. |

Returns the created DearImage instance.

.rescale(scalingX = 1, scalingY = 1)

Changes the size of the image factorially.

| argument | description | | ---: | :--- | | scalingX | A number as the scaling factor for the width. | | scalingY | A number as the scaling factor for the height. |

Returns the created DearImage instance.

.scale(scaling = 1)

Changes the size of the image factorially. The aspect ratio of the image is preserved.

| argument | description | | ---: | :--- | | scaling | A number as the scaling factor. |

Returns the created DearImage instance.

.scaleIn(sizeX = this.sizeX, sizeY = this.sizeY)

Scales the image inside an area. The aspect ratio of the image is preserved.

| argument | description | | ---: | :--- | | sizeX | A number as the width of the area. | | sizeY | A number as the height of the area. |

Returns the created DearImage instance.

.scaleOut(sizeX = this.sizeX, sizeY = this.sizeY)

Scales the image outside an area. The aspect ratio of the image is preserved.

| argument | description | | ---: | :--- | | sizeX | A number as the width of the area. | | sizeY | A number as the height of the area. |

Returns the created DearImage instance.

.scaleDownIn(sizeX = this.sizeX, sizeY = this.sizeY)

If necessary, scales the image down inside an area. The aspect ratio of the image is preserved.

| argument | description | | ---: | :--- | | sizeX | A number as the width of the area. | | sizeY | A number as the height of the area. |

Returns the created DearImage instance.

.scaleDownOut(sizeX = this.sizeX, sizeY = this.sizeY)

If necessary, scales the image down outside an area. The aspect ratio of the image is preserved.

| argument | description | | ---: | :--- | | sizeX | A number as the width of the area. | | sizeY | A number as the height of the area. |

Returns the created DearImage instance.

.scaleUpIn(sizeX = this.sizeX, sizeY = this.sizeY)

If necessary, scales the image up inside an area. The aspect ratio of the image is preserved.

| argument | description | | ---: | :--- | | sizeX | A number as the width of the area. | | sizeY | A number as the height of the area. |

Returns the created DearImage instance.

.scaleUpOut(sizeX = this.sizeX, sizeY = this.sizeY)

If necessary, scales the image up outside an area. The aspect ratio of the image is preserved.

| argument | description | | ---: | :--- | | sizeX | A number as the width of the area. | | sizeY | A number as the height of the area. |

Returns the created DearImage instance.

.flipX()

Flips the image horizontally.

Returns the created DearImage instance.

.flipY()

Flips the image vertically.

Returns the created DearImage instance.

.rotate(angle)

Rotates the image.

| argument | description | | ---: | :--- | | angle | A number as the angle of the rotation in radians. |

Returns the created DearImage instance.

.rotateClockwise()

Rotates the image clockwise.

Returns the created DearImage instance.

.rotateCounterClockwise()

Rotates the image counter clockwise.

Returns the created DearImage instance.

.drawForeground(image, options = { alignment: { x: 'center', y: 'center', }, repeat: { x: false, y: false, }, })

Draws an image above the current image.

| argument | description | | ---: | :--- | | image | Anything the function .from supports. | | options.alignment.x | A string as the horizontal alignment of the image. Possible values are 'start', 'center' and 'end'. | | options.alignment.y | A string as the vertical alignment of the image. Possible values are 'start', 'center' and 'end'. | | options.repeat.x | If true, repeats the image horizontally. | | options.repeat.y | If true, repeats the image vertically. |

Returns the created DearImage instance.

let image = DearImage.from(source).drawForeground(otherSource, {
  alignment: 'start',
  repeat: {
    y: true,
  },
});

.drawBackground(image, options = { alignment: { x: 'center', y: 'center', }, repeat: { x: false, y: false, }, })

Draws an image below the current image.

| argument | description | | ---: | :--- | | image | Anything the function .from supports. | | options.alignment.x | A string as the horizontal alignment of the image. Possible values are 'start', 'center' and 'end'. | | options.alignment.y | A string as the vertical alignment of the image. Possible values are 'start', 'center' and 'end'. | | options.repeat.x | If true, repeats the image horizontally. | | options.repeat.y | If true, repeats the image vertically. |

Returns the created DearImage instance.

let image = DearImage.from(source).drawBackground(otherSource, {
  alignment: {
    x: 'center',
  },
  repeat: true,
});

.fillForeground(fill)

Draws an image above the current image.

| argument | description | | ---: | :--- | | fill | A string as the fill color. |

Returns the created DearImage instance.

.fillBackground(fill)

Draws an image below the current image.

| argument | description | | ---: | :--- | | fill | A string as the fill color. |

Returns the created DearImage instance.

.toDataURL(format, quality)

Creates a data URL string representing the content.

Returns the created data URL string.

.toImageData()

Creates an ImageData object representing the content.

Returns the created ImageData object.

.toBlob(format, quality)

browser only

Creates a Blob instance representing the content.

Returns the created Blob instance.

.toBuffer(format, quality)

node only

Creates a Buffer instance representing the content.

Returns the created Buffer instance.

.toHTMLCanvasElement()

browser only

Creates a HTMLCanvasElement instance representing the content.

Returns the created HTMLCanvasElement instance.

.toOffscreenCanvas()

browser only

Creates an OffscreenCanvas instance representing the content.

Returns the created OffscreenCanvas instance.

.toHTMLImageElement(format, quality)

browser only

Creates a HTMLImageElement instance representing the content.

Returns the created HTMLImageElement instance.

let image = DearImage.from(source);
let element = image.toHTMLImageElement('image/jpeg', 0.75);
element.style.border = '1px solid BlueViolet';
document.body.appendChild(element);

.saveToFileSystem(target, format, quality)

node only

Asynchronously saves the content to the file system.

| argument | description | | ---: | :--- | | target | A string as the target path to save to. |

Returns a promise.

let image = DearImage.from(source);
await image.saveToFileSystem('/path/to/image.jpg', 'image/jpeg', 0.75);

utils

.isURL(value)

Determines whether the passed value is an instance of URL or an URL string.

| argument | description | | ---: | :--- | | value | The value to be checked. |

Returns true if the passed value is an instance of URL or an URL string, false otherwise.

console.log(DearImage.utils.isURL('https://github.com/SeregPie/DearImage'));
// => true

console.log(DearImage.utils.isURL(new URL('/SeregPie/DearImage', 'https://github.com')));
// => true

console.log(DearImage.utils.isURL('/SeregPie/DearImage')));
// => true in browser and false in node

.isDataURL(value)

Determines whether the passed value is a data URL string.

| argument | description | | ---: | :--- | | value | The value to be checked. |

Returns true if the passed value is a data URL string, false otherwise.

console.log(DearImage.utils.isDataURL('data:image/png;base64,R0lGODdh'));
// => true

console.log(DearImage.utils.isDataURL('data:,')));
// => true

console.log(DearImage.utils.isDataURL('data:image/png;base64')));
// => false