0
# Constants and Enums
1
2
TIFF format constants, compression schemes, photometric interpretations, and other standardized values required for proper TIFF file creation and interpretation. These enums provide type-safe access to TIFF specification values and ensure compatibility across different TIFF implementations.
3
4
## Capabilities
5
6
### TIFF Format Constants
7
8
Core TIFF format identification and byte order constants.
9
10
```python { .api }
11
class _TIFF:
12
"""Internal class containing TIFF format constants."""
13
14
# TIFF format signatures
15
CLASSIC_LE: bytes # b'II*\x00' - Classic TIFF, little-endian
16
CLASSIC_BE: bytes # b'MM\x00*' - Classic TIFF, big-endian
17
BIG_LE: bytes # b'II+\x00' - BigTIFF, little-endian
18
BIG_BE: bytes # b'MM\x00+' - BigTIFF, big-endian
19
20
# Version numbers
21
VERSION: int # 42 - Classic TIFF version
22
BIG_VERSION: int # 43 - BigTIFF version
23
24
TIFF = _TIFF() # Singleton instance containing TIFF constants
25
```
26
27
#### Usage Examples
28
29
```python
30
# Check TIFF format
31
with open('image.tif', 'rb') as f:
32
header = f.read(4)
33
if header == tifffile.TIFF.CLASSIC_LE:
34
print("Classic TIFF, little-endian")
35
elif header == tifffile.TIFF.BIG_LE:
36
print("BigTIFF, little-endian")
37
```
38
39
### Compression Enums
40
41
Compression algorithms supported in TIFF files.
42
43
```python { .api }
44
class COMPRESSION(IntEnum):
45
NONE = 1 # No compression
46
CCITT_1D = 2 # CCITT Group 3 1-Dimensional Modified Huffman
47
CCITT_GROUP3 = 3 # CCITT Group 3 fax encoding
48
CCITT_GROUP4 = 4 # CCITT Group 4 fax encoding
49
LZW = 5 # Lempel-Ziv-Welch compression
50
JPEG_OLD = 6 # Old-style JPEG compression (deprecated)
51
JPEG = 7 # JPEG compression
52
ADOBE_DEFLATE = 8 # Adobe-style Deflate compression
53
JBIG_BW = 9 # JBIG bi-level compression
54
JBIG_COLOR = 10 # JBIG color compression
55
NEXT = 32766 # NeXT 2-bit RLE compression
56
CCITTRLEW = 32771 # CCITT RLE with word alignment
57
PACKBITS = 32773 # PackBits compression
58
THUNDERSCAN = 32809 # ThunderScan compression
59
IT8CTPAD = 32895 # IT8 CT w/padding compression
60
IT8LW = 32896 # IT8 Linework RLE compression
61
IT8MP = 32897 # IT8 Monochrome picture compression
62
IT8BL = 32898 # IT8 Binary line art compression
63
PIXARFILM = 32908 # Pixar companded 10bit LZW
64
PIXARLOG = 32909 # Pixar companded 11bit ZIP
65
DEFLATE = 32946 # PKZIP-style Deflate compression
66
DCS = 32947 # Kodak DCS encoding
67
JBIG = 34661 # ISO JBIG compression
68
SGILOG = 34676 # SGI Log Luminance RLE
69
SGILOG24 = 34677 # SGI Log 24-bit packed
70
JP2000 = 34712 # JPEG 2000 compression
71
LZMA = 34925 # LZMA compression
72
ZSTD = 50000 # Zstandard compression
73
WEBP = 50001 # WebP compression
74
PNG = 50002 # PNG compression
75
JPEGXR = 50003 # JPEG XR compression
76
```
77
78
#### Usage Examples
79
80
```python
81
# Write compressed TIFF
82
tifffile.imwrite('lzw.tif', data, compression=tifffile.COMPRESSION.LZW)
83
tifffile.imwrite('deflate.tif', data, compression='deflate') # String also works
84
85
# Check compression of existing file
86
with tifffile.TiffFile('image.tif') as tif:
87
compression = tif.pages[0].compression
88
print(f"Compression: {compression.name} ({compression.value})")
89
90
if compression == tifffile.COMPRESSION.LZW:
91
print("Uses LZW compression")
92
```
93
94
### Photometric Interpretation Enums
95
96
Color interpretation schemes for TIFF images.
97
98
```python { .api }
99
class PHOTOMETRIC(IntEnum):
100
MINISWHITE = 0 # Min value is white (inverted grayscale)
101
MINISBLACK = 1 # Min value is black (normal grayscale)
102
RGB = 2 # RGB color model
103
PALETTE = 3 # Palette/indexed color
104
MASK = 4 # Transparency mask
105
SEPARATED = 5 # Color separations (CMYK)
106
YCBCR = 6 # YCbCr color space
107
CIELAB = 8 # CIE L*a*b* color space
108
ICCLAB = 9 # ICC L*a*b* color space
109
ITULAB = 10 # ITU L*a*b* color space
110
CFA = 32803 # Color Filter Array (Bayer pattern)
111
LOGL = 32844 # CIE Log2(L)
112
LOGLUV = 32845 # CIE Log2(L) (u',v')
113
LINEAR_RAW = 34892 # Linear Raw (Adobe DNG)
114
```
115
116
#### Usage Examples
117
118
```python
119
# Write RGB image
120
rgb_data = np.random.randint(0, 256, (100, 100, 3), dtype=np.uint8)
121
tifffile.imwrite('rgb.tif', rgb_data, photometric=tifffile.PHOTOMETRIC.RGB)
122
123
# Write grayscale image
124
gray_data = np.random.randint(0, 256, (100, 100), dtype=np.uint8)
125
tifffile.imwrite('gray.tif', gray_data, photometric='minisblack')
126
127
# Check photometric interpretation
128
with tifffile.TiffFile('image.tif') as tif:
129
photometric = tif.pages[0].photometric
130
if photometric == tifffile.PHOTOMETRIC.RGB:
131
print("RGB color image")
132
elif photometric == tifffile.PHOTOMETRIC.MINISBLACK:
133
print("Grayscale image")
134
```
135
136
### Data Type Enums
137
138
TIFF tag data types for proper tag encoding and decoding.
139
140
```python { .api }
141
class DATATYPE(IntEnum):
142
BYTE = 1 # 8-bit unsigned integer
143
ASCII = 2 # 8-bit byte containing ASCII character
144
SHORT = 3 # 16-bit unsigned integer
145
LONG = 4 # 32-bit unsigned integer
146
RATIONAL = 5 # Two 32-bit unsigned integers (numerator/denominator)
147
SBYTE = 6 # 8-bit signed integer
148
UNDEFINED = 7 # 8-bit byte with undefined content
149
SSHORT = 8 # 16-bit signed integer
150
SLONG = 9 # 32-bit signed integer
151
SRATIONAL = 10 # Two 32-bit signed integers (numerator/denominator)
152
FLOAT = 11 # 32-bit IEEE floating point
153
DOUBLE = 12 # 64-bit IEEE floating point
154
LONG8 = 16 # 64-bit unsigned integer (BigTIFF)
155
SLONG8 = 17 # 64-bit signed integer (BigTIFF)
156
IFD8 = 18 # 64-bit IFD offset (BigTIFF)
157
```
158
159
### Predictor Schemes
160
161
Prediction algorithms used with compression.
162
163
```python { .api }
164
class PREDICTOR(IntEnum):
165
NONE = 1 # No prediction
166
HORIZONTAL = 2 # Horizontal differencing
167
FLOATINGPOINT = 3 # Floating point horizontal differencing
168
```
169
170
#### Usage Examples
171
172
```python
173
# Write with horizontal predictor (good for continuous-tone images)
174
tifffile.imwrite(
175
'predicted.tif',
176
data,
177
compression='lzw',
178
predictor=tifffile.PREDICTOR.HORIZONTAL
179
)
180
181
# Write floating point data with appropriate predictor
182
float_data = np.random.random((100, 100)).astype(np.float32)
183
tifffile.imwrite(
184
'float.tif',
185
float_data,
186
compression='deflate',
187
predictor='floatingpoint'
188
)
189
```
190
191
### Planar Configuration
192
193
Organization of samples within pixels.
194
195
```python { .api }
196
class PLANARCONFIG(IntEnum):
197
CONTIG = 1 # Samples are contiguous (RGBRGBRGB...)
198
SEPARATE = 2 # Samples are in separate planes (RRR...GGG...BBB...)
199
```
200
201
#### Usage Examples
202
203
```python
204
# Write RGB with separate planes
205
rgb_data = np.random.randint(0, 256, (3, 100, 100), dtype=np.uint8)
206
tifffile.imwrite(
207
'separate.tif',
208
rgb_data,
209
photometric='rgb',
210
planarconfig=tifffile.PLANARCONFIG.SEPARATE
211
)
212
213
# Write RGB with contiguous samples (default)
214
rgb_data = np.random.randint(0, 256, (100, 100, 3), dtype=np.uint8)
215
tifffile.imwrite(
216
'contiguous.tif',
217
rgb_data,
218
photometric='rgb',
219
planarconfig='contig'
220
)
221
```
222
223
### Sample Format
224
225
Interpretation of sample data values.
226
227
```python { .api }
228
class SAMPLEFORMAT(IntEnum):
229
UINT = 1 # Unsigned integer
230
INT = 2 # Signed integer
231
IEEEFP = 3 # IEEE floating point
232
VOID = 4 # Undefined/void
233
COMPLEXINT = 5 # Complex integer
234
COMPLEXIEEEFP = 6 # Complex IEEE floating point
235
```
236
237
### Orientation
238
239
Image orientation relative to display.
240
241
```python { .api }
242
class ORIENTATION(IntEnum):
243
TOPLEFT = 1 # Row 0 at top, column 0 at left
244
TOPRIGHT = 2 # Row 0 at top, column 0 at right
245
BOTRIGHT = 3 # Row 0 at bottom, column 0 at right
246
BOTLEFT = 4 # Row 0 at bottom, column 0 at left
247
LEFTTOP = 5 # Row 0 at left, column 0 at top
248
RIGHTTOP = 6 # Row 0 at right, column 0 at top
249
RIGHTBOT = 7 # Row 0 at right, column 0 at bottom
250
LEFTBOT = 8 # Row 0 at left, column 0 at bottom
251
```
252
253
### Fill Order
254
255
Bit order within bytes.
256
257
```python { .api }
258
class FILLORDER(IntEnum):
259
MSB2LSB = 1 # Most significant bit first
260
LSB2MSB = 2 # Least significant bit first
261
```
262
263
### File Type Flags
264
265
TIFF file type and subfile type indicators.
266
267
```python { .api }
268
class FILETYPE(IntFlag):
269
UNDEFINED = 0 # Undefined
270
REDUCEDIMAGE = 1 # Reduced resolution version
271
PAGE = 2 # Single page of multi-page image
272
MASK = 4 # Transparency mask
273
DNG = 65536 # Adobe DNG format
274
275
class OFILETYPE(IntEnum):
276
IMAGE = 1 # Full resolution image
277
REDUCEDIMAGE = 2 # Reduced resolution version
278
PAGE = 3 # Single page of multi-page image
279
```
280
281
### Resolution Unit
282
283
Units for X and Y resolution values.
284
285
```python { .api }
286
class RESUNIT(IntEnum):
287
NONE = 1 # No absolute unit
288
INCH = 2 # Inch
289
CENTIMETER = 3 # Centimeter
290
```
291
292
#### Usage Examples
293
294
```python
295
# Write with resolution information
296
tifffile.imwrite(
297
'high_res.tif',
298
data,
299
resolution=(300, 300),
300
resolutionunit=tifffile.RESUNIT.INCH
301
)
302
303
# Write with metric resolution
304
tifffile.imwrite(
305
'metric.tif',
306
data,
307
resolution=(118.11, 118.11), # 300 DPI in dots per cm
308
resolutionunit='centimeter'
309
)
310
```
311
312
### Extra Sample Types
313
314
Interpretation of additional samples beyond color channels.
315
316
```python { .api }
317
class EXTRASAMPLE(IntEnum):
318
UNSPECIFIED = 0 # Unspecified data
319
ASSOCALPHA = 1 # Associated alpha (premultiplied)
320
UNASSALPHA = 2 # Unassociated alpha (separate)
321
```
322
323
#### Usage Examples
324
325
```python
326
# Write RGBA with unassociated alpha
327
rgba_data = np.random.randint(0, 256, (100, 100, 4), dtype=np.uint8)
328
tifffile.imwrite(
329
'rgba.tif',
330
rgba_data,
331
photometric='rgb',
332
extrasamples=[tifffile.EXTRASAMPLE.UNASSALPHA]
333
)
334
```
335
336
### Chunk Reading Modes
337
338
Strategies for reading large TIFF files in chunks.
339
340
```python { .api }
341
class CHUNKMODE(IntEnum):
342
NONE = 0 # No chunking
343
PAGE = 1 # Chunk by pages
344
PLANE = 2 # Chunk by planes
345
TILE = 3 # Chunk by tiles
346
FRAME = 4 # Chunk by frames
347
```
348
349
#### Usage Examples
350
351
```python
352
# Read large file with page-based chunking
353
large_data = tifffile.imread('huge.tif', chunkmode=tifffile.CHUNKMODE.PAGE)
354
355
# Use Zarr with tile-based chunking
356
zarr_store = tifffile.imread('tiled.tif', aszarr=True, chunkmode='tile')
357
```
358
359
## Enum Utilities
360
361
Helper functions for working with enums.
362
363
```python { .api }
364
def enumarg(enum_class, arg):
365
"""
366
Convert argument to enum member.
367
368
Parameters:
369
- enum_class: Enum class
370
- arg: str, int, or enum member
371
372
Returns:
373
- Enum member
374
"""
375
376
def enumstr(enum_class, *args, **kwargs):
377
"""
378
Return string representation of enum values.
379
380
Parameters:
381
- enum_class: Enum class
382
- *args, **kwargs: enum values
383
384
Returns:
385
- str: Formatted enum string
386
"""
387
```
388
389
#### Usage Examples
390
391
```python
392
# Convert strings to enums
393
compression = tifffile.enumarg(tifffile.COMPRESSION, 'lzw')
394
photometric = tifffile.enumarg(tifffile.PHOTOMETRIC, 'rgb')
395
396
# Get string representations
397
comp_str = tifffile.enumstr(tifffile.COMPRESSION, tifffile.COMPRESSION.LZW)
398
print(comp_str) # "LZW"
399
```
400
401
## Common Usage Patterns
402
403
### Format Detection
404
405
```python
406
# Determine appropriate settings based on data
407
data = np.random.randint(0, 256, (100, 100, 3), dtype=np.uint8)
408
409
if data.ndim == 3 and data.shape[2] == 3:
410
photometric = tifffile.PHOTOMETRIC.RGB
411
elif data.ndim == 3 and data.shape[2] == 4:
412
photometric = tifffile.PHOTOMETRIC.RGB
413
extrasamples = [tifffile.EXTRASAMPLE.UNASSALPHA]
414
else:
415
photometric = tifffile.PHOTOMETRIC.MINISBLACK
416
417
tifffile.imwrite('auto.tif', data, photometric=photometric)
418
```
419
420
### Compression Selection
421
422
```python
423
# Choose compression based on data type
424
if data.dtype in (np.uint8, np.uint16):
425
compression = tifffile.COMPRESSION.LZW
426
predictor = None
427
elif data.dtype in (np.float32, np.float64):
428
compression = tifffile.COMPRESSION.DEFLATE
429
predictor = tifffile.PREDICTOR.FLOATINGPOINT
430
else:
431
compression = tifffile.COMPRESSION.DEFLATE
432
predictor = tifffile.PREDICTOR.HORIZONTAL
433
434
tifffile.imwrite(
435
'optimized.tif',
436
data,
437
compression=compression,
438
predictor=predictor
439
)
440
```
441
442
### Multi-format Support
443
444
```python
445
# Handle different input formats
446
def write_universal_tiff(filename, data, format_hint=None):
447
kwargs = {}
448
449
if format_hint == 'imagej':
450
kwargs.update({
451
'imagej': True,
452
'photometric': tifffile.PHOTOMETRIC.MINISBLACK
453
})
454
elif format_hint == 'ome':
455
kwargs.update({
456
'ome': True,
457
'compression': tifffile.COMPRESSION.LZW
458
})
459
elif format_hint == 'geotiff':
460
kwargs.update({
461
'photometric': tifffile.PHOTOMETRIC.RGB,
462
'compression': tifffile.COMPRESSION.DEFLATE
463
})
464
465
return tifffile.imwrite(filename, data, **kwargs)
466
```