VipsImage

VipsImage — the VIPS image class

Stability Level

Stable, unless otherwise indicated

Functions

void * (*VipsStartFn) ()
int (*VipsGenerateFn) ()
int (*VipsStopFn) ()
#define VIPS_IMAGE_SIZEOF_ELEMENT()
#define VIPS_IMAGE_SIZEOF_PEL()
#define VIPS_IMAGE_SIZEOF_LINE()
#define VIPS_IMAGE_N_ELEMENTS()
#define VIPS_IMAGE_N_PELS()
#define VIPS_IMAGE_ADDR()
#define VIPS_MATRIX()
void vips_progress_set ()
void vips_image_invalidate_all ()
void vips_image_minimise_all ()
void vips_image_set_progress ()
char * vips_filename_get_filename ()
char * vips_filename_get_options ()
VipsImage * vips_image_new ()
VipsImage * vips_image_new_memory ()
VipsImage * vips_image_memory ()
VipsImage * vips_image_new_from_file ()
VipsImage * vips_image_new_from_file_RW ()
VipsImage * vips_image_new_from_file_raw ()
VipsImage * vips_image_new_from_memory ()
VipsImage * vips_image_new_from_memory_copy ()
VipsImage * vips_image_new_from_buffer ()
VipsImage * vips_image_new_matrix ()
VipsImage * vips_image_new_matrixv ()
VipsImage * vips_image_new_matrix_from_array ()
VipsImage * vips_image_matrix_from_array ()
VipsImage * vips_image_new_from_image ()
VipsImage * vips_image_new_from_image1 ()
void vips_image_set_delete_on_close ()
guint64 vips_get_disc_threshold ()
VipsImage * vips_image_new_temp_file ()
int vips_image_write ()
int vips_image_write_to_file ()
int vips_image_write_to_buffer ()
void * vips_image_write_to_memory ()
int vips_image_decode_predict ()
int vips_image_decode ()
int vips_image_encode ()
gboolean vips_image_isMSBfirst ()
gboolean vips_image_isfile ()
gboolean vips_image_ispartial ()
gboolean vips_image_hasalpha ()
VipsImage * vips_image_copy_memory ()
int vips_image_wio_input ()
int vips_image_pio_input ()
int vips_image_pio_output ()
int vips_image_inplace ()
int vips_image_write_prepare ()
int vips_image_write_line ()
gboolean vips_band_format_isint ()
gboolean vips_band_format_isuint ()
gboolean vips_band_format_is8bit ()
gboolean vips_band_format_isfloat ()
gboolean vips_band_format_iscomplex ()
int vips_system ()
VipsArrayImage * vips_array_image_new ()
VipsArrayImage * vips_array_image_newv ()
VipsArrayImage * vips_array_image_new_from_string ()
VipsArrayImage * vips_array_image_empty ()
VipsArrayImage * vips_array_image_append ()
VipsImage ** vips_array_image_get ()
VipsImage ** vips_value_get_array_image ()
void vips_value_set_array_image ()
int vips_reorder_prepare_many ()
void vips_reorder_margin_hint ()

Properties

gint bands Read / Write
VipsCoding coding Read / Write
VipsDemandStyle demand Read / Write
gchar * filename Read / Write
gpointer foreign-buffer Read / Write
VipsBandFormat format Read / Write
gint height Read / Write
VipsInterpretation interpretation Read / Write
gboolean kill Read / Write
gchar * mode Read / Write
guint64 sizeof-header Read / Write
gint width Read / Write
gint xoffset Read / Write
gdouble xres Read / Write
gint yoffset Read / Write
gdouble yres Read / Write

Object Hierarchy

    GObject
    ╰── VipsObject
        ╰── VipsImage

Includes

#include <vips/vips.h>

Description

The image class and associated types and macros.

Images can be created from formatted files on disc, from C-style arrays on disc, from formatted areas of memory, or from C-style arrays in memory. See vips_image_new_from_file() and friends. Creating an image is fast. VIPS reads just enough of the image to be able to get the various properties, such as width in pixels. It delays reading any pixels until they are really needed.

Once you have an image, you can get properties from it in the usual way. You can use projection functions, like vips_image_get_width() or g_object_get(), to get GObject properties.

VIPS images are three-dimensional arrays, the dimensions being width, height and bands. Each dimension can be up to 2 ** 31 pixels (or band elements). An image has a format, meaning the machine number type used to represent each value. VIPS supports 10 formats, from 8-bit unsigned integer up to 128-bit double complex, see vips_image_get_format().

In VIPS, images are uninterpreted arrays, meaning that from the point of view of most operations, they are just large collections of numbers. There's no difference between an RGBA (RGB with alpha) image and a CMYK image, for example, they are both just four-band images. It's up to the user of the library to pass the right sort of image to each operation.

To take an example, VIPS has vips_Lab2XYZ(), an operation to transform an image from CIE LAB colour space to CIE XYZ space. It assumes the first three bands represent pixels in LAB colour space and returns an image where the first three bands are transformed to XYZ and any remaining bands are just copied. Pass it a RGB image by mistake and you'll just get nonsense.

VIPS has a feature to help (a little) with this: it sets a VipsInterpretation hint for each image (see vips_image_get_interpretation()); a hint which says how pixels should be interpreted. For example, vips_Lab2XYZ() will set the interpretation of the output image to VIPS_INTERPRETATION_XYZ. A few utility operations will also use interpretation as a guide. For example, you can give vips_colourspace() an input image and a desired colourspace and it will use the input's interpretation hint to apply the best sequence of colourspace transforms to get to the desired space.

Use things like vips_invert() to manipulate your images. When you are done, you can write images to disc files (with vips_image_write_to_file()), to formatted memory buffers (with vips_image_write_to_buffer()) and to C-style memory arrays (with vips_image_write_to_memory().

You can also write images to other images. Create, for example, a temporary disc image with vips_image_new_temp_file(), then write your image to that with vips_image_write(). You can create several other types of image and write to them, see vips_image_new_memory(), for example.

See operation for an introduction to running operations on images, see header for getting and setting image metadata. See object for a discussion of the lower levels.

Functions

VipsStartFn ()

void *
(*VipsStartFn) (struct _VipsImage *out,
                void *a,
                void *b);

Start a new processing sequence for this generate function. This allocates per-thread state, such as an input region.

See also: vips_start_one(), vips_start_many().

Parameters

out

image being calculated

 

a

user data

 

b

user data

 

Returns

a new sequence value


VipsGenerateFn ()

int
(*VipsGenerateFn) (struct _VipsRegion *out,
                   void *seq,
                   void *a,
                   void *b,
                   gboolean *stop);

Fill out->valid with pixels. seq contains per-thread state, such as the input regions. Set stop to TRUE to stop processing.

See also: vips_image_generate(), vips_stop_many().

Parameters

out

VipsRegion to fill

 

seq

sequence value

 

a

user data

 

b

user data

 

stop

set this to stop processing

 

Returns

0 on success, -1 on error.


VipsStopFn ()

int
(*VipsStopFn) (void *seq,
               void *a,
               void *b);

Stop a processing sequence. This frees per-thread state, such as an input region.

See also: vips_stop_one(), vips_stop_many().

Parameters

seq

sequence value

 

a

user data

 

b

user data

 

Returns

0 on success, -1 on error.


VIPS_IMAGE_SIZEOF_ELEMENT()

#define             VIPS_IMAGE_SIZEOF_ELEMENT( I )

Parameters

I

a VipsImage

 

Returns

sizeof() a band element.


VIPS_IMAGE_SIZEOF_PEL()

#define             VIPS_IMAGE_SIZEOF_PEL( I )

Parameters

I

a VipsImage

 

Returns

sizeof() a pixel.


VIPS_IMAGE_SIZEOF_LINE()

#define             VIPS_IMAGE_SIZEOF_LINE( I )

Parameters

I

a VipsImage

 

Returns

sizeof() a scanline of pixels.


VIPS_IMAGE_N_ELEMENTS()

#define             VIPS_IMAGE_N_ELEMENTS( I )

Parameters

I

a VipsImage

 

Returns

The number of band elements in a scanline.


VIPS_IMAGE_N_PELS()

#define             VIPS_IMAGE_N_PELS( I )

Parameters

I

a VipsImage

 

Returns

The number of pels in an image. A 64-bit unsigned int.


VIPS_IMAGE_ADDR()

#define             VIPS_IMAGE_ADDR( I, X, Y )

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

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

See also: vips_image_wio_input(), vips_image_inplace(), VIPS_REGION_ADDR().

Parameters

I

a VipsImage

 

X

x coordinate

 

Y

y coordinate

 

Returns

The address of pixel (X ,Y ) in I .


VIPS_MATRIX()

#define             VIPS_MATRIX( I, X, Y )

This macro returns a pointer to a pixel in an image, cast to a double*. The image must have a single band, be VIPS_FORMAT_DOUBLE and be fully available in memory, so memory buffers and small mapped images only.

If VIPS_DEBUG is defined, you get a version that checks bounds and image type for you.

See also: vips_image_wio_input(), vips_image_inplace(), vips_check_matrix().

Parameters

I

a VipsImage

 

X

x coordinate

 

Y

y coordinate

 

Returns

The address of pixel (X ,Y ) in I .


vips_progress_set ()

void
vips_progress_set (gboolean progress);

If set, vips will print messages about the progress of computation to stdout. This can also be enabled with the --vips-progress option, or by setting the environment variable VIPS_PROGRESS.

Parameters

progress

TRUE to enable progress messages

 

vips_image_invalidate_all ()

void
vips_image_invalidate_all (VipsImage *image);

Invalidate all pixel caches on image and any downstream images, that is, images which depend on this image. Additionally, all operations which depend upon this image are dropped from the VIPS operation cache.

You should call this function after destructively modifying an image with something like vips_draw_circle().

The “invalidate” signal is emitted for all invalidated images.

See also: vips_region_invalidate().

[method]

Parameters

image

VipsImage to invalidate

 

vips_image_minimise_all ()

void
vips_image_minimise_all (VipsImage *image);

Minimise memory use on this image and any upstream images, that is, images which this image depends upon. This function is called automatically at the end of a computation, but it might be useful to call at other times.

The “minimise” signal is emitted for all minimised images.

[method]

Parameters

image

VipsImage to minimise

 

vips_image_set_progress ()

void
vips_image_set_progress (VipsImage *image,
                         gboolean progress);

vips signals evaluation progress via the “preeval”, “eval” and “posteval” signals. Progress is signalled on the most-downstream image for which vips_image_set_progress() was called.

[method]

Parameters

image

image to signal progress on

 

progress

turn progress reporting on or off

 

vips_filename_get_filename ()

char *
vips_filename_get_filename (const char *vips_filename);

Given a vips filename like "fred.jpg[Q=90]", return a new string of just the filename part, "fred.jpg" in this case.

Useful for language bindings.

See also: vips_filename_get_options().

Parameters

vips_filename

a filename including a set of options

 

Returns

transfer full: just the filename component.


vips_filename_get_options ()

char *
vips_filename_get_options (const char *vips_filename);

Given a vips filename like "fred.jpg[Q=90]", return a new string of just the options part, "[Q=90]" in this case.

Useful for language bindings.

See also: vips_filename_get_filename().

Parameters

vips_filename

a filename including a set of options

 

Returns

transfer full: just the options component.


vips_image_new ()

VipsImage *
vips_image_new (void);

vips_image_new() creates a new, empty VipsImage. If you write to one of these images, vips will just attach some callbacks, no pixels will be generated.

Write pixels to an image with vips_image_generate() or vips_image_write_line(). Write a whole image to another image with vips_image_write().

[constructor]

Returns

the new VipsImage, or NULL on error.

[transfer full]


vips_image_new_memory ()

VipsImage *
vips_image_new_memory (void);

vips_image_new_memory() creates a new VipsImage which, when written to, will create a memory image.

See also: vips_image_new().

[constructor]

Returns

the new VipsImage, or NULL on error.

[transfer full]


vips_image_memory ()

VipsImage *
vips_image_memory (void);

A renamed vips_image_new_memory() ... Some gobject binding systems do not like more than one _new() method.

See also: vips_image_new_memory().

[constructor]

Returns

the new VipsImage, or NULL on error.

[transfer full]


vips_image_new_from_file ()

VipsImage *
vips_image_new_from_file (const char *name,
                          ...);

Optional arguments:

  • access : hint VipsAccess mode to loader

  • memory : force load via memory

vips_image_new_from_file() opens name for reading. It can load files in many image formats, including VIPS, TIFF, PNG, JPEG, FITS, Matlab, OpenEXR, CSV, WebP, Radiance, RAW, PPM and others.

Load options may be appended to filename as "[name=value,...]" or given as a NULL-terminated list of name-value pairs at the end of the arguments. Options given in the function call override options given in the filename. Many loaders add extra options, see vips_jpegload(), for example.

vips_image_new_from_file() always returns immediately with the header fields filled in. No pixels are actually read until you first access them.

access lets you set a VipsAccess hint giving the expected access pattern for this file. VIPS_ACCESS_RANDOM means you can fetch pixels randomly from the image. This is the default mode. VIPS_ACCESS_SEQUENTIAL means you will read the whole image exactly once, top-to-bottom. In this mode, vips can avoid converting the whole image in one go, for a large memory saving. You are allowed to make small non-local references, so area operations like convolution will work.

In VIPS_ACCESS_RANDOM mode, small images are decompressed to memory and then processed from there. Large images are decompressed to temporary random-access files on disc and then processed from there.

Set memory to TRUE to force loading via memory. The default is to load large random access images via temporary disc files. See vips_image_new_temp_file() 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 VIPS_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. The default threshold is 100 MB.

For example:

1
2
3
VipsImage *image = vips_image_new_from_file ("fred.tif",
	"page", 12,
	NULL);

Will open "fred.tif", reading page 12.

1
2
VipsImage *image = vips_image_new_from_file ("fred.jpg[shrink=2]",
	NULL);

Will open "fred.jpg", downsampling by a factor of two.

Use vips_foreign_find_load() or vips_foreign_is_a() to see what format a file is in and therefore what options are available. If you need more control over the loading process, you can call loaders directly, see vips_jpegload(), for example.

See also: vips_foreign_find_load(), vips_foreign_is_a(), vips_image_write_to_file().

[constructor]

Parameters

name

file to open

 

...

NULL-terminated list of optional named arguments

 

Returns

the new VipsImage, or NULL on error.

[transfer full]


vips_image_new_from_file_RW ()

VipsImage *
vips_image_new_from_file_RW (const char *filename);

Opens the named file for simultaneous 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: vips_draw_circle().

[constructor]

Parameters

filename

filename to open

 

Returns

the new VipsImage, or NULL on error.

[transfer full]


vips_image_new_from_file_raw ()

VipsImage *
vips_image_new_from_file_raw (const char *filename,
                              int xsize,
                              int ysize,
                              int bands,
                              guint64 offset);

This function maps the named file and returns a VipsImage you can use to read it.

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

See also: vips_copy(), vips_rawload(), vips_image_new_from_file().

[constructor]

Parameters

filename

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 VipsImage, or NULL on error.

[transfer full]


vips_image_new_from_memory ()

VipsImage *
vips_image_new_from_memory (const void *data,
                            size_t size,
                            int width,
                            int height,
                            int bands,
                            VipsBandFormat format);

This function wraps a VipsImage around a memory area. The memory area must be a simple array, for example RGBRGBRGB, left-to-right, top-to-bottom. Use vips_image_new_from_buffer() to load an area of memory containing an image in a format.

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 “close”.

Because VIPS is "borrowing" data from the caller, this function is extremely dangerous. Unless you are very careful, you will get crashes or memory corruption. Use vips_image_new_from_memory_copy() instead if you are at all unsure.

Use vips_copy() to set other image properties.

See also: vips_image_new(), vips_image_write_to_memory(), vips_image_new_from_memory_copy().

[constructor]

Parameters

data

start of memory area.

[array length=size][element-type guint8][transfer none]

size

length of memory area.

[type gsize]

width

image width

 

height

image height

 

bands

image bands (or bytes per pixel)

 

format

image format

 

Returns

the new VipsImage, or NULL on error.

[transfer full]


vips_image_new_from_memory_copy ()

VipsImage *
vips_image_new_from_memory_copy (const void *data,
                                 size_t size,
                                 int width,
                                 int height,
                                 int bands,
                                 VipsBandFormat format);

Like vips_image_new_from_memory(), but VIPS will make a copy of the memory area. This means more memory use and an extra copy operation, but is much simpler and safer.

See also: vips_image_new_from_memory().

[constructor]

Parameters

data

start of memory area.

[array length=size][element-type guint8][transfer none]

size

length of memory area.

[type gsize]

width

image width

 

height

image height

 

bands

image bands (or bytes per pixel)

 

format

image format

 

Returns

the new VipsImage, or NULL on error.

[transfer full]


vips_image_new_from_buffer ()

VipsImage *
vips_image_new_from_buffer (const void *buf,
                            size_t len,
                            const char *option_string,
                            ...);

Loads an image from the formatted area of memory buf , len using the loader recommended by vips_foreign_find_load_buffer(). To load an unformatted area of memory, use vips_image_new_from_memory().

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 “close”.

Load options may be given in option_string as "[name=value,...]" or given as a NULL-terminated list of name-value pairs at the end of the arguments. Options given in the function call override options given in the filename.

See also: vips_image_write_to_buffer().

[constructor]

Parameters

buf

image data.

[array length=len][element-type guint8][transfer none]

len

length of memory buffer.

[type gsize]

option_string

set of extra options as a string

 

...

NULL-terminated list of optional named arguments

 

Returns

the new VipsImage, or NULL on error.

[transfer full]


vips_image_new_matrix ()

VipsImage *
vips_image_new_matrix (int width,
                       int height);

This convenience function makes an image which is a matrix: a one-band VIPS_FORMAT_DOUBLE image held in memory.

Use VIPS_IMAGE_ADDR(), or VIPS_MATRIX() to address pixels in the image.

Use vips_image_set_double() to set "scale" and "offset", if required.

See also: vips_image_new_matrixv()

[constructor]

Parameters

width

image width

 

height

image height

 

Returns

the new VipsImage, or NULL on error.

[transfer full]


vips_image_new_matrixv ()

VipsImage *
vips_image_new_matrixv (int width,
                        int height,
                        ...);

As vips_image_new_matrix(), but initialise the matrix from the argument list. After height should be width * height double constants which are used to set the matrix elements.

See also: vips_image_new_matrix()

[constructor]

Parameters

width

image width

 

height

image height

 

...

matrix coefficients

 

Returns

the new VipsImage, or NULL on error.

[transfer full]


vips_image_new_matrix_from_array ()

VipsImage *
vips_image_new_matrix_from_array (int width,
                                  int height,
                                  const double *array,
                                  int size);

A binding-friendly version of vips_image_new_matrixv().

[constructor]

Parameters

width

image width

 

height

image height

 

array

array of elements.

[array length=size][transfer none]

size

number of elements.

[type gsize]

Returns

the new VipsImage, or NULL on error.

[transfer full]


vips_image_matrix_from_array ()

VipsImage *
vips_image_matrix_from_array (int width,
                              int height,
                              const double *array,
                              int size);

A renamed vips_image_new_matrix_from_array(). Some gobject bindings do not like more than one _new method.

[constructor]

Parameters

width

image width

 

height

image height

 

array

array of elements.

[array length=size][transfer none]

size

number of elements.

[type gsize]

Returns

the new VipsImage, or NULL on error.

[transfer full]


vips_image_new_from_image ()

VipsImage *
vips_image_new_from_image (VipsImage *image,
                           const double *c,
                           int n);

Creates a new image with width, height, format, interpretation, resolution and offset taken from image , but with number of bands taken from n and the value of each band element set from c .

See also: vips_image_new_from_image1()

[constructor]

Parameters

image

image to copy

 

c

array of constants.

[array length=n][transfer none]

n

number of constants

 

Returns

the new VipsImage, or NULL on error.

[transfer full]


vips_image_new_from_image1 ()

VipsImage *
vips_image_new_from_image1 (VipsImage *image,
                            double c);

Creates a new image with width, height, format, interpretation, resolution and offset taken from image , but with one band and each pixel having the value c .

See also: vips_image_new_from_image()

[constructor]

Parameters

image

image to copy

 

c

constants

 

Returns

the new VipsImage, or NULL on error.

[transfer full]


vips_image_set_delete_on_close ()

void
vips_image_set_delete_on_close (VipsImage *image,
                                gboolean delete_on_close);

Sets the delete_on_close flag for the image. If this flag is set, when image is finalized, the filename held in image->filename at the time of this call is deleted.

This function is clearly extremely dangerous, use with great caution.

See also: vips_image_new_temp_file().

[method]

Parameters

image

image to set

 

delete_on_close

format of file

 

vips_get_disc_threshold ()

guint64
vips_get_disc_threshold (void);

Return the number of bytes at which we flip between open via memory and open via disc. This defaults to 100mb, but can be changed with the VIPS_DISC_THRESHOLD environment variable or the --vips-disc-threshold command-line flag. See vips_image_new_from_file().

Returns

disc threshold in bytes.


vips_image_new_temp_file ()

VipsImage *
vips_image_new_temp_file (const char *format);

Make a VipsImage which, when written to, will create a temporary file on disc. The file will be automatically deleted when the image is destroyed. format is something like "%s.v" for a vips file.

The file is created in the temporary directory. This is set with the environment variable TMPDIR. If this is not set, then on Unix systems, vips will default to /tmp. On Windows, vips uses GetTempPath() to find the temporary directory.

See also: vips_image_new().

[constructor]

Parameters

format

format of file

 

Returns

the new VipsImage, or NULL on error.


vips_image_write ()

int
vips_image_write (VipsImage *image,
                  VipsImage *out);

Write image to out . Use vips_image_new() and friends to create the VipsImage you want to write to.

See also: vips_image_new(), vips_copy(), vips_image_write_to_file().

[method]

Parameters

image

image to write

 

out

write to this image.

[out]

Returns

0 on success, or -1 on error.


vips_image_write_to_file ()

int
vips_image_write_to_file (VipsImage *image,
                          const char *name,
                          ...);

Writes in to name using the saver recommended by vips_foreign_find_save().

Save options may be appended to filename as "[name=value,...]" or given as a NULL-terminated list of name-value pairs at the end of the arguments. Options given in the function call override options given in the filename.

See also: vips_image_new_from_file().

[method]

Parameters

image

image to write

 

name

write to this file

 

...

NULL-terminated list of optional named arguments

 

Returns

0 on success, or -1 on error.


vips_image_write_to_buffer ()

int
vips_image_write_to_buffer (VipsImage *in,
                            const char *suffix,
                            void **buf,
                            size_t *size,
                            ...);

Writes in to a memory buffer in a format specified by suffix .

Save options may be appended to suffix as "[name=value,...]" or given as a NULL-terminated list of name-value pairs at the end of the arguments. Options given in the function call override options given in the filename.

Currently only TIFF, JPEG and PNG formats are supported.

You can call the various save operations directly if you wish, see vips_jpegsave_buffer(), for example.

See also: vips_image_write_to_memory(), vips_image_new_from_buffer().

[method]

Parameters

in

image to write

 

suffix

format to write

 

buf

return buffer start here.

[array length=size][element-type guint8][transfer full]

size

return buffer length here.

[type gsize]

...

NULL-terminated list of optional named arguments

 

Returns

0 on success, -1 on error


vips_image_write_to_memory ()

void *
vips_image_write_to_memory (VipsImage *in,
                            size_t *size);

Writes in to memory as a simple, unformatted C-style array.

The caller is responsible for freeing this memory with g_free().

See also: vips_image_write_to_buffer().

[method]

Parameters

in

image to write

 

size

return buffer length here

 

Returns

return buffer start here.

[array length=size][element-type guint8][transfer full]


vips_image_decode_predict ()

int
vips_image_decode_predict (VipsImage *in,
                           int *bands,
                           VipsBandFormat *format);

We often need to know what an image will decode to without actually decoding it, for example, in arg checking.

See also: vips_image_decode().

[method]

Parameters

in

image to decode

 

bands

predict bands here.

[out]

format

predict format here.

[out]

vips_image_decode ()

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

A convenience function to unpack to a format that we can compute with. out.coding is always VIPS_CODING_NONE.

This unpacks LABQ to plain LAB. Use vips_LabQ2LabS() for a bit more speed if you need it.

See also: vips_image_encode(), vips_LabQ2Lab(), vips_rad2float().

[method]

Parameters

in

image to decode

 

out

write to this image.

[out]

Returns

0 on success, or -1 on error.


vips_image_encode ()

int
vips_image_encode (VipsImage *in,
                   VipsImage **out,
                   VipsCoding coding);

A convenience function to pack to a coding. The inverse of vips_image_decode().

See also: vips_image_decode().

[method]

Parameters

in

image to encode

 

out

write to this image.

[out]

coding

coding to apply

 

Returns

0 on success, or -1 on error.


vips_image_isMSBfirst ()

gboolean
vips_image_isMSBfirst (VipsImage *image);

Return TRUE if image is in most-significant- byte first form. This is the byte order used on the SPARC architecture and others.

[method]

Parameters

image

image to test

 

vips_image_isfile ()

gboolean
vips_image_isfile (VipsImage *image);

Return TRUE if image represents a file on disc in some way.

[method]

Parameters

image

image to test

 

vips_image_ispartial ()

gboolean
vips_image_ispartial (VipsImage *image);

Return TRUE if im represents a partial image (a delayed calculation).

[method]

Parameters

image

image to test

 

vips_image_hasalpha ()

gboolean
vips_image_hasalpha (VipsImage *image);

Look at an image's interpretation and see if it has extra alpha bands. For example, a 4-band VIPS_INTERPRETATION_RGB would, but a six-band VIPS_INTERPRETATION_MULTIBAND would not.

Return TRUE if image has an alpha channel.

[method]

Parameters

image

image to check

 

vips_image_copy_memory ()

VipsImage *
vips_image_copy_memory (VipsImage *image);

Make an image which is an area of memory.

If image is already a memory buffer, just ref and return. If it's a file on disc or a partial, allocate memory and copy the image to it.

This operation is thread-safe, unlike vips_image_wio_input().

If you are sure that image is not shared with another thread (perhaps you have made it yourself), use vips_image_wio_input() instead.

See also: vips_image_wio_input().

[method]

Parameters

image

image to copy to a memory buffer

 

Returns

the new VipsImage, or NULL on error.

[transfer full]


vips_image_wio_input ()

int
vips_image_wio_input (VipsImage *image);

Check that an image is readable via the VIPS_IMAGE_ADDR() macro, that is, that the entire image is in memory and all pixels can be read with VIPS_IMAGE_ADDR(). If it isn't, try to transform it so that VIPS_IMAGE_ADDR() can work.

Since this function modifies image , it is not thread-safe. Only call it on images which you are sure have not been shared with another thread. If the image might have been shared, use the less efficient vips_image_copy_memory() instead.

See also: vips_image_copy_memory(), vips_image_pio_input(), vips_image_inplace(), VIPS_IMAGE_ADDR().

[method]

Parameters

image

image to transform

 

Returns

0 on succeess, or -1 on error.


vips_image_pio_input ()

int
vips_image_pio_input (VipsImage *image);

Check that an image is readable with vips_region_prepare() and friends. If it isn't, try to transform the image so that vips_region_prepare() can work.

See also: vips_image_pio_output(), vips_region_prepare().

[method]

Parameters

image

image to check

 

Returns

0 on succeess, or -1 on error.


vips_image_pio_output ()

int
vips_image_pio_output (VipsImage *image);

Check that an image is writeable with vips_image_generate(). If it isn't, try to transform the image so that vips_image_generate() can work.

See also: vips_image_pio_input().

[method]

Parameters

image

image to check

 

Returns

0 on succeess, or -1 on error.


vips_image_inplace ()

int
vips_image_inplace (VipsImage *image);

Gets image ready for an in-place operation, such as vips_draw_circle(). After calling this function you can both read and write the image with VIPS_IMAGE_ADDR().

Since this function modifies image , it is not thread-safe. Only call it on images which you are sure have not been shared with another thread. All in-place operations are inherently not thread-safe, so you need to take great care in any case.

See also: vips_draw_circle(), vips_image_wio_input().

[method]

Parameters

image

image to make read-write

 

Returns

0 on succeess, or -1 on error.


vips_image_write_prepare ()

int
vips_image_write_prepare (VipsImage *image);

Call this after setting header fields (width, height, and so on) to allocate resources ready for writing.

Normally this function is called for you by vips_image_generate() or vips_image_write_line(). You will need to call it yourself if you plan to write directly to the ->data member of a memory image.

[method]

Parameters

image

image to prepare

 

Returns

0 on success, or -1 on error.


vips_image_write_line ()

int
vips_image_write_line (VipsImage *image,
                       int ypos,
                       VipsPel *linebuffer);

Write a line of pixels to an image. This function must be called repeatedly with ypos increasing from 0 to “height” . linebuffer must be VIPS_IMAGE_SIZEOF_LINE() bytes long.

See also: vips_image_generate().

[method]

Parameters

image

image to write to

 

ypos

vertical position of scan-line to write

 

linebuffer

scanline of pixels

 

Returns

0 on success, or -1 on error.


vips_band_format_isint ()

gboolean
vips_band_format_isint (VipsBandFormat format);

Return TRUE if format is one of the integer types.

Parameters

format

format to test

 

vips_band_format_isuint ()

gboolean
vips_band_format_isuint (VipsBandFormat format);

Return TRUE if format is one of the unsigned integer types.

Parameters

format

format to test

 

vips_band_format_is8bit ()

gboolean
vips_band_format_is8bit (VipsBandFormat format);

Return TRUE if format is uchar or schar.

Parameters

format

format to test

 

vips_band_format_isfloat ()

gboolean
vips_band_format_isfloat (VipsBandFormat format);

Return TRUE if format is one of the float types.

Parameters

format

format to test

 

vips_band_format_iscomplex ()

gboolean
vips_band_format_iscomplex (VipsBandFormat format);

Return TRUE if fmt is one of the complex types.

Parameters

format

format to test

 

vips_system ()

int
vips_system (const char *cmd_format,
             ...);

Optional arguments:

  • in : array of input images

  • out : output image

  • in_format : write input files like this

  • out_format : write output filename like this

  • log : stdout of command is returned here

vips_system() runs a command, optionally passing a set of images in and optionally getting an image back. The command's stdout is returned in log .

First, if in is set, the array of images are written to files. See vips_image_new_temp_file() to see how temporary files are created. If in_format is something like %s.png, the file will be written in PNG format. By default, in_format is %s.tif.

If out_format is set, an output filename is formed in the same way. Any trailing [options] are stripped from out_format .

The command string to run is made by substituting the first set of %s in cmd_format for the names of the input files, if in is set, and then the next %s for the output filename, if out_format is set. You can put a number between the % and the s to change the order in which the substitution occurs.

The command is executed with popen() and the output captured in log .

After the command finishes, if out_format is set, the output image is opened and returned in out . You can append [options] to out_format to control how this open happens. Closing out image will automatically delete the output file.

Finally the input images are deleted.

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
7
8
9
10
11
12
VipsArrayImage *in;
VipsImage *out;
char *log;

if (vips_system ("convert %s -swirl 45 %s",
	"in", in, 
	"out", &out, 
  	"in_format", "%s.jpg", 
  	"out_format", "%s.jpg", 
  	"log", &log,
  	NULL))
  	error ...

Parameters

cmd_format

command to run

 

...

NULL-terminated list of optional named arguments

 

Returns

0 on success, -1 on failure.


vips_array_image_new ()

VipsArrayImage *
vips_array_image_new (VipsImage **array,
                      int n);

Allocate a new array of images and copy array into it. Free with vips_area_unref().

The images will all be reffed by this function. They will be automatically unreffed for you by vips_area_unref().

Add an extra NULL element at the end, handy for eg. vips_image_pipeline_array() etc.

See also: VipsArea.

[constructor]

Parameters

array

array of VipsImage.

[array length=n]

n

number of images

 

Returns

A new VipsArrayImage.

[transfer full]


vips_array_image_newv ()

VipsArrayImage *
vips_array_image_newv (int n,
                       ...);

Allocate a new array of n VipsImage and copy @... into it. Free with vips_area_unref().

The images will all be reffed by this function. They will be automatically unreffed for you by vips_area_unref().

Add an extra NULL element at the end, handy for eg. vips_image_pipeline_array() etc.

See also: vips_array_image_new()

[constructor]

Parameters

n

number of images

 

...

list of VipsImage arguments

 

Returns

A new VipsArrayImage.

[transfer full]


vips_array_image_new_from_string ()

VipsArrayImage *
vips_array_image_new_from_string (const char *string,
                                  VipsAccess flags);

vips_array_image_empty ()

VipsArrayImage *
vips_array_image_empty (void);

Make an empty image array. Handy with vips_array_image_add() for bindings which can't handle object array arguments.

See also: vips_array_image_add().

[constructor]

Returns

A new VipsArrayImage.

[transfer full]


vips_array_image_append ()

VipsArrayImage *
vips_array_image_append (VipsArrayImage *array,
                         VipsImage *image);

Make a new VipsArrayImage, one larger than array , with image appended to the end. Handy with vips_array_image_empty() for bindings which can't handle object array arguments.

See also: vips_array_image_empty().

[method]

Parameters

array

append to this.

[transfer none]

image

add this

 

Returns

A new VipsArrayImage.

[transfer full]


vips_array_image_get ()

VipsImage **
vips_array_image_get (VipsArrayImage *array,
                      int *n);

Fetch an image array from a VipsArrayImage. Useful for language bindings.

[method]

Parameters

array

the VipsArrayImage to fetch from

 

n

length of array

 

Returns

array of VipsImage.

[array length=n][transfer none]


vips_value_get_array_image ()

VipsImage **
vips_value_get_array_image (const GValue *value,
                            int *n);

Return the start of the array of images held by value . optionally return the number of elements in n .

See also: vips_value_set_array_image().

Parameters

value

GValue to get from

 

n

return the number of elements here, optionally.

[allow-none]

Returns

The array address.

[transfer none]


vips_value_set_array_image ()

void
vips_value_set_array_image (GValue *value,
                            int n);

Set value to hold an array of images. Pass in the array length in n .

See also: vips_array_image_get().

Parameters

value

GValue to get from.

[out]

n

the number of elements

 

vips_reorder_prepare_many ()

int
vips_reorder_prepare_many (VipsImage *image,
                           struct _VipsRegion **regions,
                           VipsRect *r);

vips_reorder_prepare_many() runs vips_region_prepare() on each region in regions , requesting the pixels in r .

It tries to request the regions in the order which will cause least recomputation. This can give a large speedup, in some cases.

See also: vips_region_prepare(), vips_reorder_margin_hint().

[method]

Parameters

image

the image that's being written

 

regions

the set of regions to prepare.

[array][element-type VipsRegion]

r

the VipsRect to prepare on each region

 

Returns

0 on success, or -1 on error.


vips_reorder_margin_hint ()

void
vips_reorder_margin_hint (VipsImage *image,
                          int margin);

vips_reorder_margin_hint() sets a hint that image contains a margin, that is, that each vips_region_prepare() on image will request a slightly larger region from it's inputs. A good value for margin is (width * height) for the window the operation uses.

This information is used by vips_image_prepare_many() to attempt to reorder computations to minimise recomputation.

See also: vips_image_prepare_many().

[method]

Parameters

image

the image to hint on

 

margin

the size of the margin this operation has added

 

Types and Values

VIPS_MAGIC_INTEL

#define VIPS_MAGIC_INTEL (0xb6a6f208U)

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


VIPS_MAGIC_SPARC

#define VIPS_MAGIC_SPARC (0x08f2a6b6U)

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


VIPS_MAX_COORD

#define VIPS_MAX_COORD (10000000)

enum VipsDemandStyle

See vips_image_pipelinev(). 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, vips_image_generate() will use the most restrictive of the styles requested by the operations in the pipeline.

VIPS_DEMAND_STYLE_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.

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

VIPS_DEMAND_STYLE_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.

VIPS_DEMAND_STYLE_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 vips_black() where the pixels are calculated.

See also: vips_image_pipelinev().

Members

VIPS_DEMAND_STYLE_ERROR

   

VIPS_DEMAND_STYLE_SMALLTILE

demand in small (typically 64x64 pixel) tiles

 

VIPS_DEMAND_STYLE_FATSTRIP

demand in fat (typically 10 pixel high) strips

 

VIPS_DEMAND_STYLE_THINSTRIP

demand in thin (typically 1 pixel high) strips

 

VIPS_DEMAND_STYLE_ANY

demand geometry does not matter

 

enum VipsImageType

Members

VIPS_IMAGE_ERROR

   

VIPS_IMAGE_NONE

   

VIPS_IMAGE_SETBUF

   

VIPS_IMAGE_SETBUF_FOREIGN

   

VIPS_IMAGE_OPENIN

   

VIPS_IMAGE_MMAPIN

   

VIPS_IMAGE_MMAPINRW

   

VIPS_IMAGE_OPENOUT

   

VIPS_IMAGE_PARTIAL

   

enum VipsInterpretation

How the values in an image should be interpreted. For example, a three-band float image of type VIPS_INTERPRETATION_LAB should have its pixels interpreted as coordinates in CIE Lab space.

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.

The gaps in numbering are historical and must be maintained. Allocate new numbers from the end.

Members

VIPS_INTERPRETATION_ERROR

   

VIPS_INTERPRETATION_MULTIBAND

generic many-band image

 

VIPS_INTERPRETATION_B_W

some kind of single-band image

 

VIPS_INTERPRETATION_HISTOGRAM

a 1D image, eg. histogram or lookup table

 

VIPS_INTERPRETATION_XYZ

the first three bands are CIE XYZ

 

VIPS_INTERPRETATION_LAB

pixels are in CIE Lab space

 

VIPS_INTERPRETATION_CMYK

the first four bands are in CMYK space

 

VIPS_INTERPRETATION_LABQ

implies VIPS_CODING_LABQ

 

VIPS_INTERPRETATION_RGB

generic RGB space

 

VIPS_INTERPRETATION_CMC

a uniform colourspace based on CMC(1:1)

 

VIPS_INTERPRETATION_LCH

pixels are in CIE LCh space

 

VIPS_INTERPRETATION_LABS

CIE LAB coded as three signed 16-bit values

 

VIPS_INTERPRETATION_sRGB

pixels are sRGB

 

VIPS_INTERPRETATION_YXY

pixels are CIE Yxy

 

VIPS_INTERPRETATION_FOURIER

image is in fourier space

 

VIPS_INTERPRETATION_RGB16

generic 16-bit RGB

 

VIPS_INTERPRETATION_GREY16

generic 16-bit mono

 

VIPS_INTERPRETATION_MATRIX

a matrix

 

VIPS_INTERPRETATION_scRGB

pixels are scRGB

 

VIPS_INTERPRETATION_HSV

pixels are HSV

 

VIPS_INTERPRETATION_LAST

   

enum VipsBandFormat

The format used for each band element.

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

Members

VIPS_FORMAT_NOTSET

invalid setting

 

VIPS_FORMAT_UCHAR

unsigned char format

 

VIPS_FORMAT_CHAR

char format

 

VIPS_FORMAT_USHORT

unsigned short format

 

VIPS_FORMAT_SHORT

short format

 

VIPS_FORMAT_UINT

unsigned int format

 

VIPS_FORMAT_INT

int format

 

VIPS_FORMAT_FLOAT

float format

 

VIPS_FORMAT_COMPLEX

complex (two floats) format

 

VIPS_FORMAT_DOUBLE

double float format

 

VIPS_FORMAT_DPCOMPLEX

double complex (two double) format

 

VIPS_FORMAT_LAST

   

enum 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.

The gaps in the numbering are historical and must be maintained. Allocate new numbers from the end.

Members

VIPS_CODING_ERROR

   

VIPS_CODING_NONE

pixels are not coded

 

VIPS_CODING_LABQ

pixels encode 3 float CIELAB values as 4 uchar

 

VIPS_CODING_RAD

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

 

VIPS_CODING_LAST

   

enum VipsAccess

The type of access an operation has to supply. See vips_tilecache() and VipsForeign.

VIPS_ACCESS_RANDOM means requests can come in any order.

VIPS_ACCESS_SEQUENTIAL means requests will be top-to-bottom, but with some amount of buffering behind the read point for small non-local accesses.

Members

VIPS_ACCESS_RANDOM

can read anywhere

 

VIPS_ACCESS_SEQUENTIAL

top-to-bottom reading only, but with a small buffer

 

VIPS_ACCESS_SEQUENTIAL_UNBUFFERED

   

VIPS_ACCESS_LAST

   

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 “eval”.

Members

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

 

Property Details

The “bands” property

  “bands”                    gint

Number of bands in image.

Flags: Read / Write

Allowed values: [1,10000000]

Default value: 1


The “coding” property

  “coding”                   VipsCoding

Pixel coding.

Flags: Read / Write

Default value: VIPS_CODING_NONE


The “demand” property

  “demand”                   VipsDemandStyle

Preferred demand style for this image.

Flags: Read / Write

Default value: VIPS_DEMAND_STYLE_SMALLTILE


The “filename” property

  “filename”                 gchar *

Image filename.

Flags: Read / Write

Default value: NULL


The “foreign-buffer” property

  “foreign-buffer”           gpointer

Pointer to foreign pixels.

Flags: Read / Write


The “format” property

  “format”                   VipsBandFormat

Pixel format in image.

Flags: Read / Write

Default value: VIPS_FORMAT_UCHAR


The “height” property

  “height”                   gint

Image height in pixels.

Flags: Read / Write

Allowed values: [1,10000000]

Default value: 1


The “interpretation” property

  “interpretation”           VipsInterpretation

Pixel interpretation.

Flags: Read / Write

Default value: VIPS_INTERPRETATION_MULTIBAND


The “kill” property

  “kill”                     gboolean

Block evaluation on this image.

Flags: Read / Write

Default value: FALSE


The “mode” property

  “mode”                     gchar *

Open mode.

Flags: Read / Write

Default value: "p"


The “sizeof-header” property

  “sizeof-header”            guint64

Offset in bytes from start of file.

Flags: Read / Write

Allowed values: <= 1000000000

Default value: 64


The “width” property

  “width”                    gint

Image width in pixels.

Flags: Read / Write

Allowed values: [1,10000000]

Default value: 1


The “xoffset” property

  “xoffset”                  gint

Horizontal offset of origin.

Flags: Read / Write

Allowed values: [-10000000,10000000]

Default value: 0


The “xres” property

  “xres”                     gdouble

Horizontal resolution in pixels/mm.

Flags: Read / Write

Allowed values: [-0,1e+06]

Default value: 0


The “yoffset” property

  “yoffset”                  gint

Vertical offset of origin.

Flags: Read / Write

Allowed values: [-10000000,10000000]

Default value: 0


The “yres” property

  “yres”                     gdouble

Vertical resolution in pixels/mm.

Flags: Read / Write

Allowed values: [-0,1e+06]

Default value: 0

Signal Details

The “eval” signal

void
user_function (VipsImage *image,
               gpointer   progress,
               gpointer   user_data)

The ::eval signal is emitted once per work unit (typically a 128 x 128 area of pixels) during image computation.

You can use this signal to update user-interfaces with progress feedback. Beware of updating too frequently: you will usually need some throttling mechanism.

Use vips_image_set_progress() to turn on progress reporting for an image.

Parameters

image

the image being calculated

 

progress

VipsProgress for this image

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last


The “invalidate” signal

void
user_function (VipsImage *image,
               gpointer   user_data)

The ::invalidate signal is emitted when an image or one of it's upstream data sources has been destructively modified. See vips_image_invalidate_all().

Parameters

image

the image that has changed

 

user_data

user data set when the signal handler was connected.

 

Flags: Action


The “minimise” signal

void
user_function (VipsImage *image,
               gpointer   user_data)

The ::minimise signal is emitted when an image has been asked to minimise memory usage. All non-essential caches are dropped. See vips_image_minimise_all().

Parameters

image

the image that is being minimised

 

user_data

user data set when the signal handler was connected.

 

Flags: Action


The “posteval” signal

void
user_function (VipsImage *image,
               gpointer   progress,
               gpointer   user_data)

The ::posteval signal is emitted once at the end of the computation of image . It's a good place to shut down evaluation feedback.

Use vips_image_set_progress() to turn on progress reporting for an image.

Parameters

image

the image that was calculated

 

progress

VipsProgress for this image

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last


The “preeval” signal

void
user_function (VipsImage *image,
               gpointer   progress,
               gpointer   user_data)

The ::preeval signal is emitted once before computation of image starts. It's a good place to set up evaluation feedback.

Use vips_image_set_progress() to turn on progress reporting for an image.

Parameters

image

the image to be calculated

 

progress

VipsProgress for this image

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last


The “written” signal

void
user_function (VipsImage *image,
               gpointer   result,
               gpointer   user_data)

The ::written signal is emitted just after an image has been written to. It is used by vips to implement things like write to foreign file formats.

Parameters

image

the image that was calculated

 

result

set to non-zero to indicate error

 

user_data

user data set when the signal handler was connected.

 

Flags: Action