add dropShadow

Author: matmen

CHANGELOG.md

@@ -4,6 +4,7 @@
 
 ### New
 
+- **`image.dropShadow({ x, y, blur, spread, color, expand })`**: a shadow behind the image, shaped by its alpha. Without an offset it is a glow: `image.dropShadow({ blur: 8, spread: 2, color: 0xff2fb9ff })`. The image grows to fit it, unless `expand: false`.
 - **`Image.linearGradient(width, height, { stops, angle })`** and **`Image.radialGradient(width, height, { stops, x, y, radius })`**: images with a gradient, with the angle like CSS' `linear-gradient()`. `stops` are positions and colors like `Colors.gradient()` takes them, or just the colors, evenly spaced.
 - **`image.recolor(otherImage)`**: takes the colors from another image of the same size and keeps the alpha. With a gradient it fills a shape, e.g. gradient text: `text.recolor(Image.linearGradient(text.width, text.height, { stops: [0x22d3eeff, 0xfb923cff], angle: 90 }))`.
 

src/frame.ts

@@ -197,6 +197,23 @@ export class Frame extends Image {
         return Frame.from(this, { duration: this.duration, xOffset: this.xOffset, yOffset: this.yOffset, disposalMode: this.disposalMode });
     }
 
+    /**
+     * @internal
+     * @ignore
+     */
+    protected override __room__(): { left: number, top: number } {
+        return { left: this.xOffset, top: this.yOffset };
+    }
+
+    /**
+     * @internal
+     * @ignore
+     */
+    protected override __grown__(left: number, top: number): void {
+        this.xOffset -= left;
+        this.yOffset -= top;
+    }
+
     /**
      * Removes borders of one color, moving the frame's offsets so the remaining pixels stay in place
      * @param options See {@link TrimOptions}

src/image.ts

@@ -171,6 +171,25 @@ export interface SharpenOptions {
     radius?: number;
 }
 
+/** 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` */
+    x?: number;
+    /** How far to move the shadow down (negative values: up), in pixels. Default: `0` */
+    y?: number;
+    /** How soft the shadow's edge is: the standard deviation of a gaussian blur in pixels, like {@link Image.blur}. Default: `0` */
+    blur?: number;
+    /** How far to grow the shadow's shape before blurring it, in pixels. Default: `0` */
+    spread?: number;
+    /** The shadow's color, its alpha is the shadow's opacity. Default: `0x00000080` (50% black) */
+    color?: Color;
+    /**
+     * Whether to make the image larger so the shadow isn't cut off. Without it, the image keeps its size and the part
+     * of the shadow outside is lost. Default: `true`
+     */
+    expand?: boolean;
+}
+
 /** The colors of a gradient, see {@link Image.linearGradient} */
 export interface GradientOptions {
     /**
@@ -1987,6 +2006,111 @@ export class Image {
         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
+     * the shadow, unless `expand` is `false`. Frames stay where they are (their offsets move with the growth), they only
+     * grow up and left as far as their offset allows
+     * @param options See {@link ShadowOptions}
+     */
+    dropShadow(options: ShadowOptions = {}): this {
+        const { x = 0, y = 0, blur = 0, spread = 0, color = 0x00000080, expand = true } = options;
+        finite(x, 'x');
+        finite(y, 'y');
+        if (finite(blur, 'blur') < 0) throw new RangeError('Invalid blur radius');
+        if (finite(spread, 'spread') < 0) throw new RangeError('Invalid spread');
+        const [r, g, b, a] = Colors.toRGBA(checkColor(color));
+
+        // the shadow's room: the spread and what the blur reaches (3 standard deviations), and a border for the outline
+        const reach = spread + 3 * blur, margin = Math.ceil(reach) + 1;
+        const layer = this.__shape_layer__(margin);
+        const width = layer.width;
+        const coverage = new Uint8Array(width * layer.height);
+        for (let i = 0; i < coverage.length; i++) coverage[i] = layer.bitmap[i * 4 + 3];
+        const grown = spread > 0 ? outline(coverage, width, layer.height, spread) : null;
+        const bitmap = layer.bitmap;
+        for (let i = 0; i < coverage.length; i++) {
+            bitmap[i * 4] = r;
+            bitmap[i * 4 + 1] = g;
+            bitmap[i * 4 + 2] = b;
+            bitmap[i * 4 + 3] = (grown ? grown[i] * 255 : coverage[i]) * a / 255;
+        }
+        if (blur > 0) {
+            layer.blur(blur);
+            // (a flat color: blurring the alpha only, the exact color goes back, 8 bit premultiplied colors drift where it's faint)
+            for (let i = 0; i < coverage.length; i++) {
+                if (!bitmap[i * 4 + 3]) continue;
+                bitmap[i * 4] = r;
+                bitmap[i * 4 + 1] = g;
+                bitmap[i * 4 + 2] = b;
+            }
+        }
+
+        const room = this.__room__();
+        return this.__under__(layer, x - margin, y - margin, expand ? {
+            left: Math.min(room.left, Math.max(0, Math.ceil(reach - x))),
+            top: Math.min(room.top, Math.max(0, Math.ceil(reach - y))),
+            right: Math.max(0, Math.ceil(reach + x)),
+            bottom: Math.max(0, Math.ceil(reach + y))
+        } : { left: 0, top: 0, right: 0, bottom: 0 });
+    }
+
+    /**
+     * A transparent image with this one's alpha in the middle, with a margin all around
+     * @internal
+     * @ignore
+     */
+    protected __shape_layer__(margin: number): Image {
+        const layer = new Image(this.width + 2 * margin, this.height + 2 * margin);
+        for (let y = 0; y < this.height; y++)
+            for (let x = 0; x < this.width; x++)
+                layer.bitmap[((y + margin) * layer.width + x + margin) * 4 + 3] = this.bitmap[(y * this.width + x) * 4 + 3];
+        return layer;
+    }
+
+    /**
+     * Puts a layer behind the image on a larger canvas (the layer's position is relative to the image), keeping the
+     * gain map in place
+     * @internal
+     * @ignore
+     */
+    protected __under__(layer: Image, layerX: number, layerY: number, grow: { left: number, top: number, right: number, bottom: number }): this {
+        const { left, top, right, bottom } = grow;
+        const width = this.width + left + right, height = this.height + top + bottom;
+        const result = new Image(width, height);
+        result.composite(layer, { x: layerX + left, y: layerY + top });
+        const map = this.__gain_map__;
+        this.__gain_map__ = null;
+        try {
+            result.composite(this, { x: left, y: top });
+        } finally {
+            this.__gain_map__ = map;
+        }
+        map?.__transform__(this.width, this.height, width, height, (X, Y) => [X - left, Y - top]);
+        this.__apply__(result);
+        if (left || top) this.__grown__(left, top);
+        return this;
+    }
+
+    /**
+     * How far the image may grow up and left
+     * @internal
+     * @ignore
+     */
+    protected __room__(): { left: number, top: number } {
+        return { left: Infinity, top: Infinity };
+    }
+
+    /**
+     * Called when the image has grown up and left
+     * @internal
+     * @ignore
+     */
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    protected __grown__(_left: number, _top: number): void {
+        // (frames move their offsets)
+    }
+
     /**
      * Sharpens the image with an unsharp mask: the difference to a blurred copy is amplified
      * @param options See {@link SharpenOptions}

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, 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, 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';

tests/regressions.js

@@ -613,10 +613,11 @@ const rgba = (image, x, y) => Image.colorToRGBA(image.getPixelAt(x, y));
         assert(Buffer.from(await map.encode()).equals(Buffer.from(await map.encode({}))), 'GainMap.encode() without arguments');
     }
 
-    // gradients and recolor with an image
+    // gradients, recolor with an image and drop shadows / glows
     {
         const {GainMap} = require('..');
         const px = (image, x, y) => Array.from(image.bitmap.subarray((y * image.width + x) * 4, (y * image.width + x) * 4 + 4));
+        const alphaAt = (image, x, y) => image.bitmap[(y * image.width + x) * 4 + 3];
         const throws = (fn, type, message) => {
             let error = null;
             try { fn(); } catch (e) { error = e; }
@@ -674,6 +675,47 @@ const rgba = (image, x, y) => Image.colorToRGBA(image.getPixelAt(x, y));
         mapped.gainMap = new GainMap(new Image(4, 4).fill(0x808080ff), {gainMapMin: 0, gainMapMax: 2});
         mapped.recolor(Image.linearGradient(8, 8, {stops: [0xff0000ff, 0x0000ffff], angle: 90}));
         assert(px(mapped, 0, 0)[0] > 200 && px(mapped, 7, 0)[2] > 200 && mapped.gainMap && mapped.gainMap.width === 4, 'recolor(image) keeps the gain map');
+
+        // drop shadows and glows
+        const square = () => new Image(10, 10).fill((x, y) => x >= 3 && x < 7 && y >= 3 && y < 7 ? 0xff8040ff : 0);
+        let image = square().dropShadow();
+        assert(image.width === 10 && image.height === 10 && px(image, 4, 4).join() === '255,128,64,255' && px(image, 2, 4)[3] === 0, 'dropShadow() without offset or blur changes nothing outside of the shape');
+        image = square().dropShadow({x: 2, y: 3});
+        assert(image.width === 12 && image.height === 13, `dropShadow({x, y}) grows right and down: ${image.width}x${image.height}`);
+        assert(px(image, 8, 9).join() === '0,0,0,128' && px(image, 4, 4).join() === '255,128,64,255' && px(image, 9, 9)[3] === 0, `dropShadow: the shadow is 50% black behind the shape, shifted: ${px(image, 8, 9)}`);
+        image = square().dropShadow({x: -2, y: -1, color: 0xff0000ff});
+        assert(image.width === 12 && image.height === 11 && px(image, 3, 3).join() === '255,0,0,255' && px(image, 5, 5).join() === '255,128,64,255', `dropShadow({x: -2, y: -1}) grows left and up, the image moves: ${image.width}x${image.height} ${px(image, 3, 3)}`);
+        image = square().dropShadow({x: 2, y: 3, expand: false});
+        assert(image.width === 10 && image.height === 10 && px(image, 8, 9).join() === '0,0,0,128', 'dropShadow({expand: false}) keeps the size');
+        image = square().dropShadow({blur: 2});
+        assert(image.width === 22 && image.height === 22, `dropShadow({blur}) leaves room for the blur (3 deviations): ${image.width}x${image.height}`);
+        assert(alphaAt(image, 3 + 6 - 1, 3 + 6 + 2) > 0 && alphaAt(image, 0, 0) <= 1 && alphaAt(image, 3 + 6 + 1, 3 + 6 + 1) === 255 && px(image, 11, 11).join() === '255,128,64,255', 'dropShadow({blur}): a soft shadow around the shape, the shape on top');
+        image = square().dropShadow({spread: 1.5, color: 0x00ff00ff});
+        assert(image.width === 14 && px(image, 4, 7).join() === '0,255,0,255' && alphaAt(image, 3, 7) > 64 && alphaAt(image, 3, 7) < 192 && alphaAt(image, 2, 7) === 0, `dropShadow({spread}) grows the shape by the spread: ${[2, 3, 4].map(x => alphaAt(image, x, 7))}`);
+        const glowing = square().dropShadow({blur: 3, spread: 1, color: 0xff2fb9ff});
+        let pinks = 0;
+        for (let i = 0; i < glowing.bitmap.length; i += 4)
+            if (glowing.bitmap[i + 3] > 0 && glowing.bitmap[i + 3] < 255) pinks += glowing.bitmap[i] === 255 && glowing.bitmap[i + 1] === 47 && glowing.bitmap[i + 2] === 185 ? 1 : 0;
+        assert(pinks > 200 && pinks === (() => { let n = 0; for (let i = 0; i < glowing.bitmap.length; i += 4) if (glowing.bitmap[i + 3] > 0 && glowing.bitmap[i + 3] < 255) n++; return n; })(), `a glow is exactly the color all around, also where it's faint: ${pinks} pixels`);
+        throws(() => square().dropShadow({blur: -1}), RangeError, 'negative blur');
+        throws(() => square().dropShadow({spread: -1}), RangeError, 'negative spread');
+        throws(() => square().dropShadow({x: NaN}), RangeError, 'NaN offset');
+        const translucent = new Image(6, 6).fill(0xffffff80);
+        const shadowed = translucent.clone().dropShadow({color: 0x000000ff});
+        assert(px(shadowed, 2, 2).join() === px(translucent, 2, 2).join() || px(shadowed, 2, 2)[3] >= 128, 'dropShadow keeps translucent pixels over their shadow');
+
+        // frames stay in place: the offsets move with the growth, up and left only as far as they allow
+        const frame = Frame.from(square(), {duration: 40, xOffset: 2, yOffset: 5}).dropShadow({blur: 2});
+        assert(frame.xOffset === 0 && frame.yOffset === 0 && frame.width === 10 + 2 + 6 && frame.height === 10 + 5 + 6 && frame.duration === 40, `Frame.dropShadow: ${frame.width}x${frame.height} at ${frame.xOffset},${frame.yOffset}`);
+        assert(px(frame, 2 + 4, 5 + 4).join() === '255,128,64,255', 'Frame.dropShadow: the pixels stay where they were on the animation canvas');
+        const farFrame = Frame.from(square(), {xOffset: 20, yOffset: 20}).dropShadow({blur: 1});
+        assert(farFrame.xOffset === 17 && farFrame.yOffset === 17, 'Frame.dropShadow with room moves the offsets by the growth');
+
+        // gain maps grow with the image
+        const hdr = square();
+        hdr.gainMap = new GainMap(new Image(5, 5).fill(0xc0c0c0ff), {gainMapMin: 0, gainMapMax: 2});
+        const hdrShadow = hdr.clone().dropShadow({x: 5, y: 0, blur: 1});
+        assert(hdrShadow.gainMap && Math.abs(hdrShadow.gainMap.width / hdrShadow.width - 0.5) < 0.1 && Math.abs(hdrShadow.gainMap.height / hdrShadow.height - 0.5) < 0.1, 'dropShadow keeps the gain map at its scale');
     }
 
     // Colors: the color helpers, and the deprecated Image ones they replaced, give the same values