tessl/pypi-pyvips

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

—

Pending

Overview

Eval results

Files

Image Creation

Name: tessl/pypi-pyvips
Author: tessl

Methods for creating Image objects from various sources including files, memory buffers, arrays, and custom sources. PyVips supports all major image formats and provides flexible initialization options for different use cases.

Capabilities

File Loading

Load images from filesystem paths with automatic format detection and extensive format-specific options.

@classmethod
def new_from_file(cls, vips_filename: str, **kwargs) -> 'Image':
    """
    Load an image from a file.
    
    Parameters:
    - vips_filename: str, file path to load
    - access: str, access pattern ('random', 'sequential', 'sequential_unbuffered')  
    - fail_on: str, error level ('none', 'truncated', 'error', 'warning')
    - disc: bool, force disk-based processing
    - Format-specific options like 'page' for multi-page formats, 'dpi' for PDF, etc.
    
    Returns:
    Image object
    """

Example usage:

# Basic file loading
image = pyvips.Image.new_from_file('photo.jpg')

# Load with sequential access for large files
image = pyvips.Image.new_from_file('large.tiff', access='sequential')

# Load specific page from multi-page format
image = pyvips.Image.new_from_file('document.pdf', page=2, dpi=300)

# Load with error handling control
image = pyvips.Image.new_from_file('input.jpg', fail_on='warning')

Buffer Loading

Load images from memory buffers, useful for processing images received from network requests or other in-memory sources.

@classmethod  
def new_from_buffer(cls, data: bytes, options: str, **kwargs) -> 'Image':
    """
    Load an image from a memory buffer.
    
    Parameters:
    - data: bytes, image data in memory
    - options: str, format hint (empty string for auto-detection)
    - Same keyword arguments as new_from_file
    
    Returns:
    Image object
    """

Example usage:

# Load from HTTP response
import requests
response = requests.get('https://example.com/image.jpg')
image = pyvips.Image.new_from_buffer(response.content, '')

# Load with format hint
with open('image.webp', 'rb') as f:
    data = f.read()
image = pyvips.Image.new_from_buffer(data, '.webp')

# Load with specific options
image = pyvips.Image.new_from_buffer(jpeg_data, '.jpg', shrink=2)

Array Creation

Create images from Python lists and arrays, enabling programmatic image generation and integration with numerical data.

@classmethod
def new_from_array(cls, array, scale: float = 1.0, offset: float = 0.0, 
                   interpretation: str = None) -> 'Image':
    """
    Create an image from a 2D array.
    
    Parameters:
    - array: 2D list/array of numbers, image pixel data
    - scale: float, scale factor applied to pixel values
    - offset: float, offset added to pixel values  
    - interpretation: str, color space interpretation
    
    Returns:
    Image object
    """

@classmethod
def new_from_list(cls, array: list, scale: float = 1.0, 
                  offset: float = 0.0) -> 'Image':
    """
    Create an image from a Python list.
    
    Parameters:
    - array: 2D list of numbers
    - scale: float, scale factor
    - offset: float, offset value
    
    Returns:
    Image object
    """

Example usage:

# Create from 2D list
pixel_data = [
    [255, 128, 0],
    [128, 255, 128], 
    [0, 128, 255]
]
image = pyvips.Image.new_from_array(pixel_data)

# Create with scaling
kernel = [
    [-1, -1, -1],
    [-1,  8, -1],
    [-1, -1, -1]
]
sharpen_kernel = pyvips.Image.new_from_array(kernel, scale=1, offset=0)

# Create with color space
rgb_data = [[255, 0, 0], [0, 255, 0], [0, 0, 255]]
image = pyvips.Image.new_from_array(rgb_data, interpretation='srgb')

Raw Memory Creation

Create images from raw pixel data in memory, useful for interfacing with other image processing libraries or hardware.

@classmethod
def new_from_memory(cls, data: bytes, width: int, height: int, 
                    bands: int, format: str) -> 'Image':
    """
    Create an image from raw memory data.
    
    Parameters:
    - data: bytes, raw pixel data
    - width: int, image width in pixels
    - height: int, image height in pixels  
    - bands: int, number of bands (channels)
    - format: str, pixel format ('uchar', 'ushort', 'float', etc.)
    
    Returns:
    Image object
    """

Example usage:

# Create from raw RGB data
width, height = 100, 100
bands = 3
pixel_data = bytes([255, 0, 0] * (width * height))  # Red image
image = pyvips.Image.new_from_memory(pixel_data, width, height, bands, 'uchar')

# Create from float data  
import struct
float_data = struct.pack('f' * (width * height), *([0.5] * (width * height)))
image = pyvips.Image.new_from_memory(float_data, width, height, 1, 'float')

Source-based Loading

Load images from Source objects for advanced I/O scenarios and streaming operations.

@classmethod
def new_from_source(cls, source: 'Source', options: str, **kwargs) -> 'Image':
    """
    Load an image from a Source object.
    
    Parameters:
    - source: Source object providing the image data
    - options: str, format hint
    - Same keyword arguments as new_from_file
    
    Returns:
    Image object
    """

Example usage:

# Load from file source
source = pyvips.Source.new_from_file('image.jpg')
image = pyvips.Image.new_from_source(source, '')

# Load from memory source
data = open('image.png', 'rb').read()  
source = pyvips.Source.new_from_memory(data)
image = pyvips.Image.new_from_source(source, '.png')

# Load from custom source
custom_source = pyvips.SourceCustom()
custom_source.on_read(my_read_handler)
image = pyvips.Image.new_from_source(custom_source, '')

Temporary File Creation

Create temporary image files for intermediate processing steps.

@classmethod
def new_temp_file(cls, format: str) -> 'Image':
    """
    Create a temporary file image.
    
    Parameters:
    - format: str, file format suffix (e.g., '.jpg', '.png')
    
    Returns:
    Image object representing temporary file
    """

Example usage:

# Create temporary JPEG
temp_image = pyvips.Image.new_temp_file('.jpg')

# Use for intermediate processing
large_image = pyvips.Image.new_from_file('huge.tiff')
temp = large_image.thumbnail_image(1000).new_temp_file('.jpg')
result = temp.gaussblur(2.0)

Format Support

PyVips automatically detects formats and supports extensive format-specific options:

Common Formats

JPEG: quality, optimize, strip, etc.
PNG: compression, palette, etc.
TIFF: compression, tile, pyramid, etc.
WebP: quality, lossless, alpha_q, etc.
HEIF/AVIF: quality, compression, speed, etc.

Specialized Formats

OpenSlide: Multi-resolution microscopy images
OpenEXR: High dynamic range images
FITS: Astronomical images
Matlab: .mat files
Raw formats: Various camera raw formats

Multi-page Support

PDF: page, dpi, background
TIFF: page, n (number of pages)
GIF: page, n
WebP: page, n

Error Handling

Image creation operations can fail for various reasons:

try:
    image = pyvips.Image.new_from_file('nonexistent.jpg')
except pyvips.Error as e:
    print(f"Failed to load image: {e.message}")
    print(f"Details: {e.details}")

# Check file existence first
import os
if os.path.exists(filename):
    image = pyvips.Image.new_from_file(filename)
else:
    print("File not found")

Install with Tessl CLI