libvips/doc/reference/using-python.xml

<?xml version="1.0"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
               "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
]>
<!-- vim: set ts=2 sw=2 expandtab: --> 
<refentry id="using-from-python">
  <refmeta>
    <refentrytitle>VIPS from Python</refentrytitle>
    <manvolnum>3</manvolnum>
    <refmiscinfo>VIPS Library</refmiscinfo>
  </refmeta>

  <refnamediv>
    <refname>Using VIPS</refname>
    <refpurpose>How to use the VIPS library from Python</refpurpose>
  </refnamediv>

  <refsect1 id="using-python">
    <title>Using VIPS from Python</title>
    <para>
      VIPS comes with a convenient, high-level Python API based 
      on <code>gobject-introspection</code>. As long as you can get GOI 
      for your platform, you should be able to use vips. The 
      <code>Vips.py</code> file 
      needs to be copied to the overrides directory of your GOI install,
      and you need to have the vips typelib on your 
      <code>GI_TYPELIB_PATH</code>. 
    </para>

<example>
<title>VIPS from Python example</title>
<programlisting language="Python">
#!/usr/bin/python

import sys

from gi.repository import Vips

im = Vips.Image.new_from_file(sys.argv[1])

im = im.extract_area(100, 100, im.width - 200, im.height - 200)
im = im.similarity(scale = 0.9)
mask = Vips.Image.new_from_array([[-1, -1,  -1], 
                                  [-1,  16, -1], 
                                  [-1, -1,  -1]], scale = 8)
im = im.conv(mask)

im.write_to_file(sys.argv[2])
</programlisting>
</example>

    <para>
      Reading the example, the first line loads the input file. You can append
      load options to the argument list as keyword arguments, for example:

<programlisting language="Python">
im = Vips.Image.new_from_file(sys.argv[1], access = Vips.Access.SEQUENTIAL)
</programlisting>

      See the various loaders for a list of the available options for each 
      file format. The C 
      equivalent to this function, vips_image_new_from_file(), has more 
      extensive documentation. 
	  </para>

    <para>
	    There are 
      several other constructors: you can load a formatted image (for example, 
      a JPEG format image) from a string with <code>.new_from_buffer()</code>. 
    </para>

    <para>
      The next line crops 100 pixels off every edge. See the docs for the C 
      function vips_extract_area() for details of the parameters. You can use 
      <code>.crop()</code> as a synonym, if you like. 
      <code>im.width</code> gets the image width in pixels, see 
      vips_image_get_width() and friends for a list of the other getters. 
    </para>

    <para>
      The <code>similarity</code> line shrinks by 10%, see the docs for the C 
      function vips_similarity() for details. By default it uses bilinear 
      interpolation, use <code>interpolate</code> to pick another 
      interpolator, for example:

<programlisting language="Python">
im = im.similarity(scale = 0.9, interpolate = Vips.Interpolate.new("bicubic"))
</programlisting>

    </para>

    <para>
      <code>.new_from_array()</code> makes an image from a 2D array. The 
      <code>scale</code> keyword argument lets you set a divisor for 
      convolution, handy for integer convolutions. You can set 
      <code>offset</code> as well. See vips_conv() for details on the vips 
      convolution operator. 
    </para>

    <para>
      Finally, <code>.write_to_file()</code> sends the image back to the 
      filesystem. There's also <code>.write_to_buffer()</code> to make a 
      string containing the formatted image. 
    </para>
  </refsect1>

  <refsect1 id="python-basics">
    <title><code>pyvips8</code> Basics</title>
    <para>
      The Python interface comes in two main parts. First, the C source code 
      to libvips has been marked up with special comments describing the 
      internals in a standard way. These comments are read by 
      gobject-introspection when libvips is compiled and used to generate a 
      typelib, a description of the library's internals. When your Python 
      program starts, the import line:

<programlisting language="Python">
from gi.repository import Vips
</programlisting>

      loads the typelib and creates Python classes for all the objects and 
      all the functions in the library. You can then call these functions 
      from your code, and they will call into libvips for you. C functions 
      become Python functions in an obvious way: vips_operation_new(), 
      for example, the constructor for the class #VipsOperation, becomes 
      <code>Vips.Operation.new()</code>.
    </para>

    <para>
      Using libvips like this is possible, but a bit painful. To make the API 
      seem more pythonesque, vips includes a set of overrides which wrap up 
      the bare functions created by gobject-introspection in a nicer package. 
      These overrides do the following things:

      <itemizedlist>
        <listitem>
          <para><emphasis>
            Automatic wrapping of vips operations
          </emphasis> </para>

          <para>
            It intercepts member lookup 
            on the <code>Vips.Image</code> class and looks for vips operations
            with that name. So the vips operation "add", which appears in the 
            C API as vips_add(), appears in Python as 
            <code>Vips.Image.add</code>.
          </para>
        </listitem>

        <listitem>
          <para>
            Automatic wrapping of operation arguments. The first input image 
            argument becomes the <code>self</code> argument. If there are no 
            input image arguments, the operation appears as a class member. 
            Optional input 
            arguments become keyword arguments. The result is a list of all 
            the output arguments, or a single output if there is only one. 
          </para>
            
          <para>
            Optional output arguments are enabled with a boolean keyword 
            argument of that name. For example, "min" (the operation which 
            appears in the C API as vips_min()), can be called like this:

<programlisting language="Python">
min_value = im.min()
</programlisting>

            and <code>min_value</code> will be a floating point value giving 
            the minimum value in the image. "min" can also find the position 
            of the minimum value with the <code>x</code> and <code>y</code>
            optional output arguments. Call it like this:

<programlisting language="Python">
min_value, x_pos, y_pos = im.min(x = True, y = True)
</programlisting>
          </para>
        </listitem>

        <listitem>
          <para><emphasis>Automatic type conversion</emphasis></para>
          <para>
            The override looks at the type of 
            argument required by the operation and converts the value you 
            supply, when it can. For example, "linear" takes a 
            #VipsArrayDouble as an argument for the constant to use for 
            multiplication. You can supply this value as an integer, a float, 
            or some kind of compound object and it will be converted for you.
          </para>

          <para>
            It does a couple of more ambitious conversions. It will 
            automatically convert to and from the various vips types, 
            like #VipsBlob and #VipsArrayImage. For example, you can read the
            ICC profile out of an image like this:

<programlisting language="Python">
profile = im.get_value("icc-profile-data")
</programlisting>

            and <code>profile</code> will be a string. 
          </para>

          <para>
            If an operation 
            takes several input images, you can use a constant for all but 
            one of them and the wrapper will make a constant image for you. 
            For example, <code>.ifthenelse()</code> uses a condition image to 
            pick pixels between a then and an else image: 

<programlisting language="Python">
result_image = condition_image.ifthenelse(then_image, else_image)
</programlisting>

            You can use a constant instead of either the then or the else 
            parts, and it will be expanded to an image for you. If you use a 
            constant for both then and else, it will be expanded to match the 
            condition image. For example:

<programlisting language="Python">
result_image = condition_image.ifthenelse([0, 255, 0], [255, 0, 0])
</programlisting>

            Will make an image where true pixels are green and false pixels 
            are red.
          </para>

          <para>
            This is useful for <code>.bandjoin()</code>, the thing to join 
            two, or a set of images up bandwise. You can write:

<programlisting language="Python">
rgba = rgb.bandjoin(255)
</programlisting>
      
            to add a constant 255 band to an image, perhaps to add an alpha 
            channel. Of course you can also write:

<programlisting language="Python">
result_image = image1.bandjoin(image2)
result_image = image1.bandjoin([image2, image3])
result_image = Vips.Image.bandjoin([image1, image2, image3])
result_image = image1.bandjoin([image2, 255])
</programlisting>
      
            and so on. 
          </para>
        </listitem>

        <listitem>
          <para><emphasis>Exceptions</emphasis></para>
          
          <para>
            The wrapper spots errors from vips operations and raises the 
            <code>Vips.Error</code> exception. You can catch it in the 
            usual way. 
          </para>
        </listitem>

        <listitem>
          <para><emphasis>Overloads</emphasis></para>

          <para>
            The wrapper defines the usual set of arithmetic, boolean and 
            relation overloads on 
            <code>image</code>. You can mix images, constants and lists of 
            constants (almost) freely. 
          </para>
        </listitem>

        <listitem>
          <para><emphasis>Expansions</emphasis></para>

          <para>
            Some vips operators take an enum to select an action, for example
            <code>.math()</code> can be used to calculate sine of every pixel 
            like this:

<programlisting language="Python">
result_image = image.math(Vips.OperationMath.SIN)
</programlisting>

            This is annoying, so the wrapper expands all these enums into 
            separate members named after the enum. So you can write:

<programlisting language="Python">
result_image = image.sin()
</programlisting>
          </para>
        </listitem>

        <listitem>
          <para><emphasis>Utility functions</emphasis></para>

          <para>
            The wrapper defines a few extra useful utility functions: 
            <code>.get_value()</code>, <code>.set_value()</code>
            <code>.bandsplit()</code>, <code>.maxpos()</code>
            <code>.minpos()</code>.
          </para>
        </listitem>

      </itemizedlist>
    </para>
      
  </refsect1>

</refentry>