The VImage class is a layer over the VIPS IMAGE type. It automates almost all of the image creation and destruction issues that complicate the C API, it automates error handling, and it provides a convenient system for composing operations.
There are two principal constructors for VImage:
The first form creates a new VImage, linking it to the named file. mode sets the mode for the file: it can take the following values:
The second form of constructor is shorthand for:
It is used for representing intermediate results of computations.
Two further constructors are handy for wrapping VImage around existing images.
The first constructor makes a VImage from an area of memory (perhaps from another image processing system), and the second makes a VImage from an IMAGE.
In both these two cases, the VIPS C++ API does not assume responsibility for the resources: it’s up to you to make sure the buffer is freed.
The Python interface adds the usual frombuffer and fromstring methods.
Use fromstring to avoid worries about object lifetime, but you’ll see a lot of copies and high memory use. Use frombuffer for speed, but you have to manage object lifetime yourself.
They are useful for moving images into VIPS from other image processing libraries. There’s also a utility function, vips_from_PIL_mode, which turns a PIL mode into a VIPS band, format, type triple.
See also tobuffer and tostring below.
VIPS can read and write a number of different file formats. Information about file format conversion is taken from the filename. For example:
This will decompress the file fred.jpg to a memory buffer, wrap a VIPS image around the buffer and build a reference to it called jim.
Options are passed to the file format converters embedded in the filename. For example:
Writing to the descriptor out will cause a TIFF image to be written to disc with deflate compression.
See the manual page for im_open(3) for details of all the file formats and conversions available. See the man page for VipsFormat(3) for a lower-level API which lets you control more of the detail of reading and writing data and is more suitable for large files.
A set of member functions of VImage provide access to the fields in the header:
Where TBandFmt, TCoding, TType and TCompression are enums for the types in the VIPS file header. See section §1.2.1 for an explanation of all of these fields.
Two functions give access to the filename and history fields maintained by the VIPS IO system.
You can get and set extra metadata fields with meta_get() and meta_set(). They read and write GValue objects, see §2.2.6.
A set of convenience functions build on these two to provide accessors for common types.
The image() member function provides access to the IMAGE descriptor underlying the C++ API. See the §2.1 for details.
The data() member function returns a pointer to an array of pixel data for the image.
This can be very slow and use huge amounts of RAM.
The Python interface adds tobuffer and tostring. These operations call data() to generate the image pixels and then either copy it and return the copy as a string, or wrap the pixels up as a Python buffer object.
Use tostring to avoid worries about object lifetime, but you’ll see a lot of copies and high memory use. Use tobuffer for speed, but you have to manage object lifetime yourself.
They are useful for moving images from VIPS into other image processing libraries. There’s also a utility function, PIL_mode_from_vips, which makes a PIL mode from a VIPS image.
See also frombuffer and fromstring above.
VImage defines copy and assignment, with reference-counted, pointer-style semantics. For example, if you write:
This will automatically close the file fred.v, and make the variable fred point to the image jim.v instead. Both jim and fred now point to the same underlying image object.
Internally, a VImage object is just a pointer to a reference-counting block, which in turn holds a pointer to the underlying VIPS IMAGE type. You can therefore efficiently pass VImage objects to functions by value, and return VImage objects as function results.
All VIPS image processing operations are member functions of the VImage class. For example:
Will apply im_costra() to fred.v, making an image where each pixel is the cosine of the corresponding pixel in fred.v; then add that image to jim.v. Finally, the result will be held in result.
VIPS is a demand-driven image processing system: when it computes expressions like this, no actual pixels are calculated (although you can use the projection functions on images — result.BandFmt() for example). When you finally write the result to a file (or use some operation that needs pixel values, such as min(), find minimum value), VIPS evaluates all of the operations you have called to that point in parallel. If you have more than one CPU in your machine, the load is spread over the available processors. This means that there is no limit to the size of the images you can process.
§4.2 lists all of the VIPS packages. These general rules apply:
For example, im_project(3) returns two images. You can call it from Python like this:
In other words, .project() writes the second result to the VImage you pass as an argument.
This part of the C++ API is generated automatically from the VIPS function database, so it should all be up-to-date.
There are a set of arithmetic operators defined for your convenience. You can generally write any arithmetic expression and include VImage in there.
Once you have computed some result, you can write it to a file with the member write(). It takes the following forms:
The first form simply writes the image to the named file. The second form writes the image to the specified VImage object, for example:
This creates a temporary memory buffer called jim, and fills it with the result of adding 42 to every pixel in fred.v.
The final form of write() writes the image to a memory buffer, and returns that.
Two type conversions are defined: you can cast VImage to a VDMask and to a VIMask.
These operations are slow and need a lot of memory! Emergencies only.