\section{VIPS packages} \mylabel{sec:packages} \subsection{Arithmetic} See \fref{fg:arithmetic}. 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 \verb+IM_BANDFMT_UCHAR+ images together, for example, produces a \verb+IM_BANDFMT_USHORT+ image, and taking the \verb+im_costra()+ of a \verb+IM_BANDFMT_USHORT+ image produces a \verb+IM_BANDFMT_FLOAT+ image. The details of the type conversions are in the manual pages. \begin{fig2} \begin{verbatim} john% 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_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_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 in image im_maxpos_avg - position of maximum, averaging in case of draw im_measure - measure averages of a grid of patches im_min - minimum value of image im_minpos - position of minimum value 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 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) \end{verbatim} \caption{Arithmetic functions} \label{fg:arithmetic} \end{fig2} \subsection{Relational} See \fref{fg:relational}. 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 \verb+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 \verb+im_max()+ (or \verb+im_min()+) to find out if a condition is true (or false) for a whole image. \begin{fig2} \begin{verbatim} john% 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 \end{verbatim} \caption{Relational functions} \label{fg:relational} \end{fig2} \subsection{Boolean} See \fref{fg:boolean}. The boolean functions perform boolean arithmetic on pairs of \verb+IM_BANDFMT_UCHAR+ images. They are useful for combining the results of the relational and morphological functions. You can use \verb+im_eorconst()+ with 255 as \verb+im_not()+. \begin{fig2} \begin{verbatim} john% 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 \end{verbatim} \caption{Boolean functions} \label{fg:boolean} \end{fig2} \subsection{Colour} \label{sec:colour} See \fref{fg:colour}. The colour functions can be divided into two main types. First, functions to transform images between the different colour spaces supported by VIPS: \verb+RGB+ (also referred to as \verb+disp+), \verb+sRGB+, \verb+XYZ+, \verb+Yxy+, \verb+Lab+, \verb+LabQ+, \verb+LabS+, \verb+LCh+ and \verb+UCS+), and second, functions for calculating colour difference metrics. Figure~\ref{fg:convert} shows how the VIPS colour spaces interconvert. \begin{fig2} \figw{5in}{interconvert.png} \caption{VIPS colour space conversion} \label{fg:convert} \end{fig2} The colour spaces supported by VIPS are: \begin{description} \item[\texttt{LabQ}] This is the principal VIPS colorimetric storage format. See the man page for \verb+im_LabQ2Lab()+ for an explanation. You cannot perform calculations on \verb+LabQ+ images. They are for storage only. Also refered to as \verb+LABPACK+. \item[\texttt{LabS}] This format represents coordinates in \cielab{} space as a three- band \verb+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. \item[\texttt{Lab}] \verb+Lab+ colourspace represents \cielab{} colour values with a three-band \verb+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. \item[\texttt{XYZ}] \ciexyz{} colour space represented as a three-band \verb+IM_BANDFMT_FLOAT+ image. \item[\texttt{XYZ}] \cieyxy{} colour space represented as a three-band \verb+IM_BANDFMT_FLOAT+ image. \item[\texttt{RGB}] (also refered to as \verb+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 \verb+RGB+, then turn it to TIFF with \verb+im_vips2tiff()+. You need to supply a structure which characterises your display. See the manual page for \verb+im_col_XYZ2rgb()+ for hints on these guys. VIPS also supports \verb+sRGB+. This is a version of RGB with a carefully defined and standard conversion from XYZ. See: \begin{verbatim} http://www.color.org/ \end{verbatim} \item[\texttt{LCh}] Like \verb+Lab+, but rectangular $ab$ coordinates are replaced with polar $Ch$ (Chroma and hue) coordinates. Hue angles are expressed in degrees. \item[\texttt{UCS}] A colour space based on the CMC(1:1) colour difference measurement. This is a highly uniform colour space, much better than \cielab{} for expressing small differences. Conversions to and from \verb+UCS+ are extremely slow. \end{description} All VIPS colourspaces assume a D65 illuminant. The colour-difference functions calculate either $\Delta{}E$ \cielab{} (1976 or 2000) or $\Delta{}E$ CMC(1:1) on two images in \verb+Lab+, \verb+XYZ+ or \verb+disp+ colour space. \begin{fig2} \begin{verbatim} example% 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_icc_ac2rc - convert LAB from AC to RC using a profile im_icc_export - convert LAB to 8-bit device with a profile im_icc_export_depth - convert LAB to device with a profile im_icc_import - convert device to LAB with a profile im_icc_import_embedded - convert device to 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 profiles im_lab_morph - morph colourspace of a LAB image im_sRGB2XYZ - convert sRGB to XYZ \end{verbatim} \caption{Colour functions} \label{fg:colour} \end{fig2} \subsection{Conversion} See \fref{fg:conversion}. These functions may be split into three broad groups: functions which convert between the VIPS numeric formats (\verb+im_clip2fmt()+, for example, converts an image of any type to the specified \verb+IM_BANDFMT+), functions supporting complex arithmetic (\verb+im_c2amph()+, for example, converts a complex image from rectangular to polar co ordinates) and functions which perform some simple geometric conversion (\verb+im_extract()+ forms a sub-image). \verb+gbandjoin+ and the C function \verb+im_gbandjoin()+ will do a bandwise join of many images at the same time. See the manual pages. \begin{fig2} \begin{verbatim} example% 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_csv2vips - read a file in csv format 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_jpeg2vips - convert from jpeg im_lrjoin - join two images left-right im_magick2vips - load file with libMagick 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_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_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 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 \end{verbatim} \caption{Conversion functions} \label{fg:conversion} \end{fig2} \begin{fig2} \begin{verbatim} 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_tiff2vips - convert TIFF file to VIPS image im_vips2csv - write an image in csv format im_vips2jpeg - convert to jpeg im_vips2mask - convert VIPS image to DOUBLEMASK 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 im_zoom - simple zoom of an image by integer factors \end{verbatim} \caption{Conversion functions (cont.)} \end{fig2} \subsection{Matricies} See \fref{fg:matricies}. VIPS uses matricies for morphological operations, for convolutions, and for some colour-space conversions. There are two types of matrix: integer (\verb+INTMASK+) and double precision floating point (\verb+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: \[ result = {value \over scale} + offset \] 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: \begin{verbatim} 4 4 1 0 0 0 0 1 0 0 0 0 1 0 0 0 0 1 \end{verbatim} And a 3 by 3 mask for block averaging with convolution might be stored as: \begin{verbatim} 3 3 9 0 1 1 1 1 1 1 1 1 1 \end{verbatim} \noindent (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 \verb+INTMASK+ and \verb+DOUBLEMASK+ matricies. However, masks containing floating-point values (such as the output of \verb+im_matinv()+) can only be used as arguments to functions expecting \verb+DOUBLEMASK+s. A set of functions for mask input and output are also available for C-programmers --- see the manual pages for \verb+im_read_dmask()+. For other matrix functions, see also the convolution sections and the arithmetic sections. \begin{fig2} \begin{verbatim} example% 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 \end{verbatim} \caption{Matrix functions} \label{fg:matricies} \end{fig2} \subsection{Convolution} See \fref{fg:convolution}. The functions available in the convolution package can be split into five main groups. First, are the convolution functions. The most useful function is \verb+im_conv()+ which will convolve any non-complex type with an \verb+INTMASK+ matrix. The output image will have the same size, type, and number of bands as the input image. Of the other \verb+im_conv()+ functions, functions whose name ends in \verb+_raw+ do not add a black border around the output image, functions ending in \verb+f+ use a \verb+DOUBLEMASK+ matrix and write float (or double) output, and functions containing \verb+sep+ are for seperable convolutions. \verb+im_compass()+, \verb+im_lindetect()+ and \verb+im_gradient()+ convolve with rotating masks. \verb+im_embed()+ is used by the convolution functions to add the border to the output. Next, are the build functions. \verb+im_gauss_*mask()+ and its ilk generate gaussian masks, \verb+im_log_*mask()+ generate logs of Laplacians. \verb+im_addgnoise()+ and \verb+im_gaussnoise()+ create or add gaussian noise to an image. Two functions do correlation: \verb+im_fastcor()+ does a quick and dirty correlation, \verb+im_spcor()+ calculates true spatial correlation, and is rather slow. Some functions are provided for analysing images: \verb+im_zerox()+ counts zero-crossing points in an image, \verb+im_mpercent()+ finds a threshold that will isolate a percentage of points in an image. Finally, \verb+im_resize_linear()+ and \verb+im_shrink()+ do as you would expect. \begin{fig2} \begin{verbatim} example% 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_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_gaussnoise - generate image of gaussian noise with specified statistics im_gradient - convolve with 2-way rotating mask 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_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_spcor2 - normalised correlation of in2 within in1 im_spcor2_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 IM_BANDFMT_INT image \end{verbatim} \caption{Convolution functions} \label{fg:convolution} \end{fig2} \subsection{In-place operations} \label{sec:inplace} See \fref{fg:inplace}. A few of the in-place operations are available from the command-line. Most are not. More will be added. \begin{fig2} \begin{verbatim} example% 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) \end{verbatim} \caption{In-place operations} \label{fg:inplace} \end{fig2} \subsection{Frequency filtering} See \fref{fg:freq}. The basic Fourier functions are \verb+im_fwfft()+ and \verb+im_invfft()+, which calculate the fast-fourier transform and inverse transform of an image. Also \verb+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 \verb+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 \verb+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. \verb+im_freqflt()+ transforms an input image to Fourier space, multiplies it by a mask image, and transforms it back again. \verb+im_flt_image_freq()+ will create a mask image of the correct size for you, and call \verb+im_freqflt()+. \verb+im_disp_ps()+ will call the right combinations of functions to make a displayable power spectrum for an image. \begin{fig2} \begin{verbatim} example% 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 \end{verbatim} \caption{Fourier functions} \label{fg:freq} \end{fig2} \subsection{Histograms and LUTs} See \fref{fg:hist}. VIPS represents histograms and look-up tables in the same way --- as images. They should have either \verb+Xsize+ or \verb+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 \verb+im_histgr()+ to find the histogram of an image. Use \verb+im_histnD()+ to find the n-dimensional histogram of an n-band image. Perform operations on histograms with \verb+im_histcum()+, \verb+im_histnorm()+, \verb+im_histspec()+, \verb+im_invertlut()+. Visualise histograms with \verb+im_histplot()+. Use a histogram (or LUT) to transform an image with \verb+im_maplut()+. Build a histogram from scratch with \verb+im_identity()+ or \verb+im_identity_ushort()+. Use \verb+im_lhist*()+ for local histogram equalisation, and \verb+im_stdif*()+ for statisticaol differencing. The \verb+im_tone_*()+ functions are for operations on the L channel of a LAB image. Other functions are useful combinations of these basic operations. \begin{fig2} \begin{verbatim} example% 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 \end{verbatim} \caption{Histogram/LUT functions} \label{fg:hist} \end{fig2} \subsection{Morphology} See \fref{fg:morph}. The morphological functions are used on one-band \verb+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 (\verb+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: \begin{verbatim} 3 3 128 255 128 255 0 255 128 255 128 \end{verbatim} \noindent applied to an image with \verb+im_erode()+, will find all black pixels 4-way connected with white pixels. Essentially, \verb+im_dilate()+ sets pixels in the output if any part of the mask matches, whereas \verb+im_erode()+ sets pixels only if all of the mask matches. The \verb+_raw()+ version of the functions do not add a black border to the output. \verb+im_cntlines()+ and \verb+im_profile+ are occasionally useful for analysing results. See the boolean operations \verb+im_and()+, \verb+im_or()+ and \verb+im_eor()+ for analogues of the usual set difference and set union operations. \begin{fig2} \begin{verbatim} example% 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 \end{verbatim} \caption{Morphological functions} \label{fg:morph} \end{fig2} \subsection{Mosaicing} See \fref{fg:mosaicing}. 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 \verb+im_correl()+. and \verb+im_affine()+. \verb+im_correl()+ searches a large image for a small sub-image, returning the position of the best sub-image match. \verb+im_affine()+ performs a general affine transform on an image: that is, any transform in which parallel lines remain parallel. Next, \verb+im_lrmerge()+ and \verb+im_tbmerge()+ blend two images together left-right or up-down. Next up are \verb+im_lrmosaic()+ and \verb+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), \verb+im_lrmosaic()+ and \verb+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 \verb+im_lrmosaic1()+ and \verb+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, \verb+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 \verb+im_lrmosaic()+ and \verb+im_tbmosaic()+. See the man page. \verb+im_remosaic()+ uses the same techniques, but will reassemble the image from a different set of source images. \begin{fig2} \begin{verbatim} example% vips --list mosaicing im_affine - affine transform 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_remosaic - automatically rebuild mosaic with new files im_similarity_area - output area xywh of similarity transformation im_similarity - similarity transformation 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 \end{verbatim} \caption{Mosaic functions} \label{fg:mosaicing} \end{fig2} \subsection{Other} See \fref{fg:other}. These functions generate various test images. You can combine them with the arithmetic and rotate functions to build more complicated images. The \verb+im_benchmark*()+ operations are for testing the VIPS SMP system. \begin{fig2} \begin{verbatim} example% 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 \end{verbatim} \caption{Other functions} \label{fg:other} \end{fig2} \subsection{IO functions} See \fref{fg:other}. These functions are related to the image IO system. \begin{fig2} \begin{verbatim} example% vips --list iofuncs im_binfile - open a headerless binary file im_cache - cache results of an operation im_guess_prefix - guess install 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 \end{verbatim} \caption{IO functions} \label{fg:io} \end{fig2}