![]() |
![]() |
![]() |
VIPS Reference Manual | ![]() |
---|---|---|---|---|
Top | Description |
#include <vips/vips.h> #define IM_MAGIC_INTEL #define IM_MAGIC_SPARC enum VipsDemandStyle; enum VipsType; enum VipsBandFmt; enum VipsCoding; VipsProgress; VipsImage; #define IM_IMAGE_SIZEOF_ELEMENT (I) #define IM_IMAGE_SIZEOF_PEL (I) #define IM_IMAGE_SIZEOF_LINE (I) #define IM_IMAGE_N_ELEMENTS (I) #define IM_IMAGE_ADDR (I,X,Y) int im_init_world (const char *argv0); GOptionGroup * im_get_option_group (void); const char * im_version_string (void); int im_version (int flag); const char * im_guess_prefix (const char *, const char *); const char * im_guess_libdir (const char *, const char *); VipsImage * im_open (const char *filename, const char *mode); #define im_open_local ( IM, NAME, MODE ) #define im_open_local_array ( IM, OUT, N, NAME, MODE ) int im_close (VipsImage *im); void im_invalidate (VipsImage *im); void im_initdesc (VipsImage *image, int xsize, int ysize, int bands, int bandbits, VipsBandFmt bandfmt, VipsCoding coding, VipsType type, float xres, float yres, int xo, int yo); int im_cp_desc (VipsImage *out, VipsImage *in); int im_cp_descv (VipsImage *out, VipsImage *in1, ...); int im_cp_desc_array (VipsImage *out, VipsImage *in[]); VipsImage * im_binfile (const char *name, int xsize, int ysize, int bands, int offset); VipsImage * im_image (void *buffer, int width, int height, int bands, VipsBandFmt bandfmt);
#define IM_MAGIC_INTEL (0xb6a6f208U)
The first four bytes of a VIPS file in Intel byte ordering.
#define IM_MAGIC_SPARC (0x08f2a6b6U)
The first four bytes of a VIPS file in SPARC byte ordering.
typedef enum { IM_SMALLTILE, IM_FATSTRIP, IM_THINSTRIP, IM_ANY } VipsDemandStyle;
See im_demand_hint()
. Operations can hint to the VIPS image IO system about
the kind of demand geometry they prefer.
These demand styles are given below in order of increasing
restrictiveness. When demanding output from a pipeline, im_generate()
will use the most restrictive of the styles requested by the operations
in the pipeline.
IM_THINSTRIP --- This operation would like to output strips the width of the image and a few pels high. This is option suitable for point-to-point operations, such as those in the arithmetic package.
This option is only efficient for cases where each output pel depends upon the pel in the corresponding position in the input image.
IM_FATSTRIP --- This operation would like to output strips the width
of the image and as high as possible. This option is suitable for area
operations which do not violently transform coordinates, such as im_conv()
.
IM_SMALLTILE --- This is the most general demand format. Output is demanded in small (around 100x100 pel) sections. This style works reasonably efficiently, even for bizzare operations like 45 degree rotate.
IM_ANY --- This image is not being demand-read from a disc file (even
indirectly) so any demand style is OK. It's used for things like
im_black()
where the pixels are calculated.
See also: im_demand_hint()
.
typedef enum { IM_TYPE_MULTIBAND = 0, IM_TYPE_B_W = 1, IM_TYPE_HISTOGRAM = 10, IM_TYPE_FOURIER = 24, IM_TYPE_XYZ = 12, IM_TYPE_LAB = 13, IM_TYPE_CMYK = 15, IM_TYPE_LABQ = 16, IM_TYPE_RGB = 17, IM_TYPE_UCS = 18, IM_TYPE_LCH = 19, IM_TYPE_LABS = 21, IM_TYPE_sRGB = 22, IM_TYPE_YXY = 23, IM_TYPE_RGB16 = 25, IM_TYPE_GREY16 = 26 } VipsType;
These values are set by operations as hints to user-interfaces built on top of VIPS to help them show images to the user in a meaningful way. Operations do not use these values to decide their action.
generic many-band image | |
some kind of single-band image | |
a 1D image such as a histogram or lookup table | |
image is in fourier space | |
the first three bands are colours in CIE XYZ colourspace | |
pixels are in CIE Lab space | |
the first four bands are in CMYK space | |
implies IM_CODING_LABQ
|
|
generic RGB space | |
a uniform colourspace based on CMC | |
pixels are in CIE LCh space | |
pixels are CIE LAB coded as three signed 16-bit values | |
pixels are sRGB | |
pixels are CIE Yxy | |
generic 16-bit RGB | |
generic 16-bit mono |
typedef enum { IM_BANDFMT_NOTSET = -1, IM_BANDFMT_UCHAR = 0, IM_BANDFMT_CHAR = 1, IM_BANDFMT_USHORT = 2, IM_BANDFMT_SHORT = 3, IM_BANDFMT_UINT = 4, IM_BANDFMT_INT = 5, IM_BANDFMT_FLOAT = 6, IM_BANDFMT_COMPLEX = 7, IM_BANDFMT_DOUBLE = 8, IM_BANDFMT_DPCOMPLEX = 9 } VipsBandFmt;
The format used for each band element.
Each corresponnds to a native C type for the current machine. For example,
IM_BANDFMT_USHORT
is unsigned short.
unsigned char format | |
char format | |
unsigned short format | |
short format | |
unsigned int format | |
int format | |
float format | |
complex (two floats) format | |
double float format | |
double complex (two double) format |
typedef enum { IM_CODING_NONE = 0, IM_CODING_LABQ = 2, IM_CODING_RAD = 6 } VipsCoding;
How pixels are coded.
Normally, pixels are uncoded and can be manipulated as you would expect. However some file formats code pixels for compression, and sometimes it's useful to be able to manipulate images in the coded format.
typedef struct { int run; /* Time we have been running */ int eta; /* Estimated seconds of computation left */ gint64 tpels; /* Number of pels we expect to calculate */ gint64 npels; /* Number of pels calculated so far */ int percent; /* Percent complete */ GTimer *start; /* Start time */ } VipsProgress;
A structure available to eval callbacks giving information on evaluation
progress. See im_add_eval_callback()
.
typedef struct { /* Fields from file header. */ int Xsize; /* image width, in pixels */ int Ysize; /* image height, in pixels */ int Bands; /* number of image bands */ int BandFmt; /* #VipsBandFmt describing the pixel format */ int Coding; /* #VipsCoding describing the pixel coding */ int Type; /* #VipsType hinting at pixel interpretation */ float Xres; /* horizontal pixels per millimetre */ float Yres; /* vertical pixels per millimetre */ int Xoffset; /* image origin hint */ int Yoffset; /* image origin hint */ /* Derived fields that user can fiddle with. */ char *filename; /* pointer to copy of filename */ char *data; /* start of image data for WIO */ VipsProgress *time; /* evaluation progress */ int kill; /* set to non-zero to block partial eval */ } VipsImage;
An image. These can represent an image on disc, a memory buffer, an image in the process of being written to disc or a partially evaluated image in memory.
image width, in pixels | |
image height, in pixels | |
number of image bands | |
VipsFormat describing the pixel type | |
VipsCoding describing the pixel coding type | |
a VipsType hinting how the image pixels should be interpreted | |
horizontal pixels per millimetre | |
vertical pixels per millimetre | |
a hint giving the position of the origin in the image | |
a hint giving the position of the origin in the image | |
the disc file associated with this image, or NULL
|
|
the pixel data associated with this image, or NULL
|
|
VipsProgress * |
the evaluation progress associated with this image, or NULL
|
set this to non-zero to block evaluation of this image |
#define IM_IMAGE_SIZEOF_ELEMENT(I)
|
a VipsImage |
Returns : |
sizeof() a band element.
|
#define IM_IMAGE_SIZEOF_LINE(I)
|
a VipsImage |
Returns : |
sizeof() a scanline of pixels.
|
#define IM_IMAGE_N_ELEMENTS(I)
|
a VipsImage |
Returns : |
The number of band elements in a scanline. |
#define IM_IMAGE_ADDR(I,X,Y)
This macro returns a pointer to a pixel in an image. It only works for images which are fully available in memory, so memory buffers and small mapped images only.
If DEBUG is defined, you get a version that checks bounds for you.
|
a VipsImage |
|
x coordinate |
|
y coordinate |
Returns : |
The address of pixel (x,y) in the image. |
int im_init_world (const char *argv0);
im_init_world()
starts up the world of VIPS. You should call this on
program startup before using any other VIPS operations. If you do not call
im_init_world()
, VIPS will call it for you when you use your first VIPS
operation, but
it may not be able to get hold of argv0
and VIPS may therefore be unable
to find its data files. It is much better to call this function yourself.
im_init_world()
does approximately the following:
initialises any libraries that VIPS is using, including GObject and the threading system, if neccessary
guesses where the VIPS data files are and sets up
internationalisation --- see im_guess_prefix()
loads any plugins from $libdir/vips-x.y, where x and y are the major and minor version numbers for this VIPS.
Example:
int main( int argc, char **argv ) { if( im_init_world( argv[0] ) ) error_exit( "unable to start VIPS" ); return( 0 ); }
See also: im_get_option_group()
, im_version()
, im_guess_prefix()
,
im_guess_libdir()
.
|
name of application |
Returns : |
0 on success, -1 otherwise |
GOptionGroup * im_get_option_group (void);
im_get_option_group()
returns a GOptionGroup containing various VIPS
command-line options. It can be used with GOption to help
parse argc/argv.
See also: im_version()
, im_guess_prefix()
,
im_guess_libdir()
, im_init_world()
.
Returns : |
a GOptionGroup for VIPS, see GOption |
const char * im_version_string (void);
Get the VIPS version as a static string, including a build date and time. Do not free.
Returns : |
a static version string |
int im_version (int flag);
Get the major, minor or micro library version, with flag
values 0, 1 and
2.
|
which field of the version to get |
Returns : |
library version number |
const char * im_guess_prefix (const char *, const char *);
im_guess_prefix()
tries to guess the install directory. You should pass
in the value of argv[0] (the name your program was run as) as a clue to
help it out, plus the name of the environment variable you let the user
override your package install area with (eg. "VIPSHOME").
On success, im_guess_prefix()
returns the prefix it discovered, and as a
side effect, sets the environment variable (if it's not set).
Don't free the return string!
See also: im_guess_libdir()
.
|
program name (typically argv[0]) |
|
save prefix in this environment variable |
Returns : |
the install prefix as a static string, do not free. |
const char * im_guess_libdir (const char *, const char *);
im_guess_libdir()
tries to guess the install directory (usually the
configure libdir, or $prefix/lib). You should pass
in the value of argv[0] (the name your program was run as) as a clue to
help it out, plus the name of the environment variable you let the user
override your package install area with (eg. "VIPSHOME").
On success, im_guess_libdir()
returns the libdir it discovered, and as a
side effect, sets the prefix environment variable (if it's not set).
Don't free the return string!
See also: im_guess_prefix()
.
|
program name (typically argv[0]) |
|
save prefix in this environment variable |
Returns : |
the libdir as a static string, do not free. |
VipsImage * im_open (const char *filename, const char *mode);
im_open()
examines the mode string, and creates an appropriate IMAGE.
"r"
opens the named file for reading. If the file is not in the native
VIPS format for your machine, im_open()
automatically converts the
file for you in memory.
For some large files (eg. TIFF) this may not be what you want: you should call the appropriate converter yourself, and arrange for the conversion to take place on disc. See VipsFormat.
im_open()
can read files in most formats.
Note that "r" mode works in at least two stages. It should return quickly and let you check header fields. It will only actually read in pixels when you first access them.
"w" opens the named file for writing. It looks at the file name suffix to determine the type to write -- for example:
im_open( "fred.tif", "w" )
will write in TIFF format.
"t" creates a temporary memory buffer image.
"p" creates a "glue" descriptor you can use to join two image processing operations together.
"rw" opens the named file for reading and writing. This will only work for VIPS files in a format native to your machine. It is only for paintbox-type applications.
See also: im_close()
, VipsFormat
|
file to open |
|
mode to open with |
Returns : |
the image descriptor on success and NULL on error. |
#define im_open_local( IM, NAME, MODE )
Just like im_open()
, but the IMAGE will be closed for you automatically
when IM
is closed.
See also: im_open()
, im_close()
, im_local()
.
|
image to open local to |
|
filename to open |
|
mode to open with |
Returns : |
a new IMAGE, or NULL on error |
#define im_open_local_array( IM, OUT, N, NAME, MODE )
Just like im_open()
, but opens an array of images. Handy for creating a set
of temporary images for a function.
Example:
IMAGE *t[5]; if( im_open_local_array( out, t, 5, "some-temps", "p" ) || im_add( a, b, t[0] ) || im_invert( t[0], t[1] ) || im_add( t[1], t[0], t[2] ) || im_costra( t[2], out ) ) return( -1 );
See also: im_open()
, im_open_local()
, im_local_array()
.
|
image to open local to |
|
array to fill with IMAGE |
|
array size |
|
filename to open |
|
mode to open with |
Returns : |
0 on sucess, or -1 on error |
int im_close (VipsImage *im);
Frees all resources associated with im
.
If there are open REGION s on im
, close is delayed until the last region
is freed.
See also: im_open()
.
|
image to close |
Returns : |
0 on success and 1 on error. |
void im_invalidate (VipsImage *im);
Invalidate all pixel caches on an IMAGE and any derived images. The "invalidate" callback is triggered for all invalidated images.
See also: im_add_invalidate_callback()
.
|
IMAGE to invalidate |
void im_initdesc (VipsImage *image, int xsize, int ysize, int bands, int bandbits, VipsBandFmt bandfmt, VipsCoding coding, VipsType type, float xres, float yres, int xo, int yo);
A convenience function to set the header fields after creating an image.
Normally you copy the fields from one of your input images with
im_cp_desc()
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: im_cp_desc()
.
|
image to init |
|
image width |
|
image height |
|
image bands |
|
ignored, just here for compatibility |
|
band format |
|
image coding |
|
image type |
|
horizontal resolution, pixels per millimetre |
|
vertical resolution, pixels per millimetre |
|
x offset |
|
y offset |
int im_cp_desc (VipsImage *out, VipsImage *in);
Copy fields from in
to out
. A convenience
function over im_cp_desc_array()
.
See also: im_cp_desc_array()
, im_cp_descv()
.
|
image to copy to |
|
image to copy from |
Returns : |
0 on success, -1 on error. |
int im_cp_descv (VipsImage *out, VipsImage *in1, ...);
Copy fields from all the input images to the output image. A convenience
function over im_cp_desc_array()
.
See also: im_cp_desc_array()
, im_cp_desc()
.
|
image to copy to |
|
first image to copy from |
|
NULL -terminated list of images to copy from
|
Returns : |
0 on success, -1 on error. |
int im_cp_desc_array (VipsImage *out, VipsImage *in[]);
Copy fields from all the input images to the output image. There must be at
least one input image. If you are making an image which has no input images
(for example, im_black()
or im_vips2jpeg()
), use im_initdesc()
instead.
The first input image is used to set the main fields of out
(XSize
, Coding
and so on).
Metadata from all the image 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: im_cp_descv()
, im_cp_desc()
.
|
image to copy to |
|
NULL -terminated array of images to copy from
|
Returns : |
0 on success, -1 on error. |
VipsImage * im_binfile (const char *name, int xsize, int ysize, int bands, int offset);
This function maps the named file and returns an IMAGE you can use to read it.
It returns an 8-bit image with bands
bands. If the image is not 8-bit, use
im_copy_set()
to transform the descriptor after loading it.
See also: im_copy_set()
, im_raw2vips()
, im_open()
.
|
filename to open |
|
image width |
|
image height |
|
image bands (or bytes per pixel) |
|
bytes to skip at start of file |
Returns : |
the new IMAGE, or NULL on error. |
VipsImage * im_image (void *buffer, int width, int height, int bands, VipsBandFmt bandfmt);
This function wraps an IMAGE around a memory buffer. VIPS does not take
responsibility for the area of memory, it's up to you to make sure it's
freed when the image is closed. See for example im_add_close_callback()
.
See also: im_binfile()
, im_raw2vips()
, im_open()
.
|
start of memory area |
|
image width |
|
image height |
|
image bands (or bytes per pixel) |
|
image format |
Returns : |
the new IMAGE, or NULL on error.
|