Skip to content

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.