Class VIPS::Image
In: ext/image.c
lib/vips/reader.rb
lib/vips/writer.rb
Parent: Object

Image objects reference in-memory images. All operations that manipulate and return an image will simply add the operation to the pipeline and return an image that references the image after the operation. The actual operation is not performed until the image is written to a file or to a string.

Methods

&   *   +   -   /   <<   >>   []   ^   abs   acos   add   addgnoise   affinei   affinei_resize   align_bands   asin   atan   avg   bandjoin   bandmean   black   blend   buildlut   c2amph   c2imag   c2real   c2rect   ceil   clip2fmt   cntlines_h   cntlines_v   coding   compass   contrast_surface   conv   convsep   copy_file   copy_native   copy_swap   correl   cos   cross_phase   csv   csv   data   de00_from_lab   de_from_lab   de_from_xyz   decmc_from_lab   deviate   dilate   disp_ps   divide   dup   each_pixel   embed   equal   erode   expn   exr   extract_area   extract_band   falsecolour   fastcor   filename   fliphor   flipver   float_to_rad   floor   fmask_butterworth_bandpass   fmask_butterworth_bandreject   fmask_butterworth_highpass   fmask_butterworth_lowpass   fmask_butterworth_ringpass   fmask_butterworth_ringreject   fmask_fractal_flt   fmask_gauss_bandpass   fmask_gauss_bandreject   fmask_gauss_highpass   fmask_gauss_lowpass   fmask_gauss_ringpass   fmask_gauss_ringreject   fmask_ideal_bandpass   fmask_ideal_bandreject   fmask_ideal_highpass   fmask_ideal_lowpass   fmask_ideal_ringpass   fmask_ideal_ringreject   fractsurf   freqflt   fwfft   gammacorrect   gaussnoise   global_balance   global_balancef   grad_x   grad_y   gradcor   gradient   grid   heq   hist   hist_indexed   histcum   histeq   histgr   histnd   histnorm   histplot   histspec   hsp   icc_ac2rc   icc_export_depth   icc_import   icc_import_embedded   icc_transform   identity   identity_ushort   ifthenelse   im_lab_morph   insert   insert_noexpand   invert   invertlut   invfft   invfftr   jpeg   jpeg   kill   lab_to_labq   lab_to_labs   lab_to_lch   lab_to_ucs   lab_to_xyz   lab_to_xyz_temp   label_regions   labq_to_lab   labq_to_labs   labq_to_xyz   labs_to_lab   labs_to_labq   lch_to_lab   lch_to_ucs   less   lesseq   lhisteq   lin   lindetect   linreg   log   log10   lrjoin   lrmerge   lrmerge1   lrmosaic   lrmosaic1   magick   maplut   match_linear   match_linear_search   max   maxpos   maxpos_avg   maxpos_subpel   maxvalue   measure_area   min   minpos   monotonic?   more   moreeq   mpercent   mpercent_hist   msb   multiply   new   notequal   phasecor_fft   png   png   point   pow   ppm   ppm   profile_h   profile_v   project   rad_to_float   rank   rank_image   recomb   remainder   replicate   ri2c   rightshift_size   rint   rot180   rot270   rot90   rotquad   scale   scaleps   sharpen   shrink   sign   sin   spcor   srgb_to_xyz   stats   stdif   stretch3   subsample   subtract   tan   tbjoin   tbmerge   tbmerge1   tbmosaic   tbmosaic1   text   tiff   tiff   to_mask   tone_analyze   tone_build   tone_build_range   ucs_to_lab   ucs_to_lch   ucs_to_xyz   vips   vips   vtype   wrap   write   xyz_to_lab   xyz_to_lab_temp   xyz_to_srgb   xyz_to_ucs   xyz_to_yxy   yxy_to_xyz   zerox_neg   zerox_pos   zoom   |  

Included Modules

VIPS::Header

Public Class methods

Make a black unsigned char image of a specified size.

This operation builds a lookup table from a set of points. Intermediate values are generated by piecewise linear interpolation.

For example, consider this 2 x 2 matrix of (x, y) coordinates:

  input = [
    [  0,   0],
    [255, 100]
  ]
  im = Image.invertlut(input)

We then generate an image with the following pixel values:

  im[0, 0] # => 0
  im[0, 1] # => 0.4
  # ...
  im[0, 255] # => 100

This is then written as the output image, with the left column giving the index in the image to place the value.

The (x, y) points don‘t need to be sorted: we do that. You can have several Ys, each becomes a band in the output LUT. You don‘t need to start at zero, any integer will do, including negatives.

Load a csv file straight to a VIPS Image.

Load an exr file straight to a VIPS Image.

This mask is handy for filtering images of gaussian noise in order to create surfaces of a given fractal dimension. @fractal_dimension should be between 2 and 3.

This operation creates a one-band float image of the size x by y. The image must be square, and the sides must be a power of two. The image has values in the range [0, 1] and is typically used for multiplying against frequency domain images to filter them.

All masks are created with the DC component at (0, 0), so you might want to rotate the quadrants with im_rotquad() before viewing. The DC pixel always has the value 1.0.

Unless noted below, all parameters are expressed as percentages, scaled to [0, 1].

  • High-pass, low-pass masks: A high pass filter mask filters the low frequencies while allowing the high frequencies to get through. The reverse happens with a low pass filter mask.
  • Ring-pass, ring-reject masks: A ring filter passes or rejects a range of frequencies. The range is specified by the frequency_cutoff and the width.
  • Band-pass, band-reject masks: These masks are used to pass or remove spatial frequencies around a given frequency. The position of the frequency to pass or remove is given by frequency_cutoffx and frequency_cutoffy. The size of the region around the point is given by radius.
  • Ideal filters: These filters pass or reject frequencies with a sharp cutoff at the transition.
  • Butterworth filters: These filters use a Butterworth function to separate the frequencies (see Gonzalez and Wintz, Digital Image Processing, 1987). The shape of the curve is controlled by order: higher values give a sharper transition.
  • Gaussian filters: These filters have a smooth Gaussian shape, controlled by amplitude_cutoff.

Generate an image of size size and fractal dimension frd. The dimension should be between 2 and 3.

Make a one band float image of gaussian noise with the specified distribution. The noise distribution is created by averaging 12 random numbers with the appropriate weights.

Creates a image file with Xsize=256, Ysize=1, Bands=bands, BandFmt= :UCHAR, Type=:HISTOGRAM.

The created image consist of a bands-bands linear lut and is the basis for building up look-up tables.

As Image.identity, but make a ushort LUT. ushort LUTs can be up to 65536 elements - size is the number of elements required.

The created image consist of a bands-bands linear lut and is the basis for building up look-up tables.

Given a input of target values and real values, generate a LUT which will map reals to targets. Handy for linearising images from measurements of a colour chart. All values in [0,1]. Piecewise linear interpolation, extrapolate head and tail to 0 and 1.

Eg. input like this:

 input = [
   [0.2, 0.2, 0.3, 0.1],
   [0.2, 0.4, 0.4, 0.2],
   [0.7, 0.5, 0.6, 0.3]
 ]

Means a patch with 10% reflectance produces an image with 20% in channel 1, 30% in channel 2, and 10% in channel 3, and so on.

Inputs don‘t need to be sorted (we do that). Generate any precision LUT, typically you might ask for 256 elements.

It won‘t work too well for non-monotonic camera responses.

input can be an array or a Mask object.

Load a jpeg file straight to a VIPS Image.

Function to find perform pixelwise linear regression on an array of single band images. The output is a seven-band double image.

x is the position of each image (pixel value is Y).

Load a file straight to a VIPS Image using the magick library.

Load any file straight to a VIPS Image. VIPS will determine the format based on the file extension. If the extension is not recognized, VIPS will look at the file signature.

Load a png file straight to a VIPS Image.

Load a ppm file straight to a VIPS Image.

Draw the string text to an image. @out is a one-band 8-bit unsigned char image, with 0 for no text and 255 for text. Values inbetween are used for anti-aliasing.

text is the text to render as a UTF-8 string. It can contain Pango markup, for example "&lt;i&gt;The&lt;/i&gt;Guardian".

font is the font to render with, selected by fontconfig. Examples might be "sans 12" or perhaps "bitstream charter bold 10".

width is the maximum number of pixels across to draw within. If the generated text is wider than this, it will wrap to a new line. In this case, alignment can be used to set the alignment style for multi-line text. 0 means left-align, 1 centre, 2 right-align.

dpi sets the resolution to render at. "sans 12" at 72 dpi draws characters approximately 12 pixels high.

Load a tiff file straight to a VIPS Image.

As Image#tone_build_range, but set 32767 and 32767 as values for in_max and out_max. This makes a curve suitable for correcting LABS images, the most common case.

Generates a tone curve for the adjustment of image levels. It is mostly designed for adjusting the L* part of a LAB image in way suitable for print work, but you can use it for other things too.

The curve is an unsigned 16-bit image with (in_max + 1) entries, each in the range [0, out_max].

lb, lw are expressed as 0-100, as in LAB colour space. You specify the scaling for the input and output images with the in_max and out_max parameters.

Load a native vips file straight to a VIPS Image.

Public Instance methods

In the first form, this operation calculates the bitwise and between each pixel in this image and other_image. The images must be the same size. They may have any format.

If the number of bands differs, one of the images must have one band. In this case, an n-band image is formed from the one-band image by joining n copies of the one-band image together and then the two n-band images are operated upon.

In the second form, it calculates the bitwise and of image pixels with a constant. If the image has multiple bands, then the constant is applied to all bands.

In the third form, it calculates the bitwise and of image pixels with an array of constants. The number of constants must match the number of bands in the image.

*(p1)

Alias for multiply

+(p1)

Alias for add

-(p1)

Alias for subtract

/(p1)

Alias for divide

Calculates the bitwise left-shift by c bits.

If only one constant is given, it calculates the left-shift for all bands in the image. If an array of constants is given, it applies each constant to an image band.

Calculates the bitwise right-shift by c bits.

If only one constant is given, it calculates the right-shift for all bands in the image. If an array of constants is given, it applies each constant to an image band.

Returns the band values at the given x, y location of the image. The upper left corner of the image is at 0, 0, and the lower right corner is at im.x_size - 1, im.y_size - 1.

If it is a one-band image, then this method returns the value without an array.

In the first form, this operation calculates the bitwise xor between each pixel in this image and other_image. The images must be the same size. They may have any format.

If the number of bands differs, one of the images must have one band. In this case, an n-band image is formed from the one-band image by joining n copies of the one-band image together and then the two n-band images are operated upon.

In the second form, it calculates the bitwise xor of image pixels with a constant. If the image has multiple bands, then the constant is applied to all bands.

In the third form, it calculates the bitwise xor of image pixels with an array of constants. The number of constants must match the number of bands in the image.

This operation finds the absolute value of an image. It does a copy for unsigned integer types, negate for negative values in signed integer types, fabs(3) for float types, and calculate modulus for complex types.

For each pixel, calculate the arc or inverse cosine. Angles are expressed in degrees. The output type is float, unless the input is double, in which case the output is double. Non-complex images only.

This operation calculates im + other_image and writes the result to a new image. The images must be the same size. They may have any format.

If the number of bands differs, one of the images must have one band. In this case, an n-band image is formed from the one-band image by joining n copies of the one-band image together, and then the two n-band images are operated upon.

The two input images are cast up to the smallest common type.

Add gaussian noise with mean 0 and variance sigma to self. The noise is generated by averaging 12 random numbers, see page 78, PIETGEN, 1989.

Applies an affine transformation on self. self many have any number of bands, be any size, and have any non-complex type.

The transformation is described by a, b, c, d, dx, dy. The point (x,y) in the input is mapped onto point (X,Y) in the output by

  X = a * x + b * y + dx
  Y = c * x + d * y + dy

In the first form, the entire image is transformed. In the second form, the area of the output image given by ow, oh, ox, oy is generated. (0,0) is the position of the transformed top-left-hand corner of the input image.

Points are generated using the supplied interpolator.

Applies an affine resize using the supplied interpolator. If y is ommitted then the aspect ratio of self will be maintained.

Brute force align the bands of an image.

For each pixel, calculate the arc or inverse sine. Angles are expressed in degrees. The output type is float, unless the input is double, in which case the output is double. Non-complex images only.

For each pixel, calculate the arc or inverse tangent. Angles are expressed in degrees. The output type is float, unless the input is double, in which case the output is double. Non-complex images only.

Finds the average of an image. Works on any non-complex image format.

Join a set of images together, bandwise. If the images have n and m bands, then the output image will have n + m bands, with the first n coming from the first image and the last m from the second.

The images must be the same size. The input images are cast up to the smallest common type.

Creates a one-band image where each pixel is the average of the bands for that pixel in the input image. The output band format is the same as the input band format. Integer types use round-to-nearest averaging.

This operation scans the condition image self (which must be unsigned char) and uses it to blend pixels from either the then image a_image or the else image b_image. 255 means a_image only, 0 means b_image only, and intermediate values are a mixture.

Any image can have either 1 band or n bands, where n is the same for all the non-1-band images. Single band images are then effectively copied to make n-band images.

Images a_image and b_image are cast up to the smallest common format.

Images a_image and b_image must match exactly in size.

Convert a complex image from rectangular to polar coordinates. Angles are expressed in degrees.

Extract the imaginary part of a complex image.

Extract the real part of a complex image.

Convert a complex image from polar to rectangular coordinates. Angles are expressed in degrees.

For each pixel, find the smallest integral value not less than. Copy for integer types. Output type == input type.

Convert the image to fmt_symbol format. You can convert between any pair of formats. Floats are truncated (not rounded). Out of range values are clipped.

fmt_symbol can be any of: :NOTSET, :UCHAR, :CHAR, :USHORT, :SHORT, :UINT, :INT, :FLOAT, :COMPLEX, :DOUBLE, :DPCOMPLEX.

Calculates the number of transitions between black and white for the horizontal direction of an image. black is < 128, and white is >= 128.

Returns the mean of the result. Input should be binary one channel.

Calculates the number of transitions between black and white for the vertical direction of an image. black is < 128, and white is >= 128.

Returns the mean of the result. Input should be binary one channel.

Returns the data coding for this image. Coding can be one of: :NONE, :LABQ, :RAD.

self is convolved 8 times with mask, each time mask is rotated by 45 degrees. Each output pixel is the largest absolute value of the 8 convolutions.

mask can be an array or a Mask object.

Generate an image where the value of each pixel represents the contrast within a window of half_win_size from the corresponsing point in the input image. Sub-sample by a factor of spacing.

Convolve self with mask. The output image always has the same band format as self. Non-complex images only.

Each output pixel is calculated as sigma[i]{pixel[i] * mask[i]} / scale + offset, where scale and offset are part of mask. For integer self, the division by scale includes round-to-nearest.

mask can be an array in which case scale defaults to 1 and offset defaults to zero. mask can also be a Mask object.

Perform a separable convolution of self with mask using integer arithmetic.

mask must be 1xn or nx1 elements.

The output image always has the same band format as self. Non-complex images only.

The image is convolved twice: once with mask and then again with mask rotated by 90 degrees. This is much faster for certain types of mask (gaussian blur, for example) than doing a full 2D convolution.

Each output pixel is calculated as sigma[i]{pixel[i] * mask[i]} / scale + offset, where scale and offset are part of mask. For integer self, the division by scale includes round-to-nearest.

mask can be an array in which case scale defaults to 1 and offset defaults to zero. mask can also be a Mask object.

Copy an image to a disc file, then copy again to output. If the image is already a disc file, just copy straight through.

The file is automatically deleted when image is closed.

Copy an image to native order, that is, the order for the executing program.

Copy an image, swapping byte order between little and big endian. This really does change image pixels and does not just alter the header.

Find position of other_image within self. Search around point xsec, ysec for the best match for the area around xref, yref. Search an area of size hsearchsize for an of size hwindowsize.

Return a new value for xsec, ysec and the correlation at that point.

For each pixel, calculate the cosine. Angles are expressed in degrees. The output type is float, unless the input is double, in which case the output is double. Non-complex images only.

Find the phase of the cross power spectrum of two complex images, expressed as a complex image where the modulus of each pixel is one.

Returns the uncompressed data of the image.

Calculate CIE dE00 from two Lab images.

Calculate CIE dE 1976 from two Lab images.

Calculate CIELAB dE 1976 from a pair of XYZ images.

Calculate dE CMC from two Lab images.

This operation finds the standard deviation of all pixels in the image. It operates on all bands of the input image: use Image#stats if you need to calculate an average for each band.

Non-complex images only.

Dilates self, according to mask. The output image is the same size as the input. Sets pixels in the output if any part of the mask matches.

self must be a one channel binary image ie. with pixels that are either 0 (black) or 255 (white). This method assume that self contains white objects against a black background.

mask can be a two-dimensional array or a Mask object. All mask values must be integers or this method will raise an exception.

Mask coefficients can be either 0 (for object) or 255 (for background) or 128 (for do not care). The mask should have odd length sides and the origin of the mask is at location (mask_columns/2, mask_rows/2) integer division.

Based on the book "Fundamentals of Digital Image Processing" by A. Jain, pp 384-388, Prentice-Hall, 1989.

Make a displayable (ie. 8-bit unsigned int) power spectrum.

If self is non-complex, it is transformed to Fourier space. Then the absolute value is passed through Image#scaleps, and Image#rotquad.

This operation calculates im / other_image. The images must be the same size. They may have any format.

If the number of bands differs, one of the images must have one band. In this case, an n-band image is formed from the one-band image by joining n copies of the one-band image together, and then the two n-band images are operated upon.

The two input images are cast up to the smallest common type.

Create a copy of an image.

Yields every pixel in the image, with coordinates.

The opposite of Image#extract: embed an image within a larger image. type_sym controls what appears in the new pixels:

  • :black - black pels (all bytes == 0)
  • :extend - extend pels from image edge
  • :repeat - repeat image
  • :mirror - mirror image
  • :white - white pixels (all bytes == 255)

In the first form, this operation calculates self == other_image (image element equals image element) and writes the result to the output image.

In the second form, this operation calculates self == constant (image element equals constant array) and writes the result to the output image.

Erodes self, according to mask. The output image is the same size as the input. Sets pixels in the output if all part of the mask matches.

self must be a one channel binary image ie. with pixels that are either 0 (black) or 255 (white). This method assume that self contains white objects against a black background.

mask can be a two-dimensional array or a Mask object. All mask values must be integers or this method will raise an exception.

Mask coefficients can be either 0 (for object) or 255 (for background) or 128 (for do not care). The mask should have odd length sides and the origin of the mask is at location (mask_columns/2, mask_rows/2) integer division.

Based on the book "Fundamentals of Digital Image Processing" by A. Jain, pp 384-388, Prentice-Hall, 1989.

Transforms each pixel value of the input image to c ** value in the output image. It detects division by zero, setting those pixels to zero in the output. Beware: it does this silently!

If one constant c is given, that constant is used for each image band. If more than one value is given, it must have the same number of elements as there are bands in the image, and one element is used for each band.

The first form will extract an area from an image.

The second form will extract an area and a number of bands from an image. Bands number from zero. Extracting outside the input image will trigger an error.

Extract the band given by band from the image. If num_bands is given, extract that many bands. Bands number from zero.

  im.extract_band(0, 2) # => new image with bands 0 & 1 from original.

Extracting bands outside the input image will trigger an error.

Turn a 1-band 8-bit image into a 3-band 8-bit image with a false colour map. The map is supposed to make small differences in brightness more obvious.

Calculate a fast correlation surface.

other_image is placed at every position in self and the sum of squares of differences calculated. One-band, 8-bit unsigned images only. The output image is always band format :UINT. other_image must be smaller than or equal to self. The output image is the same size as the input.

Returns the path from which self was read.

Flips an image left-right.

Flips an image top-bottom.

Convert a three-band float image to Radiance 32-bit packed format.

For each pixel, find the largest integral value not less than. Copy for integer types. Output type == input type.

Filter an image in Fourier space.

self is transformed to Fourier space, multipled with other_image, then transformed back to real space. If self is already a complex image, just multiply then inverse transform.

Transform an image to Fourier space.

VIPS uses the fftw3 or fftw2 Fourier transform libraries if possible. If they were not available when VIPS was built, it falls back to its own FFT functions which are slow and only work for square images whose sides are a power of two.

Gamma-correct an 8- or 16-bit unsigned image with a lookup table. The output format is the same as the input format.

Takes an image assembled with the mosaicing functions, take it apart, and reassemble it, globally optimising the image balance. This is useful for assembling image mosaics from sources where the exposure is uncontrolled and may vary from tile to tile — such as video, or photographic sources.

The function finds a set of factors, one for each of the input images, and scales each image by its factor before reassembling. The factors are chosen so as to minimise the average grey-level difference between neighboring images at their overlaps. Trivial overlaps (where the width and height of the overlap are both less than 20 pixels) are ignored.

The gamma parameter is the gamma of the image input system. It is used during brightness adjustment. Set to 1.0 to disable gamma, to 1.6 for a typical IR vidicon camera, or 2.3 for a typical video camera.

It relies on information left by the mosaicing functions in ".desc" files. If the ".desc" file of the input image has been corrupted, or is strangely complicated, or if any of the original input images have been moved or deleted, the function can fail.

The function will fail for mosaics larger than about 7 by 7 frames, since it will run out of file descriptors (UNIX sets a limit of 256 per process). To balance larger mosaics, just assemble them in 7x7 sections, balancing and saving each part in turn, before loading, assembling and balancing the final image. The function can also fail if there are significant mosaicing errors.

Works as Image#global_balance, but outputs a float rather than a uchar image. This lets you adjust the range of the image manually, if the automatically-found scales are causing burn-out.

Find horizontal differences between adjacent pixels.

Generates an image where the value of each pixel is the difference between it and the pixel to its right. The output has the same height as the input and one pixel less width. One-band integer formats only. The result is always band format :INT.

This operation is much faster than (though equivalent to) Image#conv with the mask [[-1, 1]].

Find vertical differences between adjacent pixels.

Generates an image where the value of each pixel is the difference between it and the pixel below it. The output has the same width as the input and one pixel less height. One-band integer formats only. The result is always band format :INT.

This operation is much faster than (though equivalent to) Image#conv with the mask [[-1], [1]].

Calculate a correlation surface.

other_image is placed at every position in self and a correlation coefficient calculated. One-band, integer images only. self and other_image must have the same band format. The output image is always band format :FLOAT. other_image must be smaller than self. The output image is the same size as the input.

The method takes the gradient images of the two images then takes the dot-product correlation of the two vector images. The vector expression of this method is my (tcv) own creation. It is equivalent to the complex-number method of:

ARGYRIOU, V. et al. 2003. Estimation of sub-pixel motion using gradient cross correlation. Electronics Letters, 39 (13).

self is convolved with mask and with mask after a 90 degree rotation. The result is the sum of the absolute value of the two convolutions.

mask can be an array or a Mask object.

Chop a tall thin image up into a set of tiles, lay the tiles out in a grid.

self should be a very tall, thin image containing a list of smaller images. Volumetric or time-sequence images are often laid out like this. This image is chopped into a series of tiles, each tile_height pixels’ high and the width of self. The tiles are then rearranged into a grid across tiles across and down tiles down in row-major order.

Histogram-equalise self. Equalise using band band, or if not given, equalise all bands.

Find and plot the histogram of self. If band is not given, plot all bands. Otherwise plot the specified band.

Make a histogram of other_image, but use self to pick the bins. In other words, element zero in the output image contains the sum of all the pixels in other_image whose corresponding pixel in self is zero.

self must have just one band and be u8 or u16. other_image must be non-complex. The output image always has the same size and format as other_image.

This operation is useful in conjunction with Image#label_regions. You can use it to find the centre of gravity of blobs in an image, for example.

Form cumulative histogram.

Histogram equalisation: normalised cumulative histogram.

Find the histogram of self. If band is given, find the histogram for that band (producing a one-band histogram). If band is not given, find the histogram for all bands (producing an n-band histogram).

self must be u8 or u16. The output image is always u32.

Make a one, two or three dimensional histogram of a 1, 2 or 3 band image. Divide each axis into a certain number of bins .. ie. output is 1 x bins, bins x bins, or bins x bins x bins bands. uchar and ushort only.

Normalise histogram … normalise range to make it square (ie. max == number of elements). Normalise each band separately.

Plot a 1 by any or any by 1 image as a max by any or any by max image using these rules:

  • unsigned char max is always 256
  • other unsigned integer types output 0 - maxium value of self.
  • signed int types - min moved to 0, max moved to max + min.
  • float types - min moved to 0, max moved to any (square output).

Creates a lut which, when applied to the image from which histogram self was formed, will produce an image whose PDF matches that of the image from which other_image was formed.

Maps self to the output image,, adjusting the histogram to match image other_image.

Both images should have the same number of bands.

Transform an image from absolute to relative colorimetry using the MediaWhitePoint stored in the ICC profile.

Export an image with the ICC library. The input image in D65 LAB is transformed to device space using the supplied profile. depth can be 8 or 16, for 8 or 16-bit image export.

Import an image with the ICC library. The input image in device space is moved to D65 LAB with the input profile.

Import an image with the ICC library. The input image in device space is moved to D65 LAB with the input profile from the input image header attached.

Transform an image with the ICC library. The input image is moved to profile-connection space with the input profile and then to the output space with the output profile.

Use Image#icc_import and Image#icc_export_depth to do either the first or second half of this operation in isolation.

This operation scans the condition image self and uses it to select pixels from either the then image a_image or the else image b_image. Non-zero means a_image, 0 means b_image.

Any image can have either 1 band or n bands, where n is the same for all the non-1-band images. Single band images are then effectively copied to make n-band images.

Images a_image and b_image are cast up to the smallest common format.

Images a_image and b_image must match exactly in size.

Morph an image in CIELAB colour space. Useful for certain types of gamut mapping, or correction of greyscales on some printers.

We perform three adjustments.

  • cast

    Pass in mask containing CIELAB readings for a neutral greyscale. For example:

      mask = [
        [14.23, 4.8 , -3.95],
        [18.74, 2.76, -2.62],
        [23.46, 1.4 , -1.95],
        [27.46, 1.76, -2.01]
      ]
    

    Interpolation from this makes cast corrector. The top and tail are interpolated towards [0, 0, 0] and [100, 0, 0], intermediate values are interpolated along straight lines fitted between the specified points. Rows may be in any order (ie. they need not be sorted on L*).

    Each pixel is displaced in a/b by the amount specified for that L in the table.

  • L*

    Pass in l_scale and l_offset for L. L’ = (L + offset) * scale.

  • saturation

    scale a and b by these amounts, eg. 1.5 increases saturation.

Find the top two by generating and printing a greyscale. Find the bottom by printing a Macbeth and looking at a/b spread

Insert other_image repeatedly into self at the positions listed in the coordinates arrays. These arrays should contain x and y coordinates:

  im.insert(other_image, 100, 100) # => other_image inserted once at 100, 100
  im.insert(other_image, [12, 20], [32, 22]) # => inserted twice at given coordinates

The output image is the same size as self. other_image is clipped against the edges of self.

This operation is fast for large @n, but will use a memory buffer the size of the output image. It‘s useful for things like making scatter plots.

If the number of bands differs, one of the images must have one band. In this case, an n-band image is formed from the one-band image by joining n copies of the one-band image together, and then the two n-band images are operated upon.

The two input images are cast up to the smallest common type.

Insert one image into another. other_image is inserted into self at position x, y relative to the top LH corner of self. The output image is the same size as self. other_image is clipped against the edges of self.

If the number of bands differs, one of the images must have one band. In this case, an n-band image is formed from the one-band image by joining n copies of the one-band image together, and then the two n-band images are operated upon.

The two input images are cast up to the smallest common type.

This operation calculates (255 - im). The operation works on uchar images only. The input can have any no of channels.

See Image#exptra for a function which can process any input image type.

Transform an image from Fourier space to real space. The result is complex. If you are OK with a real result, use Image#invfftr instead, it‘s quicker.

VIPS uses the fftw3 or fftw2 Fourier transform libraries if possible. If they were not available when VIPS was built, it falls back to its own FFT functions which are slow and only work for square images whose sides are a power of two.

Transform an image from Fourier space to real space, giving a real result. This is faster than Image#invfft, which gives a complex result.

VIPS uses the fftw3 or fftw2 Fourier transform libraries if possible. If they were not available when VIPS was built, it falls back to it‘s own FFT functions which are slow and only work for square images whose sides are a power of two.

Returns whether this image has been flagged to stop processing.

Turn Lab to LabQ.

Turn Lab to LabS.

Turn Lab to LCh.

Turn Lab to UCS.

Turn Lab to XYZ.

Turn Lab to XYZ. x0, y0, z0 give the Lab colour temperature.

self is repeatedly scanned and regions of 4-connected pixels with the same pixel value found. Every time a region is discovered, those pixels are marked in the output image with a unique serial number. Once all pixels have been labelled, the operation returns, returning an an image and segments, the number of discrete regions which were detected.

The output image is always a 1-band image with band format :UINT, and of the same dimensions as self.

This operation is useful for, for example, blob counting. You can use the morphological operators to detect and isolate a series of objects, then use this method to number them all.

Use Image#histindexed to (for example) find blob coordinates.

Turn LabQ to Lab.

Turn LabQ to LabS.

Turn LabQ to XYZ.

Turn LabS to Lab.

Turn LabS to LabQ.

Turn LCh to Lab.

Turn LCh to UCS.

In the first form, this operation calculates self < other_image (image element equals image element) and writes the result to the output image.

In the second form, this operation calculates self < constant (image element equals constant array) and writes the result to the output image.

In the first form, this operation calculates self <= other_image (image element equals image element) and writes the result to the output image.

In the second form, this operation calculates self <= constant (image element equals constant array) and writes the result to the output image.

Performs local histogram equalisation on self using a window of size xwin by ywin centered on the input pixel. Works only on monochrome images.

The output image is the same size as the input image. The edge pixels are created by copy edge pixels of the input image outwards.

Pass an image through a linear transform - ie. im * a + b. Output is always float for integer input, double for double input, complex for complex input and double complex for double complex input.

If the arrays are passed in and they have the same number of elements as there are bands in the image, then one array element is used for each band. If the arrays have more than one element and the image only has a single band, the result is a many-band image where each band corresponds to one array element.

self is convolved four times with @mask, each time @mask is rotated by 45 degrees. Each output pixel is the largest absolute value of the four convolutions.

mask can be an array or a Mask object.

For each pixel, calculate the natural logarithm. The output type is float, unless the input is double, in which case the output is double. Non-complex images only.

For each pixel, calculate the base 10 logarithm. The output type is float, unless the input is double, in which case the output is double. Non-complex images only.

Join self and other_image together, left-right. If one is taller than the other, the output image will be as high as the smaller image.

If the number of bands differs, one of the images must have one band. In this case, an n-band image is formed from the one-band image by joining n copies of the one-band image together, and then the two n-band images are operated upon.

The two input images are cast up to the smallest common type.

Merge self as the reference image and other_image as the secondary image according to the values dx and dy. dx and dy give the displacement of other_image relative to self. The result is written to the output image.

The program carries out a smooth merge using a raised cosine function. Works for any image type, including LABPACK.

Pixels are treated with the value zero as "transparent", that is, zero pixels in the overlap area do not contribute to the merge. This makes it possible to join non-rectangular images.

The "mwidth" parameter limits the maximum width of the blend area. If not given, the width will be unlimited.

Mosaic self and other_image left-right.

In order to carry out mosaicing, the coordinates of one tie point are required. The tie point is expected to be in the overlapping area and has coordinates (xref, yref) on self, and (xsec, ysec) on other_image. The tie-point is not used as a start point for the search, but is used to specify the overlap of the two images.

The function splits the overlap area into three parts (top, middle and bottom) and searches t*self* in each part for the 20 best high contrast points. These 60 points are then searched for in other_image, giving a set of 60 possible corrected vectors.

A straight line is fitted through the 60 vectors, and points discarded which lie a significant distance from the line. The line is then refitted to the remaining points, and the process repeated until either all remaining points lie on a straight line, or too many points have been discarded.

If a good straight line fit is found, self and other_image are joined. If no fit was found, the function fails with an error message. Note that this function detects rotation: if the straight line found requires other_image to be rotated, it also fails with an error message.

halfcorrelationsize - sets the size of the fragments of self for which the function searches sec. The actual window will be of size 2 * halfcorrelationsize + 1. We recommend a value of 5.

halfareasize - sets the size of the area of sec that is searched. The The actual area searched will be of size 2 * halfareasize + 1. We recommend a value of 14.

balancetype - sets the style of the balancing the functions perform. Balancing finds the average value of pixels in the overlap area, and scales the left and right images so as to make the images match in average overlap.

  • :balance_none - no balancing.
  • :balance_left - keep the left image unadjusted and adjust the contrast of the right image to match the left.
  • :balance_right - keep the right image unadjusted and scale the left image to match it.
  • :balance_both - adjust the contrast of both the left and right images to bring both averages to a middle value. The middle value chosen is weighted by the number of pixels in each image: large images will be adjusted less than small images.

Balancing is useful for mosaicing frames from photographic or video sources where exact colour control is impossible and exposure varies from frame to frame. Balancing is only allowed for uncoded uchar images.

The mwidth parameter sets the maximum blend width, see Image#lrmerge.

Map an image through another image acting as a LUT (Look Up Table). The lut may have any type, and the output image will be that type.

The input image will be cast to one of the unsigned integer types, that is, band format :UCHAR, :USHORT or :UINT.

If lut is too small for the input type (for example, if self is band format :UCHAR but lut only has 100 elements), the lut is padded out by copying the last element. Overflows are reported at the end of computation.

If lut is too large, extra values are ignored.

If lut has one band, then all bands of self pass through it. If lut has same number of bands as self, then each band is mapped separately. If self has one band, then @lut may have many bands and the output will have the same number of bands as lut.

Works exactly as Image#match_linear_search, but does not attempt to correlate to correct your tie points. It can thus be used for any angle and any scale, but you must be far more careful in your selection.

Attempts to transform sec to make it match ref. The transformation is linear, that is, it only involves scale, rotate and translate.

Requires a pair of tie points to fix the parameters of its transformation. You should pick points as far apart as possible to increase accuracy. It will search the area in the image around each tie point for a good fit, so your selection of points need not be exact. WARNING! This searching process will fail for rotations of more than about 10 degrees or for scales of more than about 10 percent.

The best you can hope for is < 1 pixel error, since the command does not attempt sub-pixel correlation.

hwindowsize and hsearchsize set the size of the area to be searched: we recommend values of 5 and 14.

The output image is positioned and clipped so that you can immediately subtract it from orig to obtain pixel difference images.

Finds the the maximum value of self. If input is complex, the max modulus is returned. Finds the maximum of all bands: if you want to find the maximum of each band separately, use Image#stats.

Function to find the maximum of an image. Works for any image type. Returns an array with the x and y coordinates of the maximum value and the corresponding value. If n is given, returns the n largest values. For complex images, finds the pixel with the highest modulus.

Function to find the maximum of an image. In the event of a draw, returns average of all drawing coords.

This function implements "Extension of Phase Correlation to Subpixel Registration" by H. Foroosh, from IEEE trans. Im. Proc. 11(3), 2002.

If the best three matches in the correlation are aranged:

  02   or   01
  1         2

then we return a subpixel match using the ratio of correlations in the vertical and horizontal dimension.

( xs[0], ys[0] ) is the best integer alignment ( xs[ use_x ], ys[ use_x ] ) is equal in y and (+/-)1 off in x ( xs[ use_y ], ys[ use_y ] ) is equal in x and (+/-)1 off in y

Alternatively if the best four matches in the correlation are aranged in a square:

  01  or  03  or  02  or  03
  32      12      31      21

then we return a subpixel match weighting with the sum the two on each side over the sum of all four, but only if all four of them are very close to the best, and the fifth is nowhere near.

This alternative method is not described by Foroosh, but is often the case where the match is close to n-and-a-half pixels in both dimensions.

Sorts the input images pixel-wise, then outputs an image in which each pixel is the maximum from the input pixels.

It works for any uncoded, non-complex image type. All input images must match in size, format, and number of bands.

Analyse a grid of colour patches, producing an array of averages. Pass a box defined by left, top, width, and height, the number of horizontal and vertical patches h and v, an array giving the numbers of the patches to measure sel (patches are numbered left-to-right, top-to-bottom, starting with 1). Return an array in which rows are patches and columns are bands. Only the central 50% of each patch is averaged.

Finds the the minimum value of the image. If input is complex, the min modulus is returned. Finds the minimum of all bands: if you want to find the minimum of each band separately, use Image#stats.

Function to find the minimum of an image. Works for any image type. Returns an array with the x and y coordinates of the minimum value and the corresponding value. If n is given, returns the n lowest values. For complex images, finds the pixel with the lowest modulus.

Test self for monotonicity. Returns true if self is monotonic.

In the first form, this operation calculates self > other_image (image element equals image element) and writes the result to the output image.

In the second form, this operation calculates self > constant (image element equals constant array) and writes the result to the output image.

In the first form, this operation calculates self >= other_image (image element equals image element) and writes the result to the output image.

In the second form, this operation calculates self >= constant (image element equals constant array) and writes the result to the output image.

Returns the threshold above which there are percent values of self. If for example percent=.1, the number of pels of the input image with values greater than the returned int will correspond to 10% of all pels of the image.

The function works for uchar and ushort images only. It can be used to threshold the scaled result of a filtering operation.

Just like Image#mpercent, except it works on an image histogram. Handy if you want to run Image#mpercent several times without having to recompute the histogram each time.

Turn any integer image to 8-bit unsigned char by discarding all but the most significant byte. Signed values are converted to unsigned by adding 128.

This operator also works for LABQ coding.

If band is given, this will turn any integer image to a single-band’ 8-bit unsigned char by discarding all but the most significant byte from the selected band.

This operation calculates im * other_image. The images must be the same size. They may have any format.

If the number of bands differs, one of the images must have one band. In this case, an n-band image is formed from the one-band image by joining n copies of the one-band image together, and then the two n-band images are operated upon.

The two input images are cast up to the smallest common type.

In the first form, this operation calculates self != other_image (image element equals image element) and writes the result to the output image.

In the second form, this operation calculates self != constant (image element equals constant array) and writes the result to the output image.

Convert the two input images to Fourier space, calculate phase-correlation, back to real space.

Find the value at (@x, @y) in given band of image. Non-integral values are calculated using the supplied interpolator, e.g. :bilinear.

To get a list of available interpolators, look at

    VIPS::Interpolator::INTERPOLATORS.keys
   im ** c        -> image
   im ** [c, ...] -> image

Tansforms each pixel value in the input image to value ** c in the output image. It detects division by zero, setting those pixels to zero in the output. Beware: it does this silently!

If one constant c is given, that constant is used for each image band. If more than one value is given, it must have the same number of elements as there are bands in the image, and one element is used for each band.

For each horizontal line, find the position of the first non-zero pixel from the left. Output is USHORT with width = 1 and height = input height.

For each vertical line, find the position of the first non-zero pixel from the top. Output is USHORT with width = input width and height = 1.

Find the horizontal and vertical projections of an image, ie. the sum of every row of pixels, and the sum of every column of pixels. The output format is uint, int or double, depending on the input format.

Non-complex images only.

Unpack a RAD image to a three-band float image.

Does rank filtering on an image. A window of size xsize by ysize is passed over the image. At each position, the pixels inside the window are sorted into ascending order and the pixel at the nth position is output. n numbers from 0.

It works for any non-complex image type, with any number of bands. The input is expanded by copying edge pixels before performing the operation so that the output image has the same size as self. Edge pixels in the output image are therefore only approximate.

Sorts the input images pixel-wise, then outputs an image in which each pixel is selected from the sorted list by index parameter. For example, if index is zero, then each output pixel will be the minimum of all the corresponding input pixels.

It works for any uncoded, non-complex image type. All input images must match in size, format, and number of bands.

This operation recombines an image‘s bands. Each pixel in im is treated as an n-element vector, where n is the number of bands in im, and multipled by the n x m matrix array to produce the m-band output image.

The output image is always float, unless im is double, in which case it is double too. No complex images allowed.

It‘s useful for various sorts of colour space conversions.

   im.remainder(other_image) -> image
   im.remainder(c)           -> image
   im.remainder(c, ...)      -> image

The first form calculates im % other_image (remainder after division). The images must be the same size. They may have any non-complex format. For float formats, it calculates im - other_image * floor (im / other_image).

If the number of bands differs, one of the images must have one band. In this case, an n-band image is formed from the one-band image by joining n copies of the one-band image together, and then the two n-band images are operated upon.

The two input images are cast up to the smallest common type.

The second and third form calculates im % c (remainder after division by constant). The image may have any non-complex format. For float formats, calculates im - c * floor (im / c).

If the number of image bands and constants differs, then the image must have one band or there must only one constant. Either the image is up-banded by joining n copies of the one-band image together, or the same constant is used for all image bands.

Replicate an image across times horizontally down times vertically.

Compose two real images to make a complex image. If either image has band format :DOUBLE, the output image is band format :DPCOMPLEX. Otherwise the output image is :COMPLEX.

If the number of bands differs, one of the images must have one band. In this case, an n-band image is formed from the one-band image by joining n copies of the one-band image together, and then the two n-band images are operated upon.

The two input images are cast up to the smallest common type.

Decreases the size of an integer type image by a power-of-two factor, very quickly, by summing the values of adjacent pixels. The sum is shifted to produce output of the specified band format.

xshift and yshift are positive and give the base-two logarithms of the scale factors.

If the input image is a signed type, then the band format must be one of :CHAR, :SHORT or :INT. If it is an unsigned type, then the band format must be one of :UCHAR, :USHORT or :UINT.

Finds the nearest integral value. Copy for integer types. Output type == input type.

Rotate an image 180 degrees.

Rotate an image 270 degrees.

Rotate an image 90 degrees.

Rotate the quadrants of the image so that the point that was at the top-left is now in the centre. Handy for moving Fourier images to optical space.

Search the image for the maximum and minimum value, then return the image as unsigned 8-bit, scaled so that the maximum value is 255 and the minimum is zero.

Scale a power spectrum. Transform with log10(1.0 + x ** 0.25)) + 0.5, then scale so max == 255.

Selectively sharpen the L channel of a LAB image. Works for :LABQ coding and LABS images.

The operation performs a gaussian blur of size mask_size and subtract from self to generate a high-frequency signal. This signal is passed through a lookup table formed from the five parameters and added back to self.

For printing, we recommend the following settings:

  mask_size == 7
  x1 == 1.5
  y2 == 20         (don't brighten by more than 20 L*)
  y3 == 50         (can darken by up to 50 L*)

  m1 == 1          (some sharpening in flat areas)
  m2 == 2          (more sharpening in jaggy areas)

If you want more or less sharpening, we suggest you just change the m1 and m2 parameters.

The mask_size parameter changes the width of the fringe and can be adjusted according to the output printing resolution. As an approximate guideline, use 3 for 4 pixels/mm (CRT display resolution), 5 for 8 pixels/mm, 7 for 12 pixels/mm and 9 for 16 pixels/mm (300 dpi == 12 pixels/mm). These figures refer to the image raster, not the half-tone resolution.

Shrink self by width_ratio along the horizontal and height_ratio along the vertical direction. If height_ratio is not given, it uses width_ratio. The function does not perform subpixel interpolation and therefore the resultant image can present aliasing especially for small x and y factors. Any size image, any non-complex type, any number of bands.

Finds the unit vector in the direction of the pixel value. For non-complex images, it returns a signed char image with values -1, 0, and 1 for negative, zero and positive pixels. For complex images, it returns a complex normalised to length 1.

For each pixel, calculate the sine. Angles are expressed in degrees. The output type is float, unless the input is double, in which case the output is double. Non-complex images only.

Calculate a correlation surface.

other_image is placed at every position in self and the correlation coefficient calculated. One-band, 8 or 16-bit images only. self and other_image must have the same band format.. The output image is always band format :FLOAT. other_image must be smaller than or equal to self. The output image is the same size as self.

The correlation coefficient is calculated as:

          sumij (ref(i,j)-mean(ref))(inkl(i,j)-mean(inkl))
 c(k,l) = ------------------------------------------------
          sqrt(sumij (ref(i,j)-mean(ref))^2) *
                      sqrt(sumij (inkl(i,j)-mean(inkl))^2)

where inkl is the area of self centred at position (k,l).

from Niblack "An Introduction to Digital Image Processing", Prentice/Hall, pp 138.

Turn sRGB to XYZ.

Find many image statistics in a single pass through the pixels. Returns an array of 6 columns by n+1 (where n is number of bands in the image) rows. Columns are statistics, and are, in order: minimum, maximum, sum, sum of squares, mean, standard deviation. Row 0 has statistics for all bands together, row 1 has stats for band 1, and so on.

Preforms statistical differencing according to the formula given in page 45 of the book "An Introduction to Digital Image Processing" by Wayne Niblack. This transformation emphasises the way in which a pel differs statistically from its neighbours. It is useful for enhancing low-contrast images with lots of detail, such as X-ray plates.

At point (i,j) the output is given by the equation:

  vout(i,j) = a * m0 + (1 - a) * meanv +
      (vin(i,j) - meanv) * (b * s0) / (s0 + b * stdv)

Values a, m0, b and s0 are entered, while meanv and stdv are the values calculated over a moving window of size xwin, ywin centred on pixel (i,j).

m0 is the new mean, a is the weight given to it. s0 is the new standard deviation, b is the weight given to it.

Try:

  im.stdif(0.5, 128, 0.5, 50, 11, 11)

The operation works on one-band uchar images only, and writes a one-band uchar image as its result. The output image has the same size as the input.

Stretches the input image by 3% horizontally, and displaces it by dx/dy. It uses bi-cubic interpolation, but runs quickly. It works only for unsigned short images.

This function is part of the MARC acquisition software, but is generally useful for squaring up the pixels in images from the Kontron ProgRes camera range.

Subsample an image by an integer fraction. This is fast nearest-neighbour shrink.

If only one integer is given the width and height are subsampled equally.

This operation calculates im - image and writes the result to a new image. The images must be the same size. They may have any format.

If the number of bands differs, one of the images must have one band. In this case, an n-band image is formed from the one-band image by joining n copies of the one-band image together, and then the two n-band images are operated upon.

The two input images are cast up to the smallest common type.

For each pixel, calculate the tangent. Angles are expressed in degrees. The output type is float, unless the input is double, in which case the output is double. Non-complex images only.

Join self and other_image together, top-bottom. If one is taller than the other, the output image will be as high as the smaller image.

If the number of bands differs, one of the images must have one band. In this case, an n-band image is formed from the one-band image by joining n copies of the one-band image together, and then the two n-band images are operated upon.

The two input images are cast up to the smallest common type.

Make a mask from an image. All images are cast to band format :DOUBLE before processing. There are two cases for handling bands:

If the image has a single band, Image#to_mask will write a mask the same size as the image.

If the image has more than one band, it must be one pixel high or wide. In this case the output mask uses that axis to represent band values.

As Image#tone_build, but analyse the histogram of self and use it to pick the 0.1% and 99.9% points for lb and lw.

Turn UCS to Lab.

Turn UCS to LCh.

Turn UCS to XYZ.

Returns the type of image that Vips has assigned to self. This can by any of:

:B_W, :HISTOGRAM, :FOURIER, :XYZ, :LAB, :CMYK, :LABQ, :RGB, :UCS, :LCH, :LABS, :sRGB, :YXY, :RGB16, :GREY16

Slice an image up and move the segments about so that the pixel that was at 0, 0 is now at x, y.

Turn XYZ to Lab.

Turn XYZ to LAB. x0, y0, z0 give the Lab colour temperature.

Turn XYZ to sRGB.

Turn XYZ to UCS.

Turn XYZ to Yxy.

Turn Yxy to XYZ.

Detects the -ve edges of zero crossings of self. Works on integer images. The output image is byte with zero crossing set to 255 and all other values set to zero.

Detects the +ve edges of zero crossings of self. Works on integer images. The output image is byte with zero crossing set to 255 and all other values set to zero.

Zoom an image by repeating pixels. This is fast nearest-neighbour zoom.

If only one integer is given the width and height are zoomed equally.

In the first form, this operation calculates the bitwise or between each pixel in this image and other_image. The images must be the same size. They may have any format.

If the number of bands differs, one of the images must have one band. In this case, an n-band image is formed from the one-band image by joining n copies of the one-band image together and then the two n-band images are operated upon.

In the second form, it calculates the bitwise or of image pixels with a constant. If the image has multiple bands, then the constant is applied to all bands.

In the third form, it calculates the bitwise or of image pixels with an array of constants. The number of constants must match the number of bands in the image.

[Validate]