Libvips
From VipsWiki
(Difference between revisions)
| Revision as of 12:26, 6 January 2009 John (Talk | contribs) (→C++ interface) ← Previous diff |
Revision as of 12:27, 6 January 2009 John (Talk | contribs) (→C++ interface) Next diff → |
||
| Line 74: | Line 74: | ||
| Compile with something like: | Compile with something like: | ||
| - | g++ -Wall -o try -g try.cc `pkg-config vipsCC-7.14 --cflags --libs` | + | g++ -Wall -o try -g try.cc `pkg-config vipsCC-7.16 --cflags --libs` |
| === Python interface === | === Python interface === | ||
Revision as of 12:27, 6 January 2009
Contents |
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 mages
- 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) have size limits).
- 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.
- Supports ICC colour management with liblcms
- The VIPS 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 and TIFF writers will embed any attached profile in the output file.
- Completely demand-driven
- Images are not pushed through the system in single large lumps. Instead they are split into small tiles 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.
- 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.
- Automatic file format conversion
- Files are automatically converted between the various supported formats on read and write.
- (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 and 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, and no segmentation (sadly). The VIPS Reference Guide summarises the available operations.
- Reads and writes TIFF, JPEG (JFIF), PPM/PGM/PBM, PNG, CSV, EXR 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.).
- Documented
- 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;
int
main (int argc, char **argv)
{
try {
// open the file named in argv[1] ... can be TIFF, JPEG,
// PBM/PGM/PPM, PNG 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 try.cc `pkg-config vipsCC-7.16 --cflags --libs`
Python interface
This is a simple wrapping of the C++ interface with SWIG, so all the documentation there applies. For example:
import sys
from vipsCC import *
if len (sys.argv) != 3:
print 'usage:', sys.argv[0], 'inputimage outputimage'
sys.exit (1)
try:
a = VImage.VImage (sys.argv[1])
a.invert ().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
prints
usage: vips im_insert in sub out x y
where:
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 much 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.
