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 and C++ interfaces, see below. There's a nice Python interface over the C++ one. 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, operation database, and so on) is about 20,000 lines of heavily-commented C. The various operators are a further 100,000 or so lines of C and C++.
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(1:1), and LCh. Almost all operations can work on images in any colour format.
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.
If you have more than one CPU in your computer, work is automatically spread over them, increasing processing speed. We have some Benchmarks.
(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. The graphical user interface tends to be less stable.
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, Video 4 Linux, Image Magick (or optionally Graphics Magick), libpng, libtiff, matio, cfitsio, OpenSlide, 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.
Simple image-processing operation database 
The operation database lists all the supported image processing operations, together with the number and type of their arguments. The C++ API is generated automatically from the database, and all the user-interfaces query it when they start up. If you write a new operation you only need to add it to the database and it automatically appears in all the user-interfaces. You can even replace the standard VIPS operations with your own implementations. You don't need to recompile any parts of VIPS to do this: plugins are found and loaded at run time.
Around 300 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.
Reads and writes TIFF, JPEG (JFIF), PPM/PGM/PBM/PFM, PNG, CSV, EXR, HDR (Radiance), Matlab, FITS 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, DICOM3, PDF etc.).
See Documentation for the VIPS manual, plus a set of UNIX manual pages describing each function in more detail. There's other stuff there as well, and a set of HOWTOs.

Simple examples

C++ interface

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

#include <vips/vips>
using namespace vips;
main (int argc, char **argv)
    try {
        // open the file named in argv[1] ... can be TIFF, JPEG,
        // PBM/PGM/PPM, PNG, HDR, Matlab or VIPS format
        // if libMagick was found when VIPS was built, this will
        // also load any libMagick-supported image format (more than 80)
        VImage fred (argv[1]);
        // make a 3x3 sharpen mask
        VIMask sharp (3, 3, 8, 0,
            -1, -1, -1,
            -1, 16, -1,
            -1, -1, -1);
        // brighten and sharpen
        VImage jim = (fred * 1.2).conv (sharp);
        // write to file argv[2]
        jim.write (argv[2]);
    catch (VError &e) {
        e.perror (argv[0]);
    return (0);

Compile with something like:

g++ -Wall -o try -g `pkg-config vipsCC-7.20 --cflags --libs`

Python interface

This is a simple wrapping of the C++ interface with SWIG, so all the documentation there applies. For example, the C++ program above would be:

import sys
from vipsCC import *
    fred = VImage.VImage (sys.argv[1])
    sharp = VMask.VIMask (3, 3, 8, 0, 
		  [-1, -1, -1, 
		   -1,  16, -1, 
		   -1, -1, -1])
    jim = fred.lin (1.2, 0).conv (sharp)
    jim.write (sys.argv[2])
except VError.VError, e:
    e.perror (sys.argv[0])

See also the Python page.

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 im_rot90 fred.jpg jim.tif 

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 im_rot90 fred.jpeg jim.tif:deflate,tile 

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 -u im_insert


usage: vips im_insert in sub out x y
       in is of type "image"
       sub is of type "image"
       out is of type "image"
       x is of type "integer"
       y is of type "integer"
insert sub-image into main image at position, from package "conversion"
flags: (PIO function) (coordinate transformer) (area operation) (result can be cached)

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.