tessl/pypi-pyvips

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

—

Pending

Overview

Eval results

Files

Image Operations

Name: tessl/pypi-pyvips
Author: tessl

Comprehensive image processing operations including geometric transformations, filtering, color manipulation, and advanced effects. All operations support method chaining and return new Image objects, enabling efficient pipeline construction.

Capabilities

Geometric Transformations

Resize, rotate, and transform images with high-quality resampling and flexible options.

def resize(self, scale: float, **kwargs) -> 'Image':
    """
    Resize image by scale factor.
    
    Parameters:
    - scale: float, scale factor (0.5 = half size, 2.0 = double size)
    - vscale: float, vertical scale factor (defaults to scale)
    - kernel: str, resampling kernel ('nearest', 'linear', 'cubic', 'mitchell', 'lanczos2', 'lanczos3')
    - centre: bool, center the image
    - gap: float, gap between tiles
    
    Returns:
    Resized Image object
    """

def rotate(self, angle: float, **kwargs) -> 'Image':
    """
    Rotate image by arbitrary angle.
    
    Parameters:
    - angle: float, rotation angle in degrees
    - interpolate: Interpolate, interpolation method
    - background: list, background color for exposed areas
    - odx: float, horizontal output displacement
    - ody: float, vertical output displacement
    - idx: float, horizontal input displacement  
    - idy: float, vertical input displacement
    
    Returns:
    Rotated Image object
    """

def affine(self, matrix: list, **kwargs) -> 'Image':
    """
    Apply affine transformation.
    
    Parameters:
    - matrix: list, 2x2 transformation matrix [a, b, c, d]
    - interpolate: Interpolate, interpolation method
    - oarea: list, output area [left, top, width, height]
    - odx: float, horizontal output displacement
    - ody: float, vertical output displacement
    - idx: float, horizontal input displacement
    - idy: float, vertical input displacement
    - background: list, background color
    - premultiplied: bool, images have premultiplied alpha
    - extend: str, edge extension method
    
    Returns:
    Transformed Image object
    """

def similarity(self, **kwargs) -> 'Image':
    """
    Apply similarity transformation (scale + rotate + translate).
    
    Parameters:
    - scale: float, scale factor
    - angle: float, rotation angle in degrees
    - dx: float, horizontal translation
    - dy: float, vertical translation
    - interpolate: Interpolate, interpolation method
    - background: list, background color
    - odx: float, horizontal output displacement
    - ody: float, vertical output displacement
    - idx: float, horizontal input displacement
    - idy: float, vertical input displacement
    
    Returns:
    Transformed Image object
    """

Example usage:

# Basic resize
small = image.resize(0.5)
large = image.resize(2.0, kernel='lanczos3')

# Resize with different vertical scale
stretched = image.resize(1.0, vscale=0.5)

# Rotation
rotated = image.rotate(45, background=[255, 255, 255])

# Affine transformation (shear)
sheared = image.affine([1, 0.5, 0, 1])

# Combined scale and rotate
transformed = image.similarity(scale=0.8, angle=30, dx=10, dy=20)

Image Filtering

Apply various filters for blur, sharpening, noise reduction, and artistic effects.

def gaussblur(self, sigma: float, **kwargs) -> 'Image':
    """
    Gaussian blur filter.
    
    Parameters:
    - sigma: float, blur radius in pixels
    - min_ampl: float, minimum amplitude (default 0.2)
    - precision: str, computation precision ('integer', 'float', 'approximate')
    
    Returns:
    Blurred Image object
    """

def sharpen(self, **kwargs) -> 'Image':
    """
    Sharpen image with unsharp mask.
    
    Parameters:
    - radius: float, sharpening radius (default 1.0)
    - amount: float, sharpening amount (default 1.0) 
    - threshold: float, threshold for sharpening (default 0.05)
    - x1: float, flat area sharpening
    - y2: float, sharpening in flat areas
    - m1: float, sharpening slope 1
    - m2: float, sharpening slope 2
    
    Returns:
    Sharpened Image object
    """

def conv(self, mask: 'Image', **kwargs) -> 'Image':
    """
    Convolution with custom kernel.
    
    Parameters:
    - mask: Image, convolution kernel/mask
    - precision: str, computation precision
    - layers: int, number of layers in mask
    - cluster: int, cluster mask elements
    
    Returns:
    Convolved Image object
    """

def median(self, size: int) -> 'Image':
    """
    Median filter for noise reduction.
    
    Parameters:
    - size: int, filter size (must be odd)
    
    Returns:
    Filtered Image object
    """

Example usage:

# Gaussian blur
blurred = image.gaussblur(2.0)
soft_blur = image.gaussblur(5.0, precision='approximate')

# Sharpening
sharp = image.sharpen()
very_sharp = image.sharpen(radius=2.0, amount=2.0)

# Custom convolution kernel
kernel = pyvips.Image.new_from_array([
    [-1, -1, -1],
    [-1,  8, -1], 
    [-1, -1, -1]
])
edge_detected = image.conv(kernel)

# Noise reduction
denoised = image.median(3)

Color and Tone Operations

Color space conversions, tone adjustments, and color manipulation operations.

def colourspace(self, space: str, **kwargs) -> 'Image':
    """
    Convert to different color space.
    
    Parameters:
    - space: str, target color space ('srgb', 'rgb', 'cmyk', 'lab', 'xyz', 'grey16', etc.)
    - source_space: str, source color space (auto-detected if not specified)
    
    Returns:
    Converted Image object
    """

def icc_import(self, **kwargs) -> 'Image':
    """
    Import from ICC profile.
    
    Parameters:
    - input_profile: str, input profile filename
    - pcs: str, profile connection space ('lab', 'xyz')
    - intent: str, rendering intent ('perceptual', 'relative', 'saturation', 'absolute')
    - black_point_compensation: bool, use black point compensation
    - embedded: bool, use embedded profile
    
    Returns:
    Color-corrected Image object
    """

def icc_export(self, **kwargs) -> 'Image':
    """
    Export with ICC profile.
    
    Parameters:
    - output_profile: str, output profile filename
    - pcs: str, profile connection space
    - intent: str, rendering intent
    - black_point_compensation: bool, use black point compensation
    - depth: int, output bit depth
    
    Returns:
    Exported Image object
    """

def linear(self, a: list, b: list) -> 'Image':
    """
    Apply linear transformation: out = a * in + b
    
    Parameters:
    - a: list, multiplication coefficients per band
    - b: list, addition coefficients per band
    
    Returns:
    Transformed Image object
    """

def gamma(self, **kwargs) -> 'Image':
    """
    Apply gamma correction.
    
    Parameters:
    - gamma: float, gamma value (default 2.4)
    - exponent: float, exponent for gamma curve
    
    Returns:
    Gamma-corrected Image object
    """

Example usage:

# Color space conversion
srgb = image.colourspace('srgb')
cmyk = image.colourspace('cmyk')
grayscale = image.colourspace('grey16')

# ICC profile handling
corrected = image.icc_import(input_profile='input.icc')
ready_for_print = corrected.icc_export(output_profile='printer.icc')

# Linear tone adjustment
brightened = image.linear([1.2, 1.2, 1.2], [10, 10, 10])

# Gamma correction
gamma_corrected = image.gamma(gamma=2.2)

Size and Cropping

Thumbnail generation, cropping, and smart resizing operations.

def thumbnail_image(self, width: int, **kwargs) -> 'Image':
    """
    Generate thumbnail maintaining aspect ratio.
    
    Parameters:
    - width: int, maximum width in pixels
    - height: int, maximum height in pixels (defaults to width)
    - size: str, sizing behavior ('both', 'up', 'down', 'force')
    - no_rotate: bool, don't auto-rotate using EXIF
    - crop: str, crop mode ('none', 'centre', 'attention', 'entropy', 'smart')
    - linear: bool, reduce in linear light
    - import_profile: str, fallback import profile
    - export_profile: str, export profile
    - intent: str, rendering intent
    
    Returns:
    Thumbnail Image object
    """

def crop(self, left: int, top: int, width: int, height: int) -> 'Image':
    """
    Crop rectangular area from image.
    
    Parameters:
    - left: int, left edge of crop area
    - top: int, top edge of crop area  
    - width: int, width of crop area
    - height: int, height of crop area
    
    Returns:
    Cropped Image object
    """

def smartcrop(self, width: int, height: int, **kwargs) -> 'Image':
    """
    Smart crop using attention or entropy.
    
    Parameters:
    - width: int, target width
    - height: int, target height
    - interesting: str, area selection method ('none', 'centre', 'entropy', 'attention')
    - premultiplied: bool, images have premultiplied alpha
    
    Returns:
    Smart-cropped Image object
    """

Example usage:

# Thumbnail with max width
thumb = image.thumbnail_image(200)

# Thumbnail with max dimensions
thumb = image.thumbnail_image(200, height=150)

# Smart thumbnail with cropping
thumb = image.thumbnail_image(200, crop='attention')

# Basic crop
cropped = image.crop(100, 100, 400, 300)

# Smart crop using entropy
smart = image.smartcrop(300, 200, interesting='entropy')

Arithmetic and Logical Operations

Mathematical operations between images and with constants.

def add(self, other) -> 'Image':
    """Add another image or constant."""

def subtract(self, other) -> 'Image':
    """Subtract another image or constant."""

def multiply(self, other) -> 'Image':  
    """Multiply by another image or constant."""

def divide(self, other) -> 'Image':
    """Divide by another image or constant."""

def remainder(self, other) -> 'Image':
    """Remainder after division."""

def relational(self, other, operation: str) -> 'Image':
    """
    Relational operation with image or constant.
    
    Parameters:
    - other: Image or constant
    - operation: str, comparison ('equal', 'noteq', 'less', 'lesseq', 'more', 'moreeq')
    
    Returns:
    Binary mask Image
    """

def boolean(self, other, operation: str) -> 'Image':
    """
    Boolean operation with image or constant.
    
    Parameters:
    - other: Image or constant  
    - operation: str, boolean op ('and', 'or', 'eor', 'lshift', 'rshift')
    
    Returns:
    Result Image
    """

Example usage:

# Arithmetic with constants
brightened = image + 50
darkened = image - 30
scaled = image * 1.2
normalized = image / 255.0

# Arithmetic with other images
combined = image1 + image2
difference = image1 - image2
blended = image1 * 0.7 + image2 * 0.3

# Logical operations
mask = image > 128
result = image.boolean(mask, 'and')

# Comparisons
equal_mask = image1.relational(image2, 'equal')

Operation Chaining

All operations return new Image objects, enabling efficient method chaining:

# Chain multiple operations
result = (image
    .resize(0.8)
    .rotate(45)
    .gaussblur(1.0)
    .sharpen(radius=1.5)
    .colourspace('srgb')
    .linear([1.1, 1.1, 1.1], [0, 0, 0]))

# Complex processing pipeline
processed = (pyvips.Image.new_from_file('input.jpg')
    .thumbnail_image(800, crop='attention')
    .icc_import()
    .gaussblur(0.5)
    .sharpen()
    .gamma(gamma=2.2)
    .colourspace('srgb')
    .linear([1.05, 1.0, 0.95], [5, 0, -5]))