meta

meta — get and set image metadata

Stability Level

Stable, unless otherwise indicated

Synopsis

#include <vips/vips.h>

#define             IM_META_EXIF_NAME
#define             IM_META_ICC_NAME
#define             IM_META_XML
#define             IM_META_RESOLUTION_UNIT
#define             IM_TYPE_SAVE_STRING
GType               im_save_string_get_type             (void);
const char *        im_save_string_get                  (const GValue *value);
void                im_save_string_set                  (GValue *value,
                                                         const char *str);
void                im_save_string_setf                 (GValue *value,
                                                         const char *fmt,
                                                         ...);
#define             IM_TYPE_AREA
GType               im_area_get_type                    (void);
#define             IM_TYPE_REF_STRING
GType               im_ref_string_get_type              (void);
int                 im_ref_string_set                   (GValue *value,
                                                         const char *str);
const char *        im_ref_string_get                   (const GValue *value);
size_t              im_ref_string_get_length            (const GValue *value);
#define             IM_TYPE_BLOB
GType               im_blob_get_type                    (void);
void *              im_blob_get                         (const GValue *value,
                                                         size_t *length);
int                 im_blob_set                         (GValue *value,
                                                         im_callback_fn free_fn,
                                                         void *data,
                                                         size_t length);
int                 im_meta_set                         (IMAGE *im,
                                                         const char *field,
                                                         GValue *value);
gboolean            im_meta_remove                      (IMAGE *im,
                                                         const char *field);
int                 im_meta_get                         (IMAGE *im,
                                                         const char *field,
                                                         GValue *value_copy);
GType               im_meta_get_typeof                  (IMAGE *im,
                                                         const char *field);
int                 im_meta_set_int                     (IMAGE *im,
                                                         const char *field,
                                                         int i);
int                 im_meta_get_int                     (IMAGE *im,
                                                         const char *field,
                                                         int *i);
int                 im_meta_set_double                  (IMAGE *im,
                                                         const char *field,
                                                         double d);
int                 im_meta_get_double                  (IMAGE *im,
                                                         const char *field,
                                                         double *d);
int                 im_meta_set_area                    (IMAGE *im,
                                                         const char *field,
                                                         im_callback_fn free_fn,
                                                         void *data);
int                 im_meta_get_area                    (IMAGE *im,
                                                         const char *field,
                                                         void **data);
int                 im_meta_set_string                  (IMAGE *im,
                                                         const char *field,
                                                         const char *str);
int                 im_meta_get_string                  (IMAGE *im,
                                                         const char *field,
                                                         char **str);
int                 im_meta_set_blob                    (IMAGE *im,
                                                         const char *field,
                                                         im_callback_fn free_fn,
                                                         void *data,
                                                         size_t length);
int                 im_meta_get_blob                    (IMAGE *im,
                                                         const char *field,
                                                         void **data,
                                                         size_t *length);

Description

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. im_meta_set_int()) let you easily attach simple types like numbers, strings and memory blocks to images. Use im_header_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 pofile 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 'edvips' 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 "im_save_string", a variety of string. If your GValue can be transformed to im_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.

Details

IM_META_EXIF_NAME

#define IM_META_EXIF_NAME "exif-data"

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


IM_META_ICC_NAME

#define IM_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 im_icc_transform() operations.


IM_META_XML

#define IM_META_XML "xml-header"

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


IM_META_RESOLUTION_UNIT

#define IM_META_RESOLUTION_UNIT "resolution-unit"

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


IM_TYPE_SAVE_STRING

#define IM_TYPE_SAVE_STRING (im_save_string_get_type())

The GType for an "im_save_string".


im_save_string_get_type ()

GType               im_save_string_get_type             (void);

im_save_string_get ()

const char *        im_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.

im_save_string_set ()

void                im_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

im_save_string_setf ()

void                im_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

IM_TYPE_AREA

#define IM_TYPE_AREA (im_area_get_type())

The GType for an im_area.


im_area_get_type ()

GType               im_area_get_type                    (void);

IM_TYPE_REF_STRING

#define IM_TYPE_REF_STRING (im_ref_string_get_type())

The GType for an im_refstring.


im_ref_string_get_type ()

GType               im_ref_string_get_type              (void);

im_ref_string_set ()

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

Copies the C string str into value.

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

im_ref_string_get ()

const char *        im_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.

im_ref_string_get_length ()

size_t              im_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.

IM_TYPE_BLOB

#define IM_TYPE_BLOB (im_blob_get_type())

The GType for an im_blob.


im_blob_get_type ()

GType               im_blob_get_type                    (void);

im_blob_get ()

void *              im_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: im_blob_set().

value :

GValue to get from

length :

return the blob length here, optionally

Returns :

The blob address.

im_blob_set ()

int                 im_blob_set                         (GValue *value,
                                                         im_callback_fn 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: im_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.

im_meta_set ()

int                 im_meta_set                         (IMAGE *im,
                                                         const char *field,
                                                         GValue *value);

Set a piece of metadata on im. 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 im_meta_set_int() in practice), you would need:

GValue value = { 0 };

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

if( im_meta_set( im, field, &value ) ) {
  g_value_unset( &value );
  return( -1 );
}
g_value_unset( &value );

return( 0 );

See also: im_meta_get().

im :

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.

im_meta_remove ()

gboolean            im_meta_remove                      (IMAGE *im,
                                                         const char *field);

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

See also: im_meta_set(), im_meta_get_typeof().

im :

image to test

field :

the name to search for

Returns :

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

im_meta_get ()

int                 im_meta_get                         (IMAGE *im,
                                                         const char *field,
                                                         GValue *value_copy);

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

This will return -1 and add a message to the error buffer if the item of metadata does not exist. Use im_meta_get_typeof() to test for the existence of a piece of metadata 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 im_meta_get_double() in practice):

GValue value = { 0 };
double d;

if( im_meta_get( im, field, &value ) )
  return( -1 );

if( G_VALUE_TYPE( &value ) != G_TYPE_DOUBLE ) {
  im_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: im_meta_get_typeof(), im_meta_set().

im :

image to get the metadata from

field :

the name to give the metadata

value_copy :

the GValue is copied into this

Returns :

0 on success, -1 otherwise.

im_meta_get_typeof ()

GType               im_meta_get_typeof                  (IMAGE *im,
                                                         const char *field);

Read the GType for an item of metadata. Returns zero if there is no metadata of that name.

See also: im_meta_get().

im :

image to test

field :

the name to search for

Returns :

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

im_meta_set_int ()

int                 im_meta_set_int                     (IMAGE *im,
                                                         const char *field,
                                                         int i);

Attaches i as a metadata item on im under the name field. A convenience function over im_meta_set().

See also: im_meta_get_int(), im_meta_set()

im :

image to attach the metadata to

field :

metadata name

i :

metadata value

Returns :

0 on success, -1 otherwise.

im_meta_get_int ()

int                 im_meta_get_int                     (IMAGE *im,
                                                         const char *field,
                                                         int *i);

Gets i from im under the name field. A convenience function over im_meta_get(). Use im_meta_get_typeof() to test for the existance of a piece of metadata.

See also: im_meta_set_int(), im_meta_get(), im_meta_get_typeof()

im :

image to get the metadata from

field :

metadata name

i :

return metadata value

Returns :

0 on success, -1 otherwise.

im_meta_set_double ()

int                 im_meta_set_double                  (IMAGE *im,
                                                         const char *field,
                                                         double d);

Attaches d as a metadata item on im under the name field. A convenience function over im_meta_set().

See also: im_meta_get_double(), im_meta_set()

im :

image to attach the metadata to

field :

metadata name

d :

metadata value

Returns :

0 on success, -1 otherwise.

im_meta_get_double ()

int                 im_meta_get_double                  (IMAGE *im,
                                                         const char *field,
                                                         double *d);

Gets d from im under the name field. A convenience function over im_meta_get(). Use im_meta_get_typeof() to test for the existance of a piece of metadata.

See also: im_meta_set_double(), im_meta_get(), im_meta_get_typeof()

im :

image to get the metadata from

field :

metadata name

d :

return metadata value

Returns :

0 on success, -1 otherwise.

im_meta_set_area ()

int                 im_meta_set_area                    (IMAGE *im,
                                                         const char *field,
                                                         im_callback_fn free_fn,
                                                         void *data);

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

See also: im_meta_get_double(), im_meta_set()

im :

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.

im_meta_get_area ()

int                 im_meta_get_area                    (IMAGE *im,
                                                         const char *field,
                                                         void **data);

Gets data from im under the name field. A convenience function over im_meta_get(). Use im_meta_get_typeof() to test for the existance of a piece of metadata.

See also: im_meta_set_area(), im_meta_get(), im_meta_get_typeof()

im :

image to get the metadata from

field :

metadata name

data :

return metadata value

Returns :

0 on success, -1 otherwise.

im_meta_set_string ()

int                 im_meta_set_string                  (IMAGE *im,
                                                         const char *field,
                                                         const char *str);

Attaches str as a metadata item on im under the name field. A convenience function over im_meta_set() using an im_ref_string.

See also: im_meta_get_double(), im_meta_set(), im_ref_string

im :

image to attach the metadata to

field :

metadata name

str :

metadata value

Returns :

0 on success, -1 otherwise.

im_meta_get_string ()

int                 im_meta_get_string                  (IMAGE *im,
                                                         const char *field,
                                                         char **str);

Gets str from im under the name field. A convenience function over im_meta_get(). Use im_meta_get_typeof() to test for the existance of a piece of metadata.

See also: im_meta_set_string(), im_meta_get(), im_meta_get_typeof(), im_ref_string

im :

image to get the metadata from

field :

metadata name

str :

return metadata value

Returns :

0 on success, -1 otherwise.

im_meta_set_blob ()

int                 im_meta_set_blob                    (IMAGE *im,
                                                         const char *field,
                                                         im_callback_fn free_fn,
                                                         void *data,
                                                         size_t length);

Attaches blob as a metadata item on im under the name field. A convenience function over im_meta_set() using an im_blob.

See also: im_meta_get_blob(), im_meta_set(), im_blob

im :

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.

im_meta_get_blob ()

int                 im_meta_get_blob                    (IMAGE *im,
                                                         const char *field,
                                                         void **data,
                                                         size_t *length);

Gets blob from im under the name field, optionally return its length in length. A convenience function over im_meta_get(). Use im_meta_get_typeof() to test for the existance of a piece of metadata.

See also: im_meta_get(), im_meta_get_typeof(), im_blob_get(),

im :

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.

See Also

header