API break: version 1.0 of this gem is an API break, see below for some notes
on why there is a break and how to update your code.
ruby-vips is still here and still maintained in branch
This gem provides a Ruby binding for the vips image processing library.
Programs that use
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.
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.
real time in seconds, fastest of three runs benchmark tiff jpeg ruby-vips.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 117604 image_sci.rb 146536 rmagick.rb 3352020
- OS X or Linux
- libvips 8.2 and later
Install homebrew and enter:
$ brew install homebrew/science/vips
To verify that your vips install is working, try:
$ vips --version vips-8.2.1
Check your package manager and see if the libvips on your system is new enough.
ruby-vips needs libvips 8.2 or later.
Installing the gem.
$ gem install ruby-vips
or include it in Gemfile:
And take a look in
examples/. There is full yard documentation, take a look
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 # 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 # 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 # finally, write the result back to a file on disk im.write_to_file output_filename
Why the API break?
There's been a
ruby-vips for a few years now.
It was written by a Ruby
expert, it works well, it includes a test-suite, and has pretty full
documentation. Why rewrite?
ruby-vips 0.3 was based on the old vips7 API. There's now vips8,
which adds several
very useful new features:
GObject-based API with full introspection. You can discover the vips8 API at runtime. This means that if libvips gets a new operator, any binding that goes via vips8 will get the new thing immediately. With vips7, whenever libvips was changed, all the bindings needed to be changed too.
No C required. Thanks to gobject-introspection you can write the binding in Ruby itself, there's no need for any C. This makes it a lot smaller and more portable.
vips7 probably won't get new features. vips7 doesn't really exist any more: the API is still there, but now just a thin compatibility layer over vips8. New features may well not get added to the vips7 API.
There are some more minor pluses as well:
Named and optional arguments. vips8 lets you have optional and required arguments, both input and output, and optional arguments can have default values.
Operation cache. vips8 keeps track of the last 1,000 or so operations and will automatically reuse results when it can. This can give a huge speedup in some cases.
vips8 is much simpler and more regular. For example, ruby-vips had to work hard to offer a nice loader system, but that's all built into vips8. It can do things like load and save formatted images to and from memory buffers as well, which just wasn't possible before.
This binding adds some extra useful features over the old
Full set of arithmetic operator overloads.
Automatic constant expansion. You can write things like
image.bandjoin(255)and the 255 will be automatically expanded to an image and attached as an extra band. You can mix int, float, scalar, vector and image constants freely.
How to update your code
Vips::Image.new_from_file(filename), similarly for other formats.
#write_to_file(filename), same for all other formats.
Most member functions are unchanged, but check the yard docs. You can also use the C docs directly, since
ruby-vipsis now a very thin layer over the C API. See the docs for the
Vipsclass for guidance.
There are lots of nice new features, see the docs and examples.