![]() |
![]() |
![]() |
VIPS Reference Manual | ![]() |
---|---|---|---|---|
Top | Description | Object Hierarchy |
conversionconversion — convert images in some way: change band format, change header, insert, extract, join |
#include <vips/vips.h> enum VipsAlign; enum VipsAngle; enum VipsCacheStrategy; enum VipsDirection; enum VipsExtend; int im_copy_file (VipsImage *in
,VipsImage *out
); int im_falsecolour (VipsImage *in
,VipsImage *out
); int im_gaussnoise (VipsImage *out
,int x
,int y
,double mean
,double sigma
); int im_grid (VipsImage *in
,VipsImage *out
,int tile_height
,int across
,int down
); int im_insertset (VipsImage *main
,VipsImage *sub
,VipsImage *out
,int n
,int *x
,int *y
); int im_msb (VipsImage *in
,VipsImage *out
); int im_msb_band (VipsImage *in
,VipsImage *out
,int band
); int im_scale (VipsImage *in
,VipsImage *out
); int im_scaleps (VipsImage *in
,VipsImage *out
); int im_subsample (VipsImage *in
,VipsImage *out
,int xshrink
,int yshrink
); int im_system (VipsImage *im
,const char *cmd
,char **out
); VipsImage * im_system_image (VipsImage *im
,const char *in_format
,const char *out_format
,const char *cmd_format
,char **log
); int im_text (VipsImage *out
,const char *text
,const char *font
,int width
,int alignment
,int dpi
); int im_wrap (VipsImage *in
,VipsImage *out
,int x
,int y
); int im_zoom (VipsImage *in
,VipsImage *out
,int xfac
,int yfac
); int vips_bandand (VipsImage *in
,VipsImage **out
,...
); int vips_bandbool (VipsImage *in
,VipsImage **out
,VipsOperationBoolean operation
,...
); int vips_bandeor (VipsImage *in
,VipsImage **out
,...
); int vips_bandjoin (VipsImage **in
,VipsImage **out
,int n
,...
); int vips_bandjoin2 (VipsImage *in1
,VipsImage *in2
,VipsImage **out
,...
); int vips_bandmean (VipsImage *in
,VipsImage **out
,...
); int vips_bandor (VipsImage *in
,VipsImage **out
,...
); int vips_black (VipsImage **out
,int width
,int height
,...
); int vips_cache (VipsImage *in
,VipsImage **out
,...
); int vips_cast (VipsImage *in
,VipsImage **out
,VipsBandFormat format
,...
); int vips_cast_char (VipsImage *in
,VipsImage **out
,...
); int vips_cast_complex (VipsImage *in
,VipsImage **out
,...
); int vips_cast_double (VipsImage *in
,VipsImage **out
,...
); int vips_cast_dpcomplex (VipsImage *in
,VipsImage **out
,...
); int vips_cast_float (VipsImage *in
,VipsImage **out
,...
); int vips_cast_int (VipsImage *in
,VipsImage **out
,...
); int vips_cast_short (VipsImage *in
,VipsImage **out
,...
); int vips_cast_uchar (VipsImage *in
,VipsImage **out
,...
); int vips_cast_uint (VipsImage *in
,VipsImage **out
,...
); int vips_cast_ushort (VipsImage *in
,VipsImage **out
,...
); int vips_copy (VipsImage *in
,VipsImage **out
,...
); int vips_embed (VipsImage *in
,VipsImage **out
,int x
,int y
,int width
,int height
,...
); int vips_extract_area (VipsImage *input
,VipsImage **output
,int left
,int top
,int width
,int height
,...
); int vips_extract_band (VipsImage *input
,VipsImage **output
,int band
,...
); int vips_flatten (VipsImage *in
,VipsImage **out
,...
); int vips_flip (VipsImage *in
,VipsImage **out
,VipsDirection direction
,...
); int vips_ifthenelse (VipsImage *cond
,VipsImage *in1
,VipsImage *in2
,VipsImage **out
,...
); int vips_insert (VipsImage *main
,VipsImage *sub
,VipsImage **out
,int x
,int y
,...
); int vips_join (VipsImage *main
,VipsImage *sub
,VipsImage **out
,VipsDirection direction
,...
); int vips_linecache (VipsImage *in
,VipsImage **out
,...
); int vips_recomb (VipsImage *in
,VipsImage **out
,VipsImage *m
,...
); int vips_replicate (VipsImage *in
,VipsImage **out
,int across
,int down
,...
); int vips_rot (VipsImage *in
,VipsImage **out
,VipsAngle angle
,...
); int vips_sequential (VipsImage *in
,VipsImage **out
,...
); int vips_tilecache (VipsImage *in
,VipsImage **out
,...
);
GEnum +----VipsAlign
GEnum +----VipsAngle
GEnum +----VipsCacheStrategy
GEnum +----VipsDirection
GEnum +----VipsExtend
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.
typedef enum { VIPS_ALIGN_LOW, VIPS_ALIGN_CENTRE, VIPS_ALIGN_HIGH, VIPS_ALIGN_LAST } 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()
.
typedef enum { VIPS_ANGLE_0, VIPS_ANGLE_90, VIPS_ANGLE_180, VIPS_ANGLE_270, VIPS_ANGLE_LAST } VipsAngle;
See vips_rot()
and so on.
Fixed rotate angles.
See also: vips_rot()
.
typedef enum { VIPS_CACHE_RANDOM, VIPS_CACHE_SEQUENTIAL, VIPS_CACHE_LAST } VipsCacheStrategy;
See vips_tilecache()
and friends.
Used to hint to caches about the expected access pattern. RANDOM might mean LRU eviction, SEQUENTIAL might mean top-most eviction.
See also: vips_tilecache()
.
typedef enum { VIPS_DIRECTION_HORIZONTAL, VIPS_DIRECTION_VERTICAL, VIPS_DIRECTION_LAST } 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()
.
typedef enum { VIPS_EXTEND_BLACK, VIPS_EXTEND_COPY, VIPS_EXTEND_REPEAT, VIPS_EXTEND_MIRROR, VIPS_EXTEND_WHITE, VIPS_EXTEND_BACKGROUND, VIPS_EXTEND_LAST } 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()
.
extend with black (all 0) pixels | |
copy the image edges | |
repeat the whole image | |
mirror the whole image | |
extend with white (all bits set) pixels | |
extend with colour from the background property
|
|
int im_copy_file (VipsImage *in
,VipsImage *out
);
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 disc file is allocated in the same way as im_system_image()
.
The file is automatically deleted when out
is closed.
See also: im_copy()
, im_system_image()
.
|
input image |
|
output image |
Returns : |
0 on success, -1 on error |
int im_falsecolour (VipsImage *in
,VipsImage *out
);
Force in
to 1 band, 8-bit, then transform to
3-band 8-bit image with a false colour
map. The map is supposed to make small differences in brightness more
obvious.
See also: im_maplut()
.
|
input image |
|
output image |
Returns : |
0 on success, -1 on error |
int im_gaussnoise (VipsImage *out
,int x
,int y
,double mean
,double sigma
);
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.
See also: im_addgnoise()
, im_make_xy()
, im_text()
, im_black()
.
|
output image |
|
output width |
|
output height |
|
average value in output |
|
standard deviation in output |
Returns : |
0 on success, -1 on error |
int im_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.
See also: im_embed()
, im_insert()
, im_lrjoin()
.
|
input image |
|
output image |
|
chop into tiles this high |
|
tiles across |
|
tiles down |
Returns : |
0 on success, -1 on error |
int im_insertset (VipsImage *main
,VipsImage *sub
,VipsImage *out
,int n
,int *x
,int *y
);
Insert sub
repeatedly into main
at the positions listed in the arrays x
,
y
of length n
. out
is the same
size as main
. sub
is clipped against the edges of main
.
This operation is fast for large n
, but will use a memory buffer the size
of out
. 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 (see table Smallest common format in arithmetic).
See also: im_insert()
, im_lrjoin()
.
|
big image |
|
small image |
|
output image |
|
number of positions |
|
left positions of sub
|
|
top positions of sub
|
Returns : |
0 on success, -1 on error |
int im_msb (VipsImage *in
,VipsImage *out
);
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.
See also: im_msb_band()
.
|
input image |
|
output image |
Returns : |
0 on success, -1 on error |
int im_msb_band (VipsImage *in
,VipsImage *out
,int band
);
Turn any integer image to a single-band 8-bit unsigned char by discarding all but the most significant byte from the selected band. Signed values are converted to unsigned by adding 128.
This operator also works for LABQ coding.
See also: im_msb_band()
.
|
input image |
|
output image |
|
select this band |
Returns : |
0 on success, -1 on error |
int im_scale (VipsImage *in
,VipsImage *out
);
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.
See also: im_clip2fmt()
, im_scaleps()
.
|
input image |
|
output image |
Returns : |
0 on success, -1 on error |
int im_scaleps (VipsImage *in
,VipsImage *out
);
Scale a power spectrum. Transform with log10(1.0 + pow(x, 0.25)) + .5, then scale so max == 255.
See also: im_scale()
.
|
input image |
|
output image |
Returns : |
0 on success, -1 on error |
int im_subsample (VipsImage *in
,VipsImage *out
,int xshrink
,int yshrink
);
Subsample an image by an integer fraction. This is fast nearest-neighbour shrink.
See also: im_shrink()
, im_affinei()
, im_zoom()
.
|
input image |
|
output image |
|
horizontal shrink factor |
|
vertical shrink factor |
Returns : |
0 on success, -1 on error. |
int im_system (VipsImage *im
,const char *cmd
,char **out
);
im_system()
runs a command on an image, returning the command's output as a
string. The command is executed with popen()
, the first '%s
' in the
command being substituted for a filename.
If the IMAGE is a file on disc, then the filename will be the name of the real file. If the image is in memory, or the result of a computation, then a new file is created in the temporary area called something like "vips_XXXXXX.v", and that filename given to the command. The file is deleted when the command finishes.
See im_system_image()
for details on how VIPS selects a temporary
directory.
In all cases, log
must be freed with im_free()
.
See also: im_system_image()
.
|
image to run command on |
|
command to run |
|
stdout of command is returned here |
Returns : |
0 on success, -1 on error |
VipsImage * im_system_image (VipsImage *im
,const char *in_format
,const char *out_format
,const char *cmd_format
,char **log
);
im_system_image()
runs a command, passing an image in and getting an image
back. The command's stdout is returned in log
.
First, im
is written to a file. The filename is formed by substituting
something like "vips-49857-1" for the first %s
in in_format
, then
prepending "/tmp". If the environment variable TMPDIR is defined, it
can be used to set a different temporary directory. If in_format
is
something like "%s
.png", the file will be written in PNG format.
On Windows, if the environment variable TMPDIR is not defined, VIPS calls
GetTempPath()
to get the user's preferred temporary area. If that fails, it
defaults to C:\temp.
Next an output filename is created in the same way using out_format
. The
command string to run is made by substituting the first %s
in cmd_format
for the name of the input file and the second %s
for the output filename.
The command is executed with popen()
and the output captured in log
. If
the command fails, the temporary files are deleted and im_system_image()
returns NULL. log
is still set.
If the command succeeds, the input file is deleted, the output file opened, and returned. Closing the output image will automatically delete the file.
In all cases, log
must be freed with im_free()
.
For example, this call will run the ImageMagick convert program on an image, using JPEG files to pass images into and out of the convert command.
1 2 3 4 5 6 |