ruby-vips Documentation

To install ruby-vips, you must first install the libvips binary using your system's package manager. For example, use apt install libvips42 on Debian/Ubuntu or brew install vips on macOS. Once the binary is installed, install the gem via the command line or add it to your Gemfile.

Steps:

1. Install libvips binary via package manager.
2. Run gem install ruby-vips or add gem "ruby-vips" to your Gemfile.

Documentation for ruby-vips can be found in several places:

• Rubydoc: https://www.rubydoc.info/gems/ruby-vips
• GitHub Pages (Mirror): http://libvips.github.io/ruby-vips
• Tutorials: See the Vips section in the documentation for an introduction with examples.
• Method Reference: For a complete explanation of every method, refer to the official libvips reference manual.

On Windows, the ruby-vips gemspec automatically pulls in the msys libvips dependency. You only need to install the gem itself. It has been tested with Ruby and MSYS from Chocolatey (choco).

gem install ruby-vips

A Vips::Target represents a destination for image data. You can create different types of targets (files, memory, or file descriptors) and then use the Image#write_to_target method to write an image to that destination. When writing to a memory target, you can retrieve the resulting data using Object#get("blob").

target = Vips::Target.new_to_file('k2.jpg')
image.write_to_target(target, '.jpg')

The Vips::Image class uses method_missing to allow calling any libvips operation as if it were a method on the image object. If a method name corresponds to a valid VipsOperation nickname, it will be executed with the image as the first argument.

# If 'invert' is a valid vips operation:
new_image = image.invert

This also works on the class level: Vips::Image.method_name(args).

# Instead of explicit operation calls, use nicknames directly
new_image = image.some_vips_operation(arg1, arg2)

While Vips::Image objects are generally immutable, you can perform multiple modifications efficiently using the mutate method. This provides a Vips::MutableImage object within a block, allowing you to set or remove metadata and modify pixels without creating intermediate image objects.

image = image.mutate do |x|
  (0 ... 1).step(0.01) do |i|
    x.draw_line! 255, x.width * i, 0, 0, x.height * (1 - i)
  end
end

image = image.mutate do |x|
  x.set! "some-metadata", "value"
end

A Vips::Region represents a specific area of an image. You can create a region from an existing image object and then use the fetch method to quickly retrieve a block of raw pixel data from that region. This is useful for high-performance access to specific rectangular areas of an image.

To use it:

1. Initialize a new region with an image: region = Vips::Region.new(image).
2. Call fetch(left, top, width, height) to get the bytes.

Note: fetch requires libvips version 8.8 or higher.

region = Vips::Region.new(image)
pixels = region.fetch(10, 10, 100, 100)

In ruby-vips, standard Vips::Image objects are immutable. To perform in-place modifications (mutations) on an image, you should use the Vips::Image#mutate method. This method provides a Vips::MutableImage object within a block.

Inside the block, you can call VIPS operations that modify the image in-place. Once the block finishes, the method returns the modified Vips::Image.

Important: Vips::MutableImage is intended for internal use via the mutate interface. Do not attempt to instantiate Vips::MutableImage directly.

# Example pattern (conceptual usage)
# image.mutate do |x|
#   x.draw_point!(ink, left, top)
#   x.set!("metadata_key", "value")
# end

Images in libvips can hold metadata fields (e.g., icc-profile-data). Because images are immutable, you must use a mutate block to modify metadata.

Reading Metadata:

• Image#get_fields: Returns an array of supported metadata field names.
• Image#get_typeof(field): Returns the type of a specific field.
• Image#get(field): Returns the value of the field converted to a Ruby type.

Writing Metadata:

• Use MutableImage#set!(field, value) to change a value.
• Use MutableImage#set_type!(field, type) to create a new field with a specific type.

# Remove all metadata except the ICC profile
image = image.mutate do |mutable|
  image.get_fields.each do |field|
    mutable.remove! field unless field == "icc-profile-data"
  end
end

To use the ruby-vips bindings in your Ruby application, you must first require the vips library. This makes the Vips module and its associated image processing classes available.

require "vips"

Standard libvips operations are immutable and return a new image. If you perform many draw operations (like draw_line or draw_circle) on a standard Image, ruby-vips will create a full copy of the image for every single call, which is extremely slow and memory-intensive.

To modify an image in-place, use Image#mutate to obtain a MutableImage. Within the block, use the ! version of draw operations (e.g., draw_line!) to modify the image directly without copying.

image = image.mutate do |mutable|
  (0 ... 1).step(0.01) do |i|
    # Use the bang (!) version to modify in-place
    mutable.draw_line! 255, mutable.width * i, 0, 0, mutable.height * (1 - i)
  end
end