cross-image 0.1.4 → 0.2.0

package/script/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

package/script/src/image.js

@@ -2,13 +2,16 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Image = void 0;
 const resize_js_1 = require("./utils/resize.js");
+const image_processing_js_1 = require("./utils/image_processing.js");
 const png_js_1 = require("./formats/png.js");
 const jpeg_js_1 = require("./formats/jpeg.js");
 const webp_js_1 = require("./formats/webp.js");
 const gif_js_1 = require("./formats/gif.js");
 const tiff_js_1 = require("./formats/tiff.js");
 const bmp_js_1 = require("./formats/bmp.js");
-const raw_js_1 = require("./formats/raw.js");
+const dng_js_1 = require("./formats/dng.js");
+const pam_js_1 = require("./formats/pam.js");
+const pcx_js_1 = require("./formats/pcx.js");
 const ascii_js_1 = require("./formats/ascii.js");
 const security_js_1 = require("./utils/security.js");
 /**
@@ -154,12 +157,12 @@ class Image {
         return Image.formats;
     }
     /**
-     * Read an image from bytes
+     * Decode 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) {
+    static async decode(data, format) {
         const image = new Image();
         // Try specified format first
         if (format) {
@@ -179,12 +182,22 @@ class Image {
         throw new Error("Unsupported or unrecognized image format");
     }
     /**
-     * Read all frames from a multi-frame image (GIF animation, multi-page TIFF)
+     * 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, format) {
+        return Image.decode(data, format);
+    }
+    /**
+     * 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 async readFrames(data, format) {
+    static async decodeFrames(data, format) {
         // Try specified format first
         if (format) {
             const handler = Image.formats.find((f) => f.name === format);
@@ -201,13 +214,23 @@ class Image {
         throw new Error("Unsupported or unrecognized multi-frame image format");
     }
     /**
-     * Save multi-frame image data to bytes in the specified format
+     * 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, format) {
+        return Image.decodeFrames(data, format);
+    }
+    /**
+     * 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 save
+     * @param imageData Multi-frame image data to encode
      * @param options Optional format-specific encoding options
      * @returns Encoded image bytes
      */
-    static async saveFrames(format, imageData, options) {
+    static async encodeFrames(format, imageData, options) {
         const handler = Image.formats.find((f) => f.name === format);
         if (!handler) {
             throw new Error(`Unsupported format: ${format}`);
@@ -217,6 +240,17 @@ class Image {
         }
         return await handler.encodeFrames(imageData, options);
     }
+    /**
+     * 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 encode
+     * @param options Optional format-specific encoding options
+     * @returns Encoded image bytes
+     */
+    static saveFrames(format, imageData, options) {
+        return Image.encodeFrames(format, imageData, options);
+    }
     /**
      * Create an image from raw RGBA data
      * @param width Image width
@@ -234,6 +268,31 @@ class Image {
         image.imageData = { width, height, data: new Uint8Array(data) };
         return 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, height, r = 0, g = 0, b = 0, a = 255) {
+        // Validate dimensions for security (prevent integer overflow and heap exhaustion)
+        (0, security_js_1.validateImageDimensions)(width, height);
+        const data = new Uint8Array(width * height * 4);
+        // Fill with the specified color
+        for (let i = 0; i < data.length; i += 4) {
+            data[i] = r;
+            data[i + 1] = g;
+            data[i + 2] = b;
+            data[i + 3] = a;
+        }
+        const image = new Image();
+        image.imageData = { width, height, data };
+        return image;
+    }
     /**
      * Resize the image
      * @param options Resize options
@@ -273,12 +332,12 @@ class Image {
         return this;
     }
     /**
-     * Save the image to bytes in the specified format
+     * 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
      */
-    async save(format, options) {
+    async encode(format, options) {
         if (!this.imageData)
             throw new Error("No image loaded");
         const handler = Image.formats.find((f) => f.name === format);
@@ -287,6 +346,16 @@ class Image {
         }
         return await handler.encode(this.imageData, options);
     }
+    /**
+     * 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
+     */
+    save(format, options) {
+        return this.encode(format, options);
+    }
     /**
      * Clone this image
      * @returns New image instance with copied data and metadata
@@ -310,6 +379,174 @@ class Image {
         };
         return 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, x, y, opacity = 1) {
+        if (!this.imageData)
+            throw new Error("No image loaded");
+        if (!overlay.imageData)
+            throw new Error("Overlay has no image loaded");
+        this.imageData.data = (0, image_processing_js_1.composite)(this.imageData.data, this.imageData.width, this.imageData.height, overlay.imageData.data, overlay.imageData.width, overlay.imageData.height, x, y, opacity);
+        return 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) {
+        if (!this.imageData)
+            throw new Error("No image loaded");
+        this.imageData.data = (0, image_processing_js_1.adjustBrightness)(this.imageData.data, amount);
+        return 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) {
+        if (!this.imageData)
+            throw new Error("No image loaded");
+        this.imageData.data = (0, image_processing_js_1.adjustContrast)(this.imageData.data, amount);
+        return 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) {
+        if (!this.imageData)
+            throw new Error("No image loaded");
+        this.imageData.data = (0, image_processing_js_1.adjustExposure)(this.imageData.data, amount);
+        return 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) {
+        if (!this.imageData)
+            throw new Error("No image loaded");
+        this.imageData.data = (0, image_processing_js_1.adjustSaturation)(this.imageData.data, amount);
+        return this;
+    }
+    /**
+     * Invert colors of the image
+     * @returns This image instance for chaining
+     */
+    invert() {
+        if (!this.imageData)
+            throw new Error("No image loaded");
+        this.imageData.data = (0, image_processing_js_1.invert)(this.imageData.data);
+        return this;
+    }
+    /**
+     * Convert the image to grayscale
+     * @returns This image instance for chaining
+     */
+    grayscale() {
+        if (!this.imageData)
+            throw new Error("No image loaded");
+        this.imageData.data = (0, image_processing_js_1.grayscale)(this.imageData.data);
+        return 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, y, width, height, r, g, b, a = 255) {
+        if (!this.imageData)
+            throw new Error("No image loaded");
+        this.imageData.data = (0, image_processing_js_1.fillRect)(this.imageData.data, this.imageData.width, this.imageData.height, x, y, width, height, r, g, b, a);
+        return 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, y, width, height) {
+        if (!this.imageData)
+            throw new Error("No image loaded");
+        const result = (0, image_processing_js_1.crop)(this.imageData.data, this.imageData.width, this.imageData.height, x, y, width, height);
+        this.imageData.width = result.width;
+        this.imageData.height = result.height;
+        this.imageData.data = result.data;
+        // Update physical dimensions if DPI is set
+        if (this.imageData.metadata) {
+            const metadata = this.imageData.metadata;
+            if (metadata.dpiX) {
+                this.imageData.metadata.physicalWidth = result.width / metadata.dpiX;
+            }
+            if (metadata.dpiY) {
+                this.imageData.metadata.physicalHeight = result.height / metadata.dpiY;
+            }
+        }
+        return 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, y) {
+        if (!this.imageData)
+            throw new Error("No image loaded");
+        if (x < 0 || x >= this.imageData.width || y < 0 || y >= this.imageData.height) {
+            return undefined;
+        }
+        const idx = (y * this.imageData.width + x) * 4;
+        return {
+            r: this.imageData.data[idx],
+            g: this.imageData.data[idx + 1],
+            b: this.imageData.data[idx + 2],
+            a: this.imageData.data[idx + 3],
+        };
+    }
+    /**
+     * 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, y, r, g, b, a = 255) {
+        if (!this.imageData)
+            throw new Error("No image loaded");
+        if (x < 0 || x >= this.imageData.width || y < 0 || y >= this.imageData.height) {
+            return this;
+        }
+        const idx = (y * this.imageData.width + x) * 4;
+        this.imageData.data[idx] = r;
+        this.imageData.data[idx + 1] = g;
+        this.imageData.data[idx + 2] = b;
+        this.imageData.data[idx + 3] = a;
+        return this;
+    }
 }
 exports.Image = Image;
 Object.defineProperty(Image, "formats", {
@@ -323,7 +560,9 @@ Object.defineProperty(Image, "formats", {
         new gif_js_1.GIFFormat(),
         new tiff_js_1.TIFFFormat(),
         new bmp_js_1.BMPFormat(),
-        new raw_js_1.RAWFormat(),
+        new dng_js_1.DNGFormat(),
+        new pam_js_1.PAMFormat(),
+        new pcx_js_1.PCXFormat(),
         new ascii_js_1.ASCIIFormat(),
     ]
 });

package/script/src/utils/image_processing.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Image processing utilities for common operations like compositing,
+ * level adjustments, and color manipulations.
+ */
+/**
+ * Composite one image on top of another at a specified position
+ * @param base Base image data (RGBA)
+ * @param baseWidth Base image width
+ * @param baseHeight Base image height
+ * @param overlay Overlay image data (RGBA)
+ * @param overlayWidth Overlay image width
+ * @param overlayHeight Overlay image height
+ * @param x X position to place overlay (can be negative)
+ * @param y Y position to place overlay (can be negative)
+ * @param opacity Opacity of overlay (0-1, default: 1)
+ * @returns New image data with overlay composited on base
+ */
+export declare function composite(base: Uint8Array, baseWidth: number, baseHeight: number, overlay: Uint8Array, overlayWidth: number, overlayHeight: number, x: number, y: number, opacity?: number): Uint8Array;
+/**
+ * Adjust brightness of an image
+ * @param data Image data (RGBA)
+ * @param amount Brightness adjustment (-1 to 1, where 0 is no change)
+ * @returns New image data with adjusted brightness
+ */
+export declare function adjustBrightness(data: Uint8Array, amount: number): Uint8Array;
+/**
+ * Adjust contrast of an image
+ * @param data Image data (RGBA)
+ * @param amount Contrast adjustment (-1 to 1, where 0 is no change)
+ * @returns New image data with adjusted contrast
+ */
+export declare function adjustContrast(data: Uint8Array, amount: number): Uint8Array;
+/**
+ * Adjust exposure of an image
+ * @param data Image data (RGBA)
+ * @param amount Exposure adjustment in stops (-3 to 3, where 0 is no change)
+ * @returns New image data with adjusted exposure
+ */
+export declare function adjustExposure(data: Uint8Array, amount: number): Uint8Array;
+/**
+ * Adjust saturation of an image
+ * @param data Image data (RGBA)
+ * @param amount Saturation adjustment (-1 to 1, where 0 is no change)
+ * @returns New image data with adjusted saturation
+ */
+export declare function adjustSaturation(data: Uint8Array, amount: number): Uint8Array;
+/**
+ * Invert colors of an image
+ * @param data Image data (RGBA)
+ * @returns New image data with inverted colors
+ */
+export declare function invert(data: Uint8Array): Uint8Array;
+/**
+ * Convert image to grayscale
+ * @param data Image data (RGBA)
+ * @returns New image data in grayscale
+ */
+export declare function grayscale(data: Uint8Array): Uint8Array;
+/**
+ * Fill a rectangular region with a color
+ * @param data Image data (RGBA)
+ * @param width Image width
+ * @param height Image height
+ * @param x Starting X position
+ * @param y Starting Y position
+ * @param fillWidth Width of the fill region
+ * @param fillHeight 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)
+ * @returns Modified image data
+ */
+export declare function fillRect(data: Uint8Array, width: number, height: number, x: number, y: number, fillWidth: number, fillHeight: number, r: number, g: number, b: number, a: number): Uint8Array;
+/**
+ * Crop an image to a rectangular region
+ * @param data Image data (RGBA)
+ * @param width Image width
+ * @param height Image height
+ * @param x Starting X position
+ * @param y Starting Y position
+ * @param cropWidth Width of the crop region
+ * @param cropHeight Height of the crop region
+ * @returns Cropped image data and dimensions
+ */
+export declare function crop(data: Uint8Array, width: number, height: number, x: number, y: number, cropWidth: number, cropHeight: number): {
+    data: Uint8Array;
+    width: number;
+    height: number;
+};
+//# sourceMappingURL=image_processing.d.ts.map