From 677e6bf32c21bbd48d6b7cd836f57c637b97b7de Mon Sep 17 00:00:00 2001 From: John Cupitt Date: Thu, 6 Nov 2014 14:57:44 +0000 Subject: [PATCH] pyvips8 docs hacking --- doc/reference/using-python.xml | 135 +++++++++++++++++++++++++++++++-- 1 file changed, 130 insertions(+), 5 deletions(-) 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. + + +