From a7766b28b34c5335f1125145e9a43d1ad805ca5c Mon Sep 17 00:00:00 2001 From: John Cupitt Date: Wed, 7 Oct 2015 12:20:22 +0100 Subject: [PATCH] improve py docs --- doc/using-python.xml | 188 ++++++++++++++++++++++++++++++++++--------- 1 file changed, 149 insertions(+), 39 deletions(-) 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