imagescript 1.3.1 → 3.0.0

package/LICENSE

@@ -9,4 +9,7 @@ mentioned licenses, but a license must be chosen.
 
 The corresponding license files can be found in the projects
 root directory, prefixed with LICENSE, suffixed with their
-corresponding SPDX identifier.
+corresponding SPDX identifier.
+
+Parts of this software are derived from third party projects under their
+own licenses (MIT, Apache-2.0 and the IJG license), see THIRD_PARTY_NOTICES.md.

package/README.md

@@ -3,49 +3,87 @@
 [![Discord Server](https://img.shields.io/discord/691713541262147687.svg?label=Discord&logo=discord&logoColor=ffffff&color=7389D8&labelColor=6A7EC2&style=for-the-badge)](https://discord.gg/8hPrwAH)
 [![Documentation](https://img.shields.io/badge/Documentation-informational?style=for-the-badge)](https://imagescript.matmen.dev/)
 [![Github](https://img.shields.io/badge/Github-Repository-181717?logo=github&style=for-the-badge)](https://github.com/matmen/ImageScript)
-[![deno.land](https://shields.io/badge/deno.land-gray?logo=deno&style=for-the-badge)](https://deno.land/x/imagescript)
 [![NPM](https://nodei.co/npm/imagescript.png)](https://www.npmjs.com/package/imagescript)
 
 ---
 
-**ImageScript** is a zero-dependency alternative to common JavaScript bitmap image manipulation tools. It can achieve
-much more performant results by utilizing lower-level memory access, less memory copying and WebAssembly / native
-binaries for decoding and encoding.
+**ImageScript** is a zero-dependency alternative to common JavaScript bitmap image manipulation tools. Every codec and
+renderer is written in TypeScript: no WebAssembly, no native binaries, no npm dependencies, no install scripts. The
+package is about 120 kB (compressed) and runs in Node.js 22.13 or newer (including Alpine/musl, ARM and bundled
+serverless functions), Deno, Bun and browsers. It works with both `import` and `require()`, type definitions are included.
+
+```sh
+npm install imagescript              # Node.js, Bun and bundlers
+deno add jsr:@matmen/imagescript     # Deno (npm:imagescript works too)
+```
 
 ---
 
 ### Features
 
-- [Decoding images](https://imagescript.matmen.dev/Image.html#.decode)
-  - PNGs (grayscale, RGB, indexed colors) with and without alpha channels
-  - JPEGs (grayscale, RGB, CMYK)
-  - TIFFs
-- [Decoding GIFs](https://imagescript.matmen.dev/GIF.html#.decode)
-- [Rendering SVGs](https://imagescript.matmen.dev/Image.html#.renderSVG)
-- [Rendering vector fonts](https://imagescript.matmen.dev/Image.html#.renderText)
-- Image manipulation functions ([crop](https://imagescript.matmen.dev/Image.html#crop)
-  , [rotate](https://imagescript.matmen.dev/Image.html#rotate)
-  , [composite](https://imagescript.matmen.dev/Image.html#composite), ...)
-- Color manipulation functions ([invert](https://imagescript.matmen.dev/Image.html##invert)
-  , [hueShift](https://imagescript.matmen.dev/Image.html##hueshift), ...)
-- Color information functions ([averageColor](https://imagescript.matmen.dev/Image.html#averageColor)
-  , [dominantColor](https://imagescript.matmen.dev/Image.html#dominantColor), ...)
-- Encoding images as [PNGs](https://imagescript.matmen.dev/Image.html#encode)
-  , [JPEGs](https://imagescript.matmen.dev/Image.html#encodejpeg)
-  , [WEBPs](https://imagescript.matmen.dev/Image.html#encodeWEBP)
-  and [GIFs](https://imagescript.matmen.dev/GIF.html#encode)
+- [Decoding images](https://imagescript.matmen.dev/classes/Image.html#decode)
+  - PNGs (grayscale, RGB, indexed colors, 1-16 bit, interlaced) with and without alpha channels
+  - JPEGs (baseline and progressive; grayscale, RGB, CMYK)
+  - TIFFs (strips and tiles; uncompressed, LZW, deflate, PackBits and JPEG compressed; BigTIFF)
+  - JPEGs, TIFFs and PNGs are rotated as their Exif (or, for PNGs, XMP) orientation says
+- [Decoding GIFs](https://imagescript.matmen.dev/classes/GIF.html#decode) with all frames, durations and disposal modes
+- [Rendering SVGs](https://imagescript.matmen.dev/classes/Image.html#rendersvg) (shapes, paths, gradients, strokes, clip paths,
+  masks, CSS; no text, images or filters)
+- [Rendering vector fonts](https://imagescript.matmen.dev/classes/Image.html#rendertext) (TrueType and OpenType, with kerning and outlines)
+- [Resizing](https://imagescript.matmen.dev/classes/Image.html#resize) (bilinear, bicubic, area averaging and nearest neighbor)
+- Image manipulation functions ([crop](https://imagescript.matmen.dev/classes/Image.html#crop)
+  , [rotate](https://imagescript.matmen.dev/classes/Image.html#rotate)
+  , [cropCircle](https://imagescript.matmen.dev/classes/Image.html#cropcircle)
+  , [roundCorners](https://imagescript.matmen.dev/classes/Image.html#roundcorners), ...)
+- Filters and color adjustments ([blur](https://imagescript.matmen.dev/classes/Image.html#blur)
+  , [sharpen](https://imagescript.matmen.dev/classes/Image.html#sharpen)
+  , [brightness](https://imagescript.matmen.dev/classes/Image.html#brightness)
+  , [hueShift](https://imagescript.matmen.dev/classes/Image.html#hueshift), ...)
+- Compositing with opacity and blend modes ([composite](https://imagescript.matmen.dev/classes/Image.html#composite))
+- Color information functions ([averageColor](https://imagescript.matmen.dev/classes/Image.html#averagecolor)
+  , [dominantColor](https://imagescript.matmen.dev/classes/Image.html#dominantcolor), ...)
+- Encoding images as [PNGs](https://imagescript.matmen.dev/classes/Image.html#encode) (smallest lossless color type)
+  , [JPEGs](https://imagescript.matmen.dev/classes/Image.html#encodejpeg)
+  and animated [GIFs](https://imagescript.matmen.dev/classes/GIF.html#encode)
 
 ---
 
 ### Example
 
-Check out one of these examples:
-* **NodeJS**: [README image generation](https://github.com/matmen/ImageScript/blob/master/tests/readme.js)
-* **Deno**: [README image generation](https://github.com/matmen/ImageScript/blob/deno/tests/readme.js)
-* **Browser**: [Grayscale Conversion Example Page](https://github.com/matmen/ImageScript/blob/browser/example/index.html) (via CDN)
+```js
+import { Image } from 'imagescript';
+import { readFile, writeFile } from 'node:fs/promises';
+
+const image = await Image.decode(await readFile('input.jpg'));
+image.resize(256, Image.RESIZE_AUTO).roundCorners(16);
+await writeFile('output.png', await image.encode());
+```
+
+With CommonJS:
+
+```js
+const { Image } = require('imagescript');
+```
+
+All coordinates are 0-based, `(0, 0)` is the top left pixel.
+
+A bigger example is the [README image generation](https://github.com/matmen/ImageScript/blob/master/tests/readme.js).
+Upgrading from 1.x? Version 3 has breaking changes (0-based coordinates, removed WebP encoding, Node.js 22.13+, ...),
+see the [changelog](https://github.com/matmen/ImageScript/blob/master/CHANGELOG.md). There is no 2.x release, the number was skipped because of the old experimental
+`imagescript/v2` API.
 
 [![Example](https://github.com/matmen/ImageScript/raw/master/tests/targets/readme.png)](https://github.com/matmen/ImageScript/blob/master/tests/readme.js)
 
 ---
 
+### Credits
+
+The deflate/inflate implementation is derived from [fflate](https://github.com/101arrowz/fflate) and the CRC-32 from
+[Fast CRC32 in JavaScript](https://gist.github.com/101arrowz/e58695f7ccfdf74f60ba22018093edea), both by Arjun Barrett.
+The JPEG codec is based in part on the work of the Independent JPEG Group (libjpeg) and on
+[pdf.js](https://github.com/mozilla/pdf.js), the glyph rasterizer is translated from
+[font-rs](https://github.com/raphlinus/font-rs). See [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md) for their licenses.
+
+---
+
 If you have any additional questions, feel free to join the [discord support server](https://discord.gg/8hPrwAH).

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,74 @@
+# Third party notices
+
+ImageScript is licensed under AGPL-3.0-or-later OR MIT (see [LICENSE](LICENSE)). Parts of it are derived from the
+following projects, under their own licenses. Each derived file says so in its header.
+
+| Project | Used in | License |
+|---|---|---|
+| [fflate](https://github.com/101arrowz/fflate) by Arjun Barrett | `src/codecs/zlib.ts` (deflate/inflate) | MIT |
+| [Fast CRC32 in JavaScript](https://gist.github.com/101arrowz/e58695f7ccfdf74f60ba22018093edea) by Arjun Barrett | `src/codecs/crc.ts` (slice-by-16 CRC-32) | MIT |
+| [libjpeg](https://ijg.org/) / [libjpeg-turbo](https://libjpeg-turbo.org/) by the Independent JPEG Group | `src/codecs/jpeg.ts` (IDCT, FDCT, upsampling, color conversion, progressive refinement, optimal Huffman tables) | IJG |
+| [pdf.js](https://github.com/mozilla/pdf.js) (forked from [jpgjs](https://github.com/notmasteryet/jpgjs) by notmasteryet) | `src/codecs/jpeg.ts` (structure of the scan decoder) | Apache-2.0 |
+| [font-rs](https://github.com/raphlinus/font-rs) by Raph Levien | `src/render/text.ts` (the `Rasterizer` class, also used for SVGs) | Apache-2.0 |
+
+## fflate, Fast CRC32 in JavaScript
+
+```
+MIT License
+
+Copyright (c) 2020 Arjun Barrett (fflate)
+Copyright (c) 2021 Arjun Barrett (Fast CRC32 in JavaScript)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```
+
+## libjpeg / libjpeg-turbo
+
+This software is based in part on the work of the Independent JPEG Group.
+
+The JPEG codec translates parts of libjpeg (as shipped by libjpeg-turbo) to TypeScript: the integer inverse DCT
+(`jidctint.c`), the floating point forward DCT (`jfdctflt.c`), fancy upsampling (`jdsample.c`), the YCbCr to RGB
+tables (`jdcolor.c`), the progressive AC refinement (`jdphuff.c`) and the optimal Huffman table generation
+(`jcphuff.c`/`jchuff.c`). The translations were rewritten for TypeScript's numbers and typed arrays; the rest of the
+codec is ImageScript's own. libjpeg's README with its copyright and terms is included unaltered as
+[licenses/README.ijg](licenses/README.ijg).
+
+## pdf.js, font-rs
+
+```
+pdf.js: Copyright 2014 Mozilla Foundation
+font-rs: Copyright 2015 Google Inc. All rights reserved.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+```
+
+The scan decoder of `src/codecs/jpeg.ts` follows the structure of pdf.js' `src/core/jpg.js` (block and MCU layout,
+one decode function per scan type). The `Rasterizer` class in `src/render/text.ts` is a translation of font-rs'
+`Raster` from Rust to TypeScript (`draw_line`, `draw_quad`, `accumulate`); its `cubic` method is adapted from
+`draw_quad`. The full license text is in [licenses/Apache-2.0.txt](licenses/Apache-2.0.txt).

package/dist/codecs/crc.d.ts

@@ -0,0 +1,9 @@
+/*!
+ * Slice-by-16 CRC-32, derived from "Fast CRC32 in JavaScript" (https://gist.github.com/101arrowz/e58695f7ccfdf74f60ba22018093edea)
+ * Copyright (c) 2021 Arjun Barrett, MIT License (see THIRD_PARTY_NOTICES.md)
+ */
+/**
+ * CRC-32 (ISO 3309), as used by PNG and zlib. Processes 16 bytes per step (slice-by-16, see #12), byte by byte so
+ * it doesn't depend on alignment or endianness
+ */
+export declare function crc32(buffer: Uint8Array): number;

package/dist/codecs/crc.js

@@ -0,0 +1,29 @@
+/*!
+ * Slice-by-16 CRC-32, derived from "Fast CRC32 in JavaScript" (https://gist.github.com/101arrowz/e58695f7ccfdf74f60ba22018093edea)
+ * Copyright (c) 2021 Arjun Barrett, MIT License (see THIRD_PARTY_NOTICES.md)
+ */
+const TABLE = new Int32Array(16 * 256);
+for (let n = 0; n < 256; n++) {
+    let c = n;
+    for (let k = 0; k < 8; k++)
+        c = c & 1 ? 0xedb88320 ^ c >>> 1 : c >>> 1;
+    TABLE[n] = c;
+}
+for (let n = 0; n < 256; n++) {
+    let c = TABLE[n];
+    for (let k = 256; k < TABLE.length; k += 256)
+        c = TABLE[k + n] = TABLE[c & 0xff] ^ c >>> 8;
+}
+export function crc32(buffer) {
+    let crc = -1, i = 0;
+    for (const end = buffer.length - 16; i <= end; i += 16) {
+        crc = TABLE[3840 + ((buffer[i] ^ crc) & 0xff)] ^ TABLE[3584 + ((buffer[i + 1] ^ crc >> 8) & 0xff)]
+            ^ TABLE[3328 + ((buffer[i + 2] ^ crc >> 16) & 0xff)] ^ TABLE[3072 + (buffer[i + 3] ^ crc >>> 24)]
+            ^ TABLE[2816 + buffer[i + 4]] ^ TABLE[2560 + buffer[i + 5]] ^ TABLE[2304 + buffer[i + 6]] ^ TABLE[2048 + buffer[i + 7]]
+            ^ TABLE[1792 + buffer[i + 8]] ^ TABLE[1536 + buffer[i + 9]] ^ TABLE[1280 + buffer[i + 10]] ^ TABLE[1024 + buffer[i + 11]]
+            ^ TABLE[768 + buffer[i + 12]] ^ TABLE[512 + buffer[i + 13]] ^ TABLE[256 + buffer[i + 14]] ^ TABLE[buffer[i + 15]];
+    }
+    for (; i < buffer.length; i++)
+        crc = TABLE[(crc ^ buffer[i]) & 0xff] ^ crc >>> 8;
+    return (crc ^ -1) >>> 0;
+}

package/dist/codecs/exif.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Reads the orientation tag (0x0112) from the first IFD of Exif data
+ * @param data a TIFF header and IFDs, optionally preceded by "Exif\0\0" (as in JPEG's APP1)
+ * @return the orientation (1-8), 1 if it is missing or invalid
+ */
+export declare function orientation(data: Uint8Array): number;
+/**
+ * Reads tiff:Orientation from an XMP packet, as attribute or element
+ * @return the orientation (1-8), 1 if it is missing or invalid
+ */
+export declare function xmpOrientation(xmp: string): number;

package/dist/codecs/exif.js

@@ -0,0 +1,27 @@
+export function orientation(data) {
+    if (data.length >= 6 && data[0] === 0x45 && data[1] === 0x78 && data[2] === 0x69 && data[3] === 0x66 && data[4] === 0 && data[5] === 0)
+        data = data.subarray(6);
+    if (data.length < 8)
+        return 1;
+    const tiff = new DataView(data.buffer, data.byteOffset, data.byteLength);
+    const little = tiff.getUint16(0) === 0x4949;
+    if (!little && tiff.getUint16(0) !== 0x4d4d)
+        return 1;
+    const ifd = tiff.getUint32(4, little);
+    if (ifd + 2 > tiff.byteLength)
+        return 1;
+    for (let i = 0, count = tiff.getUint16(ifd, little); i < count; i++) {
+        const entry = ifd + 2 + i * 12;
+        if (entry + 12 > tiff.byteLength)
+            break;
+        if (tiff.getUint16(entry, little) !== 0x0112)
+            continue;
+        const value = tiff.getUint16(entry + 8, little);
+        return value >= 1 && value <= 8 ? value : 1;
+    }
+    return 1;
+}
+export function xmpOrientation(xmp) {
+    const match = /tiff:Orientation\s*(?:=\s*["']|>\s*)([1-8])\b/.exec(xmp);
+    return match ? +match[1] : 1;
+}

package/dist/codecs/gif.d.ts

@@ -0,0 +1,44 @@
+export interface GIFFrame {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    /** Frame delay in centiseconds */
+    delay: number;
+    /** ImageScript disposal mode (0 any, 1 keep, 2 previous, 3 background) */
+    dispose: number;
+    /** RGBA pixel data */
+    pixels: Uint8Array;
+}
+export interface GIFData {
+    width: number;
+    height: number;
+    /** -1 loops forever, 0 plays once, n repeats n times */
+    loopCount: number;
+    frames: GIFFrame[];
+}
+/**
+ * Encodes frames into a GIF
+ * @param {{width: number, height: number, loopCount?: number, frames: GIFFrame[]}} gif loopCount -1 loops forever, 0 plays once, n repeats n times
+ * @param {number} [quality=95] 1-100, scales the palette size (1 = 8 colors, 50 = 55, 90 and above = 256)
+ * @return {Uint8Array}
+ */
+export declare function encode({ width, height, loopCount, frames }: Omit<GIFData, 'loopCount'> & {
+    loopCount?: number;
+}, quality?: number): Uint8Array;
+/**
+ * Decodes a GIF into its individual (uncomposited) frames, zero-sized images are skipped
+ * @param {Uint8Array} data
+ * @param {boolean} [onlyFirstFrame=false]
+ * @return {{width: number, height: number, loopCount: number, frames: GIFFrame[]}}
+ */
+export declare function decode(data: Uint8Array, onlyFirstFrame?: boolean): GIFData;
+/**
+ * Composites decoded frames onto the logical screen, applying their disposal modes
+ * @param {{width: number, height: number, frames: GIFFrame[]}} gif output of {@link decode}
+ * @return {Array<{pixels: Uint8Array, delay: number}>} full screen RGBA frames
+ */
+export declare function composite({ width, height, frames }: GIFData): Array<{
+    pixels: Uint8Array;
+    delay: number;
+}>;