remove the onlyFirstFrame option

Author: matmen

CHANGELOG.md

@@ -33,11 +33,11 @@ Upgrading from 3.x? Upgrade to the latest 3.x release first, fix the deprecation
 
 - **The positional arguments of `Image.renderSVG()` are removed**: `Image.renderSVG(svg, size, mode)` is `Image.renderSVG(svg, { size, mode })`, which takes the same `fonts` and `images` as before: `Image.renderSVG(svg, 2, 'width')` is now `Image.renderSVG(svg, { size: 2, mode: 'width' })`.
 
-- **The positional arguments of `new Frame()`, `Frame.from()` and `new Animation()` are removed, and `Animation.decode()` takes no flag**: `new Frame(width, height, duration, xOffset, yOffset, disposalMode)` is `new Frame(width, height, { duration, xOffset, yOffset, disposalMode })`, `Frame.from(image, duration, xOffset, yOffset, disposalMode)` is `Frame.from(image, { duration, xOffset, yOffset, disposalMode })`, `new Animation(frames, loopCount)` is `new Animation(frames, { loopCount })`, and `Animation.decode(data, true)` is `Animation.decode(data, { onlyFirstFrame: true })`.
+- **The positional arguments of `new Frame()`, `Frame.from()` and `new Animation()` are removed, and `Animation.decode()` takes no flag**: `new Frame(width, height, duration, xOffset, yOffset, disposalMode)` is `new Frame(width, height, { duration, xOffset, yOffset, disposalMode })`, `Frame.from(image, duration, xOffset, yOffset, disposalMode)` is `Frame.from(image, { duration, xOffset, yOffset, disposalMode })`, `new Animation(frames, loopCount)` is `new Animation(frames, { loopCount })`, and `Animation.decode(data, true)` is `Animation.decode(data)`, or `Image.decode(data)` for the first frame only.
 
 - **`Image.decode()` returns the first frame of an animation**: a GIF or an animated WebP, which threw in 3.x, is an `Image` of its first frame, composed onto the canvas as `Animation.decode()` composes it, and decoding stops after that frame, so it is fast on long animations. Animated JPEG XLs and AVIF sequences were already their first frame. An APNG is still its default image, what viewers without APNG support show. Use `Animation.decode()` for all the frames.
 
-- **`decode()` returns an `Animation` only for files with several frames**: a GIF, APNG, animated WebP or JPEG XL with more than one frame is an `Animation` (`decode(gif)` used to be a `GIF`), and one with a single frame is an `Image`, like a still image (a one-frame GIF used to be a `GIF`). With `onlyFirstFrame`, the first frame comes back as an `Image`, since the frame count isn't read.
+- **`decode()` returns an `Animation` only for files with several frames**: a GIF, APNG, animated WebP or JPEG XL with more than one frame is an `Animation` (`decode(gif)` used to be a `GIF`), and one with a single frame is an `Image`, like a still image (a one-frame GIF used to be a `GIF`). For the first frame alone, `Image.decode()` returns an `Image`.
 
 - **The `GIF` class is removed**: `new GIF(frames, loopCount)` is `new Animation(frames, { loopCount })`, `GIF.decode(data)` is `Animation.decode(data)` and `gif.encode(quality)` is `animation.encodeGIF({ quality })`. `Animation` decodes and encodes GIFs the same way it does APNGs and WebPs.
 
@@ -47,7 +47,7 @@ Upgrading from 3.x? Upgrade to the latest 3.x release first, fix the deprecation
 
 - **Text alignments only take the values of their own axis**: `TextLayout`'s `horizontalAlign` takes `'left'`, `'center'` or `'right'` and `verticalAlign` takes `'top'`, `'middle'` or `'bottom'`. 3.x accepted the other axis' values in either field, which now throws a `TypeError`: `new TextLayout({ verticalAlign: 'right' })` is `new TextLayout({ horizontalAlign: 'right' })`.
 
-- **`decode()` takes options only**: `decode(data, true)` is `decode(data, { onlyFirstFrame: true })`, and a boolean throws a `TypeError` that names the options form.
+- **`decode()` takes options only**: `decode(data, true)` is `Image.decode(data)` for the first frame, and a boolean throws a `TypeError` that names the options form.
 
 - **`opacity()`, `red()`, `green()`, `blue()`, `lightness()` and `saturation()` reject a second argument**: 3.x's `absolute` call like `image.red(0.5, true)` would silently scale by 0.5 now, so it throws a `TypeError` before the image is touched. Use `image.red(0.5)` to scale and `image.recolor()` for a fixed color.
 

guides/Migrating to 4.0.md

@@ -49,8 +49,7 @@ animation. Use `Animation.decode()` for all the frames. An APNG still gives its
 const first = await Image.decode(data); // the first frame of an animated GIF or WebP
 ```
 
-Search your code for: `decode(` where the result is used for `encode`, `.length`, indexing or `instanceof GIF`, and
-`onlyFirstFrame`.
+Search your code for: `decode(` where the result is used for `encode`, `.length`, indexing or `instanceof GIF`.
 
 ### `Animation` holds its frames instead of extending `Array`
 
@@ -265,8 +264,9 @@ object under the names of their options. The options of each method are on its o
 | `new Frame(w, h, duration, x, y, disposal)` | `new Frame(w, h, { duration, xOffset, yOffset, disposalMode })` |
 | `Frame.from(image, duration, x, y, disposal)` | `Frame.from(image, { duration, xOffset, yOffset, disposalMode })` |
 | `new Animation(frames, loopCount)` | `new Animation(frames, { loopCount })` |
-| `Animation.decode(data, true)` | `Animation.decode(data, { onlyFirstFrame: true })` |
-| `decode(data, true)` | `decode(data, { onlyFirstFrame: true })` |
+| `Animation.decode(data, true)` | `Image.decode(data)` for the first frame, `Animation.decode(data)` for all |
+| `decode(data, true)` | `Image.decode(data)` |
+| `decode(data, { onlyFirstFrame: true })` | `Image.decode(data)` |
 
 `decode()` and `Animation.decode()` take options only: a boolean throws a `TypeError` that names the options form.
 
@@ -306,7 +306,7 @@ grep -rnE 'iterateWithColors|for \(const \[[a-z]+, ?[a-z]+\] of' src
 grep -rnE 'PNGMetadata|AnimationEncoderOptions|AdjustOptions|TextOptions|FrameDisposalModeId|\bGIF\b' src
 
 # decode and animations
-grep -rnE 'decode\(|onlyFirstFrame' src
+grep -rnE 'decode\(.*, *(true|false)\)' src
 grep -rnE 'loopCount\s*(:|=|===)\s*-1|loopCount\s*<\s*0' src
 grep -rnE 'Array\.isArray|\.slice\(|\.frames\b|\.length\s*=' src
 

src/animation.ts

@@ -38,8 +38,6 @@ export interface AnimationOptions {
 
 /** Options of {@link Animation.decode} */
 export interface AnimationDecodeOptions {
-    /** Whether to stop decoding after the first frame. Default: `false` */
-    onlyFirstFrame?: boolean;
     /**
      * The most pixels to decode, of all frames together (every frame is a full canvas): larger animations throw a
      * RangeError before anything that size is allocated, so small files declaring huge animations (decompression
@@ -423,7 +421,7 @@ export class Animation {
     static decode(input: BinaryData, options?: AnimationDecodeOptions): Promise<Animation>;
     static async decode(input: BinaryData, options: AnimationDecodeOptions = {}): Promise<Animation> {
         // (checked outside of decoding(), which reports RangeErrors as damaged data)
-        checkOptions(options, 'Animation.decode(data, { onlyFirstFrame: true })');
+        checkOptions(options, 'Animation.decode(data, { maxPixels: 1e8 })');
         const { maxPixels = MAX_PIXELS, threads = 1 } = options;
         if (!Number.isInteger(threads) || threads < 1) throw new RangeError(`threads must be a positive integer, not ${threads}`);
         if (!(Number(maxPixels) > 0)) throw new RangeError(`maxPixels must be a positive number, not ${maxPixels}`);
@@ -437,7 +435,7 @@ export class Animation {
      * @ignore
      */
     private static async __decode__(input: BinaryData, options: AnimationDecodeOptions): Promise<Animation> {
-        const { onlyFirstFrame: onlyExtractFirstFrame = false, maxPixels = MAX_PIXELS, applyColorProfile = true, threads = Math.max(1, Math.min(availableThreads(), 8)), applyOrientation = true, toneMapping = 'reinhard', gainMap = true } = options;
+        const { maxPixels = MAX_PIXELS, applyColorProfile = true, threads = Math.max(1, Math.min(availableThreads(), 8)), applyOrientation = true, toneMapping = 'reinhard', gainMap = true } = options;
         const orient = (frames: Frame[], orientation: number): Frame[] => {
             if (applyOrientation && orientation > 1) for (const frame of frames) frame.__orient__(orientation);
             return frames;
@@ -450,10 +448,10 @@ export class Animation {
         const data = view(input);
         const type = ImageType.getType(data);
 
-        if (type === 'gif') return Animation.__gifFrames__(data, onlyExtractFirstFrame, maxPixels);
+        if (type === 'gif') return Animation.__gifFrames__(data, maxPixels);
 
         if (type === 'webp') {
-            const decoded = webp.decodeAnimation(data, onlyExtractFirstFrame, maxPixels);
+            const decoded = webp.decodeAnimation(data, false, maxPixels);
             const frames = orient(profile(canvasFrames(decoded.width, decoded.height, webp.composite(decoded)), decoded.icc), decoded.orientation);
             return new Animation(frames, { loopCount: fromPlays(decoded.loopCount) });
         }
@@ -464,7 +462,7 @@ export class Animation {
             return new Animation(canvasFrames(image.width, image.height, [{ pixels: image.bitmap, duration: 0 }]), { loopCount: Infinity });
         }
         if (type === 'png') {
-            const decoded = await png.decodeAnimation(data, onlyExtractFirstFrame, maxPixels);
+            const decoded = await png.decodeAnimation(data, false, maxPixels);
             const frames = orient(profile(canvasFrames(decoded.width, decoded.height, png.compositeAnimation(decoded)), decoded.icc), decoded.orientation);
             return new Animation(frames, { loopCount: decoded.frames.length > 1 ? fromPlays(decoded.plays) : Infinity });
         }
@@ -481,7 +479,6 @@ export class Animation {
                 loops = fromPlays(decoded.loopCount);
                 icc = decoded.icc;
                 space = decoded.colorSpace;
-                if (onlyExtractFirstFrame) break;
             }
             // (a gain map that can't be read leaves the frames without one, it doesn't fail the decoding)
             const map = gainMap && data[0] !== 0xff ? await jxl.decodeGainMap(data, maxPixels).catch(() => undefined) : undefined;
@@ -510,8 +507,8 @@ export class Animation {
      * @internal
      * @ignore
      */
-    private static __gifFrames__(data: Uint8Array, onlyExtractFirstFrame: boolean, maxPixels: number): Animation {
-        const decoded = gifCodec.decode(data, onlyExtractFirstFrame, maxPixels);
+    private static __gifFrames__(data: Uint8Array, maxPixels: number): Animation {
+        const decoded = gifCodec.decode(data, false, maxPixels);
         const frames = gifCodec.composite(decoded).map(({ pixels, delay }) => ({ pixels, duration: 10 * delay }));
         return new Animation(canvasFrames(decoded.width, decoded.height, frames), { loopCount: decoded.loopCount });
     }

src/codecs/gif.ts

@@ -219,10 +219,10 @@ function writeSubBlocks(out: GIFWriter, data: Uint8Array): void {
 /**
  * Decodes a GIF into its individual (uncomposited) frames, zero-sized images are skipped
  * @param {Uint8Array} data
- * @param {boolean} [onlyFirstFrame=false]
+ * @param {boolean} [firstFrameOnly=false]
  * @return {{width: number, height: number, loopCount: number, frames: GIFFrame[]}}
  */
-export function decode(data: Uint8Array, onlyFirstFrame = false, maxPixels = MAX_PIXELS): DecodedGIF {
+export function decode(data: Uint8Array, firstFrameOnly = false, maxPixels = MAX_PIXELS): DecodedGIF {
     const reader = new ByteReader(data);
 
     const signature = reader.string(6);
@@ -329,7 +329,7 @@ export function decode(data: Uint8Array, onlyFirstFrame = false, maxPixels = MAX
             }
 
             frames.push({ x, y, width: fw, height: fh, delay, dispose, indices: ordered, colors, transparentIndex });
-            if (onlyFirstFrame) break;
+            if (firstFrameOnly) break;
         }
     }
 }

src/codecs/png.ts

@@ -718,12 +718,12 @@ export function isAnimated(array: Uint8Array): boolean {
  * a single frame
  * @return plays: 0 = forever
  */
-export async function decodeAnimation(array: Uint8Array, onlyFirstFrame = false, maxPixels = MAX_PIXELS): Promise<{ width: number, height: number, plays: number, frames: APNGFrame[], icc?: Uint8Array, orientation: number }> {
+export async function decodeAnimation(array: Uint8Array, firstFrameOnly = false, maxPixels = MAX_PIXELS): Promise<{ width: number, height: number, plays: number, frames: APNGFrame[], icc?: Uint8Array, orientation: number }> {
     const p = parse(array);
     const { width, height } = p.header;
     const orientation = p.exif ? exifOrientation(p.exif) : await textOrientation(p.text);
     // every frame is composited onto a canvas of its own
-    checkPixels(width, height, maxPixels, !p.animation || p.animationError || onlyFirstFrame ? 1 : Math.max(1, p.frames.length));
+    checkPixels(width, height, maxPixels, !p.animation || p.animationError || firstFrameOnly ? 1 : Math.max(1, p.frames.length));
 
     // broken animations show the default image, like browsers do
     if (!p.animation || p.animationError) {
@@ -741,7 +741,7 @@ export async function decodeAnimation(array: Uint8Array, onlyFirstFrame = false,
             blend: c.blend,
             pixels: await decodeImageData(p, data, c.width, c.height)
         });
-        if (onlyFirstFrame) break;
+        if (firstFrameOnly) break;
     }
 
     return { width, height, plays: p.animation.plays, frames, icc: await profile(p.iccp), orientation };

src/codecs/webp.ts

@@ -183,7 +183,7 @@ export function decode(data: Uint8Array, maxPixels = MAX_PIXELS): { width: numbe
 /**
  * Decodes an animated WebP into its frames (not composited); still WebPs become a single frame
  */
-export function decodeAnimation(data: Uint8Array, onlyFirstFrame = false, maxPixels = MAX_PIXELS): WebPAnimation {
+export function decodeAnimation(data: Uint8Array, firstFrameOnly = false, maxPixels = MAX_PIXELS): WebPAnimation {
     const list = container(data);
     const header = list[0];
     if (!header || header.type !== VP8X || !list.some(c => c.type === ANMF)) {
@@ -194,7 +194,7 @@ export function decodeAnimation(data: Uint8Array, onlyFirstFrame = false, maxPix
     if (header.data.length < 10) throw new Error('WebP: invalid VP8X chunk');
     const width = u24(header.data, 4) + 1, height = u24(header.data, 7) + 1;
     // every frame is composited onto a canvas of its own
-    checkPixels(width, height, maxPixels, onlyFirstFrame ? 1 : list.filter(c => c.type === ANMF).length);
+    checkPixels(width, height, maxPixels, firstFrameOnly ? 1 : list.filter(c => c.type === ANMF).length);
     let loopCount = 0, background = 0;
     const frames: WebPFrame[] = [];
 
@@ -218,7 +218,7 @@ export function decodeAnimation(data: Uint8Array, onlyFirstFrame = false, maxPix
                 dispose: (d[15] & 1) === 1,
                 pixels: frame.pixels
             });
-            if (onlyFirstFrame) break;
+            if (firstFrameOnly) break;
         }
     }
 

src/index.ts

@@ -31,15 +31,13 @@ export type { Metadata } from './metadata.ts';
  * returned as an {@link Animation} of its frames, and any other file as an {@link Image}: a file with a single frame
  * (also a GIF, APNG, WebP or JPEG XL with one frame) becomes an Image of that frame, without its offsets and duration.
  * Static formats (PNG, JPEG, AVIF, ...) are always Images, AVIF image sequences decode to their first frame, as
- * {@link Image.decode} does. The options are passed on to {@link Animation.decode} or {@link Image.decode}. With
- * `onlyFirstFrame` the rest of the file isn't decoded, so the frame count isn't known: the first frame is returned as
- * an Image.
+ * {@link Image.decode} does. The options are passed on to {@link Animation.decode} or {@link Image.decode}.
  * @param data The image data
  * @param options See {@link AnimationDecodeOptions} and {@link DecodeOptions}
  */
 export function decode(data: BinaryData, options?: AnimationDecodeOptions & DecodeOptions): Promise<Image | Animation>;
 export async function decode(data: BinaryData, options: AnimationDecodeOptions & DecodeOptions = {}): Promise<Image | Animation> {
-    checkOptions(options, 'decode(data, { onlyFirstFrame: true })');
+    checkOptions(options, 'decode(data, { maxPixels: 1e8 })');
     const bytes = view(data);
     const type = ImageType.getType(bytes);
     const animated = type === 'gif' || type === 'jxl' || (type === 'webp' && webp.isAnimated(bytes)) || (type === 'png' && png.isAnimated(bytes));

tests/decode-frames.js

@@ -65,10 +65,10 @@ const throwsA = async (fn, type, label) => {
         if (sha256(image.bitmap) !== sha256(reference.bitmap)) panic(`${name}: pixels differ from Image.decode`);
     }
 
-    // options pass through: onlyFirstFrame gives the first frame as an Image, maxPixels applies to both kinds
-    const first = await decode(gif, {onlyFirstFrame: true});
-    if (first instanceof Animation || !(first instanceof Image)) panic('onlyFirstFrame: expected an Image');
-    if (sha256(first.bitmap) !== sha256((await Animation.decode(gif, {onlyFirstFrame: true})).frames[0].bitmap)) panic('onlyFirstFrame: wrong frame');
+    // options pass through: Image.decode gives the first frame as an Image, maxPixels applies to both kinds
+    const first = await Image.decode(gif);
+    if (first instanceof Animation || !(first instanceof Image)) panic('Image.decode: expected an Image');
+    if (sha256(first.bitmap) !== sha256((await Animation.decode(gif)).frames[0].bitmap)) panic('Image.decode: wrong frame');
     await throwsA(() => decode(gif, {maxPixels: 100}), RangeError, 'maxPixels on a GIF');
     const jpeg = await fs.readFile('./tests/targets/external.jpg');
     await throwsA(() => decode(jpeg, {maxPixels: 100}), RangeError, 'maxPixels on a JPEG');

tests/gif.js

@@ -1,6 +1,6 @@
 const fs = require('fs').promises;
 const crypto = require('crypto');
-const {Frame, FrameDisposalModes, Animation, Colors} = require('..');
+const {Image, Frame, FrameDisposalModes, Animation, Colors} = require('..');
 
 const panic = message => {
     console.error(message);
@@ -35,9 +35,9 @@ const panic = message => {
                 panic('decode: incorrect frame bitmap length');
         }
 
-        const first = await Animation.decode(binary, {onlyFirstFrame: true});
-        if (first.length !== 1)
-            panic('decode: onlyExtractFirstFrame returned more than one frame');
+        const first = await Image.decode(binary);
+        if (first.constructor !== Image)
+            panic('decode: Image.decode should return the first frame as an Image');
     }
 
     {

tests/jxl.js

@@ -51,8 +51,9 @@ const difference = (bitmap, width, height, reference, step = 1, premultiplied =
     }
 
     // the first frame only; Animation.decode of a still image
-    const first = await Animation.decode(await fs.readFile('./tests/jxl/animation.jxl'), {onlyFirstFrame: true});
-    if (first.length !== 1) panic(`onlyFirstFrame: ${first.length} frames`);
+    const animated = await fs.readFile('./tests/jxl/animation.jxl');
+    const first = await Image.decode(animated);
+    if (first.constructor !== Image || !Buffer.from(first.bitmap).equals(Buffer.from((await Animation.decode(animated)).frames[0].bitmap))) panic('Image.decode: the first frame of an animated JPEG XL should be Animation.decode\'s first frame');
     const still = await Animation.decode(await fs.readFile('./tests/jxl/lossy.jxl'));
     if (still.length !== 1 || still.frames[0].width !== 64) panic('a still JPEG XL as an animation');