Repository navigation
Releases
3.12.2
This release makes JPEG encoding about 30% faster and byte for byte identical to libjpeg-turbo, and gives ImageScript a logo. There are no API changes.
await image.encodeJPEG(90); // the same bytes as cjpeg -quality 90 -baseline -optimize (but for the Exif segment)JPEG encoding like libjpeg-turbo
encodeJPEG() now uses libjpeg-turbo's integer pipeline instead of floating point: its color conversion, chroma downsampling, DCT and quantization, including how it pads partial blocks at the image's edges. The files are exactly what cjpeg -quality <q> -baseline -optimize writes (with -sample 1x1 above quality 90), apart from our Exif segment. Over 490 test encodes at every quality, all were identical, and the tests check this against cjpeg's output.
- About 30% faster: the integer pipeline, chroma converted and subsampled two rows at a time (16 MB less memory for a 1920x1080 image) and leaner entropy coding.
- Slightly different files: photos come out 0.1-1% larger at the same quality. Rendered images (screenshots, graphics) at quality 90 and above can be up to 9% larger, mostly because libjpeg rounds the color samples to 8 bits. These are the same files sharp, Pillow and other libjpeg-based tools produce.
JPEG decoding now upsamples chroma a row at a time while converting to RGB, about 6 MB less memory for a 1920x1080 image, with the same pixels and speed.
Logo
ImageScript has a logo: it heads the README on GitHub, npm and JSR, and the documentation at imagescript.dev now has a favicon and shows a preview with the logo when you share a link.
See the changelog for the details.
3.12.1
This release makes lossless WebP files smaller, especially for graphics, screenshots and images with transparency. There are no API changes.
await image.encodeWebP(); // lossless: the benchmark graphic now takes 277 kB instead of 557 kBLossless WebP
- Transforms chosen by entropy analysis: like libwebp, the encoder now estimates whether the predictor and subtracting green pay off instead of always predicting. Graphics with flat areas and repeated parts compress much better without the predictor: the 1434x1434 benchmark graphic takes 277 kB instead of 557 kB (cwebp: 278 kB), screenshots and images with transparency 15-30% less. Photos stay the same.
- Color transform: after the predictor, red and blue are predicted from green per 32x32 block, like libwebp does. Emoji and rendered graphics get 5-6% smaller, about 0.6% on average, at about 9% more encoding time.
Over 39 test images, our lossless WebP bitstreams went from 1.11 to 1.04 times the size of cwebp's (-m 4 -q 75, sharp's default). As before, all of it is plain TypeScript: no WebAssembly and no native code.
Documentation
The documentation moved to imagescript.dev. Links to imagescript.matmen.dev redirect there.
See the changelog for the details.
3.12.0
This release adds variable fonts to text and SVG rendering, and converts AVIFs with wide gamut color primaries (Display P3, BT.2020) to sRGB when decoding. Like every codec and renderer in ImageScript, it's plain TypeScript: no WebAssembly and no native code. There are no breaking API changes, but decoded pixels of AVIFs with other primaries than sRGB's change (see below).
await Image.renderText(robotoFlex, 32, 'Hello', { variations: { weight: 700, width: 87.5 } });
await Image.renderText(robotoFlex, 32, 'Hello', { variations: { weight: 500, GRAD: 50 } }); // custom axes by tag
await Image.renderSVG(svg, { fonts: [interVariable] }); // font-weight: 650 → Inter at wght 650
await Image.decode(p3Avif); // now converted from Display P3 to sRGBVariable fonts
renderText() renders the instance TextStyle.variations asks for:
- Axes by name:
weight(1-1000),width(percent of normal),slant(degrees),italic(true/false),opticalSize(pixels); other axes by their tag, like Roboto Flex'sGRAD - Optical size: the font size unless given, like browsers'
font-optical-sizing: auto, so small text uses the font's sturdier small-size design - Values outside an axis's range are clamped, axes a font doesn't have are ignored, and misspelled names throw a
RangeError
renderSVG() uses variable fonts like browsers do: font-weight, font-stretch and font-style set the weight, width, italic and slant axes, font-optical-sizing the optical size, and font-variation-settings overrides them. A variable font covers its whole range of weights and widths when fonts are matched, like several faces of a family.
What varies: TrueType outlines (with composite glyphs), advances, line metrics, kerning and mark positions, the glyphs fonts substitute at some axis values, and hinting. Outlines and advances are the same as fontTools' and HarfBuzz's, shaping matches HarfBuzz, and all 14 of resvg's font-variation-settings tests pass. Variable fonts with CFF2 (PostScript) outlines aren't supported yet.
AVIF color primaries
AVIFs without an ICC profile whose color information gives other primaries than sRGB's (Display P3, BT.2020, DCI-P3, ...) or a gamma 2.2, 2.8 or linear transfer are converted to sRGB when decoding, like browsers show them, relative colorimetric and within 1 of LittleCMS. applyColorProfile: false keeps the stored values. Most AVIFs (sRGB/BT.709 or unspecified primaries) stay the same.
See the changelog for the details.
3.11.0
This release converts JPEG XLs with an embedded ICC color profile to sRGB when decoding, like PNG, JPEG, WebP, AVIF and TIFF already were, and fixes the JSR package: 3.10.0 only made it to npm. There are no breaking API changes, but decoded pixels of JPEG XLs with a non-sRGB profile change (see below).
await Image.decode(losslessP3Jxl); // now converted from Display P3 to sRGB
await Image.decode(losslessP3Jxl, { applyColorProfile: false }); // the stored values, as beforeJPEG XL color profiles
JPEG XLs whose pixels are stored in their embedded profile's color space (lossless ones, and JPEGs recompressed with cjxl) are converted to sRGB, in Image.decode() and Animation.decode(), the way browsers display them.
- The profile is decoded from JPEG XL's compressed ICC stream (ported from jxl-oxide), byte for byte the profile libjxl reads
- It's applied like the other formats' profiles: matrix/TRC profiles relative colorimetric, within 1 of LittleCMS; profiles with only lookup tables, CMYK and sRGB profiles leave the pixels as they are
- Lossy (XYB) JPEG XLs already decoded to sRGB; their profile only describes what the image was before encoding, so they stay the same
applyColorProfile: falsekeeps the stored values
Fixes
- 3.10.0 is on npm but JSR refused it (a global type declaration for
import.meta.url), so JSR's latest was still 3.9.0. 3.11.0 is on both, with everything from 3.10.0: worker threads for AVIF, JPEG XL and lossless WebP, and the faster SVG rasterizer (release notes). The release check now catches this before anything is published.
See the changelog for the details.
3.10.0
This release is about speed: AVIF, JPEG XL and lossless WebP encode and decode in worker threads, with byte-for-byte the same files and pixels as on one thread, and SVG rendering is faster too. Like every codec in ImageScript, it's still plain TypeScript: no WebAssembly and no native code. There are no breaking changes.
await image.encodeAVIF(); // in threads: 1.7 s instead of 4.9 s for a 1920x1080 photo
await image.encodeJXL({ quality: 90 }); // 0.86 s instead of 2.2 s
await Image.decode(bigJxl); // lossy 4K: 395 ms instead of 640 ms
await image.encodeWebP({ threads: 1 }); // threads can be limited or turned off everywhereWorker threads
Encoders and decoders split their work into worker threads where it pays off: by default as many as the processors available, at most 8. The new threads option (AVIFEncodeOptions, JXLEncodeOptions, WebPEncodeOptions, DecodeOptions, AnimationDecodeOptions) limits them, 1 turns them off. Every result is the same as without threads.
| 8 threads, Ryzen 7 5800X | before | now |
|---|---|---|
| AVIF encode, 1920x1080, effort 1 | 4.9 s | 1.7 s |
| AVIF encode, 1920x1080, effort 2 | 14.2 s | 3.4 s |
| JPEG XL encode lossy, 3840x2160, effort 1 | 8.5 s | 2.0 s |
| JPEG XL encode lossy, 3840x2160, effort 2 | 19.2 s | 4.8 s |
| JPEG XL decode lossy, 3840x2160 | 640 ms | 395 ms |
| JPEG XL decode lossless, 3840x2160 | 671 ms | 304 ms |
| AVIF decode, 3840x2160 4:2:0 | 466 ms | 355 ms |
| AVIF decode, 6400x2880 grid | 2.68 s | 1.12 s |
| WebP encode lossless, 3862x2172 | 2.34 s | 1.62 s |
- What runs in parallel: AVIF superblock rows in a wavefront (like libaom's row-based multithreading, so no loss in compression) and the filter trials; JPEG XL's XYB conversion, quantization field, varblock search, coefficients and tokens when encoding, its groups, Gaborish, EPF and color conversion when decoding; AVIF's conversion to RGB and grid tiles; WebP's predictor and prefix code search
- When: only for images large enough to gain from it. The thresholds were measured with 1 to 8 threads on 0.25 to 8 megapixels of photos, screenshots, images with few colors and transparency; below them (and for small lossless JPEG XLs) everything runs on the calling thread as before
- Where: Node.js (
worker_threads), Deno, Bun and browsers (Web Workers; bundlers like Vite pick up the worker's module). Browser pages without cross-origin isolation, edge runtimes and other runtimes without shared memory between workers run on one thread - Lossy JPEG XL decoding no longer keeps the coefficients of the whole frame (about 100 MB less at 4K)
Faster on one thread too
- SVG rendering: the rasterizer is 23-36% faster (500 text labels: 15% faster in all), with the same pixels on all of resvg's test files
- JPEG XL: lossless images decode straight to RGBA bytes (6% faster), and the patch search at effort 2 is about 30% faster
- AVIF: 4:2:0 and 4:2:2 images convert to RGB about 7% faster
Tests
Edge runtimes are tested on every commit: Cloudflare's workerd (with and without nodejs_compat) and Vercel's Edge Runtime run every codec and the renderers bundled like deployments, and Chromium runs them bundled by Vite, with threads on a cross-origin isolated page and without on another.
See the changelog for the details.
3.9.0
This release renders SVG text, converts images with embedded ICC color profiles to sRGB when decoding, hints glyphs exactly like FreeType, and adds patches to lossy JPEG XL and alpha quality to lossy WebP. SVG rendering also gains blend modes, transform-origin, paint-order and context paints. Like every codec in ImageScript, it's plain TypeScript: no WebAssembly and no native code. There are no breaking API changes, but decoded pixels of images with a non-sRGB ICC profile change (see below).
await Image.renderSVG(svg, { fonts: [await fs.readFile('Inter.ttf')] }); // <text>, <tspan>, <textPath>, ...
await Image.decode(p3Photo); // now converted from Display P3 to sRGB
await Image.decode(p3Photo, { applyColorProfile: false }); // the stored values, as before
await image.encodeJXL({ quality: 90, effort: 2 }); // patches for screenshots and text
await image.encodeWebP({ quality: 80, alphaQuality: 50 });New
SVG text
Image.renderSVG() renders <text>, <tspan>, <tref> and <textPath> with the fonts passed as SVGOptions.fonts and the ones the SVG embeds with @font-face (TrueType, OpenType and WOFF data: URIs).
- Font matching like browsers match installed fonts:
font-family, thenfont-stretch,font-styleandfont-weightby CSS Fonts' algorithm, generic families by the fonts' panose and pitch flags, and missing characters from the other fonts - Layout ported from resvg (usvg): chunks shaped as a whole (kerning and ligatures across spans), bidirectional text,
x/y/dx/dy/rotatelists,text-anchor,letter-spacing,word-spacing,textLength,baseline-shift,dominant-baseline,text-decoration, text along paths, vertical text,font-variant: small-caps, thefontshorthand andxml:space - Painting like shapes (gradients, patterns, strokes,
paint-order), in clip paths and bounding boxes, with color glyphs (COLR v0/v1, CBDT, sbix, SVG) - 359 of resvg's 431 text tests pass, plus 41 of its other tests that contain text. Variable fonts aren't supported yet
ICC color profiles
Decoding converts images with an embedded ICC profile to sRGB, the way browsers display them: PNG (iCCP), JPEG (APP2), WebP (ICCP, animations too), AVIF (colr) and TIFF. Display P3 photos from phones and Adobe RGB or ProPhoto images no longer look washed out.
- Matrix/TRC profiles (RGB and gray) are applied relative colorimetric. The results are within 1 of LittleCMS's
- Profiles with only lookup tables, CMYK profiles and sRGB profiles leave the pixels as they are
applyColorProfile: false(inImage.decode()andAnimation.decode()options) keeps the stored values- A 1920x1080 image takes about 35 ms to convert
Patches in lossy JPEG XL
encodeJXL({ quality, effort: 2 }) stores repeated text-like features (glyphs on the flat backgrounds of screenshots) once in a reference frame and adds them back where they occur, like libjxl's patches (cjxl -e 7), ported from it. A page of text takes 62% fewer bytes, screenshots 1-2% fewer. Other images come out the same.
Alpha quality in lossy WebP
encodeWebP({ quality, alphaQuality }) (0-100, default 100; also for animations and Animation.webpEncoder()) keeps fewer alpha levels below 100, with the same alpha values as cwebp's -alpha_q. For example, potato.png's alpha plane takes 1.3 kB at 50 instead of 1.9 kB, and a gradient takes 4.3 kB instead of 16.7 kB.
SVG rendering
- Blending:
mix-blend-mode(all 16 modes andplus-lighter) andisolation: isolate. All 23 of resvg's tests for them pass transform-originon elements, clip paths, gradients and patterns (21 of 23 tests)paint-order(fill, stroke, markers; 12 of 14 tests)context-fill/context-strokein markers and<use>(13 of 16 tests)shape-rendering: crispEdges/optimizeSpeeddraw without antialiasing, and the root'sbackground-coloris usedfont-sizeresolvesem,ex, percentages and keywords against the parent's size everywhere;font-weightacceptsbolder/lighter
Text rendering
Hinting (renderText with hinting) now places every point exactly where FreeType's TrueType interpreter (v35) puts it. This was checked on 18 fonts at 8-48 px and on all 6190 glyphs of DejaVu Sans at 4 sizes. Before, up to 30% of the glyphs of some fonts were off by fractions of a pixel, and a few were off by up to 4 pixels.
Fixes
- SVG: zero-length dashes at the start of a path get caps (square ones turned along the path)
- SVG: shapes without a bounding box painted with an
objectBoundingBoxgradient or pattern use its fallback color - SVG:
display: noneelements no longer count towards group bounding boxes - SVG:
overflow="inherit"on markers and nested viewports takes the parent's value - SVG: path data ends at the first character that isn't part of it, instead of that character being skipped
- SVG: CR LF and CR line ends read as line feeds, like in XML parsers
3.8.1
A performance release: decoding JPEG, PNG, GIF and lossy WebP and encoding JPEG are faster, and the results are identical to 3.8.0 (the same pixels and the same files). There are no API changes.
Performance
- JPEG decoding is about 14% faster (a 1920x1080 photo: 47 ms instead of 55 ms). YCbCr to RGB conversion runs in its own loop, clamps through a lookup table and stores whole pixels
- JPEG encoding is about 10% faster. Coefficients are stored in zigzag order along with each block's last nonzero position, so writing a block stops there instead of scanning all 64 coefficients twice
- PNG decoding is about 14% faster (a 1920x1080 photo: 36 ms instead of 41 ms). The Paeth filter keeps the neighbours of 3- and 4-byte pixels in variables, and RGB rows are stored as RGBA one whole pixel at a time
- GIF decoding is about 14% faster (101 frames of 300x300: 40 ms instead of 46 ms). LZW strings are copied from where they were decoded earlier instead of following the code chain back one byte at a time
- Lossy WebP decoding is about 8% faster. Upsampled pixels are stored one whole pixel at a time
3.8.0
This release encodes animations a frame at a time, adds OpenType features to text rendering and sharp YUV conversion to lossy WebP, and brings SVG rendering much closer to resvg: filters, patterns, markers and embedded images. It also fixes lossless WebPs that 3.7.0 could write undecodable (#82). Like every codec in ImageScript, it's plain TypeScript: no WebAssembly and no native code. There are no breaking API changes.
const encoder = Animation.webpEncoder(1000, 1000, { quality: 85 });
for (const frame of frames) await encoder.add(frame, { duration: 40 });
const webp = await encoder.finish();
await Image.renderText(font, 32, 'Office 1/2', { features: { smcp: true, frac: true } });
await image.encodeWebP({ quality: 80, sharpYuv: true });
await Image.renderSVG(svg); // now with filters, patterns, markers and <image>New
Animations a frame at a time
Animation.webpEncoder(), Animation.gifEncoder() and Animation.apngEncoder() (width, height, options) encode animations without holding all frames in memory: await encoder.add(frame, options) for each frame (a Frame or any image; options like { duration: 40 } override the frame's), then await encoder.finish().
- Same files as
encodeWebP(),encodeGIF()andencodeAPNG()produce for the same frames - Memory: only the canvas and the previous frame are kept (APNG keeps its frames compressed until the end): 120 frames of 1000x1000 take 159 MB instead of 1066 MB
OpenType features in renderText
features: { tnum: true, smcp: true, liga: false, salt: 2 } turns features on for the whole text (tabular numbers, small caps, stylistic sets, ...), turns them off (default ones like ligatures and kerning included) or picks an alternate by number. It works like HarfBuzz's user features and shapes exactly like hb-shape --features. Fonts that lack a feature ignore it.
Sharp YUV for lossy WebP
encodeWebP({ quality, sharpYuv: true }) (for images, animations and Animation.webpEncoder) converts to YUV with libwebp's sharp conversion, ported so the files match cwebp -sharp_yuv. Colored edges stay sharp. Encoding takes about twice as long. Photos come out about the same size (+0.3% on a 1920x1080 photo), but images with many hard color edges get considerably larger.
Image#region()
region(x, y, width, height) copies a region into a new image without changing the original. It's like crop on a clone, but without copying the whole image first.
SVG rendering
- Filters: all 17 primitives (blur, offset, flood, composite, merge, drop shadow, color matrix, component transfer, tile, blend with all 16 modes, morphology, convolve matrix, turbulence, displacement map, diffuse and specular lighting with all three lights, image), plus the CSS filter functions (
blur(),drop-shadow(),grayscale(), ...). Filter regions,color-interpolation-filtersandhrefinheritance are supported. Ported from resvg: 396 of its 408 filter tests pass, up from 81 - Patterns: in both units, with
viewBox,preserveAspectRatio,patternTransformandhrefinheritance. 32 of resvg's 33 pattern tests pass, up from 4 - Markers: start, mid and end markers, with
orient(includingauto-start-reverse),markerUnits,refX/refY,viewBoxand clipping, placed like resvg places them. 61 of 64 tests pass, up from 11 - Images (
<image>) from data URIs: every formatImage.decode()reads (GIFs show their first frame) and nested SVGs, gzipped ones included. External files and URLs aren't loaded
Text in SVGs isn't rendered yet.
Improvements
- Optimized lossy WebP animations are smaller and look better. Like libwebp, they skip pixels that changed by less than a tolerance derived from the quality, and make unchanged pixels transparent only in whole 8x8 blocks. On cross-fading animations the files are up to 13% smaller than before, at 0.1 dB PSNR below unoptimized ones (before: 0.8-1 dB below)
Fixes
- Lossless WebPs, and lossy ones with alpha (most optimized animations), could be undecodable since 3.7.0 (#82)
Performance
composite()with an opacity is about 40% faster innormalmode (7.6 ms instead of 12.6 ms for a 1100x680 layer), and 5-30% faster without an opacity
3.7.0
This release encodes lossy JPEG XLs, makes lossless WebPs and the alpha of lossy ones smaller, and decodes lossy JPEG XLs about 15% faster. Like every codec in ImageScript, it's plain TypeScript: no WebAssembly and no native code. There are no breaking API changes.
await image.encodeJXL(); // lossless, as before
await image.encodeJXL({ quality: 90 }); // lossy, like cjxl -q 90
await image.encodeJXL({ quality: 75, effort: 2 });New
Lossy JPEG XL encoding
encodeJXL({ quality, effort }) encodes lossy JPEG XLs (VarDCT) when given a quality. Without it, images are encoded losslessly as before.
quality(0-100) maps to the Butteraugli distance likecjxl -q: 90 is cjxl's default, 100 is losslesseffort(0-2, default 1): 1 chooses the transforms' sizes like libjxl's effort 5 (from 4x4 up to 64x64, chroma from luma per tile), 2 also tries the 4x8 and AFV transforms, 0 uses 8x8 DCTs only (like effort 3)- Alpha is lossless
- Compression: at the same SSIMULACRA2 score the files are about 1.5% smaller than
cjxl -e 5's at effort 1 (3.5% at effort 2), and within 1-4% ofcjxl -e 7's, the default (up to 9% for screenshots) - Speed: a 1920x1080 photo takes about 1 s at effort 0, 5 s at effort 1, 10 s at effort 2
Improvements
- Lossless WebP files are about 6% smaller (within about 7% of cwebp's), the alpha of lossy WebPs about 17% (at the default effort smaller than cwebp's): blocks are grouped by their statistics with prefix codes per group, the color cache's size is chosen, matches look one pixel ahead, smooth alpha is predicted instead of indexed. Lossless encoding takes about 65% longer
Performance
- JPEG XL decoding of lossy images is about 15% faster (2048x1536: 0.73 s instead of 0.87 s), with identical results
- AVIF encoding is about 8% faster, with files about as large as before
Fixes
AVIFEncodeOptionsis exported, with the newJXLEncodeOptions
3.6.0
This release writes metadata into AVIFs and JPEG XLs, makes PNGs of graphics up to 30% smaller and lossy WebP encoding about four times faster by default. There are no breaking API changes.
await image.encodeAVIF({ metadata: { author: 'me', description: 'a cat' } });
await image.encodeJXL({ metadata: { software: '' } }); // without the software tag
await image.encodeWebP({ quality: 75 }); // effort 2 now, about 250 ms for 1920x1080
await image.encodeWebP({ quality: 75, effort: 4 }); // like cwebp's default, as beforeNew
Metadata in AVIF and JPEG XL
encodeAVIF() and encodeJXL() take metadata like the other encoders: author, description, copyright, creation time and software (by default ImageScript and its version) as Exif.
- AVIF: an Exif item that describes the image, like libavif writes it
- JPEG XL: the codestream goes into the container, with an Exif box. The codestream is still byte for byte what
cjxl -e 1writes. As the creation time is always written, JPEG XLs are now always in the container (about 250 bytes more), like JPEGs and WebPs always have Exif
Improvements
- PNG (and APNG): rows are left unfiltered when that compresses better than the paeth filter, as it often does for graphics and screenshots: their files are up to 30% smaller, and encoded faster. Photos are encoded as before, about 8% slower
- Lossy WebP defaults to
effort: 2instead of 4: about a quarter of the time (about 250 ms instead of 900 ms for a 1920×1080 photo) for files about 5% larger, at a slightly lower quality (about 0.5 dB PSNR).effort: 4still encodes byte for byte like cwebp's default - AVIF encoding also splits blocks into halves where that pays off: files about 2% smaller at the default effort, about 20% slower.
effort: 2also chooses smaller transforms within blocks: about 1% smaller (up to 4% for graphics)
Performance
- Lossy WebP with
effort3 to 6 is about 25% faster, with byte for byte the same files