image

image — the VIPS image class

Stability Level

Stable, unless otherwise indicated

Synopsis

#include <vips/vips.h>

#define             IM_MAGIC_INTEL
#define             IM_MAGIC_SPARC
enum                VipsDemandStyle;
enum                VipsType;
enum                VipsBandFmt;
enum                VipsCoding;
                    VipsProgress;
                    VipsImage;
#define             IM_IMAGE_SIZEOF_ELEMENT             (I)
#define             IM_IMAGE_SIZEOF_PEL                 (I)
#define             IM_IMAGE_SIZEOF_LINE                (I)
#define             IM_IMAGE_N_ELEMENTS                 (I)
#define             IM_IMAGE_ADDR                       (I,
                                                         X,
                                                         Y)
const char *        im_get_argv0                        (void);
int                 im_init_world                       (const char *argv0);
GOptionGroup *      im_get_option_group                 (void);
const char *        im_version_string                   (void);
int                 im_version                          (int flag);
const char *        im_guess_prefix                     (const char *argv0,
                                                         const char *env_name);
const char *        im_guess_libdir                     (const char *argv0,
                                                         const char *env_name);
VipsImage *         im_open                             (const char *filename,
                                                         const char *mode);
#define             im_open_local                       (IM,
                                                         NAME,
                                                         MODE)
#define             im_open_local_array                 (IM,
                                                         OUT,
                                                         N,
                                                         NAME,
                                                         MODE)
int                 im_close                            (VipsImage *im);
void                im_invalidate                       (VipsImage *im);
void                im_initdesc                         (VipsImage *image,
                                                         int xsize,
                                                         int ysize,
                                                         int bands,
                                                         int bandbits,
                                                         VipsBandFmt bandfmt,
                                                         VipsCoding coding,
                                                         VipsType type,
                                                         float xres,
                                                         float yres,
                                                         int xo,
                                                         int yo);
int                 im_cp_desc                          (VipsImage *out,
                                                         VipsImage *in);
int                 im_cp_descv                         (VipsImage *out,
                                                         VipsImage *in1,
                                                         ...);
int                 im_cp_desc_array                    (VipsImage *out,
                                                         VipsImage *in[]);
VipsImage *         im_binfile                          (const char *name,
                                                         int xsize,
                                                         int ysize,
                                                         int bands,
                                                         int offset);
VipsImage *         im_image                            (void *buffer,
                                                         int xsize,
                                                         int ysize,
                                                         int bands,
                                                         VipsBandFmt bandfmt);

Description

The VIPS image class and associated types and macros.

Details

IM_MAGIC_INTEL

#define IM_MAGIC_INTEL (0xb6a6f208U)

The first four bytes of a VIPS file in Intel byte ordering.


IM_MAGIC_SPARC

#define IM_MAGIC_SPARC (0x08f2a6b6U)

The first four bytes of a VIPS file in SPARC byte ordering.


enum VipsDemandStyle

typedef enum {
	IM_SMALLTILE,	
	IM_FATSTRIP,
	IM_THINSTRIP,
	IM_ANY			
} VipsDemandStyle;

See im_demand_hint(). Operations can hint to the VIPS image IO system about the kind of demand geometry they prefer.

These demand styles are given below in order of increasing restrictiveness. When demanding output from a pipeline, im_generate() will use the most restrictive of the styles requested by the operations in the pipeline.

IM_THINSTRIP --- This operation would like to output strips the width of the image and a few pels high. This is option suitable for point-to-point operations, such as those in the arithmetic package.

This option is only efficient for cases where each output pel depends upon the pel in the corresponding position in the input image.

IM_FATSTRIP --- This operation would like to output strips the width of the image and as high as possible. This option is suitable for area operations which do not violently transform coordinates, such as im_conv().

IM_SMALLTILE --- This is the most general demand format. Output is demanded in small (around 100x100 pel) sections. This style works reasonably efficiently, even for bizzare operations like 45 degree rotate.

IM_ANY --- This image is not being demand-read from a disc file (even indirectly) so any demand style is OK. It's used for things like im_black() where the pixels are calculated.

See also: im_demand_hint().

IM_SMALLTILE

demand in small (typically 64x64 pixel) tiles

IM_FATSTRIP

demand in fat (typically 10 pixel high) strips

IM_THINSTRIP

demand in thin (typically 1 pixel high) strips

IM_ANY

demand geometry does not matter

enum VipsType

typedef enum {
	IM_TYPE_MULTIBAND = 0,
	IM_TYPE_B_W = 1,
	IM_TYPE_HISTOGRAM = 10,
	IM_TYPE_FOURIER = 24,
	IM_TYPE_XYZ = 12,
	IM_TYPE_LAB = 13,
	IM_TYPE_CMYK = 15,
	IM_TYPE_LABQ = 16,
	IM_TYPE_RGB = 17,
	IM_TYPE_UCS = 18,
	IM_TYPE_LCH = 19,
	IM_TYPE_LABS = 21,
	IM_TYPE_sRGB = 22,
	IM_TYPE_YXY = 23,
	IM_TYPE_RGB16 = 25,
	IM_TYPE_GREY16 = 26
} VipsType;

These values are set by operations as hints to user-interfaces built on top of VIPS to help them show images to the user in a meaningful way. Operations do not use these values to decide their action.

IM_TYPE_MULTIBAND

generic many-band image

IM_TYPE_B_W

some kind of single-band image

IM_TYPE_HISTOGRAM

a 1D image such as a histogram or lookup table

IM_TYPE_FOURIER

image is in fourier space

IM_TYPE_XYZ

the first three bands are colours in CIE XYZ colourspace

IM_TYPE_LAB

pixels are in CIE Lab space

IM_TYPE_CMYK

the first four bands are in CMYK space

IM_TYPE_LABQ

implies IM_CODING_LABQ

IM_TYPE_RGB

generic RGB space

IM_TYPE_UCS

a uniform colourspace based on CMC

IM_TYPE_LCH

pixels are in CIE LCh space

IM_TYPE_LABS

pixels are CIE LAB coded as three signed 16-bit values

IM_TYPE_sRGB

pixels are sRGB

IM_TYPE_YXY

pixels are CIE Yxy

IM_TYPE_RGB16

generic 16-bit RGB

IM_TYPE_GREY16

generic 16-bit mono

enum VipsBandFmt

typedef enum {
	IM_BANDFMT_NOTSET = -1,
	IM_BANDFMT_UCHAR = 0,
	IM_BANDFMT_CHAR = 1,
	IM_BANDFMT_USHORT = 2,
	IM_BANDFMT_SHORT = 3,
	IM_BANDFMT_UINT = 4,
	IM_BANDFMT_INT = 5,
	IM_BANDFMT_FLOAT = 6,
	IM_BANDFMT_COMPLEX = 7,
	IM_BANDFMT_DOUBLE = 8,
	IM_BANDFMT_DPCOMPLEX = 9,
	IM_BANDFMT_LAST = 10
} VipsBandFmt;

The format used for each band element.

Each corresponnds to a native C type for the current machine. For example, IM_BANDFMT_USHORT is unsigned short.

IM_BANDFMT_NOTSET

invalid setting

IM_BANDFMT_UCHAR

unsigned char format

IM_BANDFMT_CHAR

char format

IM_BANDFMT_USHORT

unsigned short format

IM_BANDFMT_SHORT

short format

IM_BANDFMT_UINT

unsigned int format

IM_BANDFMT_INT

int format

IM_BANDFMT_FLOAT

float format

IM_BANDFMT_COMPLEX

complex (two floats) format

IM_BANDFMT_DOUBLE

double float format

IM_BANDFMT_DPCOMPLEX

double complex (two double) format

IM_BANDFMT_LAST


enum VipsCoding

typedef enum {
	IM_CODING_NONE = 0,
	IM_CODING_LABQ = 2,
	IM_CODING_RAD = 6
} VipsCoding;

How pixels are coded.

Normally, pixels are uncoded and can be manipulated as you would expect. However some file formats code pixels for compression, and sometimes it's useful to be able to manipulate images in the coded format.

IM_CODING_NONE

pixels are not coded

IM_CODING_LABQ

pixels encode 3 float CIELAB values as 4 uchar

IM_CODING_RAD

pixels encode 3 float RGB as 4 uchar (Radiance coding)

VipsProgress

typedef struct {
	int run;		/* Time we have been running */
	int eta;		/* Estimated seconds of computation left */
	gint64 tpels;		/* Number of pels we expect to calculate */
	gint64 npels;		/* Number of pels calculated so far */
	int percent;		/* Percent complete */
	GTimer *start;		/* Start time */
} VipsProgress;

A structure available to eval callbacks giving information on evaluation progress. See im_add_eval_callback().

int run;

Time we have been running

int eta;

Estimated seconds of computation left

gint64 tpels;

Number of pels we expect to calculate

gint64 npels;

Number of pels calculated so far

int percent;

Percent complete

GTimer *start;

Start time

VipsImage

typedef struct {
	/* Fields from file header.
	 */
	int Xsize;		/* image width, in pixels */
	int Ysize;		/* image height, in pixels */
	int Bands;		/* number of image bands */
	VipsBandFmt BandFmt; /* #VipsBandFmt describing the pixel format */
	VipsCoding Coding; /* #VipsCoding describing the pixel coding */
	VipsType Type;		/* #VipsType hinting at pixel interpretation */
	float Xres;		/* horizontal pixels per millimetre */
	float Yres;		/* vertical pixels per millimetre */
	int Xoffset;		/* image origin hint */
	int Yoffset;		/* image origin hint */

	/* Derived fields that user can fiddle with.
	 */
	char *filename;		/* pointer to copy of filename */
	char *data;		/* start of image data for WIO */
	VipsProgress *time; /* evaluation progress */
	int kill;		/* set to non-zero to block partial eval */
} VipsImage;

An image. These can represent an image on disc, a memory buffer, an image in the process of being written to disc or a partially evaluated image in memory.

int Xsize;

image width, in pixels

int Ysize;

image height, in pixels

int Bands;

number of image bands

VipsBandFmt BandFmt;

VipsFormat describing the pixel type

VipsCoding Coding;

VipsCoding describing the pixel coding type

VipsType Type;

a VipsType hinting how the image pixels should be interpreted

float Xres;

horizontal pixels per millimetre

float Yres;

vertical pixels per millimetre

int Xoffset;

a hint giving the position of the origin in the image

int Yoffset;

a hint giving the position of the origin in the image

char *filename;

the disc file associated with this image, or NULL

char *data;

the pixel data associated with this image, or NULL

VipsProgress *time;

the evaluation progress associated with this image, or NULL

int kill;

set this to non-zero to block evaluation of this image

IM_IMAGE_SIZEOF_ELEMENT()

#define             IM_IMAGE_SIZEOF_ELEMENT(I)

I :

a VipsImage

Returns :

sizeof() a band element.

IM_IMAGE_SIZEOF_PEL()

#define             IM_IMAGE_SIZEOF_PEL(I)

I :

a VipsImage

Returns :

sizeof() a pixel.

IM_IMAGE_SIZEOF_LINE()

#define             IM_IMAGE_SIZEOF_LINE(I)

I :

a VipsImage

Returns :

sizeof() a scanline of pixels.

IM_IMAGE_N_ELEMENTS()

#define             IM_IMAGE_N_ELEMENTS(I)

I :

a VipsImage

Returns :

The number of band elements in a scanline.

IM_IMAGE_ADDR()

#define             IM_IMAGE_ADDR(I,X,Y)

This macro returns a pointer to a pixel in an image. It only works for images which are fully available in memory, so memory buffers and small mapped images only.

If DEBUG is defined, you get a version that checks bounds for you.

I :

a VipsImage

X :

x coordinate

Y :

y coordinate

Returns :

The address of pixel (x,y) in the image.

im_get_argv0 ()

const char *        im_get_argv0                        (void);

See also: im_init_world().

Returns :

a pointer to an internal copy of the argv0 string passed to im_init_world(). Do not free this value

im_init_world ()

int                 im_init_world                       (const char *argv0);

im_init_world() starts up the world of VIPS. You should call this on program startup before using any other VIPS operations. If you do not call im_init_world(), VIPS will call it for you when you use your first VIPS operation, but it may not be able to get hold of argv0 and VIPS may therefore be unable to find its data files. It is much better to call this function yourself.

im_init_world() does approximately the following:

  • initialises any libraries that VIPS is using, including GObject and the threading system, if neccessary

  • guesses where the VIPS data files are and sets up internationalisation --- see im_guess_prefix()

  • loads any plugins from $libdir/vips-x.y, where x and y are the major and minor version numbers for this VIPS.

Example:

int main( int argc, char **argv )
{
  if( im_init_world( argv[0] ) )
    error_exit( "unable to start VIPS" );

  return( 0 );
}

See also: im_get_option_group(), im_version(), im_guess_prefix(), im_guess_libdir().

argv0 :

name of application

Returns :

0 on success, -1 otherwise

im_get_option_group ()

GOptionGroup *      im_get_option_group                 (void);

im_get_option_group() returns a GOptionGroup containing various VIPS command-line options. It can be used with GOption to help parse argc/argv.

See also: im_version(), im_guess_prefix(), im_guess_libdir(), im_init_world().

Returns :

a GOptionGroup for VIPS, see GOption

im_version_string ()

const char *        im_version_string                   (void);

Get the VIPS version as a static string, including a build date and time. Do not free.

Returns :

a static version string

im_version ()

int                 im_version                          (int flag);

Get the major, minor or micro library version, with flag values 0, 1 and 2.

flag :

which field of the version to get

Returns :

library version number

im_guess_prefix ()

const char *        im_guess_prefix                     (const char *argv0,
                                                         const char *env_name);

im_guess_prefix() tries to guess the install directory. You should pass in the value of argv[0] (the name your program was run as) as a clue to help it out, plus the name of the environment variable you let the user override your package install area with (eg. "VIPSHOME").

On success, im_guess_prefix() returns the prefix it discovered, and as a side effect, sets the environment variable (if it's not set).

Don't free the return string!

See also: im_guess_libdir().

argv0 :

program name (typically argv[0])

env_name :

save prefix in this environment variable

Returns :

the install prefix as a static string, do not free.

im_guess_libdir ()

const char *        im_guess_libdir                     (const char *argv0,
                                                         const char *env_name);

im_guess_libdir() tries to guess the install directory (usually the configure libdir, or $prefix/lib). You should pass in the value of argv[0] (the name your program was run as) as a clue to help it out, plus the name of the environment variable you let the user override your package install area with (eg. "VIPSHOME").

On success, im_guess_libdir() returns the libdir it discovered, and as a side effect, sets the prefix environment variable (if it's not set).

Don't free the return string!

See also: im_guess_prefix().

argv0 :

program name (typically argv[0])

env_name :

save prefix in this environment variable

Returns :

the libdir as a static string, do not free.

im_open ()

VipsImage *         im_open                             (const char *filename,
                                                         const char *mode);

im_open() examines the mode string, and creates an appropriate IMAGE.

  • "r" opens the named file for reading. If the file is not in the native VIPS format for your machine, im_open() automatically converts the file for you in memory.

    For some large files (eg. TIFF) this may not be what you want, it can fill memory very quickly. Instead, you can either use "rd" mode (see below), or you can use the lower-level API and control the loading process yourself. See VipsFormat.

    im_open() can read files in most formats.

    Note that "r" mode works in at least two stages. It should return quickly and let you check header fields. It will only actually read in pixels when you first access them.

  • "rd" opens the named file for reading. If the uncompressed image is larger than a threshold and the file format does not support random access, rather than uncompressing to memory, im_open() will uncompress to a temporary disc file. This file will be automatically deleted when the IMAGE is closed.

    See im_system_image() for an explanation of how VIPS selects a location for the temporary file.

    The disc threshold can be set with the "--vips-disc-threshold" command-line argument, or the IM_DISC_THRESHOLD environment variable. The value is a simple integer, but can take a unit postfix of "k", "m" or "g" to indicate kilobytes, megabytes or gigabytes.

    For example:

            vips --vips-disc-threshold "500m" im_copy fred.tif fred.v
          

    will copy via disc if "fred.tif" is more than 500 Mbytes uncompressed. The default threshold is 100MB.

  • "w" opens the named file for writing. It looks at the file name suffix to determine the type to write -- for example:

            im_open( "fred.tif", "w" )
          

    will write in TIFF format.

  • "t" creates a temporary memory buffer image.

  • "p" creates a "glue" descriptor you can use to join two image processing operations together.

  • "rw" opens the named file for reading and writing. This will only work for VIPS files in a format native to your machine. It is only for paintbox-type applications.

See also: im_close(), VipsFormat

filename :

file to open

mode :

mode to open with

Returns :

the image descriptor on success and NULL on error.

im_open_local()

#define             im_open_local( IM, NAME, MODE )

Just like im_open(), but the IMAGE will be closed for you automatically when IM is closed.

See also: im_open(), im_close(), im_local().

IM :

image to open local to

NAME :

filename to open

MODE :

mode to open with

Returns :

a new IMAGE, or NULL on error

im_open_local_array()

#define             im_open_local_array( IM, OUT, N, NAME, MODE )

Just like im_open(), but opens an array of images. Handy for creating a set of temporary images for a function.

Example:

IMAGE *t[5];

if( im_open_local_array( out, t, 5, "some-temps", "p" ) ||
  im_add( a, b, t[0] ) ||
  im_invert( t[0], t[1] ) ||
  im_add( t[1], t[0], t[2] ) ||
  im_costra( t[2], out ) )
  return( -1 );

See also: im_open(), im_open_local(), im_local_array().

IM :

image to open local to

OUT :

array to fill with IMAGE

N :

array size

NAME :

filename to open

MODE :

mode to open with

Returns :

0 on sucess, or -1 on error

im_close ()

int                 im_close                            (VipsImage *im);

Frees all resources associated with im.

If there are open REGION s on im, close is delayed until the last region is freed.

See also: im_open().

im :

image to close

Returns :

0 on success and 1 on error.

im_invalidate ()

void                im_invalidate                       (VipsImage *im);

Invalidate all pixel caches on an IMAGE and any derived images. The "invalidate" callback is triggered for all invalidated images.

See also: im_add_invalidate_callback().

im :

IMAGE to invalidate

im_initdesc ()

void                im_initdesc                         (VipsImage *image,
                                                         int xsize,
                                                         int ysize,
                                                         int bands,
                                                         int bandbits,
                                                         VipsBandFmt bandfmt,
                                                         VipsCoding coding,
                                                         VipsType type,
                                                         float xres,
                                                         float yres,
                                                         int xo,
                                                         int yo);

A convenience function to set the header fields after creating an image. Normally you copy the fields from one of your input images with im_cp_desc() and then make any adjustments you need, but if you are creating an image from scratch, for example im_black() or im_jpeg2vips(), you do need to set all the fields yourself.

See also: im_cp_desc().

image :

image to init

xsize :

image width

ysize :

image height

bands :

image bands

bandbits :

ignored, just here for compatibility

bandfmt :

band format

coding :

image coding

type :

image type

xres :

horizontal resolution, pixels per millimetre

yres :

vertical resolution, pixels per millimetre

xo :

x offset

yo :

y offset

im_cp_desc ()

int                 im_cp_desc                          (VipsImage *out,
                                                         VipsImage *in);

Copy fields from in to out. A convenience function over im_cp_desc_array().

See also: im_cp_desc_array(), im_cp_descv().

out :

image to copy to

in :

image to copy from

Returns :

0 on success, -1 on error.

im_cp_descv ()

int                 im_cp_descv                         (VipsImage *out,
                                                         VipsImage *in1,
                                                         ...);

Copy fields from all the input images to the output image. A convenience function over im_cp_desc_array().

See also: im_cp_desc_array(), im_cp_desc().

out :

image to copy to

in1 :

first image to copy from

... :

NULL-terminated list of images to copy from

Returns :

0 on success, -1 on error.

im_cp_desc_array ()

int                 im_cp_desc_array                    (VipsImage *out,
                                                         VipsImage *in[]);

Copy fields from all the input images to the output image. There must be at least one input image. If you are making an image which has no input images (for example, im_black() or im_vips2jpeg()), use im_initdesc() instead.

The first input image is used to set the main fields of out (XSize, Coding and so on).

Metadata from all the image is merged on to out, with lower-numbered items overriding higher. So for example, if in[0] and in[1] both have an item called "icc-profile", it's the profile attached to in[0] that will end up on out.

Image history is completely copied from all in. out will have the history of all the intput images.

See also: im_cp_descv(), im_cp_desc().

out :

image to copy to

in :

NULL-terminated array of images to copy from

Returns :

0 on success, -1 on error.

im_binfile ()

VipsImage *         im_binfile                          (const char *name,
                                                         int xsize,
                                                         int ysize,
                                                         int bands,
                                                         int offset);

This function maps the named file and returns an IMAGE you can use to read it.

It returns an 8-bit image with bands bands. If the image is not 8-bit, use im_copy_set() to transform the descriptor after loading it.

See also: im_copy_set(), im_raw2vips(), im_open().

name :

filename to open

xsize :

image width

ysize :

image height

bands :

image bands (or bytes per pixel)

offset :

bytes to skip at start of file

Returns :

the new IMAGE, or NULL on error.

im_image ()

VipsImage *         im_image                            (void *buffer,
                                                         int xsize,
                                                         int ysize,
                                                         int bands,
                                                         VipsBandFmt bandfmt);

This function wraps an IMAGE around a memory buffer. VIPS does not take responsibility for the area of memory, it's up to you to make sure it's freed when the image is closed. See for example im_add_close_callback().

See also: im_binfile(), im_raw2vips(), im_open().

buffer :

start of memory area

xsize :

image width

ysize :

image height

bands :

image bands (or bytes per pixel)

bandfmt :

image format

Returns :

the new IMAGE, or NULL on error.

See Also

region