tessl/pypi-pyvips

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

—

Pending

Overview

Eval results

Files

Enumerations

Name: tessl/pypi-pyvips
Author: tessl

Comprehensive set of enumeration classes defining constants for all image processing operations, formats, and options. These enumerations provide type-safe string constants for configuring PyVips operations and ensure compatibility with the underlying libvips library.

Capabilities

Core Image Properties

Fundamental enumerations that define image characteristics and data representation.

class BandFormat:
    """Pixel format for each band element."""
    NOTSET: str      # Invalid setting
    UCHAR: str       # Unsigned char (8-bit) - 0 to 255
    CHAR: str        # Signed char (8-bit) - -128 to 127
    USHORT: str      # Unsigned short (16-bit) - 0 to 65535
    SHORT: str       # Signed short (16-bit) - -32768 to 32767
    UINT: str        # Unsigned int (32-bit)
    INT: str         # Signed int (32-bit)
    FLOAT: str       # Float (32-bit)
    COMPLEX: str     # Complex (two 32-bit floats)
    DOUBLE: str      # Double (64-bit)
    DPCOMPLEX: str   # Double complex (two 64-bit floats)

class Interpretation:
    """Color space and meaning of image bands."""
    MULTIBAND: str   # Generic multi-band image
    B_W: str         # Single band black and white
    HISTOGRAM: str   # Histogram data
    XYZ: str         # CIE XYZ color space
    LAB: str         # CIE LAB color space
    CMYK: str        # CMYK color space
    LABQ: str        # LAB with alpha, quantized
    RGB: str         # RGB color space
    CMC: str         # CMC color space
    LCH: str         # LCH color space
    LABS: str        # LAB signed
    SRGB: str        # sRGB color space
    YXY: str         # Yxy color space
    FOURIER: str     # Fourier transform
    RGB16: str       # 16-bit RGB
    GREY16: str      # 16-bit grayscale
    MATRIX: str      # Matrix data
    SCRGB: str       # scRGB color space
    HSV: str         # HSV color space

class Coding:
    """Pixel coding methods."""
    NONE: str        # No coding
    LABQ: str        # LAB quantized coding
    RAD: str         # Radiance coding

Example usage:

# Check image format
if image.format == pyvips.BandFormat.UCHAR:
    print("8-bit unsigned image")
elif image.format == pyvips.BandFormat.FLOAT:
    print("32-bit floating point image")

# Set specific format when creating images
array_data = [[255, 128, 0], [128, 255, 128]]
image = pyvips.Image.new_from_array(array_data)
# Convert to specific format
float_image = image.cast(pyvips.BandFormat.FLOAT)

# Check color space
if image.interpretation == pyvips.Interpretation.SRGB:
    print("sRGB color space")
elif image.interpretation == pyvips.Interpretation.CMYK:
    print("CMYK color space")

# Convert color spaces
srgb_image = image.colourspace(pyvips.Interpretation.SRGB)
lab_image = image.colourspace(pyvips.Interpretation.LAB)

Geometric and Layout Options

Enumerations for image positioning, alignment, and geometric transformations.

class CompassDirection:
    """Compass directions for positioning."""
    CENTRE: str      # Center position
    NORTH: str       # Top center
    EAST: str        # Right center
    SOUTH: str       # Bottom center
    WEST: str        # Left center
    NORTH_EAST: str  # Top right
    SOUTH_EAST: str  # Bottom right
    SOUTH_WEST: str  # Bottom left
    NORTH_WEST: str  # Top left

class Direction:
    """Basic directional orientations."""
    HORIZONTAL: str  # Horizontal direction
    VERTICAL: str    # Vertical direction

class Align:
    """Alignment options."""
    LOW: str         # Align to low edge
    CENTRE: str      # Center alignment
    HIGH: str        # Align to high edge

class Angle:
    """Fixed rotation angles."""
    D0: str          # 0 degrees
    D90: str         # 90 degrees clockwise
    D180: str        # 180 degrees
    D270: str        # 270 degrees clockwise (90 CCW)

class Angle45:
    """45-degree increment angles."""
    D0: str          # 0 degrees
    D45: str         # 45 degrees
    D90: str         # 90 degrees
    D135: str        # 135 degrees
    D180: str        # 180 degrees
    D225: str        # 225 degrees
    D270: str        # 270 degrees
    D315: str        # 315 degrees

Example usage:

# Image positioning
positioned = image.gravity(pyvips.CompassDirection.NORTH_EAST, 800, 600)

# Rotation by fixed angles
rotated_90 = image.rot(pyvips.Angle.D90)
rotated_180 = image.rot(pyvips.Angle.D180)

# 45-degree rotations
diagonal = image.rot45(pyvips.Angle45.D45)

# Alignment in operations
aligned = image.embed(10, 10, 800, 600, extend=pyvips.Extend.COPY)

Processing Options

Enumerations for controlling image processing behavior and quality.

class Access:
    """Memory access patterns."""
    RANDOM: str                    # Random access
    SEQUENTIAL: str                # Sequential access
    SEQUENTIAL_UNBUFFERED: str     # Sequential without buffering

class Extend:
    """Edge extension methods."""
    BLACK: str       # Extend with black pixels
    COPY: str        # Copy edge pixels
    REPEAT: str      # Repeat image
    MIRROR: str      # Mirror image
    WHITE: str       # Extend with white pixels
    BACKGROUND: str  # Use background color

class Precision:
    """Computation precision levels."""
    INTEGER: str     # Integer precision
    FLOAT: str       # Floating point precision
    APPROXIMATE: str # Approximate (faster) precision

class Size:
    """Sizing behavior for operations."""
    BOTH: str        # Size both dimensions
    UP: str          # Only size up
    DOWN: str        # Only size down
    FORCE: str       # Force exact size

class Interesting:
    """Interest detection algorithms."""
    NONE: str        # No interest detection
    CENTRE: str      # Use center
    ENTROPY: str     # Use entropy (edge detection)
    ATTENTION: str   # Use attention algorithm
    LOW: str         # Favor low values
    HIGH: str        # Favor high values
    ALL: str         # Use all algorithms

Example usage:

# File loading with access pattern
large_image = pyvips.Image.new_from_file('huge.tiff', 
    access=pyvips.Access.SEQUENTIAL)

# Edge extension for operations
padded = image.embed(10, 10, 800, 600, 
    extend=pyvips.Extend.MIRROR)

# Precision control for performance
fast_blur = image.gaussblur(2.0, 
    precision=pyvips.Precision.APPROXIMATE)

# Smart cropping with interest detection
smart_crop = image.smartcrop(300, 200, 
    interesting=pyvips.Interesting.ATTENTION)

# Thumbnail sizing behavior
thumb_up_only = image.thumbnail_image(800, 
    size=pyvips.Size.UP)

Arithmetic and Logical Operations

Enumerations for mathematical and logical operations between images.

class OperationRelational:
    """Relational comparison operations."""
    EQUAL: str       # Equal to
    NOTEQ: str       # Not equal to
    LESS: str        # Less than
    LESSEQ: str      # Less than or equal
    MORE: str        # Greater than
    MOREEQ: str      # Greater than or equal

class OperationBoolean:
    """Boolean bitwise operations."""
    AND: str         # Bitwise AND
    OR: str          # Bitwise OR
    EOR: str         # Bitwise XOR (exclusive OR)
    LSHIFT: str      # Left bit shift
    RSHIFT: str      # Right bit shift

class OperationMath2:
    """Two-argument mathematical operations."""
    POW: str         # Power (x^y)
    WOP: str         # Complex multiply
    ATAN2: str       # Two-argument arctangent

class OperationMath:
    """Single-argument mathematical functions."""
    SIN: str         # Sine
    COS: str         # Cosine
    TAN: str         # Tangent
    ASIN: str        # Arcsine
    ACOS: str        # Arccosine
    ATAN: str        # Arctangent
    LOG: str         # Natural logarithm
    LOG10: str       # Base-10 logarithm
    EXP: str         # Exponential (e^x)
    EXP10: str       # Base-10 exponential
    SINH: str        # Hyperbolic sine
    COSH: str        # Hyperbolic cosine
    TANH: str        # Hyperbolic tangent

class OperationRound:
    """Rounding operations."""
    RINT: str        # Round to nearest integer
    CEIL: str        # Round up (ceiling)
    FLOOR: str       # Round down (floor)

Example usage:

# Relational operations
mask = image.relational(128, pyvips.OperationRelational.MORE)
equal_pixels = image1.relational(image2, pyvips.OperationRelational.EQUAL)

# Boolean operations
combined = image1.boolean(image2, pyvips.OperationBoolean.AND)
shifted = image.boolean(2, pyvips.OperationBoolean.LSHIFT)

# Mathematical functions
sine_wave = image.math(pyvips.OperationMath.SIN)
logarithmic = image.math(pyvips.OperationMath.LOG)

# Two-argument math
power_image = image1.math2(image2, pyvips.OperationMath2.POW)

# Rounding
rounded = float_image.round(pyvips.OperationRound.RINT)
ceiling = float_image.round(pyvips.OperationRound.CEIL)

Complex Number Operations

Enumerations for complex number processing and transformations.

class OperationComplex:
    """Complex number operations."""
    POLAR: str       # Convert to polar form
    RECT: str        # Convert to rectangular form
    CONJ: str        # Complex conjugate

class OperationComplexget:
    """Extract components from complex numbers."""
    REAL: str        # Real component
    IMAG: str        # Imaginary component

class OperationComplex2:
    """Two-argument complex operations."""
    CROSS_PHASE: str # Cross phase

Example usage:

# Complex number operations (for FFT results, etc.)
polar_form = complex_image.complex(pyvips.OperationComplex.POLAR)
conjugate = complex_image.complex(pyvips.OperationComplex.CONJ)

# Extract components
real_part = complex_image.complexget(pyvips.OperationComplexget.REAL)
imag_part = complex_image.complexget(pyvips.OperationComplexget.IMAG)

Resampling and Interpolation

Enumerations for image resampling kernels and interpolation methods.

class Kernel:
    """Resampling kernels for resize operations."""
    NEAREST: str     # Nearest neighbor (fastest, blocky)
    LINEAR: str      # Linear interpolation (fast)
    CUBIC: str       # Cubic interpolation (good quality)
    MITCHELL: str    # Mitchell filter (balanced)
    LANCZOS2: str    # Lanczos 2-tap (sharp)
    LANCZOS3: str    # Lanczos 3-tap (very sharp)

Example usage:

# Different resampling quality levels
fast_resize = image.resize(0.5, kernel=pyvips.Kernel.LINEAR)
quality_resize = image.resize(0.5, kernel=pyvips.Kernel.LANCZOS3)
pixelated = image.resize(2.0, kernel=pyvips.Kernel.NEAREST)

# Create interpolator objects
linear_interp = pyvips.Interpolate.new(pyvips.Kernel.LINEAR)
bicubic_interp = pyvips.Interpolate.new(pyvips.Kernel.CUBIC)

Color Management

Enumerations for color profiles and rendering intents.

class Intent:
    """Color rendering intents for ICC profiles."""
    PERCEPTUAL: str  # Perceptual rendering
    RELATIVE: str    # Relative colorimetric
    SATURATION: str  # Saturation rendering
    ABSOLUTE: str    # Absolute colorimetric
    AUTO: str        # Automatic selection

class PCS:
    """Profile Connection Space."""
    LAB: str         # CIE LAB color space
    XYZ: str         # CIE XYZ color space

Example usage:

# ICC profile operations with rendering intent
imported = image.icc_import(
    intent=pyvips.Intent.PERCEPTUAL,
    pcs=pyvips.PCS.LAB)

exported = image.icc_export(
    output_profile='printer.icc',
    intent=pyvips.Intent.RELATIVE)

Format-Specific Options

Enumerations for various file format options and features.

class ForeignKeep:
    """Metadata preservation options."""
    NONE: str        # Keep no metadata
    EXIF: str        # Keep EXIF data
    XMP: str         # Keep XMP data
    IPTC: str        # Keep IPTC data
    ICC: str         # Keep ICC profile
    OTHER: str       # Keep other metadata
    ALL: str         # Keep all metadata

class FailOn:
    """Error handling levels."""
    NONE: str        # Don't fail on errors
    TRUNCATED: str   # Fail on truncated files
    ERROR: str       # Fail on errors
    WARNING: str     # Fail on warnings

class ForeignPngFilter:
    """PNG filtering options."""
    NONE: str        # No filtering
    SUB: str         # Sub filter
    UP: str          # Up filter
    AVG: str         # Average filter
    PAETH: str       # Paeth filter
    ALL: str         # All filters

Example usage:

# Metadata preservation
image.write_to_file('output.jpg', 
    keep=pyvips.ForeignKeep.EXIF | pyvips.ForeignKeep.ICC)

# Error handling
strict_image = pyvips.Image.new_from_file('image.jpg',
    fail_on=pyvips.FailOn.WARNING)

# PNG optimization
image.write_to_file('optimized.png',
    filter=pyvips.ForeignPngFilter.ALL,
    compression=9)

Morphological Operations

Enumerations for mathematical morphology operations.

class OperationMorphology:
    """Morphological operations."""
    ERODE: str       # Erosion operation
    DILATE: str      # Dilation operation

Example usage:

# Morphological operations with custom kernel
kernel = pyvips.Image.new_from_array([
    [1, 1, 1],
    [1, 1, 1], 
    [1, 1, 1]
])

eroded = image.morph(kernel, pyvips.OperationMorphology.ERODE)
dilated = image.morph(kernel, pyvips.OperationMorphology.DILATE)

Blend and Composite Operations

Enumerations for image blending and compositing modes.

class BlendMode:
    """Porter-Duff blend modes."""
    CLEAR: str       # Clear destination
    SOURCE: str      # Copy source
    OVER: str        # Source over destination
    IN: str          # Source in destination
    OUT: str         # Source out destination
    ATOP: str        # Source atop destination
    DEST: str        # Keep destination
    DEST_OVER: str   # Destination over source
    DEST_IN: str     # Destination in source
    DEST_OUT: str    # Destination out source
    DEST_ATOP: str   # Destination atop source
    XOR: str         # Exclusive or
    ADD: str         # Addition
    SATURATE: str    # Saturate
    MULTIPLY: str    # Multiply
    SCREEN: str      # Screen
    OVERLAY: str     # Overlay
    DARKEN: str      # Darken
    LIGHTEN: str     # Lighten
    COLOUR_DODGE: str # Color dodge
    COLOUR_BURN: str  # Color burn
    HARD_LIGHT: str   # Hard light
    SOFT_LIGHT: str   # Soft light
    DIFFERENCE: str   # Difference
    EXCLUSION: str    # Exclusion

class CombineMode:
    """Image combination modes."""
    SET: str         # Set (replace)
    ADD: str         # Add values

Example usage:

# Composite images with blend modes
composite = base_image.composite([overlay_image], 
    [pyvips.BlendMode.MULTIPLY])

# Multiple overlays with different blend modes
result = base_image.composite(
    [overlay1, overlay2, overlay3],
    [pyvips.BlendMode.OVERLAY, 
     pyvips.BlendMode.SOFT_LIGHT, 
     pyvips.BlendMode.SCREEN])

Usage Best Practices

Type Safety

# Use enums instead of strings for type safety
# Good
image.resize(0.5, kernel=pyvips.Kernel.LANCZOS3)
image.colourspace(pyvips.Interpretation.SRGB)

# Avoid raw strings (error-prone)
# image.resize(0.5, kernel='lanczos3')  # Risky - typos not caught

Feature Detection

# Check for enum availability based on libvips version
def safe_enum_use():
    """Use enums safely across different libvips versions."""
    
    # Some enums may not be available in older versions
    try:
        return pyvips.ForeignKeep.ALL
    except AttributeError:
        # Fallback for older versions
        return 'all'

# Version-specific enum usage
if pyvips.at_least_libvips(8, 10):
    keep_option = pyvips.ForeignKeep.ALL
else:
    keep_option = 'all'  # String fallback

Combining Flags

# Some enums can be combined with bitwise OR
metadata_flags = (pyvips.ForeignKeep.EXIF | 
                 pyvips.ForeignKeep.ICC |
                 pyvips.ForeignKeep.XMP)

image.write_to_file('output.jpg', keep=metadata_flags)

Install with Tessl CLI