README
======
.. image:: https://github.com/libvips/pyvips/workflows/CI/badge.svg
:alt: Build Status
:target: https://github.com/libvips/pyvips/actions
PyPI package:
https://pypi.python.org/pypi/pyvips
conda package:
https://anaconda.org/conda-forge/pyvips
We have formatted docs online here:
https://libvips.github.io/pyvips/
This module wraps the libvips image processing library:
https://libvips.github.io/libvips/
The libvips docs are also very useful:
https://libvips.github.io/libvips/API/current/
If you have the development headers for libvips installed and have a working C
compiler, this module will use cffi API mode to try to build a libvips
binary extension for your Python.
If it is unable to build a binary extension, it will use cffi ABI mode
instead and only needs the libvips shared library. This takes longer to
start up and is typically ~20% slower in execution. You can find out how
pyvips installed with ``pip show pyvips``.
This binding passes the vips test suite cleanly and with no leaks under
python2.7 - python3.11, pypy and pypy3 on Windows, macOS and Linux.
How it works
------------
Programs that use ``pyvips`` don't manipulate images directly, instead
they create pipelines of image processing operations building on a source
image. When the end of the pipe is connected to a destination, the whole
pipeline executes at once, streaming the image in parallel from source to
destination a section at a time.
Because ``pyvips`` is parallel, it's quick, and because it doesn't need to
keep entire images in memory, it's light. For example, the libvips
speed and memory use benchmark:
https://github.com/libvips/libvips/wiki/Speed-and-memory-use
Loads a large tiff image, shrinks by 10%, sharpens, and saves again. On this
test ``pyvips`` is typically 3x faster than ImageMagick and needs 5x less
memory.
There's a handy chapter in the docs explaining how libvips opens files,
which gives some more background.
http://libvips.github.io/libvips/API/current/How-it-opens-files.md.html
Install
-------
You need the libvips shared library on your library search path,
version 8.2 or later, though at least version 8.9 is required for all features
to work. See:
https://libvips.github.io/libvips/install.html
Linux install
-------------
Perhaps:
.. code-block:: shell
$ sudo apt install libvips-dev --no-install-recommends
$ pip install pyvips
With python 3.11 and later, you will need to create a venv first and add
`path/to/venv` to your `PATH`. Something like:
.. code-block:: shell
$ python3 -m venv ~/.local
$ pip install pyvips
macOS install
-------------
With homebrew:
.. code-block:: shell
$ brew install vips python pkg-config
$ pip3 install pyvips
Windows install
---------------
on Windows you can download a pre-compiled binary from the libvips website.
https://libvips.github.io/libvips/install.html
You'll need a 64-bit Python. The official one works well.
You can add ``vips-dev-x.y\bin`` to your ``PATH``, but this will add a lot of
extra DLLs to your search path and they might conflict with other programs,
so it's usually safer to set ``PATH`` in your program.
To set ``PATH`` from within Python, you need something like this at the
start of your program:
.. code-block:: python
import os
vipsbin = r'c:\vips-dev-8.13\bin'
os.environ['PATH'] = vipsbin + ';' + os.environ['PATH']
For Python 3.8 and later, you need:
.. code-block:: python
import os
vipsbin = r'c:\vips-dev-8.13\bin'
add_dll_dir = getattr(os, 'add_dll_directory', None)
if callable(add_dll_dir):
add_dll_dir(vipsbin)
else:
os.environ['PATH'] = os.pathsep.join((vipsbin, os.environ['PATH']))
Now when you import pyvips, it should be able to find the DLLs.
conda install
-------------
The conda package includes a matching libvips binary, so just enter:
.. code-block:: shell
$ conda install --channel conda-forge pyvips
Example
-------
This sample program loads a JPG image, doubles the value of every green pixel,
sharpens, and then writes the image back to the filesystem again:
.. code-block:: python
import pyvips
image = pyvips.Image.new_from_file('some-image.jpg', access='sequential')
image *= [1, 2, 1]
mask = pyvips.Image.new_from_array([
[-1, -1, -1],
[-1, 16, -1],
[-1, -1, -1],
], scale=8)
image = image.conv(mask, precision='integer')
image.write_to_file('x.jpg')
Notes
-----
Local user install:
.. code-block:: shell
$ pip3 install -e .
$ pypy -m pip --user -e .
Run all tests:
.. code-block:: shell
$ tox
Run test suite:
.. code-block:: shell
$ pytest
Run a specific test:
.. code-block:: shell
$ pytest tests/test_saveload.py
Run perf tests:
.. code-block:: shell
$ cd tests/perf
$ ./run.sh
Stylecheck:
.. code-block:: shell
$ flake8
Generate HTML docs in ``doc/build/html``:
.. code-block:: shell
$ cd doc; sphinx-build -bhtml . build/html
Regenerate enums:
Make sure you have installed a libvips with all optional packages enabled,
then
.. code-block:: shell
$ cd examples; \
./gen-enums.py ~/GIT/libvips/libvips/Vips-8.0.gir > enums.py
Then check and move `enums.py` into `pyvips/`.
Regenerate autodocs:
Make sure you have installed a libvips with all optional packages enabled,
then
.. code-block:: shell
$ cd doc; \
python3 -c "import pyvips; pyvips.Operation.generate_sphinx_all()" > x
And copy-paste ``x`` into the obvious place in ``doc/vimage.rst``.
Update version number:
.. code-block:: shell
$ vi pyvips/version.py
$ vi doc/conf.py
Update pypi package:
.. code-block:: shell
$ python3 setup.py sdist
$ twine upload --repository pyvips dist/*
$ git tag -a v2.2.0 -m "as uploaded to pypi"
$ git push origin v2.2.0
Raw data
{
"_id": null,
"home_page": "https://github.com/libvips/pyvips",
"name": "pyvips",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "image processing",
"author": "John Cupitt",
"author_email": "jcupitt@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/7b/88/f73dae807ec68b228fba72507105e3ba80a561dc0bade0004ce24fd118fc/pyvips-2.2.3.tar.gz",
"platform": null,
"description": "README\n======\n\n.. image:: https://github.com/libvips/pyvips/workflows/CI/badge.svg\n :alt: Build Status\n :target: https://github.com/libvips/pyvips/actions\n\nPyPI package:\n\nhttps://pypi.python.org/pypi/pyvips\n\nconda package:\n\nhttps://anaconda.org/conda-forge/pyvips\n\nWe have formatted docs online here:\n\nhttps://libvips.github.io/pyvips/\n\nThis module wraps the libvips image processing library:\n\nhttps://libvips.github.io/libvips/\n\nThe libvips docs are also very useful:\n\nhttps://libvips.github.io/libvips/API/current/\n\nIf you have the development headers for libvips installed and have a working C\ncompiler, this module will use cffi API mode to try to build a libvips \nbinary extension for your Python. \n\nIf it is unable to build a binary extension, it will use cffi ABI mode\ninstead and only needs the libvips shared library. This takes longer to\nstart up and is typically ~20% slower in execution. You can find out how\npyvips installed with ``pip show pyvips``.\n\nThis binding passes the vips test suite cleanly and with no leaks under\npython2.7 - python3.11, pypy and pypy3 on Windows, macOS and Linux. \n\nHow it works\n------------\n\nPrograms that use ``pyvips`` don't manipulate images directly, instead\nthey create pipelines of image processing operations building on a source\nimage. When the end of the pipe is connected to a destination, the whole\npipeline executes at once, streaming the image in parallel from source to\ndestination a section at a time.\n\nBecause ``pyvips`` is parallel, it's quick, and because it doesn't need to\nkeep entire images in memory, it's light. For example, the libvips \nspeed and memory use benchmark:\n\nhttps://github.com/libvips/libvips/wiki/Speed-and-memory-use\n\nLoads a large tiff image, shrinks by 10%, sharpens, and saves again. On this\ntest ``pyvips`` is typically 3x faster than ImageMagick and needs 5x less\nmemory. \n\nThere's a handy chapter in the docs explaining how libvips opens files,\nwhich gives some more background.\n\nhttp://libvips.github.io/libvips/API/current/How-it-opens-files.md.html\n\nInstall\n-------\n\nYou need the libvips shared library on your library search path,\nversion 8.2 or later, though at least version 8.9 is required for all features\nto work. See:\n\nhttps://libvips.github.io/libvips/install.html\n\nLinux install\n-------------\n\nPerhaps:\n\n.. code-block:: shell\n\n $ sudo apt install libvips-dev --no-install-recommends\n $ pip install pyvips\n\nWith python 3.11 and later, you will need to create a venv first and add\n`path/to/venv` to your `PATH`. Something like:\n\n.. code-block:: shell\n\n $ python3 -m venv ~/.local\n $ pip install pyvips\n\nmacOS install\n-------------\n\nWith homebrew:\n\n.. code-block:: shell\n\n $ brew install vips python pkg-config\n $ pip3 install pyvips\n\nWindows install\n---------------\n\non Windows you can download a pre-compiled binary from the libvips website.\n\nhttps://libvips.github.io/libvips/install.html\n\nYou'll need a 64-bit Python. The official one works well.\n\nYou can add ``vips-dev-x.y\\bin`` to your ``PATH``, but this will add a lot of\nextra DLLs to your search path and they might conflict with other programs,\nso it's usually safer to set ``PATH`` in your program.\n\nTo set ``PATH`` from within Python, you need something like this at the\nstart of your program:\n\n.. code-block:: python\n\n import os\n vipsbin = r'c:\\vips-dev-8.13\\bin'\n os.environ['PATH'] = vipsbin + ';' + os.environ['PATH']\n\nFor Python 3.8 and later, you need:\n\n.. code-block:: python\n\n import os\n vipsbin = r'c:\\vips-dev-8.13\\bin'\n add_dll_dir = getattr(os, 'add_dll_directory', None)\n if callable(add_dll_dir):\n add_dll_dir(vipsbin)\n else:\n os.environ['PATH'] = os.pathsep.join((vipsbin, os.environ['PATH']))\n\nNow when you import pyvips, it should be able to find the DLLs.\n\nconda install\n-------------\n\nThe conda package includes a matching libvips binary, so just enter:\n\n.. code-block:: shell\n\n $ conda install --channel conda-forge pyvips\n\nExample\n-------\n\nThis sample program loads a JPG image, doubles the value of every green pixel,\nsharpens, and then writes the image back to the filesystem again:\n\n.. code-block:: python\n\n import pyvips\n\n image = pyvips.Image.new_from_file('some-image.jpg', access='sequential')\n image *= [1, 2, 1]\n mask = pyvips.Image.new_from_array([\n [-1, -1, -1],\n [-1, 16, -1],\n [-1, -1, -1],\n ], scale=8)\n image = image.conv(mask, precision='integer')\n image.write_to_file('x.jpg')\n\n\nNotes\n-----\n\nLocal user install:\n\n.. code-block:: shell\n\n $ pip3 install -e .\n $ pypy -m pip --user -e .\n\nRun all tests:\n\n.. code-block:: shell\n\n $ tox \n\nRun test suite:\n\n.. code-block:: shell\n\n $ pytest\n\nRun a specific test:\n\n.. code-block:: shell\n\n $ pytest tests/test_saveload.py\n\nRun perf tests:\n\n.. code-block:: shell\n\n $ cd tests/perf\n $ ./run.sh\n\nStylecheck:\n\n.. code-block:: shell\n\n $ flake8\n\nGenerate HTML docs in ``doc/build/html``:\n\n.. code-block:: shell\n\n $ cd doc; sphinx-build -bhtml . build/html\n\nRegenerate enums:\n\nMake sure you have installed a libvips with all optional packages enabled,\nthen\n\n.. code-block:: shell\n\n $ cd examples; \\\n ./gen-enums.py ~/GIT/libvips/libvips/Vips-8.0.gir > enums.py\n\nThen check and move `enums.py` into `pyvips/`.\n\nRegenerate autodocs:\n\nMake sure you have installed a libvips with all optional packages enabled,\nthen\n\n.. code-block:: shell\n\n $ cd doc; \\\n python3 -c \"import pyvips; pyvips.Operation.generate_sphinx_all()\" > x \n\nAnd copy-paste ``x`` into the obvious place in ``doc/vimage.rst``. \n\nUpdate version number:\n\n.. code-block:: shell\n\n $ vi pyvips/version.py\n $ vi doc/conf.py\n\nUpdate pypi package:\n\n.. code-block:: shell\n\n $ python3 setup.py sdist\n $ twine upload --repository pyvips dist/*\n $ git tag -a v2.2.0 -m \"as uploaded to pypi\"\n $ git push origin v2.2.0\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "binding for the libvips image processing library, API mode",
"version": "2.2.3",
"project_urls": {
"Homepage": "https://github.com/libvips/pyvips"
},
"split_keywords": [
"image",
"processing"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "7b88f73dae807ec68b228fba72507105e3ba80a561dc0bade0004ce24fd118fc",
"md5": "a3363bbfa1382aac3a14396bf8f913ac",
"sha256": "43bceced0db492654c93008246a58a508e0373ae1621116b87b322f2ac72212f"
},
"downloads": -1,
"filename": "pyvips-2.2.3.tar.gz",
"has_sig": false,
"md5_digest": "a3363bbfa1382aac3a14396bf8f913ac",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 56626,
"upload_time": "2024-04-28T11:19:58",
"upload_time_iso_8601": "2024-04-28T11:19:58.158771Z",
"url": "https://files.pythonhosted.org/packages/7b/88/f73dae807ec68b228fba72507105e3ba80a561dc0bade0004ce24fd118fc/pyvips-2.2.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-28 11:19:58",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "libvips",
"github_project": "pyvips",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "pyvips"
}
JSON
