DearImage
A class that represents a graphical image.
setup
npm
npm i dear-image
Install optionally to support Node.
npm i canvas
ES module
;
Node
let DearImage = ;
browser
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;let image = DearImage;documentbody;
.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;let image = DearImage;let otherImage = DearImage;console; // => 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;documentbody;
.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;let otherImage = await DearImage;console; // => 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;let font = ...fontFace size: 32;let image = DearImagetext'Hello World' font;
properties
.sizeX
The size of the image along the x-axis.
let image = DearImage;console; // => 300
.sizeY
The size of the image along the y-axis.
let image = DearImage;console; // => 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;
.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;
.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;let element = image;elementstyleborder = '1px solid BlueViolet';documentbody;
.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;await image;
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;// => true console;// => true console);// => 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;// => true console);// => true console);// => false