add Image.linearGradient and Image.radialGradient

Author: matmen

CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 3.19.0
+
+### New
+
+- **`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.
+
 ## 3.18.0
 
 ### Changes

src/image.ts

@@ -171,6 +171,36 @@ export interface SharpenOptions {
     radius?: number;
 }
 
+/** The colors of a gradient, see {@link Image.linearGradient} */
+export interface GradientOptions {
+    /**
+     * The colors along the gradient: their positions (0..1) and colors, like {@link Colors.gradient} takes them
+     * (`{ 0: 0xff0000ff, 0.5: 0xffff00ff, 1: 0x00ff00ff }`), or just the colors, evenly spaced
+     * (`[0xff0000ff, 0x00ff00ff]`)
+     */
+    stops: Record<number, Color> | Color[];
+}
+
+/** Options of {@link Image.linearGradient} */
+export interface LinearGradientOptions extends GradientOptions {
+    /**
+     * The direction of the gradient in degrees, like CSS' `linear-gradient()`: `0` goes up, `90` to the right, `180`
+     * down, `270` to the left. The first stop is at the start of the line through the center that touches the
+     * corners. Default: `180`
+     */
+    angle?: number;
+}
+
+/** Options of {@link Image.radialGradient} */
+export interface RadialGradientOptions extends GradientOptions {
+    /** The x position of the center in pixels. Default: the middle of the image */
+    x?: number;
+    /** The y position of the center in pixels. Default: the middle of the image */
+    y?: number;
+    /** The radius of the last stop in pixels. Default: the distance to the farthest corner */
+    radius?: number;
+}
+
 /** Options of {@link Image.encode} */
 export interface PNGEncodeOptions {
     /** The compression level (0-9), higher is smaller but slower. Default: `4` */
@@ -769,6 +799,50 @@ export class Image {
         return Colors.toRGB(color);
     }
 
+    /**
+     * Creates an image with a linear gradient, like CSS' `linear-gradient()`
+     * @param width The image's width
+     * @param height The image's height
+     * @param options The colors and the direction, see {@link LinearGradientOptions}
+     * @returns The new image
+     */
+    static linearGradient(width: number, height: number, options: LinearGradientOptions): Image {
+        const { stops, angle = 180 } = options;
+        const color = gradientFunction(stops);
+        finite(angle, 'angle');
+        const image = new Image(width, height);
+        const radians = angle * Math.PI / 180;
+        // the direction (y points down, 0 degrees up), and the length of the line through the center to the corners
+        const dx = Math.sin(radians), dy = -Math.cos(radians);
+        const length = Math.abs(width * dx) + Math.abs(height * dy);
+        const cx = width / 2, cy = height / 2, bitmap = new DataView(image.bitmap.buffer, image.bitmap.byteOffset, image.bitmap.byteLength);
+        for (let y = 0, i = 0; y < height; y++)
+            for (let x = 0; x < width; x++, i += 4)
+                bitmap.setUint32(i, color(((x + 0.5 - cx) * dx + (y + 0.5 - cy) * dy) / length + 0.5), false);
+        return image;
+    }
+
+    /**
+     * Creates an image with a radial (circular) gradient, like CSS' `radial-gradient(circle)`
+     * @param width The image's width
+     * @param height The image's height
+     * @param options The colors and the circle, see {@link RadialGradientOptions}
+     * @returns The new image
+     */
+    static radialGradient(width: number, height: number, options: RadialGradientOptions): Image {
+        const { stops, x: cx = width / 2, y: cy = height / 2, radius = Math.hypot(Math.max(cx, width - cx), Math.max(cy, height - cy)) } = options;
+        const color = gradientFunction(stops);
+        finite(cx, 'x');
+        finite(cy, 'y');
+        if (!(finite(radius, 'radius') > 0)) throw new RangeError('Invalid radius');
+        const image = new Image(width, height);
+        const bitmap = new DataView(image.bitmap.buffer, image.bitmap.byteOffset, image.bitmap.byteLength);
+        for (let y = 0, i = 0; y < height; y++)
+            for (let x = 0; x < width; x++, i += 4)
+                bitmap.setUint32(i, color(Math.hypot(x + 0.5 - cx, y + 0.5 - cy) / radius), false);
+        return image;
+    }
+
     /**
      * Creates a multi-point gradient generator
      * @param colors The gradient points to use (e.g. `{0: 0xff0000ff, 1: 0x00ff00ff}`)
@@ -2992,6 +3066,15 @@ const BLEND_MODES: Record<BlendMode, (backdrop: number, source: number) => numbe
     'add': (b, s) => Math.min(1, b + s)
 };
 
+// the color at every position of a gradient, from its stops
+function gradientFunction(stops: Record<number, Color> | Color[]): (position: number) => Color {
+    if (!Array.isArray(stops)) return Colors.gradient(stops);
+    if (!stops.length) throw new RangeError('Invalid gradient point count');
+    // (one color is a gradient of two equal ones)
+    const colors = stops.length === 1 ? [stops[0], stops[0]] : stops;
+    return Colors.gradient(Object.fromEntries(colors.map((color, i) => [i / (colors.length - 1), color])));
+}
+
 /**
  * Grows a coverage mask by a radius, using the distance of every pixel to the glyphs (an exact euclidean distance
  * transform, so the cost doesn't depend on the radius). Near the outline's edge, the distance goes to the glyph edge

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, 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, 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,6 +613,54 @@ 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
+    {
+        const px = (image, x, y) => Array.from(image.bitmap.subarray((y * image.width + x) * 4, (y * image.width + x) * 4 + 4));
+        const throws = (fn, type, message) => {
+            let error = null;
+            try { fn(); } catch (e) { error = e; }
+            assert(error instanceof type, `${message}: should throw a ${type.name}, got ${error}`);
+        };
+        const stops = {0: 0xff0000ff, 0.5: 0x00ff00ff, 1: 0x0000ffff};
+        const gradient = ColorHelpers.gradient(stops);
+        const rgba = color => ColorHelpers.toRGBA(color);
+
+        // linear gradients follow Colors.gradient along CSS' directions (0 up, 90 right, 180 down, 270 left)
+        for (const [angle, at] of [[90, x => [x, 0, (x + 0.5) / 4]], [270, x => [x, 0, 1 - (x + 0.5) / 4]]]) {
+            const horizontal = Image.linearGradient(4, 1, {stops, angle});
+            for (let x = 0; x < 4; x++) {
+                const [X, Y, t] = at(x);
+                assert(px(horizontal, X, Y).join() === rgba(gradient(t)).join(), `linearGradient ${angle}deg, x ${x}: ${px(horizontal, X, Y)} vs ${rgba(gradient(t))}`);
+            }
+        }
+        for (const [angle, t] of [[180, y => (y + 0.5) / 4], [0, y => 1 - (y + 0.5) / 4]]) {
+            const vertical = Image.linearGradient(1, 4, {stops, angle});
+            for (let y = 0; y < 4; y++)
+                assert(px(vertical, 0, y).join() === rgba(gradient(t(y))).join(), `linearGradient ${angle}deg, y ${y}`);
+        }
+        const defaultDirection = Image.linearGradient(2, 3, {stops: [0xff0000ff, 0x0000ffff]});
+        assert(px(defaultDirection, 0, 0).join() === px(defaultDirection, 1, 0).join() && px(defaultDirection, 0, 0)[0] > px(defaultDirection, 0, 2)[0], 'linearGradient goes down by default');
+        const diagonal = Image.linearGradient(8, 8, {stops: [0x000000ff, 0xffffffff], angle: 135});
+        assert(px(diagonal, 0, 0)[0] < 20 && px(diagonal, 7, 7)[0] > 235 && px(diagonal, 7, 0).join() === px(diagonal, 0, 7).join(), 'linearGradient at 135deg runs from corner to corner');
+        // (an array of colors is evenly spaced, one color is a plain fill, alpha is part of the color)
+        assert(px(Image.linearGradient(3, 1, {stops: [0xff0000ff, 0x00ff00ff, 0x0000ffff], angle: 90}), 1, 0).join() === rgba(ColorHelpers.gradient({0: 0xff0000ff, 0.5: 0x00ff00ff, 1: 0x0000ffff})(0.5)).join(), 'linearGradient with an array of colors');
+        assert(px(Image.linearGradient(3, 3, {stops: [0x336699ff]}), 2, 2).join() === '51,102,153,255', 'linearGradient with one color');
+        assert(px(Image.linearGradient(2, 1, {stops: [0xff000000, 0xff0000ff], angle: 90}), 0, 0)[3] < 100, 'linearGradient keeps alpha');
+
+        // radial gradients: the center is the first stop, the radius the last
+        const radial = Image.radialGradient(9, 9, {stops: [0xffffffff, 0x000000ff]});
+        assert(px(radial, 4, 4)[0] > 240 && px(radial, 0, 0)[0] < 40 && px(radial, 0, 8).join() === px(radial, 8, 0).join(), 'radialGradient from the center to the farthest corner');
+        const circle = Image.radialGradient(20, 20, {stops: [0xff0000ff, 0x0000ffff], x: 5.5, y: 5.5, radius: 4});
+        assert(px(circle, 5, 5)[0] > 240 && px(circle, 15, 15).join() === '0,0,255,255' && px(circle, 9, 5)[2] > 200, 'radialGradient with a center and a radius');
+        for (const [name, call] of Object.entries({
+            'no stops': () => Image.linearGradient(2, 2, {stops: []}),
+            'no stops (object)': () => Image.radialGradient(2, 2, {stops: {}}),
+            'NaN angle': () => Image.linearGradient(2, 2, {stops: [1, 2], angle: NaN}),
+            'zero radius': () => Image.radialGradient(2, 2, {stops: [1, 2], radius: 0}),
+            'NaN center': () => Image.radialGradient(2, 2, {stops: [1, 2], x: NaN})
+        })) throws(call, RangeError, name);
+    }
+
     // Colors: the color helpers, and the deprecated Image ones they replaced, give the same values
     {
         const { Colors } = require('..');