4.2 VIPS packages

4.2.1 Arithmetic

See Figure 4.1.

Arithmetic functions work on images as if each band element were a separate number. All operations are point-to-point — each output element depends exactly upon the corresponding input element. All (except in a few cases noted in the manual pages) will work with images of any type (or any mixture of types), of any size and of any number of bands.

Arithmetic operations try to preserve precision by increasing the number of bits in the output image when necessary. Generally, this follows the ANSI C conventions for type promotion — so multiplying two IM_BANDFMT_UCHAR images together, for example, produces a IM_BANDFMT_USHORT image, and taking the im_costra() of a IM_BANDFMT_USHORT image produces a IM_BANDFMT_FLOAT image. The details of the type conversions are in the manual pages.

4.2.2 Relational

See Figure 4.2.

Relational functions compare images to other images or to constants. They accept any image or pair of images (provided they are the same size and have the same number of bands — their types may differ) and produce a IM_BANDFMT_UCHAR image with the same number of bands as the input image, with 255 in every band element for which the condition is true and 0 elsewhere.

They may be combined with the boolean functions to form complex relational conditions. Use im_max() (or im_min()) to find out if a condition is true (or false) for a whole image.

4.2.3 Boolean

See Figure 4.3.

The boolean functions perform boolean arithmetic on pairs of IM_BANDFMT_UCHAR images. They are useful for combining the results of the relational and morphological functions. You can use im_eorconst() with 255 as im_not().

4.2.4 Colour

See Figure 4.5.

The colour functions can be divided into two main types. First, functions to transform images between the different colour spaces supported by VIPS: RGB (also referred to as disp), sRGB, XYZ, Yxy, Lab, LabQ, LabS, LCh and UCS), and second, functions for calculating colour difference metrics. Figure 4.4 shows how the VIPS colour spaces interconvert.

The colour spaces supported by VIPS are:

LabQ

This is the principal VIPS colorimetric storage format. See the man page for im_LabQ2Lab() for an explanation. You cannot perform calculations on LabQ images. They are for storage only. Also refered to as LABPACK.

LabS

This format represents coordinates in CIE L∗a∗b∗ space as a three- band IM_BANDFMT_SHORT image, scaled to fit the full range of bits. It is the best format for computation, being relatively compact, quick, and accurate. Colour values expressed in this way are hard to visualise.

Lab

Lab colourspace represents CIE L∗a∗b∗ colour values with a three-band IM_BANDFMT_FLOAT image. This is the simplest format for general work: adding the constant 50 to the L channel, for example, has the expected result.

XYZ

CIE XYZ colour space represented as a three-band IM_BANDFMT_FLOAT image.

XYZ

CIE Yxy colour space represented as a three-band IM_BANDFMT_FLOAT image.

RGB

(also refered to as disp) This format is similar to the RGB colour systems used in other packages. If you want to export your image to a PC, for example, convert your colorimetric image to RGB, then turn it to TIFF with im_vips2tiff(). You need to supply a structure which characterises your display. See the manual page for im_col_XYZ2rgb() for hints on these guys.

VIPS also supports sRGB. This is a version of RGB with a carefully defined and standard conversion from XYZ. See:

http://www.color.org/

LCh

Like Lab, but rectangular ab coordinates are replaced with polar Ch (Chroma and hue) coordinates. Hue angles are expressed in degrees.

UCS

A colour space based on the CMC(1:1) colour difference measurement. This is a highly uniform colour space, much better than CIE L∗a∗b∗ for expressing small differences. Conversions to and from UCS are extremely slow.

All VIPS colourspaces assume a D65 illuminant.

The colour-difference functions calculate either ΔE CIE L∗a∗b∗ (1976 or 2000) or ΔE CMC(1:1) on two images in Lab, XYZ or disp colour space.

4.2.5 Conversion

See Figure 4.6.

These functions may be split into three broad groups: functions which convert between the VIPS numeric formats (im_clip2fmt(), for example, converts an image of any type to the specified IM_BANDFMT), functions supporting complex arithmetic (im_c2amph(), for example, converts a complex image from rectangular to polar co ordinates) and functions which perform some simple geometric conversion (im_extract() forms a sub-image).

gbandjoin and the C function im_gbandjoin() will do a bandwise join of many images at the same time. See the manual pages.

4.2.6 Matricies

See Figure 4.8.

VIPS uses matricies for morphological operations, for convolutions, and for some colour-space conversions. There are two types of matrix: integer (INTMASK) and double precision floating point (DOUBLEMASK).

For convenience, both types are stored in files as ASCII. The first line of the file should start with the matrix dimensions, width first, then on the same line an optional scale and offset. The two size fields should be integers; the scale and offset may be floats. Subsequent lines should contain the matrix elements, one row per line. The scale and offset are the conventional ones used to represent non-integer values in convolution masks — in other words:

If the scale and offset are missing, they default to 1.0 and 0.0. See the sections on convolution for more on the use of these fields. So as an example, a 4 by 4 identity matrix would be stored as:

And a 3 by 3 mask for block averaging with convolution might be stored as:

(in other words, sum all the pels in every 3 by 3 area, and divide by 9).

This matrix contains only integer elements and so could be used as an argument to functions expecting both INTMASK and DOUBLEMASK matricies. However, masks containing floating-point values (such as the output of im_matinv()) can only be used as arguments to functions expecting DOUBLEMASKs.

A set of functions for mask input and output are also available for C-programmers — see the manual pages for im_read_dmask(). For other matrix functions, see also the convolution sections and the arithmetic sections.

4.2.7 Convolution

See Figure 4.9.

The functions available in the convolution package can be split into five main groups.

First, are the convolution functions. The most useful function is im_conv() which will convolve any non-complex type with an INTMASK matrix. The output image will have the same size, type, and number of bands as the input image. Of the other im_conv() functions, functions whose name ends in _raw do not add a black border around the output image, functions ending in f use a DOUBLEMASK matrix and write float (or double) output, and functions containing sep are for seperable convolutions. im_compass(), im_lindetect() and im_gradient() convolve with rotating masks. im_embed() is used by the convolution functions to add the border to the output.

Next, are the build functions. im_gauss_⋆mask() and its ilk generate gaussian masks, im_log_⋆mask() generate logs of Laplacians. im_addgnoise() and im_gaussnoise() create or add gaussian noise to an image.

Two functions do correlation: im_fastcor() does a quick and dirty correlation, im_spcor() calculates true spatial correlation, and is rather slow.

Some functions are provided for analysing images: im_zerox() counts zero-crossing points in an image, im_mpercent() finds a threshold that will isolate a percentage of points in an image.

Finally, im_resize_linear() and im_shrink() do as you would expect.

4.2.8 In-place operations

See Figure 4.10.

A few of the in-place operations are available from the command-line. Most are not.

4.2.9 Frequency filtering

See Figure 4.11.

The basic Fourier functions are im_fwfft() and im_invfft(), which calculate the fast-fourier transform and inverse transform of an image. Also im_invfftr(), which just returns the real part of the inverse transform. The Fourier image has its origin at pel (0,0) — for viewing, use im_rotquad() to move the origin to the centre of the image.

Once an image is in the frequency domain, it can be filtered by multiplying it with a mask image. The VIPS mask generator is im_create_fmask() see the manual page for details of the arguments, but it will create low pass, high pass, ring pass and band pass filters, which may each be ideal, Gaussian or Butterworth. There is also a fractal mask option.

The other functions in the package build on these base facilities. im_freqflt() transforms an input image to Fourier space, multiplies it by a mask image, and transforms it back again. im_flt_image_freq() will create a mask image of the correct size for you, and call im_freqflt(). im_disp_ps() will call the right combinations of functions to make a displayable power spectrum for an image.

4.2.10 Histograms and LUTs

See Figure 4.12.

VIPS represents histograms and look-up tables in the same way — as images.

They should have either Xsize or Ysize set to 1, and the other dimension set to the number of elements in the table. The table can be of any size, have any band format, and have any number of bands.

Use im_histgr() to find the histogram of an image. Use im_histnD() to find the n-dimensional histogram of an n-band image. Perform operations on histograms with im_histcum(), im_histnorm(), im_histspec(), im_invertlut(). Visualise histograms with im_histplot(). Use a histogram (or LUT) to transform an image with im_maplut(). Build a histogram from scratch with im_identity() or im_identity_ushort().

Use im_lhist⋆() for local histogram equalisation, and im_stdif⋆() for statisticaol differencing. The im_tone_⋆() functions are for operations on the L channel of a LAB image. Other functions are useful combinations of these basic operations.

4.2.11 Morphology

See Figure 4.13.

The morphological functions are used on one-band IM_BANDFMT_UCHAR binary images (images containing only zero and not-zero). They search images for particular patterns of pixels (specified with the mask argument), either adding or removing pixels when they find a match. They are useful for cleaning up images — for example, you might threshold an image, and then use one of the morphological functions to remove all single isolated pixels from the result.

If you combine the morphological operators with the mask rotators (im_rotate_imask45(), for example) and apply them repeatedly, you can achieve very complicated effects: you can thin, prune, fill, open edges, close gaps, and many others. For example, see ‘Fundamentals of Digital Image Processing’ by A. Jain, pp 384-388, Prentice-Hall, 1989 for more ideas.

Beware that VIPS reverses the usual image processing convention, by assuming white objects on a black background.

The mask you give to the morphological functions should contain only the values 0 (for background), 128 (for don’t care) and 255 (for object). The mask must have odd length sides — the origin of the mask is taken to be the centre value. For example, the mask:

applied to an image with im_erode(), will find all black pixels 4-way connected with white pixels. Essentially, im_dilate() sets pixels in the output if any part of the mask matches, whereas im_erode() sets pixels only if all of the mask matches.

The _raw() version of the functions do not add a black border to the output. im_cntlines() and im_profile are occasionally useful for analysing results.

See the boolean operations im_and(), im_or() and im_eor() for analogues of the usual set difference and set union operations.

4.2.12 Mosaicing

See Figure 4.2.12.

These functions are useful for joining many small images together to make one large image. They can cope with unstable contrast, and arbitary sub-image layout, but will not do any geometric correction. The mosaicing functions can be grouped into layers:

The lowest level functions are im_correl(). and im_affine(). im_correl() searches a large image for a small sub-image, returning the position of the best sub-image match. im_affine() performs a general affine transform on an image: that is, any transform in which parallel lines remain parallel.

Next, im_lrmerge() and im_tbmerge() blend two images together left-right or up-down.

Next up are im_lrmosaic() and im_tbmosaic(). These use the two low-level merge operations to join two images given just an approximate overlap as a start point. Optional extra parameters let you do ’balancing’ too: if your images have come from a source where there is no precise control over the exposure (for example, images from a tube camera, or a set of images scanned from photographic sources), im_lrmosaic() and im_tbmosaic() will adjust the contrast of the left image to match the right, the right to the left, or both to some middle value.

The functions im_lrmosaic1() and im_tbmosaic1() are first-order analogues of the basic mosaic functions: they take two tie-points and use them to rotate and scale the right-hand or bottom image before starting to join.

Finally, im_global_balance() can be used to re-balance a mosaic which has been assembled with these functions. It will generally do a better job than the low-level balancer built into im_lrmosaic() and im_tbmosaic(). See the man page. im_remosaic() uses the same techniques, but will reassemble the image from a different set of source images.

4.2.13 CImg functions

See Figure 4.14.

These operations wrap the anisotropic blur function from the CImg library. They are useful for removing noise from images.

4.2.14 Other

See Figure 4.15.

These functions generate various test images. You can combine them with the arithmetic and rotate functions to build more complicated images.

The im_benchmark⋆() operations are for testing the VIPS SMP system.

4.2.15 IO functions

See Figure 4.16.

These functions are related to the image IO system.

4.2.16 Format functions

See Figure 4.17.

These functions convert to and from various image formats. See §2.5 for a nice API over these. VIPS can read more than these formats, see the man page for VipsFormat.

4.2.17 Resample functions

See Figure 4.18.

These functions resample images with various interpolators.