more pyvips8 docs

and cleanups of various small doc markup errors
This commit is contained in:
John Cupitt 2014-11-07 14:49:18 +00:00
parent 02e8c600db
commit be4ffa6d8a
44 changed files with 196 additions and 35 deletions

18
TODO
View File

@ -1,16 +1,26 @@
- try:
$ vipsthumbnail 360mp.png --vips-leak --vips-concurrency=1
--vips-progress
$ vipsthumbnail 360mp.png --vips-leak --vips-concurrency=1 --vips-progress
works in tiles ... should it be strips?
no %complete feedback
- try:
vips gaussnoise r.v 64 64
vips gaussnoise g.v 64 64
vips gaussnoise b.v 64 64
vips bandjoin "r.v g.v b.v" out.png
out.png is monochrome for the first line of tiles ... do we need to seed the
generator?
- why don't we get gtk-doc expansions in the leading chapters? we turn them on
- need a thing to test C++ overloads
- can we generate python docstrings?
when we make a __getattr__ object, make it respond to __doc__
- test other arg types

View File

@ -134,8 +134,12 @@ from gi.repository import Vips
<itemizedlist>
<listitem>
<para><emphasis>
Automatic wrapping of vips operations
</emphasis> </para>
<para>
Automatic wrapping of vips operations. It intercepts member lookup
It intercepts member lookup
on the <code>Vips.Image</code> 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
@ -174,8 +178,9 @@ min_value, x_pos, y_pos = im.min(x = True, y = True)
</listitem>
<listitem>
<para><emphasis>Automatic type conversion</emphasis></para>
<para>
Automatic type conversion. The override looks at the type of
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
@ -184,16 +189,120 @@ min_value, x_pos, y_pos = im.min(x = True, y = True)
</para>
<para>
It does a couple of more ambitious conversions. If an operation
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:
<programlisting language="Python">
profile = im.get_value("icc-profile-data")
</programlisting>
and <code>profile</code> will be a string.
</para>
<para>
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, <code>.bandjoin()</code>
For example, <code>.ifthenelse()</code> uses a condition image to
pick pixels between a then and an else image:
<programlisting language="Python">
result_image = condition_image.ifthenelse(then_image, else_image)
</programlisting>
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:
<programlisting language="Python">
result_image = condition_image.ifthenelse([0, 255, 0], [255, 0, 0])
</programlisting>
Will make an image where true pixels are green and false pixels
are red.
</para>
<para>
This is useful for <code>.bandjoin()</code>, the thing to join
two, or a set of images up bandwise. You can write:
<programlisting language="Python">
rgba = rgb.bandjoin(255)
</programlisting>
to add a constant 255 band to an image, perhaps to add an alpha
channel. Of course you can also write:
<programlisting language="Python">
result_image = image1.bandjoin(image2)
result_image = image1.bandjoin([image2, image3])
result_image = Vips.Image.bandjoin([image1, image2, image3])
result_image = image1.bandjoin([image2, 255])
</programlisting>
and so on.
</para>
</listitem>
<listitem>
<para><emphasis>Exceptions</emphasis></para>
<para>
The wrapper spots errors from vips operations and raises the
<code>Vips.Error</code> exception. You can catch it in the
usual way.
</para>
</listitem>
<listitem>
<para><emphasis>Overloads</emphasis></para>
<para>
The wrapper defines the usual set of arithmetic, boolean and
relation overloads on
<code>image</code>. You can mix images, constants and lists of
constants (almost) freely.
</para>
</listitem>
<listitem>
<para><emphasis>Expansions</emphasis></para>
<para>
Some vips operators take an enum to select an action, for example
<code>.math()</code> can be used to calculate sine of every pixel
like this:
<programlisting language="Python">
result_image = image.math(Vips.OperationMath.SIN)
</programlisting>
This is annoying, so the wrapper expands all these enums into
separate members named after the enum. So you can write:
<programlisting language="Python">
result_image = image.sin()
</programlisting>
</para>
</listitem>
<listitem>
<para><emphasis>Utility functions</emphasis></para>
<para>
The wrapper defines a few extra useful utility functions:
<code>.get_value()</code>, <code>.set_value()</code>
<code>.bandsplit()</code>, <code>.maxpos()</code>
<code>.minpos()</code>.
</para>
</listitem>
</itemizedlist>
</para>
</refsect1>
</refentry>

View File

@ -932,6 +932,7 @@ vips_complexform_init( VipsComplexform *complexform )
* @left: input image
* @right: input image
* @out: output image
* @...: %NULL-terminated list of optional named arguments
*
* Compose two real images to make a complex image. If either @left or @right
* are #VIPS_FORMAT_DOUBLE, @out is #VIPS_FORMAT_DPCOMPLEX. Otherwise @out

View File

@ -177,6 +177,7 @@ vips_getpoint_init( VipsGetpoint *getpoint )
* @n: length of output vector
* @x: position to read
* @y: position to read
* @...: %NULL-terminated list of optional named arguments
*
* Reads a single pixel on an image.
*

View File

@ -187,6 +187,7 @@ vips_multiply_init( VipsMultiply *multiply )
* @left: left-hand image
* @right: right-hand image
* @out: output image
* @...: %NULL-terminated list of optional named arguments
*
* This operation calculates @left * @right and writes the result to @out.
*

View File

@ -165,6 +165,7 @@ vips_sign_init( VipsSign *sign )
* vips_sign:
* @in: input image
* @out: output image
* @...: %NULL-terminated list of optional named arguments
*
* Finds the unit vector in the direction of the pixel value. For non-complex
* images, it returns a signed char image with values -1, 0, and 1 for negative,

View File

@ -134,6 +134,7 @@ vips_LCh2Lab_init( VipsLCh2Lab *LCh2Lab )
* vips_LCh2Lab:
* @in: input image
* @out: output image
* @...: %NULL-terminated list of optional named arguments
*
* Turn LCh to Lab.
*

View File

@ -220,6 +220,7 @@ vips_LCh2CMC_init( VipsLCh2CMC *LCh2CMC )
* vips_LCh2CMC:
* @in: input image
* @out: output image
* @...: %NULL-terminated list of optional named arguments
*
* Turn LCh to CMC.
*

View File

@ -146,6 +146,7 @@ vips_Lab2LCh_init( VipsLab2LCh *Lab2LCh )
* vips_Lab2LCh:
* @in: input image
* @out: output image
* @...: %NULL-terminated list of optional named arguments
*
* Turn Lab to LCh.
*

View File

@ -160,6 +160,7 @@ vips_Lab2LabQ_init( VipsLab2LabQ *Lab2LabQ )
* vips_Lab2LabQ:
* @in: input image
* @out: output image
* @...: %NULL-terminated list of optional named arguments
*
* Convert a Lab three-band float image to LabQ (#IM_CODING_LABQ).
*

View File

@ -101,6 +101,7 @@ vips_Lab2LabS_init( VipsLab2LabS *Lab2LabS )
* vips_Lab2LabS:
* @in: input image
* @out: output image
* @...: %NULL-terminated list of optional named arguments
*
* Turn Lab to LabS, signed 16-bit int fixed point.
*

View File

@ -144,6 +144,7 @@ vips_LabQ2Lab_init( VipsLabQ2Lab *LabQ2Lab )
* vips_LabQ2Lab:
* @in: input image
* @out: output image
* @...: %NULL-terminated list of optional named arguments
*
* Unpack a LabQ (#IM_CODING_LABQ) image to a three-band float image.
*

View File

@ -124,6 +124,7 @@ vips_LabQ2LabS_init( VipsLabQ2LabS *LabQ2LabS )
* vips_LabQ2LabS:
* @in: input image
* @out: output image
* @...: %NULL-terminated list of optional named arguments
*
* Unpack a LabQ (#IM_CODING_LABQ) image to a three-band short image.
*

View File

@ -476,6 +476,7 @@ vips_LabQ2sRGB_init( VipsLabQ2sRGB *LabQ2sRGB )
* vips_LabQ2sRGB:
* @in: input image
* @out: output image
* @...: %NULL-terminated list of optional named arguments
*
* Unpack a LabQ (#VIPS_CODING_LABQ) image to a three-band short image.
*

View File

@ -99,6 +99,7 @@ vips_LabS2Lab_init( VipsLabS2Lab *LabS2Lab )
* vips_LabS2Lab:
* @in: input image
* @out: output image
* @...: %NULL-terminated list of optional named arguments
*
* Convert a LabS three-band signed short image to a three-band float image.
*

View File

@ -148,6 +148,7 @@ vips_LabS2LabQ_init( VipsLabS2LabQ *LabS2LabQ )
* vips_LabS2LabQ:
* @in: input image
* @out: output image
* @...: %NULL-terminated list of optional named arguments
*
* Convert a LabS three-band signed short image to LabQ
*

View File

@ -281,6 +281,7 @@ vips_CMC2LCh_init( VipsCMC2LCh *CMC2LCh )
* vips_CMC2LCh:
* @in: input image
* @out: output image
* @...: %NULL-terminated list of optional named arguments
*
* Turn LCh to CMC.
*

View File

@ -106,6 +106,7 @@ vips_XYZ2Yxy_init( VipsXYZ2Yxy *XYZ2Yxy )
* vips_XYZ2Yxy:
* @in: input image
* @out: output image
* @...: %NULL-terminated list of optional named arguments
*
* Turn XYZ to Yxy.
*

View File

@ -117,6 +117,7 @@ vips_XYZ2scRGB_init( VipsXYZ2scRGB *XYZ2scRGB )
* vips_XYZ2scRGB:
* @in: input image
* @out: output image
* @...: %NULL-terminated list of optional named arguments
*
* Turn XYZ to Yxy.
*

View File

@ -107,6 +107,7 @@ vips_Yxy2XYZ_init( VipsYxy2XYZ *Yxy2XYZ )
* vips_Yxy2XYZ:
* @in: input image
* @out: output image
* @...: %NULL-terminated list of optional named arguments
*
* Turn XYZ to Yxy.
*

View File

@ -250,6 +250,7 @@ vips_dE00_init( VipsdE00 *dE00 )
* @left: first input image
* @right: second input image
* @out: output image
* @...: %NULL-terminated list of optional named arguments
*
* Calculate dE 00.
*

View File

@ -128,6 +128,7 @@ vips_dE76_init( VipsdE76 *dE76 )
* @left: first input image
* @right: second input image
* @out: output image
* @...: %NULL-terminated list of optional named arguments
*
* Calculate dE 76.
*

View File

@ -76,6 +76,7 @@ vips_dECMC_init( VipsdECMC *dECMC )
* @left: first input image
* @right: second input image
* @out: output image
* @...: %NULL-terminated list of optional named arguments
*
* Calculate dE CMC. The input images are transformed to CMC colour space and
* the euclidean distance between corresponding pixels calculated.

View File

@ -223,6 +223,7 @@ vips_float2rad_init( VipsFloat2rad *float2rad )
* vips_float2rad:
* @in: input image
* @out: output image
* @...: %NULL-terminated list of optional named arguments
*
* Convert a three-band float image to Radiance 32-bit packed format.
*

View File

@ -210,6 +210,7 @@ vips_rad2float_init( VipsRad2float *rad2float )
* vips_rad2float:
* @in: input image
* @out: output image
* @...: %NULL-terminated list of optional named arguments
*
* Unpack a RAD (#IM_CODING_RAD) image to a three-band float image.
*

View File

@ -178,6 +178,7 @@ vips_sRGB2scRGB_init( VipssRGB2scRGB *sRGB2scRGB )
* vips_sRGB2scRGB:
* @in: input image
* @out: output image
* @...: %NULL-terminated list of optional named arguments
*
* Convert an sRGB image to scRGB.
*

View File

@ -69,7 +69,14 @@
* @VIPS_PRECISION_APPROXIMATE: approximate integer output
*
* How accurate an operation should be.
*/
/**
* VipsCombine:
* @VIPS_COMBINE_MAX: take the maximum of the possible values
* @VIPS_COMBINE_SUM: sum all the values
*
* How to combine values.
*/
G_DEFINE_ABSTRACT_TYPE( VipsConvolution, vips_convolution,

View File

@ -30,9 +30,7 @@ libcreate_la_SOURCES = \
black.c \
text.c \
gaussnoise.c \
im_benchmark.c \
sines.c \
zone.c \
other_dispatch.c
zone.c
AM_CPPFLAGS = -I${top_srcdir}/libvips/include @VIPS_CFLAGS@ @VIPS_INCLUDES@

View File

@ -100,7 +100,7 @@ vips_mask_ideal_init( VipsMaskIdeal *ideal )
* @out: output image
* @width: image size
* @height: image size
* @frequency_cutoff:
* @frequency_cutoff: threshold at which filter ends
* @...: %NULL-terminated list of optional named arguments
*
* Optional arguments:

View File

@ -114,8 +114,8 @@ vips_mask_ideal_ring_init( VipsMaskIdealRing *ideal_ring )
* @out: output image
* @width: image size
* @height: image size
* @frequency_cutoff:
* @ringwidth: ringwidth
* @frequency_cutoff: threshold at which filter ends
* @ringwidth: ring width
* @...: %NULL-terminated list of optional named arguments
*
* Optional arguments:

View File

@ -20,6 +20,7 @@ libdeprecated_la_SOURCES = \
im_zerox.c \
arith_dispatch.c \
hist_dispatch.c \
other_dispatch.c \
im_maxpos_avg.c \
wrapvips7.c \
lazy.c \
@ -31,6 +32,7 @@ libdeprecated_la_SOURCES = \
cooc_funcs.c \
glds_funcs.c \
im_fav4.c \
im_benchmark.c \
im_gadd.c \
im_gaddim.c \
im_gradcor.c \

View File

@ -339,6 +339,7 @@ vips_draw_linev( VipsImage *image,
* @y1: start of draw_line
* @x2: end of draw_line
* @y2: end of draw_line
* @...: %NULL-terminated list of optional named arguments
*
* Draws a 1-pixel-wide line on an image. Subclass and override ::plot to draw
* lines made of other objects. See vips_draw_line_mask(), for example.
@ -371,6 +372,7 @@ vips_draw_line( VipsImage *image,
* @y1: start of draw_line
* @x2: end of draw_line
* @y2: end of draw_line
* @...: %NULL-terminated list of optional named arguments
*
* As vips_draw_line(), but just take a single double for @ink.
*

View File

@ -364,10 +364,12 @@ vips_draw_maskv( VipsImage *image,
/**
* vips_draw_mask:
* @image: image to draw on
* @ink: value to draw
* @ink: (array length=n): value to draw
* @n: size of ink array
* @mask: mask of 0/255 values showing where to plot
* @x: draw mask here
* @y: draw mask here
* @...: %NULL-terminated list of optional named arguments
*
* Draw @mask on the image. @mask is a monochrome 8-bit image with 0/255
* for transparent or @ink coloured points. Intermediate values blend the ink
@ -401,6 +403,7 @@ vips_draw_mask( VipsImage *image,
* @mask: mask of 0/255 values showing where to plot
* @x: draw mask here
* @y: draw mask here
* @...: %NULL-terminated list of optional named arguments
*
* As vips_draw_mask(), but just takes a single double for @ink.
*

View File

@ -235,6 +235,7 @@ vips_draw_smudge_init( VipsDrawSmudge *draw_smudge )
* @top: point to paint
* @width: area to paint
* @height: area to paint
* @...: %NULL-terminated list of optional named arguments
*
* Smudge a section of @image. Each pixel in the area @left, @top, @width,
* @height is replaced by the average of the surrounding 3x3 pixels.

View File

@ -158,13 +158,13 @@ vips_foreign_load_raw_init( VipsForeignLoadRaw *raw )
* vips_rawload:
* @filename: file to load
* @out: output image
* @width: width of image in pixels
* @height: height of image in pixels
* @bands: number of image bands
* @...: %NULL-terminated list of optional named arguments
*
* Optional arguments:
*
* @width: width of image in pixels
* @height: height of image in pixels
* @bands: number of image bands
* @offset: offset in bytes from start of file
*
* This operation mmaps the file, setting @out so that access to that

View File

@ -121,6 +121,8 @@ typedef enum {
* @VIPS_OPERATION_BOOLEAN_AND: &
* @VIPS_OPERATION_BOOLEAN_OR: |
* @VIPS_OPERATION_BOOLEAN_EOR: ^
* @VIPS_OPERATION_BOOLEAN_LSHIFT: >>
* @VIPS_OPERATION_BOOLEAN_RSHIFT: <<
*
* See also: vips_boolean().
*/

View File

@ -67,7 +67,7 @@ int vips_stop_many( void *seq, void *a, void *b );
VipsImage **vips_allocate_input_array( VipsImage *out, ... )
__attribute__((sentinel));
int vips_image_generate( VipsImage *im,
int vips_image_generate( VipsImage *image,
VipsStartFn start_fn, VipsGenerateFn generate_fn, VipsStopFn stop_fn,
void *a, void *b
);

View File

@ -129,7 +129,7 @@ int vips_threadpool_run( VipsImage *im,
VipsThreadpoolProgressFn progress,
void *a );
void vips_get_tile_size( VipsImage *im,
int *tile_width, int *tile_height, int *nlines );
int *tile_width, int *tile_height, int *n_lines );
void vips_concurrency_set( int concurrency );
int vips_concurrency_get( void );

View File

@ -525,7 +525,7 @@ vips_start_many( VipsImage *out, void *a, void *b )
/**
* vips_allocate_input_array:
* @image: free array when this image closes
* @out: free array when this image closes
* @...: %NULL-terminated list of input images
*
* Convenience function --- make a %NULL-terminated array of input images.
@ -536,7 +536,7 @@ vips_start_many( VipsImage *out, void *a, void *b )
* Returns: %NULL-terminated array of images. Do not free the result.
*/
VipsImage **
vips_allocate_input_array( VipsImage *image, ... )
vips_allocate_input_array( VipsImage *out, ... )
{
va_list ap;
VipsImage **ar;
@ -544,19 +544,19 @@ vips_allocate_input_array( VipsImage *image, ... )
/* Count input images.
*/
va_start( ap, image );
va_start( ap, out );
for( n = 0; va_arg( ap, VipsImage * ); n++ )
;
va_end( ap );
/* Allocate array.
*/
if( !(ar = VIPS_ARRAY( image, n + 1, VipsImage * )) )
if( !(ar = VIPS_ARRAY( out, n + 1, VipsImage * )) )
return( NULL );
/* Fill array.
*/
va_start( ap, image );
va_start( ap, out );
for( i = 0; i < n; i++ )
ar[i] = va_arg( ap, VipsImage * );
va_end( ap );
@ -567,7 +567,7 @@ vips_allocate_input_array( VipsImage *image, ... )
/**
* VipsStartFn:
* @image: image being calculated
* @out: image being calculated
* @a: user data
* @b: user data
*
@ -581,13 +581,14 @@ vips_allocate_input_array( VipsImage *image, ... )
/**
* VipsGenerateFn:
* @region: #VipsRegion to fill
* @out: #VipsRegion to fill
* @seq: sequence value
* @a: user data
* @b: user data
* @stop: set this to stop processing
*
* Fill @image->valid with pixels. @seq contains per-thread state, such as the
* input regions.
* Fill @out->valid with pixels. @seq contains per-thread state, such as the
* input regions. Set @stop to %TRUE to stop processing.
*
* See also: vips_image_generate(), vips_stop_many().
*

View File

@ -160,7 +160,8 @@
/**
* VipsOperationFlags:
* @VIPS_OPERATION_NONE: no flags
* @VIPS_OPERATION_SEQUENTIAL: can work sequentially
* @VIPS_OPERATION_SEQUENTIAL: can work sequentially with a small buffer
* @VIPS_OPERATION_SEQUENTIAL_UNBUFFERED: can work sequentially with no buffer
* @VIPS_OPERATION_NOCACHE: must not be cached
* @VIPS_OPERATION_DEPRECATED: a compatibility thing
*
@ -831,15 +832,15 @@ vips_call_by_name( const char *operation_name,
/**
* vips_call:
* @operation_name:
* @operation_name: name of operation to call
* @...: required args, then a %NULL-terminated list of argument/value pairs
*
* vips_call() calls the named operation, passing in required arguments, and
* vips_call() calls the named operation, passing in required arguments and
* then setting any optional ones from the remainder of the arguments as a set
* of name/value pairs.
*
* For example, vips_embed() takes six required arguments, @in, @out, @x, @y,
* @width, @height; and has two optional arguments, @extend and @background.
* @width, @height, and has two optional arguments, @extend and @background.
* You can run it with vips_call() like this:
*
* |[

View File

@ -1428,7 +1428,7 @@ vips_value_get_array_int( const GValue *value, int *n )
/**
* vips_value_set_array_int:
* @value: (out): %GValue to get from
* @array: (array length=n) (allow_none): array of ints
* @array: (array length=n) (allow-none): array of ints
* @n: the number of elements
*
* Set @value to hold a copy of @array. Pass in the array length in @n.

View File

@ -435,6 +435,7 @@ vips_shrink_init( VipsShrink *shrink )
* @out: output image
* @xshrink: horizontal shrink
* @yshrink: vertical shrink
* @...: %NULL-terminated list of optional named arguments
*
* Shrink @in by a pair of factors with a simple box filter.
*