| \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} |
