@winput/image 🖼️

Image loading, saving, and processing for Windows.

Requirements

• OS: Windows 64-bit
• Runtime: Bun (npm not supported)

Installation

bun add @winput/image

Usage

import { image, Image } from "@winput/image";

const img = await image.load("input.png");
await img?.grayscale().blur(2).edges().save("output.png");

// Drawing
img?.drawer().rectangle(10, 10, 100, 50).circle(200, 200, 50);

// OCR
const text = await img?.ocr().recognize();

// Display
img?.display().show("Preview");

API

image

| Method | Params | Returns | Description | | ------------------ | ------------------------------------- | ---------------------------------------- | ----------------------------------------- | | load(path) | string | Promise<Image \| null> | Load file (formats) | | save(data, path) | ImageData, string | Promise<boolean> | Save (formats) | | process(data) | ImageData | Image | Create processor |

Image

All processing methods return Image for chaining.

Transform

| Method | Params | Returns | Description | | -------------------- | -------- | ------------------- | ----------------------- | | grayscale() | - | Image | Convert to grayscale | | brightness(factor) | number | Image | Adjust brightness (0-∞) | | contrast(factor) | number | Image | Adjust contrast (0-∞) | | blur(radius?) | number | Image | Gaussian blur | | sharpen() | - | Image | Sharpen image | | edges() | - | Image | Sobel edge detection | | invert() | - | Image | Invert colors | | sepia() | - | Image | Sepia tone effect | | hue(degrees) | number | Image | Shift hue (0-360) | | saturate(factor) | number | Image | Adjust saturation |

Morphological

| Method | Params | Returns | Description | | ----------------------- | ------------------------------------- | ------------------- | ---------------------- | | dilate(pixels?) | number | Image | Expand bright regions | | erode(pixels?) | number | Image | Shrink bright regions | | erode2dilate(pixels?) | number | Image | Opening (remove noise) | | dilate2erode(pixels?) | number | Image | Closing (fill holes) | | denoise(strength?) | DenoiseStrength | Image | Preset denoising |

Geometry

| Method | Params | Returns | Description | | -------------------------- | --------------------------------------------- | ------------------- | ---------------- | | resize(w, h, algorithm?) | number, number, Algorithm | Image | Resize | | crop(x, y, w, h) | number×4 | Image | Crop region | | rotate(degrees) | number | Image | Rotate clockwise | | flip(h?, v?) | boolean, boolean | Image | Flip image |

Threshold

| Method | Params | Returns | Description | | ------------------------------- | -------- | ------------------- | ------------------------ | | threshold(value?) | number | Image | Binary threshold (0-255) | | adaptiveThreshold(blockSize?) | number | Image | Local adaptive |

Filters

| Method | Params | Returns | Description | | ----------------------------------- | ------------------ | ------------------- | ------------------------ | | medianFilter(radius?) | number | Image | Remove salt/pepper noise | | bilateralFilter(spatial?, range?) | number, number | Image | Edge-preserving smooth |

Analysis & Compositing

| Method | Params | Returns | Description | | ------------------------------ | ------------------------------------------------------ | ------------------------- | ------------------ | | histogram() | - | Histogram | Get RGB histograms | | autoLevel() | - | Image | Auto-adjust levels | | overlay(img, x?, y?, alpha?) | ImageData, number×3 | Image | Overlay with alpha | | blend(img, mode?) | ImageData, BlendMode | Image | Blend images |

Output

| Method | Params | Returns | Description | | ------------- | -------- | ------------------- | --------------- | | save(path?) | string | Promise<boolean> | Save to file | | clone() | - | Image | Deep copy | | toPixels() | - | [r,g,b,a][] | Get pixel array |

Sub-modules

| Method | Params | Returns | Description | | --------- | ------ | --------------------------------- | ---------------- | | display | - | ImageDisplay | Window display | | drawer | - | ImageDrawer | Draw shapes | | ocr | - | ImageOCR | Text recognition |

ImageDisplay

| Method | Params | Returns | Description | | ----------------------- | ------------------ | --------------------------------- | -------------- | | show(name?, waitKey?) | string, number | ImageDisplay | Show window | | destroyWindow(name) | string | ImageDisplay | Destroy window | | destroyAllWindows() | - | ImageDisplay | Destroy all |

ImageDrawer

All methods return ImageDrawer for chaining.

| Method | Params | Returns | Description | | -------------------------------------- | -------------------------------------------------------- | ------------------------------- | ------------- | | rectangle(x, y, w, h, options?) | number×4, DrawOptions | ImageDrawer | Rectangle | | circle(cx, cy, radius, options?) | number×3, DrawOptions | ImageDrawer | Circle | | line(x1, y1, x2, y2, options?) | number×4, DrawOptions | ImageDrawer | Line | | fillRect(x, y, w, h, color?) | number×4, RGB | ImageDrawer | Filled rect | | fillCircle(cx, cy, radius, color?) | number×3, RGB | ImageDrawer | Filled circle | | ellipse(cx, cy, rx, ry, options?) | number×4, EllipseOptions | ImageDrawer | Ellipse | | polygon(points, options?) | Point[], PolygonOptions | ImageDrawer | Polygon | | arrow(x1, y1, x2, y2, options?) | number×4, ArrowOptions | ImageDrawer | Arrow | | cross(cx, cy, size, options?) | number×3, DrawOptions | ImageDrawer | Cross/plus | | arc(cx, cy, r, start, end, options?) | number×5, DrawOptions | ImageDrawer | Arc | | text(x, y, text, options?) | number×2, string, TextOptions | ImageDrawer | Text |

ImageOCR

| Method | Params | Returns | Description | | --------------------- | --------------------------- | ---------------------------------------------- | --------------- | | recognize(options?) | OCROptions | Promise<OCRResult \| null> | Perform OCR | | terminate() | - | Promise<void> | Free resources | | reinitialize(lang) | string | Promise<void> | Change language |

Supported Formats

| Format | Extension | Description | | ------ | --------------- | ------------------------------------ | | PNG | .png | Portable Network Graphics (lossless) | | JPEG | .jpg, .jpeg | JPEG (lossy compression) | | BMP | .bmp | Bitmap (uncompressed) | | WebP | .webp | Modern format | | GIF | .gif | Limited colors | | TIFF | .tiff | High quality | | ICO | .ico | Icon format | | HEIC | .heic | High Efficiency Image Container | | HEIF | .heif | High Efficiency Image Format | | AVIF | .avif | AV1 Image File Format | | SVG | .svg | Scalable Vector Graphics | | RAW | .raw | Raw image data |

Types

ImageData

{
  width: number;
  height: number;
  buffer: Uint8Array;
}

RGB

{
  r: number;
  g: number;
  b: number;
}

Point

{
  x: number;
  y: number;
}

Histogram

{ r: number[]; g: number[]; b: number[] }

DenoiseStrength

type DenoiseStrength = "light" | "medium" | "heavy";

Algorithm

type Algorithm = "nearest" | "bilinear";

BlendMode

type BlendMode = "multiply" | "screen" | "overlay" | "add" | "subtract";

DrawOptions

{ color?: RGB; thickness?: number }

EllipseOptions

{ color?: RGB; thickness?: number; filled?: boolean }

PolygonOptions

{ color?: RGB; thickness?: number; filled?: boolean }

ArrowOptions

{ color?: RGB; thickness?: number; arrowSize?: number }

TextOptions

{ color?: RGB; scale?: number }

OCROptions

{ lang?: string }  // Default: "eng"

OCRResult

{
  text: string;
  confidence: number;
  words: Array<{ text: string; confidence: number; bbox: Rect }>;
}

Exports

| Export | Type | Description | | ----------- | ------------------------- | ------------------------- | | image | image | Main image operations | | Image | Image | Chainable image processor | | ImageData | ImageData | Image data structure |

License

MIT