![]() |
![]() |
![]() |
VIPS Reference Manual | ![]() |
---|---|---|---|---|
Top | Description |
#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 *data_length); int im_blob_set (GValue *value, im_callback_fn free_fn, void *data, size_t length); int im_meta_set (IMAGE *, const char *field, GValue *); int im_meta_get (IMAGE *, const char *field, GValue *); GType im_meta_get_typeof (IMAGE *im, const char *field); int im_meta_set_int (IMAGE *, const char *field, int i); int im_meta_get_int (IMAGE *, const char *field, int *i); int im_meta_set_double (IMAGE *, const char *field, double d); int im_meta_get_double (IMAGE *, const char *field, double *d); int im_meta_set_area (IMAGE *, const char *field, im_callback_fn , void *); int im_meta_get_area (IMAGE *, const char *field, void **data); int im_meta_set_string (IMAGE *, const char *field, const char *str); int im_meta_get_string (IMAGE *, const char *field, char **str); int im_meta_set_blob (IMAGE *im, const char *field, im_callback_fn free_fn, void *blob, size_t blob_length); int im_meta_get_blob (IMAGE *im, const char *field, void **blob, size_t *blob_length);
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.
#define IM_META_EXIF_NAME "exif-data"
The name that JPEG read and write operations use for the image's EXIF data.
#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.
#define IM_META_XML "xml-header"
The original XML that was used to code the metadata after reading a VIPS format file.
#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.
#define IM_TYPE_SAVE_STRING (im_save_string_get_type())
The GType for an "im_save_string".
const char * im_save_string_get (const GValue *value);
Get the C string held internally by the GValue.
|
GValue to get from |
Returns : |
The C string held by value . This must not be freed.
|
void im_save_string_set (GValue *value, const char *str);
Copies the C string into value
.
|
GValue to set |
|
C string to copy into the GValue |
void im_save_string_setf (GValue *value, const char *fmt, ...);
Generates a string and copies it into value
.
|
GValue to set |
|
printf() -style format string
|
|
arguments to printf() -formatted fmt
|
#define IM_TYPE_REF_STRING (im_ref_string_get_type())
The GType for an im_refstring.
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.
|
GValue to set |
|
C string to copy into the GValue |
Returns : |
0 on success, -1 otherwise. |
const char * im_ref_string_get (const GValue *value);
Get the C string held internally by the GValue.
|
GValue to get from |
Returns : |
The C string held by value . This must not be freed.
|
size_t im_ref_string_get_length (const GValue *value);
Gets the cached string length held internally by the refstring.
|
GValue to get from |
Returns : |
The length of the string. |
void * im_blob_get (const GValue *value, size_t *data_length);
Get the address of the blob (binary large object) being held in value
and
optionally return its length in blob_length
.
See also: im_blob_set()
|
GValue to get from |
|
return the blob length here, optionally |
Returns : |
The blob address. |
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()
|
GValue to set |
|
free function for data
|
|
pointer to area of memory |
|
length of memory area |
Returns : |
0 on success, -1 otherwise. |
int im_meta_set (IMAGE *, const char *field, GValue *);
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()
.
|
image to set the metadata on |
|
the name to give the metadata |
|
the GValue to copy into the image |
Returns : |
0 on success, -1 otherwise. |
int im_meta_get (IMAGE *, const char *field, GValue *);
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()
.
|
image to get the metadata from |
|
the name to give the metadata |
|
the GValue is copied into this |
Returns : |
0 on success, -1 otherwise. |
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()
.
|
image to test |
|
the name to search for |
Returns : |
the GType of the metadata, or zero if there is no metadata of that name. |
int im_meta_set_int (IMAGE *, 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()
|
image to attach the metadata to |
|
metadata name |
|
metadata value |
Returns : |
0 on success, -1 otherwise. |
int im_meta_get_int (IMAGE *, 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()
|
image to get the metadata from |
|
metadata name |
|
return metadata value |
Returns : |
0 on success, -1 otherwise. |
int im_meta_set_double (IMAGE *, 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()
|
image to attach the metadata to |
|
metadata name |
|
metadata value |
Returns : |
0 on success, -1 otherwise. |
int im_meta_get_double (IMAGE *, 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()
|
image to get the metadata from |
|
metadata name |
|
return metadata value |
Returns : |
0 on success, -1 otherwise. |
int im_meta_set_area (IMAGE *, const char *field, im_callback_fn , void *);
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()
|
image to attach the metadata to |
|
metadata name |
|
free function for data
|
|
pointer to area of memory |
Returns : |
0 on success, -1 otherwise. |
int im_meta_get_area (IMAGE *, 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()
|
image to get the metadata from |
|
metadata name |
|
return metadata value |
Returns : |
0 on success, -1 otherwise. |
int im_meta_set_string (IMAGE *, 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
|
image to attach the metadata to |
|
metadata name |
|
metadata value |
Returns : |
0 on success, -1 otherwise. |
int im_meta_get_string (IMAGE *, 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
|
image to get the metadata from |
|
metadata name |
|
return metadata value |
Returns : |
0 on success, -1 otherwise. |
int im_meta_set_blob (IMAGE *im, const char *field, im_callback_fn free_fn, void *blob, size_t blob_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
|
image to attach the metadata to |
|
metadata name |
|
free function for data
|
|
pointer to area of memory |
|
length of memory area |
Returns : |
0 on success, -1 otherwise. |
int im_meta_get_blob (IMAGE *im, const char *field, void **blob, size_t *blob_length);
Gets blob
from im
under the name field
, optionally return its length in
blob_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_blob
|
image to get the metadata from |
|
metadata name |
|
pointer to area of memory |
|
return the blob length here, optionally |
Returns : |
0 on success, -1 otherwise. |