cross-image 0.4.1 → 0.4.3

package/README.md

@@ -1,8 +1,8 @@
 # @cross/image
 
-A pure JavaScript, dependency-free, cross-runtime image processing library for Deno, Node.js, and
-Bun. Decode, encode, manipulate, and process images in multiple formats including PNG, JPEG, WebP,
-GIF, and more—all without native dependencies.
+A pure JavaScript, dependency-free, cross-runtime image processing library for Deno, Node.js, Bun
+and browsers. Decode, encode, manipulate, and process images in multiple formats including PNG,
+JPEG, WebP, GIF, and more—all without native dependencies.
 
 📚 **[Full Documentation](https://cross-image.56k.guru/)**
 
@@ -10,7 +10,7 @@ GIF, and more—all without native dependencies.
 
 - 🚀 **Pure JavaScript** - No native dependencies
 - 🔌 **Pluggable formats** - Easy to extend with custom formats
-- 📦 **Cross-runtime** - Works on Deno, Node.js (18+), and Bun
+- 📦 **Cross-runtime** - Works on Deno, Node.js (18+), Bun and Browsers.
 - 🎨 **Multiple formats** - PNG, APNG, JPEG, WebP, GIF, TIFF, BMP, ICO, DNG, PAM, PPM, PCX, ASCII,
   HEIC, and AVIF support
 - ✂️ **Image manipulation** - Resize, crop, composite, and more
@@ -284,6 +284,79 @@ const compressed = await image.encode("tiff", {
 - **Full compression support**: CMYK works with all TIFF compression methods
 - **Industry standard**: TIFF is the preferred format for CMYK images in print production
 
+## JPEG Coefficient Extraction
+
+The library provides advanced APIs for extracting and encoding JPEG quantized DCT coefficients,
+enabling coefficient-domain steganography and other frequency-domain processing techniques.
+
+### Extracting Coefficients
+
+```typescript
+import { Image } from "jsr:@cross/image";
+
+const data = await Deno.readFile("photo.jpg");
+
+// Extract quantized DCT coefficients
+const coefficients = await Image.extractCoefficients(data, "jpeg");
+
+if (coefficients) {
+  console.log(`Image: ${coefficients.width}x${coefficients.height}`);
+  console.log(`Progressive: ${coefficients.isProgressive}`);
+  console.log(`Components: ${coefficients.components.length}`);
+
+  // Access coefficient blocks (Y, Cb, Cr components)
+  for (const comp of coefficients.components) {
+    console.log(`Component ${comp.id}: ${comp.blocks.length} block rows`);
+  }
+}
+```
+
+### Modifying and Re-encoding Coefficients
+
+```typescript
+import { Image } from "jsr:@cross/image";
+
+const data = await Deno.readFile("input.jpg");
+const coefficients = await Image.extractCoefficients(data, "jpeg");
+
+if (coefficients) {
+  // Modify coefficients (e.g., for steganography)
+  for (const comp of coefficients.components) {
+    for (const row of comp.blocks) {
+      for (const block of row) {
+        // Modify AC coefficients (indices 1-63)
+        // DC coefficient is at index 0
+        // block is an Int32Array of 64 quantized DCT values in zigzag order
+      }
+    }
+  }
+
+  // Re-encode to JPEG
+  const encoded = await Image.encodeFromCoefficients(coefficients, "jpeg");
+  await Deno.writeFile("output.jpg", encoded);
+}
+```
+
+### Coefficient Structure
+
+The `JPEGQuantizedCoefficients` type provides:
+
+- `width`, `height` - Image dimensions
+- `isProgressive` - Whether the source was progressive JPEG
+- `components` - Array of Y, Cb, Cr (or grayscale) component data
+- `quantizationTables` - The quantization tables used
+- `mcuWidth`, `mcuHeight` - MCU block dimensions
+
+Each component contains `blocks[][]` where each block is an `Int32Array` of 64 quantized DCT
+coefficients in zigzag order.
+
+**Use Cases:**
+
+- DCT-domain steganography (survives JPEG re-compression)
+- Coefficient analysis and visualization
+- Custom frequency-domain filtering
+- Forensic analysis of JPEG compression artifacts
+
 ## Base64 / Data URLs
 
 The library includes small utilities for working with base64 and `data:` URLs.

package/esm/mod.d.ts

@@ -43,7 +43,7 @@
  * ```
  */
 export { Image } from "./src/image.js";
-export type { APNGEncoderOptions, ASCIIEncoderOptions, AVIFEncoderOptions, FrameMetadata, GIFEncoderOptions, HEICEncoderOptions, ImageData, ImageDecoderOptions, ImageFormat, ImageFrame, ImageMetadata, JPEGEncoderOptions, MultiFrameImageData, PNGEncoderOptions, ResizeOptions, TIFFEncoderOptions, WebPEncoderOptions, } from "./src/types.js";
+export type { APNGEncoderOptions, ASCIIEncoderOptions, AVIFEncoderOptions, CoefficientData, FrameMetadata, GIFEncoderOptions, HEICEncoderOptions, ImageData, ImageDecoderOptions, ImageFormat, ImageFrame, ImageMetadata, JPEGComponentCoefficients, JPEGEncoderOptions, JPEGQuantizedCoefficients, MultiFrameImageData, PNGEncoderOptions, ResizeOptions, TIFFEncoderOptions, WebPEncoderOptions, } from "./src/types.js";
 export { PNGFormat } from "./src/formats/png.js";
 export { APNGFormat } from "./src/formats/apng.js";
 export { JPEGFormat } from "./src/formats/jpeg.js";

package/esm/src/formats/gif.d.ts

@@ -48,6 +48,7 @@ export declare class GIFFormat implements ImageFormat {
      * Encode multi-frame image data to animated GIF
      */
     encodeFrames(imageData: MultiFrameImageData, options?: GIFEncoderOptions): Promise<Uint8Array>;
+    private mapDisposalMethodToNumber;
     private mapDisposalMethod;
     private decodeUsingRuntime;
     private readDataSubBlocks;

package/esm/src/formats/gif.js

@@ -243,12 +243,29 @@ export class GIFFormat {
         }
         const encoder = new GIFEncoder(imageData.width, imageData.height);
         for (const frame of imageData.frames) {
-            // Get delay from metadata (default to 100ms if not set)
             const delay = frame.frameMetadata?.delay ?? 100;
-            encoder.addFrame(frame.data, delay);
+            encoder.addFrame(frame.data, delay, {
+                left: frame.frameMetadata?.left ?? 0,
+                top: frame.frameMetadata?.top ?? 0,
+                width: frame.width,
+                height: frame.height,
+                disposal: this.mapDisposalMethodToNumber(frame.frameMetadata?.disposal),
+            });
         }
         return Promise.resolve(encoder.encode(options));
     }
+    mapDisposalMethodToNumber(disposal) {
+        switch (disposal) {
+            case "none":
+                return 1;
+            case "background":
+                return 2;
+            case "previous":
+                return 3;
+            default:
+                return 0;
+        }
+    }
     mapDisposalMethod(disposal) {
         switch (disposal) {
             case 0:

package/esm/src/formats/jpeg.d.ts

@@ -1,4 +1,4 @@
-import type { ImageData, ImageDecoderOptions, ImageFormat, ImageMetadata, JPEGEncoderOptions } from "../types.js";
+import type { CoefficientData, ImageData, ImageDecoderOptions, ImageFormat, ImageMetadata, JPEGEncoderOptions, JPEGQuantizedCoefficients } from "../types.js";
 /**
  * JPEG format handler
  * Implements a basic JPEG decoder and encoder
@@ -42,6 +42,26 @@ export declare class JPEGFormat implements ImageFormat {
      * Get the list of metadata fields supported by JPEG format
      */
     getSupportedMetadata(): Array<keyof ImageMetadata>;
+    /**
+     * Extract quantized DCT coefficients from JPEG data
+     * These coefficients can be modified for steganography and re-encoded
+     * @param data Raw JPEG data
+     * @param options Decoder options
+     * @returns JPEGQuantizedCoefficients or undefined if extraction fails
+     */
+    extractCoefficients(data: Uint8Array, options?: ImageDecoderOptions): Promise<JPEGQuantizedCoefficients | undefined>;
+    /**
+     * Type guard to check if coefficient data is JPEG format
+     */
+    private isJPEGCoefficients;
+    /**
+     * Encode JPEG from quantized DCT coefficients
+     * Useful for steganography - modify coefficients and re-encode
+     * @param coeffs JPEG quantized coefficients
+     * @param options Encoding options
+     * @returns Encoded JPEG bytes
+     */
+    encodeFromCoefficients(coeffs: CoefficientData, options?: JPEGEncoderOptions): Promise<Uint8Array>;
     /**
      * Extract metadata from JPEG data without fully decoding the pixel data
      * This quickly parses JFIF and EXIF markers to extract metadata

package/esm/src/formats/jpeg.js

@@ -1072,6 +1072,65 @@ export class JPEGFormat {
             "dpiY",
         ];
     }
+    /**
+     * Extract quantized DCT coefficients from JPEG data
+     * These coefficients can be modified for steganography and re-encoded
+     * @param data Raw JPEG data
+     * @param options Decoder options
+     * @returns JPEGQuantizedCoefficients or undefined if extraction fails
+     */
+    async extractCoefficients(data, options) {
+        if (!this.canDecode(data)) {
+            return undefined;
+        }
+        try {
+            // Force pure-JS decoding since runtime decoders don't expose coefficients
+            const { JPEGDecoder } = await import("../utils/jpeg_decoder.js");
+            const decoder = new JPEGDecoder(data, {
+                tolerantDecoding: options?.tolerantDecoding ?? true,
+                onWarning: options?.onWarning,
+                extractCoefficients: true,
+            });
+            // Decode to extract coefficients
+            decoder.decode();
+            // Get the quantized coefficients
+            return decoder.getQuantizedCoefficients();
+        }
+        catch (error) {
+            if (options?.onWarning) {
+                options.onWarning(`Failed to extract JPEG coefficients: ${error}`, error);
+            }
+            return undefined;
+        }
+    }
+    /**
+     * Type guard to check if coefficient data is JPEG format
+     */
+    isJPEGCoefficients(coeffs) {
+        return ("format" in coeffs &&
+            coeffs.format === "jpeg" &&
+            "components" in coeffs &&
+            "quantizationTables" in coeffs &&
+            "isProgressive" in coeffs);
+    }
+    /**
+     * Encode JPEG from quantized DCT coefficients
+     * Useful for steganography - modify coefficients and re-encode
+     * @param coeffs JPEG quantized coefficients
+     * @param options Encoding options
+     * @returns Encoded JPEG bytes
+     */
+    async encodeFromCoefficients(coeffs, options) {
+        if (!this.isJPEGCoefficients(coeffs)) {
+            throw new Error("Invalid coefficient format for JPEG");
+        }
+        const { JPEGEncoder } = await import("../utils/jpeg_encoder.js");
+        const encoder = new JPEGEncoder({
+            quality: options?.quality,
+            progressive: options?.progressive ?? coeffs.isProgressive,
+        });
+        return encoder.encodeFromCoefficients(coeffs, options);
+    }
     /**
      * Extract metadata from JPEG data without fully decoding the pixel data
      * This quickly parses JFIF and EXIF markers to extract metadata

package/esm/src/image.d.ts

@@ -1,4 +1,4 @@
-import type { ImageDecoderOptions, ImageFormat, ImageMetadata, MultiFrameImageData, ResizeOptions } from "./types.js";
+import type { CoefficientData, ImageDecoderOptions, ImageFormat, ImageMetadata, MultiFrameImageData, ResizeOptions } from "./types.js";
 /**
  * Main Image class for reading, manipulating, and saving images
  */
@@ -98,6 +98,44 @@ export declare class Image {
      * @returns Metadata extracted from the image, or undefined if extraction fails or format is unsupported
      */
     static extractMetadata(data: Uint8Array, format?: string): Promise<ImageMetadata | undefined>;
+    /**
+     * Extract coefficients from encoded image data
+     * For JPEG, this returns quantized DCT coefficients that can be modified for steganography
+     * and re-encoded using encodeFromCoefficients()
+     * @param data Raw image data
+     * @param format Optional format hint (e.g., "jpeg")
+     * @param options Optional decoder options
+     * @returns Format-specific coefficient structure or undefined if not supported
+     *
+     * @example
+     * ```ts
+     * // Extract JPEG coefficients for steganography
+     * const coeffs = await Image.extractCoefficients(jpegData, "jpeg");
+     * if (coeffs) {
+     *   // Modify coefficients for steganography...
+     *   const modified = await Image.encodeFromCoefficients(coeffs, "jpeg");
+     * }
+     * ```
+     */
+    static extractCoefficients(data: Uint8Array, format?: string, options?: ImageDecoderOptions): Promise<CoefficientData | undefined>;
+    /**
+     * Encode image from coefficients
+     * For JPEG, accepts quantized DCT coefficients and produces a valid JPEG file
+     * Useful for steganography where coefficients are extracted, modified, and re-encoded
+     * @param coeffs Format-specific coefficient structure
+     * @param format Optional format hint (auto-detected from coeffs.format if available)
+     * @param options Optional format-specific encoding options
+     * @returns Encoded image bytes
+     *
+     * @example
+     * ```ts
+     * // Re-encode modified JPEG coefficients
+     * const coeffs = await Image.extractCoefficients(jpegData, "jpeg");
+     * // Modify coefficients...
+     * const encoded = await Image.encodeFromCoefficients(coeffs, "jpeg");
+     * ```
+     */
+    static encodeFromCoefficients(coeffs: CoefficientData, format?: string, options?: unknown): Promise<Uint8Array>;
     /**
      * Read an image from bytes
      * @deprecated Use `decode()` instead. This method will be removed in a future version.

package/esm/src/image.js

@@ -230,6 +230,74 @@ export class Image {
         }
         return undefined;
     }
+    /**
+     * Extract coefficients from encoded image data
+     * For JPEG, this returns quantized DCT coefficients that can be modified for steganography
+     * and re-encoded using encodeFromCoefficients()
+     * @param data Raw image data
+     * @param format Optional format hint (e.g., "jpeg")
+     * @param options Optional decoder options
+     * @returns Format-specific coefficient structure or undefined if not supported
+     *
+     * @example
+     * ```ts
+     * // Extract JPEG coefficients for steganography
+     * const coeffs = await Image.extractCoefficients(jpegData, "jpeg");
+     * if (coeffs) {
+     *   // Modify coefficients for steganography...
+     *   const modified = await Image.encodeFromCoefficients(coeffs, "jpeg");
+     * }
+     * ```
+     */
+    static async extractCoefficients(data, format, options) {
+        // Try specified format first
+        if (format) {
+            const handler = Image.formats.find((f) => f.name === format);
+            if (handler && handler.canDecode(data) && handler.extractCoefficients) {
+                return await handler.extractCoefficients(data, options);
+            }
+        }
+        // Auto-detect format
+        for (const handler of Image.formats) {
+            if (handler.canDecode(data) && handler.extractCoefficients) {
+                return await handler.extractCoefficients(data, options);
+            }
+        }
+        return undefined;
+    }
+    /**
+     * Encode image from coefficients
+     * For JPEG, accepts quantized DCT coefficients and produces a valid JPEG file
+     * Useful for steganography where coefficients are extracted, modified, and re-encoded
+     * @param coeffs Format-specific coefficient structure
+     * @param format Optional format hint (auto-detected from coeffs.format if available)
+     * @param options Optional format-specific encoding options
+     * @returns Encoded image bytes
+     *
+     * @example
+     * ```ts
+     * // Re-encode modified JPEG coefficients
+     * const coeffs = await Image.extractCoefficients(jpegData, "jpeg");
+     * // Modify coefficients...
+     * const encoded = await Image.encodeFromCoefficients(coeffs, "jpeg");
+     * ```
+     */
+    static async encodeFromCoefficients(coeffs, format, options) {
+        // Detect format from coefficient structure or use provided format
+        const detectedFormat = format ??
+            coeffs.format;
+        if (!detectedFormat) {
+            throw new Error("Format must be specified or present in coefficient data");
+        }
+        const handler = Image.formats.find((f) => f.name === detectedFormat);
+        if (!handler) {
+            throw new Error(`Unknown format: ${detectedFormat}`);
+        }
+        if (!handler.encodeFromCoefficients) {
+            throw new Error(`Format ${detectedFormat} does not support encoding from coefficients`);
+        }
+        return await handler.encodeFromCoefficients(coeffs, options);
+    }
     /**
      * Read an image from bytes
      * @deprecated Use `decode()` instead. This method will be removed in a future version.

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
  */
@@ -339,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/gif_encoder.d.ts

@@ -3,11 +3,20 @@
  * Supports GIF89a format with LZW compression
  */
 export declare class GIFEncoder {
-    private width;
-    private height;
+    private canvasWidth;
+    private canvasHeight;
     private frames;
     constructor(width: number, height: number, data?: Uint8Array);
-    addFrame(data: Uint8Array, delay?: number): void;
+    /**
+     * Add a frame with optional metadata for partial frame support
+     */
+    addFrame(data: Uint8Array, delay?: number, options?: {
+        left?: number;
+        top?: number;
+        width?: number;
+        height?: number;
+        disposal?: number;
+    }): void;
     private writeBytes;
     private writeUint16LE;
     private writeString;
@@ -20,7 +29,7 @@ export declare class GIFEncoder {
      */
     private quantizeChannel;
     /**
-     * Quantize RGBA image to 256 colors using median cut algorithm
+     * Quantize RGBA image to 256 colors with transparency support
      */
     private quantize;
     private nextPowerOf2;