## header header — get, set and walk image headers |

## Stability Level

Stable, unless otherwise indicated

## Functions

guint64 | vips_format_sizeof ()
guint64 | vips_format_sizeof_unsafe ()
int | vips_image_get_width ()
int | vips_image_get_height ()
int | vips_image_get_bands ()
VipsBandFormat | vips_image_get_format ()
VipsBandFormat | vips_image_guess_format ()
VipsCoding | vips_image_get_coding ()
VipsInterpretation | vips_image_get_interpretation ()
VipsInterpretation | vips_image_guess_interpretation ()
double | vips_image_get_xres ()
double | vips_image_get_yres ()
int | vips_image_get_xoffset ()
int | vips_image_get_yoffset ()
const char * | vips_image_get_filename ()
const char * | vips_image_get_mode ()
double | vips_image_get_scale ()
double | vips_image_get_offset ()
const void * | vips_image_get_data ()
void | vips_image_init_fields ()
void | vips_image_set ()
int | vips_image_get ()
int | vips_image_get_as_string ()
GType | vips_image_get_typeof ()
gboolean | vips_image_remove ()
void * | (*VipsImageMapFn) ()
void * | vips_image_map ()
gchar ** | vips_image_get_fields ()
void | vips_image_set_area ()
int | vips_image_get_area ()
void | vips_image_set_blob ()
int | vips_image_get_blob ()
int | vips_image_get_int ()
void | vips_image_set_int ()
int | vips_image_get_double ()
void | vips_image_set_double ()
int | vips_image_get_string ()
void | vips_image_set_string ()
void | vips_image_print_field ()
int | vips_image_history_printf ()
int | vips_image_history_args ()
const char * | vips_image_get_history ()

## Types and Values

#define | VIPS_META_EXIF_NAME
#define | VIPS_META_XMP_NAME
#define | VIPS_META_IPTC_NAME
#define | VIPS_META_PHOTOSHOP_NAME
#define | VIPS_META_ICC_NAME
#define | VIPS_META_IMAGEDESCRIPTION
#define | VIPS_META_RESOLUTION_UNIT
#define | VIPS_META_LOADER
#define | VIPS_META_SEQUENTIAL
#define | VIPS_META_ORIENTATION
#define | VIPS_META_PAGE_HEIGHT
#define | VIPS_META_N_PAGES

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