Image

https://jimp-dev.github.io/jimp
npm i @pi-r/jimp

Note

Jimp is used as the reference implementation for an Image module.

Example configuration

squared.json

{
  "image": {
    "handler": "@pi-r/jimp",
    "webp": "webp-custom", // IImage handler for "image/webp" (npm i webp-custom)
    "avif": "avif-custom", // IImage handler for "image/avif" (npm i avif-custom)
    "settings": {
      "jimp": {
        "rotate_clockwise": false,
        "cache_expires": "1w",
        "gifwrap_quantize": "none",
        "options": {
          "decode": {
            "image/jpeg": { // @jimp/js-jpeg{DecodeJpegOptions}
              "colorTransform": true,
              "formatAsRGBA": true
            }
          },
          "encode": {
            "image/jpeg": { // @jimp/js-jpeg{JPEGOptions}
              "quality": 75
            }
          }
        },
        "worker": { // Settings will override process.env
          "min": 2, // PIR_JIMP_WORKER_MIN
          "max": 8, // PIR_JIMP_WORKER_MAX
          "expires": "1m" // PIR_JIMP_WORKER_TIMEOUT
        }
      },
      "webp": {
        "path": "/path/to/libwebp" // Optional
      }
    }
  }
}

Tip

Jimp rotation is counter-clockwise. Use {-45} to achieve a 45-degree clockwise rotation.

Image conversion can be achieved using the commands array property in a FileAsset object.

{
  "selector": "p > img",
  "saveTo": "/static/generated", // Does not replace original image
  "commands": [
    "png(800x600){45}", // width: 800px; height: 600px; rotate: 45deg;
    "jpeg(50,50)!sepia" // left: 50px; top: 50px; method: sepia;
  ]
}

Supported formats

Format	0.x	1.x
png	r/w	r/w
jpeg	r/w	r/w
bmp	r/w	r/w
gif	r	r/w
tiff	r	r/w

WebP

Library	R	W	NPM	CJS	ESM
dwebp	x		dwebp-bin [1]	1.0.0	2.0.0
cwebp		x	cwebp-bin [1]	6.0.0	8.0.0
gif2webp		x	gif2webp-bin	3.0.0	5.0.0
webpmux	x	x	node-webpmux	3.2.0	3.2.0

There can be transparency issues for WebP animated transformations due to the WebP compression algorithm. node-webpmux is used to extract the raw data from the WebP image and to reconstruct the frames.

Note

libwebp [1] is supported locally for WebP transforms through settings.webp.path.

Command syntax

Placing an “@” symbol after the format (e.g. png@) will replace the original file inside the project. Using the “%” symbol will choose the smaller of the two files.

All segments are optional except format. Outer groupings and inner brackets are required.

format

| choose one |
- @
- %
~size(n)(w|x) (chrome only)
( minSize(n,0) , maxSize(n,*)? )
( width(n|auto) x height(n|auto) [bilinear|bicubic|hermite|bezier|nearest|none]? ^(cover|contain|scale)?[left|center|right|top|middle|bottom]? #background-color? )
( left(+|-n) , top(+|-n) | cropWidth(n) x cropHeight(n) )
{ …rotate(n|-n) #background-color? }
| choose one |
- opacity(0.0-1.0)
- jpeg_quality(0-100)
- webp_quality(0-100?[photo|picture|drawing|icon|text]?[0-100]?) [2]
!method [3]
!method(1, “string_arg2”, [1, 2], true, { “a”: 1, “b”: “\}” }, …args?) [4]

Example commands

Methods use simple bracket matching and does not fully check inside quoted strings. Unescaped “\\” with unpaired (”{}” or “[]”) will fail to parse.

webp(50000)(800x600[bezier]^contain[right|bottom]#FFFFFF)(-50,50|200x200){45,-45,215,315#FFFFFF}|0.5||100[photo][75]|!sepia

webp!opacity(0.5)
webp!op(0.5)

webp~800w(800x600)
webp~2x(1024x768)

Tip

The “~” is used to target the <img srcset> attribute.

Method aliases [5]

autocrop	au	background	bg	blit	bt
blur	bl	brightness	br	circle	ci
color	co	composite [6]	cp	contain [7]	ct
contrast	cn	convolute	cl	convolution	cu
cover	cv	crop	cr	displace	dp
dither	dt	fade	fa	fisheye	fe
flip	fl	gaussian	ga	greyscale	gr
invert	in	mask	ma	normalize	no
opacity	op	opaque	oq	pixelate	px
posterize	po	print	pr	quantize	qu
resize	re	rotate	ro	scale	sc
scaleToFit	sf	sepia	se	threshold	th

data-chrome-commands

<img src="https://s3-us-west-2.amazonaws.com/s.cdpn.io/12005/harbour1.jpg"
     data-chrome-file="saveAs:images/harbour.webp"
     data-chrome-options="inline"> <!-- data:image/webp;base64 -->

You can use image commands with saveTo (directory) on any element where the image is the primary display output.

img | object | embed | iframe

<img src="https://s3-us-west-2.amazonaws.com/s.cdpn.io/12005/harbour1.jpg"
     data-chrome-file="saveTo:../images/harbour"
     data-chrome-commands="png(10000,75000)(800x600[bezier]^contain[right|bottom])::webp|0.5|">

Workers (timeout 10s)

<img src="https://s3-us-west-2.amazonaws.com/s.cdpn.io/12005/harbour1.jpg"
     data-chrome-file="saveAs:images/harbour.png"
     data-chrome-commands="png@!sepia{45}"
     data-chrome-options='{ "worker": 10000 }'>

Tip

Multiple transformations use “::” as the separator.

Transformations are given a UUID filename except when “@” or “%” are used. Leaving data-chrome-file empty will save the transformations to the current image directory.

@pi-r/jimp

Changed in version 0.12.0:

Package will be developed under pi-r for future releases. [8]

Added in version 0.11.0:

NPM package jimp was upgraded to 1.6.0.
ImageModule settings jimp.options for MIME-based decode and encode optimizations was implemented.
Workers for native Jimp commands was implemented. [9]
ImageModule settings jimp.worker for available threads was implemented.
NPM binaries for WebP (ESM) are supported.
Jimp plugin method print supports built-in fonts as string using these names:
SANS_8_BLACK

SANS_10_BLACK

SANS_12_BLACK

SANS_14_BLACK

SANS_16_BLACK
SANS_32_BLACK

SANS_64_BLACK

SANS_128_BLACK

SANS_8_WHITE
SANS_16_WHITE

SANS_32_WHITE

SANS_64_WHITE

SANS_128_WHITE

Changed in version 0.11.0:

Package will be developed under pi-r2 for future releases. [10]

Added in version 0.10.0:

Jimp rotate strategy mode nearest | none were implemented.

Changed in version 0.9.4:

NPM binaries for WebP (ESM) are supported.

Added in version 0.8.1:

ImageModule settings property jimp.gifwrap_quantize was implemented using these method types:
sorokin
wu
dekker
none