[next] [prev] [prev-tail] [tail] [up]

### 1.3 The VImage class

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.

#### 1.3.1 Constructors

There are two principal constructors for VImage:

VImage::VImage( const char ⋆name, const char ⋆mode = "r" ); VImage::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:

"r"
  The named image file is opened read-only. This is the default mode.
"w"
  A VImage is created which, when written to, will write pixels to disc in the specified file.
"t"
  As the "w" mode, but pixels written to the VImage will be saved in a temporary memory buffer.
"p"
  This creates a special ‘partial’ image. Partial images represent intermediate results, and are used to join VIPS operations together, see §1.3.6.
"rw"
  As the "r" mode, but the image is mapped into your address space read-write. This mode is only provided for the use of paintbox-style applications, which need to directly modify an image. See §4.2.8.

The second form of constructor is shorthand for:

VImage( "VImage:1", "p" )

It is used for representing intermediate results of computations.

Two further constructors are handy for wrapping VImage around existing images.

VImage( void ⋆buffer, int width, int height, int bands, TBandFmt format ); VImage( void ⋆image );

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 resouces: it’s up to you to make sure the buffer is freed.

#### 1.3.2 File conversion

VIPS can read and write a number of different file formats. Information about file format conversion is taken from the filename. For example:

VImage jim( "fred.jpg" );

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:

VImage out( "jen.tif:deflate", "w" );

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.

#### 1.3.3 Large files

Opening large files in formats like JPEG which do not support random access can use large amounts of memory, since the file has to be decompressed before it can be used.

The convert2disc() member lets you decompress to a disc file rather than to memory. For example:

VImage fred = VImage::convert2disc( "im_jpeg2vips", "file.jpg", "temp.v" );

Will decompress to the file temp.v, then open that and return a reference to it. You will need to delete the file once you are finished with it.

#### 1.3.4 Projection functions

A set of member functions of VImage provide access to the fields in the header:

int Xsize(); int Ysize(); int Bands(); TBandFmt BandFmt(); TCoding Coding(); TType Type(); float Xres(); float Yres(); int Length(); TCompression Compression(); short Level(); int Xoffset(); int Yoffset();

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.

The image() member function provides access to the IMAGE descriptor underlying the C++ API. See the §2.1 for details.

void ⋆image();

The data() member function returns a pointer to an array of pixel data for the image.

void ⋆data() const;

This can be very slow and use huge amounts of RAM.

Finally, two projection functions give access to the filename and history fields maintained by the VIPS IO system.

char ⋆filename(); char ⋆Hist();

#### 1.3.5 Assignment

VImage defines copy and assignment, with reference-counted pointer-style semantics. For example, if you write:

VImage fred( "fred.v" ); VImage jim( "jim.v" ); fred = jim;

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.

#### 1.3.6 Computing with VImages

All VIPS image processing operations are member functions of the VImage class. For example:

VImage fred( "fred.v" ); VImage jim( "jim.v" ); VImage result = fred.cos() + jim;

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:

- VIPS operation names become C++ member function names by dropping the im_ prefix, and if present, the tra postfix, the const postfix and the _vec postfix. For example, the VIPS operation im_extract() becomes extract(), and im_costra() becomes cos().
- The VImage object to which you apply the member function is the first input image, the member function returns the first output. If there is no image input, the member is declared static.
- INTMASK and DOUBLEMASK types become VMask objects, im_col_display types become VDisplay objects.
- Several C API functions can map to the same C++ API member. For example, im_andimage, im_andimage_vec and im_andimageconst all map to the member andimage. The API relies on overloading to discriminate between these functions.

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.

VImage fred( "fred.v" ); VImage jim( "jim.v" ); Vimage v = int((fred + jim) / 2);

#### 1.3.7 Writing results

Once you have computed some result, you can write it to a file with the member write(). It takes the following forms:

VImage write( const char ⋆name ); VImage write( VImage out ); VImage write();

The first form simply writes the image to the named file. The second form writes the image to the specified VImage object, for example:

VImage fred( "fred.v" ); VImage jim( "jim buffer", "t" ); Vimage v = (fred + 42).write( jim );

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.

#### 1.3.8 Type conversions

Two type conversions are defined: you can cast VImage to a VDMask and to a VIMask.

operator VDMask(); operator VIMask();

These operations are slow and need a lot of memory! Emergencies only.

[next] [prev] [prev-tail] [front] [up]