Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Ruby extension for the vips image processing library.
C Ruby

This branch is 53 commits behind jcupitt:master

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.
examples
ext
lib
spec
.gitignore
.rspec
.travis.yml
CHANGELOG.md
Gemfile
Gemfile.lock
LICENSE
README.md
Rakefile
TODO
compile
ruby-vips.gemspec
ruby.supp

README.md

ruby-vips : A fast image processing extension for Ruby.

Build Status

ruby-vips is a ruby extension for vips. It is fast and it can process images without requiring the entire image to be loaded into memory. For example, the benchmark at vips-benchmarks loads a large image, crops, shrinks, sharpens and saves again:

real time in seconds, fastest of three runs
benchmark       tiff    jpeg
ruby-vips.rb    0.45    0.56    
rmagick.rb      1.69    1.90    
netpbm.sh       1.74    1.63    
image-magick.sh 2.87    3.02    
image_sci.rb    3.19    2.90    

peak memory use in kilobytes
benchmark       peak RSS
ruby-vips.rb    160400
image_sci.rb    546992
rmagick.rb      1370064

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

ruby-vips 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.

note: ruby-vips will work with versions of libvips as far back as 7.12, but with missing features and with reduced performance. For best results, use the latest libvips you can.

Requirements.

  • OS X or Linux
  • MRI 1.8.7, 1.9.2
  • libvips 7.24 and later (it will work with earlier libvips, but some features may not be functional)

Installation.

Ubuntu Prerequisites.

$ apt-get install libvips-dev

OS X Prerequisites.

$ brew install --use-llvm vips

You may need to set your PKG_CONFIG_PATH before vips can see your libpng. Try something like:

export PKG_CONFIG_PATH=/usr/local/lib/pkgconfig:/usr/lib/pkgconfig:/usr/X11/lib/pkgconfig

See the Mac OS X Lion section in Installation on various platforms.

TODO: Describe & test with macports.

Other platforms

See Installation on various platforms.

Installing the gem.

$ gem install ruby-vips

Alternatively, for a debug build:

$ gem install ruby-vips -- --enable-debug

or include it in Gemfile:

gem 'ruby-vips'

Documentation.

ruby-vips has rdoc documentation. Also see Wiki page

Small example

See also the examples directory.

require 'rubygems'
require 'vips'

include VIPS

# Create an image object. It will not actually load the pixel data until 
# needed. 
im = Image.jpeg('mypic.jpg')

# You can read all the header fields without triggering a pixel load.
puts "it's #{im.x_size} pixels across!"

# Shrink the jpeg by a factor of four when loading -- huge speed and CPU
# improvements on large images.
im = Image.jpeg('mypic.jpg', :shrink_factor => 4)
puts "but only #{im.x_size} pixels when we shrink on load"

# Add a shrink by a factor of two to the pipeline. This will not actually be
# executed yet.
im_shrink_by_two = im.shrink(2)

# Write out the shrunk image to a PNG file. This is where the image is
# actually loaded and resized. With images that allow for random access from
# the hard drive (VIPS native format, tiled OpenEXR, ppm/pbm/pgm/pfm, tiled
# tiff, and RAW images), the entire image is never read into memory.
# For other formats, the image is either decompressed to a temporary disc 
# file and then processed from there, or, if you give the :sequential hint, 
# streamed directly from the file.
im_shrink_by_two.png('out.png', :interlace => true)

# All ruby-vips image commands can be chained, so the above sequence could
# be written as:
Image.jpeg('mypic.jpg', :shrink_factor => 4).shrink(2).png('out.png')

# You hint sequential mode in the loader, so this will stream directly from
# the source image:
Image.jpeg('large.png', :sequential => true).shrink(2).png('out.png')

# The statement above will load the jpeg (pre-shrunk by a factor of four),
# shrink the image again by a factor of two, and then save as a png image.

# If you want to let vips determine file formats, you can use the generic
# reader and writer:
Image.new('mypic.jpg').shrink(2).write('out.png')

Why use ruby-vips?

  • It supports over 250 low-level image and color manipulation operations.
  • Operations are chainable and do not get executed until the image is sent to an output.
  • Memory use is low, even for very, very large images.
  • Fastest ruby library for resizing large images. See benchmarks at the official libvips website and vips-benchmarks
Something went wrong with that request. Please try again.