Immagine

WARNING: this repository is not currently maintained!

Unfortunately we're not using this product internally at present and hence users should assume it's unmaintained. There may be known security issues or just general bit-rot. We hope the code may remain useful to some but we cannot offer any support at this time.

Immagine is the image manipulation service for nature.com.

Running an Immagine Server

Immagine is a Ruby application, so you need to be comfortable running Ruby applications in your infrastructure. It should work with any rack compatible web server, but we run it with and recommend puma proxied behind NGINX configured with a file based cache (see the example nginx.conf) for pretty acceptable results.

Dependencies

• Ruby - see .ruby-version for the version currently targeted.
• Imagemagick - Immagine uses imagemagick to do all the hard work with the images. You'll need at least version 2.7+ to take full advantage of all of Immagines' capabilities.
• FFMpeg - ffmpeg is required to take screenshots from videos (mov flv mp4 avi mpg and wmv are currently supported)
• A rack application server - again, we recommend puma.
• A proxying web server - again, we recommend NGINX.

Configuration

Immagine is configured via a config/application.yml file. Here is an example config:

source_folder: ./test-data/src
format_whitelist:
  - w100h100  # Example cropped thumbnail
  - h125      # At a glance thumbnails
  - w250      # Figure index page thumbnails
  - w450      # At a glance popups
  - w926      # Full size figures
  - m685      # Article figures
  - relative  # Illustrations

Here's a brief description of the available options:

• source_folder - [required] - the directory of images that you'd like Immagine to handle/serve.
• format_whitelist - [optional] - a list of allowable image manipulation options (see Requesting Images for further details), if a request comes through with a format that is not on this list, Immagine will respond with a not found response (404). This is used to limit potential abuse of the system - i.e. automated requests for images with random processing options that could lead to a DOS situation.
• statsd_host - [optional] - the address of your statsd server (if you use statsd) for performance/usage metrics.
• statsd_port - [optional] - the port that your statsd server listens on.
• statsd_namespace - [optional] - a prefix for all of the immagine stats to go under.

Requesting Images

Immagine removes the need to create multiple resized versions of the same image to suit your design requirements. A single high-resolution image can instead be requested using a custom URL structure, and Immagine will resize & serve the image. Caching is handled by NGINX, and Immagine also manages all the HTTP headers you would expect for assets.

Original (Unmodified) Images

Unresized images can be requested by users via the URL structure /{path}/{file_name}

We recommend serving unresized images via Immagine to ensure:

• consistent URLs for all images across your application
• consistent cache control (set by Immagine)

Modified Images

URL structure

The basic URL structure for serving modified (resized, cropped, blurred, overlaid) images is /{path}/{format_code}/{file_name}

Here's a rundown of the basic formatting options and how they can be passed into Immagine:

• wXXX - alter an images width. Set this to a pixel value (i.e. w200) and the image will have its width reduced to that number of pixels. If the image is already smaller (less-wide) than this setting, the width will not be altered or stretched to fit.
• hXXX - alter an images height. As with the width, set this to a pixel value (i.e. h200) and the image will have its height reduced to that number of pixels. If the image is already smaller (less-tall) than this setting, the height will not be altered or stretched to fit.
• mXXX - max. Resize by width or height, whichever is largest
• cXX-XXX-XXX-XX - crop an image. See Image Cropping for full details.
• bXX-XX - blur an image. See Blurring an Image for full details.
• ovXXX-XX - overlay an image with a transparent color. See Overlaying an Image for full details.

The formatting options can be combined, when they do not conflict. See Combining Options

Image Cropping

Image cropping in Immagine is quite a powerful thing, here is the full info on the format string allowed:

c{gravity}-{width}-{height}-{resize_ratio}

• gravity - [required] - where to focus the cropping of the image, acceptable options for this are:
  • C - center
  • N - north
  • E - east
  • S - south
  • W - west
  • NE - north east
  • NW - north west
  • SE - south east
  • SW - south west
• width - [required] - width (in pixels) of the final cropped image.
• height - [required] - height (in pixels) of the final cropped image.
• resize_ratio - [optional] - resize the image (using this ratio) prior to cropping. I.e. a ratio of '0.5' would reduce the image by half (in both width and height) before cropping.

Of the above options, resize_ratio is the only optional property. Here are a couple of examples to show you how cropping can be used:

• cC-500-100-0.5 - first reduce an image to half its original size (0.5 resize_ratio), then crop it in the center to 500 pixels wide by 100 pixels tall.
• cSW-100-100 - Do not resize the image prior to cropping, just crop it to 100x100 pixels in the bottom-left.

Blurring an Image

Sometimes your images are just too sharp, it's OK, Immagine has your back. Here's the format string for adding some blur to your images:

b{radius}-{sigma}

• radius - [required]
• sigma - [optional]

Overlaying an Image

You can also add a transparent colour overlay to your images with Immagine:

ov{colour}-{opacity}

• colour - [optional] - the hex code for the colour to use in the overlay (minus the hash - these are NOT allowed in URLs) - i.e. FFF. Another acceptable value for this is the string dominant (this is the default if the colour is omitted) - this tells Immagine to extract the most dominant colour from the image (read more on this below) and use that as the colour overlay.
• opacity - [optional] -

Combining Formatting Options

The above options can be combined in various ways, with the exception of the resizing options which cannot all be combined with each other.

Valid combinations might be:

• b2m100 - blur and resize by max
• w1000cW-100-100-0.5 - resize by width and crop
• ovb1.1-11cNW-100-100 - overlay and crop
• w100h200 - resize by width and resize by height

Invalid combinations might be:

• m100h100 - resize by max and resize by height
• cNW-100 - crop (without all required parameters - see Image Cropping)
• m100w100 - resize by max and resize by width

As you can see, the formatting codes can get quite complex, but you can make them a little more readable if you use a sensible delimiter - i.e. an underscore.

Image Quality

Image quality can be controlled by including a quality component in the URL: /{path}/{format_code}/q{quality}/{file_name}

where quality can be a value from 1 to 100. Values outside this range will result in a 404 error. When the quality is not provided through the URL it will default to 85.

Colour Analysis

To analyse the colour in an image, use the following URL structure: /analyse/{path}/{file_name}

Average Colour

To find the average colour of an image, Immagine first shrinks the image to 1x1px in size, and extracts the colour from this pixel.

Dominant Colour

To find the dominant colour of an image, Immagine first shrinks the image to 300x300px, then counts the top 10 most used colours in this image. The 10 colours are ranked in order of most used. The first colour which has a lightness of less than 0.7 is picked as the dominant colour (or, if none of the colours have a lightness less than 0.7, the most common colour is picked).

The lightness factor is used to ensure that an image which consists of coloured artefacts on a white background does not return white as the most common colour.

Getting Started and Contributing

Please read the contributing guidelines first, then run the following commands to quickly get setup:

bundle install
cp config/application.yml.sample config/application.yml
bundle exec rake
foreman start

Go to:

http://localhost:3000/live/images/w250/matz.jpg

Licence

© 2015, Springer Nature.

Immagine is licensed under the GNU General Public License 3.0.