ruby-vips8

This gem provides a Ruby binding for the vips image processing library. It wraps version 8 of the API. The older vips7-based ruby-vips gem is still being maintained.

ruby-vips8 is fast and it can work without needing the entire image to be loaded into memory. ruby-vips8 allows you to set up pipelines that don’t get executed until you output the image to disk or to a string. This means you can create, manipulate, and pass around Image objects without incurring any memory or CPU costs. The image is not actually processed until you write the image to memory or to disk.

For example, the benchmark at vips-benchmarks loads a large image, crops, shrinks, sharpens and saves again, and repeats 10 times.

real time in seconds, fastest of three runs
benchmark       tiff    jpeg
ruby-vips.rb    2.77    2.98    
ruby-vips8.rb   2.97    3.29    
image-magick    8.18    9.71    
rmagick.rb      9.22    10.06   
image_sci.rb    9.39    7.20    

peak memory use in bytes
benchmark       peak RSS
ruby-vips.rb    107340
ruby-vips8.rb   117604
image_sci.rb    146536
rmagick.rb      3352020

See also benchmarks at the official libvips website. There’s a handy blog post explaining how libvips opens files which gives some more background.

Requirements

Installation prerequisites

OS X

Install homebrew and enter:

$ brew install homebrew/science/vips

To verify that your vips install is working, try:

$ vips --version
vips-8.2.1

Make sure you have Vips-8.0.typelib on your GI_TYPELIB_PATH. Enter something like:

$ export GI_TYPELIB_PATH=/usr/local/lib/girepository-1.0

Other platforms

You need to install libvips from source since 8.2 has not been packaged yet (Jan 2016).

Download a tarball from the libvips website, or build from the git repository and see the README.

Installing the gem.

$ gem install ruby-vips8

or include it in Gemfile:

gem 'ruby-vips8'

And take a look in examples/. There is full yard documentation, take a look there too.

Example

require 'vips8'

im = Vips::Image.new_from_file filename

# put im at position (100, 100) in a 3000 x 3000 pixel image,
# make the other pixels in the image by mirroring im up / down /
# left / right, see
# http://www.vips.ecs.soton.ac.uk/supported/current/doc/html/libvips/libvips-conversion.html#vips-embed
im = im.embed 100, 100, 3000, 3000, :extend => :mirror
im.write_to_file output_filename

# multiply the green (middle) band by 2, leave the other two alone
im *= [1, 2, 1]

# make an image from an array constant, convolve with it
mask = Vips::Image.new_from_array [
    [-1, -1, -1],
    [-1, 16, -1],
    [-1, -1, -1]], 8
im = im.conv mask

What’s wrong with ruby-vips?

There’s an existing Ruby binding for vips here. It was written by a Ruby expert, it works well, it includes a test-suite, and has pretty full documentation. Why do another?

ruby-vips is based on the old vips7 API. There’s now vips8, which adds several very useful new features:

There are some more minor pluses as well:

This binding adds some extra useful features over the old ruby-vips binding.