cross-image 0.1.2

package/esm/src/image.js

@@ -0,0 +1,320 @@
+import { resizeBilinear, resizeNearest } from "./utils/resize.js";
+import { PNGFormat } from "./formats/png.js";
+import { JPEGFormat } from "./formats/jpeg.js";
+import { WebPFormat } from "./formats/webp.js";
+import { GIFFormat } from "./formats/gif.js";
+import { TIFFFormat } from "./formats/tiff.js";
+import { BMPFormat } from "./formats/bmp.js";
+import { RAWFormat } from "./formats/raw.js";
+import { ASCIIFormat } from "./formats/ascii.js";
+/**
+ * Main Image class for reading, manipulating, and saving images
+ */
+export class Image {
+    constructor() {
+        Object.defineProperty(this, "imageData", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: null
+        });
+    }
+    /**
+     * Get the current image width
+     */
+    get width() {
+        if (!this.imageData)
+            throw new Error("No image loaded");
+        return this.imageData.width;
+    }
+    /**
+     * Get the current image height
+     */
+    get height() {
+        if (!this.imageData)
+            throw new Error("No image loaded");
+        return this.imageData.height;
+    }
+    /**
+     * Get the current image data
+     */
+    get data() {
+        if (!this.imageData)
+            throw new Error("No image loaded");
+        return this.imageData.data;
+    }
+    /**
+     * Get the current image metadata
+     */
+    get metadata() {
+        if (!this.imageData)
+            throw new Error("No image loaded");
+        return this.imageData.metadata;
+    }
+    /**
+     * Set or update image metadata
+     * @param metadata Metadata to set or merge
+     * @param merge If true, merges with existing metadata. If false, replaces it. Default: true
+     */
+    setMetadata(metadata, merge = true) {
+        if (!this.imageData)
+            throw new Error("No image loaded");
+        if (merge && this.imageData.metadata) {
+            this.imageData.metadata = {
+                ...this.imageData.metadata,
+                ...metadata,
+                custom: {
+                    ...(this.imageData.metadata.custom || {}),
+                    ...(metadata.custom || {}),
+                },
+            };
+        }
+        else {
+            this.imageData.metadata = { ...metadata };
+        }
+        return this;
+    }
+    /**
+     * Get a specific metadata field
+     * @param key The metadata field to retrieve
+     * @returns The metadata value or undefined
+     */
+    getMetadataField(key) {
+        if (!this.imageData)
+            throw new Error("No image loaded");
+        return this.imageData.metadata?.[key];
+    }
+    /**
+     * Get position (latitude, longitude) from metadata
+     * @returns Object with latitude and longitude, or undefined if not available
+     */
+    getPosition() {
+        const latitude = this.getMetadataField("latitude");
+        const longitude = this.getMetadataField("longitude");
+        if (latitude !== undefined && longitude !== undefined) {
+            return { latitude, longitude };
+        }
+        return undefined;
+    }
+    /**
+     * Set position (latitude, longitude) in metadata
+     * @param latitude GPS latitude
+     * @param longitude GPS longitude
+     */
+    setPosition(latitude, longitude) {
+        return this.setMetadata({ latitude, longitude });
+    }
+    /**
+     * Get physical dimensions from metadata
+     * @returns Object with DPI and physical dimensions, or undefined if not available
+     */
+    getDimensions() {
+        const dpiX = this.getMetadataField("dpiX");
+        const dpiY = this.getMetadataField("dpiY");
+        const physicalWidth = this.getMetadataField("physicalWidth");
+        const physicalHeight = this.getMetadataField("physicalHeight");
+        if (dpiX !== undefined || dpiY !== undefined || physicalWidth !== undefined ||
+            physicalHeight !== undefined) {
+            return { dpiX, dpiY, physicalWidth, physicalHeight };
+        }
+        return undefined;
+    }
+    /**
+     * Set physical dimensions in metadata
+     * @param dpiX Dots per inch (horizontal)
+     * @param dpiY Dots per inch (vertical), defaults to dpiX if not provided
+     */
+    setDPI(dpiX, dpiY) {
+        const actualDpiY = dpiY ?? dpiX;
+        // Calculate physical dimensions based on pixel dimensions and DPI
+        const physicalWidth = this.width / dpiX;
+        const physicalHeight = this.height / actualDpiY;
+        return this.setMetadata({
+            dpiX,
+            dpiY: actualDpiY,
+            physicalWidth,
+            physicalHeight,
+        });
+    }
+    /**
+     * Register a custom image format
+     * @param format Custom format implementation
+     */
+    static registerFormat(format) {
+        Image.formats.push(format);
+    }
+    /**
+     * Get all registered formats
+     */
+    static getFormats() {
+        return Image.formats;
+    }
+    /**
+     * Read an image from bytes
+     * @param data Raw image data
+     * @param format Optional format hint (e.g., "png", "jpeg", "webp")
+     * @returns Image instance
+     */
+    static async read(data, format) {
+        const image = new Image();
+        // Try specified format first
+        if (format) {
+            const handler = Image.formats.find((f) => f.name === format);
+            if (handler && handler.canDecode(data)) {
+                image.imageData = await handler.decode(data);
+                return image;
+            }
+        }
+        // Auto-detect format
+        for (const handler of Image.formats) {
+            if (handler.canDecode(data)) {
+                image.imageData = await handler.decode(data);
+                return image;
+            }
+        }
+        throw new Error("Unsupported or unrecognized image format");
+    }
+    /**
+     * Read 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 async readFrames(data, format) {
+        // Try specified format first
+        if (format) {
+            const handler = Image.formats.find((f) => f.name === format);
+            if (handler && handler.canDecode(data) && handler.decodeFrames) {
+                return await handler.decodeFrames(data);
+            }
+        }
+        // Auto-detect format
+        for (const handler of Image.formats) {
+            if (handler.canDecode(data) && handler.decodeFrames) {
+                return await handler.decodeFrames(data);
+            }
+        }
+        throw new Error("Unsupported or unrecognized multi-frame image format");
+    }
+    /**
+     * Save 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 save
+     * @param options Optional format-specific encoding options
+     * @returns Encoded image bytes
+     */
+    static async saveFrames(format, imageData, options) {
+        const handler = Image.formats.find((f) => f.name === format);
+        if (!handler) {
+            throw new Error(`Unsupported format: ${format}`);
+        }
+        if (!handler.encodeFrames) {
+            throw new Error(`Format ${format} does not support multi-frame encoding`);
+        }
+        return await handler.encodeFrames(imageData, options);
+    }
+    /**
+     * Create an image from raw RGBA data
+     * @param width Image width
+     * @param height Image height
+     * @param data Raw RGBA pixel data (4 bytes per pixel)
+     * @returns Image instance
+     */
+    static fromRGBA(width, height, data) {
+        if (data.length !== width * height * 4) {
+            throw new Error(`Data length mismatch: expected ${width * height * 4}, got ${data.length}`);
+        }
+        const image = new Image();
+        image.imageData = { width, height, data: new Uint8Array(data) };
+        return image;
+    }
+    /**
+     * Resize the image
+     * @param options Resize options
+     * @returns This image instance for chaining
+     */
+    resize(options) {
+        if (!this.imageData)
+            throw new Error("No image loaded");
+        const { width, height, method = "bilinear" } = options;
+        const { data: srcData, width: srcWidth, height: srcHeight } = this.imageData;
+        let resizedData;
+        if (method === "nearest") {
+            resizedData = resizeNearest(srcData, srcWidth, srcHeight, width, height);
+        }
+        else {
+            resizedData = resizeBilinear(srcData, srcWidth, srcHeight, width, height);
+        }
+        // Preserve metadata when resizing
+        const metadata = this.imageData.metadata;
+        this.imageData = {
+            width,
+            height,
+            data: resizedData,
+            metadata: metadata ? { ...metadata } : undefined,
+        };
+        // Update physical dimensions if DPI is set
+        if (this.imageData.metadata) {
+            if (metadata?.dpiX) {
+                this.imageData.metadata.physicalWidth = width / metadata.dpiX;
+            }
+            if (metadata?.dpiY) {
+                this.imageData.metadata.physicalHeight = height / metadata.dpiY;
+            }
+        }
+        return this;
+    }
+    /**
+     * Save 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
+     */
+    async save(format, options) {
+        if (!this.imageData)
+            throw new Error("No image loaded");
+        const handler = Image.formats.find((f) => f.name === format);
+        if (!handler) {
+            throw new Error(`Unsupported format: ${format}`);
+        }
+        return await handler.encode(this.imageData, options);
+    }
+    /**
+     * Clone this image
+     * @returns New image instance with copied data and metadata
+     */
+    clone() {
+        if (!this.imageData)
+            throw new Error("No image loaded");
+        const image = new Image();
+        image.imageData = {
+            width: this.imageData.width,
+            height: this.imageData.height,
+            data: new Uint8Array(this.imageData.data),
+            metadata: this.imageData.metadata
+                ? {
+                    ...this.imageData.metadata,
+                    custom: this.imageData.metadata.custom
+                        ? { ...this.imageData.metadata.custom }
+                        : undefined,
+                }
+                : undefined,
+        };
+        return image;
+    }
+}
+Object.defineProperty(Image, "formats", {
+    enumerable: true,
+    configurable: true,
+    writable: true,
+    value: [
+        new PNGFormat(),
+        new JPEGFormat(),
+        new WebPFormat(),
+        new GIFFormat(),
+        new TIFFFormat(),
+        new BMPFormat(),
+        new RAWFormat(),
+        new ASCIIFormat(),
+    ]
+});

package/esm/src/types.d.ts

@@ -0,0 +1,167 @@
+/**
+ * Image metadata
+ */
+export interface ImageMetadata {
+    /** Physical width in inches (derived from DPI if available) */
+    physicalWidth?: number;
+    /** Physical height in inches (derived from DPI if available) */
+    physicalHeight?: number;
+    /** Dots per inch (horizontal) */
+    dpiX?: number;
+    /** Dots per inch (vertical) */
+    dpiY?: number;
+    /** GPS latitude */
+    latitude?: number;
+    /** GPS longitude */
+    longitude?: number;
+    /** Image title */
+    title?: string;
+    /** Image description */
+    description?: string;
+    /** Image author */
+    author?: string;
+    /** Copyright information */
+    copyright?: string;
+    /** Creation date */
+    creationDate?: Date;
+    /** Custom metadata fields */
+    custom?: Record<string, string | number | boolean>;
+}
+/**
+ * Frame-specific metadata for multi-frame images
+ */
+export interface FrameMetadata {
+    /** Frame delay in milliseconds (for animations) */
+    delay?: number;
+    /** Frame disposal method: how to treat the frame before rendering the next one */
+    disposal?: "none" | "background" | "previous";
+    /** X offset of frame within the canvas */
+    left?: number;
+    /** Y offset of frame within the canvas */
+    top?: number;
+}
+/**
+ * Image data representation
+ */
+export interface ImageData {
+    /** Image width in pixels */
+    width: number;
+    /** Image height in pixels */
+    height: number;
+    /** Raw pixel data as RGBA (4 bytes per pixel) */
+    data: Uint8Array;
+    /** Optional metadata */
+    metadata?: ImageMetadata;
+}
+/**
+ * Single frame in a multi-frame image
+ */
+export interface ImageFrame {
+    /** Frame width in pixels */
+    width: number;
+    /** Frame height in pixels */
+    height: number;
+    /** Raw pixel data as RGBA (4 bytes per pixel) */
+    data: Uint8Array;
+    /** Optional frame-specific metadata */
+    frameMetadata?: FrameMetadata;
+}
+/**
+ * Multi-frame image data representation
+ */
+export interface MultiFrameImageData {
+    /** Canvas width in pixels (for GIF logical screen) */
+    width: number;
+    /** Canvas height in pixels (for GIF logical screen) */
+    height: number;
+    /** Array of frames */
+    frames: ImageFrame[];
+    /** Optional global metadata */
+    metadata?: ImageMetadata;
+}
+/**
+ * Options for resizing images
+ */
+export interface ResizeOptions {
+    /** Target width in pixels */
+    width: number;
+    /** Target height in pixels */
+    height: number;
+    /** Resize method (default: "bilinear") */
+    method?: "nearest" | "bilinear";
+}
+/**
+ * Options for ASCII art encoding
+ */
+export interface ASCIIOptions {
+    /** Target width in characters (default: 80) */
+    width?: number;
+    /** Character set to use (default: "simple") */
+    charset?: "simple" | "extended" | "blocks" | "detailed";
+    /** Aspect ratio correction factor for terminal display (default: 0.5) */
+    aspectRatio?: number;
+    /** Whether to invert brightness (default: false) */
+    invert?: boolean;
+}
+/**
+ * Options for WebP encoding
+ */
+export interface WebPEncodeOptions {
+    /**
+     * Encoding quality (1-100, default: 90)
+     * - 100 = lossless (VP8L)
+     * - 1-99 = lossy (VP8 if OffscreenCanvas available, otherwise quantized VP8L)
+     */
+    quality?: number;
+    /**
+     * Force lossless encoding even with quality < 100
+     * Uses VP8L format with optional color quantization based on quality
+     */
+    lossless?: boolean;
+}
+/**
+ * Image format handler interface
+ */
+export interface ImageFormat {
+    /** Format name (e.g., "png", "jpeg", "webp") */
+    readonly name: string;
+    /** MIME type (e.g., "image/png") */
+    readonly mimeType: string;
+    /**
+     * Decode image data from bytes
+     * @param data Raw image data
+     * @returns Decoded image data
+     */
+    decode(data: Uint8Array): Promise<ImageData>;
+    /**
+     * Encode image data to bytes
+     * @param imageData Image data to encode
+     * @param options Optional format-specific encoding options
+     * @returns Encoded image bytes
+     */
+    encode(imageData: ImageData, options?: unknown): Promise<Uint8Array>;
+    /**
+     * Check if the given data is in this format
+     * @param data Raw data to check
+     * @returns true if the data matches this format
+     */
+    canDecode(data: Uint8Array): boolean;
+    /**
+     * Decode all frames from multi-frame image (optional)
+     * @param data Raw image data
+     * @returns Decoded multi-frame image data
+     */
+    decodeFrames?(data: Uint8Array): Promise<MultiFrameImageData>;
+    /**
+     * Encode multi-frame image data to bytes (optional)
+     * @param imageData Multi-frame image data to encode
+     * @param options Optional format-specific encoding options
+     * @returns Encoded image bytes
+     */
+    encodeFrames?(imageData: MultiFrameImageData, options?: unknown): Promise<Uint8Array>;
+    /**
+     * Check if the format supports multiple frames
+     */
+    supportsMultipleFrames?(): boolean;
+}
+//# sourceMappingURL=types.d.ts.map

package/esm/src/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/src/types.ts"],"names":[],"mappings":"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"}

package/esm/src/types.js

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,42 @@
+/**
+ * Pure JavaScript GIF decoder implementation
+ * Supports GIF87a and GIF89a formats with LZW decompression
+ */
+interface GIFImage {
+    width: number;
+    height: number;
+    data: Uint8Array;
+}
+interface GIFFrame {
+    width: number;
+    height: number;
+    left: number;
+    top: number;
+    data: Uint8Array;
+    delay: number;
+    disposal: number;
+}
+export declare class GIFDecoder {
+    private data;
+    private pos;
+    constructor(data: Uint8Array);
+    private readByte;
+    private readUint16LE;
+    private readBytes;
+    private readColorTable;
+    private readDataSubBlocks;
+    decode(): GIFImage;
+    /**
+     * Decode all frames from an animated GIF
+     * @returns Object with canvas dimensions and array of frames
+     */
+    decodeAllFrames(): {
+        width: number;
+        height: number;
+        frames: GIFFrame[];
+    };
+    private indexedToRGBA;
+    private deinterlace;
+}
+export {};
+//# sourceMappingURL=gif_decoder.d.ts.map

package/esm/src/utils/gif_decoder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gif_decoder.d.ts","sourceRoot":"","sources":["../../../src/src/utils/gif_decoder.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,UAAU,QAAQ;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,UAAU,CAAC;CAClB;AAED,UAAU,QAAQ;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,UAAU,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,qBAAa,UAAU;IACrB,OAAO,CAAC,IAAI,CAAa;IACzB,OAAO,CAAC,GAAG,CAAS;gBAER,IAAI,EAAE,UAAU;IAK5B,OAAO,CAAC,QAAQ;IAOhB,OAAO,CAAC,YAAY;IAMpB,OAAO,CAAC,SAAS;IASjB,OAAO,CAAC,cAAc;IAKtB,OAAO,CAAC,iBAAiB;IAWzB,MAAM,IAAI,QAAQ;IAwHlB;;;OAGG;IACH,eAAe,IAAI;QACjB,KAAK,EAAE,MAAM,CAAC;QACd,MAAM,EAAE,MAAM,CAAC;QACf,MAAM,EAAE,QAAQ,EAAE,CAAC;KACpB;IA0KD,OAAO,CAAC,aAAa;IAwErB,OAAO,CAAC,WAAW;CA0BpB"}