or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

array-integration.md enumerations.md image-creation.md image-operations.md image-output.md index.md io-connections.md properties-metadata.md system-control.md

tile.json

tessl/pypi-pyvips

Python binding for the libvips image processing library with high-performance streaming architecture

Workspace: tessl
Visibility: Public
Created: 3 months ago
Last updated: 3 months ago
Describes: pkg:pypi/pyvips@3.0.x

To install, run

npx @tessl/cli install tessl/pypi-pyvips@3.0.0

PyVips

PyVips is a Python binding for the libvips image processing library that provides high-performance image manipulation capabilities through a streaming, pipeline-based architecture. It enables developers to perform complex image processing operations including format conversion, resizing, filtering, color space transformations, and advanced effects while maintaining memory efficiency by processing images in sections rather than loading them entirely into memory.

Package Information

Package Name: pyvips
Language: Python
Installation: pip install pyvips
Binary Mode: Automatically uses compiled binary extensions when available for maximum performance, falls back to ABI mode for broader compatibility

Core Imports

import pyvips

For most image operations, you'll primarily work with the Image class:

from pyvips import Image

Additional imports for specific functionality:

from pyvips import (
    Image, Source, Target, SourceCustom, TargetCustom,
    Error, Operation, Interpolate, Region
)

Basic Usage

import pyvips

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

# Basic operations - these return new Image objects  
resized = image.resize(0.5)  # Resize to 50%
rotated = image.rotate(90)   # Rotate 90 degrees
converted = image.colourspace('srgb')  # Convert color space

# Chain operations for efficiency
processed = (image
    .resize(0.5)
    .rotate(90) 
    .gaussblur(1.5)
    .sharpen())

# Save result
processed.write_to_file('output.jpg')

# Memory-efficient processing from buffer
data = open('input.jpg', 'rb').read()
image = pyvips.Image.new_from_buffer(data, '')
result = image.thumbnail_image(200)
output_data = result.write_to_buffer('.jpg', Q=95)

Architecture

PyVips implements a streaming, pipeline-based architecture that provides superior performance and memory efficiency:

Image Objects: Immutable image representations that describe processing pipelines rather than storing pixel data
Lazy Evaluation: Operations are queued and executed only when pixel data is actually needed
Streaming Processing: Images are processed in small tiles, keeping memory usage constant regardless of image size
Operation Pipeline: Each operation creates a new Image object representing the cumulative pipeline
Automatic Optimization: libvips automatically optimizes operation chains for maximum efficiency

This design enables processing of very large images (gigapixel+) with minimal memory usage while maintaining high performance through parallel processing and efficient caching.

Capabilities

Image Loading and Creation

Primary methods for creating Image objects from various sources including files, memory buffers, arrays, and custom sources. Supports all major image formats and provides flexible initialization options.

@classmethod
def new_from_file(cls, vips_filename: str, **kwargs) -> 'Image': ...

@classmethod  
def new_from_buffer(cls, data: bytes, options: str, **kwargs) -> 'Image': ...

@classmethod
def new_from_array(cls, array, scale: float = 1.0, offset: float = 0.0, 
                   interpretation: str = None) -> 'Image': ...

@classmethod
def new_from_memory(cls, data: bytes, width: int, height: int, 
                    bands: int, format: str) -> 'Image': ...

Image Creation

Image Operations and Processing

Comprehensive image processing operations including geometric transformations, filtering, color manipulation, and advanced effects. PyVips dynamically exposes hundreds of libvips operations as Image methods through metaclass magic. All operations support method chaining and return new Image objects.

def resize(self, scale: float, **kwargs) -> 'Image': ...
def rotate(self, angle: float, **kwargs) -> 'Image': ...
def gaussblur(self, sigma: float, **kwargs) -> 'Image': ...
def sharpen(self, **kwargs) -> 'Image': ...
def colourspace(self, space: str, **kwargs) -> 'Image': ...
def thumbnail_image(self, width: int, **kwargs) -> 'Image': ...

Image Operations

Image Output and Export

Methods for saving and exporting images to files, memory buffers, and custom targets. Supports all major output formats with extensive format-specific options.

def write_to_file(self, vips_filename: str, **kwargs) -> None: ...
def write_to_buffer(self, format_string: str, **kwargs) -> bytes: ...
def write_to_target(self, target: 'Target', format_string: str, **kwargs) -> None: ...
def write_to_memory(self) -> bytes: ...

Image Output

I/O Connections and Streaming

Advanced I/O system supporting custom sources and targets for streaming operations, enabling integration with various data sources and destinations beyond the filesystem.

class Source:
    @classmethod
    def new_from_file(cls, filename: str) -> 'Source': ...
    
    @classmethod  
    def new_from_memory(cls, data: bytes) -> 'Source': ...

class Target:
    @classmethod
    def new_to_file(cls, filename: str) -> 'Target': ...
    
    @classmethod
    def new_to_memory(cls) -> 'Target': ...

I/O Connections

Image Properties and Metadata

Access and manipulation of image properties, metadata, and introspection capabilities for understanding image characteristics and processing pipelines.

def get(self, name: str): ...
def set(self, name: str, value) -> None: ...
def get_fields(self) -> list: ...
def remove(self, name: str) -> None: ...

# Properties
@property
def width(self) -> int: ...

@property  
def height(self) -> int: ...

@property
def bands(self) -> int: ...

@property
def format(self) -> str: ...

Properties and Metadata

Array and NumPy Integration

Seamless integration with Python arrays and NumPy for data exchange, enabling easy interoperability with the scientific Python ecosystem.

def tolist(self) -> list: ...
def numpy(self, dtype=None): ...
def __array__(self, dtype=None): ...

@classmethod
def new_from_list(cls, array: list, scale: float = 1.0, 
                  offset: float = 0.0) -> 'Image': ...

Array Integration

Low-Level Operations and System Control

Advanced functionality for operation introspection, cache management, and low-level system control for fine-tuning performance and behavior.

class Operation:
    @classmethod
    def call(cls, operation_name: str, *args, **kwargs): ...
    
    @classmethod
    def generate_docstring(cls, operation_name: str) -> str: ...

def cache_set_max(mx: int) -> None: ...
def cache_set_max_mem(mx: int) -> None: ...
def version(flag: int) -> int: ...

System Control

Enumerations and Constants

Comprehensive set of enumeration classes defining constants for all image processing operations, formats, and options.

class BandFormat:
    UCHAR: str
    CHAR: str  
    USHORT: str
    SHORT: str
    UINT: str
    INT: str
    FLOAT: str
    COMPLEX: str
    DOUBLE: str
    DPCOMPLEX: str

class Interpretation:
    MULTIBAND: str
    B_W: str
    HISTOGRAM: str
    XYZ: str
    LAB: str
    CMYK: str
    RGB: str
    SRGB: str

Enumerations

Error Handling

class Error(Exception):
    """An error from vips."""
    message: str
    detail: str

PyVips operations can raise pyvips.Error exceptions. The error contains both a high-level message and detailed diagnostics from the underlying libvips library.

Types

class Image:
    """Main image class wrapping VipsImage."""
    
    width: int
    height: int  
    bands: int
    format: str
    interpretation: str
    xres: float
    yres: float
    
class Source:
    """Input connection for streaming."""
    
class Target:  
    """Output connection for streaming."""
    
class SourceCustom(Source):
    """Custom input source."""
    
class TargetCustom(Target):
    """Custom output target."""
    
class Operation:
    """libvips operation wrapper."""
    
class Interpolate:
    """Interpolation method."""
    
class Region:
    """Region of an image for pixel access."""