add transform

Author: matmen

CHANGELOG.md

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

src/image.ts

@@ -37,6 +37,8 @@ import { isOptions, finite, color as checkColor, quality as checkQuality, effort
 import { MAX_PIXELS, decoding } from './util/limits.ts';
 import { GainMap } from './gainmap.ts';
 import * as gain from './util/gain.ts';
+import { multiply, invert } from './util/matrix.ts';
+import { sampleAffine } from './util/affine.ts';
 import * as gainMapCodec from './codecs/gainmap.ts';
 
 /** A color as a 32-bit RGBA integer (`0xRRGGBBAA`) */
@@ -203,6 +205,38 @@ export interface QuantizeOptions {
     ditherStrength?: number;
 }
 
+/** How {@link Image.transform} samples the pixels between the source's */
+export type TransformMode = 'nearest-neighbor' | 'bilinear' | 'bicubic';
+
+// the sampling modes of Image.transform()
+const TRANSFORM_MODES: readonly string[] = ['nearest-neighbor', 'bilinear', 'bicubic'];
+
+/** Options of {@link Image.transform} */
+export interface TransformOptions {
+    /**
+     * The point the transform is applied around, in pixels: a rotation turns around it, a scale grows from it.
+     * Default: the middle of the image. It only decides where the result lies on a canvas that stays as large as the
+     * image (`expand: false`)
+     */
+    origin?: {
+        /** The x position of the point in pixels. Default: half the width */
+        x?: number;
+        /** The y position of the point in pixels. Default: half the height */
+        y?: number;
+    };
+    /**
+     * Whether to make the image as large as the transformed one, which then fills it (a rotated image grows to fit its
+     * corners, a skewed one gets wider). Without it, the image keeps its size and the parts outside are lost. Frames
+     * only grow up and left as far as their offset allows. Default: `true`
+     */
+    expand?: boolean;
+    /**
+     * How the pixels between the source's are sampled: `'nearest-neighbor'` (hard pixels, no smoothing, for pixel art),
+     * `'bilinear'` (smooth), `'bicubic'` (sharper, slower, can overshoot a little at hard edges). Default: `'bilinear'`
+     */
+    mode?: TransformMode;
+}
+
 /** Options of {@link Image.dropShadow} */
 export interface ShadowOptions {
     /** How far to move the shadow to the right (negative values: to the left), in pixels. Default: `0` */
@@ -2142,6 +2176,81 @@ export class Image {
         return this;
     }
 
+    /**
+     * 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 numbers are SVG's `matrix(a b c d e f)`: a point (x, y) of the
+     * image ends up at (a x + c y + e, b x + d y + f), with y pointing down.
+     * ```ts
+     * image.transform([1, 0, Math.tan(-0.3), 1, 0, 0]);             // slanted like italics, around the middle
+     * image.transform([0.5, 0, 0, 0.5, 0, 0], { origin: { x: 0, y: 0 } }); // half the size
+     * image.transform([-1, 0, 0, 1, 0, 0]);                         // flipped horizontally
+     * const a = Math.PI / 6;
+     * image.transform([Math.cos(a), Math.sin(a), -Math.sin(a), Math.cos(a), 0, 0]); // turned 30° clockwise
+     * ```
+     * The image grows to hold the result (`expand: false` keeps its size), so a shift only shows with `expand: false`.
+     * The edges fade, like the pixels outside were transparent. A transform that flattens the image (a factor of 0) is
+     * refused. With a gain map (an HDR image), the map moves with the image
+     * @param matrix The six values [a, b, c, d, e, f]
+     * @param options See {@link TransformOptions}
+     */
+    transform(matrix: ArrayLike<number>, options: TransformOptions = {}): this {
+        if (matrix === null || typeof matrix !== 'object' || matrix.length !== 6) throw new RangeError('A transform has 6 values: [a, b, c, d, e, f]');
+        // (numbers only: a string is a mistake in data like this)
+        const values = Array.from({ length: 6 }, (_, i) => finite(typeof matrix[i] === 'number' ? matrix[i] : NaN, 'transform value'));
+        if (typeof options !== 'object' || options === null) throw new TypeError('transform takes an options object');
+        const { origin = {}, expand = true, mode = 'bilinear' } = options;
+        if (!TRANSFORM_MODES.includes(mode)) throw new TypeError(`transform mode must be one of ${TRANSFORM_MODES.map(name => `'${name}'`).join(', ')}, not ${String(mode)}`);
+        const { x: pivotX = this.width / 2, y: pivotY = this.height / 2 } = origin;
+        finite(pivotX, 'origin x');
+        finite(pivotY, 'origin y');
+
+        // around the origin: move it to (0, 0), transform, move it back
+        const around = multiply(multiply([1, 0, 0, 1, pivotX, pivotY], values), [1, 0, 0, 1, -pivotX, -pivotY]);
+        const inverse = invert(around);
+        if (!inverse) throw new RangeError('The transform has to be invertible: it can\'t flatten the image');
+
+        const { width, height } = this;
+        // (the canvas's top left corner in the transformed space, which isn't on a pixel border for a scale around the
+        // middle of an image of odd size: then the grid starts there, so that doubling an image is exactly doubling)
+        let left = 0, top = 0, outWidth = width, outHeight = height;
+        if (expand) {
+            const xs: number[] = [], ys: number[] = [];
+            for (const [x, y] of [[0, 0], [width, 0], [0, height], [width, height]]) {
+                xs.push(around[0] * x + around[2] * y + around[4]);
+                ys.push(around[1] * x + around[3] * y + around[5]);
+            }
+            const minX = Math.min(...xs), maxX = Math.max(...xs), minY = Math.min(...ys), maxY = Math.max(...ys);
+            // the size rounds, the transformed image is centered on the canvas (a turned image is a bit off a pixel size)
+            outWidth = Math.max(1, Math.round(maxX - minX));
+            outHeight = Math.max(1, Math.round(maxY - minY));
+            left = minX - (outWidth - (maxX - minX)) / 2;
+            top = minY - (outHeight - (maxY - minY)) / 2;
+            // frames only grow as far up and left as their offset allows
+            const room = this.__room__();
+            if (left < -room.left) {
+                left = -room.left;
+                outWidth = Math.max(1, Math.round(maxX - left));
+            }
+            if (top < -room.top) {
+                top = -room.top;
+                outHeight = Math.max(1, Math.round(maxY - top));
+            }
+            if (outWidth * outHeight > MAX_PIXELS) throw new RangeError(`The transformed image would have ${outWidth}x${outHeight} pixels, more than the ${MAX_PIXELS} allowed`);
+        }
+
+        const out = new Image(outWidth, outHeight);
+        sampleAffine(this.bitmap, width, height, out.bitmap, outWidth, outHeight, inverse, left, top, mode);
+        const scale = Math.sqrt(Math.abs(around[0] * around[3] - around[1] * around[2]));
+        this.__gain_map__?.__transform__(width, height, outWidth, outHeight, (X, Y) => {
+            const x = X + left, y = Y + top;
+            return [inverse[0] * x + inverse[2] * y + inverse[4], inverse[1] * x + inverse[3] * y + inverse[5]];
+        }, scale);
+        this.__apply__(out);
+        // (a frame's offsets are whole pixels)
+        if (left || top) this.__grown__(-Math.round(left), -Math.round(top));
+        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

src/index.ts

@@ -9,7 +9,7 @@ import { ImageType } from './image-type.ts';
 
 export { Image, ResizeModes, SVGScaleModes } from './image.ts';
 export { Colors } from './colors.ts';
-export type { Color, ColorFunction, ResizeMode, SVGScaleMode, PNGMetadata, TextStyle, DecodeOptions, CompositeOptions, BlendMode, CropCircleOptions, DominantColorOptions, RotateOptions, ColorToAlphaOptions, ResizeOptions, ResizeToOptions, AdjustOptions, SharpenOptions, PNGEncodeOptions, JPEGEncodeOptions, WebPEncodeOptions, AVIFEncodeOptions, JXLEncodeOptions, EncodeOptions, SVGOptions, TextOptions, RenderTextOptions, ShadowOptions, OutlineOptions, QuantizeOptions, GradientOptions, LinearGradientOptions, RadialGradientOptions, RoundCornersOptions, FisheyeOptions, TrimOptions } from './image.ts';
+export type { Color, ColorFunction, ResizeMode, SVGScaleMode, PNGMetadata, TextStyle, DecodeOptions, CompositeOptions, BlendMode, CropCircleOptions, DominantColorOptions, RotateOptions, ColorToAlphaOptions, ResizeOptions, ResizeToOptions, AdjustOptions, SharpenOptions, PNGEncodeOptions, JPEGEncodeOptions, WebPEncodeOptions, AVIFEncodeOptions, JXLEncodeOptions, EncodeOptions, SVGOptions, TextOptions, RenderTextOptions, ShadowOptions, OutlineOptions, QuantizeOptions, TransformOptions, TransformMode, GradientOptions, LinearGradientOptions, RadialGradientOptions, RoundCornersOptions, FisheyeOptions, TrimOptions } from './image.ts';
 export { Frame, FrameDisposalModes } from './frame.ts';
 export type { FrameDisposalModeName, FrameDisposalModeId, FrameOptions } from './frame.ts';
 export { GainMap } from './gainmap.ts';

src/util/affine.ts

@@ -0,0 +1,96 @@
+// resampling an image through an affine transform, on straight (non premultiplied) 8-bit RGBA
+
+import type { Matrix } from './matrix.ts';
+
+/** How the pixels between the source's are sampled */
+export type SampleMode = 'nearest-neighbor' | 'bilinear' | 'bicubic';
+
+// Catmull-Rom weights of the four taps around a position (t is the fraction between the 2nd and the 3rd)
+function cubic(t: number, out: Float64Array): void {
+    const t2 = t * t, t3 = t2 * t;
+    out[0] = -0.5 * t3 + t2 - 0.5 * t;
+    out[1] = 1.5 * t3 - 2.5 * t2 + 1;
+    out[2] = -1.5 * t3 + 2 * t2 + 0.5 * t;
+    out[3] = 0.5 * t3 - 0.5 * t2;
+}
+
+/**
+ * Fills `out` with the source as seen through `inverse` (the transform from the output's space to the source's: x' = a x
+ * + c y + e, y' = b x + d y + f). The output's top left pixel is at (`left`, `top`) in that space. Positions are
+ * continuous (pixel x spans x to x + 1) and samples are taken at pixel centers, so the identity copies the source.
+ * Pixels outside of the source are transparent: the edges fade, like the taps outside were transparent. Colors are
+ * weighted by their alpha, so transparent pixels don't bleed their color
+ */
+export function sampleAffine(src: Uint8ClampedArray, width: number, height: number, out: Uint8ClampedArray, outWidth: number, outHeight: number, inverse: Matrix, left: number, top: number, mode: SampleMode): void {
+    const [a, b, c, d, e, f] = inverse;
+    const wx = new Float64Array(4), wy = new Float64Array(4);
+
+    for (let oy = 0; oy < outHeight; oy++) {
+        const y = oy + top + 0.5;
+        // the source position of the row's first pixel center, then a step per pixel
+        const sx0 = a * (left + 0.5) + c * y + e, sy0 = b * (left + 0.5) + d * y + f;
+
+        for (let ox = 0; ox < outWidth; ox++) {
+            const sx = sx0 + a * ox, sy = sy0 + b * ox;
+            const o = 4 * (oy * outWidth + ox);
+
+            if (mode === 'nearest-neighbor') {
+                const ix = Math.floor(sx), iy = Math.floor(sy);
+                if (ix < 0 || iy < 0 || ix >= width || iy >= height) continue;
+                const i = 4 * (iy * width + ix);
+                out[o] = src[i];
+                out[o + 1] = src[i + 1];
+                out[o + 2] = src[i + 2];
+                out[o + 3] = src[i + 3];
+                continue;
+            }
+
+            // the taps are at pixel centers
+            const u = sx - 0.5, v = sy - 0.5;
+            const x0 = Math.floor(u), y0 = Math.floor(v), fx = u - x0, fy = v - y0;
+            let r = 0, g = 0, bl = 0, alpha = 0;
+
+            if (mode === 'bilinear') {
+                if (x0 < -1 || y0 < -1 || x0 >= width || y0 >= height) continue;
+                for (let j = 0; j < 2; j++) {
+                    const yy = y0 + j;
+                    if (yy < 0 || yy >= height) continue;
+                    const weightY = j ? fy : 1 - fy;
+                    for (let i = 0; i < 2; i++) {
+                        const xx = x0 + i;
+                        if (xx < 0 || xx >= width) continue;
+                        const p = 4 * (yy * width + xx), weight = (i ? fx : 1 - fx) * weightY * src[p + 3];
+                        r += weight * src[p];
+                        g += weight * src[p + 1];
+                        bl += weight * src[p + 2];
+                        alpha += weight;
+                    }
+                }
+            } else {
+                if (x0 < -2 || y0 < -2 || x0 > width || y0 > height) continue;
+                cubic(fx, wx);
+                cubic(fy, wy);
+                for (let j = 0; j < 4; j++) {
+                    const yy = y0 - 1 + j;
+                    if (yy < 0 || yy >= height) continue;
+                    for (let i = 0; i < 4; i++) {
+                        const xx = x0 - 1 + i;
+                        if (xx < 0 || xx >= width) continue;
+                        const p = 4 * (yy * width + xx), weight = wx[i] * wy[j] * src[p + 3];
+                        r += weight * src[p];
+                        g += weight * src[p + 1];
+                        bl += weight * src[p + 2];
+                        alpha += weight;
+                    }
+                }
+            }
+
+            if (alpha <= 0) continue;
+            // (the clamped array rounds and clamps on assignment: the lobes of the cubic can overshoot)
+            out[o] = r / alpha;
+            out[o + 1] = g / alpha;
+            out[o + 2] = bl / alpha;
+            out[o + 3] = alpha;
+        }
+    }
+}