module Vips
This module provides a binding for the [libvips image processing library](libvips.github.io/libvips/).
# Example
“‘ruby require ’vips’
if ARGV.length < 2
raise "usage: #{$PROGRAM_NAME}: input-file output-file"
end
im = Vips::Image.new_from_file
ARGV, access: :sequential
im *= [1, 2, 1]
mask = Vips::Image.new_from_array
[
[-1, -1, -1], [-1, 16, -1], [-1, -1, -1] ], 8
im = im.conv mask, precision: :integer
im.write_to_file ARGV “‘
This example loads a file, boosts the green channel (I’m not sure why), sharpens the image, and saves it back to disc again.
Reading this example line by line, we have:
“‘ruby im = Vips::Image.new_from_file
ARGV, access: :sequential “`
{Image.new_from_file} can load any image file supported by vips. In this example, we will be accessing pixels top-to-bottom as we sweep through the image reading and writing, so ‘:sequential` access mode is best for us. The default mode is `:random`: this allows for full random access to image pixels, but is slower and needs more memory. See {Access} for full details on the various modes available.
You can also load formatted images from memory buffers, create images that wrap C-style memory arrays, or make images from constants.
Use {Source} and {Image.new_from_source} to load images from any data source, for example URIs.
The next line:
“‘ruby im *= [1, 2, 1] “`
Multiplying the image by an array constant uses one array element for each image band. This line assumes that the input image has three bands and will double the middle band. For RGB images, that’s doubling green.
Next we have:
“‘ruby mask = Vips::Image.new_from_array
[
[-1, -1, -1], [-1, 16, -1], [-1, -1, -1] ], 8
im = im.conv mask, precision: :integer “‘
{Image.new_from_array} creates an image from an array constant. The 8 at the end sets the scale: the amount to divide the image by after integer convolution.
See the libvips API docs for ‘vips_conv()` (the operation invoked by {Image#conv}) for details on the convolution operator. By default, it computes with a float mask, but `:integer` is fine for this case, and is much faster.
Finally:
“‘ruby im.write_to_file ARGV “`
{Image#write_to_file} writes an image back to the filesystem. It can write any format supported by vips: the file type is set from the filename suffix. You can also write formatted images to memory buffers, or dump image data to a raw memory array.
Use {Target} and {Image#write_to_target} to write formatted images to any data sink, for example URIs.
# How it works
The binding uses [ruby-ffi](github.com/ffi/ffi) to open the libvips shared library. When you call a method on the image class, it uses libvips introspection system (based on GObject
) to search the library for an operation of that name, transforms the arguments to a form libvips can digest, and runs the operation.
This means ruby-vips always presents the API implemented by the libvips shared library. It should update itself as new features are added.
# Automatic wrapping
‘ruby-vips` adds a {Image.method_missing} handler to {Image} and uses it to look up vips operations. For example, the libvips operation `add`, which appears in C as `vips_add()`, appears in Ruby as {Image#add}.
The operation’s list of required arguments is searched and the first input image is set to the value of ‘self`. Operations which do not take an input image, such as {Image.black}, appear as class methods. The remainder of the arguments you supply in the function call are used to set the other required input arguments. Any trailing keyword arguments are used to set options on the operation.
The result is the required output argument if there is only one result, or an array of values if the operation produces several results. If the operation has optional output objects, they are returned as a final hash.
For example, {Image#min}, the vips operation that searches an image for the minimum value, has a large number of optional arguments. You can use it to find the minimum value like this:
“‘ruby min_value = image.min “`
You can ask it to return the position of the minimum with ‘:x` and `:y`.
“‘ruby min_value, opts = min x: true, y: true x_pos = opts y_pos = opts “`
Now ‘x_pos` and `y_pos` will have the coordinates of the minimum value. There’s actually a convenience method for this, {Image#minpos}.
You can also ask for the top n minimum, for example:
“‘ruby min_value, opts = min size: 10, x_array: true, y_array: true x_pos = opts y_pos = opts “`
Now ‘x_pos` and `y_pos` will be 10-element arrays.
Because operations are member functions and return the result image, you can chain them. For example, you can write:
“‘ruby result_image = image.real.cos “`
to calculate the cosine of the real part of a complex image. There are also a full set of arithmetic operator overloads, see below.
libvips types are also automatically wrapped. The override looks at the type of argument required by the operation and converts the value you supply, when it can. For example, {Image#linear} takes a ‘VipsArrayDouble` as an argument for the set of constants to use for multiplication. You can supply this value as an integer, a float, or some kind of compound object and it will be converted for you. You can write:
“‘ruby result_image = image.linear 1, 3 result_image = image.linear 12.4, 13.9 result_image = image.linear [1, 2, 3], [4, 5, 6] result_image = image.linear 1, [4, 5, 6] “`
And so on. A set of overloads are defined for {Image#linear}, see below.
It does a couple of more ambitious conversions. It will automatically convert to and from the various vips types, like ‘VipsBlob` and `VipsArrayImage`. For example, you can read the ICC profile out of an image like this:
“‘ruby profile = im.get_value “icc-profile-data” “`
and profile will be a byte array.
If an operation takes several input images, you can use a constant for all but one of them and the wrapper will expand the constant to an image for you. For example, {Image#ifthenelse} uses a condition image to pick pixels between a then and an else image:
“‘ruby result_image = condition_image.ifthenelse then_image, else_image “`
You can use a constant instead of either the then or the else parts and it will be expanded to an image for you. If you use a constant for both then and else, it will be expanded to match the condition image. For example:
“‘ruby result_image = condition_image.ifthenelse [0, 255, 0], [255, 0, 0] “`
Will make an image where true pixels are green and false pixels are red.
This is useful for {Image#bandjoin}, the thing to join two or more images up bandwise. You can write:
“‘ruby rgba = rgb.bandjoin 255 “`
to append a constant 255 band to an image, perhaps to add an alpha channel. Of course you can also write:
“‘ruby result_image = image1.bandjoin image2 result_image = image1.bandjoin [image2, image3] result_image = Vips::Image.bandjoin
[image1, image2, image3] result_image = image1.bandjoin [image2, 255] “`
and so on.
# Logging
Libvips uses g_log() to log warning, debug, info and (some) error messages.
developer.gnome.org/glib/stable/glib-Message-Logging.html
You can disable warnings by defining the ‘VIPS_WARNING` environment variable. You can enable info output by defining `VIPS_INFO`.
# Exceptions
The wrapper spots errors from vips operations and raises the {Vips::Error} exception. You can catch it in the usual way.
# Automatic YARD documentation
The bulk of these API docs are generated automatically by {Vips::Yard::generate}. It examines libvips and writes a summary of each operation and the arguments and options that that operation expects.
Use the [C API docs](libvips.github.io/libvips/API/current) for more detail.
# Enums
The libvips enums, such as ‘VipsBandFormat` appear in ruby-vips as Symbols like `:uchar`. They are documented as a set of classes for convenience, see the class list.
# Draw operations
Paint operations like {Image#draw_circle} and {Image#draw_line} modify their input image. This makes them hard to use with the rest of libvips: you need to be very careful about the order in which operations execute or you can get nasty crashes.
The wrapper spots operations of this type and makes a private copy of the image in memory before calling the operation. This stops crashes, but it does make it inefficient. If you draw 100 lines on an image, for example, you’ll copy the image 100 times. The wrapper does make sure that memory is recycled where possible, so you won’t have 100 copies in memory.
If you want to avoid the copies, you’ll need to call drawing operations yourself.
# Progress
You can attach signal handlers to images to watch computation progress. For example:
“‘ruby image = Vips::Image.black 1, 100000 image.set_progress true
def progress_to_s(name, progress)
puts "#{name}:" puts " run = #{progress[:run]}" puts " eta = #{progress[:eta]}" puts " tpels = #{progress[:tpels]}" puts " npels = #{progress[:npels]}" puts " percent = #{progress[:percent]}"
end
image.signal_connect :preeval do |progress|
progress_to_s("preeval", progress)
end
image.signal_connect :eval do |progress|
progress_to_s("eval", progress) image.set_kill(true) if progress[:percent] > 50
end
image.signal_connect :posteval do |progress|
progress_to_s("posteval", progress)
end
image.avg “‘
The ‘:eval` signal will fire for every tile that is processed. You can stop progress with {Image#set_kill} and processing will end with an exception.
User streams
You can make your own input and output stream objects with {SourceCustom} and {TargetCustom}. For example:
“‘ruby file = File.open “some/file”, “rb” source = Vips::SourceCustom.new
source.on_read { |length| file.read length } image = Vips::Image.new_from_source
source, “”, access: “sequential” “`
# Overloads
The wrapper defines the usual set of arithmetic, boolean and relational overloads on image. You can mix images, constants and lists of constants (almost) freely. For example, you can write:
“‘ruby result_image = ((image * [1, 2, 3]).abs < 128) | 4 “`
# Expansions
Some vips operators take an enum to select an action, for example {Image#math} can be used to calculate sine of every pixel like this:
“‘ruby result_image = image.math :sin “`
This is annoying, so the wrapper expands all these enums into separate members named after the enum. So you can write:
“‘ruby result_image = image.sin “`
# Convenience functions
The wrapper defines a few extra useful utility functions: {Image#get_value}, {Image#set_value}, {Image#bandsplit}, {Image#maxpos}, {Image#minpos}, {Image#median}.
Constants
- ARGUMENT_CONSTRUCT
- ARGUMENT_DEPRECATED
- ARGUMENT_FLAGS
- ARGUMENT_INPUT
- ARGUMENT_MODIFY
- ARGUMENT_OUTPUT
- ARGUMENT_REQUIRED
-
enum VipsArgumentFlags
- ARGUMENT_SET_ALWAYS
- ARGUMENT_SET_ONCE
- ARRAY_DOUBLE_TYPE
- ARRAY_IMAGE_TYPE
- ARRAY_INT_TYPE
- BAND_FORMAT_TYPE
- BLEND_MODE_TYPE
- BLOB_TYPE
- CODING_TYPE
- IMAGE_TYPE
-
some handy gtypes
- INTERPRETATION_TYPE
- LIBRARY_VERSION
- LOG_DOMAIN
- MARSHAL_ALL
-
map signal name to marshal proc
- MARSHAL_FINISH
- MARSHAL_PROGRESS
-
Our signal marshalers.
These are functions which take the handler as a param and return a closure with the right FFI signature for g_signal_connect for this specific signal.
ruby-ffi makes it hard to use the g_signal_connect user data param to pass the function pointer through, unfortunately.
We can’t throw exceptions across C, so we must catch everything.
- MARSHAL_READ
- MARSHAL_SEEK
- MARSHAL_WRITE
- MAX_COORD
-
libvips has this arbitrary number as a sanity-check upper bound on image size. It’s sometimes useful to know when calculating scale factors.
- OPERATION_DEPRECATED
- OPERATION_FLAGS
- OPERATION_NOCACHE
- OPERATION_SEQUENTIAL
- REFSTR_TYPE
- VERSION
Public Class Methods
Source
# File lib/vips.rb, line 640 def self.at_least_libvips?(x, y) major = version(0) minor = version(1) major > x || (major == x && minor >= y) end
True if this is at least libvips x.y
Source
# File lib/vips.rb, line 597 def self.cache_set_max size vips_cache_set_max size end
Set the maximum number of operations that libvips should cache. Set 0 to disable the operation cache. The default is 1000.
Source
# File lib/vips.rb, line 610 def self.cache_set_max_files size vips_cache_set_max_files size end
Set the maximum number of files libvips should keep open in the operation cache. Set 0 to disable the operation cache. The default is 100.
Source
# File lib/vips.rb, line 603 def self.cache_set_max_mem size vips_cache_set_max_mem size end
Set the maximum amount of memory that libvips should use for the operation cache. Set 0 to disable the operation cache. The default is 100mb.
Source
# File lib/vips.rb, line 616 def self.concurrency_set n vips_concurrency_set n end
Set the size of the libvips worker pool. This defaults to the number of hardware threads on your computer. Set to 1 to disable threading.
Source
# File lib/vips.rb, line 650 def self.get_suffixes # vips_foreign_get_suffixes() was added in libvips 8.8 return [] unless Vips.respond_to? :vips_foreign_get_suffixes array = Vips::vips_foreign_get_suffixes names = [] p = array until (q = p.read_pointer).null? suff = q.read_string GLib::g_free q names << suff unless names.include? suff p += FFI::Type::POINTER.size end GLib::g_free array names end
Get a list of all supported file suffixes.
@return [[String]] array of supported suffixes
Source
# File lib/vips.rb, line 587 def self.leak_set leak vips_leak_set((leak ? 1 : 0)) end
Turn libvips leak testing on and off. Handy for debugging ruby-vips, not very useful for user code.
Source
# File lib/vips/image.rb, line 59 def self.p2str(pointer) pointer = FFI::AutoPointer.new(pointer, GLib::G_FREE) pointer.read_string end
turn a raw pointer that must be freed into a self-freeing Ruby string
Source
# File lib/vips.rb, line 630 def self.set_debug debug if debug GLib::logger.level = Logger::DEBUG end end
Deprecated compatibility function.
Don’t use this, instead change GLib::logger.level.
Source
# File lib/vips.rb, line 623 def self.vector_set enabled vips_vector_set_enabled(enabled ? 1 : 0) end
Enable or disable SIMD and the run-time compiler. This can give a nice speed-up, but can also be unstable on some systems or with some versions of the run-time compiler.