\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}
$ 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)
\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}
$ 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}
$ 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}
$ 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
\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}
$ 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
\end{verbatim}
\caption{Conversion functions}
\label{fg:conversion}
\end{fig2}

\begin{fig2}
\begin{verbatim}
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
\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}
$ 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}
$ 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
\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. 

\begin{fig2}
\begin{verbatim}
$ 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}
$ 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}
$ 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}
$ 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}
$ 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
\end{verbatim}
\caption{Mosaic functions}
\label{fg:mosaicing}
\end{fig2}

\subsection{CImg functions}

See \fref{fg:cimg}.

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

\begin{fig2}
\begin{verbatim}
$ vips --list cimg
im_greyc           - noise-removing filter
im_greyc_mask      - noise-removing filter, with a mask
\end{verbatim}
\caption{CImg functions}
\label{fg:cimg}
\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}
$ 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:io}.

These functions are related to the image IO system. 

\begin{fig2}
\begin{verbatim}
$ 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
\end{verbatim}
\caption{IO functions}
\label{fg:io}
\end{fig2}

\subsection{Format functions}

See \fref{fg:format}.

These functions convert to and from various image formats. See
\pref{sec:format} for a nice API over these. VIPS can read more than these
formats, see the man page for \verb+VipsFormat+.

\begin{fig2}
\begin{verbatim}
$ 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
\end{verbatim}
\caption{Format functions}
\label{fg:format}
\end{fig2}

\subsection{Resample functions}

See \fref{fg:resample}.

These functions resample images with various interpolators.

\begin{fig2}
\begin{verbatim}
$ 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
\end{verbatim}
\caption{Resample functions}
\label{fg:resample}
\end{fig2}