image

# Image

`Image` is a fast, memory-efficient image processing library for Elixir. It is a high-level wrapper around [Vix](https://hex.pm/packages/vix), the Elixir bindings for the [libvips](https://www.libvips.org) C library, and provides an idiomatic functional API for image manipulation, drawing, text rendering, EXIF/XMP metadata, video frame extraction (via Xav/FFmpeg), blurhash, perceptual hashing, and many other image-related operations.

Machine-learning features (object detection, image classification, image segmentation, face detection, image captioning, background removal, and zero-shot classification) live in the companion [`image_vision`](https://hex.pm/packages/image_vision) library, which depends on `:image` and pulls in [Nx](https://hex.pm/packages/nx), [EXLA](https://hex.pm/packages/exla), and optionally [Ortex](https://hex.pm/packages/ortex) and [Bumblebee](https://hex.pm/packages/bumblebee).

In a simple resize benchmark, `Image` is approximately 2 to 3 times faster than [Mogrify](https://hex.pm/packages/mogrify) and uses about 5 times less memory.

Documentation can be found at [hexdocs.pm/image](https://hexdocs.pm/image).

## Features

* **Image processing** — open, write, resize, thumbnail, crop, embed, rotate, flip, flatten, trim, replace colour, chroma key, warp perspective, distort, blur (Gaussian, box, bilateral), sharpen, modulate, vibrance, tone map, local contrast, equalize, blend, composite, mask, dilate / erode, edge detect.

* **Drawing** — `Image.Draw` provides points, rectangles, circles, lines, masks, flood fill, image overlay, smudge.

* **Text rendering** — `Image.Text` produces antialiased text overlays with full Pango markup support, font selection, alignment, background fills, stroke, and per-character control.

* **Colour management** — colour arguments accept atoms, hex strings, CSS named colours, hex shorthand, `#RRGGBBAA`, `Color.*` structs, CSS Color 4 / 5 functions (`rgb()`, `hsl()`, `lab()`, `oklch()`, `color-mix()`, relative colour syntax via `from`, `none` keyword, `calc()`), and are converted to the **target image's interpretation** via `Image.Pixel.to_pixel/3`. The same colour string draws correctly on sRGB, Lab, scRGB, CMYK, 16-bit, and greyscale images.

* **Colour spaces** — `Image.colorspace/1`, `Image.to_colorspace/2`, and full conversion between sRGB / scRGB / Lab / LCh / CMYK / HSV / XYZ / B&W / 16-bit RGB.

* **UltraHDR** — the gain map of an UltraHDR JPEG stays aligned through resize, crop, rotate, flip and embed and is written back on save; `Image.GainMap` inspects, removes or applies it. See [the HDR and gain maps guide](https://hexdocs.pm/image/hdr_and_gain_maps.html).

* **Dominant colour and palette extraction** — `Image.dominant_color/2` with two methods: a fast 3D-histogram (default) and an imagequant-backed perceptual quantiser. See [the performance guide](https://hexdocs.pm/image/performance.html) for benchmarks.

* **K-means clustering** — `Image.k_means/2` (when `:scholar` is av