1. Products
  2.   Image
  3.   GO
  4.   imaginary
 
  

Go API for HTTP Based Image Processing

Open Source Go Library That Supports Online Smart Cropping, Flip or Rotate Images, Create Image Thumbnails, Image Zooming, Adding Watermark to PNG, WEBP, TIFF, PDF, GIF, and SVG, etc.

What is Imaginary?

Imaginary is a high-performance, open-source HTTP-based image processing API for Go, enabling developers to execute advanced image operations through secure private or public HTTP services with minimal dependencies. This powerful library excels in security and scalability, featuring API token authorization, URL signature protection, HTTP traffic throttling, and built-in CORS support for web clients. It offers flexible image sourcing, capable of reading from HTTP POST payloads, local server paths, or remote HTTP servers. Built on the robust and efficient libvips library, Imaginary ensures fast processing while supporting a wide array of image formats including JPEG, PNG, HEIF, WEBP, TIFF, PDF, GIF, and SVG, with seamless transparent conversion between them.

The library provides comprehensive support for deployment via Docker and Fly.io, leveraging Fly.io's global network to reduce latency by serving traffic closer to end-users. Imaginary's extensive feature set covers all critical aspects of image creation, conversion, and manipulation. Key capabilities include resizing, enlarging, cropping (with smart-crop support), rotating, and AutoRotate transformations. It also supports auto-flip based on EXIF metadata, image flop, zooming, thumbnail creation, fitting, embedding, extending, watermarking, and applying blur effects, making it a complete solution for sophisticated image processing workflows.

Previous Next

Getting Started with imaginary

The easiest and recommended way to install imaginary is via GitHub.

Install imaginary via GitHub

go get -u github.com/h2non/imaginary

Convert Images to Other Formats via Go

The open-source API imaginary library has included support for converting your images to other supported file formats with ease. You can save images in some very useful formats like JPEG, PNG, and WEBP formats. The library has provided conversion support with additional quality and compression settings. You just need to provide the correct image name, address & conversion format and the library will easily convert it for you with just a couple of Go commands.

How to Convert Image via Imaginary Library?

func Convert(buf []byte, o ImageOptions) (Image, error) {
	if o.Type == "" {
		return Image{}, NewError("Missing required param: type", http.StatusBadRequest)
	}
	if ImageType(o.Type) == bimg.UNKNOWN {
		return Image{}, NewError("Invalid image type: "+o.Type, http.StatusBadRequest)
	}
	opts := BimgOptions(o)

	return Process(buf, opts)
}

Online Image Cropping via Go

The open source imaginary library enables software developers to crop their images online with just a couple of lines of Go code inside their own applications. You can crop your image by providing custom width or height. The library makes your job easy by maintaining the Image ratio. The library also supports cropping the image by using the libvips built-in smart crop algorithm. You can also define the image compression level for PNG images and flip, flop, and rotate your images with ease.

How to Image Cropping via Go Library?

{
    "operation": "crop",
    "params": {
      "width": 500,
      "height": 300
    }

Resize Images to Fit

The Free imaginary library has included support for resizing images to fit using Go commands inside their apps.  You can easily resize an image to fit within width and height, without cropping. The library makes your job easy by maintaining the image aspect ratio. The width and height specify a maximum bounding box for the image.

How to Resize Image via Free Go Library?

func Resize(buf []byte, o ImageOptions) (Image, error) {
	if o.Width == 0 && o.Height == 0 {
		return Image{}, NewError("Missing required param: height or width", http.StatusBadRequest)
	}

	opts := BimgOptions(o)
	opts.Embed = true

	if o.IsDefinedField.NoCrop {
		opts.Crop = !o.NoCrop
	}

	return Process(buf, opts)
}

Rotate and Auto-Rotate Your Images

The Free imaginary library has provided functionality for rotating your images with ease. It has also included a very useful function for auto-rotating images inside Go applications. It automatically rotates the image with no further image transformations based on EXIF orientation metadata. The AutoRotate method produces a new image with the same size and format as the input image.

How to Auto-Rotate Image via Free Go Library?

func AutoRotate(buf []byte, o ImageOptions) (out Image, err error) {
	defer func() {
		if r := recover(); r != nil {
			switch value := r.(type) {
			case error:
				err = value
			case string:
				err = errors.New(value)
			default:
				err = errors.New("libvips internal error")
			}
			out = Image{}
		}
	}
 English