header

header — get, set and walk image headers

Stability Level

Stable, unless otherwise indicated

Includes

#include <vips/vips.h>

Description

These functions let you get at image header data (including metadata) in a uniform way.

Use vips_image_get_typeof() to test for the existance and GType of a header field.

You can attach arbitrary metadata to images. Metadata is copied as images are processed, so all images which used this image as input, directly or indirectly, will have this same bit of metadata attached to them. Copying is implemented with reference-counted pointers, so it is efficient, even for large items of data. This does however mean that metadata items need to be immutable. Metadata is handy for things like ICC profiles or EXIF data.

Various convenience functions (eg. vips_image_set_int()) let you easily attach simple types like numbers, strings and memory blocks to images. Use vips_image_map() to loop over an image's fields, including all metadata.

Items of metadata are identified by strings. Some strings are reserved, for example the ICC profile for an image is known by convention as "icc-profile-data".

If you save an image in VIPS format, all metadata (with a restriction, see below) is automatically saved for you in a block of XML at the end of the file. When you load a VIPS image, the metadata is restored. You can use the vipsedit command-line tool to extract or replace this block of XML.

VIPS metadata is based on GValue. See the docs for that system if you want to do fancy stuff such as defining a new metadata type. VIPS defines a new GValue called vips_save_string, a variety of string, see vips_value_set_save_string(). If your GValue can be transformed to vips_save_string, it will be saved and loaded to and from VIPS files for you.

VIPS provides a couple of base classes which implement reference-counted areas of memory. If you base your metadata on one of these types, it can be copied between images efficiently.

Functions

vips_format_sizeof ()

guint64
vips_format_sizeof (VipsBandFormat format);

Parameters

format

format type

 

Returns

number of bytes for a band format.


vips_format_sizeof_unsafe ()

guint64
vips_format_sizeof_unsafe (VipsBandFormat format);

A fast but dangerous version of vips_format_sizeof(). You must have previously range-checked format or you'll crash.

[skip]

Parameters

format

format type

 

Returns

number of bytes for a band format.


vips_image_get_width ()

int
vips_image_get_width (const VipsImage *image);

[method]

Parameters

image

image to get from

 

Returns

the number of pixels across the image.


vips_image_get_height ()

int
vips_image_get_height (const VipsImage *image);

[method]

Parameters

image

image to get from

 

Returns

the number of pixels down the image.


vips_image_get_bands ()

int
vips_image_get_bands (const VipsImage *image);

[method]

Parameters

image

image to get from

 

Returns

the number of bands (channels) in the image.


vips_image_get_format ()

VipsBandFormat
vips_image_get_format (const VipsImage *image);

[method]

Parameters

image

image to get from

 

Returns

the format of each band element.


vips_image_guess_format ()

VipsBandFormat
vips_image_guess_format (const VipsImage *image);

Return the VipsBandFormat for an image, guessing a sane value if the set value looks crazy.

For example, for a float image tagged as rgb16, we'd return ushort.

[method]

Parameters

image

image to guess for

 

Returns

a sensible VipsBandFormat for the image.


vips_image_get_coding ()

VipsCoding
vips_image_get_coding (const VipsImage *image);

[method]

Parameters

image

image to get from

 

Returns

the image coding


vips_image_get_interpretation ()

VipsInterpretation
vips_image_get_interpretation (const VipsImage *image);

Return the VipsInterpretation set in the image header. Use vips_image_guess_interpretation() if you want a sanity-checked value.

[method]

Parameters

image

image to get from

 

Returns

the VipsInterpretation from the image header.


vips_image_guess_interpretation ()

VipsInterpretation
vips_image_guess_interpretation (const VipsImage *image);

Return the VipsInterpretation for an image, guessing a sane value if the set value looks crazy.

[method]

Parameters

image

image to guess for

 

Returns

a sensible VipsInterpretation for the image.


vips_image_get_xres ()

double
vips_image_get_xres (const VipsImage *image);

[method]

Parameters

image

image to get from

 

Returns

the horizontal image resolution in pixels per millimeter.


vips_image_get_yres ()

double
vips_image_get_yres (const VipsImage *image);

[method]

Parameters

image

image to get from

 

Returns

the vertical image resolution in pixels per millimeter.


vips_image_get_xoffset ()

int
vips_image_get_xoffset (const VipsImage *image);

[method]

Parameters

image

image to get from

 

Returns

the horizontal position of the image origin, in pixels.


vips_image_get_yoffset ()

int
vips_image_get_yoffset (const VipsImage *image);

[method]

Parameters

image

image to get from

 

Returns

the vertical position of the image origin, in pixels.


vips_image_get_filename ()

const char *
vips_image_get_filename (const VipsImage *image);

[method]

Parameters

image

image to get from

 

Returns

the name of the file the image was loaded from.


vips_image_get_mode ()

const char *
vips_image_get_mode (const VipsImage *image);

Image modes are things like "t", meaning a memory buffer, and "p" meaning a delayed computation.

[method]

Parameters

image

image to get from

 

Returns

the image mode.


vips_image_get_scale ()

double
vips_image_get_scale (const VipsImage *image);

Matrix images can have an optional scale field for use by integer convolution.

[method]

Parameters

image

image to get from

 

Returns

the scale.


vips_image_get_offset ()

double
vips_image_get_offset (const VipsImage *image);

Matrix images can have an optional offset field for use by integer convolution.

[method]

Parameters

image

image to get from

 

Returns

the offset.


vips_image_get_data ()

const void *
vips_image_get_data (VipsImage *image);

Return a pointer to the image's pixel data, if possible. This can involve allocating large amounts of memory and performing a long computation. Image pixels are laid out in band-packed rows.

Since this function modifies image , it is not threadsafe. Only call it on images which you are sure have not been shared with another thread.

See also: vips_image_wio_input(), vips_image_copy_memory().

[method]

Parameters

image

image to get data for

 

Returns

a pointer to pixel data, if possible.

[transfer none]


vips_image_init_fields ()

void
vips_image_init_fields (VipsImage *image,
                        int xsize,
                        int ysize,
                        int bands,
                        VipsBandFormat format,
                        VipsCoding coding,
                        VipsInterpretation interpretation,
                        double xres,
                        double yres);

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

See also: vips_image_pipelinev().

[method]

Parameters

image

image to init

 

xsize

image width

 

ysize

image height

 

bands

image bands

 

format

band format

 

coding

image coding

 

interpretation

image type

 

xres

horizontal resolution, pixels per millimetre

 

yres

vertical resolution, pixels per millimetre

 

vips_image_set ()

void
vips_image_set (VipsImage *image,
                const char *name,
                GValue *value);

Set a piece of metadata on image . Any old metadata with that name is destroyed. The GValue is copied into the image, so you need to unset the value when you're done with it.

For example, to set an integer on an image (though you would use the convenience function vips_image_set_int() in practice), you would do:

1
2
3
4
5
6
GValue value = { 0 };

g_value_init (&value, G_TYPE_INT);
g_value_set_int (&value, 42);
vips_image_set (image, name, &value);
g_value_unset (&value);

See also: vips_image_get().

[method]

Parameters

image

image to set the metadata on

 

name

the name to give the metadata

 

value

the GValue to copy into the image

 

vips_image_get ()

int
vips_image_get (const VipsImage *image,
                const char *name,
                GValue *value_copy);

Fill value_copy with a copy of the header field. value_copy must be zeroed but uninitialised.

This will return -1 and add a message to the error buffer if the field does not exist. Use vips_image_get_typeof() to test for the existence of a field first if you are not certain it will be there.

For example, to read a double from an image (though of course you would use vips_image_get_double() in practice):

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
GValue value = { 0 };
double d;

if (vips_image_get (image, name, &value))
  return -1;

if (G_VALUE_TYPE (&value) != G_TYPE_DOUBLE) {
  vips_error( "mydomain", 
    _("field \"%s\" is of type %s, not double"),
    name, 
    g_type_name (G_VALUE_TYPE (&value)));
  g_value_unset (&value);
  return -1;
}

d = g_value_get_double (&value);
g_value_unset (&value);

See also: vips_image_get_typeof(), vips_image_get_double().

[method]

Parameters

image

image to get the field from from

 

name

the name to fetch

 

value_copy

the GValue is copied into this.

[transfer full][out caller-allocates]

Returns

0 on success, -1 otherwise.

[skip]


vips_image_get_as_string ()

int
vips_image_get_as_string (const VipsImage *image,
                          const char *name,
                          char **out);

Returns name from image in out . This function will read any field, returning it as a printable string. You need to free the string with g_free() when you are done with it.

This will base64-encode BLOBs, for example. Use vips_buf_appendgv() to make a string that's for humans.

See also: vips_image_get(), vips_image_get_typeof(), vips_buf_appendgv().

[method]

Parameters

image

image to get the header field from

 

name

field name

 

out

return field value as string.

[transfer full]

Returns

0 on success, -1 otherwise.


vips_image_get_typeof ()

GType
vips_image_get_typeof (const VipsImage *image,
                       const char *name);

Read the GType for a header field. Returns zero if there is no field of that name.

See also: vips_image_get().

[method]

Parameters

image

image to test

 

name

the name to search for

 

Returns

the GType of the field, or zero if there is no field of that name.


vips_image_remove ()

gboolean
vips_image_remove (VipsImage *image,
                   const char *name);

Find and remove an item of metadata. Return FALSE if no metadata of that name was found.

See also: vips_image_set(), vips_image_get_typeof().

[method]

Parameters

image

image to test

 

name

the name to search for

 

Returns

TRUE if an item of metadata of that name was found and removed


VipsImageMapFn ()

void *
(*VipsImageMapFn) (VipsImage *image,
                   const char *name,
                   GValue *value,
                   void *a);

vips_image_map ()

void *
vips_image_map (VipsImage *image,
                VipsImageMapFn fn,
                void *a);

This function calls fn for every header field, including every item of metadata.

Like all _map functions, the user function should return NULL to continue iteration, or a non-NULL pointer to indicate early termination.

See also: vips_image_get_typeof(), vips_image_get().

[method]

Parameters

image

image to map over

 

fn

function to call for each header field.

[scope call]

a

user data for function.

[closure fn]

Returns

NULL on success, the failing pointer otherwise.

[transfer none]


vips_image_get_fields ()

gchar **
vips_image_get_fields (VipsImage *image);

Get a NULL-terminated array listing all the metadata field names on image . Free the return result with g_strfreev().

This is handy for language bindings. From C, it's usually more convenient to use vips_image_map().

[method]

Parameters

image

image to get fields from

 

Returns

metadata fields in image, as a NULL-terminated array.

[transfer full]


vips_image_set_area ()

void
vips_image_set_area (VipsImage *image,
                     const char *name,
                     VipsCallbackFn free_fn,
                     void *data);

Attaches data as a metadata item on image under the name name . When VIPS no longer needs the metadata, it will be freed with free_fn .

See also: vips_image_get_double(), vips_image_set()

[method]

Parameters

image

image to attach the metadata to

 

name

metadata name

 

free_fn

free function for data .

[scope async]

data

pointer to area of memory

 

vips_image_get_area ()

int
vips_image_get_area (const VipsImage *image,
                     const char *name,
                     void **data);

Gets data from image under the name name . A convenience function over vips_image_get(). Use vips_image_get_typeof() to test for the existance of a piece of metadata.

See also: vips_image_set_area(), vips_image_get(), vips_image_get_typeof()

[method]

Parameters

image

image to get the metadata from

 

name

metadata name

 

data

return metadata value.

[out]

Returns

0 on success, -1 otherwise.


vips_image_set_blob ()

void
vips_image_set_blob (VipsImage *image,
                     const char *name,
                     VipsCallbackFn free_fn,
                     void *data,
                     size_t length);

Attaches blob as a metadata item on image under the name name . A convenience function over vips_image_set() using a vips_blob.

See also: vips_image_get_blob(), vips_image_set().

[method]

Parameters

image

image to attach the metadata to

 

name

metadata name

 

free_fn

free function for data .

[scope async]

data

pointer to area of memory

 

length

length of memory area

 

vips_image_get_blob ()

int
vips_image_get_blob (const VipsImage *image,
                     const char *name,
                     void **data,
                     size_t *length);

Gets blob from image under the name name , optionally returns its length in length . A convenience function over vips_image_get(). Use vips_image_get_typeof() to test for the existance of a piece of metadata.

See also: vips_image_get(), vips_image_get_typeof(), vips_blob_get(),

[method]

Parameters

image

image to get the metadata from

 

name

metadata name

 

data

pointer to area of memory

 

length

return the blob length here, optionally

 

Returns

0 on success, -1 otherwise.


vips_image_get_int ()

int
vips_image_get_int (const VipsImage *image,
                    const char *name,
                    int *out);

Gets out from im under the name name . The value will be transformed into an int, if possible.

See also: vips_image_get(), vips_image_get_typeof()

[method]

Parameters

image

image to get the header field from

 

name

field name

 

out

return field value.

[out]

Returns

0 on success, -1 otherwise.


vips_image_set_int ()

void
vips_image_set_int (VipsImage *image,
                    const char *name,
                    int i);

Attaches i as a metadata item on image under the name name . A convenience function over vips_image_set().

See also: vips_image_get_int(), vips_image_set()

[method]

Parameters

image

image to attach the metadata to

 

name

metadata name

 

i

metadata value

 

vips_image_get_double ()

int
vips_image_get_double (const VipsImage *image,
                       const char *name,
                       double *out);

Gets out from im under the name name . The value will be transformed into a double, if possible.

See also: vips_image_get(), vips_image_get_typeof()

[method]

Parameters

image

image to get the header field from

 

name

field name

 

out

return field value

 

Returns

0 on success, -1 otherwise.


vips_image_set_double ()

void
vips_image_set_double (VipsImage *image,
                       const char *name,
                       double d);

Attaches d as a metadata item on image as name . A convenience function over vips_image_set().

See also: vips_image_get_double(), vips_image_set()

[method]

Parameters

image

image to attach the metadata to

 

name

metadata name

 

d

metadata value

 

vips_image_get_string ()

int
vips_image_get_string (const VipsImage *image,
                       const char *name,
                       const char **out);

Gets out from im under the name name . The field must be of type VIPS_TYPE_REFSTRING.

Do not free out .

Use vips_image_get_as_string() to fetch any field as a string.

See also: vips_image_get(), vips_image_get_typeof()

[method]

Parameters

image

image to get the header field from

 

name

field name

 

out

return field value.

[transfer none]

Returns

0 on success, -1 otherwise.


vips_image_set_string ()

void
vips_image_set_string (VipsImage *image,
                       const char *name,
                       const char *str);

Attaches str as a metadata item on image as name . A convenience function over vips_image_set() using an vips_ref_string.

See also: vips_image_get_double(), vips_image_set(), vips_ref_string

[method]

Parameters

image

image to attach the metadata to

 

name

metadata name

 

str

metadata value

 

vips_image_print_field ()

void
vips_image_print_field (const VipsImage *image,
                        const char *field);

Prints field name to stdout as ASCII. Handy for debugging.

[method]

Parameters

image

image to get the header field from

 

name

field name

 

vips_image_history_printf ()

int
vips_image_history_printf (VipsImage *image,
                           const char *format,
                           ...);

Add a line to the image history. The format and arguments are expanded, the date and time is appended prefixed with a hash character, and the whole string is appended to the image history and terminated with a newline.

For example:

1
2
vips_image_history_printf (image, "vips invert %s %s", 
  in->filename, out->filename);

Might add the string

1
"vips invert /home/john/fred.v /home/john/jim.v # Fri Apr 3 23:30:35 2009\n"

VIPS operations don't add history lines for you because a single action at the application level might involve many VIPS operations. History must be recorded by the application.

[method]

Parameters

image

add history line to this image

 

format

printf() format string

 

...

arguments to format string

 

Returns

0 on success, -1 on error.


vips_image_history_args ()

int
vips_image_history_args (VipsImage *image,
                         const char *name,
                         int argc,
                         char *argv[]);

Formats the name/argv as a single string and calls vips_image_history_printf(). A convenience function for command-line prorams.

See also: vips_image_get_history().

[method]

Parameters

image

image to attach history line to

 

name

program name

 

argc

number of program arguments

 

argv

program arguments.

[array length=argc][element-type char*]

Returns

0 on success, -1 on error.


vips_image_get_history ()

const char *
vips_image_get_history (VipsImage *image);

This function reads the image history as a C string. The string is owned by VIPS and must not be freed.

VIPS tracks the history of each image, that is, the sequence of operations that generated that image. Applications built on VIPS need to call vips_image_history_printf() for each action they perform, setting the command-line equivalent for the action.

See also: vips_image_history_printf().

[method]

Parameters

image

get history from here

 

Returns

The history of image as a C string. Do not free!.

[transfer none]

Types and Values

VIPS_META_EXIF_NAME

#define VIPS_META_EXIF_NAME "exif-data"

The name that JPEG read and write operations use for the image's EXIF data.


VIPS_META_XMP_NAME

#define VIPS_META_XMP_NAME "xmp-data"

The name that read and write operations use for the image's XMP data.


VIPS_META_IPTC_NAME

#define VIPS_META_IPTC_NAME "iptc-data"

The name that read and write operations use for the image's IPTC data.


VIPS_META_PHOTOSHOP_NAME

#define VIPS_META_PHOTOSHOP_NAME "photoshop-data"

The name that TIFF read and write operations use for the image's TIFFTAG_PHOTOSHOP data.


VIPS_META_ICC_NAME

#define VIPS_META_ICC_NAME "icc-profile-data"

The name we use to attach an ICC profile. The file read and write operations for TIFF, JPEG, PNG and others use this item of metadata to attach and save ICC profiles. The profile is updated by the vips_icc_transform() operations.


VIPS_META_IMAGEDESCRIPTION

#define VIPS_META_IMAGEDESCRIPTION "image-description"

The IMAGEDESCRIPTION tag. Often has useful metadata.


VIPS_META_RESOLUTION_UNIT

#define VIPS_META_RESOLUTION_UNIT "resolution-unit"

The JPEG and TIFF read and write operations use this to record the file's preferred unit for resolution.


VIPS_META_LOADER

#define VIPS_META_LOADER "vips-loader"

Record the name of the original loader here. Handy for hinting file formats and for debugging.


VIPS_META_SEQUENTIAL

#define VIPS_META_SEQUENTIAL "vips-sequential"

Images loaded via vips_sequential() have this int field defined. Some operations (eg. vips_shrinkv()) add extra caches if they see it on their input.


VIPS_META_ORIENTATION

#define VIPS_META_ORIENTATION "orientation"

The orientation tag for this image. An int from 1 - 8 using the standard exif/tiff meanings.

  • 1 - The 0th row represents the visual top of the image, and the 0th column represents the visual left-hand side.

  • 2 - The 0th row represents the visual top of the image, and the 0th column represents the visual right-hand side.

  • 3 - The 0th row represents the visual bottom of the image, and the 0th column represents the visual right-hand side.

  • 4 - The 0th row represents the visual bottom of the image, and the 0th column represents the visual left-hand side.

  • 5 - The 0th row represents the visual left-hand side of the image, and the 0th column represents the visual top.

  • 6 - The 0th row represents the visual right-hand side of the image, and the 0th column represents the visual top.

  • 7 - The 0th row represents the visual right-hand side of the image, and the 0th column represents the visual bottom.

  • 8 - The 0th row represents the visual left-hand side of the image, and the 0th column represents the visual bottom.


VIPS_META_PAGE_HEIGHT

#define VIPS_META_PAGE_HEIGHT "page-height"

If set, the height of each page when this image was loaded. If you save an image with "page-height" set to a format that supports multiple pages, such as tiff, the image will be saved as a series of pages.


VIPS_META_N_PAGES

#define VIPS_META_N_PAGES "n-pages"

If set, the number of pages in the original file.

See Also

type