cross-image 0.1.4 → 0.2.0

package/esm/src/formats/pam.js

@@ -0,0 +1,177 @@
+import { validateImageDimensions } from "../utils/security.js";
+/**
+ * PAM format handler
+ * Implements the Netpbm PAM (Portable Arbitrary Map) format.
+ * This is a standard uncompressed format supported by GIMP and other tools.
+ *
+ * Format structure:
+ * - Header (text):
+ *   P7
+ *   WIDTH <width>
+ *   HEIGHT <height>
+ *   DEPTH 4
+ *   MAXVAL 255
+ *   TUPLTYPE RGB_ALPHA
+ *   ENDHDR
+ * - Data (binary):
+ *   RGBA pixel data (width * height * 4 bytes)
+ */
+export class PAMFormat {
+    constructor() {
+        /** Format name identifier */
+        Object.defineProperty(this, "name", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: "pam"
+        });
+        /** MIME type for PAM images */
+        Object.defineProperty(this, "mimeType", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: "image/x-portable-arbitrary-map"
+        });
+    }
+    /**
+     * Check if the given data is a PAM image
+     * @param data Raw image data to check
+     * @returns true if data has PAM signature
+     */
+    canDecode(data) {
+        // Check if data has at least magic bytes
+        if (data.length < 3) {
+            return false;
+        }
+        // Check for P7 followed by whitespace (usually newline)
+        return data[0] === 0x50 && // P
+            data[1] === 0x37 && // 7
+            (data[2] === 0x0a || data[2] === 0x0d || data[2] === 0x20); // \n, \r, or space
+    }
+    /**
+     * Decode PAM image data to RGBA
+     * @param data Raw PAM image data
+     * @returns Decoded image data with RGBA pixels
+     */
+    decode(data) {
+        if (!this.canDecode(data)) {
+            throw new Error("Invalid PAM signature");
+        }
+        // Parse header
+        let offset = 0;
+        let width = 0;
+        let height = 0;
+        let depth = 0;
+        let maxval = 0;
+        let headerDone = false;
+        const decoder = new TextDecoder();
+        // Find end of header
+        // We need to read line by line.
+        // Since we have the full buffer, we can just scan for newlines.
+        let lineStart = 0;
+        while (!headerDone && offset < data.length) {
+            // Find next newline
+            let lineEnd = -1;
+            for (let i = offset; i < data.length; i++) {
+                if (data[i] === 0x0a) {
+                    lineEnd = i;
+                    break;
+                }
+            }
+            if (lineEnd === -1) {
+                throw new Error("Unexpected end of file in header");
+            }
+            const line = decoder.decode(data.subarray(lineStart, lineEnd)).trim();
+            offset = lineEnd + 1; // Skip newline
+            lineStart = offset;
+            // Skip comments
+            if (line.startsWith("#"))
+                continue;
+            if (line === "")
+                continue;
+            if (line === "P7")
+                continue;
+            if (line === "ENDHDR") {
+                headerDone = true;
+                break;
+            }
+            // Parse fields
+            const parts = line.split(/\s+/);
+            if (parts.length >= 2) {
+                const key = parts[0];
+                const value = parts[1];
+                switch (key) {
+                    case "WIDTH":
+                        width = parseInt(value, 10);
+                        break;
+                    case "HEIGHT":
+                        height = parseInt(value, 10);
+                        break;
+                    case "DEPTH":
+                        depth = parseInt(value, 10);
+                        break;
+                    case "MAXVAL":
+                        maxval = parseInt(value, 10);
+                        break;
+                    case "TUPLTYPE":
+                        // Optional check
+                        break;
+                }
+            }
+        }
+        if (!headerDone) {
+            throw new Error("Invalid PAM header: missing ENDHDR");
+        }
+        // Validate dimensions
+        if (width <= 0 || height <= 0) {
+            throw new Error(`Invalid PAM dimensions: ${width}x${height}`);
+        }
+        // Validate dimensions for security
+        validateImageDimensions(width, height);
+        // We only support DEPTH 4 (RGBA) and MAXVAL 255 for now
+        if (depth !== 4) {
+            throw new Error(`Unsupported PAM depth: ${depth}. Only depth 4 (RGBA) is supported.`);
+        }
+        if (maxval !== 255) {
+            throw new Error(`Unsupported PAM maxval: ${maxval}. Only maxval 255 is supported.`);
+        }
+        const expectedDataLength = width * height * 4;
+        const actualDataLength = data.length - offset;
+        if (actualDataLength < expectedDataLength) {
+            throw new Error(`Invalid PAM data length: expected ${expectedDataLength}, got ${actualDataLength}`);
+        }
+        // Extract pixel data
+        const pixelData = new Uint8Array(expectedDataLength);
+        pixelData.set(data.subarray(offset, offset + expectedDataLength));
+        return Promise.resolve({ width, height, data: pixelData });
+    }
+    /**
+     * Encode RGBA image data to PAM format
+     * @param imageData Image data to encode
+     * @returns Encoded PAM image bytes
+     */
+    encode(imageData) {
+        const { width, height, data } = imageData;
+        // Validate input
+        if (data.length !== width * height * 4) {
+            throw new Error(`Data length mismatch: expected ${width * height * 4}, got ${data.length}`);
+        }
+        // Create header
+        const header = `P7\n` +
+            `WIDTH ${width}\n` +
+            `HEIGHT ${height}\n` +
+            `DEPTH 4\n` +
+            `MAXVAL 255\n` +
+            `TUPLTYPE RGB_ALPHA\n` +
+            `ENDHDR\n`;
+        const encoder = new TextEncoder();
+        const headerBytes = encoder.encode(header);
+        // Create output buffer
+        const output = new Uint8Array(headerBytes.length + data.length);
+        // Write header
+        output.set(headerBytes, 0);
+        // Write pixel data
+        output.set(data, headerBytes.length);
+        return Promise.resolve(output);
+    }
+}

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

@@ -0,0 +1,13 @@
+import type { ImageData, ImageFormat } from "../types.js";
+/**
+ * PCX format handler
+ * Implements PCX decoder and encoder
+ */
+export declare class PCXFormat implements ImageFormat {
+    readonly name = "pcx";
+    readonly mimeType = "image/x-pcx";
+    canDecode(data: Uint8Array): boolean;
+    decode(data: Uint8Array): Promise<ImageData>;
+    encode(image: ImageData): Promise<Uint8Array>;
+}
+//# sourceMappingURL=pcx.d.ts.map

package/esm/src/formats/pcx.js

@@ -0,0 +1,204 @@
+/**
+ * PCX format handler
+ * Implements PCX decoder and encoder
+ */
+export class PCXFormat {
+    constructor() {
+        Object.defineProperty(this, "name", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: "pcx"
+        });
+        Object.defineProperty(this, "mimeType", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: "image/x-pcx"
+        });
+    }
+    canDecode(data) {
+        // PCX header check
+        // Byte 0: Manufacturer (must be 0x0A)
+        // Byte 1: Version (0, 2, 3, 4, 5)
+        // Byte 2: Encoding (1 = RLE)
+        return data.length >= 128 &&
+            data[0] === 0x0A &&
+            (data[1] === 0 || data[1] === 2 || data[1] === 3 || data[1] === 4 ||
+                data[1] === 5) &&
+            data[2] === 1;
+    }
+    decode(data) {
+        if (!this.canDecode(data)) {
+            return Promise.reject(new Error("Invalid PCX data"));
+        }
+        const view = new DataView(data.buffer, data.byteOffset, data.byteLength);
+        // Parse header
+        // const manufacturer = view.getUint8(0);
+        // const version = view.getUint8(1);
+        // const encoding = view.getUint8(2);
+        const bitsPerPixel = view.getUint8(3);
+        const xMin = view.getUint16(4, true);
+        const yMin = view.getUint16(6, true);
+        const xMax = view.getUint16(8, true);
+        const yMax = view.getUint16(10, true);
+        // const hDpi = view.getUint16(12, true);
+        // const vDpi = view.getUint16(14, true);
+        // const colormap = data.slice(16, 64);
+        // const reserved = view.getUint8(64);
+        const nPlanes = view.getUint8(65);
+        const bytesPerLine = view.getUint16(66, true);
+        // const paletteInfo = view.getUint16(68, true);
+        // const hScreenSize = view.getUint16(70, true);
+        // const vScreenSize = view.getUint16(72, true);
+        const width = xMax - xMin + 1;
+        const height = yMax - yMin + 1;
+        if (width <= 0 || height <= 0) {
+            return Promise.reject(new Error("Invalid PCX dimensions"));
+        }
+        // Decode RLE data
+        let offset = 128;
+        const scanlineLength = nPlanes * bytesPerLine;
+        const rawData = new Uint8Array(height * scanlineLength);
+        let ptr = 0;
+        // Decode all scanlines
+        for (let y = 0; y < height; y++) {
+            let x = 0;
+            while (x < scanlineLength) {
+                if (offset >= data.length)
+                    break;
+                let byte = data[offset++];
+                let count = 1;
+                if ((byte & 0xC0) === 0xC0) {
+                    count = byte & 0x3F;
+                    if (offset >= data.length)
+                        break;
+                    byte = data[offset++];
+                }
+                for (let i = 0; i < count; i++) {
+                    if (ptr < rawData.length) {
+                        rawData[ptr++] = byte;
+                    }
+                    x++;
+                }
+            }
+        }
+        const rgba = new Uint8Array(width * height * 4);
+        if (nPlanes === 3 && bitsPerPixel === 8) {
+            // 24-bit RGB
+            for (let y = 0; y < height; y++) {
+                for (let x = 0; x < width; x++) {
+                    const r = rawData[y * scanlineLength + x];
+                    const g = rawData[y * scanlineLength + bytesPerLine + x];
+                    const b = rawData[y * scanlineLength + 2 * bytesPerLine + x];
+                    const idx = (y * width + x) * 4;
+                    rgba[idx] = r;
+                    rgba[idx + 1] = g;
+                    rgba[idx + 2] = b;
+                    rgba[idx + 3] = 255;
+                }
+            }
+        }
+        else if (nPlanes === 1 && bitsPerPixel === 8) {
+            // 8-bit palette
+            // Check for palette at end of file
+            let palette;
+            if (data[data.length - 769] === 0x0C) {
+                palette = data.slice(data.length - 768);
+            }
+            else {
+                // Fallback or error?
+                // Some old PCX might use header palette but that's only 16 colors.
+                // For 8bpp we expect 256 color palette at end.
+                return Promise.reject(new Error("Missing PCX palette"));
+            }
+            for (let y = 0; y < height; y++) {
+                for (let x = 0; x < width; x++) {
+                    const colorIndex = rawData[y * scanlineLength + x];
+                    const idx = (y * width + x) * 4;
+                    rgba[idx] = palette[colorIndex * 3];
+                    rgba[idx + 1] = palette[colorIndex * 3 + 1];
+                    rgba[idx + 2] = palette[colorIndex * 3 + 2];
+                    rgba[idx + 3] = 255;
+                }
+            }
+        }
+        else {
+            // Unsupported PCX format (e.g. 1-bit, 4-bit)
+            // For now only supporting 24-bit and 8-bit
+            return Promise.reject(new Error("Unsupported PCX format"));
+        }
+        return Promise.resolve({
+            width,
+            height,
+            data: rgba,
+        });
+    }
+    encode(image) {
+        const width = image.width;
+        const height = image.height;
+        const data = image.data;
+        // We will encode as 24-bit RGB (3 planes)
+        const header = new Uint8Array(128);
+        const view = new DataView(header.buffer);
+        view.setUint8(0, 0x0A); // Manufacturer
+        view.setUint8(1, 5); // Version 3.0+
+        view.setUint8(2, 1); // Encoding RLE
+        view.setUint8(3, 8); // Bits per pixel (8 per plane)
+        view.setUint16(4, 0, true); // XMin
+        view.setUint16(6, 0, true); // YMin
+        view.setUint16(8, width - 1, true); // XMax
+        view.setUint16(10, height - 1, true); // YMax
+        view.setUint16(12, 72, true); // HDpi
+        view.setUint16(14, 72, true); // VDpi
+        view.setUint8(65, 3); // NPlanes (3 for RGB)
+        view.setUint16(66, width + (width % 2), true); // BytesPerLine (must be even)
+        view.setUint16(68, 1, true); // PaletteInfo (Color/BW)
+        const bytesPerLine = width + (width % 2);
+        const scanlineLength = bytesPerLine * 3;
+        const rleData = [];
+        // Helper to write RLE
+        const writeRLE = (byte, count) => {
+            if ((byte & 0xC0) === 0xC0 || count > 1) {
+                rleData.push(0xC0 | count);
+                rleData.push(byte);
+            }
+            else {
+                rleData.push(byte);
+            }
+        };
+        for (let y = 0; y < height; y++) {
+            // Prepare scanline planes
+            const lineR = new Uint8Array(bytesPerLine);
+            const lineG = new Uint8Array(bytesPerLine);
+            const lineB = new Uint8Array(bytesPerLine);
+            for (let x = 0; x < width; x++) {
+                const idx = (y * width + x) * 4;
+                lineR[x] = data[idx];
+                lineG[x] = data[idx + 1];
+                lineB[x] = data[idx + 2];
+            }
+            // Compress each plane
+            for (const plane of [lineR, lineG, lineB]) {
+                let currentByte = plane[0];
+                let runLength = 1;
+                for (let x = 1; x < bytesPerLine; x++) {
+                    const byte = plane[x];
+                    if (byte === currentByte && runLength < 63) {
+                        runLength++;
+                    }
+                    else {
+                        writeRLE(currentByte, runLength);
+                        currentByte = byte;
+                        runLength = 1;
+                    }
+                }
+                writeRLE(currentByte, runLength);
+            }
+        }
+        const result = new Uint8Array(header.length + rleData.length);
+        result.set(header);
+        result.set(rleData, header.length);
+        return Promise.resolve(result);
+    }
+}

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

@@ -15,9 +15,9 @@ export interface TIFFEncodeOptions {
  */
 export declare class TIFFFormat implements ImageFormat {
     /** Format name identifier */
-    readonly name = "tiff";
+    readonly name: string;
     /** MIME type for TIFF images */
-    readonly mimeType = "image/tiff";
+    readonly mimeType: string;
     /**
      * Check if this format supports multiple frames (pages)
      * @returns true for TIFF format
@@ -52,11 +52,11 @@ export declare class TIFFFormat implements ImageFormat {
      * Extract metadata from an IFD
      */
     private extractMetadataFromIFD;
-    private readUint16;
-    private readUint32;
-    private writeUint16LE;
-    private writeUint32LE;
-    private writeIFDEntry;
+    protected readUint16(data: Uint8Array, offset: number, isLittleEndian: boolean): number;
+    protected readUint32(data: Uint8Array, offset: number, isLittleEndian: boolean): number;
+    protected writeUint16LE(result: number[], value: number): void;
+    protected writeUint32LE(result: number[], value: number): void;
+    protected writeIFDEntry(result: number[], tag: number, type: number, count: number, valueOrOffset: number): void;
     private getIFDValue;
     private decodeUsingRuntime;
     private readString;

package/esm/src/image.d.ts

@@ -72,24 +72,49 @@ export declare class Image {
      * Get all registered formats
      */
     static getFormats(): readonly ImageFormat[];
+    /**
+     * Decode an image from bytes
+     * @param data Raw image data
+     * @param format Optional format hint (e.g., "png", "jpeg", "webp")
+     * @returns Image instance
+     */
+    static decode(data: Uint8Array, format?: string): Promise<Image>;
     /**
      * Read an image from bytes
+     * @deprecated Use `decode()` instead. This method will be removed in a future version.
      * @param data Raw image data
      * @param format Optional format hint (e.g., "png", "jpeg", "webp")
      * @returns Image instance
      */
     static read(data: Uint8Array, format?: string): Promise<Image>;
+    /**
+     * 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 decodeFrames(data: Uint8Array, format?: string): Promise<MultiFrameImageData>;
     /**
      * 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.
      * @param data Raw image data
      * @param format Optional format hint (e.g., "gif", "tiff")
      * @returns MultiFrameImageData with all frames
      */
     static readFrames(data: Uint8Array, format?: string): Promise<MultiFrameImageData>;
+    /**
+     * Encode multi-frame image data to bytes in the specified format
+     * @param format Format name (e.g., "gif", "tiff")
+     * @param imageData Multi-frame image data to encode
+     * @param options Optional format-specific encoding options
+     * @returns Encoded image bytes
+     */
+    static encodeFrames(format: string, imageData: MultiFrameImageData, options?: unknown): Promise<Uint8Array>;
     /**
      * Save multi-frame image data to bytes in the specified format
+     * @deprecated Use `encodeFrames()` instead. This method will be removed in a future version.
      * @param format Format name (e.g., "gif", "tiff")
-     * @param imageData Multi-frame image data to save
+     * @param imageData Multi-frame image data to encode
      * @param options Optional format-specific encoding options
      * @returns Encoded image bytes
      */
@@ -102,14 +127,33 @@ export declare class Image {
      * @returns Image instance
      */
     static fromRGBA(width: number, height: number, data: Uint8Array): Image;
+    /**
+     * Create a blank image with the specified dimensions and color
+     * @param width Image width
+     * @param height Image height
+     * @param r Red component (0-255, default: 0)
+     * @param g Green component (0-255, default: 0)
+     * @param b Blue component (0-255, default: 0)
+     * @param a Alpha component (0-255, default: 255)
+     * @returns Image instance
+     */
+    static create(width: number, height: number, r?: number, g?: number, b?: number, a?: number): Image;
     /**
      * Resize the image
      * @param options Resize options
      * @returns This image instance for chaining
      */
     resize(options: ResizeOptions): this;
+    /**
+     * Encode the image to bytes in the specified format
+     * @param format Format name (e.g., "png", "jpeg", "webp", "ascii")
+     * @param options Optional format-specific encoding options
+     * @returns Encoded image bytes
+     */
+    encode(format: string, options?: unknown): Promise<Uint8Array>;
     /**
      * Save the image to bytes in the specified format
+     * @deprecated Use `encode()` instead. This method will be removed in a future version.
      * @param format Format name (e.g., "png", "jpeg", "webp", "ascii")
      * @param options Optional format-specific encoding options
      * @returns Encoded image bytes
@@ -120,5 +164,93 @@ export declare class Image {
      * @returns New image instance with copied data and metadata
      */
     clone(): Image;
+    /**
+     * Composite another image on top of this image at the specified position
+     * @param overlay Image to place on top
+     * @param x X position (can be negative)
+     * @param y Y position (can be negative)
+     * @param opacity Opacity of overlay (0-1, default: 1)
+     * @returns This image instance for chaining
+     */
+    composite(overlay: Image, x: number, y: number, opacity?: number): this;
+    /**
+     * Adjust brightness of the image
+     * @param amount Brightness adjustment (-1 to 1, where 0 is no change)
+     * @returns This image instance for chaining
+     */
+    brightness(amount: number): this;
+    /**
+     * Adjust contrast of the image
+     * @param amount Contrast adjustment (-1 to 1, where 0 is no change)
+     * @returns This image instance for chaining
+     */
+    contrast(amount: number): this;
+    /**
+     * Adjust exposure of the image
+     * @param amount Exposure adjustment in stops (-3 to 3, where 0 is no change)
+     * @returns This image instance for chaining
+     */
+    exposure(amount: number): this;
+    /**
+     * Adjust saturation of the image
+     * @param amount Saturation adjustment (-1 to 1, where 0 is no change)
+     * @returns This image instance for chaining
+     */
+    saturation(amount: number): this;
+    /**
+     * Invert colors of the image
+     * @returns This image instance for chaining
+     */
+    invert(): this;
+    /**
+     * Convert the image to grayscale
+     * @returns This image instance for chaining
+     */
+    grayscale(): this;
+    /**
+     * Fill a rectangular region with a color
+     * @param x Starting X position
+     * @param y Starting Y position
+     * @param width Width of the fill region
+     * @param height Height of the fill region
+     * @param r Red component (0-255)
+     * @param g Green component (0-255)
+     * @param b Blue component (0-255)
+     * @param a Alpha component (0-255, default: 255)
+     * @returns This image instance for chaining
+     */
+    fillRect(x: number, y: number, width: number, height: number, r: number, g: number, b: number, a?: number): this;
+    /**
+     * Crop the image to a rectangular region
+     * @param x Starting X position
+     * @param y Starting Y position
+     * @param width Width of the crop region
+     * @param height Height of the crop region
+     * @returns This image instance for chaining
+     */
+    crop(x: number, y: number, width: number, height: number): this;
+    /**
+     * Get the pixel color at the specified position
+     * @param x X position
+     * @param y Y position
+     * @returns Object with r, g, b, a components (0-255) or undefined if out of bounds
+     */
+    getPixel(x: number, y: number): {
+        r: number;
+        g: number;
+        b: number;
+        a: number;
+    } | undefined;
+    /**
+     * Set the pixel color at the specified position
+     * @param x X position
+     * @param y Y position
+     * @param r Red component (0-255)
+     * @param g Green component (0-255)
+     * @param b Blue component (0-255)
+     * @param a Alpha component (0-255, default: 255)
+     * @returns This image instance for chaining
+     */
+    setPixel(x: number, y: number, r: number, g: number, b: number, a?: number): this;
 }
 //# sourceMappingURL=image.d.ts.map