libvips/whatsnew-8.5.md

libvips 8.5 should be out by the end of March 2017. This page introduces the main features.

New operators

Almost all of the logic from the vipsthumbnail program is now in a pair of new operators, vips_thumbnail() and vips_thumbnail_buffer(). These are very handy for the various scripting languages with vips bindings: you can now make a high-quality, high-speed thumbnail in PHP (for example) with just:

$filename = ...;
$image = Vips\Image::thumbnail($filename, 200, ["height" => 200]);
$image.writeToFile("my-thumbnail.jpg");

The new thumbnail operator has also picked up some useful features:

• Smart crop A new cropping mode called attention searches the image for edges, skin tones and areas of saturated colour, and attempts to position the crop box over the most significant feature. There's a vips_smartcrop() operator as well.

• Crop constraints Thanks to tomasc, libvips has crop constraints. You can set it to only thumbnail if the image is larger or smaller than the target (the < and > modifiers in imagemagick), and to crop to a width or height.

• Buffer sources vips_thumbnail_buffer() will thumbnail an image held as a formatted block of data in memory. This is useful for cloud services, where the filesystem is often rather slow.

CLAHE, or Contrast-Limited Adaptive Histogram Equalisation, is a simple way to make local histogram equalisation more useful.

Plain local equalization removes all global brightness variation and can make images hard to understand. The hist_local operator now has a max-slope parameter you can use to limit how much equalisation can alter your image. A value of 3 generally works well.

Toilet roll images

libvips used to let you pick single pages out of multi-page images, such as PDFs, but had little support for processing entire documents.

libvips 8.5 now has good support for toilet roll images. You can load a multipage image as a very tall, thin strip, process the whole thing, and write back to another multi-page file. The extra feature is an n parameter which gives the number of pages to load, or -1 to load all pages.

For example, (OME- TIFF)[https://www.openmicroscopy.org/site/support/ome-model/ome-tiff] is a standard for microscopy data that stores volumetric images as multi-page TIFFs. They have some (sample data)[https://www.openmicroscopy.org/site/support/ome-model/ome-tiff/data.html] including a 4D image of an embryo.

Each TIFF contains 10 slices. Normally you just see page 0:

$ vipsheader tubhiswt_C0_TP13.ome.tif
tubhiswt_C0_TP13.ome.tif: 512x512 uchar, 1 band, b-w, tiffload

Use n=-1 and you see all the pages as a very tall strip:

$ vipsheader tubhiswt_C0_TP13.ome.tif[n=-1]
tubhiswt_C0_TP13.ome.tif: 512x5120 uchar, 1 band, b-w, tiffload

You can work with PDF, TIFF, GIF and all imagemagick-supported formats in this way.

You can write this tall strip to another file, and it will be broken up into pages:

$ vips copy tubhiswt_C0_TP13.ome.tif[n=-1] x.tif
$ vipsheader x.tif 
x.tif: 512x512 uchar, 1 band, b-w, tiffload
$ vipsheader x.tif[n=-1]
x.tif: 512x5120 uchar, 1 band, b-w, tiffload

The extra magic is a page-height property that images carry around that says how long each sheet of toilet paper is.

There are clearly some restrictions with this style of multi-page document handling: all pages must have identical width, height and colour depth; and image processing operators have no idea they are dealing with a multi-page document, so if you do something like resize, you'll need to update page-height. You'll also need to be careful about edge effects if you're using spatial filters.

Computation reordering

Thanks to the developer of (PhotoFlow)[https://github.com/aferrero2707/PhotoFlow], a non-destructive image editor with a libvips backend, libvips can now reorder computations to reduce recalculation. This can (sometimes) produce a dramatic speedup.

This has been (discussed on the libvips blog)[http://libvips.blogspot.co.uk/2017/01/automatic-computation-reordering.html], but briefly, the order in which operator arguments are evaluated can have a big effect on runtime due to the way libvips tries to cache and reuse results behind the scenes.

The blog post has some examples and some graphs.

New sequential mode

libvips sequential mode has been around for a while. This is the thing libvips uses to stream pixels through your computer, from input file to output file, without having to have the whole image in memory all at the same time. When it works, it give a nice performance boost and a large drop in memory use.

There are some more complex cases where it didn't work. Consider this Python program:

#!/usr/bin/python

import sys 
import random

import gi 
gi.require_version('Vips', '8.0') 
from gi.repository import Vips

composite = Vips.Image.black(10000, 10000)

for filename in sys.argv[2:]:
    tile = Vips.Image.new_from_file(filename, access = Vips.Access.SEQUENTIAL)
    x = random.randint(0, composite.width - tile.width) 
    y = random.randint(0, composite.height - tile.height) 
    composite = composite.insert(tile, x, y)

composite.write_to_file(sys.argv[1]) 

It makes a large 10,000 x 10,000 pixel image, then inserts all of the images you list at random positions, then writes the result.

You'd think this could work with sequential mode, but sadly with earlier libvipses it will sometimes fail. The problem is that images can cover each other, so while writing, libvips can discover that it only needs the bottom few pixels of one of the input images. The image loaders used to track the current read position, and if a request came in for some pixels way down the image, they'd assume one of the evaluation threads had run ahead of the rest and needed to be stalled. Once stalled, it was only restarted on a long timeout, causing performance to drop through the floor.

libvips 8.5 has a new implementation of sequential mode that changes the way threads are kept together as images are processed. Rather than trying to add constraints to load operations, instead it puts the constraints into operations that can cause threads to become spread out, such as vertical shrink.

As a result of this change, many more things can run in sequential mode, and out of order reads should be impossible.

libxml2 swapped out for expat

libvips has used libxml2 as its XML parser since dinosaurs roamed the Earth. Now libvips is based on gobject, the XML parser selected by glib, expat, makes more sense, since it will already be linked.

It's nice to be able to remove a required dependency for a change.

File format support

As usual, there are a range of improvements to file format read and write.

• Thanks to a push from Felix Bünemann, TIFF now supports load and save to and from memory buffers.
• dzsave can write to memory (as a zip file) as well.
• Again, thanks to pushing from Felix, libvips now supports ICC, XMP and IPCT metadata for WebP images.
• FITS images support bzero and bscale.
• tiffload memory use is now much lower for images with large strips.

Other

Many small bug fixes, improvements to the C++ binding. As usual, the ChangeLog has more detail, if you're interested.