Public Repository

Last pushed: 4 months ago
Short Description
Image service with advanced capabilities : on the fly resizing + caching.
Full Description

imAPI

This is an image service with on the fly resize, filling, fitting capabilities. The service always keep aspect ratio of image, thus filling to a given size will scale + crop to avoid deformation.

More, the service also supports extraction of a source rectangle on images.

All returned images can be cached on the server if redis is available (recommended), and HTTP caching (Cache-Control header is filled properly) information is always sent for proper handling by the client (usually a browser).

A simple token authentication scheme is also provided, and is usable in production as long as you serve over HTTPS.

Launch the service

Here is a docker-compose.yml sample to get you started:

version: '2'
services:
  imapi:
    image: clems71/imapi
    links:
      - redis
      - mongodb
    ports:
      - 8080:8080
    environment:
      - REDIS_HOST=redis
      - MONGODB_URL=mongodb://mongodb:27017/imapi-test
  redis:
    image: redis:3-alpine
  mongodb:
    image: mvertes/alpine-mongo

$ docker-compose run --service-ports imapi

And you should have an instance of imAPI available on http://localhost:8080.

Upload an image

$ curl -F "image=@image.jpg" http://<imapiHost>/images

{
  "id":"2b864a3c4e8e33b96d0dde5166f53cb4",
  "width":200,
  "height":150,
  "format":"jpeg",
  "space":"srgb",
  "channels":3,
  "hasAlpha":false,
  "url":"http://<imapiHost>/images/2b864a3c4e8e33b96d0dde5166f53cb4"
}

Get an image

All modes will output the image in the same format as the originally uploaded image. If JPG was uploaded then JPG is given back to you. You can change this by querying a different format with ?format=png or ?format=jpg

Supported queries

  • mode: original (default) | fill | fit
  • width: not specified = same as original | integer
  • height: not specified = same as original | integer
  • format: not specified = same as original | jpg | png
  • background: default to rgba(0,0,0,255)
  • sharpen: false (default) or true | on

background is used when performing a fit operation, to select the background color. It is alos used when asking for JPG format when the source was PNG with transparent background, to select the new background color. It hence flatten the image.

Original image

http://<imapiHost>/images/2b864a3c4e8e33b96d0dde5166f53cb4

Fill to a given width (keep aspect ratio)

http://<imapiHost>/images/2b864a3c4e8e33b96d0dde5166f53cb4?width=100&mode=fill

Fill to a given height (keep aspect ratio)

http://<imapiHost>/images/2b864a3c4e8e33b96d0dde5166f53cb4?height=50&mode=fill

Fill to a given size

http://<imapiHost>/images/2b864a3c4e8e33b96d0dde5166f53cb4?height=100&width=100&mode=fill

Fit to a given rectangle

http://<imapiHost>/images/2b864a3c4e8e33b96d0dde5166f53cb4?height=100&width=100&mode=fit&background=rgb(255,0,0)

Extract a rectangle

http://<imapiHost>/images/2b864a3c4e8e33b96d0dde5166f53cb4?rect=0,0,200,200

200x200, top-left extraction

rect format is the following rect=X,Y,W,H, in a top-left coordinates basis:

  • X: distance from left of image
  • Y: distance from top of image
  • W: width
  • H: height

rect also supports basic math expression evaluation. Available variables include w and h for respectively the width and height of original image. As an example, to extract a centered 100x100 patch from an image, you can use the following rect expression:

rect=w/2-50,h/2-50,100,100

Of course, all operators are still available when extracting a part of an image (mode, format, ...).

License

MIT

Docker Pull Command
Owner
clems71

Comments (0)