header

header — get, set and walk image headers

Stability Level

Stable, unless otherwise indicated

Synopsis

#include <vips/vips.h>

#define             VIPS_META_EXIF_NAME
#define             VIPS_META_ICC_NAME
#define             VIPS_META_IPCT_NAME
#define             VIPS_META_LOADER
#define             VIPS_META_RESOLUTION_UNIT
#define             VIPS_META_XML
#define             VIPS_META_XMP_NAME
void *              (*VipsImageMapFn)                   (VipsImage *image,
                                                         const char *field,
                                                         GValue *value,
                                                         void *a);
guint64             vips_format_sizeof                  (VipsBandFormat format);
int                 vips_image_copy_fields              (VipsImage *out,
                                                         VipsImage *in);
int                 vips_image_copy_fields_array        (VipsImage *out,
                                                         VipsImage *in[]);
int                 vips_image_copy_fieldsv             (VipsImage *out,
                                                         VipsImage *in1,
                                                         ...);
int                 vips_image_get                      (VipsImage *image,
                                                         const char *field,
                                                         GValue *value_copy);
int                 vips_image_get_area                 (VipsImage *image,
                                                         const char *field,
                                                         void **data);
int                 vips_image_get_as_string            (VipsImage *image,
                                                         const char *field,
                                                         char **out);
int                 vips_image_get_bands                (const VipsImage *image);
int                 vips_image_get_blob                 (VipsImage *image,
                                                         const char *field,
                                                         void **data,
                                                         size_t *length);
VipsCoding          vips_image_get_coding               (const VipsImage *image);
void *              vips_image_get_data                 (VipsImage *image);
int                 vips_image_get_double               (VipsImage *image,
                                                         const char *field,
                                                         double *out);
const char *        vips_image_get_filename             (const VipsImage *image);
VipsBandFormat      vips_image_get_format               (const VipsImage *image);
int                 vips_image_get_height               (const VipsImage *image);
const char *        vips_image_get_history              (VipsImage *image);
int                 vips_image_get_int                  (VipsImage *image,
                                                         const char *field,
                                                         int *out);
VipsInterpretation  vips_image_get_interpretation       (const VipsImage *image);
const char *        vips_image_get_mode                 (const VipsImage *image);
int                 vips_image_get_string               (VipsImage *image,
                                                         const char *field,
                                                         char **out);
GType               vips_image_get_typeof               (VipsImage *image,
                                                         const char *field);
int                 vips_image_get_width                (const VipsImage *image);
int                 vips_image_get_xoffset              (const VipsImage *image);
double              vips_image_get_xres                 (const VipsImage *image);
int                 vips_image_get_yoffset              (const VipsImage *image);
double              vips_image_get_yres                 (const VipsImage *image);
VipsInterpretation  vips_image_guess_interpretation     (const VipsImage *image);
int                 vips_image_history_args             (VipsImage *image,
                                                         const char *name,
                                                         int argc,
                                                         char *argv[]);
int                 vips_image_history_printf           (VipsImage *image,
                                                         const char *format,
                                                         ...);
void                vips_image_init_fields              (VipsImage *image,
                                                         int xsize,
                                                         int ysize,
                                                         int bands,
                                                         VipsBandFormat format,
                                                         VipsCoding coding,
                                                         VipsInterpretation interpretation,
                                                         double xres,
                                                         double yres);
void *              vips_image_map                      (VipsImage *image,
                                                         VipsImageMapFn fn,
                                                         void *a);
gboolean            vips_image_remove                   (VipsImage *image,
                                                         const char *field);
void                vips_image_set                      (VipsImage *image,
                                                         const char *field,
                                                         GValue *value);
void                vips_image_set_area                 (VipsImage *image,
                                                         const char *field,
                                                         VipsCallbackFn free_fn,
                                                         void *data);
void                vips_image_set_blob                 (VipsImage *image,
                                                         const char *field,
                                                         VipsCallbackFn free_fn,
                                                         void *data,
                                                         size_t length);
void                vips_image_set_double               (VipsImage *image,
                                                         const char *field,
                                                         double d);
void                vips_image_set_int                  (VipsImage *image,
                                                         const char *field,
                                                         int i);
void                vips_image_set_string               (VipsImage *image,
                                                         const char *field,
                                                         const char *str);

Description

These functions let you get at image header data (including metadata) in a uniform way. They are handy for language bindings but less useful for C users.

They first search the VIPS header fields (see image), then search for a metadata field of that name (see meta). Use vips_image_get_typeof() to test for the existance and GType of a header field.

See meta for a set of functions for adding new metadata to an image.

Details

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_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_IPCT_NAME

#define VIPS_META_IPCT_NAME "ipct-data"

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


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_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_XML

#define VIPS_META_XML "xml-header"

The original XML that was used to code the metadata after reading a VIPS format file.


VIPS_META_XMP_NAME

#define VIPS_META_XMP_NAME "xmp-data"

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


VipsImageMapFn ()

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


vips_format_sizeof ()

guint64             vips_format_sizeof                  (VipsBandFormat format);


vips_image_copy_fields ()

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

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

See also: vips_image_copy_fields_array(), vips_image_copy_fieldsv().

out :

image to copy to

in :

image to copy from

Returns :

0 on success, -1 on error.

vips_image_copy_fields_array ()

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

Copy fields from all the input images to the output image. There must be at least one input image.

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

Metadata from all the images 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: vips_image_copy_fieldsv(), vips_image_copy_fields().

out :

image to copy to

in :

NULL-terminated array of images to copy from

Returns :

0 on success, -1 on error.

vips_image_copy_fieldsv ()

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

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

See also: vips_image_copy_fields_array(), vips_image_copy_fields().

out :

image to copy to

in1 :

first image to copy from

Returns :

0 on success, -1 on error.

vips_image_get ()

int                 vips_image_get                      (VipsImage *image,
                                                         const char *field,
                                                         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
18
19
20
21
22