move frame offsets with every size-changing method and add them to Animation

Author: matmen

src/animation.ts

@@ -6,7 +6,7 @@ import * as jxl from './codecs/jxl.ts';
 import { availableThreads } from './util/threads.ts';
 import { BinaryData, view } from './util/mem.ts';
 import { GainMap } from './gainmap.ts';
-import { Image, DecodeOptions, EncodeOptions, GIFEncodeOptions, ContainOptions, ResizeOptions, ResizeToOptions, resizeArguments, insideSize } from './image.ts';
+import { Image, DecodeOptions, EncodeOptions, GIFEncodeOptions, ContainOptions, ResizeOptions, ResizeToOptions, RotateOptions, TransformOptions, ShadowOptions, OutlineOptions, TrimOptions, resizeArguments, insideSize } from './image.ts';
 import { Frame } from './frame.ts';
 import { ImageType } from './image-type.ts';
 import { optimize, OptimizeOptions, OptimizedFrame } from './util/optimize.ts';
@@ -283,16 +283,120 @@ export class Animation {
         }
         this.__canvas__ = [boxWidth, boxHeight];
         if (backgroundColor !== 0) {
-            const composited = png.compositeAnimation({ width: boxWidth, height: boxHeight, frames: this.__apngFrames__() });
-            this.frames = composited.map(({ pixels, duration }) => {
-                const content = new Image(boxWidth, boxHeight);
-                content.bitmap = pixels;
-                return new Frame(new Image(boxWidth, boxHeight).fill(backgroundColor).composite(content), { duration, disposalMode: 'background' });
+            this.frames = this.__flattened__().map(frame => {
+                frame.image = new Image(boxWidth, boxHeight).fill(backgroundColor).composite(frame.image);
+                return frame;
             });
         }
         return this;
     }
 
+    /**
+     * Scales the animation by a factor: every frame and its offsets, and the canvas
+     * @param factor The factor
+     * @param options See {@link ResizeOptions}
+     */
+    scale(factor: number, options?: ResizeOptions): this {
+        if (!(finite(factor, 'factor') > 0)) throw new RangeError(`Invalid scale factor: ${factor}`);
+        return this.resize(this.width * factor, this.height * factor, options);
+    }
+
+    /**
+     * Trims the canvas: removes the borders of one color around what any frame shows (in the composited animation),
+     * like {@link Image.trim}. The frames keep their pixels, the canvas is cropped like {@link Animation.crop}
+     * @param options The color (by default the top left pixel of the first frame) and the tolerance, see
+     *     {@link TrimOptions}
+     */
+    trim(options: TrimOptions = {}): this {
+        checkOptions(options, 'trim({ tolerance: 0.1 })');
+        const frames = this.__flattened__();
+        if (!frames.length) return this;
+        const { color = frames[0].image.getPixelAt(0, 0), ...rest } = options;
+        let left = Infinity, top = Infinity, right = -Infinity, bottom = -Infinity;
+        for (const { image } of frames) {
+            const bounds = image.__trim_bounds__(color, rest);
+            if (!bounds) continue;
+            left = Math.min(left, bounds[0]);
+            top = Math.min(top, bounds[1]);
+            right = Math.max(right, bounds[0] + bounds[2]);
+            bottom = Math.max(bottom, bounds[1] + bounds[3]);
+        }
+        if (left === Infinity) return this;
+        return this.crop(left, top, right - left, bottom - top);
+    }
+
+    /**
+     * Rotates the animation clockwise, like {@link Image.rotate}: the frames become full canvas frames of the
+     * composited animation (a partial frame turned by any angle wouldn't cover a rectangle anymore), each one rotated,
+     * and the canvas takes their size
+     * @param angle The angle in degrees, clockwise
+     * @param options See {@link RotateOptions}
+     */
+    rotate(angle: number, options?: RotateOptions): this {
+        return this.__each__(image => image.rotate(angle, options));
+    }
+
+    /**
+     * Transforms the animation with an affine transform, like {@link Image.transform}: the frames become full canvas
+     * frames of the composited animation, each one transformed (by default around the canvas' middle), and the canvas
+     * takes their size
+     * @param matrix The six values [a, b, c, d, e, f]
+     * @param options See {@link TransformOptions}
+     */
+    transform(matrix: ArrayLike<number>, options?: TransformOptions): this {
+        return this.__each__(image => image.transform(matrix, options));
+    }
+
+    /**
+     * Adds a shadow behind what the animation shows, like {@link Image.dropShadow}: the frames become full canvas
+     * frames of the composited animation, each one with its shadow, and the canvas grows with them
+     * @param options See {@link ShadowOptions}
+     */
+    dropShadow(options?: ShadowOptions): this {
+        return this.__each__(image => image.dropShadow(options));
+    }
+
+    /**
+     * Draws an outline around what the animation shows, like {@link Image.outline}: the frames become full canvas
+     * frames of the composited animation, each one outlined, and the canvas grows with them
+     * @param options See {@link OutlineOptions}
+     */
+    outline(options?: OutlineOptions): this {
+        return this.__each__(image => image.outline(options));
+    }
+
+    /**
+     * The composited animation: one full canvas frame per frame, with its duration (gain maps are dropped)
+     * @internal
+     * @ignore
+     */
+    __flattened__(): Frame[] {
+        const { width, height } = this;
+        if (!this.length) return [];
+        return png.compositeAnimation({ width, height, frames: this.__apngFrames__() }).map(({ pixels, duration }) => {
+            const image = new Image(width, height);
+            image.bitmap = pixels;
+            return new Frame(image, { duration, disposalMode: 'background' });
+        });
+    }
+
+    /**
+     * Applies a change to every frame of the composited animation; the canvas takes the frames' new size. Nothing
+     * changes if the change throws
+     * @internal
+     * @ignore
+     */
+    private __each__(change: (image: Image) => unknown): this {
+        const { width, height } = this;
+        if (!width || !height) throw new RangeError('An animation without frames or canvas can\'t be changed');
+        const frames = this.__flattened__();
+        const probe = frames[0]?.image ?? new Image(width, height);
+        for (const frame of frames.length ? frames : [new Frame(probe)]) change(frame.image);
+        this.frames = frames;
+        this.__canvas__ = [probe.width, probe.height];
+        return this;
+    }
+
     /**
      * Resizes the animation to cover the given box, keeping its aspect ratio, and crops the overflowing edges, like
      * {@link Image.cover}: the canvas gets exactly that size

src/frame.ts

@@ -1,4 +1,4 @@
-import { Image, ResizeOptions, ResizeToOptions, TrimOptions, resizeArguments } from './image.ts';
+import { Image, ResizeOptions, ResizeToOptions, TrimOptions, ContainOptions, RotateOptions, TransformOptions, ShadowOptions, OutlineOptions } from './image.ts';
 import { checkOptions, finite } from './util/options.ts';
 
 /**
@@ -29,8 +29,10 @@ export interface FrameOptions {
 
 /**
  * A frame of an {@link Animation}: an {@link Image} ({@link Frame.image}) with a duration, offsets and a disposal mode.
- * The frame's own methods (resize, scale, crop, trim) keep its pixels where they are in the animation by moving the
- * offsets along; every other change goes to the image (`frame.image.blur(2)`), which leaves the offsets as they are
+ * The frame has the methods that change the image's size (resize, scale, contain, cover, crop, trim, rotate, transform,
+ * dropShadow, outline), which move the offsets along so the frame stays in place in the animation; every other change
+ * goes to the image (`frame.image.blur(2)`). The image's own size-changing methods leave the offsets as they are.
+ * Offsets can become negative: the parts of a frame outside the animation's canvas aren't encoded
  */
 export class Frame {
     /** @internal @ignore */
@@ -177,6 +179,25 @@ export class Frame {
         return new Frame(this.__image__.clone(), { duration: this.duration, xOffset: this.xOffset, yOffset: this.yOffset, disposalMode: this.disposalMode });
     }
 
+    /**
+     * Runs a change of the image, moving the offsets the way the image reports its pixels moved
+     * @internal
+     * @ignore
+     */
+    private __tracked__(change: (image: Image) => unknown): this {
+        const image = this.__image__;
+        image.__moved__ = (scaleX, scaleY, x, y) => {
+            this.xOffset = Math.round(this.xOffset * scaleX + x);
+            this.yOffset = Math.round(this.yOffset * scaleY + y);
+        };
+        try {
+            change(image);
+        } finally {
+            delete image.__moved__;
+        }
+        return this;
+    }
+
     /**
      * Resizes the frame, scaling its offsets along with it (as if the whole animation was resized by the same factor)
      * @param width The new width
@@ -191,15 +212,9 @@ export class Frame {
      */
     resize(options: ResizeToOptions): this;
     resize(widthOrOptions: number | ResizeToOptions, heightArgument?: number, optionsArgument?: ResizeOptions): this {
-        const originalWidth = this.width, originalHeight = this.height;
-        if (typeof widthOrOptions === 'number') this.__image__.resize(widthOrOptions, heightArgument as number, optionsArgument);
-        else {
-            resizeArguments(widthOrOptions, heightArgument, optionsArgument);
-            this.__image__.resize(widthOrOptions);
-        }
-        this.xOffset = Math.round(this.xOffset * this.width / originalWidth);
-        this.yOffset = Math.round(this.yOffset * this.height / originalHeight);
-        return this;
+        return this.__tracked__(image => typeof widthOrOptions === 'number'
+            ? image.resize(widthOrOptions, heightArgument as number, optionsArgument)
+            : image.resize(widthOrOptions));
     }
 
     /**
@@ -208,11 +223,30 @@ export class Frame {
      * @param options See {@link ResizeOptions}
      */
     scale(factor: number, options?: ResizeOptions): this {
-        const originalWidth = this.width, originalHeight = this.height;
-        this.__image__.scale(factor, options);
-        this.xOffset = Math.round(this.xOffset * this.width / originalWidth);
-        this.yOffset = Math.round(this.yOffset * this.height / originalHeight);
-        return this;
+        return this.__tracked__(image => image.scale(factor, options));
+    }
+
+    /**
+     * Resizes the frame to fit inside the given box and pads it to exactly that size, like {@link Image.contain}. The
+     * offsets scale with the image and then move by the padding, so the image stays where the scaled frame would be
+     * @param width The width of the box
+     * @param height The height of the box
+     * @param options The background and how to resize, see {@link ContainOptions}
+     */
+    contain(width: number, height: number, options?: ContainOptions): this {
+        return this.__tracked__(image => image.contain(width, height, options));
+    }
+
+    /**
+     * Resizes the frame to cover the given box and crops the overflowing edges, like {@link Image.cover}. The offsets
+     * scale with the image and then move by the cropped amount, so the remaining pixels stay where the scaled frame
+     * had them
+     * @param width The width of the box
+     * @param height The height of the box
+     * @param options See {@link ResizeOptions}
+     */
+    cover(width: number, height: number, options?: ResizeOptions): this {
+        return this.__tracked__(image => image.cover(width, height, options));
     }
 
     /**
@@ -224,26 +258,52 @@ export class Frame {
      * @param height The new height
      */
     crop(x: number, y: number, width: number, height: number): this {
-        const left = Math.max(0, Math.floor(finite(x, 'x'))), top = Math.max(0, Math.floor(finite(y, 'y')));
-        this.__image__.crop(x, y, width, height);
-        this.xOffset += left;
-        this.yOffset += top;
-        return this;
+        return this.__tracked__(image => image.crop(x, y, width, height));
     }
 
     /**
      * Removes borders of one color, moving the offsets so the remaining pixels stay where they are in the animation
      * @param options See {@link TrimOptions}
      */
-    trim(options?: TrimOptions): this;
-    trim(options: TrimOptions = {}): this {
-        checkOptions(options, 'trim({ tolerance: 0.1 })');
-        const { color, ...rest } = options;
-        const bounds = this.__image__.__trim_bounds__(color, rest);
-        if (!bounds) return this;
-        this.__image__.crop(...bounds);
-        this.xOffset += bounds[0];
-        this.yOffset += bounds[1];
-        return this;
+    trim(options?: TrimOptions): this {
+        return this.__tracked__(image => image.trim(options));
+    }
+
+    /**
+     * Rotates the frame clockwise around its middle, like {@link Image.rotate}: when it grows (or shrinks), the
+     * offsets move so its middle stays where it is in the animation
+     * @param angle The angle in degrees, clockwise
+     * @param options See {@link RotateOptions}
+     */
+    rotate(angle: number, options?: RotateOptions): this {
+        return this.__tracked__(image => image.rotate(angle, options));
+    }
+
+    /**
+     * Transforms the frame with an affine transform, like {@link Image.transform}: when it grows, the offsets move
+     * so the transform's origin stays where it is in the animation
+     * @param matrix The six values [a, b, c, d, e, f]
+     * @param options See {@link TransformOptions}
+     */
+    transform(matrix: ArrayLike<number>, options?: TransformOptions): this {
+        return this.__tracked__(image => image.transform(matrix, options));
+    }
+
+    /**
+     * Adds a shadow behind the frame's image, like {@link Image.dropShadow}: when it grows up or left, the offsets
+     * move so the image stays where it is in the animation
+     * @param options See {@link ShadowOptions}
+     */
+    dropShadow(options?: ShadowOptions): this {
+        return this.__tracked__(image => image.dropShadow(options));
+    }
+
+    /**
+     * Draws an outline around the frame's shape, like {@link Image.outline}: when it grows up or left, the offsets
+     * move so the image stays where it is in the animation
+     * @param options See {@link OutlineOptions}
+     */
+    outline(options?: OutlineOptions): this {
+        return this.__tracked__(image => image.outline(options));
     }
 }