| Name | pmipyvips JSON |
| Version |
3.0.0
JSON |
| download |
| home_page | None |
| Summary | binding for the libvips image processing library |
| upload_time | 2025-08-27 13:41:09 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.7 |
| license | MIT |
| keywords |
image
processing
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
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://www.libvips.org/
The libvips docs are also very useful:
https://www.libvips.org/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 if
API mode is being used with:
.. code-block:: python
import pyvips
print(pyvips.API_mode)
This binding passes the vips test suite cleanly and with no leaks under
python3 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.
https://www.libvips.org/API/current/How-it-opens-files.html
Binary installation
-------------------
The quickest way to start with pyvips is by installing the binary package
with:
.. code-block:: shell
$ pip install "pyvips[binary]"
This installs a self-contained package with the most commonly needed
libraries. It should just work on most common platforms, including Linux,
Windows and macOS, with x64 and ARM CPUs.
If your platform is unsupported or the pre-built binary is
unsuitable, you can install libvips separately instead.
Local installation
------------------
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://www.libvips.org/install.html
Linux
^^^^^
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
^^^^^
With Homebrew:
.. code-block:: shell
$ brew install vips python pkg-config
$ pip install pyvips
Windows
^^^^^^^
On Windows, you can download a pre-compiled binary from the libvips website.
https://www.libvips.org/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.16\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.16\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
^^^^^
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
$ pip install -e .[binary]
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/build/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 -m build --sdist
$ twine upload --repository pyvips dist/*
$ git tag -a v3.0.0 -m "as uploaded to pypi"
$ git push origin v3.0.0
Raw data
{
"_id": null,
"home_page": null,
"name": "pmipyvips",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "image processing",
"author": null,
"author_email": "John Cupitt <jcupitt@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/47/97/4e25be7e729c340213f8b13b5a7f8db2ae78588757fd72730b0099003eec/pmipyvips-3.0.0.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://www.libvips.org/\n\nThe libvips docs are also very useful:\n\nhttps://www.libvips.org/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 if\nAPI mode is being used with:\n\n.. code-block:: python\n\n import pyvips\n\n print(pyvips.API_mode)\n\nThis binding passes the vips test suite cleanly and with no leaks under\npython3 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\nhttps://www.libvips.org/API/current/How-it-opens-files.html\n\nBinary installation\n-------------------\n\nThe quickest way to start with pyvips is by installing the binary package\nwith:\n\n.. code-block:: shell\n\n $ pip install \"pyvips[binary]\"\n\nThis installs a self-contained package with the most commonly needed\nlibraries. It should just work on most common platforms, including Linux,\nWindows and macOS, with x64 and ARM CPUs.\n\nIf your platform is unsupported or the pre-built binary is\nunsuitable, you can install libvips separately instead.\n\nLocal installation\n------------------\n\nYou need the libvips shared library on your library search path, version 8.2\nor later, though at least version 8.9 is required for all features to work.\nSee:\n\nhttps://www.libvips.org/install.html\n\nLinux\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\n^^^^^\n\nWith Homebrew:\n\n.. code-block:: shell\n\n $ brew install vips python pkg-config\n $ pip install pyvips\n\nWindows\n^^^^^^^\n\nOn Windows, you can download a pre-compiled binary from the libvips website.\n\nhttps://www.libvips.org/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.16\\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.16\\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\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 $ pip install -e .[binary]\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/build/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 -m build --sdist\n $ twine upload --repository pyvips dist/*\n $ git tag -a v3.0.0 -m \"as uploaded to pypi\"\n $ git push origin v3.0.0\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "binding for the libvips image processing library",
"version": "3.0.0",
"project_urls": {
"changelog": "https://github.com/boussaffawalid/pyvips/blob/master/CHANGELOG.rst",
"documentation": "https://libvips.github.io/pyvips/",
"funding": "https://opencollective.com/libvips",
"homepage": "https://github.com/boussaffawalid/pyvips",
"issues": "https://github.com/boussaffawalid/pyvips/issues",
"source": "https://github.com/boussaffawalid/pyvips"
},
"split_keywords": [
"image",
"processing"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "47974e25be7e729c340213f8b13b5a7f8db2ae78588757fd72730b0099003eec",
"md5": "f4bf1940fd14b8a82841041291dced16",
"sha256": "5f3bdb866e69324bb45ce26f4d63eac148f842eee4e4f0001184d0f57c790756"
},
"downloads": -1,
"filename": "pmipyvips-3.0.0.tar.gz",
"has_sig": false,
"md5_digest": "f4bf1940fd14b8a82841041291dced16",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 52956,
"upload_time": "2025-08-27T13:41:09",
"upload_time_iso_8601": "2025-08-27T13:41:09.443622Z",
"url": "https://files.pythonhosted.org/packages/47/97/4e25be7e729c340213f8b13b5a7f8db2ae78588757fd72730b0099003eec/pmipyvips-3.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-27 13:41:09",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "boussaffawalid",
"github_project": "pyvips",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "pmipyvips"
}
