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_XMP_NAME
#define             VIPS_META_IPCT_NAME
#define             VIPS_META_ICC_NAME
#define             VIPS_META_XML
#define             VIPS_META_RESOLUTION_UNIT
#define             VIPS_META_LOADER
guint64             vips_format_sizeof                  (VipsBandFormat format);
int                 vips_image_get_width                (const VipsImage *image);
int                 vips_image_get_height               (const VipsImage *image);
int                 vips_image_get_bands                (const VipsImage *image);
VipsBandFormat      vips_image_get_format               (const VipsImage *image);
VipsCoding          vips_image_get_coding               (const VipsImage *image);
VipsInterpretation  vips_image_get_interpretation       (const VipsImage *image);
VipsInterpretation  vips_image_guess_interpretation     (const VipsImage *image);
double              vips_image_get_xres                 (const VipsImage *image);
double              vips_image_get_yres                 (const VipsImage *image);
int                 vips_image_get_xoffset              (const VipsImage *image);
int                 vips_image_get_yoffset              (const VipsImage *image);
const char *        vips_image_get_filename             (const VipsImage *image);
const char *        vips_image_get_mode                 (const VipsImage *image);
double              vips_image_get_scale                (const VipsImage *array);
double              vips_image_get_offset               (const VipsImage *array);
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,
                                                         double xres,
                                                         double yres);
void                vips_image_set                      (VipsImage *image,
                                                         const char *field,
                                                         GValue *value);
int                 vips_image_get                      (const VipsImage *image,
                                                         const char *field,
                                                         GValue *value_copy);
int                 vips_image_get_as_string            (const VipsImage *image,
                                                         const char *field,
                                                         char **out);
GType               vips_image_get_typeof               (const 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 *image,
                                                         VipsImageMapFn fn,
                                                         void *a);
void                vips_image_set_area                 (VipsImage *image,
                                                         const char *field,
                                                         VipsCallbackFn free_fn,
                                                         void *data);
int                 vips_image_get_area                 (const VipsImage *image,
                                                         const char *field,
                                                         void **data);
void                vips_image_set_blob                 (VipsImage *image,
                                                         const char *field,
                                                         VipsCallbackFn free_fn,
                                                         void *data,
                                                         size_t length);
int                 vips_image_get_blob                 (const VipsImage *image,
                                                         const char *field,
                                                         void **data,
                                                         size_t *length);
int                 vips_image_get_int                  (const VipsImage *image,
                                                         const char *field,
                                                         int *out);
void                vips_image_set_int                  (VipsImage *image,
                                                         const char *field,
                                                         int i);
int                 vips_image_get_double               (const VipsImage *image,
                                                         const char *field,
                                                         double *out);
void                vips_image_set_double               (VipsImage *image,
                                                         const char *field,
                                                         double d);
int                 vips_image_get_string               (const VipsImage *image,
                                                         const char *field,
                                                         const char **out);
void                vips_image_set_string               (VipsImage *image,
                                                         const char *field,
                                                         const char *str);
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_XMP_NAME

#define VIPS_META_XMP_NAME "xmp-data"

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


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

guint64             vips_format_sizeof                  (VipsBandFormat format);


vips_image_get_width ()

int                 vips_image_get_width                (const VipsImage *image);


vips_image_get_height ()

int                 vips_image_get_height               (const VipsImage *image);


vips_image_get_bands ()

int                 vips_image_get_bands                (const VipsImage *image);


vips_image_get_format ()

VipsBandFormat      vips_image_get_format               (const VipsImage *image);


vips_image_get_coding ()

VipsCoding          vips_image_get_coding               (const VipsImage *image);


vips_image_get_interpretation ()

VipsInterpretation  vips_image_get_interpretation       (const VipsImage *image);


vips_image_guess_interpretation ()

VipsInterpretation  vips_image_guess_interpretation     (const VipsImage *image);


vips_image_get_xres ()

double              vips_image_get_xres                 (const VipsImage *image);


vips_image_get_yres ()

double              vips_image_get_yres                 (const VipsImage *image);


vips_image_get_xoffset ()

int                 vips_image_get_xoffset              (const VipsImage *image);


vips_image_get_yoffset ()

int                 vips_image_get_yoffset              (const VipsImage *image);


vips_image_get_filename ()

const char *        vips_image_get_filename             (const VipsImage *image);


vips_image_get_mode ()

const char *        vips_image_get_mode                 (const VipsImage *image);


vips_image_get_scale ()

double              vips_image_get_scale                (const VipsImage *array);


vips_image_get_offset ()

double              vips_image_get_offset               (const VipsImage *array);


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,
                                                         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 im_black() or im_jpeg2vips(), you do need to set all the fields yourself.

See also: vips_image_pipelinev().

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 *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 );
vips_image_set( image, field, &value );
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

vips_image_get ()

int                 vips_image_get                      (const 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_as_string ()

int                 vips_image_get_as_string            (const 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_get_typeof ()

GType               vips_image_get_typeof               (const 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 *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().

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_image_set_area ()

void                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. [scope async]

data :

pointer to area of memory

vips_image_get_area ()

int                 vips_image_get_area                 (const 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_blob ()

void                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. [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 *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                  (const 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 ()

void                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

vips_image_get_double ()

int                 vips_image_get_double               (const 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 ()

void                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

vips_image_get_string ()

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

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_string ()

void                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

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

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

image :

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