diff --git a/doc/using-python.xml b/doc/using-python.xml
index f9a026cd..f7b2e496 100644
--- a/doc/using-python.xml
+++ b/doc/using-python.xml
@@ -46,13 +46,17 @@
- If .new_from_file() fails, the vips overrides
- have not been found. Make sure Vips.py is in
- your system overrides area.
-
-
+ If .new_from_file() fails, the vips overrides
+ have not been found. Make sure Vips.py is in
+ your system overrides area.
+
+
+
+
+
+ Example program
Here's a complete example program:
@@ -75,8 +79,16 @@ im = im.conv(mask)
im.write_to_file(sys.argv[2])
+
- When Python executes the import line:
+
+ Reading this code, the first interesting line is:
+
+
+from gi.repository import Vips
+
+
+ When Python executes the import line it performs the following steps:
@@ -133,7 +145,13 @@ im.write_to_file(sys.argv[2])
- The next line loads the input image. You can append
+ The next line is:
+
+
+im = Vips.Image.new_from_file(sys.argv[1])
+
+
+ This loads the input image. You can append
load options to the argument list as keyword arguments, for example:
@@ -149,16 +167,32 @@ im = Vips.Image.new_from_file(sys.argv[1], access = Vips.Access.SEQUENTIAL)
- 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()
+ The next line is:
+
+
+im = im.extract_area(100, 100, im.width - 200, im.height - 200)
+
+
+ The arguments are left, top, width, height, so this 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 similarity line shrinks by 10%. By default it uses
+ The next line:
+
+
+im = im.similarity(scale = 0.9)
+
+
+ shrinks by 10%. By default it uses
bilinear interpolation, use interpolate to pick another
interpolator, for example:
@@ -166,10 +200,22 @@ im = Vips.Image.new_from_file(sys.argv[1], access = Vips.Access.SEQUENTIAL)
im = im.similarity(scale = 0.9, interpolate = Vips.Interpolate.new("bicubic"))
+ see vips_similarity() for full documentation. The similarity operator
+ will not give good results for large resizees (more than a factor of
+ two). See vips_resize() if you need to make a large change.
- .new_from_array() makes an image from a 2D array. The
+ Next:
+
+
+mask = Vips.Image.new_from_array([[-1, -1, -1],
+ [-1, 16, -1],
+ [-1, -1, -1]], scale = 8)
+im = im.conv(mask)
+
+
+ makes an image from a 2D array, then convolves with that. 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
@@ -177,11 +223,99 @@ im = im.similarity(scale = 0.9, interpolate = Vips.Interpolate.new("bicubic"))
- Finally, .write_to_file() sends the image back to the
+ Finally,
+
+
+im.write_to_file(sys.argv[2])
+
+
+ sends the image back to the
filesystem. There's also .write_to_buffer() to make a
string containing the formatted image, and .write() to
write to another image.
+
+
+ As with .new_from_file() you can append save options as
+ keyword arguments. For example:
+
+
+im.write_to_file("test.jpg", Q = 90)
+
+
+ will write a JPEG image with quality set to 90. See the various save
+ operations for a list of all the save options, for example
+ vips_jpegsave().
+
+
+
+
+
+ Getting help
+
+ 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.
+
+
+
+ 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:
+
+
+image = Vips.Image.new_from_file("x.jpg")
+help(image.add)
+
+
+ And you'll get a summary of the operator's behaviour and how the
+ arguments are represented in Python.
+
+
+
+ The API docs has a handy table of all vips
+ operations, if you want to find out how to do something, try
+ searching that.
+
+
+
+ The vips command can be useful too. For example, in a
+ terminal you can type vips jpegsave to get a
+ summary of an operation:
+
+
+$ vips jpegsave
+save image to jpeg file
+usage:
+ jpegsave in filename
+where:
+ in - Image to save, input VipsImage
+ filename - Filename to save to, input gchararray
+optional arguments:
+ Q - Q factor, input gint
+ default: 75
+ min: 1, max: 100
+ profile - ICC profile to embed, input gchararray
+ optimize-coding - Compute optimal Huffman coding tables, input gboolean
+ default: false
+ interlace - Generate an interlaced (progressive) jpeg, input gboolean
+ default: false
+ no-subsample - Disable chroma subsample, input gboolean
+ default: false
+ trellis-quant - Apply trellis quantisation to each 8x8 block, input gboolean
+ default: false
+ overshoot-deringing - Apply overshooting to samples with extreme values, input gboolean
+ default: false
+ optimize-scans - Split the spectrum of DCT coefficients into separate scans, input gboolean
+ default: false
+ strip - Strip all metadata from image, input gboolean
+ default: false
+ background - Background value, input VipsArrayDouble
+operation flags: sequential-unbuffered nocache
+
+
+
@@ -344,30 +478,6 @@ result_image = image1.bandjoin([image2, 255])
-
- 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.
-
-
-
- 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:
-
-
-image = Vips.Image.new_from_file("x.jpg")
-help(image.add)
-
-
- 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.
-
-
-
Exceptions