Skip to content

Releases

3.20.4

Choose a tag to compare

@matmen matmen released this 18 Nov 19:45
Immutable release. Only release title and notes can be modified.

3.20.4

Deprecated

The deprecation hints now lead to the names 4.0 uses, and 3.x takes those names already. 4.0 ignores an option it
doesn't know, so code that followed the earlier hints (cropCircle({ size: 'cover' })) would have changed its output
there without an error:

  • cropCircle({ fit }): the size option is deprecated, fit is its name in 4.0. The hint of cropCircle(max, feathering) and of the max option now names fit.
  • Image.renderSVG(svg, { width }), { height } and { scale }: the size and mode options (and SVGScaleMode, SVGScaleModes) are deprecated, these are their names in 4.0. Only one of the three can be given. { font } (one font or an array) is the 4.0 name of fonts, which is deprecated. RenderSVGOptions is the 4.0 name of SVGOptions.
  • new GainMap(image, { min, max }) and map.min, map.max: the 4.0 names of gainMapMin and gainMapMax, which are deprecated.
  • ResizeModes, FrameDisposalModes and the constants Image.RESIZE_*, Frame.DISPOSAL_* and Image.SVG_MODE_* point to the names 4.0 uses ('bicubic', 'background', { width }): 4.0 removes the classes too. FrameDisposalMode is the 4.0 name of FrameDisposalModeName.

4.0.0-rc.5

4.0.0-rc.5 Pre-release
Pre-release

Choose a tag to compare

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

ImageScript 4.0.0-rc.5

The fifth release candidate for ImageScript 4.0 is ready for evaluation. This is a major release with breaking API
changes from 3.x. Before upgrading, update to the latest 3.x release (3.20.3) and address its deprecation warnings, then
follow the migration guide.

This release candidate fixes values of the wrong type that were still accepted, cut-off and damaged files, right-to-left text and a few SVG and encoder details.

Breaking changes since rc.4

  • Right-to-left text is aligned to the right by default: horizontalAlign defaults to the start of each
    paragraph's direction (like CSS' text-align: start). Pass horizontalAlign: 'left' for the old placement.
  • Cut-off JPEG and lossy WebP files throw like the other formats, where they decoded as gray or smeared images. A
    JPEG that only lacks its end marker still decodes.
  • Boolean options take true or false only: optimize: 'yes', applyOrientation: 'no', hinting,
    ignoreBlack, ignoreWhite, sharpYuv, expand and the decoders' gainMap throw a TypeError (a string was read
    as true).
  • A value that isn't a number where one goes is a TypeError everywhere: transform('matrix(...)'),
    colorMatrix() without an argument, font features and variations, renderText({ width: '300' }), the canvas size
    of the streaming encoders, transform({ origin: null }), new Animation(5), and binary data that isn't any.
    Metadata text fields have to be strings (title: 123 was written as '123').
  • Options are objects: an array as options throws like a number or a string, and so does a metadata that isn't
    an object.
  • More values are checked: dominantColor({ threshold }) outside 0-256, GainMap.encodeJPEG({ quality: 0 }), the
    encoders' gainMap: { quality, scale } also for images without a gain map, alphaQuality of encodeWebP() also for
    lossless images, renderSVG() with width: null or scale: null, and new Colors().
  • Gain map capacities are checked when they are set: map.hdrCapacityMax = -0.5 throws and keeps the old value
    (it was accepted, then clone() and the encoders threw). A one-element array for a channel value throws.
  • JSON.stringify() and console.log() of an Image, Frame or Animation show their size (and duration), not
    every pixel.

Fixes

  • image.composite(image, { x, y }) onto itself (or an image sharing its pixels) gives the same result as compositing
    a copy.
  • Image.pixels() yields the pixels the image had when the iteration started, also when the image is resized meanwhile.
  • Animation.decode() gives still images a frame of 100 ms, the Frame default, not 0 ms.
  • PNG chunks with a bad checksum are skipped when they hold color or text metadata, like libpng and browsers (files
    from the pngrs and Pillow test suites were refused); the image's own chunks still throw.
  • A JPEG scan with restart markers carries on after corrupt data at the next marker, like libjpeg.
  • encodeBMP() of a fully transparent image decodes to transparent pixels (3.x and rc.4 made them opaque).
  • Wrapped right-to-left lines with horizontalAlign: 'left' or 'center' are placed by their ink, not shifted by the
    space at the wrap point.
  • renderSVG() of an SVG with a viewBox and only one of width and height sizes the other side by the aspect
    ratio, like browsers (it letterboxed the content).
  • encodeJPEG() writes gray images as grayscale JPEGs (one component, a few percent smaller).
  • software: null without other metadata writes no empty Exif block.

Performance

  • Lossy JPEG XL encoding starts no worker threads below 1.5 megapixels with fewer than 4 threads, where they took
    1.3-1.7x as long as one.

Documentation

  • The migration guide lists the right-to-left default, JSON.stringify(), boolean options and cut-off files among the
    behavior changes (seventeen now).
  • README: CommonJS projects with module: nodenext need TypeScript 5.8 or newer; bun build needs the worker module
    served like esbuild and webpack; CCITT-compressed TIFF and arithmetic-coded JPEG aren't supported.

Known limits

  • TypeScript 5.7 or newer is needed (older versions can't read the Uint8Array<ArrayBuffer> return types).
  • Single-file bundles (esbuild, webpack, bun build) and CDN builds served from another origin run without worker
    threads: the output is identical, only slower. Serve dist/util/worker.js next to the bundle for threads.
  • The default maxPixels (16383 x 16383) still allows a GIF of 300 bytes to allocate a 1 GB canvas.

Feedback on this release candidate is welcome: open an issue.

4.0.0-rc.4

4.0.0-rc.4 Pre-release
Pre-release

Choose a tag to compare

@matmen matmen released this 14 Nov 11:28
Immutable release. Only release title and notes can be modified.

ImageScript 4.0.0-rc.4

The fourth release candidate for ImageScript 4.0 is ready for evaluation. This is a major release with breaking API
changes from 3.x. Before upgrading, update to the latest 3.x release (3.20.3) and address its deprecation warnings, then
follow the migration guide.

This release candidate comes out of a full pre-release check of the public API, the packaging, the runtimes and about
370,000 fuzzed decodes. It fixes what that found, and makes the remaining numeric arguments behave like the rest.

Breaking changes since rc.3

  • Renamed: the size option of cropCircle() is fit ('contain' or 'cover'), like resize()'s. Out-of-range
    feathering (outside 0-1) throws instead of being clamped.
  • Numbers have to be numbers, everywhere: a numeric string (opacity('0.5'), quality: '50', scale('2'),
    frame.duration = '40'), null or a boolean where a number goes is a TypeError. 3.x converted them in some methods
    and rejected them in others; rc.3 still accepted a few. NaN and the infinities are a RangeError.
  • Values that did nothing useful throw: roundCorners({ radius }) below 0 (it was clamped to 0), fisheye({ strength })
    of 0 or less (an empty image), and renderText({ size: 0 }) (a 1x1 image).
  • Gradients blend transparency premultiplied, like CSS: a gradient from transparent to red is ff00007f in the
    middle, no longer a dark 7f00007f. Gradients between opaque colors are unchanged.
  • image.gainMap = map stores a copy, so images given one map no longer change each other's by resizing or cropping.
  • resize({ background }) is only typed with fit: 'contain' (it was ignored otherwise).
  • Animation.resize() and scale() size the canvas like Image does: sides are cut to whole pixels, and scale()
    never goes below one pixel.
  • Cut-off animations keep the frames that arrived whole, and throw when none did: a GIF cut before its first frame
    decoded as a blank image, and the last frame of a cut GIF, lossy WebP or lossy JPEG XL animation was half decoded.
    A cut APNG showed only its first frame.
  • A canvas that doesn't fit the format throws: GIF over 65535 pixels (70000 was written as 4464), and an animation
    without a canvas.

Security and robustness

  • SVG strokes with round joins took 9 s and 1 GB for a 17 KB path (2.7 GB for 50 KB): a join was a whole circle at every
    vertex of a flattened curve. Joins are wedges now (1.6 s and 220 MB), and a render stops with a LimitError once its
    shapes' edges cross the rows of the image more than 2^27 times (thousands of huge overlapping strokes took 38 s).
  • A million dashes (157 bytes of SVG) took 650 MB: dashes beside the image are left out and the rest are stroked in
    batches. Text of 20000 glyphs took 15 s and now 0.4 s, 8000 random curves 18 s and now 2.3 s.
  • TIFF files that ask for far more memory than they are (YCbCr subsampling of 65534x65535: 4 GB for 32 KB; 1024
    samples per pixel: 1 GB for 33 KB) are refused before anything is allocated.
  • Decoding an animation takes 1.3 times the result's memory, not 2.2 (APNG and WebP composite each frame as it is
    decoded). dropShadow() and outline() throw a LimitError for sizes an image can't have.
  • Damaged JPEG, TIFF, GIF and TGA headers are decoding errors, where some read missing bytes or threw a RangeError.

Fixes

  • Bundlers keep only what a page uses: import { Colors } bundled the whole library (201 kB minified); it is 3.4 kB now,
    because the build's dist/package.json no longer hides "sideEffects": false.
  • Animation.resize() changes a frame once when an animation lists it more than once, resizes frames that share an
    image at different offsets to their own sizes, and throws below one pixel.
  • Animation.decode() of a JPEG XL animation counts all frames against maxPixels.
  • resize({ fit: 'cover' }) and fill(fn) leave the image and its gain map untouched when they throw.
  • The animation encoders cut frames to the canvas like Animation.encode*() does with optimize: false; add() rejects
    its promise for invalid frames; Colors.gradient() with one color throws for NaN.
  • Documentation: the README, the migration guide and the doc comments match the behavior (counts, error types, defaults).

Performance

Against 3.20.3 and rc.3, one build per process on a 1920x1080 photo, nothing changed beyond noise except: animated WebP
decode is 4.6% slower than rc.3 (the price of the lower memory), and quantize() with its new default dithering is
3.3 times slower than 3.x's (dither: 'none' is equal).

Known limits

  • TypeScript 5.7 or newer is needed (older versions can't read the Uint8Array<ArrayBuffer> return types).
  • Single-file bundles (esbuild, webpack) and CDN builds served from another origin run without worker threads: the
    output is identical, only slower. Serve dist/util/worker.js next to the bundle for threads.
  • The default maxPixels (16383 x 16383) still allows a GIF of 300 bytes to allocate a 1 GB canvas.

Feedback on this release candidate is welcome: open an issue.

4.0.0-rc.3

4.0.0-rc.3 Pre-release
Pre-release

Choose a tag to compare

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

ImageScript 4.0.0-rc.3

The third release candidate for ImageScript 4.0 is ready for evaluation. This is a major release with breaking API
changes from 3.x. Before upgrading, update to the latest 3.x release (3.20.3) and address its deprecation warnings, then
follow the migration guide.

This release candidate hardens SVG rendering against untrusted input and settles the last API changes before 4.0.

Security

Untrusted SVG input is supported, and these SVGs of a few hundred bytes could block the thread indefinitely in rc.2:

  • Shapes far outside the image (<circle r="1e9"/>, a huge scale() or arc) made the rasterizer hang. They render
    normally now.
  • feTurbulence numOctaves had no limit, so one attribute could make a filter take weeks. It stops at 24 octaves,
    which is all its output can show.
  • Masks, clip paths, patterns, markers and filter images nested in each other multiplied their work (three per
    level took minutes at ten levels). Like <use>, they now share a budget: renderSVG() throws once a document would
    take too long.
  • transform lists are parsed in linear time; a long, unclosed one took quadratic time.

Breaking changes since rc.2

  • Renamed: GainMap.encode() is GainMap.encodeJPEG(), and the fonts option of renderSVG() is font, like
    renderText()'s.
  • renderText() takes width and height instead of maxWidth and maxHeight. They set the image's size:
    lines wrap to the width and are aligned in the box. wrapHardBreaks is removed.
  • dominantColor() counts colors in a histogram (16 levels per channel, like sharp's) and returns the average of
    the fullest bin, so the result is always a color the image has. Its threshold is in channel values (0-256): the
    default 60 is 3.x's 15.
  • rotate(angle, { expand: false }) keeps the size for quarter turns too: the turned image is centered and cropped
    instead of swapping width and height.
  • Removed: coordinates() (use pixels(), deprecated in 3.20.3), and the fast option of resize() and
    scale() (resizing always takes the fast path).
  • More values throw: an out-of-range JPEG quality (0-100, it was clamped), and a composite() source that isn't
    an Image.
  • Types: RenderSVGOptions is a union of the sizes (width, height or scale), with the limits, fonts and
    images in SVGResourceOptions. QuantizeOptions takes either colors or palette. The animation encoders' option
    types extend the still-image ones. AnimationEncoder has no public constructor; create one with
    Animation.webpEncoder(), gifEncoder() or apngEncoder().

New

  • Animation.flip(), which mirrors each frame and its place on the canvas, and the FlipDirection type.
  • LimitError is exported (name 'LimitError'), so a "too large" error can be told apart from other RangeErrors.
  • GainMap.decode(data, { maxPixels }) takes the limit of Image.decode().
  • metadata: { creationTime: null, software: null } leaves those fields out of the file.

Fixes

  • Animation.resize(), scale(), crop(), trim() and flip() change a frame once when the animation lists it more
    than once (a hold or ping-pong). Before, it was resized or moved once per listing.
  • The streaming encoders cut frames to the canvas like Animation.encode*() does. With optimize: false, parts outside
    the canvas were dropped, or threw for APNG.
  • AnimationEncoder.add() rejects its promise instead of throwing synchronously.
  • Image.linearGradient() and radialGradient() work with fractional sizes; they threw a RangeError.
  • scale() keeps each side at least one pixel, like resize().
  • A damaged JPEG XL with an invalid blend channel throws a decoding error instead of a raw TypeError.
  • Gain map value checks name the values that conflict.

The minimum TypeScript version is 5.7, now stated in the README.

See the migration guide
for the full list of removed and reshaped APIs, behavior changes, and migration examples.

3.20.3

Choose a tag to compare

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

3.20.3

Deprecated

  • image.coordinates() is deprecated and will be removed in 4.0, like iterating over the image (for (const [x, y] of image)), which now points to pixels() instead of coordinates(). Use for (const [x, y] of image.pixels()): pixels() yields [x, y, color], so the color comes with the position.

4.0.0-rc.2

4.0.0-rc.2 Pre-release
Pre-release

Choose a tag to compare

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

ImageScript 4.0.0-rc.2

The second release candidate for ImageScript 4.0 is ready for evaluation. This is a major release with breaking API
changes from 3.x. Before upgrading, update to the latest 3.x release and address its deprecation warnings, then follow
the migration guide.

What changed

  • Values that were wrapped, clamped or ignored throw: colors have to be integers from -2^31 to 2^32 - 1, also the ones a fill() function returns (they wrapped to 32 bits; negative ones, which bitwise operators return, keep working); pixel coordinates are truncated without wrapping at 2^32; compression is an integer 0-9 like effort (it was clamped); frame durations that GIF, APNG or WebP can't store throw a RangeError like loop counts (they were cut; unchanged frames merged by the encoders are split at the limit); frame.xOffset and frame.yOffset are truncated to integers when set; image.bitmap = view throws a TypeError for a view that doesn't start at a multiple of 4 bytes (it was copied, so changes to the view were lost); Colors.gradient() throws for a NaN position with any number of stops; encodeGIF() of an animation without frames throws like the other encoders.

  • Invalid choices throw a TypeError naming the valid ones: the resize mode (an Error, thrown once resizing started, so resize({ fit: 'cover' }) could move a frame's offsets before failing), composite()'s mode, flip(), disposalMode and wrapStyle (RangeErrors; an empty or null wrapStyle was the default).

  • No creation time and no version in encoded files by default: the encoders only write a creation time when metadata.creationTime is given, so the same image encodes to the same bytes, and the default software is 'ImageScript' without the version.

  • Drawing an SVG image that can't be drawn throws: an href that isn't a data URI or one of the images, an image that can't be decoded (with the decoding error as its cause), an unsupported data URI type or an embedded SVG that can't be read throw once they are drawn (images in <defs> or hidden ones don't); they drew nothing before.

  • renderSVG({ maxLayerPixels }) limits the layers SVG rendering uses at once (groups with opacity, masks, filters, ...; 16 bytes per pixel each), so nested ones can't multiply the memory of a small SVG: default 4 * maxPixels. renderSVG({ maxImagePixels }) limits the raster images an SVG references together (default maxPixels; each was limited on its own before).

  • renderText({ maxPixels }), default 16383², counting the outline, checked before anything is allocated.

See the migration guide for the full list of removed and reshaped APIs, behavior
changes, and migration examples.

4.0.0-rc.1

4.0.0-rc.1 Pre-release
Pre-release

Choose a tag to compare

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

ImageScript 4.0.0-rc.1

The first release candidate for ImageScript 4.0 is ready for evaluation. This is a major release with breaking API
changes from 3.x. Before upgrading, update to the latest 3.x release and address its deprecation warnings, then follow
the migration guide.

What changed

  • A more consistent API: methods that take options now use options objects instead of positional arguments.
    Resize modes and frame disposal modes are plain strings; color conversion helpers are grouped under Colors.
  • Unified frames and animations: Frame now contains an Image at frame.image; Animation stores frames in
    animation.frames instead of extending Array. The separate GIF class is replaced by Animation.
  • Flexible resizing: resize({ width, height, fit }) supports stretching, aspect-preserving inside, padded
    contain, and cropped cover behavior on images, frames, and animations.
  • More predictable animation handling: decode() recognizes animation markers, including one-frame animations;
    Image.decode() returns the first frame. Infinite looping is represented by Infinity instead of -1.
  • Behavior changes to check: rotate() now turns clockwise; HSL hue values use degrees; JPEG encoding composites
    transparency onto black by default; quantize() dithers by default; and size-changing operations on Frame move
    its offsets to keep it positioned in the animation.
  • Expanded encoding and image operations: single images can encode as GIF, GIF encoders expose color-count and
    dithering options, animations gain more image operations, and SVG rendering accepts fonts and embedded images.
  • Tighter types and validation: fixed-length tuple types, checked frame and gain-map values, and
    Promise<Uint8Array<ArrayBuffer>> encoder results improve type safety. The encoder result type requires TypeScript
    5.7 or newer.

See the migration guide for the full list of removed and reshaped APIs, behavior
changes, and migration examples.

3.20.2

Choose a tag to compare

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

Fixes

  • Loop counts that don't fit the file format are refused with a RangeError naming the format's largest count, instead of wrapping around: a GIF with loopCount: 65536 was written with 0, which plays forever (GIF and animated WebP store up to 65535 and 65534, APNG up to 2147483646). This applies to encodeGIF(), encodeWebP() and encodeAPNG() of animations and to the streaming encoders.

3.20.1

Choose a tag to compare

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

Performance

  • Drawing on an image with a gain map (an HDR photo) is much faster: drawBox() and drawCircle() only recompute the part of the map they cover, instead of the whole map for every call. 400 scanlines over a 1820x1820 Ultra HDR photo take 0.3 s instead of 5.8 s, with the same result.
  • composite() onto or from an image with a gain map is up to twice as fast: 1820x1820 with a blend mode like 'add' takes 0.22 s instead of 0.48 s, with the same result. Gain maps stay in sync with the pixels as before.

3.20.0

Choose a tag to compare

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

New

  • image.quantize({ colors, palette, dither, ditherStrength }): reduces the image to a palette, in place: image.quantize({ colors: 16 }) for the 16 colors that best represent it, or a fixed one: image.quantize({ palette: [0x0f380fff, 0x306230ff, 0x8bac0fff, 0x9bbc0fff] }) for a Game Boy look. dither: 'floyd-steinberg' (or 'atkinson', or 'ordered' for a regular pattern) makes gradients look smooth with few colors. Transparent pixels keep their color and don't count towards the palette.
  • Image.renderSVG(svg, { images }): images for the <image> elements by their href, without data URIs: Image.renderSVG('<svg ...><image href="logo.png" .../></svg>', { images: { 'logo.png': bytes } }). The values are encoded images or Images; they are decoded only when the SVG uses them. Nothing is read from files or URLs.
  • image.colorMatrix(matrix): mixes the colors of every pixel with a color matrix, like SVG's feColorMatrix: greyscale, sepia, tints, swapped channels, color blindness simulation or any mix of them in one pass. Twenty values (four rows of [red, green, blue, alpha, offset], 0 to 1) or nine for just the colors: image.colorMatrix([0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, 1, 0]) swaps red and blue.
  • image.transform(matrix, { origin, expand, mode }): moves every point of the image with an affine transform in one resampling: rotation, scaling, skew, flips and shifts in any mix and around any point. The six values are SVG's matrix(a b c d e f): image.transform([1, 0, -0.3, 1, 0, 0]) slants an image like italics. The image grows to hold the result unless expand: false, and mode is 'nearest-neighbor', 'bilinear' (default) or 'bicubic'.