Skip to content

Releases

3.19.0

Choose a tag to compare

@matmen matmen released this 08 Nov 12:10
Immutable release. Only release title and notes can be modified.

3.19.0

New

  • image.dropShadow({ x, y, blur, spread, color, expand }): a shadow behind the image, shaped by its alpha. Without an offset it is a glow: image.dropShadow({ blur: 8, spread: 2, color: 0xff2fb9ff }). The image grows to fit it, unless expand: false.
  • image.outline({ width, color, expand }): an outline around the image's shape, the sticker effect for cut-out images or an outline for rendered text. It follows the edge's antialiasing, like the strokeWidth of renderText() does.
  • Image.linearGradient(width, height, { stops, angle }) and Image.radialGradient(width, height, { stops, x, y, radius }): images with a gradient, with the angle like CSS' linear-gradient(). stops are positions and colors like Colors.gradient() takes them, or just the colors, evenly spaced.
  • image.recolor(otherImage): takes the colors from another image of the same size and keeps the alpha. With a gradient it fills a shape, e.g. gradient text: text.recolor(Image.linearGradient(text.width, text.height, { stops: [0x22d3eeff, 0xfb923cff], angle: 90 })).

3.18.0

Choose a tag to compare

@matmen matmen released this 08 Nov 10:49
Immutable release. Only release title and notes can be modified.

3.18.0

Changes

  • Resize and SVG scale modes are lowercase names: 'nearest-neighbor', 'bilinear', 'bicubic', 'area' and
    'scale', 'width', 'height', also as the values of ResizeModes and SVGScaleModes (3.17.0 gave them the old
    values). The old values ('RESIZE_BILINEAR', 1-3, still the values of the deprecated Image.RESIZE_* and
    Image.SVG_MODE_*) keep working until 4.0: image.resize(256, 256, 'bicubic').

  • Animation.decode() applies the orientation of APNGs and animated WebPs (their eXIf and EXIF chunks, and XMP
    in PNGs), like Image.decode() does (it already did for JPEG XLs). applyOrientation: false keeps the stored
    frames. Still PNGs decoded by Animation.decode() are rotated as well now.

New

  • Animation.decode() takes applyOrientation, toneMapping and gainMap like Image.decode(): JPEG XL
    animations can be tone mapped with 'clamp', and their jhgm gain map is read into the gainMap of every frame.
  • resize({ width }) and resize({ height }) on images, frames and animations: the missing side keeps the aspect
    ratio, resize({ width: 256, mode: 'bicubic' }).
  • image.coordinates() yields [x, y] and image.pixels() yields [x, y, color] for every pixel, row by row.
  • cropCircle({ size: 'contain' | 'cover' }): 'contain' (the default, as before) keeps the circle inside the image.
  • Image.renderText(text, { font, size, color, layout, ...style }): the text first, everything else in the options.
    layout is TextLayoutOptions or a TextLayout: Image.renderText('Hi', { font, size: 32, layout: { maxWidth: 400 } }).
  • Infinity as the loop count of animations that loop forever (new Animation(frames, { loopCount: Infinity }),
    and the encoders'). Animations that loop forever still have -1 as their loopCount (also the decoded ones).
  • Animation.webpEncoder(), gifEncoder() and apngEncoder() take the options of encodeWebP(), encodeGIF() and
    encodeAPNG(), plus loopCount: the options are documented once.
  • trim({ color, tolerance }) and colorToAlpha({ color, transparencyThreshold, opacityThreshold }): the color goes into the options, like the other options. GainMap.encode({ quality }) likewise.

Deprecated

  • Positional optional arguments, the options take the same values: trim(color, options), colorToAlpha(color, options), GainMap.encode(quality), resize/scale/contain/fit/cover with a mode argument (use ResizeOptions), Frame constructor and Frame.from() with duration and offsets (use FrameOptions), Animation constructor with loopCount (use AnimationOptions), Animation.decode(input, onlyExtractFirstFrame), Animation.resize(width, height, mode), Animation.encodeGIF(quality) and encodeAPNG(compression), encodePNG(compression, metadata) and encodePNG(metadata), encodeJPEG(quality), renderSVG(svg, size, mode), composite(source, x, y, options), rotate(angle, resize), sharpen(amount, radius), roundCorners(radius), fisheye(strength), dominantColor(ignoreBlack, ignoreWhite, threshold). All of them still work until 4.0.
  • The numeric frame disposal ids (0-3): use the names ('any', 'keep', 'previous', 'background'). Removed in 4.0.
  • ResizeModes.AUTO (and Image.RESIZE_AUTO, Frame.RESIZE_AUTO): pass only the width or the height instead.
    Removed in 4.0.
  • Iterating over an image (for (const [x, y] of image)) and iterateWithColors(): use coordinates() and
    pixels(). Removed in 4.0.
  • Image.renderText(font, size, text, ...): use renderText(text, { font, size, ... }). Removed in 4.0, as is the
    swapped use of horizontalAlign and verticalAlign values of TextLayout.
  • -1 as a loop count, use Infinity. Removed in 4.0, when animations that loop forever have Infinity.
  • AnimationEncoderOptions, WebPAnimationEncoderOptions, GIFAnimationEncoderOptions and
    APNGAnimationEncoderOptions: they are the same as AnimationEncodeOptions, WebPAnimationEncodeOptions,
    GIFEncodeOptions and APNGEncodeOptions with loopCount, which are all the types there are in 4.0.
  • encode(): use encodePNG(), which takes the same arguments. Removed in 4.0.
  • cropCircle(max, feathering) and the max option: use cropCircle({ size: 'contain' | 'cover' }). Removed in 4.0.

Documentation

  • Deprecated overloads are tagged in the reference as well: a Deprecated label sits in front of each one, with the replacement named below it, also for methods that have other overloads that aren't deprecated.

3.17.0

Choose a tag to compare

@matmen matmen released this 07 Nov 22:20
Immutable release. Only release title and notes can be modified.

3.17.0

New

  • Image.recolor(color): sets the RGB of every pixel to a color and keeps each pixel's alpha, for silhouettes
    and tints: image.recolor(0xffffffff) makes every pixel white, keeping its transparency.
  • AnimationEncoder.frameCount: how many frames were added. AnimationEncoder.frames is deprecated: it's a
    number, unlike Animation.frames, which is an array. It will be removed in 4.0.
  • Colors: the color helpers moved out of Image into their own class, with the same results:
    Colors.fromRGBA(), fromRGB(), fromHSLA(), fromHSL(), toRGBA(), toRGB(), toHSLA() (new: a color as
    HSLA values) and gradient().
  • ResizeModes, SVGScaleModes and FrameDisposalModes: the constants have classes of their own, with the same
    values: image.resize(256, ResizeModes.AUTO, ResizeModes.BICUBIC), Image.renderSVG(svg, 512, SVGScaleModes.WIDTH),
    new Frame(w, h, {disposalMode: FrameDisposalModes.BACKGROUND}).

Deprecated

  • Image.RESIZE_*, Image.SVG_MODE_* and Frame.DISPOSAL_*: use ResizeModes.*, SVGScaleModes.* and
    FrameDisposalModes.* (Image.RESIZE_AUTO becomes ResizeModes.AUTO). The old names keep working and will be
    removed in 4.0. They are plain read-only properties now instead of getters.
  • The absolute argument of opacity(), red(), green(), blue(), lightness(), saturation() (and the
    absolute option of AdjustOptions): these methods scale by default; setting a fixed value is removed in 4.0.
    For a fixed color, use recolor().
  • Image.rgbaToColor(), rgbToColor(), hslaToColor(), hslToColor(), rgbaToHSLA(), colorToRGBA(),
    colorToRGB() and gradient()
    : use the Colors methods of the same role (Colors.fromRGBA() and so on).

Documentation

  • imagescript.dev has a new look: the logo's colors, clearer type, signatures and
    parameters that are easier to scan, and a sidebar grouped into classes, functions, interfaces and types. Inherited
    members are hidden by default (Settings → Inherited shows them), deprecated APIs are tagged and grouped at the end.
  • Every parameter is described now.

3.16.1

Choose a tag to compare

@matmen matmen released this 06 Nov 23:41
Immutable release. Only release title and notes can be modified.

3.16.1

Performance

  • encodeJPEG() is about 4% faster again: 3.16.0's greyscale JPEG support (for gain maps) had slowed down its block
    loop. Output is unchanged, byte for byte.

3.16.0

Choose a tag to compare

@matmen matmen released this 06 Nov 20:48
Immutable release. Only release title and notes can be modified.

New

  • HDR photos (Ultra HDR / JPEG-R JPEGs, as phones take them: an SDR JPEG with a gain map saying how much brighter
    each part gets on HDR displays) stay HDR. Image.decode reads the gain map into the new image.gainMap (a
    GainMap: its pixels, decoded only when needed, and its parameters, from ISO 21496-1 or Adobe's hdrgm XMP), and
    encodeJPEG() writes it back with both kinds of metadata (Android, Chrome and Apple read them): decoding and
    re-encoding a photo keeps the gain map. Before, it was dropped and HDR photos came out SDR only.
    • The gain map follows the image: resizing, cover/contain/fit, cropping, region, trimming, rotating,
      flipping, fisheye and the Exif orientation transform it alike (at its own resolution, a quarter of the width
      and height in photos from phones).
    • Drawing keeps it right: what composite() puts over the image brings its own gain map (or none: no boost there),
      blended with the image's by the light of both; drawBox, drawCircle and fill leave no boost where they
      draw. Images without a gain map get one when an HDR image is composited onto them.
    • Color changes (brightness, contrast, gamma, lightness, red/green/blue, and for maps with a gain
      per channel also saturation, hueShift, greyscale, sepia) are made to the HDR rendition too, on values
      with SDR white as 1 and the highlights above it: what HDR displays don't boost changes like on SDR ones, the
      highlights change alike. The inverts leave no boost (the highlights would become the darkest parts); blur
      blurs the gain map alike.
    • new GainMap(image, options) makes gain maps (image.gainMap = ..., null removes it), GainMap.decode() and
      gainMap.encode() read and write one alone. encodeJPEG({ gainMap: { quality, scale } }) re-encodes the map
      at a quality or size, { gainMap: false } leaves it out; DecodeOptions.gainMap: false doesn't read it.
    • Files with the gain map cut off (some chat apps and uploads keep the index but drop the map) and broken gain map
      metadata decode as before, without one.
    • AVIFs and JPEG XLs carry gain maps too (AVIF 1.2's tone mapped item, JPEG XL's jhgm box): Image.decode reads
      them, encodeAVIF() and encodeJXL() write them (with the same gainMap option), so Ultra HDR JPEGs convert to
      HDR AVIFs and JPEG XLs a fraction of the size.
    • iPhone JPEGs carry Apple's own kind of gain map (with its headroom in Apple's XMP or Exif maker note): it's read
      too, converted to the same parameters, and written as an Ultra HDR gain map.

3.15.0

Choose a tag to compare

@matmen matmen released this 06 Nov 06:08
Immutable release. Only release title and notes can be modified.

3.15.0

New

  • effort applies to lossless encodeWebP() (and lossless animation frames) too: 0 is a fast mode (3 predictors,
    a short search for repeated pixels, one prefix code, no color transform), 1 is in between, 2 (the default) and
    up compress the most. A 1920x1080 photo with 8 threads: 0.20 s for 1.32 MB at effort 0, 0.57 s for 1.20 MB at 1,
    0.70 s for 1.22 MB at 2; a 1434x1434 graphic: 76 ms for 346 kB, 188 ms for 301 kB, 199 ms for 277 kB. Over a
    corpus of photos and graphics, effort 0 takes about a fifth (photos) to a third (graphics) of the time for files
    6-8% larger, effort 1 about two thirds for files up to 2% larger.

Performance

  • Lossless encodeWebP() makes photos about 3-4% smaller and graphics about 1.5%, and photos above a megapixel take
    less time (the 1920x1080 bench photo: 1.22 MB in 0.70 s instead of 1.34 MB in 0.80 s, with 8 threads): predicted
    images also try referencing only the pixel to the left and the one above, kept where that's estimated smaller
    (short matches further away take more bits than the pixels they replace; above a megapixel the estimate is made on
    three bands of rows, and the search for matches further away is left out).
  • cover() only resamples the part of the image it keeps instead of resizing all of it and then cropping: a 400x400
    thumbnail of a 1920x1080 photo takes 10 ms instead of 15.6 ms. The pixels are the same.
  • Bicubic resize() of opaque images is about 1.4 times as fast (a 1920x1080 photo to half: 31 ms instead of 43 ms):
    it leaves out the alpha channel and reads the source rows in order. The pixels are the same.
  • Decoding baseline (non-progressive) JPEGs takes less memory: the blocks are turned into pixels a row at a time
    instead of keeping every coefficient until the end (a 1920x1080 photo: 15 MB at the peak instead of 23 MB). The
    pixels are the same.

3.14.0

Choose a tag to compare

@matmen matmen released this 04 Nov 20:40
Immutable release. Only release title and notes can be modified.

3.14.0

New

  • Lossless encodeJXL() compresses like libjxl's cjxl -e 3 (effort 3) by default: about 15% smaller files for
    photos (a 1920x1080 photo: 1.17 MB instead of 1.39 MB) and 13% for graphics, within 1-2% of cjxl's sizes. It
    uses a palette of up to 1024 colors where it fits (else palettes of the channels that use few of their values),
    YCoCg and the weighted predictor in contexts of its error, and codes the groups in worker threads
    (JXLEncodeOptions.threads, the same files): the photo takes 0.24 s with 8 threads, 0.65 s with one. effort: 0
    keeps the fast mode, byte for byte what cjxl -e 1 writes (0.11 s for the photo); effort applies to lossless
    compression now too.

Performance

  • Lossy encodeJXL() is faster: a 1920x1080 photo at quality 90 takes 1.6 s instead of 2.3 s at effort 1 and 2.4 s
    instead of 4.8 s at effort 2 on one thread; with 8 threads 0.72 s instead of 0.81 s and 0.95 s instead of 1.46 s
    (3840x2160: 1.6 s instead of 2.0 s and 2.5 s instead of 4.1 s). The 4x8 and AFV transforms are computed directly
    instead of by a 64x64 matrix, the varblock search rounds without Math.round() (slow in V8), patch search skips
    large components after a quick labeling, and the search is split into smaller pieces for the threads. The files stay
    the same, except for rare coefficients the new transforms round differently (2 of 108 test encodes, both the same
    size).

Fixes

  • Invalid options throw a RangeError naming them before any work, instead of failing inside an encoder or being
    ignored:
    • encodeAVIF(): effort other than 0, 1 or 2 failed with a TypeError deep in the encoder, quality and
      alphaQuality outside 0-100 were accepted, and an unknown subsampling silently meant 4:4:4 (now a
      TypeError).
    • encodeWebP(), Animation.encodeWebP() and Animation.webpEncoder() check effort for lossless images too
      (which don't use it).
    • NaN is refused as GIF quality and APNG compression (out of range values are still clamped, like PNG's), as
      dominantColor()'s threshold and as renderSVG()'s size (which threw about the image's width); negative font
      sizes in renderText() (which rendered an empty image); maxPixels that isn't positive in Image.decode() and
      Animation.decode() (which reported every image as too large); fractional loop counts in new Animation().
  • Animation.decode() reports invalid threads and maxPixels as such, not as damaged image data.
  • Image.decode() refuses GIFs with a hint at Animation.decode() instead of "Unsupported image type".
  • SVG feDisplacementMap applies its scale once, like the specification and browsers (it multiplied by it twice, like
    resvg, so at typical scales the whole input was displaced out of the filter region and disappeared), and reads the
    map's colors unpremultiplied.

3.13.2

Choose a tag to compare

@matmen matmen released this 04 Nov 13:27
Immutable release. Only release title and notes can be modified.

3.13.2

Fixes

  • Lossless JPEG XLs whose color space their codestream names, without an ICC profile, are converted to sRGB like
    ones with a profile (#83). cjxl stores Display P3 images this way, and they came out washed out because the P3
    values were read as sRGB: up to 41 levels off LittleCMS's conversion, now within 1. Applies to Image.decode and
    Animation.decode; turn it off with applyColorProfile: false. The P3 and BT.2100 primaries, custom primaries and
    white points, and linear, DCI and gamma transfer functions are all converted. Lossy (XYB) JPEG XLs, ones with an
    ICC profile and HDR ones (PQ, HLG) decode as before.

3.13.1

Choose a tag to compare

@matmen matmen released this 31 Oct 19:38
Immutable release. Only release title and notes can be modified.
f69d06b

Changes

  • Shortened default creation software tag to ImageScript vX.Y.Z to prevent truncated software tags in TGA files
  • Moved GitHub repository to imagescript/ImageScript

3.13.0

Choose a tag to compare

@matmen matmen released this 31 Oct 11:41
Immutable release. Only release title and notes can be modified.

This release brings WOFF fonts everywhere, smaller PNGs by default, much faster lossy WebP decoding and more accurate hinting. There are no breaking API changes, but PNGs come out smaller and a little slower by default (see below).

const inter = await fs.readFile('node_modules/@fontsource/inter/files/inter-latin-400-normal.woff');
await Image.renderText(inter, 32, 'Hello');   // WOFF fonts work in renderText, TextLayout and renderSVG
await image.encode();                         // PNG: compression level 4 by default (was 1)

WOFF fonts

renderText(), TextLayout and SVG rendering's fonts option take WOFF fonts now, not only TrueType and OpenType ones. Font packages like Fontsource ship only WOFF and WOFF2, so their fonts can be used directly. WOFF2 fonts are refused with a clear error for now: they need Brotli, which Chrome doesn't offer to JavaScript yet.

Smaller PNGs by default

PNG and APNG encoding default to compression level 4 instead of 1: files are 7-22% smaller (graphics 11%, photos 10%, screenshots 22%) for about 30% more encoding time. Pass compression: 1 for the previous speed. This applies in Node.js and Bun; elsewhere levels 1-6 already compressed like level 6.

Faster lossy WebP decoding

Lossy WebP decoding is about 45% faster (1920x1080 at quality 75: 184 → 100 ms), with the same pixels. The decoder's main loop kept getting deoptimized by V8: reading a DC prediction mode returned -0, which V8 treats as a floating point number.

More accurate hinting

TrueType hinting scales the fonts' control values exactly like FreeType. Before, some points could land 1/64 pixel off, sometimes across a pixel boundary: of one test font's glyphs at 11-128 px, 60 of 72 matched FreeType, now all of them do.

Tests

Many new tests cover the decoders' rarer paths, each against its reference implementation (libjpeg-turbo, libwebp, libvpx, libavif, libjxl, FreeType, HarfBuzz, resvg): unusual JPEG subsamplings and YCCK, interlaced GIFs and PNGs, every WebP loop filter variant, CID-keyed and flex CFF fonts, more complex script shaping, AV1 timing info, and the code paths for big endian machines.

See the changelog for the details.