Fast HTTP microservice written in Golang
This Golang Open-Source Project for high-level image processing backed by bimg and libvips. imaginary can be used as a private or public HTTP service for massive image processing with first-class support for Docker & Fly.io. It’s almost dependency-free and only uses net/http native package without additional abstractions for better performance.
Supports multiple image operations exposed as a simple HTTP API, with additional optional features such as API token authorization, URL signature protection, HTTP traffic throttle strategy and CORS support for web clients.
imaginary can read images from HTTP POST payloads, server local path or remote HTTP servers, supporting JPEG, PNG, WEBP, HEIF, and optionally TIFF, PDF, GIF and SVG formats if libvips@8.3+ is compiled with proper library bindings.
imaginary can output images as JPEG, PNG and WEBP formats, including transparent conversion across them.
imaginary optionally supports image placeholder fallback mechanism in case of image processing error or server error of any nature. Hence an image will always be returned by imaginary even in case of error, trying to match the requested image size and format type transparently. The error details will be in the response HTTP header Error field serialized as JSON.
imaginary uses internally libvips, a powerful and efficient library written in C for fast image processing requires a low memory footprint, and it’s typically 4x faster than using the quickest ImageMagick and GraphicsMagick settings or Go native image package. In some cases, it’s even 8x faster-processing JPEG images.
To get started, look at the installation steps, usage cases and API docs.
Supported image operations
- Resize
- Enlarge
- Crop
- SmartCrop (based on libvips built-in algorithm)
- Rotate (with auto-rotate based on EXIF orientation)
- Fit
- A pipeline of multiple independent image transformations in a single HTTP request.
- Configurable image area extraction
- AutoRotate with further image transformations (based on EXIF metadata orientation)
- Flip (with auto-flip based on EXIF metadata)
- Flop
- Zoom
- Thumbnail
- Embed/Extend image, supporting multiple modes (white, black, mirror, copy or custom background color)
- Watermark (customizable by text)
- Format conversion (with additional quality/compression settings)
- Info (image size, format, orientation, alpha…)
- Watermark image
- Custom output color space (RGB, black/white…)
- Reply with default or custom placeholder image in case of error.
- Blur
Golang and Library Prerequisites
- libvips 8.8+ (8.9+ recommended)
- C compatible compilers such as gcc 4.6+ or clang 3.0+
- Golang 1.12+
Installation Procedure for the Image Processing Microservice
