[prev] [prev-tail] [tail] [up]

### 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.

$ vips list arithmetic
im_abs - absolute value
im_acostra - acos of image (result in degrees)
im_add - add two images
im_asintra - asin of image (result in degrees)
im_atantra - atan of image (result in degrees)
im_avg - average value of image
im_point_bilinear - interpolate value at single point, linearly
im_bandmean - average image bands
im_ceil - round to smallest integal value not less than
im_cmulnorm - multiply two complex images, normalising output
im_costra - cos of image (angles in degrees)
im_cross_phase - phase of cross power spectrum of two complex images
im_deviate - standard deviation of image
im_divide - divide two images
im_exp10tra - 10^pel of image
im_expntra - x^pel of image
im_expntra_vec - [x,y,z]^pel of image
im_exptra - e^pel of image
im_fav4 - average of 4 images
im_floor - round to largest integal value not greater than
im_gadd - calculate a⋆in1 + b⋆in2 + c = outfile
im_invert - photographic negative
im_lintra - calculate a⋆in + b = outfile
im_linreg - pixelwise linear regression
im_lintra_vec - calculate a⋆in + b -> out, a and b vectors
im_litecor - calculate max(white)⋆factor⋆(in/white), if clip == 1
im_log10tra - log10 of image
im_logtra - ln of image
im_max - maximum value of image
im_maxpos - position of maximum value of image
im_maxpos_avg - position of maximum value of image, averaging in case of draw
im_maxpos_vec - position and value of n maxima of image
im_measure - measure averages of a grid of patches
im_min - minimum value of image
im_minpos - position of minimum value of image
im_minpos_vec - position and value of n minima of image
im_multiply - multiply two images
im_powtra - pel^x ofbuildimage
im_powtra_vec - pel^[x,y,z] of image
im_remainder - remainder after integer division
im_remainderconst - remainder after integer division by a constant
im_remainderconst_vec - remainder after integer division by a vector of constants
im_rint - round to nearest integal value
im_sign - unit vector in direction of value
im_sintra - sin of image (angles in degrees)
im_stats - many image statistics in one pass
im_subtract - subtract two images
im_tantra - tan of image (angles in degrees)

Figure 4.1: Arithmetic functions

#### 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.

$ vips list relational
im_blend - use cond image to blend between images in1 and in2
im_equal - two images equal in value
im_equal_vec - image equals doublevec
im_equalconst - image equals const
im_ifthenelse - use cond image to choose pels from image in1 or in2
im_less - in1 less than in2 in value
im_less_vec - in less than doublevec
im_lessconst - in less than const
im_lesseq - in1 less than or equal to in2 in value
im_lesseq_vec - in less than or equal to doublevec
im_lesseqconst - in less than or equal to const
im_more - in1 more than in2 in value
im_more_vec - in more than doublevec
im_moreconst - in more than const
im_moreeq - in1 more than or equal to in2 in value
im_moreeq_vec - in more than or equal to doublevec
im_moreeqconst - in more than or equal to const
im_notequal - two images not equal in value
im_notequal_vec - image does not equal doublevec
im_notequalconst - image does not equal const

Figure 4.2: Relational functions

#### 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().

$ vips list boolean
im_andimage - bitwise and of two images
im_andimageconst - bitwise and of an image with a constant
im_andimage_vec - bitwise and of an image with a vector constant
im_orimage - bitwise or of two images
im_orimageconst - bitwise or of an image with a constant
im_orimage_vec - bitwise or of an image with a vector constant
im_eorimage - bitwise eor of two images
im_eorimageconst - bitwise eor of an image with a constant
im_eorimage_vec - bitwise eor of an image with a vector constant
im_shiftleft - shift integer image n bits to left
im_shiftright - shift integer image n bits to right

Figure 4.3: Boolean functions

#### 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.

Figure 4.4: VIPS colour space conversion

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.

$ vips list colour
im_LCh2Lab - convert LCh to Lab
im_LCh2UCS - convert LCh to UCS
im_Lab2LCh - convert Lab to LCh
im_Lab2LabQ - convert Lab to LabQ
im_Lab2LabS - convert Lab to LabS
im_Lab2UCS - convert Lab to UCS
im_Lab2XYZ - convert D65 Lab to XYZ
im_Lab2XYZ_temp - convert Lab to XYZ, with a specified colour temperature
im_Lab2disp - convert Lab to displayable
im_LabQ2LabS - convert LabQ to LabS
im_LabQ2Lab - convert LabQ to Lab
im_LabQ2XYZ - convert LabQ to XYZ
im_LabQ2disp - convert LabQ to displayable
im_LabS2LabQ - convert LabS to LabQ
im_LabS2Lab - convert LabS to Lab
im_UCS2LCh - convert UCS to LCh
im_UCS2Lab - convert UCS to Lab
im_UCS2XYZ - convert UCS to XYZ
im_XYZ2Lab - convert D65 XYZ to Lab
im_XYZ2Lab_temp - convert XYZ to Lab, with a specified colour temperature
im_XYZ2UCS - convert XYZ to UCS
im_XYZ2Yxy - convert XYZ to Yxy
im_XYZ2disp - convert XYZ to displayble
im_XYZ2sRGB - convert XYZ to sRGB
im_Yxy2XYZ - convert Yxy to XYZ
im_dE00_fromLab - calculate delta-E CIE2000 for two Lab images
im_dECMC_fromLab - calculate delta-E CMC(1:1) for two Lab images
im_dECMC_fromdisp - calculate delta-E CMC(1:1) for two displayable images
im_dE_fromLab - calculate delta-E for two Lab images
im_dE_fromXYZ - calculate delta-E for two XYZ images
im_dE_fromdisp - calculate delta-E for two displayable images
im_disp2Lab - convert displayable to Lab
im_disp2XYZ - convert displayable to XYZ
im_float2rad - convert float to Radiance packed
im_icc_ac2rc - convert LAB from AC to RC using an ICC profile
im_icc_export - convert a float LAB to an 8-bit device image with an ICC profile
im_icc_export_depth - convert a float LAB to device space with an ICC profile
im_icc_import - convert a device image to float LAB with an ICC profile
im_icc_import_embedded - convert a device image to float LAB using the embedded profile
im_icc_present - test for presence of ICC library
im_icc_transform - convert between two device images with a pair of ICC profiles
im_lab_morph - morph colourspace of a LAB image
im_rad2float - convert Radiance packed to float
im_sRGB2XYZ - convert sRGB to XYZ

Figure 4.5: Colour functions

#### 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.

$ vips list conversion
im_bandjoin - bandwise join of two images
im_bernd - extract from pyramid as jpeg
im_black - generate black image
im_c2amph - convert real and imaginary to phase and amplitude
im_c2imag - extract imaginary part of complex image
im_c2ps - find power spectrum of complex image
im_c2real - extract real part of complex image
im_c2rect - convert phase and amplitude to real and imaginary
im_clip2c - convert to signed 8-bit integer
im_clip2cm - convert to complex
im_clip2d - convert to double-precision float
im_clip2dcm - convert to double complex
im_clip2f - convert to single-precision float
im_clip2fmt - convert image format to ofmt
im_clip2i - convert to signed 32-bit integer
im_clip2s - convert to signed 16-bit integer
im_clip2ui - convert to unsigned 32-bit integer
im_clip2us - convert to unsigned 16-bit integer
im_clip - convert to unsigned 8-bit integer
im_copy - copy image
im_copy_morph - copy image, setting pixel layout
im_copy_swap - copy image, swapping byte order
im_copy_set - copy image, setting informational fields
im_copy_set_meta - copy image, setting a meta field
im_extract_area - extract area
im_extract_areabands - extract area and bands
im_extract_band - extract band
im_extract_bands - extract several bands
im_extract - extract area/band
im_falsecolour - turn luminance changes into chrominance changes
im_fliphor - flip image left-right
im_flipver - flip image top-bottom
im_gbandjoin - bandwise join of many images
im_grid - chop a tall thin image into a grid of images
im_insert - insert sub-image into main image at position
im_insert_noexpand - insert sub-image into main image at position, no expansion
im_lrjoin - join two images left-right
im_mask2vips - convert DOUBLEMASK to VIPS image
im_msb - convert to uchar by discarding bits
im_msb_band - convert to single band uchar by discarding bits
im_print - print string to stdout
im_recomb - linear recombination with mask
im_replicate - replicate an image horizontally and vertically
im_ri2c - join two non-complex images to form complex

Figure 4.6: Conversion functions

im_rot180 - rotate image 180 degrees
im_rot270 - rotate image 270 degrees clockwise
im_rot90 - rotate image 90 degrees clockwise
im_scale - scale image linearly to fit range 0-255
im_scaleps - logarithmic scale of image to fit range 0-255
im_rightshift_size - decrease size by a power-of-two factor
im_slice - slice an image using two thresholds
im_subsample - subsample image by integer factors
im_system - run command on image
im_tbjoin - join two images top-bottom
im_text - generate text image
im_thresh - slice an image at a threshold
im_vips2mask - convert VIPS image to DOUBLEMASK
im_wrap - shift image origin, wrapping at sides
im_zoom - simple zoom of an image by integer factors

Figure 4.7: Conversion functions (cont.)

#### 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:

4 4
1 0 0 0
0 1 0 0
0 0 1 0
0 0 0 1

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

3 3 9 0
1 1 1
1 1 1
1 1 1

(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.

$ vips list matrix
im_matcat - append matrix in2 to the end of matrix in1
im_matinv - invert matrix
im_matmul - multiply matrix in1 by matrix in2
im_mattrn - transpose matrix

Figure 4.8: Matrix functions

#### 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.

$ vips list convolution
im_addgnoise - add gaussian noise with mean 0 and std. dev. sigma
im_compass - convolve with 8-way rotating integer mask
im_contrast_surface - find high-contrast points in an image
im_contrast_surface_raw - find high-contrast points in an image
im_conv - convolve
im_conv_raw - convolve, no border
im_convf - convolve, with DOUBLEMASK
im_convf_raw - convolve, with DOUBLEMASK, no border
im_convsep - seperable convolution
im_convsep_raw - seperable convolution, no border
im_convsepf - seperable convolution, with DOUBLEMASK
im_convsepf_raw - seperable convolution, with DOUBLEMASK, no border
im_convsub - convolve uchar to uchar, sub-sampling by xskip, yskip
im_dmask_xsize - horizontal size of a doublemask
im_dmask_ysize - vertical size of a doublemask
im_embed - embed in within a set of borders
im_fastcor - fast correlate in2 within in1
im_fastcor_raw - fast correlate in2 within in1, no border
im_gauss_dmask - generate gaussian DOUBLEMASK
im_gauss_imask - generate gaussian INTMASK
im_gauss_imask_sep - generate separable gaussian INTMASK
im_gaussnoise - generate image of gaussian noise with specified statistics
im_grad_x - horizontal difference image
im_grad_y - vertical difference image
im_gradcor - non-normalised correlation of gradient of in2 within in1
im_gradcor_raw - non-normalised correlation of gradient of in2 within in1, no padding
im_gradient - convolve with 2-way rotating mask
im_imask_xsize - horizontal size of an intmask
im_imask_ysize - vertical size of an intmask
im_rank_image - point-wise pixel rank
im_lindetect - convolve with 4-way rotating mask
im_log_dmask - generate laplacian of gaussian DOUBLEMASK
im_log_imask - generate laplacian of gaussian INTMASK
im_maxvalue - point-wise maximum value
im_mpercent - find threshold above which there are percent values
im_phasecor_fft - non-normalised correlation of gradient of in2 within in1
im_rank - rank filter nth element of xsize/ysize window
im_rank_raw - rank filter nth element of xsize/ysize window, no border
im_read_dmask - read matrix of double from file
im_resize_linear - resize to X by Y pixels with linear interpolation
im_rotate_dmask45 - rotate DOUBLEMASK clockwise by 45 degrees
im_rotate_dmask90 - rotate DOUBLEMASK clockwise by 90 degrees
im_rotate_imask45 - rotate INTMASK clockwise by 45 degrees
im_rotate_imask90 - rotate INTMASK clockwise by 90 degrees
im_sharpen - sharpen high frequencies of L channel of LabQ
im_shrink - shrink image by xfac, yfac times
im_spcor - normalised correlation of in2 within in1
im_spcor_raw - normalised correlation of in2 within in1, no black padding
im_stretch3 - stretch 3%, sub-pixel displace by xdisp/ydisp
im_zerox - find +ve or -ve zero crossings in image

Figure 4.9: Convolution functions

#### 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.

$ vips list inplace
im_circle - plot circle on image
im_flood_blob_copy - flood while pixel == start pixel
im_insertplace - draw image sub inside image main at position (x,y)
im_line - draw line between points (x1,y1) and (x2,y2)
im_lineset - draw line between points (x1,y1) and (x2,y2)

Figure 4.10: In-place operations

#### 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.

$ vips list freq_filt
im_create_fmask - create frequency domain filter mask
im_disp_ps - make displayable power spectrum
im_flt_image_freq - frequency domain filter image
im_fractsurf - generate a fractal surface of given dimension
im_freqflt - frequency-domain filter of in with mask
im_fwfft - forward fast-fourier transform
im_rotquad - rotate image quadrants to move origin to centre
im_invfft - inverse fast-fourier transform
im_invfftr - real part of inverse fast-fourier transform

Figure 4.11: Fourier functions

#### 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.

$ vips list histograms_lut
im_gammacorrect - gamma-correct image
im_heq - histogram-equalise image
im_hist - find and graph histogram of image
im_histcum - turn histogram to cumulative histogram
im_histeq - form histogram equalistion LUT
im_histgr - find histogram of image
im_histnD - find 1D, 2D or 3D histogram of image
im_histnorm - form normalised histogram
im_histplot - plot graph of histogram
im_histspec - find histogram which will make pdf of in match ref
im_hsp - match stats of in to stats of ref
im_identity - generate identity histogram
im_identity_ushort - generate ushort identity histogram
im_ismonotonic - test LUT for monotonicity
im_lhisteq - local histogram equalisation
im_lhisteq_raw - local histogram equalisation, no border
im_invertlut - generate correction table from set of measures
im_buildlut - generate LUT table from set of x/y positions
im_maplut - map image through LUT
im_project - find horizontal and vertical projections of an image
im_stdif - statistical differencing
im_stdif_raw - statistical differencing, no border
im_tone_analyse - analyse in and create LUT for tone adjustment
im_tone_build - create LUT for tone adjustment of LabS images
im_tone_build_range - create LUT for tone adjustment
im_tone_map - map L channel of LabS or LabQ image through LUT

Figure 4.12: Histogram/LUT functions

#### 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:

3 3
128 255 128
255 0 255
128 255 128

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.

$ vips list morphology
im_cntlines - count horizontal or vertical lines
im_dilate - dilate image with mask, adding a black border
im_dilate_raw - dilate image with mask
im_erode - erode image with mask, adding a black border
im_erode_raw - erode image with mask
im_profile - find first horizontal/vertical edge

Figure 4.13: Morphological functions

#### 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.

$ vips list mosaicing
im_align_bands - align the bands of an image
im_correl - search area around sec for match for area around ref
im__find_lroverlap - search for left-right overlap of ref and sec
im__find_tboverlap - search for top-bottom overlap of ref and sec
im_global_balance - automatically rebuild mosaic with balancing
im_global_balancef - automatically rebuild mosaic with balancing, float output
im_lrmerge - left-right merge of in1 and in2
im_lrmerge1 - first-order left-right merge of ref and sec
im_lrmosaic - left-right mosaic of ref and sec
im_lrmosaic1 - first-order left-right mosaic of ref and sec
im_match_linear - resample ref so that tie-points match
im_match_linear_search - search sec, then resample so that tie-points match
im_maxpos_subpel - subpixel position of maximum of (phase correlation) image
im_remosaic - automatically rebuild mosaic with new files
im_tbmerge - top-bottom merge of in1 and in2
im_tbmerge1 - first-order top-bottom merge of in1 and in2
im_tbmosaic - top-bottom mosaic of in1 and in2
im_tbmosaic1 - first-order top-bottom mosaic of ref and sec

captionMosaic functions

#### 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.

$ vips list cimg
im_greyc - noise-removing filter
im_greyc_mask - noise-removing filter, with a mask

Figure 4.14: CImg functions

#### 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.

$ vips list other
im_benchmark - do something complicated for testing
im_benchmark2 - do something complicated for testing
im_benchmarkn - do something complicated for testing
im_eye - generate IM_BANDFMT_UCHAR [0,255] frequency/amplitude image
im_grey - generate IM_BANDFMT_UCHAR [0,255] grey scale image
im_feye - generate IM_BANDFMT_FLOAT [-1,1] frequency/amplitude image
im_fgrey - generate IM_BANDFMT_FLOAT [0,1] grey scale image
im_fzone - generate IM_BANDFMT_FLOAT [-1,1] zone plate image
im_make_xy - generate image with pixel value equal to coordinate
im_zone - generate IM_BANDFMT_UCHAR [0,255] zone plate image

Figure 4.15: Other functions

#### 4.2.15 IO functions

See Figure 4.16.

These functions are related to the image IO system.

$ vips list iofuncs
im_binfile - open a headerless binary file
im_cache - cache results of an operation
im_guess_prefix - guess install area
im_guess_libdir - guess library area
im_header_get_type - return field type
im_header_int - extract int fields from header
im_header_double - extract double fields from header
im_header_string - extract string fields from header
im_version - VIPS version number
im_version_string - VIPS version string

Figure 4.16: IO functions

#### 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.

$ vips list format
im_csv2vips - read a file in csv format
im_jpeg2vips - convert from jpeg
im_magick2vips - load file with libMagick
im_png2vips - convert PNG file to VIPS image
im_exr2vips - convert an OpenEXR file to VIPS
im_ppm2vips - read a file in pbm/pgm/ppm format
im_analyze2vips - read a file in analyze format
im_tiff2vips - convert TIFF file to VIPS image
im_vips2csv - write an image in csv format
im_vips2jpeg - convert to jpeg
im_vips2mimejpeg - convert to jpeg as mime type on stdout
im_vips2png - convert VIPS image to PNG file
im_vips2ppm - write a file in pbm/pgm/ppm format
im_vips2tiff - convert VIPS image to TIFF file

Figure 4.17: Format functions

#### 4.2.17 Resample functions

See Figure 4.18.

These functions resample images with various interpolators.

$ vips list resample
im_affine - affine transform
im_affinei - affine transform
im_affinei_all - affine transform of whole image
im_similarity_area - output area xywh of similarity transformation
im_similarity - similarity transformation

Figure 4.18: Resample functions

[prev] [prev-tail] [front] [up]