cross-image 0.2.3 → 0.4.0

package/esm/src/formats/webp.js

@@ -42,7 +42,7 @@ export class WebPFormat {
      * @param data Raw WebP image data
      * @returns Decoded image data with RGBA pixels
      */
-    async decode(data) {
+    async decode(data, settings) {
         if (!this.canDecode(data)) {
             throw new Error("Invalid WebP signature");
         }
@@ -108,7 +108,7 @@ export class WebPFormat {
         validateImageDimensions(width, height);
         // For a pure JS implementation, we'd need to implement full WebP decoding
         // which is very complex. Instead, we'll use the browser/runtime's decoder.
-        const rgba = await this.decodeUsingRuntime(data, width, height);
+        const rgba = await this.decodeUsingRuntime(data, width, height, settings);
         return {
             width,
             height,
@@ -171,9 +171,10 @@ export class WebPFormat {
     readUint24LE(data, offset) {
         return data[offset] | (data[offset + 1] << 8) | (data[offset + 2] << 16);
     }
-    async decodeUsingRuntime(data, _width, _height) {
+    async decodeUsingRuntime(data, _width, _height, settings) {
         // Try to use ImageDecoder API if available (Deno, modern browsers)
-        if (typeof ImageDecoder !== "undefined") {
+        if (settings?.runtimeDecoding !== "never" &&
+            typeof ImageDecoder !== "undefined") {
             try {
                 const decoder = new ImageDecoder({ data, type: "image/webp" });
                 const result = await decoder.decode();
@@ -188,15 +189,17 @@ export class WebPFormat {
                 bitmap.close();
                 return new Uint8Array(imageData.data.buffer);
             }
-            catch (error) {
+            catch (_error) {
                 // ImageDecoder API failed, fall through to pure JS decoder
-                console.warn("WebP decoding with ImageDecoder failed, using pure JS decoder:", error);
             }
         }
-        // Fallback to pure JavaScript decoder (VP8L lossless only)
+        // Fallback to pure JavaScript decoder (VP8L lossless only) with tolerant mode
         try {
             const { WebPDecoder } = await import("../utils/webp_decoder.js");
-            const decoder = new WebPDecoder(data);
+            const decoder = new WebPDecoder(data, {
+                tolerantDecoding: settings?.tolerantDecoding ?? true,
+                onWarning: settings?.onWarning,
+            });
             const result = decoder.decode();
             return result.data;
         }
@@ -567,4 +570,96 @@ export class WebPFormat {
             "focalLength",
         ];
     }
+    /**
+     * Extract metadata from WebP data without fully decoding the pixel data
+     * This quickly parses RIFF chunks to extract EXIF and XMP metadata
+     * @param data Raw WebP data
+     * @returns Extracted metadata or undefined
+     */
+    extractMetadata(data) {
+        if (!this.canDecode(data)) {
+            return Promise.resolve(undefined);
+        }
+        const metadata = {
+            format: "webp",
+            frameCount: 1,
+            bitDepth: 8,
+        };
+        let pos = 12; // Skip "RIFF" + size + "WEBP"
+        const readUint32LE = (data, offset) => {
+            return data[offset] | (data[offset + 1] << 8) | (data[offset + 2] << 16) |
+                (data[offset + 3] << 24);
+        };
+        const readUint16LE = (data, offset) => {
+            return data[offset] | (data[offset + 1] << 8);
+        };
+        // Parse chunks for metadata
+        while (pos + 8 <= data.length) {
+            const chunkType = String.fromCharCode(data[pos], data[pos + 1], data[pos + 2], data[pos + 3]);
+            const chunkSize = readUint32LE(data, pos + 4);
+            pos += 8;
+            // Stop if we've gone past the end
+            if (pos + chunkSize > data.length)
+                break;
+            const chunkData = data.slice(pos, pos + chunkSize);
+            if (chunkType === "VP8 ") {
+                // Lossy VP8 chunk
+                metadata.compression = "vp8";
+                metadata.colorType = "rgb";
+            }
+            else if (chunkType === "VP8L") {
+                // Lossless VP8L chunk
+                metadata.compression = "vp8l";
+                metadata.colorType = "rgba";
+            }
+            else if (chunkType === "VP8X") {
+                // Extended format chunk - contains animation info
+                if (chunkData.length >= 10) {
+                    const flags = chunkData[0];
+                    const _hasAnimation = (flags & 0x02) !== 0;
+                    const hasAlpha = (flags & 0x10) !== 0;
+                    if (hasAlpha) {
+                        metadata.colorType = "rgba";
+                    }
+                    else {
+                        metadata.colorType = "rgb";
+                    }
+                    // Animation is handled in ANIM chunk
+                }
+            }
+            else if (chunkType === "ANIM") {
+                // Animation parameters chunk
+                if (chunkData.length >= 6) {
+                    // Background color at bytes 0-3
+                    // Loop count at bytes 4-5
+                    const _loopCount = readUint16LE(chunkData, 4);
+                    // Note: Frame count is not directly in ANIM chunk, need to count ANMF chunks
+                    // Reset frame count to 0 to start counting ANMF frames
+                    metadata.frameCount = 0;
+                }
+            }
+            else if (chunkType === "ANMF") {
+                // Animation frame - count frames
+                if (metadata.frameCount !== undefined) {
+                    metadata.frameCount++;
+                }
+                else {
+                    metadata.frameCount = 1;
+                }
+            }
+            else if (chunkType === "EXIF") {
+                // EXIF metadata chunk
+                this.parseEXIF(chunkData, metadata);
+            }
+            else if (chunkType === "XMP ") {
+                // XMP metadata chunk
+                this.parseXMP(chunkData, metadata);
+            }
+            pos += chunkSize;
+            // Chunks are padded to even length
+            if (chunkSize % 2 === 1)
+                pos++;
+        }
+        return Promise.resolve(Object.keys(metadata).length > 0 ? metadata : undefined);
+    }
 }

package/esm/src/image.d.ts

@@ -1,4 +1,4 @@
-import type { ImageFormat, ImageMetadata, MultiFrameImageData, ResizeOptions } from "./types.js";
+import type { ImageDecoderOptions, ImageFormat, ImageMetadata, MultiFrameImageData, ResizeOptions } from "./types.js";
 /**
  * Main Image class for reading, manipulating, and saving images
  */
@@ -78,13 +78,26 @@ export declare class Image {
      * @param format Optional format hint (e.g., "png", "jpeg", "webp")
      * @returns Image instance
      */
-    static decode(data: Uint8Array, format?: string): Promise<Image>;
+    static decode(data: Uint8Array): Promise<Image>;
+    static decode(data: Uint8Array, format: string): Promise<Image>;
+    static decode(data: Uint8Array, format: string, options?: ImageDecoderOptions): Promise<Image>;
+    static decode(data: Uint8Array, options?: ImageDecoderOptions): Promise<Image>;
+    private static decodeWithSettings;
     /**
      * Get supported metadata fields for a specific format
      * @param format Format name (e.g., "jpeg", "png", "webp")
      * @returns Array of supported metadata field names, or undefined if format doesn't support metadata
      */
     static getSupportedMetadata(format: string): Array<keyof ImageMetadata> | undefined;
+    /**
+     * Extract metadata from image data without fully decoding the pixel data
+     * This is useful for quickly reading EXIF, XMP, or other metadata from images
+     * that may have unsupported features or compression methods
+     * @param data Raw image data
+     * @param format Optional format hint (e.g., "png", "jpeg", "webp")
+     * @returns Metadata extracted from the image, or undefined if extraction fails or format is unsupported
+     */
+    static extractMetadata(data: Uint8Array, format?: string): Promise<ImageMetadata | undefined>;
     /**
      * Read an image from bytes
      * @deprecated Use `decode()` instead. This method will be removed in a future version.
@@ -99,7 +112,11 @@ export declare class Image {
      * @param format Optional format hint (e.g., "gif", "tiff")
      * @returns MultiFrameImageData with all frames
      */
-    static decodeFrames(data: Uint8Array, format?: string): Promise<MultiFrameImageData>;
+    static decodeFrames(data: Uint8Array): Promise<MultiFrameImageData>;
+    static decodeFrames(data: Uint8Array, format: string): Promise<MultiFrameImageData>;
+    static decodeFrames(data: Uint8Array, format: string, options?: ImageDecoderOptions): Promise<MultiFrameImageData>;
+    static decodeFrames(data: Uint8Array, options?: ImageDecoderOptions): Promise<MultiFrameImageData>;
+    private static decodeFramesWithSettings;
     /**
      * Read all frames from a multi-frame image (GIF animation, multi-page TIFF)
      * @deprecated Use `decodeFrames()` instead. This method will be removed in a future version.

package/esm/src/image.js

@@ -1,4 +1,4 @@
-import { resizeBicubic, resizeBilinear, resizeNearest, } from "./utils/resize.js";
+import { resizeBicubic, resizeBilinear, resizeNearest } from "./utils/resize.js";
 import { adjustBrightness, adjustContrast, adjustExposure, adjustHue, adjustSaturation, boxBlur, composite, crop, fillRect, flipHorizontal, flipVertical, gaussianBlur, grayscale, invert, medianFilter, rotate180, rotate270, rotate90, sepia, sharpen, } from "./utils/image_processing.js";
 import { PNGFormat } from "./formats/png.js";
 import { APNGFormat } from "./formats/apng.js";
@@ -13,6 +13,8 @@ import { PAMFormat } from "./formats/pam.js";
 import { PCXFormat } from "./formats/pcx.js";
 import { PPMFormat } from "./formats/ppm.js";
 import { ASCIIFormat } from "./formats/ascii.js";
+import { HEICFormat } from "./formats/heic.js";
+import { AVIFFormat } from "./formats/avif.js";
 import { validateImageDimensions } from "./utils/security.js";
 /**
  * Main Image class for reading, manipulating, and saving images
@@ -156,26 +158,37 @@ export class Image {
     static getFormats() {
         return Image.formats;
     }
-    /**
-     * Decode an image from bytes
-     * @param data Raw image data
-     * @param format Optional format hint (e.g., "png", "jpeg", "webp")
-     * @returns Image instance
-     */
-    static async decode(data, format) {
+    static async decode(data, formatOrOptions, options) {
+        // Backward-compatible overloads:
+        // - decode(data)
+        // - decode(data, "jpeg")
+        // New:
+        // - decode(data, { tolerantDecoding, onWarning, runtimeDecoding })
+        // - decode(data, "jpeg", { ...options })
+        if (typeof formatOrOptions === "string") {
+            return await Image.decodeWithSettings(data, formatOrOptions, options);
+        }
+        return await Image.decodeWithSettings(data, undefined, formatOrOptions);
+    }
+    static async decodeWithSettings(data, format, settings) {
         const image = new Image();
+        const normalizedSettings = {
+            tolerantDecoding: settings?.tolerantDecoding ?? true,
+            onWarning: settings?.onWarning,
+            runtimeDecoding: settings?.runtimeDecoding ?? "prefer",
+        };
         // Try specified format first
         if (format) {
             const handler = Image.formats.find((f) => f.name === format);
             if (handler && handler.canDecode(data)) {
-                image.imageData = await handler.decode(data);
+                image.imageData = await handler.decode(data, normalizedSettings);
                 return image;
             }
         }
         // Auto-detect format
         for (const handler of Image.formats) {
             if (handler.canDecode(data)) {
-                image.imageData = await handler.decode(data);
+                image.imageData = await handler.decode(data, normalizedSettings);
                 return image;
             }
         }
@@ -193,6 +206,30 @@ export class Image {
         }
         return formatHandler.getSupportedMetadata?.();
     }
+    /**
+     * Extract metadata from image data without fully decoding the pixel data
+     * This is useful for quickly reading EXIF, XMP, or other metadata from images
+     * that may have unsupported features or compression methods
+     * @param data Raw image data
+     * @param format Optional format hint (e.g., "png", "jpeg", "webp")
+     * @returns Metadata extracted from the image, or undefined if extraction fails or format is unsupported
+     */
+    static async extractMetadata(data, format) {
+        // Try specified format first
+        if (format) {
+            const handler = Image.formats.find((f) => f.name === format);
+            if (handler && handler.canDecode(data) && handler.extractMetadata) {
+                return await handler.extractMetadata(data);
+            }
+        }
+        // Auto-detect format
+        for (const handler of Image.formats) {
+            if (handler.canDecode(data) && handler.extractMetadata) {
+                return await handler.extractMetadata(data);
+            }
+        }
+        return undefined;
+    }
     /**
      * Read an image from bytes
      * @deprecated Use `decode()` instead. This method will be removed in a future version.
@@ -201,26 +238,31 @@ export class Image {
      * @returns Image instance
      */
     static read(data, format) {
-        return Image.decode(data, format);
+        return format ? Image.decode(data, format) : Image.decode(data);
     }
-    /**
-     * Decode all frames from a multi-frame image (GIF animation, multi-page TIFF)
-     * @param data Raw image data
-     * @param format Optional format hint (e.g., "gif", "tiff")
-     * @returns MultiFrameImageData with all frames
-     */
-    static async decodeFrames(data, format) {
+    static async decodeFrames(data, formatOrOptions, options) {
+        if (typeof formatOrOptions === "string") {
+            return await Image.decodeFramesWithSettings(data, formatOrOptions, options);
+        }
+        return await Image.decodeFramesWithSettings(data, undefined, formatOrOptions);
+    }
+    static async decodeFramesWithSettings(data, format, settings) {
+        const normalizedSettings = {
+            tolerantDecoding: settings?.tolerantDecoding ?? true,
+            onWarning: settings?.onWarning,
+            runtimeDecoding: settings?.runtimeDecoding ?? "prefer",
+        };
         // Try specified format first
         if (format) {
             const handler = Image.formats.find((f) => f.name === format);
             if (handler && handler.canDecode(data) && handler.decodeFrames) {
-                return await handler.decodeFrames(data);
+                return await handler.decodeFrames(data, normalizedSettings);
             }
         }
         // Auto-detect format
         for (const handler of Image.formats) {
             if (handler.canDecode(data) && handler.decodeFrames) {
-                return await handler.decodeFrames(data);
+                return await handler.decodeFrames(data, normalizedSettings);
             }
         }
         throw new Error("Unsupported or unrecognized multi-frame image format");
@@ -233,7 +275,7 @@ export class Image {
      * @returns MultiFrameImageData with all frames
      */
     static readFrames(data, format) {
-        return Image.decodeFrames(data, format);
+        return format ? Image.decodeFrames(data, format) : Image.decodeFrames(data);
     }
     /**
      * Encode multi-frame image data to bytes in the specified format
@@ -841,5 +883,7 @@ Object.defineProperty(Image, "formats", {
         new PCXFormat(),
         new PPMFormat(),
         new ASCIIFormat(),
+        new HEICFormat(),
+        new AVIFFormat(),
     ]
 });

package/esm/src/types.d.ts

@@ -50,6 +50,16 @@ export interface ImageMetadata {
     software?: string;
     /** User comment / notes */
     userComment?: string;
+    /** Image file format (e.g., "png", "jpeg", "gif", "webp", "tiff") */
+    format?: string;
+    /** Compression algorithm used (e.g., "deflate", "lzw", "dct", "vp8", "vp8l", "none") */
+    compression?: string;
+    /** Number of frames in multi-frame images (e.g., animated GIFs, APNGs, multi-page TIFFs) */
+    frameCount?: number;
+    /** Bit depth per channel (e.g., 8, 16) */
+    bitDepth?: number;
+    /** Color type (e.g., "grayscale", "rgb", "rgba", "indexed", "grayscale-alpha") */
+    colorType?: string;
     /** Custom metadata fields */
     custom?: Record<string, string | number | boolean>;
 }
@@ -128,7 +138,7 @@ export interface ResizeOptions {
 /**
  * Options for ASCII art encoding
  */
-export interface ASCIIOptions {
+export interface ASCIIEncoderOptions {
     /** Target width in characters (default: 80) */
     width?: number;
     /** Character set to use (default: "simple") */
@@ -138,10 +148,21 @@ export interface ASCIIOptions {
     /** Whether to invert brightness (default: false) */
     invert?: boolean;
 }
+/**
+ * Options for TIFF encoding.
+ */
+export interface TIFFEncoderOptions {
+    /** Compression method: "none" (default), "lzw", "packbits", or "deflate" */
+    compression?: "none" | "lzw" | "packbits" | "deflate";
+    /** Encode as grayscale instead of RGB/RGBA (default: false) */
+    grayscale?: boolean;
+    /** Encode as RGB without alpha channel (default: false, ignored if grayscale is true) */
+    rgb?: boolean;
+}
 /**
  * Options for WebP encoding
  */
-export interface WebPEncodeOptions {
+export interface WebPEncoderOptions {
     /**
      * Encoding quality (1-100, default: 90)
      * - 100 = lossless (VP8L)
@@ -154,6 +175,47 @@ export interface WebPEncodeOptions {
      */
     lossless?: boolean;
 }
+/**
+ * Options for JPEG encoding.
+ */
+export interface JPEGEncoderOptions {
+    /**
+     * Encoding quality (1-100, default depends on encoder backend).
+     */
+    quality?: number;
+    /**
+     * Enable progressive JPEG output when using the pure-JS encoder.
+     * Runtime encoders do not currently expose a progressive toggle.
+     */
+    progressive?: boolean;
+}
+/**
+ * Common options for decode APIs.
+ *
+ * These options are runtime-agnostic and can be passed to `Image.decode()` and
+ * `Image.decodeFrames()`.
+ */
+export interface ImageDecoderOptions {
+    /**
+     * Controls tolerant decoding in the pure-JS decoders.
+     *
+     * - true (default): try to recover from corruption and continue
+     * - false: strict mode (fail fast)
+     */
+    tolerantDecoding?: boolean;
+    /**
+     * Optional warning callback used by pure-JS decoders when non-fatal issues are
+     * encountered.
+     */
+    onWarning?: (message: string, details?: unknown) => void;
+    /**
+     * Runtime decoder strategy.
+     *
+     * - "prefer" (default): try runtime decoders first (ImageDecoder/Canvas), then fall back to pure JS
+     * - "never": skip runtime decoders and use pure JS when available
+     */
+    runtimeDecoding?: "prefer" | "never";
+}
 /**
  * Image format handler interface
  */
@@ -167,7 +229,7 @@ export interface ImageFormat {
      * @param data Raw image data
      * @returns Decoded image data
      */
-    decode(data: Uint8Array): Promise<ImageData>;
+    decode(data: Uint8Array, options?: ImageDecoderOptions): Promise<ImageData>;
     /**
      * Encode image data to bytes
      * @param imageData Image data to encode
@@ -186,7 +248,7 @@ export interface ImageFormat {
      * @param data Raw image data
      * @returns Decoded multi-frame image data
      */
-    decodeFrames?(data: Uint8Array): Promise<MultiFrameImageData>;
+    decodeFrames?(data: Uint8Array, options?: ImageDecoderOptions): Promise<MultiFrameImageData>;
     /**
      * Encode multi-frame image data to bytes (optional)
      * @param imageData Multi-frame image data to encode
@@ -203,5 +265,13 @@ export interface ImageFormat {
      * @returns Array of metadata field names that can be persisted
      */
     getSupportedMetadata?(): Array<keyof ImageMetadata>;
+    /**
+     * Extract metadata from image data without fully decoding the pixel data
+     * This is useful for quickly reading EXIF, XMP, or other metadata from images
+     * that may have unsupported features or compression methods
+     * @param data Raw image data
+     * @returns Metadata extracted from the image, or undefined if extraction fails
+     */
+    extractMetadata?(data: Uint8Array): Promise<ImageMetadata | undefined>;
 }
 //# sourceMappingURL=types.d.ts.map

package/esm/src/utils/gif_decoder.d.ts

@@ -2,6 +2,7 @@
  * Pure JavaScript GIF decoder implementation
  * Supports GIF87a and GIF89a formats with LZW decompression
  */
+import type { ImageDecoderOptions } from "../types.js";
 interface GIFImage {
     width: number;
     height: number;
@@ -19,7 +20,8 @@ interface GIFFrame {
 export declare class GIFDecoder {
     private data;
     private pos;
-    constructor(data: Uint8Array);
+    private options;
+    constructor(data: Uint8Array, settings?: ImageDecoderOptions);
     private readByte;
     private readUint16LE;
     private readBytes;
@@ -36,6 +38,7 @@ export declare class GIFDecoder {
         frames: GIFFrame[];
     };
     private indexedToRGBA;
+    private decodeFrame;
     private deinterlace;
 }
 export {};