Libvips

From VipsWiki
Jump to: navigation, search

Main features

libvips is a fully demand-driven, threaded image processing library with no image size limits and with good support for colour. It is mature and documented. We have a How it works page with a technical explanation of how the VIPS evaluation system works, but in bullet-point form:

Designed to process large images 
You can comfortably work with images much larger than the RAM available on your machine. There is no upper size limit on images: you can easily manipulate 10GB images on a 32-bit machine (although note that some file formats (such as TIFF) do have size limits).
Fast and memory-efficient 
We have a page of Speed and Memory Use tests where, at least for that benchmark on that hardware, libvips is the fastest image processing library tested and uses the smallest amount of memory.
Simple to use 
There are straightforward C, C++ and Python interfaces, see below. Interfaces for other languages, like Ruby, are available from other projects. There's also a command-line interface (so you can write shell scripts that use VIPS), and a graphical user-interface. Confusingly, the GUI also has its own command-line mode. See below for examples.
Simple implementation 
The core of libvips (base types, image IO system, graph evaluation, threading system, and so on) is about 30,000 lines of heavily-commented C. The various operators are a further 100,000 or so lines of C and C++.
Free 
libvips is licensed under the LGPL. You can use it without charge in commercial applications, though note that if you modify the library you must make the source code of your changes available under the same terms.
Supports a large range of numeric types 
Images can be 8-, 16- and 32-bit integers, signed or unsigned, 32- and 64-bit floats, and 64- and 128-bit complex numbers. Images may have any number of bands and be of any size. Most image-processing operations can work on images of any type.
Supports a wide range of colour formats 
VIPS colours can be expressed as RGB, sRGB, XYZ, Yxy, Lab, CMC(l:c), and LCh. Almost all operations can work on images in any colour format.
Reads and writes TIFF, JPEG (JFIF), PPM/PGM/PBM/PFM, PNG, CSV, EXR, HDR (Radiance), Matlab, FITS, webp, Openslide and VIPS file formats 
The TIFF reader does most TIFF files. The VIPS image format is a fast and simple scheme VIPS uses internally for calculation, but you can also use it for saving images to files. If you build with libMagick, VIPS can load any libMagick-supported format (including BMP, GIF, DICOM, PDF etc.).
Completely demand-driven 
Images are not pushed through the system in single large lumps. Instead they are split into small regions which flow through your program pulled along by the need to create the final image. This makes it possible to perform a sequence of complex operations on a very large image without needing a lot of storage.
Threaded 
If you have more than one CPU in your computer, work is automatically spread over them, increasing processing speed. We have some Benchmarks.
Functional 
(Almost) all libvips operations are non-destructive. You never update an image, you only create new images. libvips has a variety of mechanisms to make this efficient. It has a set of destructive operations for things like line draw and flood-fill, but these operate in a slightly different manner.
Run-time code generation 
libvips uses Orc, the Oil Run-time Compiler, to generate code at run-time when possible for operations like convolution and morphology. This makes libvips very fast for many filters.
Supports ICC colour management with liblcms 
The PNG, JPEG and TIFF read operations attach any embedded profile as image metadata. Once read, you can use an attached profile (or another profile from a file) to transform an image to PCS. After processing, you can export from PCS back to device space, attaching the output profile used. The JPEG, PNG and TIFF writers will embed any attached profile in the output file.
(reasonably) reliable 
The library has been around in some form since 1991, so most of the bugs have been found and fixed. libvips includes a fairly comprehensive test suite which should pass with no memory leaks.
Conveniently wraps several other image libraries 
When VIPS configures it searches for various other image handling libraries, and if they are found, adds support for them. VIPS currently detects fftw, OpenEXR, Little CMS, Pango, Image Magick (or optionally Graphics Magick), libpng, libtiff, matio, cfitsio, OpenSlide, libwebp, libjpeg and libexif. You can manipulate images using (at least some of) the features of these other libraries, all within the same (relatively) convenient framework.
Full introspection 
VIPS operations are GObject classes. You can use the usual gobject-introspection systems, plus some extra introspection capabilities VIPS adds, to find operations and their arguments. All the interfaces to VIPS are dynamic, so when you add a new operation, it immediately appears in all interfaces.
Around 200 image-processing operations 
There are packages for filtering (various spatial and fourier), pixel arithmetic, histogram operations, morphological operations, compositing, 0-, 1- and 2-order resampling, mosaicing, and statistics. There's limited amounts of other stuff. The VIPS API docs summarise the available operations.

Simple examples

C++ interface

Here's a scrap of code to show the C++ API:

#include <vips/vips8>
 
using namespace vips;
 
int
main( int argc, char **argv )
{
        if( VIPS_INIT( argv[0] ) )
                return( -1 );
 
        VImage in = VImage::new_from_file( argv[1] );
 
        VImage mask = VImage::new_matrixv( 3, 3,
                -1, -1, -1, -1, 16, -1, -1, -1, -1 );
        mask.set( "scale", 8 );
 
        in.
                crop( 100, 100, in.width() - 200, in.height() - 200 ).
                similarity( VImage::option()->set( "scale", 0.9 ) ).
                conv( mask ).
                write_to_file( argv[2] );
 
        return( 0 );
}

Compile with something like:

g++ -Wall -o try -g try.cc `pkg-config vips-cpp --cflags --libs`

Python interface

The C++ program above would be:

import sys
from gi.repository import Vips
 
im = Vips.Image.new_from_file(sys.argv[1])
 
mask = Vips.Image.new_from_array([[-1, -1,  -1],
                                  [-1,  16, -1],
                                  [-1, -1,  -1]], scale = 8)
 
im = im.crop(100, 100, im.width - 200, im.height - 200)
im = im.similarity(scale = 0.9)
im = im.conv(mask)
 
im.write_to_file(sys.argv[2])

See also the Python page.

C interface

The same program in C would be:

#include <vips/vips.h>
 
int
main( int argc, char **argv )
{
        VipsImage *global;
        VipsImage **t;
 
        if( VIPS_INIT( argv[0] ) )
                return( -1 );
 
        global = vips_image_new();
        t = (VipsImage **) vips_object_local_array( VIPS_OBJECT( global ), 5 );
 
        if( !(t[0] = vips_image_new_from_file( argv[1], NULL )) )
                vips_error_exit( "unable to read %s", argv[1] );
 
        t[1] = vips_image_new_matrixv( 3, 3,
                -1.0, -1.0, -1.0,
                -1.0, 16.0, -1.0,
                -1.0, -1.0, -1.0 );
        vips_image_set_double( t[1], "scale", 8 );
 
        if( vips_crop( t[0], &t[2], 100, 100, t[0]->Xsize - 200, t[0]->Ysize - 200, NULL ) ||
                vips_similarity( t[2], &t[3], "scale", 0.9, NULL ) ||
                vips_conv( t[3], &t[4], t[1], NULL ) ||
                vips_image_write_to_file( t[4], argv[2], NULL ) )
                vips_error_exit( "unable to process %s", argv[1] );
 
        g_object_unref( global );
 
        return( 0 );
}

Compile with something like:

 gcc -Wall vips.c `pkg-config vips --cflags --libs` -o vips-c

Command-line interface

There's a simple command-line interface to libvips called vips. It lets you call any operation in the operation database. For example:

vips rot fred.jpg jim.tif d90

Will decompress the file fred.jpg into RAM, rotate it 90 degrees and write it to jim.tif in TIFF format.

You can embed format conversion options in the filename. For example:

vips rot fred.jpeg jim.tif[compression=deflate,tile] d90 

Writes a tiled tiff called jim.tif, with each tile compressed losslessly with DEFLATE (ie. zip) compression.

The vips program has a handy built-in help system. For example:

vips insert

prints

insert image @sub into @main at @x, @y
usage:
   insert main sub out x y
where:
   main         - Main input image, input VipsImage
   sub          - Sub-image to insert into main image, input VipsImage
   out          - Output image, output VipsImage
   x            - Left edge of sub in main, input gint
			default: 0
			min: -100000000, max: 100000000
   y            - Top edge of sub in main, input gint
			default: 0
			min: -100000000, max: 100000000
optional arguments:
   expand       - Expand output to hold all of both inputs, input gboolean
			default: false
   background   - Colour for new pixels, input VipsArrayDouble
operation flags: sequential-unbuffered 

nip2 also has a command-line interface. It is more complicated to use, but can be faster, as it is able to exploit libvips's chaining.

Further reading

The Documentation page has all the manuals on-line. See the Documentation#Publications section for a list of publications about VIPS.