ruby-vips

Ruby extension for the libvips image processing library.

Description

This gem provides a Ruby binding for the vips image processing library.

Programs that use ruby-vips don't manipulate images directly, instead they create pipelines of image processing operations building on a source image. When the end of the pipe is connected to a destination, the whole pipeline executes at once, streaming the image in parallel from source to destination a section at a time.

Because ruby-vips is very parallel, it's quick, and because it doesn't need to keep entire images in memory, it's light. For example, the benchmark at vips-benchmarks loads a large image, crops, shrinks, sharpens and saves again, and repeats 10 times.

Monthly Downloads: 1,514,145

Programming language: Ruby

License: MIT License

Tags: Image Processing     JPG     PNG     Image Manipulation     Image Resizing    

Latest version: v8.8.0.3

README

ruby-vips

This gem is a Ruby binding for the libvips image processing library. It has been tested on Linux, macOS and Windows, and with ruby 2, ruby 3 and jruby. It uses ruby-ffi to call functions in the libvips library.

libvips is a demand-driven, horizontally threaded image processing library. Compared to similar libraries, libvips runs quickly and uses little memory. libvips is licensed under the LGPL 2.1+.

Install on linux and macOS

Install the libvips binary with your package manager (eg. apt install libvips42 or perhaps brew install vips, see the libvips install instructions) then install this gem with:

gem install ruby-vips

Or include gem "ruby-vips" in your gemfile.

Install on Windows

The gemspec will pull in the msys libvips for you, so all you need is:

gem install ruby-vips

Or include gem "ruby-vips" in your gemfile.

Tested with the ruby and msys from choco, but others may work.

Example

require "vips"

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
# https://libvips.github.io/libvips/API/current/libvips-conversion.html#vips-embed
im = im.embed 100, 100, 3000, 3000, extend: :mirror

# 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, precision: :integer

# finally, write the result back to a file on disk
im.write_to_file output_filename

Documentation

There are full API docs for ruby-vips on rubydoc. This sometimes has issues updating, so we have a copy on the gh-pages for this site as well, which should always work.

See the Vips section in the docs for a tutorial introduction with examples.

The libvips reference manual has a complete explanation of every method.

The example/ directory has some simple example programs.

Benchmarks

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 five runs
benchmark       tiff    jpeg
ruby-vips.rb    0.85    0.78    
image-magick    2.03    2.44    
rmagick.rb  3.87    3.89    

peak memory use in kb
benchmark   peak RES
ruby-vips.rb    43864
rmagick.rb  788768

See also benchmarks at the official libvips website.