cross-image 0.4.1 → 0.4.3

package/esm/src/utils/gif_encoder.js

@@ -5,13 +5,13 @@
 import { LZWEncoder } from "./lzw.js";
 export class GIFEncoder {
     constructor(width, height, data) {
-        Object.defineProperty(this, "width", {
+        Object.defineProperty(this, "canvasWidth", {
             enumerable: true,
             configurable: true,
             writable: true,
             value: void 0
         });
-        Object.defineProperty(this, "height", {
+        Object.defineProperty(this, "canvasHeight", {
             enumerable: true,
             configurable: true,
             writable: true,
@@ -23,14 +23,28 @@ export class GIFEncoder {
             writable: true,
             value: []
         });
-        this.width = width;
-        this.height = height;
+        this.canvasWidth = width;
+        this.canvasHeight = height;
         if (data) {
             this.addFrame(data);
         }
     }
-    addFrame(data, delay = 0) {
-        this.frames.push({ data, delay });
+    /**
+     * Add a frame with optional metadata for partial frame support
+     */
+    addFrame(data, delay = 0, options) {
+        const pixelCount = data.length / 4;
+        const frameWidth = options?.width ?? this.canvasWidth;
+        const frameHeight = options?.height ?? Math.ceil(pixelCount / frameWidth);
+        this.frames.push({
+            data,
+            delay,
+            left: options?.left ?? 0,
+            top: options?.top ?? 0,
+            width: frameWidth,
+            height: frameHeight,
+            disposal: options?.disposal ?? 0,
+        });
     }
     writeBytes(output, bytes) {
         output.push(...bytes);
@@ -57,49 +71,59 @@ export class GIFEncoder {
         return Math.round(Math.round(value * levels / 255) * step);
     }
     /**
-     * Quantize RGBA image to 256 colors using median cut algorithm
+     * Quantize RGBA image to 256 colors with transparency support
      */
-    quantize(data) {
-        // Simple quantization: collect unique colors and build palette
+    quantize(data, frameWidth, frameHeight) {
+        // Check for transparent pixels (alpha < 128)
+        let hasTransparency = false;
+        for (let i = 3; i < data.length; i += 4) {
+            if (data[i] < 128) {
+                hasTransparency = true;
+                break;
+            }
+        }
         const colorMap = new Map();
         const colors = [];
-        // Color quantization parameters for 8-bit palette (256 colors)
-        // R/G: 8 levels (0-7) using 3 bits, B: 4 levels (0-3) using 2 bits (8*8*4=256)
-        const RG_LEVELS = 7; // Max level for R/G (8 total levels: 0-7)
-        const B_LEVELS = 3; // Max level for B (4 total levels: 0-3)
-        const rgStep = 255 / RG_LEVELS; // Step size for R/G quantization
-        const bStep = 255 / B_LEVELS; // Step size for B quantization
-        // Collect unique colors
+        const transparentIndex = 0;
+        // Reserve index 0 for transparency if needed
+        if (hasTransparency) {
+            colors.push({ r: 0, g: 0, b: 0 });
+        }
+        // Color quantization parameters
+        const RG_LEVELS = 7;
+        const B_LEVELS = 3;
+        const rgStep = 255 / RG_LEVELS;
+        const bStep = 255 / B_LEVELS;
+        const maxColors = hasTransparency ? 255 : 256;
+        // Collect unique colors from opaque pixels only
         for (let i = 0; i < data.length; i += 4) {
+            if (data[i + 3] < 128)
+                continue; // Skip transparent
             const r = data[i];
             const g = data[i + 1];
             const b = data[i + 2];
             const key = `${r},${g},${b}`;
-            if (!colorMap.has(key) && colors.length < 256) {
+            if (!colorMap.has(key) && colors.length < maxColors) {
                 colorMap.set(key, colors.length);
                 colors.push({ r, g, b });
             }
         }
-        // Track if color reduction was applied
         let useColorReduction = false;
-        // If we have too many colors, use simple color reduction
-        if (colors.length >= 256) {
-            // Downsample colors to 256 by reducing color depth
+        // If too many colors, reduce color depth
+        if (colors.length >= maxColors) {
             colorMap.clear();
-            colors.length = 0;
+            colors.length = hasTransparency ? 1 : 0;
             useColorReduction = true;
             for (let i = 0; i < data.length; i += 4) {
-                // Reduce color depth: 3 bits for R/G channels, 2 bits for B channel
-                // This gives us 8 bits total = 256 possible colors
+                if (data[i + 3] < 128)
+                    continue;
                 const r = this.quantizeChannel(data[i], RG_LEVELS, rgStep);
                 const g = this.quantizeChannel(data[i + 1], RG_LEVELS, rgStep);
                 const b = this.quantizeChannel(data[i + 2], B_LEVELS, bStep);
                 const key = `${r},${g},${b}`;
-                if (!colorMap.has(key)) {
-                    if (colors.length < 256) {
-                        colorMap.set(key, colors.length);
-                        colors.push({ r, g, b });
-                    }
+                if (!colorMap.has(key) && colors.length < maxColors) {
+                    colorMap.set(key, colors.length);
+                    colors.push({ r, g, b });
                 }
             }
         }
@@ -115,28 +139,31 @@ export class GIFEncoder {
             palette[i * 3 + 1] = colors[i].g;
             palette[i * 3 + 2] = colors[i].b;
         }
-        // Create indexed data
-        const indexed = new Uint8Array(this.width * this.height);
-        for (let i = 0, j = 0; i < data.length; i += 4, j++) {
+        // Create indexed data using frame dimensions
+        const indexed = new Uint8Array(frameWidth * frameHeight);
+        for (let i = 0, j = 0; i < data.length && j < indexed.length; i += 4, j++) {
+            // Handle transparent pixels
+            if (data[i + 3] < 128) {
+                indexed[j] = transparentIndex;
+                continue;
+            }
             let r = data[i];
             let g = data[i + 1];
             let b = data[i + 2];
-            // Apply color reduction if it was used for building the palette
             if (useColorReduction) {
                 r = this.quantizeChannel(r, RG_LEVELS, rgStep);
                 g = this.quantizeChannel(g, RG_LEVELS, rgStep);
                 b = this.quantizeChannel(b, B_LEVELS, bStep);
             }
             const key = `${r},${g},${b}`;
-            // Try fast O(1) lookup first
             if (colorMap.has(key)) {
                 indexed[j] = colorMap.get(key);
             }
             else {
-                // Fallback: find closest color in palette (shouldn't happen often)
+                // Find closest color
                 let minDist = Infinity;
-                let bestIdx = 0;
-                for (let k = 0; k < colors.length; k++) {
+                let bestIdx = hasTransparency ? 1 : 0;
+                for (let k = hasTransparency ? 1 : 0; k < colors.length; k++) {
                     const dr = r - colors[k].r;
                     const dg = g - colors[k].g;
                     const db = b - colors[k].b;
@@ -149,7 +176,7 @@ export class GIFEncoder {
                 indexed[j] = bestIdx;
             }
         }
-        return { palette, indexed };
+        return { palette, indexed, hasTransparency, transparentIndex };
     }
     nextPowerOf2(n) {
         let power = 1;
@@ -170,46 +197,34 @@ export class GIFEncoder {
             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);
+        const firstResult = this.quantize(firstFrame.data, firstFrame.width, firstFrame.height);
+        const globalPalette = firstResult.palette;
         const paletteSize = globalPalette.length / 3;
         const bitsPerColor = this.getBitsPerColor(paletteSize);
         // Header
         this.writeString(output, "GIF89a");
         // Logical Screen Descriptor
-        this.writeUint16LE(output, this.width);
-        this.writeUint16LE(output, this.height);
-        // Packed field:
-        // - Global Color Table Flag (1 bit): 1
-        // - Color Resolution (3 bits): bitsPerColor - 1
-        // - Sort Flag (1 bit): 0
-        // - Size of Global Color Table (3 bits): bitsPerColor - 1
+        this.writeUint16LE(output, this.canvasWidth);
+        this.writeUint16LE(output, this.canvasHeight);
         const packed = 0x80 | ((bitsPerColor - 1) << 4) | (bitsPerColor - 1);
         output.push(packed);
-        // Background Color Index
-        output.push(0);
-        // Pixel Aspect Ratio
-        output.push(0);
+        output.push(0); // Background Color Index
+        output.push(0); // Pixel Aspect Ratio
         // Global Color Table
-        // The GCT size is 2^(n+1) where n is the value in the packed field
-        // So we need to write that many colors, padding if necessary
         const gctSize = 1 << bitsPerColor;
         const paddedPalette = new Uint8Array(gctSize * 3);
         paddedPalette.set(globalPalette);
         this.writeBytes(output, paddedPalette);
         // Netscape Application Extension (Looping)
         if (this.frames.length > 1) {
-            output.push(0x21); // Extension Introducer
-            output.push(0xff); // Application Extension Label
-            output.push(11); // Block Size
+            output.push(0x21, 0xff, 11);
             this.writeString(output, "NETSCAPE2.0");
-            output.push(3); // Sub-block Size
-            output.push(1); // Loop Indicator (1 = loop)
-            this.writeUint16LE(output, loopCount); // Loop Count (0 = infinite, 1+ = specific count)
-            output.push(0); // Block Terminator
+            output.push(3, 1);
+            this.writeUint16LE(output, loopCount);
+            output.push(0);
         }
         // Encode frames
         for (let i = 0; i < this.frames.length; i++) {
@@ -218,67 +233,56 @@ export class GIFEncoder {
             let useLocalPalette = false;
             let localPalette = null;
             let localBitsPerColor = bitsPerColor;
+            let hasTransparency;
+            let transparentIndex;
             if (i === 0) {
-                indexed = firstIndexed;
+                indexed = firstResult.indexed;
+                hasTransparency = firstResult.hasTransparency;
+                transparentIndex = firstResult.transparentIndex;
             }
             else {
-                // Quantize subsequent frames
-                // For simplicity, we use a Local Color Table for each frame to ensure colors are correct
-                const result = this.quantize(frame.data);
+                const result = this.quantize(frame.data, frame.width, frame.height);
                 indexed = result.indexed;
                 localPalette = result.palette;
                 useLocalPalette = true;
-                const localPaletteSize = localPalette.length / 3;
-                localBitsPerColor = this.getBitsPerColor(localPaletteSize);
+                hasTransparency = result.hasTransparency;
+                transparentIndex = result.transparentIndex;
+                localBitsPerColor = this.getBitsPerColor(localPalette.length / 3);
             }
             // Graphic Control Extension
-            output.push(0x21); // Extension Introducer
-            output.push(0xf9); // Graphic Control Label
-            output.push(4); // Byte Size
-            // Packed Field
-            // Reserved (3 bits)
-            // Disposal Method (3 bits): 2 (Restore to background) - usually safe for animation
-            // User Input Flag (1 bit): 0
-            // Transparent Color Flag (1 bit): 0
-            output.push(0x08); // Disposal method 2 (Restore to background)
-            // Delay Time (1/100ths of a second)
-            // Default to 10 (100ms) if not specified
+            output.push(0x21, 0xf9, 4);
+            // Packed: disposal method + transparency flag
+            const disposal = frame.disposal & 0x07;
+            const gcePacked = (disposal << 2) | (hasTransparency ? 1 : 0);
+            output.push(gcePacked);
+            // Delay time
             const delay = frame.delay > 0 ? Math.round(frame.delay / 10) : 10;
             this.writeUint16LE(output, delay);
-            // Transparent Color Index
-            output.push(0);
+            // Transparent color index
+            output.push(hasTransparency ? transparentIndex : 0);
             output.push(0); // Block Terminator
             // Image Descriptor
-            output.push(0x2c); // Image Separator
-            this.writeUint16LE(output, 0); // Left
-            this.writeUint16LE(output, 0); // Top
-            this.writeUint16LE(output, this.width);
-            this.writeUint16LE(output, this.height);
-            // Packed Field
+            output.push(0x2c);
+            this.writeUint16LE(output, frame.left);
+            this.writeUint16LE(output, frame.top);
+            this.writeUint16LE(output, frame.width);
+            this.writeUint16LE(output, frame.height);
             if (useLocalPalette && localPalette) {
-                // LCT Flag: 1
-                // Interlace: 0
-                // Sort: 0
-                // Reserved: 0
-                // Size of LCT: localBitsPerColor - 1
                 const lctPacked = 0x80 | (localBitsPerColor - 1);
                 output.push(lctPacked);
-                // Write Local Color Table
                 const lctSize = 1 << localBitsPerColor;
                 const paddedLct = new Uint8Array(lctSize * 3);
                 paddedLct.set(localPalette);
                 this.writeBytes(output, paddedLct);
             }
             else {
-                output.push(0); // No LCT
+                output.push(0);
             }
-            // LZW Minimum Code Size
+            // LZW compression
             const minCodeSize = Math.max(2, useLocalPalette ? localBitsPerColor : bitsPerColor);
             output.push(minCodeSize);
-            // Compress image data with LZW
             const encoder = new LZWEncoder(minCodeSize);
             const compressed = encoder.compress(indexed);
-            // Write compressed data in sub-blocks (max 255 bytes per block)
             for (let k = 0; k < compressed.length; k += 255) {
                 const blockSize = Math.min(255, compressed.length - k);
                 output.push(blockSize);
@@ -288,8 +292,7 @@ export class GIFEncoder {
             }
             output.push(0); // Block Terminator
         }
-        // Trailer
-        output.push(0x3b);
+        output.push(0x3b); // Trailer
         return new Uint8Array(output);
     }
 }

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

package/esm/src/utils/jpeg_decoder.js

@@ -211,10 +211,18 @@ export class JPEGDecoder {
             writable: true,
             value: 0
         }); // Remaining blocks to skip due to EOBn
+        // Storage for quantized coefficients (when extractCoefficients is true)
+        Object.defineProperty(this, "quantizedCoefficients", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: null
+        });
         this.data = data;
         this.options = {
             tolerantDecoding: settings.tolerantDecoding ?? true,
             onWarning: settings.onWarning,
+            extractCoefficients: settings.extractCoefficients ?? false,
         };
     }
     decode() {
@@ -276,7 +284,8 @@ export class JPEGDecoder {
         // For progressive JPEGs, perform IDCT on all blocks after all scans are complete
         // This ensures that frequency-domain coefficients from multiple scans are properly
         // accumulated before transformation to spatial domain
-        if (this.isProgressive) {
+        // Skip IDCT when extracting coefficients - we want the quantized DCT values
+        if (this.isProgressive && !this.options.extractCoefficients) {
             for (const component of this.components) {
                 if (component.blocks) {
                     for (const row of component.blocks) {
@@ -287,9 +296,63 @@ export class JPEGDecoder {
                 }
             }
         }
+        // If extracting coefficients, store them before converting to RGB
+        if (this.options.extractCoefficients) {
+            this.storeQuantizedCoefficients();
+        }
         // Convert YCbCr to RGB
         return this.convertToRGB();
     }
+    /**
+     * Get the quantized DCT coefficients after decoding
+     * Only available if extractCoefficients option was set to true
+     * @returns JPEGQuantizedCoefficients or undefined if not available
+     */
+    getQuantizedCoefficients() {
+        return this.quantizedCoefficients ?? undefined;
+    }
+    /**
+     * Store quantized coefficients in the output structure
+     * Called after decoding when extractCoefficients is true
+     */
+    storeQuantizedCoefficients() {
+        // Calculate MCU dimensions
+        const maxH = Math.max(...this.components.map((c) => c.h));
+        const maxV = Math.max(...this.components.map((c) => c.v));
+        const mcuWidth = Math.ceil(this.width / (8 * maxH));
+        const mcuHeight = Math.ceil(this.height / (8 * maxV));
+        // Build component coefficients
+        const componentCoeffs = this.components.map((comp) => ({
+            id: comp.id,
+            h: comp.h,
+            v: comp.v,
+            qTable: comp.qTable,
+            blocks: comp.blocks.map((row) => row.map((block) => {
+                // Convert to Int32Array if not already
+                if (block instanceof Int32Array) {
+                    return block;
+                }
+                return new Int32Array(block);
+            })),
+        }));
+        // Copy quantization tables
+        const qTables = this.qTables.map((table) => {
+            if (table instanceof Uint8Array) {
+                return new Uint8Array(table);
+            }
+            return new Uint8Array(table);
+        });
+        this.quantizedCoefficients = {
+            format: "jpeg",
+            width: this.width,
+            height: this.height,
+            isProgressive: this.isProgressive,
+            components: componentCoeffs,
+            quantizationTables: qTables,
+            mcuWidth,
+            mcuHeight,
+        };
+    }
     readMarker() {
         while (this.pos < this.data.length && this.data[this.pos] !== 0xFF) {
             this.pos++;
@@ -590,7 +653,13 @@ export class JPEGDecoder {
                 component.pred += dcDiff;
                 // For successive approximation, shift the coefficient left by Al bits
                 const coeff = component.pred << this.successiveLow;
-                block[0] = coeff * this.qTables[component.qTable][0];
+                // When extracting coefficients, store quantized value without dequantization
+                if (this.options.extractCoefficients) {
+                    block[0] = coeff;
+                }
+                else {
+                    block[0] = coeff * this.qTables[component.qTable][0];
+                }
             }
             else {
                 // DC refinement scan: add a refinement bit
@@ -598,7 +667,12 @@ export class JPEGDecoder {
                 if (bit) {
                     // Add the refinement bit at position Al
                     const refinement = 1 << this.successiveLow;
-                    block[0] += refinement * this.qTables[component.qTable][0];
+                    if (this.options.extractCoefficients) {
+                        block[0] += refinement;
+                    }
+                    else {
+                        block[0] += refinement * this.qTables[component.qTable][0];
+                    }
                 }
             }
         }
@@ -645,8 +719,14 @@ export class JPEGDecoder {
                             break;
                         // For successive approximation, shift the coefficient left by Al bits
                         const coeff = this.receiveBits(s) << this.successiveLow;
-                        block[ZIGZAG[k]] = coeff *
-                            this.qTables[component.qTable][ZIGZAG[k]];
+                        // When extracting coefficients, store quantized value without dequantization
+                        if (this.options.extractCoefficients) {
+                            block[ZIGZAG[k]] = coeff;
+                        }
+                        else {
+                            block[ZIGZAG[k]] = coeff *
+                                this.qTables[component.qTable][ZIGZAG[k]];
+                        }
                         k++;
                     }
                 }
@@ -693,7 +773,10 @@ export class JPEGDecoder {
                             if (current !== 0) {
                                 const bit = this.readBit();
                                 if (bit) {
-                                    const refinement = (1 << this.successiveLow) * qTable[z];
+                                    // When extracting coefficients, don't dequantize
+                                    const refinement = this.options.extractCoefficients
+                                        ? (1 << this.successiveLow)
+                                        : (1 << this.successiveLow) * qTable[z];
                                     block[z] += direction * refinement;
                                 }
                             }
@@ -708,13 +791,17 @@ export class JPEGDecoder {
                             if (current !== 0) {
                                 const bit = this.readBit();
                                 if (bit) {
-                                    const refinement = (1 << this.successiveLow) * qTable[z];
+                                    // When extracting coefficients, don't dequantize
+                                    const refinement = this.options.extractCoefficients
+                                        ? (1 << this.successiveLow)
+                                        : (1 << this.successiveLow) * qTable[z];
                                     block[z] += direction * refinement;
                                 }
                             }
                             else {
                                 const newCoeff = successiveACNextValue << this.successiveLow;
-                                block[z] = newCoeff * qTable[z];
+                                // When extracting coefficients, don't dequantize
+                                block[z] = this.options.extractCoefficients ? newCoeff : newCoeff * qTable[z];
                                 successiveACState = 0;
                             }
                             break;
@@ -722,7 +809,10 @@ export class JPEGDecoder {
                             if (current !== 0) {
                                 const bit = this.readBit();
                                 if (bit) {
-                                    const refinement = (1 << this.successiveLow) * qTable[z];
+                                    // When extracting coefficients, don't dequantize
+                                    const refinement = this.options.extractCoefficients
+                                        ? (1 << this.successiveLow)
+                                        : (1 << this.successiveLow) * qTable[z];
                                     block[z] += direction * refinement;
                                 }
                             }
@@ -741,7 +831,8 @@ export class JPEGDecoder {
         // Perform IDCT only for baseline JPEGs
         // For progressive JPEGs, IDCT is deferred until all scans are complete
         // to preserve frequency-domain coefficients for accumulation across scans
-        if (!this.isProgressive) {
+        // Skip IDCT when extracting coefficients - we want the quantized DCT values
+        if (!this.isProgressive && !this.options.extractCoefficients) {
             this.idct(block);
         }
     }

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

@@ -5,6 +5,7 @@
  * This is a simplified implementation focusing on correctness over performance.
  * For production use with better quality/size, the OffscreenCanvas API is preferred.
  */
+import type { JPEGQuantizedCoefficients } from "../types.js";
 export interface JPEGEncoderOptions {
     quality?: number;
     progressive?: boolean;
@@ -43,5 +44,23 @@ export declare class JPEGEncoder {
     private forwardDCT;
     private encodeDC;
     private encodeAC;
+    /**
+     * Encode JPEG from pre-quantized DCT coefficients
+     * Skips DCT and quantization - uses provided coefficients directly
+     * Useful for steganography where coefficients are modified and re-encoded
+     * @param coeffs JPEG quantized coefficients
+     * @param _options Optional encoding options (currently unused)
+     * @returns Encoded JPEG bytes
+     */
+    encodeFromCoefficients(coeffs: JPEGQuantizedCoefficients, _options?: JPEGEncoderOptions): Uint8Array;
+    private writeDQTFromCoeffs;
+    private writeSOF0FromCoeffs;
+    private writeSOF2FromCoeffs;
+    private encodeScanFromCoeffs;
+    private encodeACFromCoeffs;
+    private encodeProgressiveFromCoeffs;
+    private encodeProgressiveDCScanFromCoeffs;
+    private encodeProgressiveACScanFromCoeffs;
+    private encodeOnlyACFromCoeffs;
 }
 //# sourceMappingURL=jpeg_encoder.d.ts.map