Introduction

1.1 Introduction

This chapter describes the C++ API for the VIPS image processing library. The C++ API is as efficient as the C interface to VIPS, but is far easier to use: almost all creation, destruction and error handling issues are handled for you automatically.

The Python interface is a very simple wrapping of this C++ API generated automatically with SWIG. It adds a few utility methods noted below, but otherwise the two interfaces are identical other than language syntax.

1.1.1 If you’ve used the C API

To show how much easier the VIPS C++ API is to use, compare Figure 2.2.5 to Figure 1.1. Figure 1.2 is the same thing in Python.

A typical build line for the C++ program might be:

g++ invert.cc \
‘pkg-config vipsCC-7.18 \
--cflags --libs‘

The key points are:

You just include <vips/vips> — this then gets all of the other includes you need. Everything is in the vips namespace.
The C++ API replaces all of the VIPS C types — IMAGE becomes VImage and so on. The C++ API also includes VDisplay, VMask and VError.
Image processing operations are member functions of the VImage class — here, VImage( argv[1] ) creates a new VImage object using the first argument to initialise it (the input filename). It then calls the member function invert(), which inverts the VImage and returns a new VImage. Finally it calls the member function write(), which writes the result image to the named file.
The VIPS C++ API uses exceptions — the VError class is covered later. If you run this program with a bad input file, for example, you get the following output:
$ invert jim fred
invert: VIPS error: format_for_file:
file "jim" not found

#include <iostream>
#include <vips/vips>

int
main (int argc, char ⋆⋆argv)
{
  if (argc != 3)
    {
      std::cerr << "usage: " << argv[0] << " infile outfile\n";
      return (1);
    }

  try
  {
    vips::VImage fred (argv[1]);

    fred.invert ().write (argv[2]);
  }
  catch (vips::VError e)
  {
    e.perror (argv[0]);
  }

  return (0);
}

Figure 1.1: invert program in C++

#!/usr/bin/python

import sys
from vipsCC import ⋆

try:
  a = VImage.VImage (sys.argv[1])
  a.invert ().write (sys.argv[2])
except VError.VError, e:
  e.perror (sys.argv[0])

Figure 1.2: invert program in Python

[next] [front] [up]