@winput/image 🖼️


Image loading, saving, and processing for Windows.

Requirements

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

Installation

``bash
bun add @winput/image
`

Usage

`typescript
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

$3

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

---

$3

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 | 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 |

---

$3

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

---

$3

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[]](#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 |

---

$3

| Method | Params | Returns | Description |
| --------------------- | --------------------------- | ---------------------------------------------- | --------------- |
| recognize(options?) | OCROptions | Promise<OCRResult \| null> | Perform OCR |
| terminate() | - | Promise | Free resources |
| reinitialize(lang) | string | Promise | 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

$3

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

$3

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

$3

`typescript
{
x: number;
y: number;
}
`

$3

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

$3

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

$3

`typescript
type Algorithm = "nearest" | "bilinear";
`

$3

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

$3

`typescript
{ color?: RGB; thickness?: number }
`

$3

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

$3

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

$3

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

$3

`typescript
{ color?: RGB; scale?: number }
`

$3

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

$3

`typescript
{
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