0
# Enumerations
1

2
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.
3

4
## Capabilities
5

6
### Core Image Properties
7

8
Fundamental enumerations that define image characteristics and data representation.
9

10
```python { .api }
11
class BandFormat:
12
    """Pixel format for each band element."""
13
    NOTSET: str      # Invalid setting
14
    UCHAR: str       # Unsigned char (8-bit) - 0 to 255
15
    CHAR: str        # Signed char (8-bit) - -128 to 127
16
    USHORT: str      # Unsigned short (16-bit) - 0 to 65535
17
    SHORT: str       # Signed short (16-bit) - -32768 to 32767
18
    UINT: str        # Unsigned int (32-bit)
19
    INT: str         # Signed int (32-bit)
20
    FLOAT: str       # Float (32-bit)
21
    COMPLEX: str     # Complex (two 32-bit floats)
22
    DOUBLE: str      # Double (64-bit)
23
    DPCOMPLEX: str   # Double complex (two 64-bit floats)
24

25
class Interpretation:
26
    """Color space and meaning of image bands."""
27
    MULTIBAND: str   # Generic multi-band image
28
    B_W: str         # Single band black and white
29
    HISTOGRAM: str   # Histogram data
30
    XYZ: str         # CIE XYZ color space
31
    LAB: str         # CIE LAB color space
32
    CMYK: str        # CMYK color space
33
    LABQ: str        # LAB with alpha, quantized
34
    RGB: str         # RGB color space
35
    CMC: str         # CMC color space
36
    LCH: str         # LCH color space
37
    LABS: str        # LAB signed
38
    SRGB: str        # sRGB color space
39
    YXY: str         # Yxy color space
40
    FOURIER: str     # Fourier transform
41
    RGB16: str       # 16-bit RGB
42
    GREY16: str      # 16-bit grayscale
43
    MATRIX: str      # Matrix data
44
    SCRGB: str       # scRGB color space
45
    HSV: str         # HSV color space
46

47
class Coding:
48
    """Pixel coding methods."""
49
    NONE: str        # No coding
50
    LABQ: str        # LAB quantized coding
51
    RAD: str         # Radiance coding
52
```
53

54
Example usage:
55

56
```python
57
# Check image format
58
if image.format == pyvips.BandFormat.UCHAR:
59
    print("8-bit unsigned image")
60
elif image.format == pyvips.BandFormat.FLOAT:
61
    print("32-bit floating point image")
62

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

69
# Check color space
70
if image.interpretation == pyvips.Interpretation.SRGB:
71
    print("sRGB color space")
72
elif image.interpretation == pyvips.Interpretation.CMYK:
73
    print("CMYK color space")
74

75
# Convert color spaces
76
srgb_image = image.colourspace(pyvips.Interpretation.SRGB)
77
lab_image = image.colourspace(pyvips.Interpretation.LAB)
78
```
79

80
### Geometric and Layout Options
81

82
Enumerations for image positioning, alignment, and geometric transformations.
83

84
```python { .api }
85
class CompassDirection:
86
    """Compass directions for positioning."""
87
    CENTRE: str      # Center position
88
    NORTH: str       # Top center
89
    EAST: str        # Right center
90
    SOUTH: str       # Bottom center
91
    WEST: str        # Left center
92
    NORTH_EAST: str  # Top right
93
    SOUTH_EAST: str  # Bottom right
94
    SOUTH_WEST: str  # Bottom left
95
    NORTH_WEST: str  # Top left
96

97
class Direction:
98
    """Basic directional orientations."""
99
    HORIZONTAL: str  # Horizontal direction
100
    VERTICAL: str    # Vertical direction
101

102
class Align:
103
    """Alignment options."""
104
    LOW: str         # Align to low edge
105
    CENTRE: str      # Center alignment
106
    HIGH: str        # Align to high edge
107

108
class Angle:
109
    """Fixed rotation angles."""
110
    D0: str          # 0 degrees
111
    D90: str         # 90 degrees clockwise
112
    D180: str        # 180 degrees
113
    D270: str        # 270 degrees clockwise (90 CCW)
114

115
class Angle45:
116
    """45-degree increment angles."""
117
    D0: str          # 0 degrees
118
    D45: str         # 45 degrees
119
    D90: str         # 90 degrees
120
    D135: str        # 135 degrees
121
    D180: str        # 180 degrees
122
    D225: str        # 225 degrees
123
    D270: str        # 270 degrees
124
    D315: str        # 315 degrees
125
```
126

127
Example usage:
128

129
```python
130
# Image positioning
131
positioned = image.gravity(pyvips.CompassDirection.NORTH_EAST, 800, 600)
132

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

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

140
# Alignment in operations
141
aligned = image.embed(10, 10, 800, 600, extend=pyvips.Extend.COPY)
142
```
143

144
### Processing Options
145

146
Enumerations for controlling image processing behavior and quality.
147

148
```python { .api }
149
class Access:
150
    """Memory access patterns."""
151
    RANDOM: str                    # Random access
152
    SEQUENTIAL: str                # Sequential access
153
    SEQUENTIAL_UNBUFFERED: str     # Sequential without buffering
154

155
class Extend:
156
    """Edge extension methods."""
157
    BLACK: str       # Extend with black pixels
158
    COPY: str        # Copy edge pixels
159
    REPEAT: str      # Repeat image
160
    MIRROR: str      # Mirror image
161
    WHITE: str       # Extend with white pixels
162
    BACKGROUND: str  # Use background color
163

164
class Precision:
165
    """Computation precision levels."""
166
    INTEGER: str     # Integer precision
167
    FLOAT: str       # Floating point precision
168
    APPROXIMATE: str # Approximate (faster) precision
169

170
class Size:
171
    """Sizing behavior for operations."""
172
    BOTH: str        # Size both dimensions
173
    UP: str          # Only size up
174
    DOWN: str        # Only size down
175
    FORCE: str       # Force exact size
176

177
class Interesting:
178
    """Interest detection algorithms."""
179
    NONE: str        # No interest detection
180
    CENTRE: str      # Use center
181
    ENTROPY: str     # Use entropy (edge detection)
182
    ATTENTION: str   # Use attention algorithm
183
    LOW: str         # Favor low values
184
    HIGH: str        # Favor high values
185
    ALL: str         # Use all algorithms
186
```
187

188
Example usage:
189

190
```python
191
# File loading with access pattern
192
large_image = pyvips.Image.new_from_file('huge.tiff', 
193
    access=pyvips.Access.SEQUENTIAL)
194

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

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

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

207
# Thumbnail sizing behavior
208
thumb_up_only = image.thumbnail_image(800, 
209
    size=pyvips.Size.UP)
210
```
211

212
### Arithmetic and Logical Operations
213

214
Enumerations for mathematical and logical operations between images.
215

216
```python { .api }
217
class OperationRelational:
218
    """Relational comparison operations."""
219
    EQUAL: str       # Equal to
220
    NOTEQ: str       # Not equal to
221
    LESS: str        # Less than
222
    LESSEQ: str      # Less than or equal
223
    MORE: str        # Greater than
224
    MOREEQ: str      # Greater than or equal
225

226
class OperationBoolean:
227
    """Boolean bitwise operations."""
228
    AND: str         # Bitwise AND
229
    OR: str          # Bitwise OR
230
    EOR: str         # Bitwise XOR (exclusive OR)
231
    LSHIFT: str      # Left bit shift
232
    RSHIFT: str      # Right bit shift
233

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

240
class OperationMath:
241
    """Single-argument mathematical functions."""
242
    SIN: str         # Sine
243
    COS: str         # Cosine
244
    TAN: str         # Tangent
245
    ASIN: str        # Arcsine
246
    ACOS: str        # Arccosine
247
    ATAN: str        # Arctangent
248
    LOG: str         # Natural logarithm
249
    LOG10: str       # Base-10 logarithm
250
    EXP: str         # Exponential (e^x)
251
    EXP10: str       # Base-10 exponential
252
    SINH: str        # Hyperbolic sine
253
    COSH: str        # Hyperbolic cosine
254
    TANH: str        # Hyperbolic tangent
255

256
class OperationRound:
257
    """Rounding operations."""
258
    RINT: str        # Round to nearest integer
259
    CEIL: str        # Round up (ceiling)
260
    FLOOR: str       # Round down (floor)
261
```
262

263
Example usage:
264

265
```python
266
# Relational operations
267
mask = image.relational(128, pyvips.OperationRelational.MORE)
268
equal_pixels = image1.relational(image2, pyvips.OperationRelational.EQUAL)
269

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

274
# Mathematical functions
275
sine_wave = image.math(pyvips.OperationMath.SIN)
276
logarithmic = image.math(pyvips.OperationMath.LOG)
277

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

281
# Rounding
282
rounded = float_image.round(pyvips.OperationRound.RINT)
283
ceiling = float_image.round(pyvips.OperationRound.CEIL)
284
```
285

286
### Complex Number Operations
287

288
Enumerations for complex number processing and transformations.
289

290
```python { .api }
291
class OperationComplex:
292
    """Complex number operations."""
293
    POLAR: str       # Convert to polar form
294
    RECT: str        # Convert to rectangular form
295
    CONJ: str        # Complex conjugate
296

297
class OperationComplexget:
298
    """Extract components from complex numbers."""
299
    REAL: str        # Real component
300
    IMAG: str        # Imaginary component
301

302
class OperationComplex2:
303
    """Two-argument complex operations."""
304
    CROSS_PHASE: str # Cross phase
305
```
306

307
Example usage:
308

309
```python
310
# Complex number operations (for FFT results, etc.)
311
polar_form = complex_image.complex(pyvips.OperationComplex.POLAR)
312
conjugate = complex_image.complex(pyvips.OperationComplex.CONJ)
313

314
# Extract components
315
real_part = complex_image.complexget(pyvips.OperationComplexget.REAL)
316
imag_part = complex_image.complexget(pyvips.OperationComplexget.IMAG)
317
```
318

319
### Resampling and Interpolation
320

321
Enumerations for image resampling kernels and interpolation methods.
322

323
```python { .api }
324
class Kernel:
325
    """Resampling kernels for resize operations."""
326
    NEAREST: str     # Nearest neighbor (fastest, blocky)
327
    LINEAR: str      # Linear interpolation (fast)
328
    CUBIC: str       # Cubic interpolation (good quality)
329
    MITCHELL: str    # Mitchell filter (balanced)
330
    LANCZOS2: str    # Lanczos 2-tap (sharp)
331
    LANCZOS3: str    # Lanczos 3-tap (very sharp)
332
```
333

334
Example usage:
335

336
```python
337
# Different resampling quality levels
338
fast_resize = image.resize(0.5, kernel=pyvips.Kernel.LINEAR)
339
quality_resize = image.resize(0.5, kernel=pyvips.Kernel.LANCZOS3)
340
pixelated = image.resize(2.0, kernel=pyvips.Kernel.NEAREST)
341

342
# Create interpolator objects
343
linear_interp = pyvips.Interpolate.new(pyvips.Kernel.LINEAR)
344
bicubic_interp = pyvips.Interpolate.new(pyvips.Kernel.CUBIC)
345
```
346

347
### Color Management
348

349
Enumerations for color profiles and rendering intents.
350

351
```python { .api }
352
class Intent:
353
    """Color rendering intents for ICC profiles."""
354
    PERCEPTUAL: str  # Perceptual rendering
355
    RELATIVE: str    # Relative colorimetric
356
    SATURATION: str  # Saturation rendering
357
    ABSOLUTE: str    # Absolute colorimetric
358
    AUTO: str        # Automatic selection
359

360
class PCS:
361
    """Profile Connection Space."""
362
    LAB: str         # CIE LAB color space
363
    XYZ: str         # CIE XYZ color space
364
```
365

366
Example usage:
367

368
```python
369
# ICC profile operations with rendering intent
370
imported = image.icc_import(
371
    intent=pyvips.Intent.PERCEPTUAL,
372
    pcs=pyvips.PCS.LAB)
373

374
exported = image.icc_export(
375
    output_profile='printer.icc',
376
    intent=pyvips.Intent.RELATIVE)
377
```
378

379
### Format-Specific Options
380

381
Enumerations for various file format options and features.
382

383
```python { .api }
384
class ForeignKeep:
385
    """Metadata preservation options."""
386
    NONE: str        # Keep no metadata
387
    EXIF: str        # Keep EXIF data
388
    XMP: str         # Keep XMP data
389
    IPTC: str        # Keep IPTC data
390
    ICC: str         # Keep ICC profile
391
    OTHER: str       # Keep other metadata
392
    ALL: str         # Keep all metadata
393

394
class FailOn:
395
    """Error handling levels."""
396
    NONE: str        # Don't fail on errors
397
    TRUNCATED: str   # Fail on truncated files
398
    ERROR: str       # Fail on errors
399
    WARNING: str     # Fail on warnings
400

401
class ForeignPngFilter:
402
    """PNG filtering options."""
403
    NONE: str        # No filtering
404
    SUB: str         # Sub filter
405
    UP: str          # Up filter
406
    AVG: str         # Average filter
407
    PAETH: str       # Paeth filter
408
    ALL: str         # All filters
409
```
410

411
Example usage:
412

413
```python
414
# Metadata preservation
415
image.write_to_file('output.jpg', 
416
    keep=pyvips.ForeignKeep.EXIF | pyvips.ForeignKeep.ICC)
417

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

422
# PNG optimization
423
image.write_to_file('optimized.png',
424
    filter=pyvips.ForeignPngFilter.ALL,
425
    compression=9)
426
```
427

428
### Morphological Operations
429

430
Enumerations for mathematical morphology operations.
431

432
```python { .api }
433
class OperationMorphology:
434
    """Morphological operations."""
435
    ERODE: str       # Erosion operation
436
    DILATE: str      # Dilation operation
437
```
438

439
Example usage:
440

441
```python
442
# Morphological operations with custom kernel
443
kernel = pyvips.Image.new_from_array([
444
    [1, 1, 1],
445
    [1, 1, 1], 
446
    [1, 1, 1]
447
])
448

449
eroded = image.morph(kernel, pyvips.OperationMorphology.ERODE)
450
dilated = image.morph(kernel, pyvips.OperationMorphology.DILATE)
451
```
452

453
### Blend and Composite Operations
454

455
Enumerations for image blending and compositing modes.
456

457
```python { .api }
458
class BlendMode:
459
    """Porter-Duff blend modes."""
460
    CLEAR: str       # Clear destination
461
    SOURCE: str      # Copy source
462
    OVER: str        # Source over destination
463
    IN: str          # Source in destination
464
    OUT: str         # Source out destination
465
    ATOP: str        # Source atop destination
466
    DEST: str        # Keep destination
467
    DEST_OVER: str   # Destination over source
468
    DEST_IN: str     # Destination in source
469
    DEST_OUT: str    # Destination out source
470
    DEST_ATOP: str   # Destination atop source
471
    XOR: str         # Exclusive or
472
    ADD: str         # Addition
473
    SATURATE: str    # Saturate
474
    MULTIPLY: str    # Multiply
475
    SCREEN: str      # Screen
476
    OVERLAY: str     # Overlay
477
    DARKEN: str      # Darken
478
    LIGHTEN: str     # Lighten
479
    COLOUR_DODGE: str # Color dodge
480
    COLOUR_BURN: str  # Color burn
481
    HARD_LIGHT: str   # Hard light
482
    SOFT_LIGHT: str   # Soft light
483
    DIFFERENCE: str   # Difference
484
    EXCLUSION: str    # Exclusion
485

486
class CombineMode:
487
    """Image combination modes."""
488
    SET: str         # Set (replace)
489
    ADD: str         # Add values
490
```
491

492
Example usage:
493

494
```python
495
# Composite images with blend modes
496
composite = base_image.composite([overlay_image], 
497
    [pyvips.BlendMode.MULTIPLY])
498

499
# Multiple overlays with different blend modes
500
result = base_image.composite(
501
    [overlay1, overlay2, overlay3],
502
    [pyvips.BlendMode.OVERLAY, 
503
     pyvips.BlendMode.SOFT_LIGHT, 
504
     pyvips.BlendMode.SCREEN])
505
```
506

507
## Usage Best Practices
508

509
### Type Safety
510

511
```python
512
# Use enums instead of strings for type safety
513
# Good
514
image.resize(0.5, kernel=pyvips.Kernel.LANCZOS3)
515
image.colourspace(pyvips.Interpretation.SRGB)
516

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

521
### Feature Detection
522

523
```python
524
# Check for enum availability based on libvips version
525
def safe_enum_use():
526
    """Use enums safely across different libvips versions."""
527
    
528
    # Some enums may not be available in older versions
529
    try:
530
        return pyvips.ForeignKeep.ALL
531
    except AttributeError:
532
        # Fallback for older versions
533
        return 'all'
534

535
# Version-specific enum usage
536
if pyvips.at_least_libvips(8, 10):
537
    keep_option = pyvips.ForeignKeep.ALL
538
else:
539
    keep_option = 'all'  # String fallback
540
```
541

542
### Combining Flags
543

544
```python
545
# Some enums can be combined with bitwise OR
546
metadata_flags = (pyvips.ForeignKeep.EXIF | 
547
                 pyvips.ForeignKeep.ICC |
548
                 pyvips.ForeignKeep.XMP)
549

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