options for trim, colorToAlpha and GainMap.encode, deprecate positional arguments

Author: matmen

CHANGELOG.md

@@ -27,9 +27,12 @@
   and the encoders'). Animations that loop forever still have `-1` as their `loopCount` (also the decoded ones).
 - `Animation.webpEncoder()`, `gifEncoder()` and `apngEncoder()` take the options of `encodeWebP()`, `encodeGIF()` and
   `encodeAPNG()`, plus `loopCount`: the options are documented once.
+- `trim({ color, tolerance })` and `colorToAlpha({ color, transparencyThreshold, opacityThreshold })`: the color goes into the options, like the other options. `GainMap.encode({ quality })` likewise.
 
 ### Deprecated
 
+- Positional optional arguments, the options take the same values: `trim(color, options)`, `colorToAlpha(color, options)`, `GainMap.encode(quality)`, `resize`/`scale`/`contain`/`fit`/`cover` with a `mode` argument (use `ResizeOptions`), `Frame` constructor and `Frame.from()` with duration and offsets (use `FrameOptions`), `Animation` constructor with `loopCount` (use `AnimationOptions`), `Animation.decode(input, onlyExtractFirstFrame)`, `Animation.resize(width, height, mode)`, `Animation.encodeGIF(quality)` and `encodeAPNG(compression)`, `encodePNG(compression, metadata)` and `encodePNG(metadata)`, `encodeJPEG(quality)`, `renderSVG(svg, size, mode)`, `composite(source, x, y, options)`, `rotate(angle, resize)`, `sharpen(amount, radius)`, `roundCorners(radius)`, `fisheye(strength)`, `dominantColor(ignoreBlack, ignoreWhite, threshold)`. All of them still work until 4.0.
+- The numeric frame disposal ids (`0`-`3`): use the names (`'any'`, `'keep'`, `'previous'`, `'background'`). Removed in 4.0.
 - `ResizeModes.AUTO` (and `Image.RESIZE_AUTO`, `Frame.RESIZE_AUTO`): pass only the width or the height instead.
   Removed in 4.0.
 - Iterating over an image (`for (const [x, y] of image)`) and `iterateWithColors()`: use `coordinates()` and

src/animation.ts

@@ -136,6 +136,7 @@ export class Animation extends Array<Frame> {
      * Creates a new animation
      * @param frames The frames to create the animation from
      * @param loopCount How many times to repeat the animation (`Infinity` = forever, 0 = play once, 1 = play twice, ...)
+      * @deprecated Pass {@link AnimationOptions} instead, the positional arguments will be removed in 4.0
      */
     constructor(frames: Frame[], loopCount?: number);
     constructor(frames: Frame[], loopCountOrOptions: number | AnimationOptions = -1) {
@@ -237,6 +238,7 @@ export class Animation extends Array<Frame> {
      * @param width The new width
      * @param height The new height
      * @param mode The resizing mode to use. Default: {@link ResizeModes.BILINEAR}
+      * @deprecated Pass {@link ResizeOptions} with `mode` instead, the positional mode will be removed in 4.0
      */
     resize(width: number, height: number, mode?: ResizeMode): this;
     /**
@@ -290,6 +292,7 @@ export class Animation extends Array<Frame> {
      * animation shows, but not necessarily to the same frames. Semi-transparent pixels become opaque or transparent
      * after the frames are composited
      * @param quality 1-100, scales the palette size from 8 colors (1) to 256 colors (90 and above)
+      * @deprecated Pass {@link GIFEncodeOptions} instead, the positional arguments will be removed in 4.0
      */
     encodeGIF(quality?: number): Promise<Uint8Array>;
     async encodeGIF(qualityOrOptions: number | GIFEncodeOptions = 95): Promise<Uint8Array> {
@@ -326,6 +329,7 @@ export class Animation extends Array<Frame> {
      * merged (unless the `optimize` option is false): the file shows exactly the same animation, but doesn't
      * necessarily decode to the same frames
      * @param compression The zlib compression level (0-9), higher is smaller but slower. Default: `4`
+      * @deprecated Pass {@link APNGEncodeOptions} instead, the positional arguments will be removed in 4.0
      */
     encodeAPNG(compression?: number): Promise<Uint8Array>;
     async encodeAPNG(compressionOrOptions: number | APNGEncodeOptions = 4): Promise<Uint8Array> {
@@ -455,6 +459,7 @@ export class Animation extends Array<Frame> {
      * Decodes an animated GIF, APNG, WebP or JPEG XL into fully composited frames (still images become a single frame)
      * @param input The binary data to decode
      * @param onlyExtractFirstFrame Whether to stop decoding after the first frame
+      * @deprecated Pass {@link AnimationDecodeOptions} instead, the positional arguments will be removed in 4.0
      */
     static decode(input: BinaryData, onlyExtractFirstFrame?: boolean): Promise<Animation>;
     static async decode(input: BinaryData, onlyFirstFrameOrOptions: boolean | AnimationDecodeOptions = false): Promise<Animation> {

src/frame.ts

@@ -3,7 +3,10 @@ import { isOptions, finite } from './util/options.ts';
 
 /** Names of the frame disposal modes, see {@link Frame.disposalMode} */
 export type FrameDisposalModeName = 'any' | 'keep' | 'previous' | 'background';
-/** Ids of the frame disposal modes, as GIFs store them (0 any, 1 keep, 2 previous, 3 background) */
+/**
+ * Ids of the frame disposal modes, as GIFs store them (0 any, 1 keep, 2 previous, 3 background). Use the names
+ * ({@link FrameDisposalModeName}) instead: the ids will be removed in 4.0
+ */
 export type FrameDisposalModeId = 0 | 1 | 2 | 3;
 
 const DISPOSAL_MODES: readonly FrameDisposalModeName[] = ['any', 'keep', 'previous', 'background'];
@@ -108,6 +111,7 @@ export class Frame extends Image {
      * @param xOffset The frame's offset on the x-axis
      * @param yOffset The frame's offset on the y-axis
      * @param disposalMode The frame's disposal mode
+      * @deprecated Pass {@link FrameOptions} instead, the positional arguments will be removed in 4.0
      */
     constructor(width: number, height: number, duration?: number, xOffset?: number, yOffset?: number, disposalMode?: FrameDisposalModeName | FrameDisposalModeId);
     constructor(width: number, height: number, durationOrOptions?: number | FrameOptions, xOffset?: number, yOffset?: number, disposalMode?: FrameDisposalModeName | FrameDisposalModeId) {
@@ -165,6 +169,7 @@ export class Frame extends Image {
      * @param xOffset The frame's offset on the x-axis
      * @param yOffset The frame's offset on the y-axis
      * @param disposalMode The frame's disposal mode
+      * @deprecated Pass {@link FrameOptions} instead, the positional arguments will be removed in 4.0
      */
     static from(image: Image, duration?: number, xOffset?: number, yOffset?: number, disposalMode?: FrameDisposalModeName | FrameDisposalModeId): Frame;
     static from(image: Image, durationOrOptions?: number | FrameOptions, xOffset?: number, yOffset?: number, disposalMode?: FrameDisposalModeName | FrameDisposalModeId): Frame {
@@ -185,12 +190,20 @@ export class Frame extends Image {
         return Frame.from(this, { duration: this.duration, xOffset: this.xOffset, yOffset: this.yOffset, disposalMode: this.disposalMode });
     }
 
+    /**
+     * Removes borders of one color, moving the frame's offsets so the remaining pixels stay in place
+     * @param options See {@link TrimOptions}
+     */
+    override trim(options?: TrimOptions): this;
     /**
      * Removes borders of one color, moving the frame's offsets so the remaining pixels stay in place
      * @param color The border color, by default the color of the top left pixel
      * @param options See {@link TrimOptions}
+      * @deprecated Pass {@link TrimOptions} instead, the positional arguments will be removed in 4.0
      */
-    override trim(color?: Color, options: TrimOptions = {}): this {
+    override trim(color?: Color, options?: TrimOptions): this;
+    override trim(colorOrOptions?: Color | TrimOptions, optionsArgument: TrimOptions = {}): this {
+        const { color, ...options } = isOptions(colorOrOptions) ? colorOrOptions : { ...optionsArgument, color: colorOrOptions ?? optionsArgument.color };
         const bounds = this.__trim_bounds__(color, options);
         if (!bounds) return this;
         this.xOffset += bounds[0];
@@ -203,9 +216,17 @@ export class Frame extends Image {
      * Pass {@link ResizeToOptions} with only a width or a height to keep the aspect ratio.
      * @param width The new width
      * @param height The new height
-     * @param modeOrOptions The resizing mode (default: {@link ResizeModes.BILINEAR}) or {@link ResizeOptions}
+     * @param options See {@link ResizeOptions}
+     */
+    override resize(width: number, height: number, options?: ResizeOptions): this;
+    /**
+     * Resizes the frame, scaling its offsets along with it.
+     * @param width The new width
+     * @param height The new height
+     * @param mode The resizing mode (default: {@link ResizeModes.BILINEAR})
+     * @deprecated Pass {@link ResizeOptions} with `mode` instead, the positional mode will be removed in 4.0
      */
-    override resize(width: number, height: number, modeOrOptions?: ResizeMode | ResizeOptions): this;
+    override resize(width: number, height: number, mode?: ResizeMode): this;
     /**
      * Resizes the frame, scaling its offsets along with it: to the given width or height (the other side keeps the
      * aspect ratio), or to both

src/gainmap.ts

@@ -2,7 +2,13 @@ import { Image } from './image.ts';
 import * as jpeg from './codecs/jpeg.ts';
 import * as codec from './codecs/gainmap.ts';
 import { BinaryData, view } from './util/mem.ts';
-import { finite, quality as checkQuality } from './util/options.ts';
+import { finite, isOptions, quality as checkQuality } from './util/options.ts';
+
+/** Options of {@link GainMap.encode} */
+export interface GainMapEncodeOptions {
+    /** The JPEG quality (1-100). Default: `90` */
+    quality?: number;
+}
 
 /** Options of the {@link GainMap} constructor: per channel values can be one number for all three or [r, g, b] */
 export interface GainMapOptions {
@@ -258,12 +264,21 @@ export class GainMap {
         this.image = out;
     }
 
+    /**
+     * Encodes the gain map alone: a JPEG with its parameters (hdrgm XMP and ISO 21496-1), like the second image in an
+     * Ultra HDR JPEG
+     * @param options See {@link GainMapEncodeOptions}
+     */
+    encode(options?: GainMapEncodeOptions): Promise<Uint8Array>;
     /**
      * Encodes the gain map alone: a JPEG with its parameters (hdrgm XMP and ISO 21496-1), like the second image in an
      * Ultra HDR JPEG
      * @param quality The JPEG quality (1-100). Default: `90`
+      * @deprecated Pass {@link GainMapEncodeOptions} instead, the positional arguments will be removed in 4.0
      */
-    async encode(quality?: number): Promise<Uint8Array> {
+    encode(quality?: number): Promise<Uint8Array>;
+    async encode(qualityOrOptions?: number | GainMapEncodeOptions): Promise<Uint8Array> {
+        let quality = isOptions(qualityOrOptions) ? qualityOrOptions.quality : qualityOrOptions;
         if (quality !== undefined) quality = Math.max(1, checkQuality(quality));
         return codec.mapWithMetadata(this.__body__(quality), this.__params__());
     }