image

↓ Methods.

module:image

Description:

  • Scaling and composing images with Sharp.js

Source:

Methods

(async, static) image.clip(item, bgitem) → {Promise}

Description:

  • Clip (crop) an item's image buffer so it fits within the background item's bounds.

    If the item is completely outside the background, it marks it as skipped.

    Side effects:

    • May set item._skip = 1 when the item is fully outside the background.
    • Replaces item._buffer with the cropped image buffer.
    • Replaces item._meta with metadata of the cropped image.
Source:
Parameters:
Name Type Description
item Object

item to be clipped.

Properties
Name Type Attributes Description
_buffer Buffer

Source image buffer.
_meta Object

Source image metadata.

Properties
Name Type Description
width number

Source image width.
height number

Source image height.
top number | string <optional>

Top position (relative to background).
left number | string <optional>

Left position (relative to background).
id string | number <optional>

Item identifier (used for logging).
bgitem Object

Background item that defines the clipping bounds.

Properties
Name Type Description
_meta Object

Background metadata.

Properties
Name Type Description
width number

Background width.
height number

Background height.
Returns:
Type Description
Promise

Resolves when clipping is complete. Returns early if no clipping is needed.

(async, static) image.composite(items, defaultsopt) → {Array.<object>}

Description:

  • Blend multiple images together, first image is used as the background for remaning items

Source:
Parameters:
Name Type Attributes Description
items Array.<object>

list of objects representing an image or text, properties are given to module:image.create, additional string property id can be used to describe or distinguish items from each other
defaults object <optional>

defaults global for all items, same parameters
Returns:
Type Description
Array.<object>
  • same items list with additional properties: buffer, meta

(static) image.convert(input, item) → {object}

Description:

  • Apply Sharp image filters and conversions

Source:
Parameters:
Name Type Description
input object

sharp image
item object
Properties
Name Type Attributes Description
filters Array.<object> <optional>

filters, each operation must provide filter name and value as a map or an object
Returns:
Type Description
object

transformed image

(async, static) image.create(item, bgitemopt) → {Promise.<object>}

Description:

  • Create an image from a photo or text, supports raunded corners, borders

Source:
Parameters:
Name Type Attributes Description
item object
Properties
Name Type Attributes Default Description
file string | Buffer <optional>

input file name
data Buffer | string <optional>

image buffer or data:image/*;base64, takes precedence over file name
width int <optional>

desired width, max width for text
height int <optional>

desired height, defaults to width if not given
background string <optional>
 #FFFFFF

main background color
border int <optional>

border size in px
border_color string <optional>
 FFFFFFF0

border color
border_radius number <optional>

make border round, this is divider of the size
padding number <optional>

transparent padding around image
padding_x number <optional>
padding_y number <optional>
padding_top number <optional>
padding_bottom number <optional>
padding_left number <optional>
padding_right number <optional>
padding_color int <optional>

padding background color
padding_radius number <optional>

make padding round
fit string <optional>

resize mode
position string <optional>
kernel string <optional>
gravity string <optional>
withoutEnlargement boolean <optional>
withoutReduction boolean <optional>
fastShrinkOnLoad boolean <optional>
radius number <optional>

make it round, inner and outer layers, this is divider of the size
text string <optional>

text to render
color string <optional>

text color
alpha string <optional>

text opacity 0-65535 or 50%
bgalpha string <optional>

text background opacity 0-65535 or 50%
font string <optional>

font family
fontfile string <optional>

font file
weight string <optional>

One of ultralight, light, normal, bold, ultrabold, heavy, or a numeric weight.
size string <optional>

font size in 1024ths of a point, or in points (e.g. 12.5pt), or one of the absolute sizes xx-small, x-small, small, medium, large, x-large, xx-large, or a percentage (e.g. 200%), or one of the relative sizes smaller or larger.
stretch string <optional>

One of ultracondensed, extracondensed, condensed, semicondensed, normal, semiexpanded, expanded, extraexpanded, ultraexpanded.
style string <optional>

One of normal, oblique, italic.
spacing int <optional>

font spacing
dpi int <optional>
 72

text size in DPI
justify boolean <optional>
 true

text justification
wrap string <optional>

text wrapping if width is provided: word, char, word-char, none
align string <optional>

text aligment: left, centre, center, right
blend string <optional>

how to blend image, one of clear, source, over, in, out, atop, dest, dest-over, dest-in, dest-out, dest-atop, xor, add, saturate, multiply, screen, overlay, darken, lighten, colour-dodge, color-dodge, colour-burn,color-burn, hard-light, soft-light, difference, exclusion.
sharp object <optional>

additional raw Sharp item
stroke_width number <optional>

trigger outlined text with given stroke width, color is used as the fill
stroke_color string <optional>

outline stroke color
stroke_alpha number <optional>

opacity for the outline fill color
dilate_radius number <optional>

trigger outline dilate filter with given radius around text
dilate_color string <optional>

outline delate filter color
dilate_alpha number <optional>

opacity for the outline delate color
stroke_linejoin string <optional>

dilate stroke line join, miter, arcs, bevel, round
shadow_width number <optional>

width of the drop shadow for SVG texts
shadow_alpha number <optional>

opacity for drop shadows
shadow_color string <optional>

drop shadow color, if not given oposite of the stroke is used
shadow_blur number <optional>
bgitem object <optional>

background item
Returns:
Type Description
Promise.<object>
  • a sharp object containing an image, as PNG

(async, static) image.createBorder(item, width, height) → {Promise.<Buffer>}

Description:

  • Create a border image buffer with optional rounded corners.

    Builds an RGBA image of the given size filled with item.border_color (and item.border_alpha), falling back to semi-transparent white when no color is provided. If a radius is specified (item.border_radius or item.radius), it applies an SVG rounded-rectangle mask using a composite operation (default dest-in or item.border_blend).

Source:
Parameters:
Name Type Description
item Object

Border configuration.

Properties
Name Type Attributes Default Description
border_color string | Object <optional>

Border color (passed through this.toColor).
border_alpha number <optional>

Alpha used with border_color (passed through this.toColor).
border_radius number <optional>

Corner radius (falls back to item.radius).
radius number <optional>

Alternate corner radius if border_radius is not provided.
border_blend string <optional>
 'dest-in'

Sharp composite blend mode used for the radius mask.
width number

Output image width in pixels.
height number

Output image height in pixels.
Returns:
Type Description
Promise.<Buffer>

PNG-encoded image buffer.

(async, static) image.createGradient(item) → {Promise.<object>}

Description:

  • Generate an SVG radial-gradient ellipse overlay for an image item and return it as a Buffer.

    Picks a gradient color (gcolor) based on item.color and item.gradient_type, adjusting for luminance/contrast, then builds an SVG sized to item.meta.width/item.meta.height.

Source:
Parameters:
Name Type Description
item Object
Properties
Name Type Attributes Default Description
_meta Object
Properties
Name Type Description
width number

SVG width in pixels.
height number

SVG height in pixels.
color string <optional>
 "#fff"

Base color in hex format.
_color string <optional>
 "#fff"

Detected color in hex format.
gradient_type string <optional>

Gradient mode, e.g. "mid" (default uses negate).
id string | number <optional>

Identifier used for debug logging.
Returns:
Type Description
Promise.<object>

Sharp instance with rendered image

(async, static) image.createImage(item, bgitemopt) → {Promise.<object>}

Description:

  • Create a Sharp image instance from different input sources and optionally resize it.

    Accepts an image from a file path/URL (item.file), an existing Sharp instance (item.data), a Buffer (item.data), or a base64 data URL (item.data starting with "data:image/"). If width/height are provided (or derived from bgitem._meta), the image is resized and a new Sharp instance is returned.

Source:
Parameters:
Name Type Attributes Description
item Object
Properties
Name Type Attributes Description
width number | string <optional>

Target width. If not provided, may be taken from bgitem._meta.width.
height number | string <optional>

Target height. If not provided, may be taken from bgitem._meta.height. If still missing, defaults to width (square).
file string <optional>

Image input as a file path/URL (anything Sharp can open).
data object | Buffer | string <optional>

Image input:

  • a Sharp instance (will be converted to Buffer),
  • a Buffer,
  • a base64 data URL beginning with "data:image/".
sharp Object <optional>

Options passed to sharp(input, item.sharp) constructor.
fit string <optional>

Sharp resize fit option (e.g. "cover", "contain", "fill", "inside", "outside").
position string | Object <optional>

Sharp resize position option (gravity/strategy).
kernel string <optional>

Sharp resize kernel option.
background string | Object <optional>

Background color used for padding when applicable.
withoutEnlargement boolean <optional>

Do not enlarge if image is smaller than target size.
withoutReduction boolean <optional>

Do not reduce if image is larger than target size.
fastShrinkOnLoad boolean <optional>

Use fast shrink-on-load where supported.
bgitem Object <optional>

Optional background item used only as a source of fallback dimensions.

Properties
Name Type Attributes Description
_meta Object <optional>
Properties
Name Type Attributes Description
width number <optional>

Fallback width if item.width is not provided.
height number <optional>

Fallback height if item.height is not provided.
Returns:
Type Description
Promise.<object>

A Sharp instance for the loaded (and possibly resized) image.

(async, static) image.createOutline(item, bgitemopt) → {Promise.<Sharp>}

Description:

  • Render an SVG text block (optionally with stroke + outline dilation or drop shadow) into an image buffer, trimming each line and stitching multiple lines together when needed.

    The function builds an SVG based on item properties, renders it with sharp, then:

    • if item.text contains multiple lines (\n), renders each line separately and stitches results
    • otherwise returns a single rendered image

    Supported effects (mutually exclusive; dilation takes precedence over shadow):

    • Dilation/outline via SVG filter when item.dilate_radius|dilate_alpha|dilate_color is set
    • Drop shadow via SVG filter when item.shadow_width|shadow_alpha|shadow_color is set

    Notes:

    • Width/height and padding may be derived from bgitem._meta.width/height.
    • item.text supports simple Pango-like tags: <b>, <i>, <small>, <big>, and closing tags </...> which are mapped to <tspan> elements.
    • item.size can be a fraction (0..1) meaning a percentage of background height.
Source:
Parameters:
Name Type Attributes Description
item Object

Text/rendering configuration.

Properties
Name Type Attributes Default Description
text string <optional>

Text to render; \\n and \n create multiple lines.
width string | number <optional>

Output width; if omitted, derived from background width minus padding.
height string | number <optional>

Output height; if omitted, derived from background height minus padding.
color string <optional>
 "#fff"

Text fill color.
alpha number <optional>

Fill opacity/alpha (implementation-specific; passed to toColor).
_color string <optional>

Fallback internal fill color.
stroke_color string <optional>

Stroke color; if omitted it is auto-picked (black/white) based on fill luminance.
stroke_alpha number <optional>

Stroke opacity/alpha (passed to toColor).
stroke_width number <optional>
 0

Stroke width.
stroke_linejoin string <optional>
 "miter"

Stroke line join.
paint_order string <optional>
 "stroke"

SVG paint-order for text (e.g. "stroke fill").
font string <optional>
 "sans-serif"

Font family.
size number | string <optional>
 50

Font size. If numeric between 0 and 1, treated as fraction of background height.
weight string <optional>

Weight keyword mapped to SVG font-weight ("ultralight","light","ultrabold","heavy","bold").
style string <optional>
 "normal"

Font style.
stretch string <optional>
 "normal"

Font stretch.
baseline string <optional>
 "hanging"

SVG dominant-baseline.
dilate_radius number <optional>
 5

Dilation radius for outline filter (enables dilation effect if set).
dilate_alpha number <optional>
 25

Outline opacity in percent (0-100).
dilate_color string <optional>

Outline color; defaults to fill color.
shadow_width number <optional>
 3

Shadow offset in px for x/y (enables shadow effect if set).
shadow_blur number <optional>
 3

Shadow blur deviation.
shadow_alpha number <optional>
 50

Shadow opacity in percent (0-100).
shadow_color string <optional>

Shadow color; defaults to negated fill color (or black).
wrap number <optional>

a factor for text wrapping, using naive formula: width/fontSize*item.wrap
bgitem Object <optional>

Background item used for sizing/padding.

Properties
Name Type Attributes Description
_meta Object <optional>
Properties
Name Type Attributes Description
width number <optional>

Background width used to resolve relative sizes.
height number <optional>

Background height used to resolve relative sizes.
Returns:
Type Description
Promise.<Sharp>

A Sharp instance for the rendered outline/shadow text image.

(static) image.createText(item, bgitemopt) → {object}

Description:

  • Create a Sharp image instance that renders a text block using Pango rendering.

    Builds an optional <span ...>...</span> wrapper around the provided text using supported attributes (color, size, weight, underline, etc.), normalizes newline sequences ("\\n" -> "\n"), and passes sizing/font/layout options to sharp({ text: ... }).

Source:
Parameters:
Name Type Attributes Description
item Object

Text render options.

Properties
Name Type Attributes Default Description
width number | string <optional>

Target width. If not provided, falls back to bgitem._meta.width.
height number | string <optional>

Target height. If not provided, falls back to bgitem._meta.height.
text string

Text to render. "\\n" sequences are converted to newlines and trimmed.
font string <optional>

Font family name to use.
fontfile string <optional>

Path to a font file to use.
dpi number | string <optional>

Text rendering DPI. When set, height is not passed to Sharp.
spacing number | string <optional>

Line/paragraph spacing passed to Sharp.
align string <optional>

Text alignment passed to Sharp (e.g. "left", "center", "right").
justify boolean | string | number <optional>

Whether to justify text (coerced via lib.toBool).
wrap string <optional>
 "word"

Wrapping mode passed to Sharp.
_color string <optional>

Text color (becomes color="..." attribute).
color string <optional>

Text color.
bgcolor string <optional>

Background color.
size string | number <optional>

Font size, Pango format or a fraction of the height if < 1
weight string | number <optional>

Font weight.
style string <optional>

Font style.
stretch string | number <optional>

Font stretch.
strikethrough string | boolean <optional>

Strikethrough enable/value.
strikethrough_color string <optional>

Strikethrough color.
underline string | boolean <optional>

Underline enable/value.
underline_color string <optional>

Underline color.
line_height string | number <optional>

Line height.
segment string | number <optional>

Pango segment attribute.
letter_spacing string | number <optional>

Letter spacing.
allow_breaks string | boolean <optional>

Allow line breaks.
rise string | number <optional>

Text rise.
baseline_shift string | number <optional>

Baseline shift.
font_features string <optional>

Font features string.
gravity_hint string <optional>

Gravity hint.
text_gravity string <optional>

Text gravity (stored as gravity attribute).
alpha string | number <optional>

Text alpha; if not ending in %, % is appended.
bgalpha string | number <optional>

Background alpha; if not ending in %, % is appended.
bgitem Object <optional>

Optional background item used for default sizing.

Properties
Name Type Attributes Description
_meta Object <optional>
Properties
Name Type Attributes Description
width number <optional>

Default width fallback.
height number <optional>

Default height fallback.
Returns:
Type Description
object

A Sharp instance configured with a text input.

(async, static) image.detect(item, bgitem)

Description:

  • Detect a text color to place on top of the area inside given background

Source:
Parameters:
Name Type Description
item object

input item
bgitem object

background item generated

(static) image.mergeDefaults(item, defaultsopt) → {object}

Description:

  • Merge defaults into an item, supports format id.name or type.name where id must match item.id and type item.type

Source:
Parameters:
Name Type Attributes Description
item object
defaults object <optional>
Returns:
Type Description
object

(async, static) image.metadata(input) → {object}

Description:

  • Return metadata about the input

Source:
Parameters:
Name Type Description
input object | Buffer

buffer or Sharp instance
Returns:
Type Description
object
  • { buffer, meta }

(static) image.padding(itemopt, widthopt, heightopt) → {Object}

Description:

  • Normalize padding-related item into a rectangle object.

    Accepts either side-specific padding values or axis-wide or single padding:

    • padding_top, padding_right, padding_bottom, padding_left (highest priority)
    • padding_y applies to top/bottom, padding_x applies to left/right
    • padding applies to all sides

    Values >= 1 are in pixels, > 0 and < 1 in percentages relative to the background dimenstions

Source:
Parameters:
Name Type Attributes Description
item object <optional>

Input item object.

Properties
Name Type Attributes Description
padding number | string <optional>

Padding for all sides.
padding_x number | string <optional>

Padding for left/right.
padding_y number | string <optional>

Padding for top/bottom.
padding_top number | string <optional>

Padding for top side.
padding_right number | string <optional>

Padding for right side.
padding_bottom number | string <optional>

Padding for bottom side.
padding_left number | string <optional>

Padding for left side.
width number <optional>

max width to be used for fractions
height number <optional>

max height to be used for fractions
Returns:
Type Description
Object

Padding rectangle.

(static) image.region(item, width, height) → {object}

Description:

  • Return region corresponding to the item gravity or absolute coordinates (top, left ,width, height)

Source:
Parameters:
Name Type Description
item object

object
width int

background image width
height int

background image height
Returns:
Type Description
object
  • object { left, top, width, height }

(static) image.stats(input, regionopt) → {object}

Description:

  • Return the stats about given region with inverted dominant color, if no region provided stats for the whole image

Source:
Parameters:
Name Type Attributes Description
input Buffer | object

buffer or sharp object
region object <optional>

region to extract and return stats for
Returns:
Type Description
object

region stats with key properties:

  • dominant - dominant color
  • mean - mean color as RGB
  • stdev - standard deviation color as RGB
  • meta - meta data object
  • image - image as hidden property

(async, static) image.stitch(images, optionsopt) → {Promise.<Sharp>}

Description:

  • Stitch multiple images into a single vertically stacked image.

    Each input image is loaded and normalized via module:image/metadata, then composited onto a transparent RGBA background. Images are placed in the order provided, starting at the top (0), with each subsequent image positioned directly below the previous one.

    The resulting canvas size is:

    • width: max width of all successfully processed images
    • height: sum of heights of all successfully processed images
Source:
Parameters:
Name Type Attributes Description
images Array.<(Buffer|string|Object)>

List of images to stitch. Each item must be accepted by image.metadata (commonly a Buffer, file path, URL, or an object supported by that helper).
options object <optional>
Properties
Name Type Attributes Description
same_height boolean <optional>

add padding so all images are the same height
Throws:

May throw if creating/compositing/encoding fails, or if the input set produces an invalid canvas size (e.g., no valid images).

Type
Error
Returns:
Type Description
Promise.<Sharp>

A Sharp instance containing the stitched PNG image.