Top |
conversionconversion — convert images in some way: change band format, change header, insert, extract, join |
Functions
Types and Values
enum | VipsExtend |
enum | VipsCompassDirection |
enum | VipsDirection |
enum | VipsAlign |
enum | VipsAngle |
enum | VipsAngle45 |
enum | VipsInteresting |
enum | VipsBlendMode |
Object Hierarchy
GEnum ├── VipsAlign ├── VipsAngle ├── VipsAngle45 ├── VipsBlendMode ├── VipsCompassDirection ├── VipsDirection ├── VipsExtend ╰── VipsInteresting
Description
These operations convert an image in some way. They can be split into a two main groups.
The first set of operations change an image's format in some way. You can change the band format (for example, cast to 32-bit unsigned int), form complex images from real images, convert images to matrices and back, change header fields, and a few others.
The second group move pixels about in some way. You can flip, rotate, extract, insert and join pairs of images in various ways.
Functions
vips_copy ()
int vips_copy (VipsImage *in
,VipsImage **out
,...
);
Optional arguments:
width
:gint
, set image widthheight
:gint
, set image heightbands
:gint
, set image bandsformat
: VipsBandFormat, set image formatcoding
: VipsCoding, set image codinginterpretation
: VipsInterpretation, set image interpretationxres
:gdouble
, set image xresyres
:gdouble
, set image yresxoffset
:gint
, set image xoffsetyoffset
:gint
, set image yoffset
Copy an image, optionally modifying the header. VIPS copies images by copying pointers, so this operation is instant, even for very large images.
You can optionally change any or all header fields during the copy. You can make any change which does not change the size of a pel, so for example you can turn a 4-band uchar image into a 2-band ushort image, but you cannot change a 100 x 100 RGB image into a 300 x 100 mono image.
See also: vips_byteswap()
, vips_bandfold()
, vips_bandunfold()
.
[method]
vips_tilecache ()
int vips_tilecache (VipsImage *in
,VipsImage **out
,...
);
Optional arguments:
tile_width
: width of tiles in cachetile_height
: height of tiles in cachemax_tiles
: maximum number of tiles to cacheaccess
: hint expected access pattern VipsAccessthreaded
: allow many threadspersistent
: don't drop cache at end of computation
This operation behaves rather like vips_copy()
between images
in
and out
, except that it keeps a cache of computed pixels.
This cache is made of up to max_tiles
tiles (a value of -1
means any number of tiles), and each tile is of size tile_width
by tile_height
pixels.
Each cache tile is made with a single call to
vips_region_prepare()
.
When the cache fills, a tile is chosen for reuse. If access
is
VIPS_ACCESS_RANDOM, then the least-recently-used tile is reused. If
access
is VIPS_ACCESS_SEQUENTIAL
the top-most tile is reused.
By default, tile_width
and tile_height
are 128 pixels, and the operation
will cache up to 1,000 tiles. access
defaults to VIPS_ACCESS_RANDOM.
Normally, only a single thread at once is allowed to calculate tiles. If
you set threaded
to TRUE
, vips_tilecache()
will allow many threads to
calculate tiles at once, and share the cache between them.
Normally the cache is dropped when computation finishes. Set persistent
to
TRUE
to keep the cache between computations.
See also: vips_cache()
, vips_linecache()
.
[method]
vips_linecache ()
int vips_linecache (VipsImage *in
,VipsImage **out
,...
);
Optional arguments:
access
: hint expected access pattern VipsAccesstile_height
: height of tiles in cachethreaded
: allow many threads
This operation behaves rather like vips_copy()
between images
in
and out
, except that it keeps a cache of computed scanlines.
The number of lines cached is enough for a small amount of non-local access.
Each cache tile is made with a single call to
vips_region_prepare()
.
When the cache fills, a tile is chosen for reuse. If access
is
VIPS_ACCESS_RANDOM, then the least-recently-used tile is reused. If
access
is VIPS_ACCESS_SEQUENTIAL, then
the top-most tile is reused. access
defaults to VIPS_ACCESS_RANDOM.
tile_height
can be used to set the size of the strips that
vips_linecache()
uses. The default is 1 (a single scanline).
Normally, only a single thread at once is allowed to calculate tiles. If
you set threaded
to TRUE
, vips_linecache()
will allow many threads to
calculate tiles at once and share the cache between them.
See also: vips_cache()
, vips_tilecache()
.
[method]
vips_sequential ()
int vips_sequential (VipsImage *in
,VipsImage **out
,...
);
Optional arguments:
tile_height
: height of cache strips
This operation behaves rather like vips_copy()
between images
in
and out
, except that it checks that pixels on in
are only requested
top-to-bottom. This operation is useful for loading file formats which are
strictly top-to-bottom, like PNG.
tile_height
can be used to set the size of the tiles that
vips_sequential()
uses. The default value is 1.
See also: vips_cache()
, vips_linecache()
, vips_tilecache()
.
[method]
vips_cache ()
int vips_cache (VipsImage *in
,VipsImage **out
,...
);
Optional arguments:
tile_width
: width of tiles in cachetile_height
: height of tiles in cachemax_tiles
: maximum number of tiles to cache
This operation behaves rather like vips_copy()
between images
in
and out
, except that it keeps a cache of computed pixels.
This cache is made of up to max_tiles
tiles (a value of -1
means any number of tiles), and each tile is of size tile_width
by tile_height
pixels. By default it will cache 250 128 x 128 pixel tiles,
enough for two 1920 x 1080 images.
This operation is a thin wrapper over vips_sink_screen()
, see the
documentation for that operation for details.
It uses a set of background threads to calculate pixels and the various active cache operations coordinate so as not to overwhelm your system. When a request is made for an area of pixels, the operation will block until all of those pixels have been calculated. Pixels are calculated with a set of threads.
See also: vips_tilecache()
.
[method]
vips_copy_file ()
int vips_copy_file (VipsImage *in
,VipsImage **out
,...
);
A simple convenience function to copy an image to a file, then copy again to output. If the image is already a file, just copy straight through.
The file is allocated with vips_image_new_temp_file()
.
The file is automatically deleted when out
is closed.
See also: vips_copy()
, vips_image_new_temp_file()
.
[method]
vips_embed ()
int vips_embed (VipsImage *in
,VipsImage **out
,int x
,int y
,int width
,int height
,...
);
Optional arguments:
extend
: VipsExtend to generate the edge pixels (default: black)background
: VipsArrayDouble colour for edge pixels
The opposite of vips_extract_area()
: embed in
within an image of size
width
by height
at position x
, y
.
extend
controls what appears in the new pels, see VipsExtend.
See also: vips_extract_area()
, vips_insert()
.
[method]
vips_gravity ()
int vips_gravity (VipsImage *in
,VipsImage **out
,VipsCompassDirection direction
,int width
,int height
,...
);
Optional arguments:
extend
: VipsExtend to generate the edge pixels (default: black)background
: VipsArrayDouble colour for edge pixels
The opposite of vips_extract_area()
: place in
within an image of size
width
by height
at a certain gravity.
extend
controls what appears in the new pels, see VipsExtend.
See also: vips_extract_area()
, vips_insert()
.
vips_flip ()
int vips_flip (VipsImage *in
,VipsImage **out
,VipsDirection direction
,...
);
Flips an image left-right or up-down.
See also: vips_rot()
.
[method]
vips_insert ()
int vips_insert (VipsImage *main
,VipsImage *sub
,VipsImage **out
,int x
,int y
,...
);
Optional arguments:
expand
: expand output to hold whole of both imagesbackground
: colour for new pixels
Insert sub
into main
at position x
, y
.
Normally out
shows the whole of main
. If expand
is TRUE then out
is
made large enough to hold all of main
and sub
.
Any areas of out
not coming from
either main
or sub
are set to background
(default 0).
If sub
overlaps main
,
sub
will appear on top of main
.
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 (see table Smallest common format in
arithmetic).See also: vips_join()
, vips_embed()
, vips_extract_area()
.
[method]
vips_join ()
int vips_join (VipsImage *in1
,VipsImage *in2
,VipsImage **out
,VipsDirection direction
,...
);
Optional arguments:
expand
:TRUE
to expand the output image to hold all of the input pixelsshim
: space between images, in pixelsbackground
: background ink colouralign
: low, centre or high alignment
Join in1
and in2
together, left-right or up-down depending on the value
of direction
.
If one is taller or wider than the
other, out
will be has high as the smaller. If expand
is TRUE
, then
the output will be expanded to contain all of the input pixels.
Use align
to set the edge that the images align on. By default, they align
on the edge with the lower value coordinate.
Use background
to set the colour of any pixels in out
which are not
present in either in1
or in2
.
Use shim
to set the spacing between the images. By default this is 0.
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 (see table Smallest common format in
arithmetic).If you are going to be joining many thousands of images in a regular
grid, vips_arrayjoin()
is a better choice.
See also: vips_arrayjoin()
, vips_insert()
.
vips_arrayjoin ()
int vips_arrayjoin (VipsImage **in
,VipsImage **out
,int n
,...
);
Optional arguments:
across
:gint
, number of images per rowshim
:gint
, space between images, in pixelsbackground
: VipsArrayDouble, background ink colourhalign
: VipsAlign, low, centre or high alignmentvalign
: VipsAlign, low, centre or high alignmenthspacing
:gint
, horizontal distance between imagesvspacing
:gint
, vertical distance between images
Lay out the images in in
in a grid. The grid is across
images across and
however high is necessary to use up all of in
. Images are set down
left-to-right and top-to-bottom. across
defaults to n
.
Each input image is placed with a box of size hspacing
by vspacing
pixels and cropped. These default to the largest width and largest height
of the input images.
Space between images is filled with background
. This defaults to 0
(black).
Images are positioned within their hspacing
by vspacing
box at low,
centre or high coordinate values, controlled by halign
and valign
. These
default to left-top.
Boxes are joined and separated by shim
pixels. This defaults to 0.
If the number of bands in the input images differs, all but 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 n-band images are operated upon.
The input images are cast up to the smallest common type (see table Smallest common format in
arithmetic).vips_colourspace() can be useful for moving the images to a common colourspace for compositing.
See also: vips_join()
, vips_insert()
, vips_colourspace()
.
vips_extract_area ()
int vips_extract_area (VipsImage *in
,VipsImage **out
,int left
,int top
,int width
,int height
,...
);
Extract an area from an image. The area must fit within in
.
See also: vips_extract_bands()
, vips_smartcrop()
.
[method]
vips_crop ()
int vips_crop (VipsImage *in
,VipsImage **out
,int left
,int top
,int width
,int height
,...
);
A synonym for vips_extract_area()
.
See also: vips_extract_bands()
, vips_smartcrop()
.
[method]
vips_smartcrop ()
int vips_smartcrop (VipsImage *in
,VipsImage **out
,int width
,int height
,...
);
Optional arguments:
interesting
: VipsInteresting to use to find interesting areas (default: VIPS_INTERESTING_ATTENTION)premultiplied
:gboolean
, input image already has premultiplied alphaattention_x
:gint
, horizontal position of attention centre when using attention based croppingattention_y
:gint
, vertical position of attention centre when using attention based cropping
Crop an image down to a specified width and height by removing boring parts.
Use interesting
to pick the method vips uses to decide which bits of the
image should be kept.
You can test xoffset / yoffset on out
to find the location of the crop
within the input image.
See also: vips_extract_area()
.
[method]
vips_extract_band ()
int vips_extract_band (VipsImage *in
,VipsImage **out
,int band
,...
);
Optional arguments:
n
: number of bands to extract
Extract a band or bands from an image. Extracting out of range is an error.
See also: vips_extract_area()
.
[method]
vips_replicate ()
int vips_replicate (VipsImage *in
,VipsImage **out
,int across
,int down
,...
);
Repeats an image many times.
See also: vips_extract_area()
.
[method]
vips_grid ()
int vips_grid (VipsImage *in
,VipsImage **out
,int tile_height
,int across
,int down
,...
);
Chop a tall thin image up into a set of tiles, lay the tiles out in a grid.
The input image 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 in
. The tiles are then rearranged into a grid
across
tiles across and down
tiles down in row-major order.
Supplying tile_height
, across
and down
is not strictly necessary, we
only really need two of these. Requiring three is a double-check that the
image has the expected geometry.
See also: vips_embed()
, vips_insert()
, vips_join()
.
[method]
vips_transpose3d ()
int vips_transpose3d (VipsImage *in
,VipsImage **out
,...
);
Optional arguments:
page_height
:gint
, size of each input page
Transpose a volumetric image.
Volumetric images are very tall, thin images, with the metadata item VIPS_META_PAGE_HEIGHT set to the height of each sub-image.
This operation swaps the two major dimensions, so that page N in the output contains the Nth scanline, in order, from each input page.
You can override the VIPS_META_PAGE_HEIGHT metadata item with the optional
page_height
parameter.
VIPS_META_PAGE_HEIGHT in the output image is the number of pages in the input image.
See also: vips_grid()
.
[method]
vips_wrap ()
int vips_wrap (VipsImage *in
,VipsImage **out
,...
);
Optional arguments:
x
: horizontal displacementy
: vertical displacement
Slice an image up and move the segments about so that the pixel that was
at 0, 0 is now at x
, y
. If x
and y
are not set, they default to the
centre of the image.
See also: vips_embed()
, vips_replicate()
.
[method]
vips_rot ()
int vips_rot (VipsImage *in
,VipsImage **out
,VipsAngle angle
,...
);
Rotate in
by a multiple of 90 degrees.
Use vips_similarity()
to rotate by an arbitrary angle. vips_rot45()
is
useful for rotating convolution masks by 45 degrees.
See also: vips_flip()
, vips_similarity()
, vips_rot45()
.
[method]
vips_rot90 ()
int vips_rot90 (VipsImage *in
,VipsImage **out
,...
);
Rotate in
by 90 degrees clockwise. A convenience function over vips_rot()
.
See also: vips_rot()
.
vips_rot180 ()
int vips_rot180 (VipsImage *in
,VipsImage **out
,...
);
Rotate in
by 180 degrees. A convenience function over vips_rot()
.
See also: vips_rot()
.
[method]
vips_rot270 ()
int vips_rot270 (VipsImage *in
,VipsImage **out
,...
);
Rotate in
by 270 degrees clockwise. A convenience function over vips_rot()
.
See also: vips_rot()
.
[method]
vips_rot45 ()
int vips_rot45 (VipsImage *in
,VipsImage **out
,...
);
Optional arguments:
angle
: VipsAngle45 rotation angle
Rotate in
by a multiple of 45 degrees. Odd-length sides and square images
only.
This operation is useful for rotating convolution masks. Use
vips_similarity()
to rotate images by arbitrary angles.
See also: vips_rot()
, vips_similarity()
.
[method]
vips_autorot_remove_angle ()
void
vips_autorot_remove_angle (VipsImage *image
);
Remove the orientation tag on image
. Also remove any exif orientation tags.
You must vips_copy()
the image before calling this function since it
modifies metadata.
[method]
vips_autorot ()
int vips_autorot (VipsImage *in
,VipsImage **out
,...
);
Optional arguments:
angle
: output VipsAngle the image was rotated byflip
: outputgboolean
whether the image was flipped
Look at the image metadata and rotate and flip the image to make it
upright. The VIPS_META_ORIENTATION tag is removed from out
to prevent
accidental double rotation.
Read angle
to find the amount the image was rotated by. Read flip
to
see if the image was also flipped.
[method]
vips_zoom ()
int vips_zoom (VipsImage *in
,VipsImage **out
,int xfac
,int yfac
,...
);
Zoom an image by repeating pixels. This is fast nearest-neighbour zoom.
See also: vips_affine()
, vips_subsample()
.
[method]
vips_subsample ()
int vips_subsample (VipsImage *in
,VipsImage **out
,int xfac
,int yfac
,...
);
Optional arguments:
point
: turn on point sample mode
Subsample an image by an integer fraction. This is fast, nearest-neighbour shrink.
For small horizontal shrinks, this operation will fetch lines of pixels
from in
and then subsample that line. For large shrinks it will fetch
single pixels.
If point
is set, in
will always be sampled in points. This can be faster
if the previous operations in the pipeline are very slow.
See also: vips_affine()
, vips_shrink()
, vips_zoom()
.
[method]
vips_cast ()
int vips_cast (VipsImage *in
,VipsImage **out
,VipsBandFormat format
,...
);
Optional arguments:
shift
:gboolean
, integer values are shifted
Convert in
to format
. You can convert between any pair of formats.
Floats are truncated (not rounded). Out of range values are clipped.
Casting from complex to real returns the real part.
If shift
is TRUE
, integer values are shifted up and down. For example,
casting from unsigned 8 bit to unsigned 16 bit would
shift every value left by 8 bits. The bottom bit is copied into the new
bits, so 255 would become 65535.
See also: vips_scale()
, vips_complexform()
, vips_real()
, vips_imag()
,
vips_cast_uchar()
, vips_msb()
.
[method]
vips_cast_uchar ()
int vips_cast_uchar (VipsImage *in
,VipsImage **out
,...
);
Convert in
to VIPS_FORMAT_UCHAR. See vips_cast()
.
[method]
vips_cast_char ()
int vips_cast_char (VipsImage *in
,VipsImage **out
,...
);
Convert in
to VIPS_FORMAT_CHAR. See vips_cast()
.
[method]
vips_cast_ushort ()
int vips_cast_ushort (VipsImage *in
,VipsImage **out
,...
);
Convert in
to VIPS_FORMAT_USHORT. See vips_cast()
.
[method]
vips_cast_short ()
int vips_cast_short (VipsImage *in
,VipsImage **out
,...
);
Convert in
to VIPS_FORMAT_SHORT. See vips_cast()
.
[method]
vips_cast_uint ()
int vips_cast_uint (VipsImage *in
,VipsImage **out
,...
);
Convert in
to VIPS_FORMAT_UINT. See vips_cast()
.
[method]
vips_cast_int ()
int vips_cast_int (VipsImage *in
,VipsImage **out
,...
);
Convert in
to VIPS_FORMAT_INT. See vips_cast()
.
[method]
vips_cast_float ()
int vips_cast_float (VipsImage *in
,VipsImage **out
,...
);
Convert in
to VIPS_FORMAT_FLOAT. See vips_cast()
.
[method]
vips_cast_double ()
int vips_cast_double (VipsImage *in
,VipsImage **out
,...
);
Convert in
to VIPS_FORMAT_DOUBLE. See vips_cast()
.
[method]
vips_cast_complex ()
int vips_cast_complex (VipsImage *in
,VipsImage **out
,...
);
Convert in
to VIPS_FORMAT_COMPLEX. See vips_cast()
.
[method]
vips_cast_dpcomplex ()
int vips_cast_dpcomplex (VipsImage *in
,VipsImage **out
,...
);
Convert in
to VIPS_FORMAT_DPCOMPLEX. See vips_cast()
.
[method]
vips_scale ()
int vips_scale (VipsImage *in
,VipsImage **out
,...
);
Optional arguments:
log
: log scale pixelsexp
: exponent for log scale
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.
If log
is set, transform with log10(1.0 + pow(x, exp
)) + .5,
then scale so max == 255. By default, exp
is 0.25.
See also: vips_cast()
.
[method]
vips_msb ()
int vips_msb (VipsImage *in
,VipsImage **out
,...
);
Optional arguments:
band
:gint
, msb just this band
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.
Use band
to make a one-band 8-bit image.
This operator also works for LABQ coding.
See also: vips_scale()
, vips_cast()
.
[method]
vips_byteswap ()
int vips_byteswap (VipsImage *in
,VipsImage **out
,...
);
Swap the byte order in an image.
See also: vips_rawload()
.
[method]
vips_bandjoin ()
int vips_bandjoin (VipsImage **in
,VipsImage **out
,int n
,...
);
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.
If the images differ in size, the smaller images are enlarged to match the larger by adding zero pixels along the bottom and right.
The input images are cast up to the smallest common type (see table Smallest common format in
arithmetic).See also: vips_insert()
.
vips_bandjoin2 ()
int vips_bandjoin2 (VipsImage *in1
,VipsImage *in2
,VipsImage **out
,...
);
Join a pair of images together, bandwise. See vips_bandjoin()
.
vips_bandjoin_const ()
int vips_bandjoin_const (VipsImage *in
,VipsImage **out
,double *c
,int n
,...
);
Append a set of constant bands to an image.
See also: vips_bandjoin()
.
[method]
vips_bandjoin_const1 ()
int vips_bandjoin_const1 (VipsImage *in
,VipsImage **out
,double c
,...
);
Append a single constant band to an image.
[method]
vips_bandrank ()
int vips_bandrank (VipsImage **in
,VipsImage **out
,int n
,...
);
Optional arguments:
index
: pick this index from list of sorted values
Sorts the images in
band-element-wise, then outputs an
image in which each band element is selected from the sorted list by the
index
parameter. For example, if index
is zero, then each output band element will be the minimum of all the
corresponding input band elements.
By default, index
is -1, meaning pick the median value.
It works for any uncoded, non-complex image type. Images are cast up to the smallest common-format.
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.
Smaller input images are expanded by adding black pixels.
See also: vips_rank()
.
vips_bandfold ()
int vips_bandfold (VipsImage *in
,VipsImage **out
,...
);
Optional arguments:
factor
: fold by this factor
Fold up an image horizontally: width is collapsed into bands.
Use factor
to set how much to fold by: factor
3, for example, will make
the output image three times narrower than the input, and with three times
as many bands. By default the whole of the input width is folded up.
See also: vips_csvload()
, vips_bandunfold()
.
[method]
vips_bandunfold ()
int vips_bandunfold (VipsImage *in
,VipsImage **out
,...
);
Optional arguments:
factor
: unfold by this factor
Unfold image bands into x axis.
Use factor
to set how much to unfold by: factor
3, for example, will make
the output image three times wider than the input, and with one third
as many bands. By default, all bands are unfolded.
See also: vips_csvload()
, vips_bandfold()
.
[method]
vips_bandbool ()
int vips_bandbool (VipsImage *in
,VipsImage **out
,VipsOperationBoolean boolean
,...
);
Perform various boolean operations across the bands of an image. For example, a three-band uchar image operated on with VIPS_OPERATION_BOOLEAN_AND will produce a one-band uchar image where each pixel is the bitwise and of the band elements of the corresponding pixel in the input image.
The output image is the same format as the input image for integer types. Float types are cast to int before processing. Complex types are not supported.
The output image always has one band.
This operation is useful in conjunction with vips_relational()
. You can use
it to see if all image bands match exactly.
See also: vips_boolean_const()
.
[method]
vips_bandand ()
int vips_bandand (VipsImage *in
,VipsImage **out
,...
);
Perform VIPS_OPERATION_BOOLEAN_AND on an image. See
vips_bandbool()
.
[method]
vips_bandor ()
int vips_bandor (VipsImage *in
,VipsImage **out
,...
);
Perform VIPS_OPERATION_BOOLEAN_OR on an image. See
vips_bandbool()
.
[method]
vips_bandeor ()
int vips_bandeor (VipsImage *in
,VipsImage **out
,...
);
Perform VIPS_OPERATION_BOOLEAN_EOR on an image. See
vips_bandbool()
.
[method]
vips_bandmean ()
int vips_bandmean (VipsImage *in
,VipsImage **out
,...
);
This operation writes 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.
See also: vips_add()
, vips_avg()
, vips_recomb()
[method]
vips_recomb ()
int vips_recomb (VipsImage *in
,VipsImage **out
,VipsImage *m
,...
);
This operation recombines an image's bands. Each pixel in in
is treated as
an n-element vector, where n is the number of bands in in
, and multiplied by
the n x m matrix m
to produce the m-band image out
.
out
is always float, unless in
is double, in which case out
is double
too. No complex images allowed.
It's useful for various sorts of colour space conversions.
See also: vips_bandmean()
.
[method]
vips_ifthenelse ()
int vips_ifthenelse (VipsImage *cond
,VipsImage *in1
,VipsImage *in2
,VipsImage **out
,...
);
Optional arguments:
blend
: blend smoothly betweenin1
andin2
This operation scans the condition image cond
and uses it to select pixels from either the then image in1
or the else
image in2
. Non-zero means in1
, 0 means in2
.
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 in1
and in2
are cast up to the smallest common format. cond
is
cast to uchar.
If the images differ in size, the smaller images are enlarged to match the largest by adding zero pixels along the bottom and right.
If blend
is TRUE
, then values in out
are smoothly blended between in1
and in2
using the formula:
out
= (cond
/ 255) * in1
+ (1 - cond
/ 255) * in2
See also: vips_equal()
.
vips_switch ()
int vips_switch (VipsImage **tests
,VipsImage **out
,int n
,...
);
The tests
images are evaluated and at each point the index of the first
non-zero value is written to out
. If all tests
are false, the value
(n
+ 1) is written.
Images in tests
must have one band. They are expanded to the
bounding box of the set of images in tests
, and that size is used for
out
. tests
can have up to 255 elements.
Combine with vips_case()
to make an efficient multi-way vips_ifthenelse()
.
See also: vips_maplut()
, vips_case()
, vips_ifthenelse()
.
vips_flatten ()
int vips_flatten (VipsImage *in
,VipsImage **out
,...
);
Optional arguments:
background
: VipsArrayDouble colour for new pixelsmax_alpha
:gdouble
, maximum value for alpha
Take the last band of in
as an alpha and use it to blend the
remaining channels with background
.
The alpha channel is 0 - max_alpha
, where max_alpha
means 100% image
and 0 means 100% background. background
defaults to zero (black).
max_alpha
has the default value 255, or 65535 for images tagged as
VIPS_INTERPRETATION_RGB16 or
VIPS_INTERPRETATION_GREY16.
Useful for flattening PNG images to RGB.
Non-complex images only.
See also: vips_premultiply()
, vips_pngload()
.
[method]
vips_addalpha ()
int vips_addalpha (VipsImage *in
,VipsImage **out
,...
);
Append an alpha channel.
See also: vips_image_hasalpha()
.
[method]
vips_premultiply ()
int vips_premultiply (VipsImage *in
,VipsImage **out
,...
);
Optional arguments:
max_alpha
:gdouble
, maximum value for alpha
Premultiplies any alpha channel. The final band is taken to be the alpha and the bands are transformed as:
1 2 3 |
alpha = clip(0, in[in.bands - 1], @max_alpha); norm = alpha / @max_alpha; out = [in[0] * norm, ..., in[in.bands - 1] * norm, alpha]; |
So for an N-band image, the first N - 1 bands are multiplied by the clipped and normalised final band, the final band is clipped. If there is only a single band, the image is passed through unaltered.
The result is VIPS_FORMAT_FLOAT unless the input format is VIPS_FORMAT_DOUBLE, in which case the output is double as well.
max_alpha
has the default value 255, or 65535 for images tagged as
VIPS_INTERPRETATION_RGB16 or
VIPS_INTERPRETATION_GREY16.
Non-complex images only.
See also: vips_unpremultiply()
, vips_flatten()
.
[method]
vips_unpremultiply ()
int vips_unpremultiply (VipsImage *in
,VipsImage **out
,...
);
Optional arguments:
max_alpha
:gdouble
, maximum value for alphaalpha_band
:gint
, band containing alpha data
Unpremultiplies any alpha channel.
Band alpha_band
(by default the final band) contains the alpha and all
other bands are transformed as:
1 2 3 4 5 6 |
alpha = (int) clip(0, in[in.bands - 1], @max_alpha); norm = (double) alpha / @max_alpha; if (alpha == 0) out = [0, ..., 0, alpha]; else out = [in[0] / norm, ..., in[in.bands - 1] / norm, alpha]; |
So for an N-band image, the first N - 1 bands are divided by the clipped and normalised final band, the final band is clipped. If there is only a single band, the image is passed through unaltered.
The result is VIPS_FORMAT_FLOAT unless the input format is VIPS_FORMAT_DOUBLE, in which case the output is double as well.
max_alpha
has the default value 255, or 65535 for images tagged as
VIPS_INTERPRETATION_RGB16 or
VIPS_INTERPRETATION_GREY16.
Non-complex images only.
See also: vips_premultiply()
, vips_flatten()
.
[method]
vips_composite ()
int vips_composite (VipsImage **in
,VipsImage **out
,int n
,int *mode
,...
);
Optional arguments:
compositing_space
: VipsInterpretation to composite inpremultiplied
:gboolean
, images are already premultipliedx
: VipsArrayInt, position of subimagesy
: VipsArrayInt, position of subimages
Composite an array of images together.
Images are placed in a stack, with in
[0] at the bottom and in
[n
- 1] at
the top. Pixels are blended together working from the bottom upwards, with
the blend mode at each step being set by the corresponding VipsBlendMode
in mode
.
Images are transformed to a compositing space before processing. This is VIPS_INTERPRETATION_sRGB, VIPS_INTERPRETATION_B_W, VIPS_INTERPRETATION_RGB16, or VIPS_INTERPRETATION_GREY16 by default, depending on how many bands and bits the input images have. You can select any other space, such as VIPS_INTERPRETATION_LAB or VIPS_INTERPRETATION_scRGB.
The output image is in the compositing space. It will always be VIPS_FORMAT_FLOAT unless one of the inputs is VIPS_FORMAT_DOUBLE, in which case the output will be double as well.
Complex images are not supported.
The output image will always have an alpha band. A solid alpha is added to any input missing an alpha.
The images do not need to match in size or format. They will be expanded to
the smallest common size and format in the usual way. Images are positioned
using the x
and y
parameters, if set.
Image are normally treated as unpremultiplied, so this operation can be used
directly on PNG images. If your images have been through vips_premultiply()
,
set premultiplied
.
See also: vips_insert()
.
Parameters
in |
array of input images. |
[array length=n][transfer none] |
out |
output image. |
[out] |
n |
number of input images |
|
mode |
array of ( |
|
... |
|
vips_composite2 ()
int vips_composite2 (VipsImage *base
,VipsImage *overlay
,VipsImage **out
,VipsBlendMode mode
,...
);
Optional arguments:
compositing_space
: VipsInterpretation to composite inpremultiplied
:gboolean
, images are already premultipliedx
:gint
, position of overlayy
:gint
, position of overlay
Composite overlay
on top of base
with mode
. See vips_composite()
.
[method]
vips_falsecolour ()
int vips_falsecolour (VipsImage *in
,VipsImage **out
,...
);
Force in
to 1 band, 8-bit, then transform to
a 3-band 8-bit image with a false colour
map. The map is supposed to make small differences in brightness more
obvious.
See also: vips_maplut()
.
[method]
vips_gamma ()
int vips_gamma (VipsImage *in
,VipsImage **out
,...
);
Optional arguments:
exponent
: gamma, default 1.0 / 2.4
Calculate in
** (1 / exponent
), normalising to the maximum range of the
input type. For float types use 1.0 as the maximum.
See also: vips_identity()
, vips_pow_const1()
, vips_maplut()
[method]
Types and Values
enum VipsExtend
See vips_embed()
, vips_conv()
, vips_affine()
and so on.
When the edges of an image are extended, you can specify how you want the extension done.
VIPS_EXTEND_BLACK --- new pixels are black, ie. all bits are zero.
VIPS_EXTEND_COPY --- each new pixel takes the value of the nearest edge pixel
VIPS_EXTEND_REPEAT --- the image is tiled to fill the new area
VIPS_EXTEND_MIRROR --- the image is reflected and tiled to reduce hash edges
VIPS_EXTEND_WHITE --- new pixels are white, ie. all bits are set
VIPS_EXTEND_BACKGROUND --- colour set from the background
property
We have to specify the exact value of each enum member since we have to keep these frozen for back compat with vips7.
See also: vips_embed()
.
enum VipsCompassDirection
A direction on a compass. Used for vips_gravity()
, for example.
enum VipsDirection
See vips_flip()
, vips_join()
and so on.
Operations like vips_flip()
need to be told whether to flip left-right or
top-bottom.
See also: vips_flip()
, vips_join()
.
enum VipsAlign
See vips_join()
and so on.
Operations like vips_join()
need to be told whether to align images on the
low or high coordinate edge, or centre.
See also: vips_join()
.
enum VipsAngle45
See vips_rot45()
and so on.
Fixed rotate angles.
See also: vips_rot45()
.
enum VipsInteresting
Pick the algorithm vips uses to decide image "interestingness". This is used
by vips_smartcrop()
, for example, to decide what parts of the image to
keep.
VIPS_INTERESTING_NONE and VIPS_INTERESTING_LOW mean the same -- the crop is positioned at the top or left. VIPS_INTERESTING_HIGH positions at the bottom or right.
See also: vips_smartcrop()
.
enum VipsBlendMode
The various Porter-Duff and PDF blend modes. See vips_composite()
,
for example.
The Cairo docs have a nice explanation of all the blend modes:
https://www.cairographics.org/operators
The non-separable modes are not implemented.
Members
where the second object is drawn, the first is removed |
||
the second object is drawn as if nothing were below |
||
the image shows what you would expect if you held two semi-transparent slides on top of each other |
||
the first object is removed completely, the second is only drawn where the first was |
||
the second is drawn only where the first isn't |
||
this leaves the first object mostly intact, but mixes both objects in the overlapping area |
||
leaves the first object untouched, the second is discarded completely |
||
like OVER, but swaps the arguments |
||
like IN, but swaps the arguments |
||
like OUT, but swaps the arguments |
||
like ATOP, but swaps the arguments |
||
something like a difference operator |
||
a bit like adding the two images |
||
a bit like the darker of the two |
||
at least as dark as the darker of the two inputs |
||
at least as light as the lighter of the inputs |
||
multiplies or screens colors, depending on the lightness |
||
the darker of each component |
||
the lighter of each component |
||
brighten first by a factor second |
||
darken first by a factor of second |
||
multiply or screen, depending on lightness |
||
darken or lighten, depending on lightness |
||
difference of the two |
||
somewhat like DIFFERENCE, but lower-contrast |
||