cross-image 0.4.0 → 0.4.2

package/esm/src/types.d.ts

@@ -1,3 +1,49 @@
+/**
+ * JPEG quantized DCT coefficients for steganography and advanced processing
+ * Contains the frequency-domain representation of the image
+ */
+export interface JPEGQuantizedCoefficients {
+    /** Format identifier */
+    format: "jpeg";
+    /** Image width in pixels */
+    width: number;
+    /** Image height in pixels */
+    height: number;
+    /** Whether the JPEG is progressive */
+    isProgressive: boolean;
+    /** Component data (Y, Cb, Cr for color images) */
+    components: JPEGComponentCoefficients[];
+    /** Quantization tables used (indexed by table ID) */
+    quantizationTables: (Uint8Array | number[])[];
+    /** MCU width (number of 8x8 blocks horizontally) */
+    mcuWidth: number;
+    /** MCU height (number of 8x8 blocks vertically) */
+    mcuHeight: number;
+}
+/**
+ * Coefficients for a single JPEG component (Y, Cb, or Cr)
+ */
+export interface JPEGComponentCoefficients {
+    /** Component ID (1=Y, 2=Cb, 3=Cr typically) */
+    id: number;
+    /** Horizontal sampling factor */
+    h: number;
+    /** Vertical sampling factor */
+    v: number;
+    /** Quantization table index */
+    qTable: number;
+    /**
+     * Quantized DCT coefficient blocks
+     * blocks[blockRow][blockCol] contains a 64-element array in zigzag order
+     * Coefficients are quantized (divided by quantization table values)
+     */
+    blocks: Int32Array[][];
+}
+/**
+ * Union type for coefficient data from different formats
+ * Currently only JPEG is supported, but this allows for future extension
+ */
+export type CoefficientData = JPEGQuantizedCoefficients;
 /**
  * Image metadata
  */
@@ -135,6 +181,42 @@ export interface ResizeOptions {
      */
     fit?: "stretch" | "fit" | "fill" | "cover" | "contain";
 }
+/**
+ * Options for PNG encoding.
+ */
+export interface PNGEncoderOptions {
+    /**
+     * Compression level (0-9)
+     * - 0-2: No filtering (fastest)
+     * - 3-6: Sub filter (balanced, default is 6)
+     * - 7-9: Adaptive filtering per scanline (best compression)
+     *
+     * Default: 6 (balanced)
+     *
+     * Note: Affects PNG filter selection. The native deflate compression
+     * is used regardless of level.
+     */
+    compressionLevel?: number;
+}
+/**
+ * Options for APNG (Animated PNG) encoding.
+ *
+ * APNG uses PNG encoding for each frame.
+ */
+export interface APNGEncoderOptions extends PNGEncoderOptions {
+}
+/**
+ * Options for GIF encoding.
+ */
+export interface GIFEncoderOptions {
+    /**
+     * Loop count for animated GIFs.
+     * - 0 (default): Loop infinitely
+     * - 1+: Loop a specific number of times
+     * - undefined or not set: Loop infinitely (same as 0)
+     */
+    loop?: number;
+}
 /**
  * Options for ASCII art encoding
  */
@@ -158,6 +240,8 @@ export interface TIFFEncoderOptions {
     grayscale?: boolean;
     /** Encode as RGB without alpha channel (default: false, ignored if grayscale is true) */
     rgb?: boolean;
+    /** Encode as CMYK color space (default: false, ignored if grayscale is true) */
+    cmyk?: boolean;
 }
 /**
  * Options for WebP encoding
@@ -189,6 +273,34 @@ export interface JPEGEncoderOptions {
      */
     progressive?: boolean;
 }
+/**
+ * Options for AVIF encoding.
+ *
+ * Note: AVIF encoding is currently delegated to runtime APIs (OffscreenCanvas).
+ * Many runtimes ignore `quality` for AVIF, or may not support AVIF encoding at all.
+ */
+export interface AVIFEncoderOptions {
+    /**
+     * Best-effort encoding quality.
+     *
+     * Accepts either 0-1 (canvas-style) or 1-100 (library-style).
+     */
+    quality?: number;
+}
+/**
+ * Options for HEIC encoding.
+ *
+ * Note: HEIC encoding is currently delegated to runtime APIs (OffscreenCanvas).
+ * Many runtimes do not support HEIC encoding.
+ */
+export interface HEICEncoderOptions {
+    /**
+     * Best-effort encoding quality.
+     *
+     * Accepts either 0-1 (canvas-style) or 1-100 (library-style).
+     */
+    quality?: number;
+}
 /**
  * Common options for decode APIs.
  *
@@ -273,5 +385,22 @@ export interface ImageFormat {
      * @returns Metadata extracted from the image, or undefined if extraction fails
      */
     extractMetadata?(data: Uint8Array): Promise<ImageMetadata | undefined>;
+    /**
+     * Extract coefficients from encoded image data (optional)
+     * For JPEG, this returns quantized DCT coefficients
+     * Useful for steganography and advanced image processing
+     * @param data Raw image data
+     * @param options Decoder options
+     * @returns Format-specific coefficient structure or undefined if not supported
+     */
+    extractCoefficients?(data: Uint8Array, options?: ImageDecoderOptions): Promise<CoefficientData | undefined>;
+    /**
+     * Encode image from coefficients (optional)
+     * For JPEG, accepts quantized DCT coefficients and produces a valid JPEG
+     * @param coeffs Format-specific coefficient structure
+     * @param options Format-specific encoding options
+     * @returns Encoded image bytes
+     */
+    encodeFromCoefficients?(coeffs: CoefficientData, options?: unknown): Promise<Uint8Array>;
 }
 //# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1,32 @@
+/**
+ * Base64 utilities.
+ *
+ * Designed to work across Deno, Node.js, and Bun without external dependencies.
+ */
+/**
+ * Encode bytes into a standard Base64 string.
+ */
+export declare function encodeBase64(bytes: Uint8Array): string;
+/**
+ * Decode a Base64 (or Base64URL) string into bytes.
+ *
+ * - Whitespace is ignored.
+ * - Missing padding is tolerated.
+ * - `-`/`_` are accepted as URL-safe variants.
+ */
+export declare function decodeBase64(base64: string): Uint8Array;
+export interface ParsedDataUrl {
+    mime: string;
+    bytes: Uint8Array;
+}
+/**
+ * Create a base64 data URL.
+ */
+export declare function toDataUrl(mime: string, bytes: Uint8Array): string;
+/**
+ * Parse a base64 data URL.
+ *
+ * Supports `data:<mime>;base64,<payload>`.
+ */
+export declare function parseDataUrl(url: string): ParsedDataUrl;
+//# sourceMappingURL=base64.d.ts.map

package/esm/src/utils/base64.js

@@ -0,0 +1,173 @@
+/**
+ * Base64 utilities.
+ *
+ * Designed to work across Deno, Node.js, and Bun without external dependencies.
+ */
+const BASE64_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+const DECODE_TABLE = (() => {
+    const table = new Uint8Array(256);
+    table.fill(0xff);
+    for (let i = 0; i < BASE64_ALPHABET.length; i++) {
+        table[BASE64_ALPHABET.charCodeAt(i)] = i;
+    }
+    return table;
+})();
+function stripWhitespace(input) {
+    // Avoid regex to keep this fast and allocation-light.
+    let out = "";
+    for (let i = 0; i < input.length; i++) {
+        const code = input.charCodeAt(i);
+        // Space, tab, CR, LF
+        if (code === 0x20 || code === 0x09 || code === 0x0d || code === 0x0a)
+            continue;
+        out += input[i];
+    }
+    return out;
+}
+function normalizeBase64(input) {
+    // Accept URL-safe alphabet in decode paths.
+    let s = stripWhitespace(input.trim());
+    if (s.length === 0)
+        return s;
+    // Map base64url to base64.
+    if (s.includes("-") || s.includes("_")) {
+        s = s.replaceAll("-", "+").replaceAll("_", "/");
+    }
+    const remainder = s.length % 4;
+    if (remainder === 1) {
+        throw new Error("Invalid base64: length must not be 1 (mod 4)");
+    }
+    if (remainder === 2)
+        s += "==";
+    if (remainder === 3)
+        s += "=";
+    return s;
+}
+/**
+ * Encode bytes into a standard Base64 string.
+ */
+export function encodeBase64(bytes) {
+    if (bytes.length === 0)
+        return "";
+    const outLen = Math.ceil(bytes.length / 3) * 4;
+    const out = new Array(outLen);
+    let i = 0;
+    let o = 0;
+    for (; i + 2 < bytes.length; i += 3) {
+        const n = (bytes[i] << 16) | (bytes[i + 1] << 8) | bytes[i + 2];
+        out[o++] = BASE64_ALPHABET[(n >> 18) & 63];
+        out[o++] = BASE64_ALPHABET[(n >> 12) & 63];
+        out[o++] = BASE64_ALPHABET[(n >> 6) & 63];
+        out[o++] = BASE64_ALPHABET[n & 63];
+    }
+    const remaining = bytes.length - i;
+    if (remaining === 1) {
+        const n = bytes[i] << 16;
+        out[o++] = BASE64_ALPHABET[(n >> 18) & 63];
+        out[o++] = BASE64_ALPHABET[(n >> 12) & 63];
+        out[o++] = "=";
+        out[o++] = "=";
+    }
+    else if (remaining === 2) {
+        const n = (bytes[i] << 16) | (bytes[i + 1] << 8);
+        out[o++] = BASE64_ALPHABET[(n >> 18) & 63];
+        out[o++] = BASE64_ALPHABET[(n >> 12) & 63];
+        out[o++] = BASE64_ALPHABET[(n >> 6) & 63];
+        out[o++] = "=";
+    }
+    return out.join("");
+}
+/**
+ * Decode a Base64 (or Base64URL) string into bytes.
+ *
+ * - Whitespace is ignored.
+ * - Missing padding is tolerated.
+ * - `-`/`_` are accepted as URL-safe variants.
+ */
+export function decodeBase64(base64) {
+    const s = normalizeBase64(base64);
+    if (s.length === 0)
+        return new Uint8Array(0);
+    let padding = 0;
+    if (s.endsWith("=="))
+        padding = 2;
+    else if (s.endsWith("="))
+        padding = 1;
+    const quadCount = s.length / 4;
+    const outLen = quadCount * 3 - padding;
+    const out = new Uint8Array(outLen);
+    let o = 0;
+    for (let i = 0; i < s.length; i += 4) {
+        const c0 = s.charCodeAt(i);
+        const c1 = s.charCodeAt(i + 1);
+        const c2 = s.charCodeAt(i + 2);
+        const c3 = s.charCodeAt(i + 3);
+        const v0 = DECODE_TABLE[c0];
+        const v1 = DECODE_TABLE[c1];
+        if (v0 === 0xff || v1 === 0xff) {
+            throw new Error("Invalid base64: invalid character");
+        }
+        const isPad2 = c2 === 0x3d; // '='
+        const isPad3 = c3 === 0x3d;
+        const v2 = isPad2 ? 0 : DECODE_TABLE[c2];
+        const v3 = isPad3 ? 0 : DECODE_TABLE[c3];
+        if ((!isPad2 && v2 === 0xff) || (!isPad3 && v3 === 0xff)) {
+            throw new Error("Invalid base64: invalid character");
+        }
+        const n = (v0 << 18) | (v1 << 12) | (v2 << 6) | v3;
+        out[o++] = (n >> 16) & 0xff;
+        if (!isPad2) {
+            if (o >= out.length)
+                break;
+            out[o++] = (n >> 8) & 0xff;
+        }
+        if (!isPad3) {
+            if (o >= out.length)
+                break;
+            out[o++] = n & 0xff;
+        }
+        if (isPad2 || isPad3) {
+            // Padding is only valid in the final quartet.
+            if (i + 4 !== s.length) {
+                throw new Error("Invalid base64: padding can only appear at the end");
+            }
+            // If third char is padding, fourth must also be padding.
+            if (isPad2 && !isPad3) {
+                throw new Error("Invalid base64: invalid padding");
+            }
+        }
+    }
+    return out;
+}
+/**
+ * Create a base64 data URL.
+ */
+export function toDataUrl(mime, bytes) {
+    if (!mime)
+        throw new Error("mime is required");
+    return `data:${mime};base64,${encodeBase64(bytes)}`;
+}
+/**
+ * Parse a base64 data URL.
+ *
+ * Supports `data:<mime>;base64,<payload>`.
+ */
+export function parseDataUrl(url) {
+    if (!url.startsWith("data:")) {
+        throw new Error("Invalid data URL: must start with 'data:'");
+    }
+    const commaIndex = url.indexOf(",");
+    if (commaIndex === -1) {
+        throw new Error("Invalid data URL: missing ',' separator");
+    }
+    const meta = url.slice(5, commaIndex);
+    const payload = url.slice(commaIndex + 1);
+    // We only support base64 payloads.
+    const metaParts = meta.split(";");
+    const mime = metaParts[0] || "application/octet-stream";
+    const isBase64 = metaParts.some((p) => p.toLowerCase() === "base64");
+    if (!isBase64) {
+        throw new Error("Invalid data URL: only base64 payloads are supported");
+    }
+    return { mime, bytes: decodeBase64(payload) };
+}

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

@@ -25,6 +25,8 @@ export declare class GIFEncoder {
     private quantize;
     private nextPowerOf2;
     private getBitsPerColor;
-    encode(): Uint8Array;
+    encode(options?: {
+        loop?: number;
+    }): Uint8Array;
 }
 //# sourceMappingURL=gif_encoder.d.ts.map

package/esm/src/utils/gif_encoder.js

@@ -165,11 +165,13 @@ export class GIFEncoder {
         }
         return Math.max(2, bits);
     }
-    encode() {
+    encode(options) {
         if (this.frames.length === 0) {
             throw new Error("No frames to encode");
         }
         const output = [];
+        // Get loop count from options (default to 0 = infinite)
+        const loopCount = options?.loop ?? 0;
         // Quantize first frame for Global Color Table
         const firstFrame = this.frames[0];
         const { palette: globalPalette, indexed: firstIndexed } = this.quantize(firstFrame.data);
@@ -206,7 +208,7 @@ export class GIFEncoder {
             this.writeString(output, "NETSCAPE2.0");
             output.push(3); // Sub-block Size
             output.push(1); // Loop Indicator (1 = loop)
-            this.writeUint16LE(output, 0); // Loop Count (0 = infinite)
+            this.writeUint16LE(output, loopCount); // Loop Count (0 = infinite, 1+ = specific count)
             output.push(0); // Block Terminator
         }
         // Encode frames

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

@@ -186,4 +186,35 @@ export declare function flipHorizontal(data: Uint8Array, width: number, height:
  * @returns Flipped image data
  */
 export declare function flipVertical(data: Uint8Array, width: number, height: number): Uint8Array;
+/**
+ * Convert RGB color to CMYK color space
+ * @param r Red component (0-255)
+ * @param g Green component (0-255)
+ * @param b Blue component (0-255)
+ * @returns CMYK values: [c (0-1), m (0-1), y (0-1), k (0-1)]
+ */
+export declare function rgbToCmyk(r: number, g: number, b: number): [number, number, number, number];
+/**
+ * Convert CMYK color to RGB color space
+ * @param c Cyan component (0-1)
+ * @param m Magenta component (0-1)
+ * @param y Yellow component (0-1)
+ * @param k Key/Black component (0-1)
+ * @returns RGB values: [r (0-255), g (0-255), b (0-255)]
+ */
+export declare function cmykToRgb(c: number, m: number, y: number, k: number): [number, number, number];
+/**
+ * Convert RGBA image data to CMYK representation
+ * Returns a Float32Array with 4 values per pixel (C, M, Y, K) in 0-1 range
+ * @param data Image data (RGBA)
+ * @returns CMYK image data as Float32Array (4 values per pixel)
+ */
+export declare function rgbaToCmyk(data: Uint8Array): Float32Array;
+/**
+ * Convert CMYK image data to RGBA representation
+ * @param cmykData CMYK image data (4 values per pixel in 0-1 range)
+ * @param alpha Optional alpha value for all pixels (0-255, default: 255)
+ * @returns RGBA image data
+ */
+export declare function cmykToRgba(cmykData: Float32Array, alpha?: number): Uint8Array;
 //# sourceMappingURL=image_processing.d.ts.map

package/esm/src/utils/image_processing.js

@@ -743,3 +743,91 @@ export function flipVertical(data, width, height) {
     }
     return result;
 }
+/**
+ * Convert RGB color to CMYK color space
+ * @param r Red component (0-255)
+ * @param g Green component (0-255)
+ * @param b Blue component (0-255)
+ * @returns CMYK values: [c (0-1), m (0-1), y (0-1), k (0-1)]
+ */
+export function rgbToCmyk(r, g, b) {
+    // Normalize RGB values to 0-1 range
+    const rNorm = r / 255;
+    const gNorm = g / 255;
+    const bNorm = b / 255;
+    // Calculate K (key/black)
+    const k = 1 - Math.max(rNorm, gNorm, bNorm);
+    // If K is 1 (pure black), CMY are undefined but conventionally set to 0
+    if (k === 1) {
+        return [0, 0, 0, 1];
+    }
+    // Calculate CMY components
+    const c = (1 - rNorm - k) / (1 - k);
+    const m = (1 - gNorm - k) / (1 - k);
+    const y = (1 - bNorm - k) / (1 - k);
+    return [c, m, y, k];
+}
+/**
+ * Convert CMYK color to RGB color space
+ * @param c Cyan component (0-1)
+ * @param m Magenta component (0-1)
+ * @param y Yellow component (0-1)
+ * @param k Key/Black component (0-1)
+ * @returns RGB values: [r (0-255), g (0-255), b (0-255)]
+ */
+export function cmykToRgb(c, m, y, k) {
+    // Convert CMYK to RGB
+    const r = 255 * (1 - c) * (1 - k);
+    const g = 255 * (1 - m) * (1 - k);
+    const b = 255 * (1 - y) * (1 - k);
+    return [
+        Math.round(Math.max(0, Math.min(255, r))),
+        Math.round(Math.max(0, Math.min(255, g))),
+        Math.round(Math.max(0, Math.min(255, b))),
+    ];
+}
+/**
+ * Convert RGBA image data to CMYK representation
+ * Returns a Float32Array with 4 values per pixel (C, M, Y, K) in 0-1 range
+ * @param data Image data (RGBA)
+ * @returns CMYK image data as Float32Array (4 values per pixel)
+ */
+export function rgbaToCmyk(data) {
+    const pixelCount = data.length / 4;
+    const result = new Float32Array(pixelCount * 4);
+    for (let i = 0; i < data.length; i += 4) {
+        const r = data[i];
+        const g = data[i + 1];
+        const b = data[i + 2];
+        const [c, m, y, k] = rgbToCmyk(r, g, b);
+        const outIdx = (i / 4) * 4;
+        result[outIdx] = c;
+        result[outIdx + 1] = m;
+        result[outIdx + 2] = y;
+        result[outIdx + 3] = k;
+    }
+    return result;
+}
+/**
+ * Convert CMYK image data to RGBA representation
+ * @param cmykData CMYK image data (4 values per pixel in 0-1 range)
+ * @param alpha Optional alpha value for all pixels (0-255, default: 255)
+ * @returns RGBA image data
+ */
+export function cmykToRgba(cmykData, alpha = 255) {
+    const pixelCount = cmykData.length / 4;
+    const result = new Uint8Array(pixelCount * 4);
+    for (let i = 0; i < cmykData.length; i += 4) {
+        const c = cmykData[i];
+        const m = cmykData[i + 1];
+        const y = cmykData[i + 2];
+        const k = cmykData[i + 3];
+        const [r, g, b] = cmykToRgb(c, m, y, k);
+        const outIdx = i;
+        result[outIdx] = r;
+        result[outIdx + 1] = g;
+        result[outIdx + 2] = b;
+        result[outIdx + 3] = alpha;
+    }
+    return result;
+}

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

@@ -8,7 +8,17 @@
  * This is a pure JavaScript implementation that handles common JPEG files.
  * For complex or non-standard JPEGs, the ImageDecoder API fallback is preferred.
  */
-import type { ImageDecoderOptions } from "../types.js";
+import type { ImageDecoderOptions, JPEGQuantizedCoefficients } from "../types.js";
+/**
+ * Extended decoder options including coefficient extraction
+ */
+interface JPEGDecoderOptions extends ImageDecoderOptions {
+    /**
+     * When true, stores quantized DCT coefficients for later retrieval
+     * via getQuantizedCoefficients(). Coefficients are stored in zigzag order.
+     */
+    extractCoefficients?: boolean;
+}
 export declare class JPEGDecoder {
     private data;
     private pos;
@@ -29,8 +39,20 @@ export declare class JPEGDecoder {
     private successiveLow;
     private scanComponentIds;
     private eobRun;
-    constructor(data: Uint8Array, settings?: ImageDecoderOptions);
+    private quantizedCoefficients;
+    constructor(data: Uint8Array, settings?: JPEGDecoderOptions);
     decode(): Uint8Array;
+    /**
+     * Get the quantized DCT coefficients after decoding
+     * Only available if extractCoefficients option was set to true
+     * @returns JPEGQuantizedCoefficients or undefined if not available
+     */
+    getQuantizedCoefficients(): JPEGQuantizedCoefficients | undefined;
+    /**
+     * Store quantized coefficients in the output structure
+     * Called after decoding when extractCoefficients is true
+     */
+    private storeQuantizedCoefficients;
     private readMarker;
     private readUint16;
     private skipSegment;
@@ -49,4 +71,5 @@ export declare class JPEGDecoder {
     private idct;
     private convertToRGB;
 }
+export {};
 //# sourceMappingURL=jpeg_decoder.d.ts.map