ImageProcessing::Vips

The ImageProcessing::Vips module contains processing macros that use the ruby-vips gem (which is installed with the image_processing gem).

Installation

You will need to install libvips before using this module:

$ brew install vips

If you're using something other than Homebrew, see the installation instructions for more details.

NOTE: libvips 8.6 or higher is required.

Usage

require "image_processing/vips"

processed = ImageProcessing::Vips
  .source(image)
  .resize_to_limit(400, 400)
  .saver(strip: true)
  .call

processed #=> #<Tempfile:/var/folders/.../image_processing20180316-18446-1j247h6.png>

Resize-on-load

If you're resizing, it's highly recommended to have #resize_* as the first operation in the chain. That way the processor can perform resize-on-load (using vips_thumbnail()), which speeds up resizing significantly, and in certain cases even makes it more accurate.

# BAD: cannot utilize resize-on-load
ImageProcessing::Vips
  .source(image)
  .colourspace(:grey16)
  .resize_to_limit(400, 400)

# GOOD: utilizes resize-on-load
ImageProcessing::Vips
  .source(image)
  .resize_to_limit(400, 400)
  .colourspace(:grey16)

Methods

`.valid_image?`

Tries to calculate the image average using sequential access, and returns true if no exception was raised, otherwise returns false.

ImageProcessing::Vips.valid_image?(normal_image)  #=> true
ImageProcessing::Vips.valid_image?(invalid_image) #=> false

`#resize_to_limit`

Downsizes the image to fit within the specified dimensions while retaining the original aspect ratio. Will only resize the image if it's larger than the specified dimensions.

pipeline = ImageProcessing::Vips.source(image) # 600x800

result = pipeline.resize_to_limit!(400, 400)

Vips::Image.new_from_file(result.path).size #=> [300, 400]

It's possible to omit one dimension, in which case the image will be resized only by the provided dimension.

pipeline.resize_to_limit!(400, nil)
# or
pipeline.resize_to_limit!(nil, 400)

Any additional options are forwarded to Vips::Image#thumbnail_image:

pipeline.resize_to_limit!(400, 400, linear: true)

See vips_thumbnail() for more details.

`#resize_to_fit`

Resizes the image to fit within the specified dimensions while retaining the original aspect ratio. Will downsize the image if it's larger than the specified dimensions or upsize if it's smaller.

pipeline = ImageProcessing::Vips.source(image) # 600x800

result = pipeline.resize_to_fit!(400, 400)

Vips::Image.new_from_file(result.path).size #=> [300, 400]

It's possible to omit one dimension, in which case the image will be resized only by the provided dimension.

pipeline.resize_to_fit!(400, nil)
# or
pipeline.resize_to_fit!(nil, 400)

Any additional options are forwarded to Vips::Image#thumbnail_image:

pipeline.resize_to_fit!(400, 400, linear: true)

See vips_thumbnail() for more details.

`#resize_to_fill`

Resizes the image to fill the specified dimensions while retaining the original aspect ratio. If necessary, will crop the image in the larger dimension.

pipeline = ImageProcessing::Vips.source(image) # 600x800

result = pipeline.resize_to_fill!(400, 400)

Vips::Image.new_from_file(result.path).size #=> [400, 400]

Any additional options are forwarded to Vips::Image#thumbnail_image:

pipeline.resize_to_fill!(400, 400, crop: :attention) # smart crop

Crop option is :centre by default. Acceptable options are currently :none, :attention, :centre, and :entropy.

Note that from libvips 8.8, :crop option will accept two new values – :high and :low – which respectively position the crop box at the high end and low end of the axis that needs cropping. On libvips versions prior to 8.8 you can still get this behaviour, it just requires some work.

See vips_thumbnail() for more details.

`#resize_and_pad`

Resizes the image to fit within the specified dimensions while retaining the original aspect ratio. If necessary, will pad the remaining area with transparent color if source image has alpha channel, black otherwise.

pipeline = ImageProcessing::Vips.source(image) # 600x800

result = pipeline.resize_and_pad!(400, 400)

Vips::Image.new_from_file(result.path).size #=> [400, 400]

If you're converting from a format that doesn't support transparent colors (e.g. JPEG) to a format that does (e.g. PNG), setting :alpha to true will add the alpha channel to the image:

pipeline.resize_and_pad!(400, 400, alpha: true)

The :extend and :background options are also accepted and are forwarded to Vips::Image#gravity:

pipeline.resize_and_pad!(400, 400, extend: :copy)

The :gravity option can be used to specify the direction where the source image will be positioned (defaults to "centre").

pipeline.resize_and_pad!(400, 400, gravity: "north-west")

Any additional options are forwarded to Vips::Image#thumbnail_image:

pipeline.resize_to_fill!(400, 400, linear: true)

See vips_thumbnail() and vips_gravity() for more details.

`#resize_to_cover`

Resizes the image to cover the specified dimensions while retaining the original aspect ratio. The overflowing areas will not be cropped.

pipeline = ImageProcessing::Vips.source(image) # 600x800

result = pipeline.resize_to_cover!(300, 300)

Vips::Image.new_from_file(result.path).size #=> [300, 400]

Any additional options (except crop) are forwarded to Vips::Image#thumbnail_image:

pipeline.resize_to_cover!(400, 400, linear: true)

See vips_thumbnail() for more details.

`#crop`

Extracts an area from an image. The first two arguments are left & top edges of area to extract, while the last two arguments are the width & height of area to extract:

ImageProcessing::Vips
  .crop(20, 50, 300, 300) # extracts 300x300 area with top-left edge 20,50

`#rotate`

Rotates the image by the specified angle.

ImageProcessing::Vips
  .rotate(90)
  # ...

For degrees that are not a multiple of 90, you can also specify a background color for the empty triangles in the corners, left over from rotating the image.

ImageProcessing::Vips
  .rotate(45, background: [0, 0, 0])
  # ...

All other options are forwarded to Vips::Image#similarity. See vips_similarity() for more details.

`#composite`

Blends the image with the specified image. One use case for this can be applying a watermark.

ImageProcessing::Vips
  .composite(overlay)
  # ...

The overlay can be a String, Pathname, object that responds to #path, or a Vips::Image.

The blend mode can be specified via the :blend option (defaults to "over").

composite(overlay, mode: "atop")

The direction and position of the overlayed image can be controlled via the :gravity and :offset options:

composite(overlay, gravity: "south-east")
composite(overlay, gravity: "north-west", offset: [55, 55])

Any additional options are forwarded to Vips::Image#composite.

composite(overlay, premultiplied: true)

You can still invoke Vips::Image#composite directly by passing the blend mode as the second argument:

composite(overlay, :over) # calls Vips::Image#composite

See vips_composite() for more details.

`#convert`

Specifies the output format.

pipeline = ImageProcessing::Vips.source(image)

result = pipeline.convert!("png")

File.extname(result.path)
#=> ".png"

By default the original format is retained when writing the image to a file. If the source file doesn't have a file extension, the format will default to JPEG.

NOTE: libvips 8.6 is able to normally read GIF images (and convert them to other formats), but it's not able to save to GIF format. If you need full GIF support, you need to use libvips 8.7+ compiled with ImageMagick support (--with-imagemagick for Homebrew).

`#method_missing`

Any unknown methods will be delegated to Vips::Image.

ImageProcessing::Vips
  .crop(0, 0, 300, 300)
  .invert
  .set("icc-profile-data", custom_profile)
  .remove("xmp-data")
  .gaussblur(2)
  # ...

`#custom`

Yields the intermediary Vips::Image object. If the block return value is a Vips::Image object it will be used in further processing, otherwise if nil is returned the original Vips::Image object will be used.

ImageProcessing::Vips
  .custom { |image| image + image.invert if invert? }
  # ...

`#loader`

Specifies options that will be forwarded to Vips::Image.new_from_file.

ImageProcessing::Vips
  .loader(access: :sequential)
  # ...

If the #loader clause is specified multiple times, the options are merged.

ImageProcessing::Vips
  .loader(page: 0)
  .loader(dpi: 300)

# resolves to

ImageProcessing::Vips
  .loader(page: 0, dpi: 300)

See vips_jpegload(), vips_pngload() etc. for more details on format-specific load options. Any provided options that are not defined for a specific loader will be ignored.

By default, libvips will select the appropriate loader based on the type of the source image. If libvips fails to determine the type of the source image, you can force a specific loader:

ImageProcessing::Vips
  .loader(loader: :svg) # calls `Vips::Image.svgload`
  # ...

An additional :autorot option is accepted to specify whether vips_autorot() should be automatically called after the image is loaded (defaults to true).

ImageProcessing::Vips
  .loader(autorot: false) # disable automatic rotation
  # ...

If you would like to have more control over loading, you can load the image directly using Vips::Image, and just pass the Vips::Image object as the source file.

vips_image = Vips::Image.magickload(file.path, n: -1)

ImageProcessing::Vips
  .source(vips_image)
  # ...

`#saver`

Specifies options that will be forwarded to Vips::Image#write_to_file.

ImageProcessing::Vips
  .saver(quality: 100) # alias for :Q
  # ...

If the #saver clause is repeated multiple times, the options are merged.

ImageProcessing::Vips
  .saver(tile: true)
  .saver(compression: :lzw)

# resolves to

ImageProcessing::Vips
  .saver(tile: true, compression: :lzw)

See vips_jpegsave(), vips_pngsave() etc. for more details on format-specific save options. Any provided options that are not defined for a specific saver will be ignored.

By default, libvips will select the appropriate saver based on the file extension of the destination path. If libvips fails to understand the file extension, you can force a specific saver:

ImageProcessing::Vips
  .saver(saver: :tiff) # calls `Vips::Image#tiffsave`
  # ...

If you would like to have more control over saving, you can call #call(save: false) to get the Vips::Image object, and call the saver on it directly.

vips_image = ImageProcessing::Vips
  .resize_to_limit(400, 400)
  .call(save: false)

vips_image #=> #<Vips::Image ...>

vips_image.write_to_file("/path/to/destination", **options)

`#apply`

This is a convenience method for sending multiple commands to the builder using a hash. Hash keys can be any method that the builder responds to. Hash values can be either a single argument, an array of arguments, or true/nil indicating no arguments. Instead of a hash you can also use an array if you want to send multiple commands with the same name.

ImageProcessing::Vips
  .apply(
    invert: true,
    smartcrop: [200, 200],
    resize_to_limit: [400, 400],
    convert: "jpg",
    saver: { quality: 100 },
  )
  # ...

Sharpening

All #resize_* operations will automatically sharpen the resulting thumbnails after resizing, using the following convolution mask:

Vips::Image.new_from_array [
  [-1, -1, -1],
  [-1, 32, -1],
  [-1, -1, -1]], 24

You can assign a different convolution mask via the :sharpen option:

sharpen_mask = Vips::Image.new_from_array [
  [-1, -1, -1],
  [-1, 24, -1],
  [-1, -1, -1]], 16

ImageProcessing::Vips
  .source(image)
  .resize_to_limit!(400, 400, sharpen: sharpen_mask)

You can disable automatic sharpening by setting :sharpen to false:

ImageProcessing::Vips
  .source(image)
  .resize_to_limit!(400, 400, sharpen: false)

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

vips.md

vips.md

ImageProcessing::Vips

Contents

Installation

Usage

Resize-on-load

Methods

`.valid_image?`

`#resize_to_limit`

`#resize_to_fit`

`#resize_to_fill`

`#resize_and_pad`

`#resize_to_cover`

`#crop`

`#rotate`

`#composite`

`#convert`

`#method_missing`

`#custom`

`#loader`

`#saver`

`#apply`

Sharpening

Files

vips.md

Latest commit

History

vips.md

File metadata and controls

ImageProcessing::Vips

Contents

Installation

Usage

Resize-on-load

Methods

.valid_image?

#resize_to_limit

#resize_to_fit

#resize_to_fill

#resize_and_pad

#resize_to_cover

#crop

#rotate

#composite

#convert

#method_missing

#custom

#loader

#saver

#apply

Sharpening

`.valid_image?`

`#resize_to_limit`

`#resize_to_fit`

`#resize_to_fill`

`#resize_and_pad`

`#resize_to_cover`

`#crop`

`#rotate`

`#composite`

`#convert`

`#method_missing`

`#custom`

`#loader`

`#saver`

`#apply`