image-edit-tools 1.0.0

package/src/ops/optimize.ts

@@ -0,0 +1,77 @@
+import sharp from 'sharp';
+import { OptimizeOptions, ImageInput, ImageResult, ErrorCode } from '../types.js';
+import { loadImage } from '../utils/load-image.js';
+import { getImageMetadata } from '../utils/validate.js';
+import { err, ok } from '../utils/result.js';
+
+export async function optimize(input: ImageInput, options: OptimizeOptions): Promise<ImageResult> {
+  try {
+    const buffer = await loadImage(input);
+    const meta = await getImageMetadata(buffer);
+    
+    let pipeline = sharp(buffer);
+
+    let format = meta.format;
+    const autoFormat = options.autoFormat ?? true;
+    if (autoFormat) {
+      format = meta.hasAlpha ? 'webp' : 'jpeg';
+    }
+
+    if (options.maxDimension) {
+      if (options.maxDimension <= 0) return err('maxDimension must be positive', ErrorCode.INVALID_INPUT);
+      if (meta.width > options.maxDimension || meta.height > options.maxDimension) {
+        if (meta.width > meta.height) {
+          pipeline = pipeline.resize({ width: options.maxDimension, withoutEnlargement: true });
+        } else {
+          pipeline = pipeline.resize({ height: options.maxDimension, withoutEnlargement: true });
+        }
+      }
+    }
+
+    const applyFormat = (p: sharp.Sharp, f: string, q: number) => {
+      if (f === 'webp') return p.webp({ quality: q });
+      if (f === 'png') return p.png({ quality: q, compressionLevel: 9 });
+      if (f === 'avif') return p.avif({ quality: q });
+      return p.jpeg({ quality: q });
+    };
+
+    if (options.maxSizeKB) {
+      if (options.maxSizeKB <= 0) return err('maxSizeKB must be positive', ErrorCode.INVALID_INPUT);
+      const targetBytes = options.maxSizeKB * 1024;
+      
+      let minQ = 10, maxQ = 95;
+      let bestBuffer: Buffer | null = null;
+      let bestDiff = Infinity;
+
+      for (let i = 0; i < 7; i++) {
+        const midQ = Math.floor((minQ + maxQ) / 2);
+        const testBuf = await applyFormat(pipeline.clone(), format, midQ).toBuffer();
+        const diff = targetBytes - testBuf.length;
+
+        if (testBuf.length <= targetBytes && diff < bestDiff && diff >= 0) {
+          bestBuffer = testBuf;
+          bestDiff = diff;
+        }
+
+        if (testBuf.length > targetBytes) {
+          maxQ = midQ - 1;
+        } else {
+          minQ = midQ + 1;
+        }
+      }
+      
+      if (bestBuffer) return ok(bestBuffer);
+      
+      const fallback = await applyFormat(pipeline.clone(), format, 10).toBuffer();
+      return ok(fallback);
+    } else {
+      const output = await applyFormat(pipeline, format, 80).toBuffer();
+      return ok(output);
+    }
+  } catch (e: any) {
+    const msg = e.message || '';
+    if (msg.includes('HTTP')) return err(msg, ErrorCode.FETCH_FAILED);
+    if (msg.includes('ENOENT')) return err('File not found', ErrorCode.INVALID_INPUT);
+    return err(msg, ErrorCode.PROCESSING_FAILED);
+  }
+}

package/src/ops/overlay.ts

@@ -0,0 +1,51 @@
+import sharp from 'sharp';
+import { OverlayOptions, ImageInput, ImageResult, ErrorCode } from '../types.js';
+import { loadImage } from '../utils/load-image.js';
+import { err, ok } from '../utils/result.js';
+
+export async function overlay(input: ImageInput, overlayImage: ImageInput, options: OverlayOptions = {}): Promise<ImageResult> {
+  try {
+    const buffer = await loadImage(input);
+    let layerBuf = await loadImage(overlayImage);
+    
+    if (options.opacity !== undefined && options.opacity >= 0 && options.opacity < 1) {
+      layerBuf = await sharp(layerBuf)
+        .ensureAlpha()
+        .composite([
+          {
+            input: Buffer.from([255, 255, 255, Math.round(options.opacity * 255)]),
+            raw: { width: 1, height: 1, channels: 4 },
+            tile: true,
+            blend: 'dest-in'
+          }
+        ])
+        .toBuffer();
+    }
+
+    let gravity = options.gravity ? options.gravity.toLowerCase() : undefined;
+    
+    const compositeOpts: sharp.OverlayOptions = {
+      input: layerBuf,
+      blend: options.blend || 'over'
+    };
+
+    if (gravity) {
+      compositeOpts.gravity = gravity;
+    } else {
+      if (options.offsetX !== undefined) compositeOpts.left = Math.floor(options.offsetX);
+      if (options.offsetY !== undefined) compositeOpts.top = Math.floor(options.offsetY);
+    }
+
+    const output = await sharp(buffer)
+      .composite([compositeOpts])
+      .toBuffer();
+    
+    return ok(output);
+  } catch (e: any) {
+    const msg = e.message || '';
+    if (msg.includes('HTTP')) return err(msg, ErrorCode.FETCH_FAILED);
+    if (msg.includes('ENOENT')) return err('File not found', ErrorCode.INVALID_INPUT);
+    if (msg.includes('unsupported image format')) return err('Corrupt or unsupported input', ErrorCode.INVALID_INPUT);
+    return err(msg, ErrorCode.PROCESSING_FAILED);
+  }
+}

package/src/ops/pad.ts

@@ -0,0 +1,63 @@
+import sharp from 'sharp';
+import { PadOptions, ImageInput, ImageResult, ErrorCode } from '../types.js';
+import { loadImage } from '../utils/load-image.js';
+import { err, ok } from '../utils/result.js';
+import { getImageMetadata } from '../utils/validate.js';
+
+export async function pad(input: ImageInput, options: PadOptions): Promise<ImageResult> {
+  try {
+    const buffer = await loadImage(input);
+    let top = 0, right = 0, bottom = 0, left = 0;
+
+    if (options.size !== undefined) {
+      if (options.size <= 0) return err('Size must be positive', ErrorCode.INVALID_INPUT);
+      const meta = await getImageMetadata(buffer);
+      const targetSize = options.size;
+      
+      if (targetSize < meta.width || targetSize < meta.height) {
+         return err('Target size must be larger than image dimensions', ErrorCode.INVALID_INPUT);
+      }
+      
+      const missingTotalW = targetSize - meta.width;
+      const missingTotalH = targetSize - meta.height;
+      left = Math.floor(missingTotalW / 2);
+      right = missingTotalW - left;
+      top = Math.floor(missingTotalH / 2);
+      bottom = missingTotalH - top;
+    } else {
+      top = options.top || 0;
+      right = options.right || 0;
+      bottom = options.bottom || 0;
+      left = options.left || 0;
+    }
+
+    if (top < 0 || right < 0 || bottom < 0 || left < 0) {
+      return err('Padding values cannot be negative', ErrorCode.INVALID_INPUT);
+    }
+    
+    let background: string | sharp.RGBA = options.color || '#ffffff';
+    let pipeline = sharp(buffer);
+    if (options.color?.toLowerCase() === 'transparent') {
+      background = { r: 0, g: 0, b: 0, alpha: 0 };
+      pipeline = pipeline.png();
+    }
+
+    const output = await pipeline
+      .extend({
+        top,
+        bottom,
+        left,
+        right,
+        background
+      })
+      .toBuffer();
+    
+    return ok(output);
+  } catch (e: any) {
+    const msg = e.message || '';
+    if (msg.includes('HTTP')) return err(msg, ErrorCode.FETCH_FAILED);
+    if (msg.includes('ENOENT')) return err('File not found', ErrorCode.INVALID_INPUT);
+    if (msg.includes('unsupported image format')) return err('Corrupt or unsupported input', ErrorCode.INVALID_INPUT);
+    return err(msg, ErrorCode.PROCESSING_FAILED);
+  }
+}

package/src/ops/pipeline.ts

@@ -0,0 +1,61 @@
+import { ImageInput, ImageResult, PipelineOperation, ErrorCode } from '../types.js';
+import { crop } from './crop.js';
+import { resize } from './resize.js';
+import { pad } from './pad.js';
+import { adjust } from './adjust.js';
+import { filter } from './filter.js';
+import { blurRegion } from './blur-region.js';
+import { addText } from './add-text.js';
+import { composite } from './composite.js';
+import { watermark } from './watermark.js';
+import { convert } from './convert.js';
+import { optimize } from './optimize.js';
+import { removeBg } from './remove-bg.js';
+
+export async function pipeline(input: ImageInput, operations: PipelineOperation[]): Promise<ImageResult & { step?: number }> {
+  let currentImage = input;
+  
+  for (let i = 0; i < operations.length; i++) {
+    const op = operations[i];
+    let result: ImageResult;
+
+    try {
+      switch (op.op) {
+        case 'crop': result = await crop(currentImage, op); break;
+        case 'resize': result = await resize(currentImage, op); break;
+        case 'pad': result = await pad(currentImage, op); break;
+        case 'adjust': result = await adjust(currentImage, op); break;
+        case 'filter': result = await filter(currentImage, op); break;
+        case 'blurRegion': result = await blurRegion(currentImage, { regions: op.regions }); break;
+        case 'addText': result = await addText(currentImage, { layers: op.layers }); break;
+        case 'composite': result = await composite(currentImage, { layers: op.layers }); break;
+        case 'watermark': result = await watermark(currentImage, op); break;
+        case 'convert': result = await convert(currentImage, op); break;
+        case 'optimize': result = await optimize(currentImage, op); break;
+        case 'removeBg': result = await removeBg(currentImage, op); break;
+        default:
+          return { ok: false, error: `Unknown operation`, code: ErrorCode.INVALID_INPUT, step: i };
+      }
+
+      if (!result.ok) {
+        return { ...result, step: i };
+      }
+      
+      currentImage = result.data;
+    } catch (e: any) {
+       return { ok: false, error: e.message, code: ErrorCode.PROCESSING_FAILED, step: i };
+    }
+  }
+
+  if (operations.length === 0) {
+     const { loadImage } = await import('../utils/load-image.js');
+     try {
+       const buf = await loadImage(input);
+       return { ok: true, data: buf };
+     } catch(e:any) {
+       return { ok: false, error: 'Failed to load initial image', code: ErrorCode.INVALID_INPUT, step: 0 };
+     }
+  }
+
+  return { ok: true, data: currentImage as Buffer };
+}

package/src/ops/remove-bg.ts

@@ -0,0 +1,82 @@
+import sharp from 'sharp';
+import { RemoveBgOptions, ImageInput, ImageResult, ErrorCode } from '../types.js';
+import { loadImage } from '../utils/load-image.js';
+import { err, ok } from '../utils/result.js';
+import { getImageMetadata } from '../utils/validate.js';
+import { AutoModel, AutoProcessor, RawImage } from '@xenova/transformers';
+
+export async function removeBg(input: ImageInput, options: RemoveBgOptions = {}): Promise<ImageResult> {
+  try {
+    const buffer = await loadImage(input);
+    const meta = await getImageMetadata(buffer);
+    
+    let model: any, processor: any;
+    try {
+      model = await AutoModel.from_pretrained('briaai/RMBG-1.4', {
+        config: { model_type: 'custom' },
+        quantized: true // Use quantized for speed and avoiding OOM
+      });
+      processor = await AutoProcessor.from_pretrained('briaai/RMBG-1.4', {
+        config: {
+          do_normalize: true,
+          do_pad: false,
+          do_rescale: true,
+          do_resize: true,
+          image_mean: [0.5, 0.5, 0.5],
+          image_std: [1, 1, 1],
+          resample: 2,
+          size: { width: 1024, height: 1024 },
+        }
+      });
+    } catch (e: any) {
+      return err('Model unavailable. Run: npx image-edit-tools download-models', ErrorCode.MODEL_NOT_FOUND);
+    }
+
+    // Process image
+    const rawImage = await RawImage.fromURL(URL.createObjectURL(new Blob([buffer]))); // Alternative for node:
+    // RawImage from buffer is easier using sharp. We need uint8 array of RGB or RGBA.
+    const rawRgb = await sharp(buffer).ensureAlpha().raw().toBuffer();
+    const img = new RawImage(new Uint8ClampedArray(rawRgb), meta.width, meta.height, 4);
+
+    const { pixel_values } = await processor(img);
+    const { output } = await model({ input: pixel_values });
+
+    // Output is a mask tensor. Resize mask back to original dimensions using sharp.
+    // The model outputs size 1024x1024.
+    const maskData = new Uint8Array(output.data.length);
+    for (let i = 0; i < output.data.length; ++i) {
+      maskData[i] = Math.max(0, Math.min(255, Math.round(output.data[i] * 255))); // Assume output is 0.0 to 1.0 floats
+    }
+
+    const maskBuffer = await sharp(Buffer.from(maskData), { raw: { width: 1024, height: 1024, channels: 1 } })
+      .resize(meta.width, meta.height, { fit: 'fill' }) // match original size
+      .toBuffer();
+
+    let outputBuf = await sharp(buffer)
+      .ensureAlpha()
+      .joinChannel(maskBuffer) // join mask as alpha channel
+      .png()
+      .toBuffer();
+
+    // Replace color or image
+    if (options.replaceColor) {
+      outputBuf = await sharp(outputBuf)
+        .flatten({ background: options.replaceColor })
+        .toBuffer();
+    } else if (options.replaceImage) {
+      const bgBuf = await loadImage(options.replaceImage);
+      // Resize background to match image if needed, or simply composite subject over background
+      const sizedBgBuf = await sharp(bgBuf).resize(meta.width, meta.height, { fit: 'cover' }).toBuffer();
+      outputBuf = await sharp(sizedBgBuf)
+        .composite([{ input: outputBuf, blend: 'over' }])
+        .toBuffer();
+    }
+    
+    return ok(outputBuf);
+  } catch (e: any) {
+    const msg = e.message || '';
+    if (msg.includes('HTTP')) return err(msg, ErrorCode.FETCH_FAILED);
+    if (msg.includes('ENOENT')) return err('File not found', ErrorCode.INVALID_INPUT);
+    return err(msg, ErrorCode.PROCESSING_FAILED);
+  }
+}

package/src/ops/resize.ts

@@ -0,0 +1,54 @@
+import sharp from 'sharp';
+import { ResizeOptions, ImageInput, ImageResult, ErrorCode } from '../types.js';
+import { loadImage } from '../utils/load-image.js';
+import { err, ok } from '../utils/result.js';
+import { getImageMetadata, isPositiveInt } from '../utils/validate.js';
+
+export async function resize(input: ImageInput, options: ResizeOptions): Promise<ImageResult> {
+  try {
+    const buffer = await loadImage(input);
+    
+    let width = options.width;
+    let height = options.height;
+
+    if (options.scale) {
+      if (options.scale <= 0) return err('Scale must be positive', ErrorCode.INVALID_INPUT);
+      const meta = await getImageMetadata(buffer);
+      width = Math.round(meta.width * options.scale);
+      height = Math.round(meta.height * options.scale);
+    }
+
+    if (width !== undefined && !isPositiveInt(width)) {
+      return err('Width must be a positive integer', ErrorCode.INVALID_INPUT);
+    }
+    if (height !== undefined && !isPositiveInt(height)) {
+      return err('Height must be a positive integer', ErrorCode.INVALID_INPUT);
+    }
+
+    if (width === undefined && height === undefined) {
+      return err('Must provide width, height, or scale', ErrorCode.INVALID_INPUT);
+    }
+
+    let kernel: keyof sharp.KernelEnum | undefined;
+    if (options.kernel === 'linear') kernel = 'mitchell';
+    else if (options.kernel) kernel = options.kernel;
+
+    const output = await sharp(buffer)
+      .resize({
+        width,
+        height,
+        fit: options.fit,
+        kernel,
+        withoutEnlargement: options.withoutEnlargement
+      })
+      .toBuffer();
+    
+    return ok(output);
+  } catch (e: any) {
+    const msg = e.message || '';
+    if (msg.includes('HTTP')) return err(msg, ErrorCode.FETCH_FAILED);
+    if (msg.includes('ENOENT')) return err('File not found', ErrorCode.INVALID_INPUT);
+    if (msg.includes('unsupported image format')) return err('Corrupt or unsupported input', ErrorCode.INVALID_INPUT);
+    return err(msg, ErrorCode.PROCESSING_FAILED);
+  }
+}

package/src/ops/watermark.ts

@@ -0,0 +1,141 @@
+import sharp from 'sharp';
+import { WatermarkOptions, ImageInput, ImageResult, ErrorCode, TextAnchor } from '../types.js';
+import { loadImage } from '../utils/load-image.js';
+import { err, ok } from '../utils/result.js';
+import { getImageMetadata } from '../utils/validate.js';
+import { addText } from './add-text.js';
+import { resize } from './resize.js';
+
+const posToGravity: Record<string, string> = {
+  'top-left': 'northwest',
+  'top-center': 'north',
+  'top-right': 'northeast',
+  'center': 'center',
+  'bottom-left': 'southwest',
+  'bottom-center': 'south',
+  'bottom-right': 'southeast'
+};
+
+const posToAnchor: Record<string, TextAnchor> = {
+  'top-left': 'top-left',
+  'top-center': 'top-center',
+  'top-right': 'top-right',
+  'center': 'center',
+  'bottom-left': 'bottom-left',
+  'bottom-center': 'bottom-center',
+  'bottom-right': 'bottom-right' 
+};
+
+export async function watermark(input: ImageInput, options: WatermarkOptions): Promise<ImageResult> {
+  try {
+    const buffer = await loadImage(input);
+    const meta = await getImageMetadata(buffer);
+    const position = options.position || 'bottom-right';
+
+    if (options.type === 'text') {
+      if (position === 'tile') {
+        const spacing = options.tileSpacing ?? 50;
+        const fontSize = options.fontSize ?? 24;
+        const color = options.color ?? '#ffffff';
+        const opacity = options.opacity ?? 0.5;
+        
+        const charWidth = fontSize * 0.6;
+        const w = options.text.length * charWidth;
+        const h = fontSize;
+
+        const cols = Math.ceil(meta.width / Math.max(1, (w + spacing)));
+        const rows = Math.ceil(meta.height / Math.max(1, (h + spacing)));
+        
+        const layers: any[] = [];
+        for (let r = 0; r < rows; r++) {
+          for (let c = 0; c < cols; c++) {
+            layers.push({
+              text: options.text,
+              x: c * (w + spacing),
+              y: r * (h + spacing),
+              fontSize,
+              color,
+              opacity,
+              anchor: 'top-left'
+            });
+          }
+        }
+        return addText(buffer, { layers });
+      } else {
+        const anchor = posToAnchor[position] || 'bottom-right';
+        let x = 0, y = 0;
+        const pad = 10;
+        const fontSize = options.fontSize ?? 24;
+        
+        if (position.includes('left')) x = pad;
+        else if (position.includes('right')) x = meta.width - pad;
+        else x = meta.width / 2;
+
+        if (position.includes('top')) y = pad;
+        else if (position.includes('bottom')) y = meta.height - pad;
+        else y = meta.height / 2;
+
+        return addText(buffer, {
+          layers: [{
+            text: options.text,
+            x, y, anchor,
+            fontSize,
+            color: options.color ?? '#ffffff',
+            opacity: options.opacity ?? 0.5
+          }]
+        });
+      }
+    } else if (options.type === 'image') {
+      let wmBuf = await loadImage(options.image);
+      const wmMeta = await getImageMetadata(wmBuf);
+      
+      if (options.scale && options.scale !== 1.0) {
+        const r = await resize(wmBuf, { scale: options.scale });
+        if (!r.ok) return r as ImageResult;
+        wmBuf = r.data;
+      }
+
+      if (options.opacity !== undefined && options.opacity >= 0 && options.opacity < 1) {
+        wmBuf = await sharp(wmBuf)
+          .ensureAlpha()
+          .composite([
+            {
+              input: Buffer.from([255, 255, 255, Math.round(options.opacity * 255)]),
+              raw: { width: 1, height: 1, channels: 4 },
+              tile: true,
+              blend: 'dest-in'
+            }
+          ])
+          .toBuffer();
+      }
+
+      if (position === 'tile') {
+        const spacing = options.tileSpacing ?? 0;
+        if (spacing > 0) {
+           wmBuf = await sharp(wmBuf)
+             .ensureAlpha()
+             .extend({ bottom: spacing, right: spacing, background: {r:0,g:0,b:0,alpha:0} })
+             .toBuffer();
+        }
+        const output = await sharp(buffer)
+          .composite([{ input: wmBuf, tile: true, blend: 'over' }])
+          .toBuffer();
+        return ok(output);
+      } else {
+        const gravity = posToGravity[position] || 'southeast';
+        const output = await sharp(buffer)
+          .composite([{ input: wmBuf, gravity, blend: 'over' }])
+          .toBuffer();
+        return ok(output);
+      }
+    }
+    
+    return err('Invalid watermark type', ErrorCode.INVALID_INPUT);
+  } catch (e: any) {
+    const msg = e.message || '';
+    if (msg.includes('HTTP')) return err(msg, ErrorCode.FETCH_FAILED);
+    if (msg.includes('ENOENT')) return err('File not found', ErrorCode.INVALID_INPUT);
+    if (msg.includes('unsupported image format')) return err('Corrupt or unsupported input', ErrorCode.INVALID_INPUT);
+    return err(msg, ErrorCode.PROCESSING_FAILED);
+  }
+}

package/src/types/color-thief-node.d.ts

@@ -0,0 +1,4 @@
+declare module 'color-thief-node' {
+    export function getPaletteFromURL(url: string, count?: number, quality?: number): Promise<number[][]>;
+    export function getColorFromURL(url: string, quality?: number): Promise<number[]>;
+}