How to write an operation in vips8

It's been years (this post was three years ago, ouch), but vips8 is finally almost here. I thought I'd write a post about using the new GObject API to write your own operations. The source code for this example together with a sample main() is here. It needs 7.38 or later.

All vips8 operations are subclasses of VipsOperation, which in turn subclasses VipsObject and then GObject. You need to define a new instance struct and a new class struct.

typedef struct _Negative {
  VipsOperation parent_instance;

  VipsImage *in;
  VipsImage *out;

  int image_max;

} Negative;

typedef struct _NegativeClass {
  VipsOperationClass parent_class;

  /* No new class members needed for this op.
   */

} NegativeClass;

This operation will find the photographic negative of an unsigned 8-bit image, optionally letting you specify the value which the pixels "pivot" about. It doesn't need any class members (ie. values common to all operations of this type), so the second struct is empty. See vips_invert() for a more complete version of this operation that's actually in the library.

GObject has a handy macro to write some of the boilerplate for you.

G_DEFINE_TYPE( Negative, negative, VIPS_TYPE_OPERATION );

This defines a function called negative_get_type(), which registers this new class and returns its GType (a pointer-sized integer). negative_get_type() in turn needs two functions, negative_init(), to initialise a new instance, and negative_class_init(), to initialise a new class.

negative_init() is very simple, it just sets the default value for our optional class parameter.

static void
negative_init( Negative *negative )
{
  negative->image_max = 255;
}

negative_class_init() is more complicated: it has to set various fields in various superclasses.

static void
negative_class_init( NegativeClass *class )
{
  GObjectClass *gobject_class = G_OBJECT_CLASS( class );
  VipsObjectClass *object_class = VIPS_OBJECT_CLASS( class );

  gobject_class->set_property = vips_object_set_property;
  gobject_class->get_property = vips_object_get_property;

  object_class->nickname = "negative";
  object_class->description = "photographic negative";
  object_class->build = negative_build;

  VIPS_ARG_IMAGE( class, "in", 1, 
    "Input", 
    "Input image",
    VIPS_ARGUMENT_REQUIRED_INPUT,
    G_STRUCT_OFFSET( Negative, in ) );

  VIPS_ARG_IMAGE( class, "out", 2, 
    "Output", 
    "Output image",
    VIPS_ARGUMENT_REQUIRED_OUTPUT, 
    G_STRUCT_OFFSET( Negative, out ) );

  VIPS_ARG_INT( class, "image_max", 4, 
    "Image maximum", 
    "Maximum value in image: pivot about this",
    VIPS_ARGUMENT_OPTIONAL_INPUT,
    G_STRUCT_OFFSET( Negative, image_max ),
    0, 255, 255 );
}

In GObject, it needs to set the getters and setters for this class. vips has a generic get/set system, so any subclass of VipsObject needs to use the vips ones.

In VipsObject, it needs to set the operation name and description, and set a build function (see below). The name is used to refer to this operation in the API, the description is used to explain this operation to users and will be translated to their language.

Finally, it needs to set the arguments this class constructor takes. There are a set of handy macros for doing this. The first few parameters are always the same and mean: class pointer for argument, argument name, argument priority (bindings expect required arguments in order of priority), long argument name (this one is internationalised and displayed to users), description (again, users can see this), some flags describing the argument, and finally the position of the member in the struct.

Integer arguments take three more values: the minimum, maximum and default value for the argument.

The build function is the thing VipsObject calls after supplying arguments. It checks that all required arguments have been set and are valid and constructs the object. After build, the object is expected to be ready for use.

static int
negative_build( VipsObject *object )
{
  VipsObjectClass *class = VIPS_OBJECT_GET_CLASS( object );
  Negative *negative = (Negative *) object;

  if( VIPS_OBJECT_CLASS( negative_parent_class )->build( object ) )
    return( -1 );

  if( vips_check_uncoded( class->nickname, negative->in ) ||
    vips_check_format( class->nickname, negative->in, VIPS_FORMAT_UCHAR ) )
    return( -1 );

  g_object_set( object, "out", vips_image_new(), NULL ); 

  if( vips_image_pipelinev( negative->out, 
    VIPS_DEMAND_STYLE_THINSTRIP, negative->in, NULL ) )
    return( -1 );

  if( vips_image_generate( negative->out, 
    vips_start_one, 
    negative_generate, 
    vips_stop_one, 
    negative->in, negative ) )
    return( -1 );

  return( 0 );
}

negative_build() first chains up to the superclass: this will check that all input arguments have been supplied and are sane.

Next, it adds its own checks. This is a demo operation, so we just work for uncoded, unsigned 8-bit images.

Next, it creates the output image. This needs to be set with g_object_set() so that vips can see that it has been assigned. vips will also handle the reference counting for you.

vips_image_pipelinev() links our new image onto the input image and notes that this operation prefers to work in lines.

Finally, vips_image_generate() attaches a set of callbacks to the output image to generate chunks of it on request. vips_start_one() and vips_stop_one() are convenience functions that make the input region for you.

And then the actual image processing.

static int
negative_generate( VipsRegion *or, 
  void *vseq, void *a, void *b, gboolean *stop )
{
  /* The area of the output region we have been asked to make.
   */
  VipsRect *r = &or->valid;

  /* The sequence value ... the thing returned by vips_start_one().
   */
  VipsRegion *ir = (VipsRegion *) vseq;

  Negative *negative = (Negative *) b;
  int line_size = r->width * negative->in->Bands; 

  int x, y;

  /* Request matching part of input region.
   */
  if( vips_region_prepare( ir, r ) )
    return( -1 );

  for( y = 0; y < r->height; y++ ) {
    unsigned char *p = (unsigned char *)
      VIPS_REGION_ADDR( ir, r->left, r->top + y ); 
    unsigned char *q = (unsigned char *)
      VIPS_REGION_ADDR( or, r->left, r->top + y ); 

    for( x = 0; x < line_size; x++ ) 
      q[x] = negative->image_max - p[x];
  }

  return( 0 );
}

This has to calculate a section of the output image. The output VipsRegion, or, contains a VipsRect called valid which is the area needing calculation. negative_generate() asks for the corresponding pixels from the input region, then loops over the area. VIPS_REGION_ADDR() is a simple macro that does pointer arithmetic for you: you need to stay within the valid area.

And that's it. You can now call negative from any of the vips interfaces. For example, in Python you'd use it like this:

out = in.negative(image_max = 128)

From the command-line it'd look like this:

$ vips negative in.png out.tif --image-max 128

And from C like this:

VipsImage *in;
VipsImage *out;
if( vips_call( "negative", in, &out, "image_max", 128, NULL ) )
  ... error

Unfortunately that will do almost no compile-time type checking, so all vips operations have a tiny extra wrapper to add a bit of safety. For example:

static int 
negative( VipsImage *in, VipsImage **out, ... )
{
  va_list ap;
  int result;

  va_start( ap, out );
  result = vips_call_split( "negative", ap, in, out );
  va_end( ap );

  return( result );
}

And now you can write:

if( negative( in, &out, "image_max" 128, NULL ) )
  ... error

and it's at least a bit safer.