![]() |
![]() |
![]() |
VIPS Reference Manual | ![]() |
---|---|---|---|---|
Top | Description |
#include <vips/vips.h> #define VIPS_META_EXIF_NAME #define VIPS_META_ICC_NAME #define VIPS_META_IPCT_NAME #define VIPS_META_LOADER #define VIPS_META_RESOLUTION_UNIT #define VIPS_META_XML #define VIPS_META_XMP_NAME void * (*VipsImageMapFn) (VipsImage *image
,const char *field
,GValue *value
,void *a
); guint64 vips_format_sizeof (VipsBandFormat format
); int vips_image_copy_fields (VipsImage *out
,VipsImage *in
); int vips_image_copy_fields_array (VipsImage *out
,VipsImage *in[]
); int vips_image_copy_fieldsv (VipsImage *out
,VipsImage *in1
,...
); int vips_image_get (VipsImage *image
,const char *field
,GValue *value_copy
); int vips_image_get_area (VipsImage *image
,const char *field
,void **data
); int vips_image_get_as_string (VipsImage *image
,const char *field
,char **out
); int vips_image_get_bands (const VipsImage *image
); int vips_image_get_blob (VipsImage *image
,const char *field
,void **data
,size_t *length
); VipsCoding vips_image_get_coding (const VipsImage *image
); void * vips_image_get_data (VipsImage *image
); int vips_image_get_double (VipsImage *image
,const char *field
,double *out
); const char * vips_image_get_filename (const VipsImage *image
); VipsBandFormat vips_image_get_format (const VipsImage *image
); int vips_image_get_height (const VipsImage *image
); const char * vips_image_get_history (VipsImage *image
); int vips_image_get_int (VipsImage *image
,const char *field
,int *out
); VipsInterpretation vips_image_get_interpretation (const VipsImage *image
); const char * vips_image_get_mode (const VipsImage *image
); int vips_image_get_string (VipsImage *image
,const char *field
,char **out
); GType vips_image_get_typeof (VipsImage *image
,const char *field
); int vips_image_get_width (const VipsImage *image
); int vips_image_get_xoffset (const VipsImage *image
); double vips_image_get_xres (const VipsImage *image
); int vips_image_get_yoffset (const VipsImage *image
); double vips_image_get_yres (const VipsImage *image
); VipsInterpretation vips_image_guess_interpretation (const VipsImage *image
); int vips_image_history_args (VipsImage *image
,const char *name
,int argc
,char *argv[]
); int vips_image_history_printf (VipsImage *image
,const char *format
,...
); 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_map (VipsImage *image
,VipsImageMapFn fn
,void *a
); gboolean vips_image_remove (VipsImage *image
,const char *field
); void vips_image_set (VipsImage *image
,const char *field
,GValue *value
); void vips_image_set_area (VipsImage *image
,const char *field
,VipsCallbackFn free_fn
,void *data
); void vips_image_set_blob (VipsImage *image
,const char *field
,VipsCallbackFn free_fn
,void *data
,size_t length
); void vips_image_set_double (VipsImage *image
,const char *field
,double d
); void vips_image_set_int (VipsImage *image
,const char *field
,int i
); void vips_image_set_string (VipsImage *image
,const char *field
,const char *str
);
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.
#define VIPS_META_EXIF_NAME "exif-data"
The name that JPEG read and write operations use for the image's EXIF data.
#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.
#define VIPS_META_IPCT_NAME "ipct-data"
The name that JPEG read and write operations use for the image's IPCT data.
#define VIPS_META_LOADER "vips-loader"
Record the name of the original loader here. Handy for hinting file formats and for debugging.
#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.
#define VIPS_META_XML "xml-header"
The original XML that was used to code the metadata after reading a VIPS format file.
#define VIPS_META_XMP_NAME "xmp-data"
The name that JPEG read and write operations use for the image's XMP data.
void * (*VipsImageMapFn) (VipsImage *image
,const char *field
,GValue *value
,void *a
);
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()
.
|
image to copy to |
|
image to copy from |
Returns : |
0 on success, -1 on error. |
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()
.
|
image to copy to |
|
NULL -terminated array of images to copy from |
Returns : |
0 on success, -1 on error. |
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()
.
|
image to copy to |
|
first image to copy from |
Returns : |
0 on success, -1 on error. |
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 to get the field from from |
|
the name to give the metadata |
|
the GValue is copied into this |
Returns : |
0 on success, -1 otherwise. |
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 to get the metadata from |
|
metadata name |
|
return metadata value |
Returns : |
0 on success, -1 otherwise. |
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 to get the header field from |
|
field name |
|
return field value as string |
Returns : |
0 on success, -1 otherwise. |
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 to get the metadata from |
|
metadata name |
|
pointer to area of memory |
|
return the blob length here, optionally |
Returns : |
0 on success, -1 otherwise. |
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 to get data for |
Returns : |
a pointer to pixel data, if possible. |
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 to get the header field from |
|
field name |
|
return field value |
Returns : |
0 on success, -1 otherwise. |
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()
.
|
get history from here |
Returns : |
The history of image as a C string. Do not free! |
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 to get the header field from |
|
field name |
|
return field value |
Returns : |
0 on success, -1 otherwise. |
VipsInterpretation vips_image_get_interpretation (const VipsImage *image
);
int vips_image_get_string (VipsImage *image
,const char *field
,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 to get the header field from |
|
field name |
|
return field value |
Returns : |
0 on success, -1 otherwise. |
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 to test |
|
the name to search for |
Returns : |
the GType of the field, or zero if there is no field of that name. |
VipsInterpretation vips_image_guess_interpretation (const VipsImage *image
);
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 to attach history line to |
|
program name |
|
number of program arguments |
|
program arguments |
Returns : |
0 on success, -1 on error. |
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.
|
add history line to this image |
|
printf() format string |
Returns : |
0 on success, -1 on error. |
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 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 to init |
|
image width |
|
image height |
|
image bands |
|
band format |
|
image coding |
|
image type |
|
horizontal resolution, pixels per millimetre |
|
vertical resolution, pixels per millimetre |
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 to map over |
|
function to call for each header field |
|
user data for function |
Returns : |
NULL on success, the failing pointer otherwise. |
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 to test |
|
the name to search for |
Returns : |
TRUE if an item of metadata of that name was found and removed |
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 to set the metadata on |
|
the name to give the metadata |
|
the GValue to copy into the image |
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 to attach the metadata to |
|
metadata name |
|
free function for data . [scope async]
|
|
pointer to area of memory |
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 to attach the metadata to |
|
metadata name |
|
free function for data . [scope async]
|
|
pointer to area of memory |
|
length of memory area |
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 to attach the metadata to |
|
metadata name |
|
metadata value |
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 to attach the metadata to |
|
metadata name |
|
metadata value |
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 to attach the metadata to |
|
metadata name |
|
metadata value |