cross-image 0.2.2 → 0.2.4

package/script/src/image.d.ts

@@ -79,6 +79,21 @@ export declare class Image {
      * @returns Image instance
      */
     static decode(data: Uint8Array, format?: string): Promise<Image>;
+    /**
+     * Get supported metadata fields for a specific format
+     * @param format Format name (e.g., "jpeg", "png", "webp")
+     * @returns Array of supported metadata field names, or undefined if format doesn't support metadata
+     */
+    static getSupportedMetadata(format: string): Array<keyof ImageMetadata> | undefined;
+    /**
+     * Extract metadata from image data without fully decoding the pixel data
+     * This is useful for quickly reading EXIF, XMP, or other metadata from images
+     * that may have unsupported features or compression methods
+     * @param data Raw image data
+     * @param format Optional format hint (e.g., "png", "jpeg", "webp")
+     * @returns Metadata extracted from the image, or undefined if extraction fails or format is unsupported
+     */
+    static extractMetadata(data: Uint8Array, format?: string): Promise<ImageMetadata | undefined>;
     /**
      * Read an image from bytes
      * @deprecated Use `decode()` instead. This method will be removed in a future version.
@@ -197,6 +212,12 @@ export declare class Image {
      * @returns This image instance for chaining
      */
     saturation(amount: number): this;
+    /**
+     * Adjust hue of the image by rotating the color wheel
+     * @param degrees Hue rotation in degrees (any value accepted, wraps at 360)
+     * @returns This image instance for chaining
+     */
+    hue(degrees: number): this;
     /**
      * Invert colors of the image
      * @returns This image instance for chaining
@@ -282,5 +303,44 @@ export declare class Image {
      * @returns This image instance for chaining
      */
     setPixel(x: number, y: number, r: number, g: number, b: number, a?: number): this;
+    /**
+     * Rotate the image 90 degrees clockwise
+     * @returns This image instance for chaining
+     */
+    rotate90(): this;
+    /**
+     * Rotate the image 180 degrees
+     * @returns This image instance for chaining
+     */
+    rotate180(): this;
+    /**
+     * Rotate the image 270 degrees clockwise (or 90 degrees counter-clockwise)
+     * @returns This image instance for chaining
+     */
+    rotate270(): this;
+    /**
+     * Rotate the image by the specified angle in degrees
+     * @param degrees Rotation angle in degrees (positive = clockwise, negative = counter-clockwise)
+     * @returns This image instance for chaining
+     *
+     * @example
+     * ```ts
+     * image.rotate(90);   // Rotate 90° clockwise
+     * image.rotate(-90);  // Rotate 90° counter-clockwise
+     * image.rotate(180);  // Rotate 180°
+     * image.rotate(45);   // Rotate 45° clockwise (rounded to nearest 90°)
+     * ```
+     */
+    rotate(degrees: number): this;
+    /**
+     * Flip the image horizontally (mirror)
+     * @returns This image instance for chaining
+     */
+    flipHorizontal(): this;
+    /**
+     * Flip the image vertically
+     * @returns This image instance for chaining
+     */
+    flipVertical(): this;
 }
 //# sourceMappingURL=image.d.ts.map

package/script/src/image.js

@@ -16,6 +16,8 @@ const pam_js_1 = require("./formats/pam.js");
 const pcx_js_1 = require("./formats/pcx.js");
 const ppm_js_1 = require("./formats/ppm.js");
 const ascii_js_1 = require("./formats/ascii.js");
+const heic_js_1 = require("./formats/heic.js");
+const avif_js_1 = require("./formats/avif.js");
 const security_js_1 = require("./utils/security.js");
 /**
  * Main Image class for reading, manipulating, and saving images
@@ -184,6 +186,42 @@ class Image {
         }
         throw new Error("Unsupported or unrecognized image format");
     }
+    /**
+     * Get supported metadata fields for a specific format
+     * @param format Format name (e.g., "jpeg", "png", "webp")
+     * @returns Array of supported metadata field names, or undefined if format doesn't support metadata
+     */
+    static getSupportedMetadata(format) {
+        const formatHandler = Image.formats.find((f) => f.name === format.toLowerCase());
+        if (!formatHandler) {
+            throw new Error(`Unknown image format: ${format}`);
+        }
+        return formatHandler.getSupportedMetadata?.();
+    }
+    /**
+     * Extract metadata from image data without fully decoding the pixel data
+     * This is useful for quickly reading EXIF, XMP, or other metadata from images
+     * that may have unsupported features or compression methods
+     * @param data Raw image data
+     * @param format Optional format hint (e.g., "png", "jpeg", "webp")
+     * @returns Metadata extracted from the image, or undefined if extraction fails or format is unsupported
+     */
+    static async extractMetadata(data, format) {
+        // Try specified format first
+        if (format) {
+            const handler = Image.formats.find((f) => f.name === format);
+            if (handler && handler.canDecode(data) && handler.extractMetadata) {
+                return await handler.extractMetadata(data);
+            }
+        }
+        // Auto-detect format
+        for (const handler of Image.formats) {
+            if (handler.canDecode(data) && handler.extractMetadata) {
+                return await handler.extractMetadata(data);
+            }
+        }
+        return undefined;
+    }
     /**
      * Read an image from bytes
      * @deprecated Use `decode()` instead. This method will be removed in a future version.
@@ -304,19 +342,98 @@ class Image {
     resize(options) {
         if (!this.imageData)
             throw new Error("No image loaded");
-        const { width, height, method = "bilinear" } = options;
+        const { width, height, method = "bilinear", fit = "stretch" } = options;
         // Validate new dimensions for security (prevent integer overflow and heap exhaustion)
         (0, security_js_1.validateImageDimensions)(width, height);
         const { data: srcData, width: srcWidth, height: srcHeight } = this.imageData;
+        // Handle fitting modes
+        let targetWidth = width;
+        let targetHeight = height;
+        let shouldCenter = false;
+        const fitMode = fit === "contain" ? "fit" : fit === "cover" ? "fill" : fit;
+        if (fitMode === "fit" || fitMode === "fill") {
+            const srcAspect = srcWidth / srcHeight;
+            const targetAspect = width / height;
+            if (fitMode === "fit") {
+                // Fit within dimensions (letterbox)
+                if (srcAspect > targetAspect) {
+                    // Source is wider - fit to width
+                    targetWidth = width;
+                    targetHeight = Math.round(width / srcAspect);
+                }
+                else {
+                    // Source is taller - fit to height
+                    targetWidth = Math.round(height * srcAspect);
+                    targetHeight = height;
+                }
+                shouldCenter = true;
+            }
+            else {
+                // Fill dimensions (crop)
+                if (srcAspect > targetAspect) {
+                    // Source is wider - fit to height and crop width
+                    targetWidth = Math.round(height * srcAspect);
+                    targetHeight = height;
+                }
+                else {
+                    // Source is taller - fit to width and crop height
+                    targetWidth = width;
+                    targetHeight = Math.round(width / srcAspect);
+                }
+                shouldCenter = true;
+            }
+        }
+        // Perform the resize
         let resizedData;
         if (method === "nearest") {
-            resizedData = (0, resize_js_1.resizeNearest)(srcData, srcWidth, srcHeight, width, height);
+            resizedData = (0, resize_js_1.resizeNearest)(srcData, srcWidth, srcHeight, targetWidth, targetHeight);
+        }
+        else if (method === "bicubic") {
+            resizedData = (0, resize_js_1.resizeBicubic)(srcData, srcWidth, srcHeight, targetWidth, targetHeight);
         }
         else {
-            resizedData = (0, resize_js_1.resizeBilinear)(srcData, srcWidth, srcHeight, width, height);
+            resizedData = (0, resize_js_1.resizeBilinear)(srcData, srcWidth, srcHeight, targetWidth, targetHeight);
         }
         // Preserve metadata when resizing
         const metadata = this.imageData.metadata;
+        // If we need to center (fit mode) or crop (fill mode), create a canvas
+        if (shouldCenter && (targetWidth !== width || targetHeight !== height)) {
+            const canvas = new Uint8Array(width * height * 4);
+            // Fill with transparent black by default
+            canvas.fill(0);
+            if (fitMode === "fit") {
+                // Center the resized image (letterbox)
+                const offsetX = Math.floor((width - targetWidth) / 2);
+                const offsetY = Math.floor((height - targetHeight) / 2);
+                for (let y = 0; y < targetHeight; y++) {
+                    for (let x = 0; x < targetWidth; x++) {
+                        const srcIdx = (y * targetWidth + x) * 4;
+                        const dstIdx = ((y + offsetY) * width + (x + offsetX)) * 4;
+                        canvas[dstIdx] = resizedData[srcIdx];
+                        canvas[dstIdx + 1] = resizedData[srcIdx + 1];
+                        canvas[dstIdx + 2] = resizedData[srcIdx + 2];
+                        canvas[dstIdx + 3] = resizedData[srcIdx + 3];
+                    }
+                }
+                resizedData = canvas;
+            }
+            else {
+                // Crop to fill (center crop)
+                const offsetX = Math.floor((targetWidth - width) / 2);
+                const offsetY = Math.floor((targetHeight - height) / 2);
+                for (let y = 0; y < height; y++) {
+                    for (let x = 0; x < width; x++) {
+                        const srcIdx = ((y + offsetY) * targetWidth + (x + offsetX)) * 4;
+                        const dstIdx = (y * width + x) * 4;
+                        canvas[dstIdx] = resizedData[srcIdx];
+                        canvas[dstIdx + 1] = resizedData[srcIdx + 1];
+                        canvas[dstIdx + 2] = resizedData[srcIdx + 2];
+                        canvas[dstIdx + 3] = resizedData[srcIdx + 3];
+                    }
+                }
+                resizedData = canvas;
+            }
+        }
         this.imageData = {
             width,
             height,
@@ -442,6 +559,17 @@ class Image {
         this.imageData.data = (0, image_processing_js_1.adjustSaturation)(this.imageData.data, amount);
         return this;
     }
+    /**
+     * Adjust hue of the image by rotating the color wheel
+     * @param degrees Hue rotation in degrees (any value accepted, wraps at 360)
+     * @returns This image instance for chaining
+     */
+    hue(degrees) {
+        if (!this.imageData)
+            throw new Error("No image loaded");
+        this.imageData.data = (0, image_processing_js_1.adjustHue)(this.imageData.data, degrees);
+        return this;
+    }
     /**
      * Invert colors of the image
      * @returns This image instance for chaining
@@ -605,6 +733,124 @@ class Image {
         this.imageData.data[idx + 3] = a;
         return this;
     }
+    /**
+     * Rotate the image 90 degrees clockwise
+     * @returns This image instance for chaining
+     */
+    rotate90() {
+        if (!this.imageData)
+            throw new Error("No image loaded");
+        const result = (0, image_processing_js_1.rotate90)(this.imageData.data, this.imageData.width, this.imageData.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 && metadata.dpiY) {
+                // Swap physical dimensions
+                const tempPhysical = metadata.physicalWidth;
+                this.imageData.metadata.physicalWidth = metadata.physicalHeight;
+                this.imageData.metadata.physicalHeight = tempPhysical;
+                // Swap DPI
+                const tempDpi = metadata.dpiX;
+                this.imageData.metadata.dpiX = metadata.dpiY;
+                this.imageData.metadata.dpiY = tempDpi;
+            }
+        }
+        return this;
+    }
+    /**
+     * Rotate the image 180 degrees
+     * @returns This image instance for chaining
+     */
+    rotate180() {
+        if (!this.imageData)
+            throw new Error("No image loaded");
+        this.imageData.data = (0, image_processing_js_1.rotate180)(this.imageData.data, this.imageData.width, this.imageData.height);
+        return this;
+    }
+    /**
+     * Rotate the image 270 degrees clockwise (or 90 degrees counter-clockwise)
+     * @returns This image instance for chaining
+     */
+    rotate270() {
+        if (!this.imageData)
+            throw new Error("No image loaded");
+        const result = (0, image_processing_js_1.rotate270)(this.imageData.data, this.imageData.width, this.imageData.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 && metadata.dpiY) {
+                // Swap physical dimensions
+                const tempPhysical = metadata.physicalWidth;
+                this.imageData.metadata.physicalWidth = metadata.physicalHeight;
+                this.imageData.metadata.physicalHeight = tempPhysical;
+                // Swap DPI
+                const tempDpi = metadata.dpiX;
+                this.imageData.metadata.dpiX = metadata.dpiY;
+                this.imageData.metadata.dpiY = tempDpi;
+            }
+        }
+        return this;
+    }
+    /**
+     * Rotate the image by the specified angle in degrees
+     * @param degrees Rotation angle in degrees (positive = clockwise, negative = counter-clockwise)
+     * @returns This image instance for chaining
+     *
+     * @example
+     * ```ts
+     * image.rotate(90);   // Rotate 90° clockwise
+     * image.rotate(-90);  // Rotate 90° counter-clockwise
+     * image.rotate(180);  // Rotate 180°
+     * image.rotate(45);   // Rotate 45° clockwise (rounded to nearest 90°)
+     * ```
+     */
+    rotate(degrees) {
+        // Normalize to 0-360 range
+        let normalizedDegrees = degrees % 360;
+        if (normalizedDegrees < 0) {
+            normalizedDegrees += 360;
+        }
+        // Round to nearest 90 degrees
+        const rounded = Math.round(normalizedDegrees / 90) * 90;
+        // Apply rotation based on rounded value
+        switch (rounded % 360) {
+            case 90:
+                return this.rotate90();
+            case 180:
+                return this.rotate180();
+            case 270:
+                return this.rotate270();
+            default:
+                // 0 or 360 degrees - no rotation needed
+                return this;
+        }
+    }
+    /**
+     * Flip the image horizontally (mirror)
+     * @returns This image instance for chaining
+     */
+    flipHorizontal() {
+        if (!this.imageData)
+            throw new Error("No image loaded");
+        this.imageData.data = (0, image_processing_js_1.flipHorizontal)(this.imageData.data, this.imageData.width, this.imageData.height);
+        return this;
+    }
+    /**
+     * Flip the image vertically
+     * @returns This image instance for chaining
+     */
+    flipVertical() {
+        if (!this.imageData)
+            throw new Error("No image loaded");
+        this.imageData.data = (0, image_processing_js_1.flipVertical)(this.imageData.data, this.imageData.width, this.imageData.height);
+        return this;
+    }
 }
 exports.Image = Image;
 Object.defineProperty(Image, "formats", {
@@ -625,5 +871,7 @@ Object.defineProperty(Image, "formats", {
         new pcx_js_1.PCXFormat(),
         new ppm_js_1.PPMFormat(),
         new ascii_js_1.ASCIIFormat(),
+        new heic_js_1.HEICFormat(),
+        new avif_js_1.AVIFFormat(),
     ]
 });

package/script/src/types.d.ts

@@ -24,6 +24,42 @@ export interface ImageMetadata {
     copyright?: string;
     /** Creation date */
     creationDate?: Date;
+    /** Camera make/manufacturer (e.g., "Canon", "Nikon") */
+    cameraMake?: string;
+    /** Camera model (e.g., "Canon EOS 5D Mark IV") */
+    cameraModel?: string;
+    /** Lens make/manufacturer */
+    lensMake?: string;
+    /** Lens model */
+    lensModel?: string;
+    /** ISO speed rating (e.g., 100, 400, 3200) */
+    iso?: number;
+    /** Exposure time / Shutter speed in seconds (e.g., 0.0125 = 1/80s) */
+    exposureTime?: number;
+    /** F-number / Aperture (e.g., 2.8, 5.6, 16) */
+    fNumber?: number;
+    /** Focal length in millimeters (e.g., 50, 85, 200) */
+    focalLength?: number;
+    /** Flash mode (0 = no flash, 1 = flash fired) */
+    flash?: number;
+    /** White balance mode (0 = auto, 1 = manual) */
+    whiteBalance?: number;
+    /** Orientation (1 = normal, 3 = 180°, 6 = 90° CW, 8 = 90° CCW) */
+    orientation?: number;
+    /** Software used to create/edit the image */
+    software?: string;
+    /** User comment / notes */
+    userComment?: string;
+    /** Image file format (e.g., "png", "jpeg", "gif", "webp", "tiff") */
+    format?: string;
+    /** Compression algorithm used (e.g., "deflate", "lzw", "dct", "vp8", "vp8l", "none") */
+    compression?: string;
+    /** Number of frames in multi-frame images (e.g., animated GIFs, APNGs, multi-page TIFFs) */
+    frameCount?: number;
+    /** Bit depth per channel (e.g., 8, 16) */
+    bitDepth?: number;
+    /** Color type (e.g., "grayscale", "rgb", "rgba", "indexed", "grayscale-alpha") */
+    colorType?: string;
     /** Custom metadata fields */
     custom?: Record<string, string | number | boolean>;
 }
@@ -88,7 +124,16 @@ export interface ResizeOptions {
     /** Target height in pixels */
     height: number;
     /** Resize method (default: "bilinear") */
-    method?: "nearest" | "bilinear";
+    method?: "nearest" | "bilinear" | "bicubic";
+    /**
+     * Fitting mode (default: "stretch")
+     * - "stretch": Stretch image to fill dimensions (may distort)
+     * - "fit": Fit image within dimensions maintaining aspect ratio (may have letterboxing)
+     * - "fill": Fill dimensions maintaining aspect ratio (may crop)
+     * - "cover": Alias for "fill"
+     * - "contain": Alias for "fit"
+     */
+    fit?: "stretch" | "fit" | "fill" | "cover" | "contain";
 }
 /**
  * Options for ASCII art encoding
@@ -163,5 +208,18 @@ export interface ImageFormat {
      * Check if the format supports multiple frames
      */
     supportsMultipleFrames?(): boolean;
+    /**
+     * Get the list of metadata fields supported by this format
+     * @returns Array of metadata field names that can be persisted
+     */
+    getSupportedMetadata?(): Array<keyof ImageMetadata>;
+    /**
+     * Extract metadata from image data without fully decoding the pixel data
+     * This is useful for quickly reading EXIF, XMP, or other metadata from images
+     * that may have unsupported features or compression methods
+     * @param data Raw image data
+     * @returns Metadata extracted from the image, or undefined if extraction fails
+     */
+    extractMetadata?(data: Uint8Array): Promise<ImageMetadata | undefined>;
 }
 //# sourceMappingURL=types.d.ts.map

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

@@ -44,6 +44,13 @@ export declare function adjustExposure(data: Uint8Array, amount: number): Uint8A
  * @returns New image data with adjusted saturation
  */
 export declare function adjustSaturation(data: Uint8Array, amount: number): Uint8Array;
+/**
+ * Adjust hue of an image by rotating the hue wheel
+ * @param data Image data (RGBA)
+ * @param degrees Hue rotation in degrees (any value accepted, wraps at 360)
+ * @returns New image data with adjusted hue
+ */
+export declare function adjustHue(data: Uint8Array, degrees: number): Uint8Array;
 /**
  * Invert colors of an image
  * @param data Image data (RGBA)
@@ -131,4 +138,52 @@ export declare function sepia(data: Uint8Array): Uint8Array;
  * @returns New image data with median filter applied
  */
 export declare function medianFilter(data: Uint8Array, width: number, height: number, radius?: number): Uint8Array;
+/**
+ * Rotate image 90 degrees clockwise
+ * @param data Image data (RGBA)
+ * @param width Image width
+ * @param height Image height
+ * @returns Rotated image data with swapped dimensions
+ */
+export declare function rotate90(data: Uint8Array, width: number, height: number): {
+    data: Uint8Array;
+    width: number;
+    height: number;
+};
+/**
+ * Rotate image 180 degrees
+ * @param data Image data (RGBA)
+ * @param width Image width
+ * @param height Image height
+ * @returns Rotated image data with same dimensions
+ */
+export declare function rotate180(data: Uint8Array, width: number, height: number): Uint8Array;
+/**
+ * Rotate image 270 degrees clockwise (or 90 degrees counter-clockwise)
+ * @param data Image data (RGBA)
+ * @param width Image width
+ * @param height Image height
+ * @returns Rotated image data with swapped dimensions
+ */
+export declare function rotate270(data: Uint8Array, width: number, height: number): {
+    data: Uint8Array;
+    width: number;
+    height: number;
+};
+/**
+ * Flip image horizontally (mirror)
+ * @param data Image data (RGBA)
+ * @param width Image width
+ * @param height Image height
+ * @returns Flipped image data
+ */
+export declare function flipHorizontal(data: Uint8Array, width: number, height: number): Uint8Array;
+/**
+ * Flip image vertically
+ * @param data Image data (RGBA)
+ * @param width Image width
+ * @param height Image height
+ * @returns Flipped image data
+ */
+export declare function flipVertical(data: Uint8Array, width: number, height: number): Uint8Array;
 //# sourceMappingURL=image_processing.d.ts.map