diff --git a/doc/reference/using-python.xml b/doc/reference/using-python.xml
index 8146b77f..c19c3bfa 100644
--- a/doc/reference/using-python.xml
+++ b/doc/reference/using-python.xml
@@ -38,8 +38,8 @@ from gi.repository import Vips
im = Vips.Image.new_from_file(sys.argv[1])
-im = im.crop(100, 100, im.width - 200, im.height - 200)
-im = im.affine([0.9, 0, 0, 0.9])
+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)
@@ -50,21 +50,146 @@ im.write_to_file(sys.argv[2])
- Reading the example, the first line loads the input file. You can put load options after the
+ Reading the example, the first line loads the input file. You can append
+ load options to the argument list as keyword arguments, for example:
+
+
+im = Vips.Image.new_from_file(sys.argv[1], access = Vips.Access.SEQUENTIAL)
+
+
+ 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.
There are
several other constructors: you can load a formatted image (for example,
- a JPEG format image) from a string with new_from_buffer()
+ a JPEG format image) from a string with .new_from_buffer().
+
+ 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
+ .crop() as a synonym, if you like.
+ im.width gets the image width in pixels, see
+ vips_image_get_width() and friends for a list of the other getters.
+
+
+
+ The similarity line shrinks by 10%, see the docs for the C
+ function vips_similarity() for details. By default it uses bilinear
+ interpolation, use interpolate to pick another
+ interpolator, for example:
+
+
+im = im.similarity(scale = 0.9, interpolate = Vips.Interpolate.new("bicubic"))
+
+
+
+
+
+ .new_from_array() makes an image from a 2D array. The
+ scale keyword argument lets you set a divisor for
+ convolution, handy for integer convolutions. You can set
+ offset as well. See vips_conv() for details on the vips
+ convolution operator.
+
+
+
+ Finally, .write_to_file() sends the image back to the
+ filesystem. There's also .write_to_buffer() to make a
+ string containing the formatted image.
+
<code>pyvips8</code> Basics
- Stuff.
+ 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:
+
+
+from gi.repository import Vips
+
+
+ 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
+ Vips.Operation.new().
+
+
+
+ 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:
+
+
+
+
+ Automatic wrapping of vips operations. It intercepts member lookup
+ on the Vips.Image 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
+ Vips.Image.add.
+
+
+
+
+
+ Automatic wrapping of operation arguments. The first input image
+ argument becomes the self 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.
+
+
+
+ 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:
+
+
+min_value = im.min()
+
+
+ and min_value 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 x and y
+ optional output arguments. Call it like this:
+
+
+min_value, x_pos, y_pos = im.min(x = True, y = True)
+
+
+
+
+
+
+ Automatic type conversion. 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.
+
+
+
+ It does a couple of more ambitious conversions. 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.
+
+
+