335 lines
12 KiB
XML
335 lines
12 KiB
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>. This may already have happened, depending
|
|
on your platform.
|
|
</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
|
|
interface in a standard way. These comments are read by
|
|
gobject-introspection when libvips is compiled and used to generate a
|
|
typelib, a description of how to call the library. 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><emphasis>Add docstrings</emphasis> </para>
|
|
|
|
<para>
|
|
Try <code>help(Vips.Image)</code>, or something like:
|
|
|
|
<programlisting language="Python">
|
|
image = Vips.Image.new_from_file("x.jpg")
|
|
help(image.add)
|
|
</programlisting>
|
|
|
|
For any operator it'll list the required and optional input and
|
|
output arguments, using all the rules listed below. This plus the
|
|
C API docs should be enough to answer most questions. IDEs should
|
|
display the help text automatically as you work.
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><emphasis>Automatic wrapping of operation arguments</emphasis> </para>
|
|
|
|
<para>
|
|
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>
|
|
|
|
Although in this case, the <code>.minpos()</code> convenience
|
|
function would be simpler.
|
|
</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. The <code>.detail</code> member gives the detailed
|
|
error message.
|
|
</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>
|
|
|
|
See <code>help(Vips.Image)</code> for a list.
|
|
</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>.
|
|
Again, see <code>help(Vips.Image)</code> for a list.
|
|
</para>
|
|
</listitem>
|
|
|
|
</itemizedlist>
|
|
</para>
|
|
|
|
</refsect1>
|
|
|
|
</refentry>
|