add outline

Author: matmen

CHANGELOG.md

@@ -5,6 +5,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.outline({ width, color, expand })`**: an outline around the image's shape, the sticker effect for cut-out images or an outline for rendered text. It follows the edge's antialiasing, like the `strokeWidth` of `renderText()` does.
 - **`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/image.ts

@@ -190,6 +190,19 @@ export interface ShadowOptions {
     expand?: boolean;
 }
 
+/** Options of {@link Image.outline} */
+export interface OutlineOptions {
+    /** The outline's width in pixels. Default: `1` */
+    width?: number;
+    /** The outline's color. Default: `0x000000ff` */
+    color?: Color;
+    /**
+     * Whether to make the image larger so the outline isn't cut off. Without it, the image keeps its size and the
+     * outline is cut where the image ends. Default: `true`
+     */
+    expand?: boolean;
+}
+
 /** The colors of a gradient, see {@link Image.linearGradient} */
 export interface GradientOptions {
     /**
@@ -2055,6 +2068,38 @@ export class Image {
         } : { left: 0, top: 0, right: 0, bottom: 0 });
     }
 
+    /**
+     * Draws an outline around the image's shape (its alpha): the sticker effect for cut-out images, or an outline for
+     * text. The image grows to fit it, 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 OutlineOptions}
+     */
+    outline(options: OutlineOptions = {}): this {
+        const { width = 1, color = 0x000000ff, expand = true } = options;
+        if (finite(width, 'outline width') < 0) throw new RangeError('Invalid outline width');
+        const [r, g, b, a] = Colors.toRGBA(checkColor(color));
+        if (width === 0) return this;
+
+        const margin = Math.ceil(width) + 1;
+        const layer = this.__shape_layer__(margin);
+        const coverage = new Uint8Array(layer.width * layer.height);
+        for (let i = 0; i < coverage.length; i++) coverage[i] = layer.bitmap[i * 4 + 3];
+        const stroke = outline(coverage, layer.width, layer.height, width);
+        const bitmap = layer.bitmap;
+        for (let i = 0; i < coverage.length; i++) {
+            // (around the shape only: it shows through translucent pixels neither)
+            bitmap[i * 4] = r;
+            bitmap[i * 4 + 1] = g;
+            bitmap[i * 4 + 2] = b;
+            bitmap[i * 4 + 3] = stroke[i] * (1 - coverage[i] / 255) * a;
+        }
+
+        const room = this.__room__(), grow = Math.ceil(width);
+        return this.__under__(layer, -margin, -margin, expand
+            ? { left: Math.min(room.left, grow), top: Math.min(room.top, grow), right: grow, bottom: grow }
+            : { 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

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, 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, 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,7 +613,7 @@ 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, recolor with an image and drop shadows / glows
+    // gradients, recolor with an image, drop shadows / glows and outlines
     {
         const {GainMap} = require('..');
         const px = (image, x, y) => Array.from(image.bitmap.subarray((y * image.width + x) * 4, (y * image.width + x) * 4 + 4));
@@ -716,6 +716,25 @@ const rgba = (image, x, y) => Image.colorToRGBA(image.getPixelAt(x, y));
         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');
+
+        // outlines
+        const outlined = square().outline({width: 2, color: 0xff0000ff});
+        assert(outlined.width === 14 && outlined.height === 14, `outline({width}) grows by the width on every side: ${outlined.width}x${outlined.height}`);
+        assert(px(outlined, 2 + 4, 2 + 4).join() === '255,128,64,255', 'outline keeps the shape');
+        assert(px(outlined, 2 + 2, 2 + 4).join() === '255,0,0,255' && px(outlined, 2 + 1, 2 + 4)[3] > 100 && alphaAt(outlined, 0, 2 + 4) === 0 && alphaAt(outlined, 2 + 3, 0) === 0, `outline: the stroke is next to the shape and as wide as asked: ${px(outlined, 4, 6)} ${px(outlined, 3, 6)} ${px(outlined, 0, 6)}`);
+        assert(alphaAt(outlined, 2 + 3 - 1, 2 + 3 - 1) > 200 && alphaAt(outlined, 2 + 3 - 2, 2 + 3 - 2) < 128, 'outline rounds the corners');
+        const clipped = square().outline({width: 2, expand: false});
+        assert(clipped.width === 10 && px(clipped, 2, 4).join() === '0,0,0,255' && px(clipped, 4, 4).join() === '255,128,64,255', 'outline({expand: false}) keeps the size');
+        assert(square().outline({width: 0}).width === 10 && Buffer.from(square().outline({width: 0}).bitmap).equals(Buffer.from(square().bitmap)), 'outline({width: 0}) does nothing');
+        assert(px(square().outline({width: 1, color: 0x00ff0080}), 2 + 2, 2 + 4).slice(3).join() === '128' || Math.abs(alphaAt(square().outline({width: 1, color: 0x00ff0080}), 3 - 1 + 1, 3 + 2 + 1) - 128) <= 1, 'outline with a translucent color');
+        const holey = new Image(9, 9).fill((x, y) => x >= 2 && x < 7 && y >= 2 && y < 7 && !(x === 4 && y === 4) ? 0xffffffff : 0);
+        assert(alphaAt(holey.clone().outline({width: 1, color: 0x000000ff}), 1 + 4, 1 + 4) === 255, 'outline fills small holes of the shape');
+        throws(() => square().outline({width: -1}), RangeError, 'negative outline width');
+        throws(() => square().outline({width: Infinity}), RangeError, 'infinite outline width');
+        const outlinedFrame = Frame.from(square(), {xOffset: 1, yOffset: 4}).outline({width: 3});
+        assert(outlinedFrame.xOffset === 0 && outlinedFrame.yOffset === 1 && outlinedFrame.width === 10 + 1 + 3 && outlinedFrame.height === 10 + 3 + 3, `Frame.outline: ${outlinedFrame.width}x${outlinedFrame.height} at ${outlinedFrame.xOffset},${outlinedFrame.yOffset}`);
+        const glowOnText = new Image(12, 12).fill((x, y) => (x - 5.5) ** 2 + (y - 5.5) ** 2 < 16 ? 0xffffffff : 0).outline({width: 2, color: 0xfacc15ff}).dropShadow({blur: 1, y: 2});
+        assert(glowOnText.width > 16 && glowOnText.height > 18, 'outline and dropShadow chain');
     }
 
     // Colors: the color helpers, and the deprecated Image ones they replaced, give the same values