dear-image

DearImage

A collection of utility functions for the image examinations and transformations.

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

constructor

new DearImage(context)

argument	description
context	The 2D rendering context.

let canvas = document.getElementById('my-canvas');
let context = canvas.getContext('2d');
let image = new DearImage(context);
console.log(image.canvas === canvas); // => true

static methods

.from(value)

Creates a DearImage instance from the given value.

argument	description
value	The value to create from. Supported value types are HTMLCanvasElement, HTMLImageElement, OffscreenCanvas, Canvas from canvas and DearImage.

Returns the created DearImage instance.

let canvas = document.getElementById('my-canvas');
let image = DearImage.from(canvas);
console.log(image.canvas === canvas); // => false
let otherDuck = DearImage.from(image);
console.log(otherDuck.canvas === image.canvas); // => false

---

.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 canvas = document.getElementById('my-canvas');
let image = DearImage.fromExcept(canvas);
console.log(image.canvas === canvas); // => false
let otherDuck = DearImage.fromExcept(image);
console.log(otherDuck === 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, Blob, HTMLImageElement, Buffer and everything the function .from supports.

Returns a promise that resolves to the created DearImage instance.

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

---

.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.

---

.blank(sizeX, sizeY)

Creates a DearImage instance with a transparent image.

argument	description
size	The size of the image.

Returns the created DearImage instance.

overloading

• () => (0, 0)

properties

.canvas

The canvas.

---

.context

The 2D rendering context.

---

.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, sizeY)

Changes the size of the image.

argument	description
size	The new size of the image.

Returns the created DearImage instance.

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

---

.resizeX(sizeX, proportionally = false)

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

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

Returns the created DearImage instance.

---

.resizeY(sizeY, proportionally = false)

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

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

Returns the created DearImage instance.

---

.crop(originX, originY, sizeX, sizeY)

Selects an area from the image.

argument	description
origin	The origin of the area. A negative number indicates the origin from the end of the image.
size	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, sizeY, alignmentX, alignmentY)

Aligns the image inside an area.

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

Returns the created DearImage instance.

overloading

• (sizeX: number, sizeY: number) => (sizeX, sizeY, 'center', 'center')

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

---

.scale(scalingX, scalingY)

Changes the size of the image factorially.

argument	description
scaling	The scaling factor.

Returns the created DearImage instance.

overloading

• (scaling: number) => (scaling, scaling)

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.

---

.toImage(format, quality)

browser only

Creates an Image instance representing the content.

Returns the created Image instance.

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

---

.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.