cross-image 0.4.0 → 0.4.1

package/README.md

@@ -196,6 +196,112 @@ const imageWithWarnings = await Image.decode(data, {
 ```
 
 **Note:** When using `Image.decode()`, the library automatically tries runtime-optimized decoders
+
+## CMYK Color Space Support
+
+The library provides utilities for working with CMYK (Cyan, Magenta, Yellow, Key/Black) color space,
+commonly used in professional printing and color manipulation.
+
+### Color Conversion Utilities
+
+```ts
+import { cmykToRgb, rgbToCmyk } from "jsr:@cross/image";
+
+// Convert RGB to CMYK
+const [c, m, y, k] = rgbToCmyk(255, 0, 0); // Red
+console.log({ c, m, y, k }); // { c: 0, m: 1, y: 1, k: 0 }
+
+// Convert CMYK back to RGB
+const [r, g, b] = cmykToRgb(c, m, y, k);
+console.log({ r, g, b }); // { r: 255, g: 0, b: 0 }
+```
+
+### Image-Level CMYK Operations
+
+```ts
+import { Image } from "jsr:@cross/image";
+
+// Load an image and convert to CMYK
+const data = await Deno.readFile("photo.jpg");
+const image = await Image.decode(data);
+
+// Get CMYK representation (Float32Array with 4 values per pixel)
+const cmykData = image.toCMYK();
+
+// Create an image from CMYK data
+const restored = Image.fromCMYK(cmykData, image.width, image.height);
+
+// Save the restored image
+await Deno.writeFile("output.png", await restored.encode("png"));
+```
+
+### Batch Conversion
+
+```ts
+import { cmykToRgba, rgbaToCmyk } from "jsr:@cross/image";
+
+// Convert entire image data to CMYK
+const rgbaData = new Uint8Array([255, 0, 0, 255]); // Red pixel
+const cmykData = rgbaToCmyk(rgbaData);
+
+// Convert CMYK data back to RGBA
+const rgbaRestored = cmykToRgba(cmykData);
+```
+
+**Use Cases:**
+
+- Pre-press and print preparation workflows
+- Color space conversion for professional printing
+- Color analysis and manipulation in CMYK space
+- Educational tools for understanding color models
+
+### CMYK TIFF Support
+
+TIFF format has native support for CMYK images:
+
+```ts
+import { Image } from "jsr:@cross/image";
+
+// Decode CMYK TIFF (automatically converted to RGBA)
+const cmykTiff = await Deno.readFile("cmyk-image.tif");
+const image = await Image.decode(cmykTiff); // Automatic CMYK → RGBA conversion
+
+// Encode image as CMYK TIFF
+const output = await image.encode("tiff", { cmyk: true });
+await Deno.writeFile("output-cmyk.tif", output);
+
+// CMYK works with all TIFF compression methods
+const compressed = await image.encode("tiff", {
+  cmyk: true,
+  compression: "lzw", // or "packbits", "deflate", "none"
+});
+```
+
+**Benefits:**
+
+- **Seamless workflow**: CMYK TIFFs decode automatically, no special handling needed
+- **Print-ready output**: Generate CMYK TIFFs for professional printing workflows
+- **Full compression support**: CMYK works with all TIFF compression methods
+- **Industry standard**: TIFF is the preferred format for CMYK images in print production
+
+## Base64 / Data URLs
+
+The library includes small utilities for working with base64 and `data:` URLs.
+
+```ts
+import { Image, parseDataUrl, toDataUrl } from "jsr:@cross/image";
+
+const image = Image.create(2, 2, 255, 0, 0);
+const pngBytes = await image.encode("png");
+
+const dataUrl = toDataUrl("image/png", pngBytes);
+const parsed = parseDataUrl(dataUrl);
+
+// parsed.bytes is a Uint8Array containing the PNG
+const roundtrip = await Image.decode(parsed.bytes, "png");
+console.log(roundtrip.width, roundtrip.height);
+```
+
 (ImageDecoder API) first, falling back to the pure JS decoder with tolerant mode for maximum
 compatibility.
 
@@ -394,7 +500,7 @@ const jpegSupports = Image.getSupportedMetadata("jpeg");
 console.log(jpegSupports); // Includes ISO, camera info, GPS, etc.
 
 // Save with metadata
-const jpeg = await image.save("jpeg");
+const jpeg = await image.encode("jpeg");
 await Deno.writeFile("output.jpg", jpeg);
 
 // Metadata is preserved on reload!
@@ -488,6 +594,8 @@ Image.getSupportedMetadata("avif"); // Full camera metadata + GPS (19 fields)
   Technical details for WebP
 - **[TIFF Implementation](https://cross-image.56k.guru/implementation/tiff-implementation/)** -
   Technical details for TIFF
+- **[GIF Implementation](https://cross-image.56k.guru/implementation/gif-implementation/)** -
+  Technical details for GIF
 
 ## Development
 

package/esm/mod.d.ts

@@ -43,7 +43,7 @@
  * ```
  */
 export { Image } from "./src/image.js";
-export type { ASCIIEncoderOptions, FrameMetadata, ImageData, ImageDecoderOptions, ImageFormat, ImageFrame, ImageMetadata, JPEGEncoderOptions, MultiFrameImageData, ResizeOptions, TIFFEncoderOptions, WebPEncoderOptions, } from "./src/types.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 { PNGFormat } from "./src/formats/png.js";
 export { APNGFormat } from "./src/formats/apng.js";
 export { JPEGFormat } from "./src/formats/jpeg.js";
@@ -59,4 +59,6 @@ export { PPMFormat } from "./src/formats/ppm.js";
 export { ASCIIFormat } from "./src/formats/ascii.js";
 export { HEICFormat } from "./src/formats/heic.js";
 export { AVIFFormat } from "./src/formats/avif.js";
+export { decodeBase64, encodeBase64, parseDataUrl, toDataUrl } from "./src/utils/base64.js";
+export { cmykToRgb, cmykToRgba, rgbaToCmyk, rgbToCmyk } from "./src/utils/image_processing.js";
 //# sourceMappingURL=mod.d.ts.map

package/esm/mod.js

@@ -58,3 +58,5 @@ export { PPMFormat } from "./src/formats/ppm.js";
 export { ASCIIFormat } from "./src/formats/ascii.js";
 export { HEICFormat } from "./src/formats/heic.js";
 export { AVIFFormat } from "./src/formats/avif.js";
+export { decodeBase64, encodeBase64, parseDataUrl, toDataUrl } from "./src/utils/base64.js";
+export { cmykToRgb, cmykToRgba, rgbaToCmyk, rgbToCmyk } from "./src/utils/image_processing.js";

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

@@ -1,4 +1,4 @@
-import type { ImageData, ImageDecoderOptions, ImageFormat, ImageMetadata, MultiFrameImageData } from "../types.js";
+import type { APNGEncoderOptions, ImageData, ImageDecoderOptions, ImageFormat, ImageMetadata, MultiFrameImageData } from "../types.js";
 import { PNGBase } from "./png_base.js";
 /**
  * APNG (Animated PNG) format handler
@@ -36,15 +36,17 @@ export declare class APNGFormat extends PNGBase implements ImageFormat {
     /**
      * Encode RGBA image data to APNG format (single frame)
      * @param imageData Image data to encode
+     * @param options Encoding options (compressionLevel 0-9, default 6)
      * @returns Encoded APNG image bytes
      */
-    encode(imageData: ImageData, _options?: unknown): Promise<Uint8Array>;
+    encode(imageData: ImageData, options?: APNGEncoderOptions): Promise<Uint8Array>;
     /**
      * Encode multi-frame image data to APNG format
      * @param imageData Multi-frame image data to encode
+     * @param options Encoding options (compressionLevel 0-9, default 6)
      * @returns Encoded APNG image bytes
      */
-    encodeFrames(imageData: MultiFrameImageData, _options?: unknown): Promise<Uint8Array>;
+    encodeFrames(imageData: MultiFrameImageData, options?: APNGEncoderOptions): Promise<Uint8Array>;
     private decodeFrameData;
     /**
      * Get the list of metadata fields supported by APNG format

package/esm/src/formats/apng.js

@@ -250,9 +250,10 @@ export class APNGFormat extends PNGBase {
     /**
      * Encode RGBA image data to APNG format (single frame)
      * @param imageData Image data to encode
+     * @param options Encoding options (compressionLevel 0-9, default 6)
      * @returns Encoded APNG image bytes
      */
-    encode(imageData, _options) {
+    encode(imageData, options) {
         // For single frame, create a multi-frame with one frame
         const multiFrame = {
             width: imageData.width,
@@ -265,15 +266,21 @@ export class APNGFormat extends PNGBase {
                 }],
             metadata: imageData.metadata,
         };
-        return this.encodeFrames(multiFrame, _options);
+        return this.encodeFrames(multiFrame, options);
     }
     /**
      * Encode multi-frame image data to APNG format
      * @param imageData Multi-frame image data to encode
+     * @param options Encoding options (compressionLevel 0-9, default 6)
      * @returns Encoded APNG image bytes
      */
-    async encodeFrames(imageData, _options) {
+    async encodeFrames(imageData, options) {
         const { width, height, frames, metadata } = imageData;
+        const compressionLevel = options?.compressionLevel ?? 6;
+        // Validate compression level
+        if (compressionLevel < 0 || compressionLevel > 9) {
+            throw new Error("Compression level must be between 0 and 9");
+        }
         if (frames.length === 0) {
             throw new Error("No frames to encode");
         }
@@ -331,7 +338,7 @@ export class APNGFormat extends PNGBase {
             fctl[25] = 0; // blend_op: APNG_BLEND_OP_SOURCE
             chunks.push(this.createChunk("fcTL", fctl));
             // Filter and compress frame data
-            const filtered = this.filterData(frame.data, frame.width, frame.height);
+            const filtered = this.filterData(frame.data, frame.width, frame.height, compressionLevel);
             const compressed = await this.deflate(filtered);
             if (i === 0) {
                 // First frame uses IDAT

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

@@ -1,4 +1,4 @@
-import type { ImageData, ImageDecoderOptions, ImageFormat, ImageMetadata } from "../types.js";
+import type { AVIFEncoderOptions, ImageData, ImageDecoderOptions, ImageFormat, ImageMetadata } from "../types.js";
 /**
  * AVIF format handler
  * Supports AVIF images using runtime APIs (ImageDecoder/OffscreenCanvas)
@@ -32,7 +32,7 @@ export declare class AVIFFormat implements ImageFormat {
      * @param imageData Image data to encode
      * @returns Encoded AVIF image bytes
      */
-    encode(imageData: ImageData, _options?: unknown): Promise<Uint8Array>;
+    encode(imageData: ImageData, options?: AVIFEncoderOptions): Promise<Uint8Array>;
     /**
      * Decode using runtime APIs
      * @param data Raw AVIF data

package/esm/src/formats/avif.js

@@ -79,8 +79,9 @@ export class AVIFFormat {
      * @param imageData Image data to encode
      * @returns Encoded AVIF image bytes
      */
-    async encode(imageData, _options) {
+    async encode(imageData, options) {
         const { width, height, data, metadata: _metadata } = imageData;
+        const requestedQuality = options?.quality;
         // Try to use runtime encoding if available
         if (typeof OffscreenCanvas !== "undefined") {
             try {
@@ -91,10 +92,19 @@ export class AVIFFormat {
                     const imgDataData = new Uint8ClampedArray(data);
                     imgData.data.set(imgDataData);
                     ctx.putImageData(imgData, 0, 0);
+                    const quality = requestedQuality === undefined
+                        ? undefined
+                        : (requestedQuality <= 1
+                            ? Math.max(0, Math.min(1, requestedQuality))
+                            : Math.max(1, Math.min(100, requestedQuality)) / 100);
                     // Try to encode as AVIF
                     const blob = await canvas.convertToBlob({
                         type: "image/avif",
+                        ...(quality === undefined ? {} : { quality }),
                     });
+                    if (blob.type !== "image/avif") {
+                        throw new Error(`Runtime did not encode AVIF (got '${blob.type || "(empty)"}')`);
+                    }
                     const arrayBuffer = await blob.arrayBuffer();
                     const encoded = new Uint8Array(arrayBuffer);
                     // Note: Metadata injection for AVIF is complex and would require

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

@@ -1,4 +1,4 @@
-import type { ImageData, ImageDecoderOptions, ImageFormat, ImageMetadata, MultiFrameImageData } from "../types.js";
+import type { GIFEncoderOptions, ImageData, ImageDecoderOptions, ImageFormat, ImageMetadata, MultiFrameImageData } from "../types.js";
 /**
  * GIF format handler
  * Now includes pure-JS implementation with custom LZW compression/decompression
@@ -39,7 +39,7 @@ export declare class GIFFormat implements ImageFormat {
      * @param imageData Image data to encode
      * @returns Encoded GIF image bytes
      */
-    encode(imageData: ImageData, _options?: unknown): Promise<Uint8Array>;
+    encode(imageData: ImageData, options?: GIFEncoderOptions): Promise<Uint8Array>;
     /**
      * Decode all frames from an animated GIF
      */
@@ -47,7 +47,7 @@ export declare class GIFFormat implements ImageFormat {
     /**
      * Encode multi-frame image data to animated GIF
      */
-    encodeFrames(imageData: MultiFrameImageData, _options?: unknown): Promise<Uint8Array>;
+    encodeFrames(imageData: MultiFrameImageData, options?: GIFEncoderOptions): Promise<Uint8Array>;
     private mapDisposalMethod;
     private decodeUsingRuntime;
     private readDataSubBlocks;

package/esm/src/formats/gif.js

@@ -153,12 +153,12 @@ export class GIFFormat {
      * @param imageData Image data to encode
      * @returns Encoded GIF image bytes
      */
-    async encode(imageData, _options) {
+    async encode(imageData, options) {
         const { width, height, data, metadata } = imageData;
         // Try pure-JS encoder first
         try {
             const encoder = new GIFEncoder(width, height, data);
-            const encoded = encoder.encode();
+            const encoded = encoder.encode(options);
             // Inject metadata if present
             if (metadata && Object.keys(metadata).length > 0) {
                 const injected = this.injectMetadata(encoded, metadata);
@@ -237,7 +237,7 @@ export class GIFFormat {
     /**
      * Encode multi-frame image data to animated GIF
      */
-    encodeFrames(imageData, _options) {
+    encodeFrames(imageData, options) {
         if (imageData.frames.length === 0) {
             throw new Error("No frames to encode");
         }
@@ -247,7 +247,7 @@ export class GIFFormat {
             const delay = frame.frameMetadata?.delay ?? 100;
             encoder.addFrame(frame.data, delay);
         }
-        return Promise.resolve(encoder.encode());
+        return Promise.resolve(encoder.encode(options));
     }
     mapDisposalMethod(disposal) {
         switch (disposal) {

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

@@ -1,4 +1,4 @@
-import type { ImageData, ImageDecoderOptions, ImageFormat, ImageMetadata } from "../types.js";
+import type { HEICEncoderOptions, ImageData, ImageDecoderOptions, ImageFormat, ImageMetadata } from "../types.js";
 /**
  * HEIC format handler
  * Supports HEIC/HEIF images using runtime APIs (ImageDecoder/OffscreenCanvas)
@@ -32,7 +32,7 @@ export declare class HEICFormat implements ImageFormat {
      * @param imageData Image data to encode
      * @returns Encoded HEIC image bytes
      */
-    encode(imageData: ImageData, _options?: unknown): Promise<Uint8Array>;
+    encode(imageData: ImageData, options?: HEICEncoderOptions): Promise<Uint8Array>;
     /**
      * Decode using runtime APIs
      * @param data Raw HEIC data

package/esm/src/formats/heic.js

@@ -80,8 +80,9 @@ export class HEICFormat {
      * @param imageData Image data to encode
      * @returns Encoded HEIC image bytes
      */
-    async encode(imageData, _options) {
+    async encode(imageData, options) {
         const { width, height, data, metadata: _metadata } = imageData;
+        const requestedQuality = options?.quality;
         // Try to use runtime encoding if available
         if (typeof OffscreenCanvas !== "undefined") {
             try {
@@ -92,10 +93,19 @@ export class HEICFormat {
                     const imgDataData = new Uint8ClampedArray(data);
                     imgData.data.set(imgDataData);
                     ctx.putImageData(imgData, 0, 0);
+                    const quality = requestedQuality === undefined
+                        ? undefined
+                        : (requestedQuality <= 1
+                            ? Math.max(0, Math.min(1, requestedQuality))
+                            : Math.max(1, Math.min(100, requestedQuality)) / 100);
                     // Try to encode as HEIC
                     const blob = await canvas.convertToBlob({
                         type: "image/heic",
+                        ...(quality === undefined ? {} : { quality }),
                     });
+                    if (blob.type !== "image/heic") {
+                        throw new Error(`Runtime did not encode HEIC (got '${blob.type || "(empty)"}')`);
+                    }
                     const arrayBuffer = await blob.arrayBuffer();
                     const encoded = new Uint8Array(arrayBuffer);
                     // Note: Metadata injection for HEIC is complex and would require

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

@@ -1,4 +1,4 @@
-import type { ImageData, ImageDecoderOptions, ImageFormat, ImageMetadata } from "../types.js";
+import type { ImageData, ImageDecoderOptions, ImageFormat, ImageMetadata, PNGEncoderOptions } from "../types.js";
 import { PNGBase } from "./png_base.js";
 /**
  * PNG format handler
@@ -24,9 +24,10 @@ export declare class PNGFormat extends PNGBase implements ImageFormat {
     /**
      * Encode RGBA image data to PNG format
      * @param imageData Image data to encode
+     * @param options Encoding options (compressionLevel 0-9, default 6)
      * @returns Encoded PNG image bytes
      */
-    encode(imageData: ImageData, _options?: unknown): Promise<Uint8Array>;
+    encode(imageData: ImageData, options?: PNGEncoderOptions): Promise<Uint8Array>;
     /**
      * Get the list of metadata fields supported by PNG format
      * Delegates to PNGBase implementation

package/esm/src/formats/png.js

@@ -110,10 +110,16 @@ export class PNGFormat extends PNGBase {
     /**
      * Encode RGBA image data to PNG format
      * @param imageData Image data to encode
+     * @param options Encoding options (compressionLevel 0-9, default 6)
      * @returns Encoded PNG image bytes
      */
-    async encode(imageData, _options) {
+    async encode(imageData, options) {
         const { width, height, data, metadata } = imageData;
+        const compressionLevel = options?.compressionLevel ?? 6;
+        // Validate compression level
+        if (compressionLevel < 0 || compressionLevel > 9) {
+            throw new Error("Compression level must be between 0 and 9");
+        }
         // Prepare IHDR chunk
         const ihdr = new Uint8Array(13);
         this.writeUint32(ihdr, 0, width);
@@ -124,7 +130,7 @@ export class PNGFormat extends PNGBase {
         ihdr[11] = 0; // filter method
         ihdr[12] = 0; // interlace method
         // Filter and compress image data
-        const filtered = this.filterData(data, width, height);
+        const filtered = this.filterData(data, width, height, compressionLevel);
         const compressed = await this.deflate(filtered);
         // Build PNG
         const chunks = [];

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

@@ -43,7 +43,48 @@ export declare abstract class PNGBase {
     /**
      * Filter PNG data for encoding (using filter type 0 - None)
      */
-    protected filterData(data: Uint8Array, width: number, height: number): Uint8Array;
+    /**
+     * Apply PNG filter to image data based on compression level
+     * @param data Raw RGBA pixel data
+     * @param width Image width
+     * @param height Image height
+     * @param compressionLevel Compression level (0-9, default 6)
+     * @returns Filtered data with filter type byte per scanline
+     */
+    protected filterData(data: Uint8Array, width: number, height: number, compressionLevel?: number): Uint8Array;
+    /**
+     * Apply filter type 0 (None) - no filtering
+     */
+    private applyNoFilter;
+    /**
+     * Apply filter type 1 (Sub) - subtract left pixel
+     */
+    private applySubFilter;
+    /**
+     * Apply filter type 2 (Up) - subtract above pixel
+     */
+    private applyUpFilter;
+    /**
+     * Apply filter type 3 (Average) - subtract average of left and above
+     */
+    private applyAverageFilter;
+    /**
+     * Apply filter type 4 (Paeth) - Paeth predictor
+     */
+    private applyPaethFilter;
+    /**
+     * Calculate sum of absolute differences for a filtered scanline
+     * Lower values indicate better compression potential
+     */
+    private calculateFilterScore;
+    /**
+     * Apply adaptive filtering - choose best filter per scanline
+     */
+    private applyAdaptiveFilter;
+    /**
+     * Filter a single scanline with specified filter type
+     */
+    private filterScanline;
     /**
      * Get bytes per pixel for a given color type and bit depth
      */