conversion

conversion — convert images in some way: change band format, change header, insert, extract, join

Stability Level

Stable, unless otherwise indicated

Synopsis

#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,
                                                         ...);

Object Hierarchy

  GEnum
   +----VipsAlign
  GEnum
   +----VipsAngle
  GEnum
   +----VipsCacheStrategy
  GEnum
   +----VipsDirection
  GEnum
   +----VipsExtend

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.

Details

enum VipsAlign

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().

VIPS_ALIGN_LOW

align low coordinate edge

VIPS_ALIGN_CENTRE

align centre

VIPS_ALIGN_HIGH

align high coordinate edge

VIPS_ALIGN_LAST


enum VipsAngle

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().

VIPS_ANGLE_0

no rotate

VIPS_ANGLE_90

90 degrees anti-clockwise

VIPS_ANGLE_180

180 degree rotate

VIPS_ANGLE_270

90 degrees clockwise

VIPS_ANGLE_LAST


enum VipsCacheStrategy

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().

VIPS_CACHE_RANDOM

expect random access

VIPS_CACHE_SEQUENTIAL

expect sequential access

VIPS_CACHE_LAST


enum VipsDirection

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().

VIPS_DIRECTION_HORIZONTAL

left-right

VIPS_DIRECTION_VERTICAL

top-bottom

VIPS_DIRECTION_LAST


enum VipsExtend

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().

VIPS_EXTEND_BLACK

extend with black (all 0) pixels

VIPS_EXTEND_COPY

copy the image edges

VIPS_EXTEND_REPEAT

repeat the whole image

VIPS_EXTEND_MIRROR

mirror the whole image

VIPS_EXTEND_WHITE

extend with white (all bits set) pixels

VIPS_EXTEND_BACKGROUND

extend with colour from the background property

VIPS_EXTEND_LAST


im_copy_file ()

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().

in :

input image

out :

output image

Returns :

0 on success, -1 on error

im_falsecolour ()

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().

in :

input image

out :

output image

Returns :

0 on success, -1 on error

im_gaussnoise ()

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().

out :

output image

x :

output width

y :

output height

mean :

average value in output

sigma :

standard deviation in output

Returns :

0 on success, -1 on error

im_grid ()

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().

in :

input image

out :

output image

tile_height :

chop into tiles this high

across :

tiles across

down :

tiles down

Returns :

0 on success, -1 on error

im_insertset ()

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().

main :

big image

sub :

small image

out :

output image

n :

number of positions

x :

left positions of sub

y :

top positions of sub

Returns :

0 on success, -1 on error

im_msb ()

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().

in :

input image

out :

output image

Returns :

0 on success, -1 on error

im_msb_band ()

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().

in :

input image

out :

output image

band :

select this band

Returns :

0 on success, -1 on error

im_scale ()

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().

in :

input image

out :

output image

Returns :

0 on success, -1 on error

im_scaleps ()

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().

in :

input image

out :

output image

Returns :

0 on success, -1 on error

im_subsample ()

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().

in :

input image

out :

output image

xshrink :

horizontal shrink factor

yshrink :

vertical shrink factor

Returns :

0 on success, -1 on error.

im_system ()

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().

im :

image to run command on

cmd :

command to run

out :

stdout of command is returned here

Returns :

0 on success, -1 on error

im_system_image ()

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