pyvips: Python binding for libvips

Warnings

• breaking The `libvips` shared library is a mandatory external dependency. If not installed on your system, `pyvips` will fail to import with an `OSError` or `ModuleNotFoundError` for `_libvips`.
  Fix: Install `libvips` system-wide (e.g., `apt install libvips-dev` on Debian/Ubuntu, `brew install vips` on macOS). On Windows, download a pre-compiled binary and add its `bin` directory to your system's `PATH` environment variable, or use `pip install "pyvips[binary]"` for a self-contained (but feature-limited) installation.
• gotcha Using `pip install "pyvips[binary]"` installs a self-contained `libvips` binary that may lack support for certain features like PDF loading, OpenSlide (for whole-slide images), or specific image formats. If you need these, a system-wide installation of `libvips` with full feature support is necessary.
  Fix: For full `libvips` features, install `libvips` separately through your system's package manager or from source, ensuring it includes desired optional dependencies, and then install `pyvips` without the `[binary]` extra (`pip install pyvips`).
• breaking Since `libvips` version 8.9, modifying metadata on 'shared' images (those with a reference count greater than one) is blocked to prevent race conditions. Attempts to do so will be ignored or raise a warning.
  Fix: Always call `.copy()` on an `Image` object before attempting to modify its metadata if there's a possibility it's being shared, e.g., `new_image = original_image.copy().set('field', value)`.
• gotcha Operations that draw directly onto an image, such as `Image.draw_circle()` or `Image.draw_line()`, inherently modify their input. `pyvips` will make a private copy of the image in memory before performing these operations to prevent crashes. Repeated drawing can thus be inefficient due to multiple memory copies.
  Fix: For complex drawing tasks, consider combining drawing elements into an overlay image and using `image.composite()` or equivalent methods to merge them efficiently, or perform drawing operations on a temporary image if performance is critical.
• gotcha If `cffi` is unable to build a binary extension for `pyvips` (API mode), it will fall back to ABI mode, which results in approximately 20% slower execution and longer startup times.
  Fix: Ensure you have `libvips` development headers and a working C compiler (e.g., build-essential on Linux, Xcode Command Line Tools on macOS) installed before running `pip install pyvips`. If issues persist, try `pip install --no-cache-dir pyvips` to force a clean build attempt.
• gotcha When processing extremely large images, errors like 'arithmetic overflow' can occur, often stemming from underlying `libvips` components (e.g., `libpng`) if a 32-bit `libvips` build is in use. This limits the maximum image size that can be handled.
  Fix: Ensure you are using a 64-bit Python installation and a 64-bit build of `libvips`. Verify `libvips` was compiled with support for large file sizes if you frequently encounter such issues.

Install

• pip install pyvips Standard installation (requires system libvips)
• pip install "pyvips[binary]" Installation with pre-built libvips (may lack features)

Imports

• Image

  import pyvips
  image = pyvips.Image.new_from_file(...)

Quickstart

This example loads an image, resizes it to 50% of its original dimensions, converts it to grayscale, and then saves it as a PNG file. It demonstrates the basic `new_from_file`, chained operations, and `write_to_file` methods. A dummy 'input.jpg' is created if not found for immediate execution.

import pyvips
import os

# Assuming 'input.jpg' exists in the current directory
# For demonstration, let's create a dummy image if not present
if not os.path.exists('input.jpg'):
    # In a real scenario, you'd have an actual image file.
    # For this quickstart, we'll create a simple black image.
    dummy_image = pyvips.Image.black(100, 100, bands=3)
    dummy_image.write_to_file('input.jpg')

# Load an image
image = pyvips.Image.new_from_file('input.jpg')

# Perform an operation, e.g., resize to 50% and convert to grayscale
processed_image = image.resize(0.5).colourspace('b-w')

# Save the processed image
processed_image.write_to_file('output_grayscale.png')

print(f"Processed image saved to output_grayscale.png (width: {processed_image.width}, height: {processed_image.height})")