dear-image

DearImage

A class that represents a graphical image.

setup

npm

npm i paperimage
npm i canvas # to support node

es6

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)

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)

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 with a transparent image.

argument	description
sizeXY	The size of the image.

Returns the created DearImage instance.

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

---

.size

The size of the image.

let image = DearImage.blank(300, 150);
console.log(image.size); // => {x: 300, y: 150}

---

.minSize

The minimum size of the image.

---

.maxSize

The maximum size of the image.

methods

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

Changes the size of the image.

argument	description
sizeXY	The new size of the image.

Returns the created DearImage instance.

let image = DearImage.from(source).resize(300, 150);

---

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

Changes the size of the image along the x-axis.

argument	description
size	The new size of the image along the x-axis.
proportionally	If true, the aspect ratio of the image is preserved.

Returns the created DearImage instance.

---

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

Changes the size of the image along the y-axis.

argument	description
size	The new size of the image along the y-axis.
proportionally	If true, the aspect ratio of the image is preserved.

Returns the created DearImage instance.

---

.crop(originX = 0, originY = 0, sizeX = this.sizeX, sizeY = this.sizeY)

Selects an area from the image.

argument	description
originXY	The origin of the area. A negative number indicates the origin from the end of the image.
sizeXY	The size of the area. A negative number reverses the direction.

Returns the created DearImage instance.

let image = DearImage.from(source).crop(100, -200, -50, 150);

---

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

Aligns the image inside an area.

argument	description
sizeXY	The size of the area.
alignmentXY	The alignment of the image. Possible values are 'start', 'center' and 'end'.

Returns the created DearImage instance.

let image = DearImage.from(source).reframe(300, 150, 'start', 'end');

---

.rescale(scalingX = 1, scalingY = 1)

Changes the size of the image factorially.

argument	description
scalingXY	The scaling factor.

Returns the created DearImage instance.

let image = DearImage.from(source).rescale(3/2, 2/3);

---

.scale(scaling = 1)

Changes the size of the image factorially while preserving the aspect ratio.

argument	description
scaling	The scaling factor.

Returns the created DearImage instance.

let image = DearImage.from(source).scale(3/2);

---

.flipX()

Flips the image along the x-axis.

Returns the created DearImage instance.

---

.flipY()

Flips the image along the y-axis.

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);