## 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_XML
    #define             VIPS_META_RESOLUTION_UNIT
    int                 vips_format_sizeof                  (VipsBandFormat format);
    int                 vips_image_get_width                (VipsImage *image);
    int                 vips_image_get_height               (VipsImage *image);
    int                 vips_image_get_bands                (VipsImage *image);
    VipsBandFormat      vips_image_get_format               (VipsImage *image);
    VipsCoding          vips_image_get_coding               (VipsImage *image);
    VipsInterpretation  vips_image_get_interpretation       (VipsImage *image);
    double              vips_image_get_xres                 (VipsImage *image);
    double              vips_image_get_yres                 (VipsImage *image);
    int                 vips_image_get_xoffset              (VipsImage *image);
    int                 vips_image_get_yoffset              (VipsImage *image);
    const char *        vips_image_get_filename             (VipsImage *image);
    const char *        vips_image_get_mode                 (VipsImage *image);
    void *              vips_image_get_data                 (VipsImage *image);
    void                vips_image_init_fields              (VipsImage *image,
                                                             int xsize,
                                                             int ysize,
                                                             int bands,
                                                             VipsBandFormat format,
                                                             VipsCoding coding,
                                                             VipsInterpretation interpretation,
                                                             float xres,
                                                             float yres);
    int                 vips_image_copy_fields_array        (VipsImage *out,
                                                             VipsImage *in[]);
    int                 vips_image_copy_fieldsv             (VipsImage *out,
                                                             VipsImage *in1,
                                                             ...);
    int                 vips_image_copy_fields              (VipsImage *out,
                                                             VipsImage *in);
    int                 vips_image_set                      (VipsImage *image,
                                                             const char *field,
                                                             GValue *value);
    int                 vips_image_get                      (VipsImage *image,
                                                             const char *field,
                                                             GValue *value_copy);
    GType               vips_image_get_typeof               (VipsImage *image,
                                                             const char *field);
    gboolean            vips_image_remove                   (VipsImage *image,
                                                             const char *field);
    void *              (*VipsImageMapFn)                   (VipsImage *image,
                                                             const char *field,
                                                             GValue *value,
                                                             void *a);
    void *              vips_image_map                      (VipsImage *im,
                                                             VipsImageMapFn fn,
                                                             void *a);
    #define             VIPS_TYPE_SAVE_STRING
    GType               vips_save_string_get_type           (void);
    const char *        vips_save_string_get                (const GValue *value);
    void                vips_save_string_set                (GValue *value,
                                                             const char *str);
    void                vips_save_string_setf               (GValue *value,
                                                             const char *fmt,
                                                             ...);
    #define             VIPS_TYPE_AREA
    GType               vips_area_get_type                  (void);
    #define             VIPS_TYPE_REF_STRING
    GType               vips_ref_string_get_type            (void);
    int                 vips_ref_string_set                 (GValue *value,
                                                             const char *str);
    const char *        vips_ref_string_get                 (const GValue *value);
    size_t              vips_ref_string_get_length          (const GValue *value);
    int                 (*VipsCallbackFn)                   (void *a,
                                                             void *b);
    #define             VIPS_TYPE_BLOB
    GType               vips_blob_get_type                  (void);
    void *              vips_blob_get                       (const GValue *value,
                                                             size_t *length);
    int                 vips_blob_set                       (GValue *value,
                                                             VipsCallbackFn free_fn,
                                                             void *data,
                                                             size_t length);
    int                 vips_image_set_area                 (VipsImage *image,
                                                             const char *field,
                                                             VipsCallbackFn free_fn,
                                                             void *data);
    int                 vips_image_get_area                 (VipsImage *image,
                                                             const char *field,
                                                             void **data);
    int                 vips_image_set_string               (VipsImage *image,
                                                             const char *field,
                                                             const char *str);
    int                 vips_image_get_string               (VipsImage *image,
                                                             const char *field,
                                                             char **str);
    int                 vips_image_set_blob                 (VipsImage *image,
                                                             const char *field,
                                                             VipsCallbackFn free_fn,
                                                             void *data,
                                                             size_t length);
    int                 vips_image_get_blob                 (VipsImage *image,
                                                             const char *field,
                                                             void **data,
                                                             size_t *length);
    int                 vips_image_get_int                  (VipsImage *image,
                                                             const char *field,
                                                             int *out);
    int                 vips_image_set_int                  (VipsImage *image,
                                                             const char *field,
                                                             int i);
    int                 vips_image_get_double               (VipsImage *image,
                                                             const char *field,
                                                             double *out);
    int                 vips_image_set_double               (VipsImage *image,
                                                             const char *field,
                                                             double d);
    int                 vips_image_get_as_string            (VipsImage *image,
                                                             const char *field,
                                                             char **out);
    int                 vips_image_history_printf           (VipsImage *image,
                                                             const char *format,
                                                             ...);
    int                 vips_image_history_args             (VipsImage *image,
                                                             const char *name,
                                                             int argc,
                                                             char *argv[]);
    const char *        vips_image_get_history              (VipsImage *image);

## 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_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_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_format_sizeof ()

    int                 vips_format_sizeof                  (VipsBandFormat format);

### vips_image_get_width ()

    int                 vips_image_get_width                (VipsImage *image);

### vips_image_get_height ()

    int                 vips_image_get_height               (VipsImage *image);

### vips_image_get_bands ()

    int                 vips_image_get_bands                (VipsImage *image);

### vips_image_get_format ()

    VipsBandFormat      vips_image_get_format               (VipsImage *image);

### vips_image_get_coding ()

    VipsCoding          vips_image_get_coding               (VipsImage *image);

### vips_image_get_interpretation ()

    VipsInterpretation  vips_image_get_interpretation       (VipsImage *image);

### vips_image_get_xres ()

    double              vips_image_get_xres                 (VipsImage *image);

### vips_image_get_yres ()

    double              vips_image_get_yres                 (VipsImage *image);

### vips_image_get_xoffset ()

    int                 vips_image_get_xoffset              (VipsImage *image);

### vips_image_get_yoffset ()

    int                 vips_image_get_yoffset              (VipsImage *image);

### vips_image_get_filename ()

    const char *        vips_image_get_filename             (VipsImage *image);

### vips_image_get_mode ()

    const char *        vips_image_get_mode                 (VipsImage *image);

### vips_image_get_data ()

    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.

See also: `vips_image_wio_input()`.

`image` : | image to get data for
Returns : | a pointer to pixel data, if possible.

### vips_image_init_fields ()

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

A convenience function to set the header fields after creating an image. Normally you copy the fields from one of your input images with `vips_image_copy_fields()` 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: `vips_image_copy_fields()`.

`image` : | image to init
`xsize` : | image width
`ysize` : | image height
`bands` : | image bands
`bandfmt` : | band format
`coding` : | image coding
`type` : | image type
`xres` : | horizontal resolution, pixels per millimetre
`yres` : | vertical resolution, pixels per millimetre

### 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
`...` : | `NULL`-terminated list of images to copy from
Returns : | 0 on success, -1 on error.

### 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_set ()

    int                 vips_image_set                      (VipsImage *image,
                                                             const char *field,
                                                             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 need:

    GValue value = { 0 };

    g_value_init( &value, G_TYPE_INT );
    g_value_set_int( &value, 42 );

    if( vips_image_set( image, field, &value ) ) {
      g_value_unset( &value );
      return( -1 );
    }
    g_value_unset( &value );

    return( 0 );

See also: `vips_image_get()`.

`image` : | image to set the metadata on
`field` : | the name to give the metadata
`value` : | the GValue to copy into the image
Returns : | 0 on success, -1 otherwise.

### 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):

    GValue value = { 0 };
    double d;

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

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

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

    return( 0 );

See also: `vips_image_get_typeof()`, `vips_image_get_double()`.

`image` : | image to get the field from from
`field` : | the name to give the metadata
`value_copy` : | the GValue is copied into this
Returns : | 0 on success, -1 otherwise.

### vips_image_get_typeof ()

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

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

See also: `vips_image_get()`.

`image` : | image to test
`field` : | 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 *field);

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

`image` : | image to test
`field` : | 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 *field,
                                                             GValue *value,
                                                             void *a);

### vips_image_map ()

    void *              vips_image_map                      (VipsImage *im,
                                                             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()`.

`image` : | image to map over
`fn` : | function to call for each header field
`a` : | user data for function
Returns : | `NULL` on success, the failing pointer otherwise.

### VIPS_TYPE_SAVE_STRING

    #define VIPS_TYPE_SAVE_STRING (vips_save_string_get_type())

The GType for an "vips_save_string".

### vips_save_string_get_type ()

    GType               vips_save_string_get_type           (void);

### vips_save_string_get ()

    const char *        vips_save_string_get                (const GValue *value);

Get the C string held internally by the GValue.

`value` : | GValue to get from
Returns : | The C string held by `value`. This must not be freed.

### vips_save_string_set ()

    void                vips_save_string_set                (GValue *value,
                                                             const char *str);

Copies the C string into `value`.

`value` : | GValue to set
`str` : | C string to copy into the GValue

### vips_save_string_setf ()

    void                vips_save_string_setf               (GValue *value,
                                                             const char *fmt,
                                                             ...);

Generates a string and copies it into `value`.

`value` : | GValue to set
`fmt` : | printf()-style format string
`...` : | arguments to `printf()`-formatted `fmt`

### VIPS_TYPE_AREA

    #define VIPS_TYPE_AREA (vips_area_get_type())

The GType for an vips_area.

### vips_area_get_type ()

    GType               vips_area_get_type                  (void);

### VIPS_TYPE_REF_STRING

    #define VIPS_TYPE_REF_STRING (vips_ref_string_get_type())

The GType for an vips_refstring.

### vips_ref_string_get_type ()

    GType               vips_ref_string_get_type            (void);

### vips_ref_string_set ()

    int                 vips_ref_string_set                 (GValue *value,
                                                             const char *str);

Copies the C string `str` into `value`.

vips_ref_string are immutable C strings that are copied between images by copying reference-counted pointers, making the much more efficient than regular GValue strings.

`value` : | GValue to set
`str` : | C string to copy into the GValue
Returns : | 0 on success, -1 otherwise.

### vips_ref_string_get ()

    const char *        vips_ref_string_get                 (const GValue *value);

Get the C string held internally by the GValue.

`value` : | GValue to get from
Returns : | The C string held by `value`. This must not be freed.

### vips_ref_string_get_length ()

    size_t              vips_ref_string_get_length          (const GValue *value);

Gets the cached string length held internally by the refstring.

`value` : | GValue to get from
Returns : | The length of the string.

### VipsCallbackFn ()

    int                 (*VipsCallbackFn)                   (void *a,
                                                             void *b);

### VIPS_TYPE_BLOB

    #define VIPS_TYPE_BLOB (vips_blob_get_type())

The GType for an vips_blob.

### vips_blob_get_type ()

    GType               vips_blob_get_type                  (void);

### vips_blob_get ()

    void *              vips_blob_get                       (const GValue *value,
                                                             size_t *length);

Get the address of the blob (binary large object) being held in `value` and optionally return its length in `length`.

See also: `vips_blob_set()`.

`value` : | GValue to get from
`length` : | return the blob length here, optionally
Returns : | The blob address.

### vips_blob_set ()

    int                 vips_blob_set                       (GValue *value,
                                                             VipsCallbackFn free_fn,
                                                             void *data,
                                                             size_t length);

Sets `value` to hold a pointer to `blob`. When `value` is freed, `blob` will be freed with `free_fn`. `value` also holds a note of the length of the memory area.

blobs are things like ICC profiles or EXIF data. They are relocatable, and are saved to VIPS files for you coded as base64 inside the XML. They are copied by copying reference-counted pointers.

See also: `vips_blob_get()`

`value` : | GValue to set
`free_fn` : | free function for `data`
`data` : | pointer to area of memory
`length` : | length of memory area
Returns : | 0 on success, -1 otherwise.

### vips_image_set_area ()

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

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

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

`image` : | image to attach the metadata to
`field` : | metadata name
`free_fn` : | free function for `data`
`data` : | pointer to area of memory
Returns : | 0 on success, -1 otherwise.

### vips_image_get_area ()

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

Gets `data` from `image` under the name `field`. 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()`

`image` : | image to get the metadata from
`field` : | metadata name
`data` : | return metadata value
Returns : | 0 on success, -1 otherwise.

### vips_image_set_string ()

    int                 vips_image_set_string               (VipsImage *image,
                                                             const char *field,
                                                             const char *str);

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

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

`image` : | image to attach the metadata to
`field` : | metadata name
`str` : | metadata value
Returns : | 0 on success, -1 otherwise.

### vips_image_get_string ()

    int                 vips_image_get_string               (VipsImage *image,
                                                             const char *field,
                                                             char **str);

Gets `out` from `im` under the name `field`. This function searches for string-valued fields.

Do not free `out`.

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

`image` : | image to get the header field from
`field` : | field name
`out` : | return field value
Returns : | 0 on success, -1 otherwise.

### vips_image_set_blob ()

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

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

See also: `vips_image_get_blob()`, `vips_image_set()`.

`image` : | image to attach the metadata to
`field` : | metadata name
`free_fn` : | free function for `data`
`data` : | pointer to area of memory
`length` : | length of memory area
Returns : | 0 on success, -1 otherwise.

### vips_image_get_blob ()

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

Gets `blob` from `image` under the name `field`, optionally return 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()`,

`image` : | image to get the metadata from
`field` : | 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                  (VipsImage *image,
                                                             const char *field,
                                                             int *out);

Gets `out` from `im` under the name `field`. This function searches for int-valued fields.

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

`image` : | image to get the header field from
`field` : | field name
`out` : | return field value
Returns : | 0 on success, -1 otherwise.

### vips_image_set_int ()

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

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

See also: `vips_image_get_int()`, `vips_image_set()`

`image` : | image to attach the metadata to
`field` : | metadata name
`i` : | metadata value
Returns : | 0 on success, -1 otherwise.

### vips_image_get_double ()

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

Gets `out` from `im` under the name `field`. This function searches for double-valued fields.

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

`image` : | image to get the header field from
`field` : | field name
`out` : | return field value
Returns : | 0 on success, -1 otherwise.

### vips_image_set_double ()

    int                 vips_image_set_double               (VipsImage *image,
                                                             const char *field,
                                                             double d);

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

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

`image` : | image to attach the metadata to
`field` : | metadata name
`d` : | metadata value
Returns : | 0 on success, -1 otherwise.

### vips_image_get_as_string ()

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

Gets `out` from `im` under the name `field`. 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.

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

`image` : | image to get the header field from
`field` : | field name
`out` : | return field value as string
Returns : | 0 on success, -1 otherwise.

### 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:

    vips_image_history_printf( image, "vips im_invert %s %s",
      in->filename, out->filename );

Might add the string

    "vips im_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.

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

`out` : | image to attach history line to
`name` : | program name
`argc` : | number of program arguments
`argv` : | program arguments
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()`.

`image` : | get history from here
Returns : | The history of `image` as a C string. Do not free!

## See Also

meta, check