8000 just autodocs left to do · libvips/pyvips@6659866 · GitHub
[go: up one dir, main page]
Skip to content

Commit 6659866

Browse files
jcupittjcupitt
committed
just autodocs left to do
1 parent 2788176 commit 6659866

15 files changed

+541
-309
lines changed

‎README.rst

Lines changed: 37 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,46 @@
1-
========
2-
pyvips
3-
========
4-
--------------------------------------------
5-
pyvips experimental CFFI binding for libvips
6-
--------------------------------------------
1+
README
2+
======
73

84
Status
95
------
106

117
This binding passes the vips test suite cleanly and with no leaks under python2
12-
and python3, so it's getting close. The docs still need updating and it could
8+
and python3, on Windows and Linux. The docs still need updating and it could
139
use a little polish.
1410

11+
Install
12+
-------
13+
14+
You need the libvips shared library on your library search path, version 8.2 or
15+
later. On linux, you can install via your package manager, on Windows you
16+
can download a pre-compiled binary from the libvips website:
17+
18+
https://jcupitt.github.io/libvips/
19+
20+
Then just install this package, perhaps::
21+
22+
$ pip install --user -e .
23+
24+
Example
25+
-------
26+
27+
Sample program to load a JPG image, double the value of every green pixel,
28+
sharpen, and write back to the filesystem again::
29+
30+
import pyvips
31+
32+
image = pyvips.Image.new_from_file('some-image.jpg', access='sequential')
33+
image *= [1, 2, 1]
34+
mask = pyvips.Image.new_from_array([[-1, -1, -1],
35+
[-1, 16, -1],
36+
[-1, -1, -1]
37+
], scale=8)
38+
image = image.conv(mask, precision='integer')
39+
image.write_to_file('x.jpg')
40+
41+
Converting old code
42+
-------------------
43+
1544
To convert old code, replace the lines::
1645

1746
import gi
@@ -75,7 +104,7 @@ Local user install::
75104
Run test suite::
76105

77106
$ nosetests --logging-level=WARNING
78-
$ python3 -m "nose" --logging-level=WARNING
107+
$ python3 -m nose --logging-level=WARNING
79108

80109
Stylecheck::
81110

‎doc/README.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
../README.rst

‎doc/conf.py

Lines changed: 7 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -15,10 +15,10 @@
1515
# If extensions (or modules to document with autodoc) are in another directory,
1616
# add these directories to sys.path here. If the directory is relative to the
1717
# documentation root, use os.path.abspath to make it absolute, like shown here.
18-
#
19-
# import os
20-
# import sys
21-
# sys.path.insert(0, os.path.abspath('.'))
18+
19+
import os
20+
import sys
21+
sys.path.insert(0, os.path.abspath('..'))
2222

2323

2424
# -- General configuration ------------------------------------------------
@@ -37,6 +37,8 @@
3737
'sphinx.ext.githubpages'
3838
]
3939

40+
autodoc_member_order = 'bysource'
41+
4042
# Add any paths that contain templates here, relative to this directory.
4143
templates_path = ['_templates']
4244

@@ -73,7 +75,7 @@
7375
# List of patterns, relative to source directory, that match files and
7476
# directories to ignore when looking for source files.
7577
# This patterns also effect to html_static_path and html_extra_path
76-
exclude_patterns = []
78+
exclude_patterns = ['global.rst']
7779

7880
# The name of the Pygments (syntax highlighting) style to use.
7981
pygments_style = 'sphinx'

‎doc/enums.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,3 +10,4 @@ valid strings for each enum.
1010

1111
.. automodule:: pyvips.enums
1212
:members:
13+
:undoc-members:

‎doc/index.rst

Lines changed: 6 additions & 266 deletions
Original file line numberDiff line numberDiff line change
@@ -6,23 +6,16 @@
66
.. module:: pyvips
77
:synopsis: Interface to the libvips image processing library.
88
.. moduleauthor:: John Cupitt <jcupitt@gmail.com>
9-
.. moduleauthor:: Kleis Auke Wolthuizen <x@y.z>
10-
11-
This module wraps the libvips image processing library. It needs vips-8.2
12-
or later to be installed, and it uses cffi to call into the library, so
13-
you need to have the compiled library on your library search path.
14-
15-
See the main libvips site for an introduction to the underlying library. These
16-
notes introduce the Python binding.
17-
18-
https://jcupitt.github.io/libvips
9+
.. moduleauthor:: Kleis Auke Wolthuizen <info@kleisauke.nl>
1910

2011
Contents
2112
--------
2213

2314
.. toctree::
24-
:maxdepth: 3
15+
:maxdepth: 2
2516

17+
README
18+
intro
2619
vimage
2720
error
2821
enums
@@ -32,261 +25,8 @@ Contents
3225
voperation
3326
vobject
3427

35-
Example
36-
-------
37-
38-
This example loads a file, boosts the green channel (I'm not sure why),
39-
sharpens the image, and saves it back to disc again::
40-
41-
import pyvips
42-
43-
image = pyvips.Image.new_from_file('some-image.jpg', access='sequential')
44-
image *= [1, 2, 1]
45-
mask = pyvips.Image.new_from_array([[-1, -1, -1],
46-
[-1, 16, -1],
47-
[-1, -1, -1]
48-
], scale=8)
49-
image = image.conv(mask, precision='integer')
50-
image.write_to_file('x.jpg')
51-
52-
Reading this example line by line, we have::
53-
54-
image = pyvips.Image.new_from_file('some-image.jpg', access='sequential')
55-
56-
:func:`Image.new_from_file` can load any image file supported by libvips. In
57-
this example, we will be accessing pixels top-to-bottom as we sweep through
58-
the image reading and writing, so `sequential` access mode is best for us.
59-
60-
The default mode is ``random`` which allows for full random access to image
61-
pixels, but is slower and needs more memory. See :class:`enums.Access` for full
62-
details on the various modes available.
63-
64-
You can also load formatted images from memory buffers, create images that
65-
wrap C-style memory arrays, or make images from constants.
66-
67-
The next line::
68-
69-
image *= [1, 2, 1]
70-
71-
Multiplying the image by an array constant uses one array element for each
72-
image band. This line assumes that the input image has three bands and will
73-
double the middle band. For RGB images, that's doubling green.
74-
75-
There are the usual range of arithmetic operator overloads.
76-
77-
Next we have::
78-
79-
mask = pyvips.Image.new_from_array([[-1, -1, -1],
80-
[-1, 16, -1],
81-
[-1, -1, -1]
82-
], scale = 8)
83-
image = image.conv(mask, precision = 'integer')
84-
85-
:func:`Image.new_from_array` creates an image from an array constant. The
86-
scale is the amount to divide the image by after integer convolution.
87-
88-
See the libvips API docs for ``vips_conv()`` (the operation
89-
invoked by :func:`Image.conv`) for details on the convolution operator. By
90-
default, it computes with a float mask, but ``integer`` is fine for this case,
91-
and is much faster.
92-
93-
Finally::
94-
95-
image.write_to_file('x.jpg')
96-
97-
:func:`Image.write_to_file` writes an image back to the filesystem. It can
98-
write any format supported by vips: the file type is set from the filename
99-
suffix. You can also write formatted images to memory buffers, or dump
100-
image data to a raw memory array.
101-
102-
How it works
103-
------------
104-
105-
The binding uses https://pypi.python.org/pypi/cffi to open the libvips
106-
shared library. When you call a method on the image class, it uses libvips
107-
introspection system (based on ``GObject``) to search the
108-
library for an operation of that name, transforms the arguments to a form
109-
libvips can digest, and runs the operation.
110-
111-
This means pyvips always presents the API implemented by the libvips shared
112-
library. It should update itself as new features are added.
113-
114-
Automatic wrapping
115-
------------------
116-
117-
``pyvips`` adds a :func:`Image.__getattr__` handler to :class:`Image`
118-
and to the Image metaclass, then uses it to look up vips operations. For
119-
example, the libvips operation ``add``, which appears in C as ``vips_add()``,
120-
appears in Python as :func:`Image.add`.
121-
122-
The operation's list of required arguments is searched and the first input
123-
image is set to the value of ``self``. Operations which do not take an input
124-
image, such as :func:`Image.black`, appear as class methods. The remainder of
125-
the arguments you supply in the function call are used to set the other
126-
required input arguments. Any trailing keyword arguments are used to set
127-
options on the operation.
128-
129-
The result is the required output argument if there is only one result,
130-
or an array of values if the operation produces several results. If the
131-
operation has optional output objects, they are returned as a final hash.
132-
133-
For example, :func:`Image.min`, the vips operation that searches an image for
134-
the minimum value, has a large number of optional arguments. You can use it to
135-
find the minimum value like this::
136-
137-
min_value = image.min()
138-
139-
You can ask it to return the position of the minimum with `:x` and `:y`::
140-
141-
min_value, opts = image.min(x=True, y=True)
142-
x_pos = opts['x']
143-
y_pos = opts['y']
144-
145-
Now ``x_pos`` and ``y_pos`` will have the coordinates of the minimum value.
146-
There's actually a convenience method for this, :func:`Image.minpos`.
147-
148-
You can also ask for the top *n* minimum, for example::
149-
150-
min_value, opts = min(size=10, x_array=True, y_array=True)
151-
x_pos = opts['x_array']
152-
y_pos = opts['y_array']
153-
154-
Now ``x_pos`` and ``y_pos`` will be 10-element arrays.
155-
156-
Because operations are member functions and return the result image, you can
157-
chain them. For example, you can write::
158-
159-
result_image = image.real().cos()
160-
161-
to calculate the cosine of the real part of a complex image. There are
162-
also a full set of arithmetic operator overloads, see below.
163-
164-
libvips types are also automatically wrapped. The binding looks at the type
165-
of argument required by the operation and converts the value you supply,
166-
when it can. For example, :func:`Image.linear` takes a ``VipsArrayDouble`` as an
167-
argument for the set of constants to use for multiplication. You can supply
168-
this value as an integer, a float, or some kind of compound object and it
169-
will be converted for you. You can write::
170-
171-
result_image = image.linear(1, 3)
172-
result_image = image.linear(12.4, 13.9)
173-
result_image = image.linear([1, 2, 3], [4, 5, 6])
174-
result_image = image.linear(1, [4, 5, 6])
175-
176-
And so on. A set of overloads are defined for :func:`Image.linear`, see below.
177-
178-
It does a couple of more ambitious conversions. It will automatically convert
179-
to and from the various vips types, like ``VipsBlob`` and
180-
``VipsArrayImage``. For example, you can read the ICC profile out of an
181-
image like this::
182-
183-
profile = im.get('icc-profile-data')
184-
185-
and profile will be a byte string.
186-
187-
If an operation takes several input images, you can use a constant for all but
188-
one of them and the wrapper will expand the constant to an image for you. For
189-
example, :func:`Image.ifthenelse` uses a condition image to pick pixels
190-
between a then and an else image::
191-
192-
result_image = condition_image.ifthenelse(then_image, else_image)
193-
194-
You can use a constant instead of either the then or the else parts and it
195-
will be expanded to an image for you. If you use a constant for both then and
196-
else, it will be expanded to match the condition image. For example::
197-
198-
result_image = condition_image.ifthenelse([0, 255, 0], [255, 0, 0])
199-
200-
Will make an image where true pixels are green and false pixels are red.
201-
202-
This is useful for :func:`Image.bandjoin`, the thing to join two or more
203-
images up bandwise. You can write::
204-
205-
rgba = rgb.bandjoin(255)
206-
207-
to append a constant 255 band to an image, perhaps to add an alpha channel. Of
208-
course you can also write::
209-
210-
result_image = image1.bandjoin(image2)
211-
result_image = image1.bandjoin([image2, image3])
212-
result_image = pyvips.Image.bandjoin([image1, image2, image3])
213-
result_image = image1.bandjoin([image2, 255])
214-
215-
and so on.
216-
217-
Automatic documentation
218-
-----------------------
219-
220-
The bulk of these API docs are generated automatically by
221-
:func:`Image.generate_docs`. It examines libvips and writes a summary of each
222-
operation and the arguments and options that that operation expects.
223-
224-
Use the C API docs for more detail:
225-
226-
https://jcupitt.github.io/libvips/API/current
227-
228-
Exceptions
229-
----------
230-
231-
The wrapper spots errors from vips operations and raises the :class:`Error`
232-
exception. You can catch it in the usual way.
233-
234-
Enums
235-
-----
236-
237-
The libvips enums, such as ``VipsBandFormat``, appear in pyvips as strings
238-
like ``'uchar'``. They are documented as a set of classes for convenience, see
239-
the class list.
240-
241-
Draw operations
242-
---------------
243-
244-
Paint operations like :func:`Image.draw_circle` and :func:`Image.draw_line`
245-
modify their input image. This makes them hard to use with the rest of
246-
libvips: you need to be very careful about the order in which operations
247-
execute or you can get nasty crashes.
248-
249-
The wrapper spots operations of this type and makes a private copy of the
250-
image in memory before calling the operation. This stops crashes, but it does
251-
make it inefficient. If you draw 100 lines on an image, for example, you'll
252-
copy the image 100 times. The wrapper does make sure that memory is recycled
253-
where possible, so you won't have 100 copies in memory.
254-
255-
If you want to avoid the copies, you'll need to call drawing operations
256-
yourself.
257-
258-
Overloads
259-
---------
260-
261-
The wrapper defines the usual set of arithmetic, boolean and relational
262-
overloads on image. You can mix images, constants and lists of constants
263-
freely. For example, you can write::
264-
265-
result_image = ((image * [1, 2, 3]).abs() < 128) | 4
266-
267-
Expansions
268-
----------
269-
270-
Some vips operators take an enum to select an action, for example
271-
:func:`Image.math` can be used to calculate sine of every pixel like this::
272-
273-
result_image = image.math('sin')
274-
275-
This is annoying, so the wrapper expands all these enums into separate members
276-
named after the enum. So you can also write::
277-
278-
result_image = image.sin()
279-
280-
Convenience functions
281-
---------------------
282-
283-
The wrapper defines a few extra useful utility functions:
284-
:func:`Image#get`, :func:`Image#set`, :func:`Image#bandsplit`,
285-
:func:`Image#maxpos`, :func:`Image#minpos`,
286-
:func:`Image#median`.
287-
288-
Indices and tables
289-
==================
28+
Indicies
29+
--------
29030

29131
* :ref:`genindex`
29232
* :ref:`modindex`

0 commit comments

Comments
 (0)
0