add colorMatrix

Author: matmen

CHANGELOG.md

@@ -6,6 +6,7 @@
 
 - **`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 `Image`s; 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.
 
 ## 3.19.0
 

src/image.ts

@@ -2105,6 +2105,43 @@ export class Image {
         return this;
     }
 
+    /**
+     * Mixes the colors of every pixel with a color matrix, like SVG's `feColorMatrix`: the new red, green, blue and alpha
+     * are each a sum of the old red, green, blue and alpha times a factor, plus an offset. Greyscale, sepia, tints,
+     * swapped channels, color blindness simulation or a mix of those in one pass.
+     *
+     * The values are 20 numbers, four rows of `[red, green, blue, alpha, offset]` for the new red, green, blue and alpha,
+     * with the colors and the offsets as 0 to 1 (like CSS and SVG): `[1, 0, 0, 0, 0,  0, 1, 0, 0, 0,  0, 0, 1, 0, 0,
+     * 0, 0, 0, 1, 0]` changes nothing, `[0, 0, 1, 0, 0,  0, 1, 0, 0, 0,  1, 0, 0, 0, 0,  0, 0, 0, 1, 0]` swaps red and
+     * blue. Nine numbers are the first three rows without the alpha and the offsets (the alpha stays as it is). The
+     * colors are the sRGB values, not premultiplied, and the results are clamped. With a gain map (an HDR image), the
+     * HDR highlights follow the change as they do for other color changes
+     * @param matrix The 9 or 20 values
+     */
+    colorMatrix(matrix: ArrayLike<number>): this {
+        if (matrix === null || typeof matrix !== 'object' || (matrix.length !== 9 && matrix.length !== 20))
+            throw new RangeError('A color matrix has 9 or 20 values');
+        const m = new Float64Array(20);
+        // (numbers only: a string is a mistake in data like this)
+        const value = (v: unknown): number => finite(typeof v === 'number' ? v : NaN, 'color matrix value');
+        if (matrix.length === 20) for (let i = 0; i < 20; i++) m[i] = value(matrix[i]);
+        else for (let row = 0; row < 3; row++) for (let column = 0; column < 3; column++) m[row * 5 + column] = value(matrix[row * 3 + column]);
+        // (nine values leave the alpha as it is)
+        if (matrix.length === 9) m[18] = 1;
+
+        if (this.__gain_map__) return this.__recolor__(image => image.colorMatrix(m));
+        const bitmap = this.bitmap;
+        for (let i = 0; i < bitmap.length; i += 4) {
+            const r = bitmap[i], g = bitmap[i + 1], b = bitmap[i + 2], a = bitmap[i + 3];
+            // (the offsets are 0 to 1, the values 0 to 255; the clamped array rounds and clamps)
+            bitmap[i] = m[0] * r + m[1] * g + m[2] * b + m[3] * a + m[4] * 255;
+            bitmap[i + 1] = m[5] * r + m[6] * g + m[7] * b + m[8] * a + m[9] * 255;
+            bitmap[i + 2] = m[10] * r + m[11] * g + m[12] * b + m[13] * a + m[14] * 255;
+            bitmap[i + 3] = m[15] * r + m[16] * g + m[17] * b + m[18] * a + m[19] * 255;
+        }
+        return this;
+    }
+
     /**
      * Adds a shadow behind the image, shaped by its alpha: a drop shadow with an offset, or a glow without one
      * (`image.dropShadow({ blur: 8, color: 0xff2fb9ff })`, with `spread` to make it stronger). The image grows to fit

tests/color-matrix.js

@@ -0,0 +1,64 @@
+const {Image, Frame, GainMap} = require('..');
+
+const panic = message => {
+    console.error(message);
+    process.exit(1);
+};
+const check = (condition, message) => {
+    if (!condition) panic(message);
+};
+const throwsA = (fn, type, label) => {
+    let error = null;
+    try { fn(); } catch (e) { error = e; }
+    if (!(error instanceof type)) panic(`${label}: should throw a ${type.name}, got ${error}`);
+};
+const px = (image, x, y) => Array.from(image.bitmap.subarray((y * image.width + x) * 4, (y * image.width + x) * 4 + 4));
+const same = (a, b) => a.width === b.width && a.height === b.height && Buffer.from(a.bitmap).equals(Buffer.from(b.bitmap));
+// an opaque image where every pixel is different
+const photo = (width, height) => new Image(width, height).fill((x, y) => Image.rgbaToColor((x * 37 + y * 11) % 256, (x * 5 + y * 91) % 256, (x * y + x) % 256, 255));
+const IDENTITY = [1, 0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 1, 0];
+
+(async () => {
+    // colorMatrix
+    {
+        const source = new Image(3, 2).fill((x, y) => [0x0a141ec8, 0x64c8ffff, 0xff000000, 0x00ff0080, 0x336699ff, 0xffffffff][y * 3 + x]);
+        check(same(source.clone().colorMatrix(IDENTITY), source), 'colorMatrix: the identity changes nothing');
+        check(same(source.clone().colorMatrix([1, 0, 0, 0, 1, 0, 0, 0, 1]), source), 'colorMatrix: the 3x3 identity changes nothing');
+        check(same(source.clone().colorMatrix(new Float32Array(IDENTITY)), source), 'colorMatrix: typed arrays are values too');
+        // red and blue swapped, the alpha as it is
+        const swapped = source.clone().colorMatrix([0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, 1, 0]);
+        check(px(swapped, 0, 0).join() === '30,20,10,200', `colorMatrix: swapped channels ${px(swapped, 0, 0)}`);
+        check(same(source.clone().colorMatrix([0, 0, 1, 0, 1, 0, 1, 0, 0]), source.clone().colorMatrix([0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, 1, 0])), 'colorMatrix: nine values are twenty with the alpha left alone');
+        // offsets are 0 to 1, the alpha row can set the alpha
+        check(px(source.clone().colorMatrix([1, 0, 0, 0, 0.2, 0, 1, 0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 1, 0]), 0, 0).join() === '61,20,30,200', 'colorMatrix: offsets are 0 to 1');
+        check(px(source.clone().colorMatrix([1, 0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 1]), 2, 0).join() === '255,0,0,255', 'colorMatrix: an offset in the alpha row makes it opaque');
+        check(px(source.clone().colorMatrix([1, 0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0.5, 0]), 1, 0)[3] === 128, 'colorMatrix: the alpha is scaled');
+        // greyscale by the luminance: 0.2126 * 100 + 0.7152 * 150 + 0.0722 * 200 = 143
+        const luma = [0.2126, 0.7152, 0.0722, 0, 0];
+        const grey = new Image(1, 1).fill(0x6496c8ff).colorMatrix([...luma, ...luma, ...luma, 0, 0, 0, 1, 0]);
+        check(px(grey, 0, 0).join() === '143,143,143,255', `colorMatrix: greyscale ${px(grey, 0, 0)}`);
+        // results are clamped
+        check(px(new Image(1, 1).fill(0x6496c8ff).colorMatrix([3, 0, 0, 0, 0, -1, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 1, 0]), 0, 0).join() === '255,0,200,255', 'colorMatrix: clamped');
+        // the sepia() of the library is such a matrix
+        const sepia = [0.393, 0.769, 0.189, 0, 0, 0.349, 0.686, 0.168, 0, 0, 0.272, 0.534, 0.131, 0, 0, 0, 0, 0, 1, 0];
+        check(same(photo(20, 15).colorMatrix(sepia), photo(20, 15).sepia()), 'colorMatrix: the sepia matrix is sepia()');
+
+        for (const [label, bad] of Object.entries({
+            'eight values': new Array(8).fill(1), 'twenty-one values': new Array(21).fill(0), 'none': [], 'a number': 5, 'null': null, 'NaN': [...IDENTITY.slice(0, 19), NaN],
+            'a string': [...IDENTITY.slice(0, 19), '1'], 'Infinity': [Infinity, ...IDENTITY.slice(1)]
+        })) {
+            const image = photo(4, 4), before = image.bitmap.slice();
+            throwsA(() => image.colorMatrix(bad), RangeError, `colorMatrix with ${label}`);
+            check(Buffer.from(image.bitmap).equals(Buffer.from(before)), `colorMatrix with ${label}: the image should be unchanged`);
+        }
+
+        const frame = Frame.from(photo(4, 4), {duration: 40, xOffset: 2, yOffset: 3}).colorMatrix(sepia);
+        check(frame instanceof Frame && frame.duration === 40 && frame.xOffset === 2 && frame.yOffset === 3 && same(frame, photo(4, 4).sepia()), 'colorMatrix on a frame');
+
+        const hdr = photo(8, 8);
+        hdr.gainMap = new GainMap(new Image(4, 4).fill(0xc0c0c0ff), {gainMapMin: 0, gainMapMax: 2});
+        hdr.colorMatrix(sepia);
+        check(hdr.gainMap && hdr.gainMap.width === 4 && hdr.gainMap.height === 4, 'colorMatrix with a gain map keeps it');
+        check((await Image.decode(await hdr.encodeJPEG())).gainMap, 'colorMatrix: the gain map is still encoded');
+    }
+})().catch(error => panic(error.stack || String(error)));