diff --git a/TODO b/TODO
index 310984d5..9f749adf 100644
--- a/TODO
+++ b/TODO
@@ -1,5 +1,3 @@
-- update python section in manual
-
- try:
$ cd vips-x.x.x/libvips
@@ -13,6 +11,24 @@
- python fitsload has both "access" and "sequential" as kwargs, is this right?
why do we need both?
+ try:
+
+ $ vips fitsload
+ load a FITS image
+ usage:
+ fitsload filename out
+ where:
+ filename - Filename to load from, input gchararray
+ out - Output image, output VipsImage
+ optional arguments:
+ flags - Flags for this file, output VipsForeignFlags
+ disc - Open to disc, input gboolean
+ access - Required access pattern for this file, input VipsAccess
+
+ seq is not there ... do we need to hide deprecated?
+
+ check cplusplus as well
+
- test other arg types
input int works
diff --git a/doc/reference/using-python.xml b/doc/reference/using-python.xml
index 2b658ba0..7f8b6e8b 100644
--- a/doc/reference/using-python.xml
+++ b/doc/reference/using-python.xml
@@ -15,8 +15,8 @@
How to use the VIPS library from Python
-
- Using VIPS from Python
+
+ Introduction
VIPS comes with a convenient, high-level Python API based
on gobject-introspection. As long as you can get GOI
@@ -28,8 +28,7 @@
on your platform.
-
-VIPS from Python example
+
#!/usr/bin/python
@@ -48,40 +47,34 @@ im = im.conv(mask)
im.write_to_file(sys.argv[2])
-
-
- Reading the example, the first line loads the input file. You can append
+ Reading this 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.
+ 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. Try
+ help(Vips.Image) to see a list of all the image
+ constructors --- you can load from memory, or create from an array,
+ for example.
- There are
- several other constructors: you can load a formatted image (for example,
- a JPEG format image) from a string with .new_from_buffer().
+ The next line crops 100 pixels off every edge. Try
+ help(im.extract_area) and the C API docs for
+ vips_extract_area() for details. You can use .crop() as a
+ synonym, if you like. im.width gets the image width in
+ pixels, see help(Vips.Image) and vips_image_get_width()
+ and friends for a list of the other getters.
- 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
+ The similarity line shrinks by 10%. By default it uses
+ bilinear interpolation, use interpolate to pick another
interpolator, for example:
@@ -124,139 +117,134 @@ from gi.repository import Vips
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().
+ Vips.Operation.new(). See the C API docs for details.
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:
+ seem more pythonesque, vips includes a set of overrides which form a
+ layer over the bare functions created by gobject-introspection.
+
+
-
+
+ Automatic wrapping
+
+ The overrides intercept member lookup
+ on the Vips.Image class and look for vips operations
+ with that name. So the vips operation "add", which appears in the
+ C API as vips_add(), appears in Python as
+ image.add().
+
-
- Automatic wrapping of vips operations
+
+ 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.
+
-
- 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.
-
-
-
-
- Add docstrings
-
-
- Try help(Vips.Image), or something like:
-
-
-image = Vips.Image.new_from_file("x.jpg")
-help(image.add)
-
-
- 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.
-
-
-
-
- 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:
+
+ 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:
+ 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)
- Although in this case, the .minpos() convenience
- function would be simpler.
-
-
+ Although in this case, the .minpos() convenience
+ function would be simpler.
+
-
- 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.
-
+
+ Because operations are member functions and return the result image,
+ you can chain them. For example, you can write:
-
- 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:
+
+result_image = image.sin().pow(2)
+
+
+ to calculate the square of the sine for each pixel. There is also a
+ full set of arithmetic operator overloads, see below.
+
+
+
+ VIPS types are also automatically wrapped. 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 set of constants 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.
+ You can write:
+
+
+result_image = image.linear(1, 3)
+result_image = image.linear(12.4, 13.9)
+result_image = image.linear([1, 2, 3], [4, 5, 6])
+result_image = image.linear(1, [4, 5, 6])
+
+
+ And so on. A set of overloads are defined for .linear(),
+ see below.
+
+
+
+ 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:
profile = im.get_value("icc-profile-data")
- and profile will be a string.
-
+ and profile will be a string.
+
-
- 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, .ifthenelse() uses a condition image to
- pick pixels between a then and an else image:
+
+ If an operation takes several input images, you can use a constant
+ for all but one of them and the wrapper will expand the constant
+ to an image for you. For example, .ifthenelse() uses
+ a condition image to pick pixels between a then and an else image:
result_image = condition_image.ifthenelse(then_image, else_image)
- 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:
+ 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:
result_image = condition_image.ifthenelse([0, 255, 0], [255, 0, 0])
- Will make an image where true pixels are green and false pixels
- are red.
-
+ Will make an image where true pixels are green and false pixels
+ are red.
+
-
- This is useful for .bandjoin(), the thing to join
- two, or a set of images up bandwise. You can write:
+
+ This is useful for .bandjoin(), the thing to join
+ two or more images up bandwise. You can write:
rgba = rgb.bandjoin(255)
- to add a constant 255 band to an image, perhaps to add an alpha
- channel. Of course you can also write:
+ to add a constant 255 band to an image, perhaps to add an alpha
+ channel. Of course you can also write:
result_image = image1.bandjoin(image2)
@@ -265,70 +253,89 @@ result_image = Vips.Image.bandjoin([image1, image2, image3])
result_image = image1.bandjoin([image2, 255])
- and so on.
-
-
+ and so on.
+
+
-
- Exceptions
-
-
- The wrapper spots errors from vips operations and raises the
- Vips.Error exception. You can catch it in the
- usual way. The .detail member gives the detailed
- error message.
-
-
+
+ Automatic docstrings
+
+ Try help(Vips) for everything,
+ help(Vips.Image) for something slightly more digestible, or
+ something like help(Vips.Image.black) for help on a
+ specific class member.
+
-
- Overloads
+
+ You can't get help on dynamically bound member functions like
+ .add() this way. Instead, make an image and get help
+ from that, for example:
-
- The wrapper defines the usual set of arithmetic, boolean and
- relation overloads on
- image. You can mix images, constants and lists of
- constants (almost) freely.
-
-
+
+image = Vips.Image.new_from_file("x.jpg")
+help(image.add)
+
-
- Expansions
+ And you'll get a summary of the operator's behaviour and how the
+ arguments are represented in Python. Use the C API docs for more detail.
+
+
-
- Some vips operators take an enum to select an action, for example
- .math() can be used to calculate sine of every pixel
- like this:
+
+ Exceptions
+
+ The wrapper spots errors from vips operations and raises the
+ Vips.Error exception. You can catch it in the
+ usual way. The .detail member gives the detailed
+ error message.
+
+
+
+
+ Overloads
+
+ The wrapper defines the usual set of arithmetic, boolean and
+ relational overloads on
+ image. You can mix images, constants and lists of
+ constants (almost) freely. For example, you can write:
+
+
+result_image = ((image * [1, 2, 3]).abs() < 128) | 4
+
+
+
+
+
+ Expansions
+
+ Some vips operators take an enum to select an action, for example
+ .math() can be used to calculate sine of every pixel
+ like this:
result_image = image.math(Vips.OperationMath.SIN)
- This is annoying, so the wrapper expands all these enums into
- separate members named after the enum. So you can write:
+ This is annoying, so the wrapper expands all these enums into
+ separate members named after the enum. So you can write:
result_image = image.sin()
- See help(Vips.Image) for a list.
-
-
-
-
- Utility functions
-
-
- The wrapper defines a few extra useful utility functions:
- .get_value(), .set_value()
- .bandsplit(), .maxpos()
- .minpos().
- Again, see help(Vips.Image) for a list.
-
-
-
-
+ See help(Vips.Image) for a list.
+
+
+
+
+ Convenience functions
+
+ The wrapper defines a few extra useful utility functions:
+ .get_value(), .set_value()
+ .bandsplit(), .maxpos()
+ .minpos().
+ Again, see help(Vips.Image) for a list.
-