src/pypdf/generic/_image_xobject.py
1"""Functions to convert an image XObject to an image"""
2from collections.abc import Sequence
3from io import BytesIO
4from typing import IO, Any, Literal, TypeAlias, cast
5
6from .._configuration import get_configuration
7from .._utils import check_if_whitespace_only, logger_warning
8from ..constants import ColorSpaces, FilterTypes, ImageAttributes, StreamAttributes
9from ..errors import EmptyImageDataError, LimitReachedError, PdfReadError
10from ..generic import (
11 ArrayObject,
12 DecodedStreamObject,
13 EncodedStreamObject,
14 NullObject,
15 TextStringObject,
16 is_null_or_none,
17)
18
19try:
20 from PIL import Image, UnidentifiedImageError
21except ImportError as exception:
22 raise ImportError(
23 "pillow is required to do image extraction. "
24 "It can be installed via 'pip install pypdf[image]'"
25 ) from exception
26
27ImageMode: TypeAlias = Literal[
28 "", "1", "RGB", "2bits", "4bits", "P", "L", "RGBA", "CMYK"
29]
30
31MAX_IMAGE_MODE_NESTING_DEPTH: int = 10
32
33_PROCESS_COLORANTS = ("/Cyan", "/Magenta", "/Yellow", "/Black")
34
35
36def _get_process_colorant_channels(color_space: Any) -> list[int] | None:
37 """
38 Return the CMYK channel of each colorant of a /DeviceN space.
39
40 Returns None if the space is something else or uses a colorant which is not a process colorant.
41 """
42 if not isinstance(color_space, list) or len(color_space) < 2 or color_space[0] != "/DeviceN":
43 return None
44 colorants = color_space[1].get_object()
45 if (
46 not isinstance(colorants, list)
47 or not colorants
48 or not all(colorant in _PROCESS_COLORANTS for colorant in colorants)
49 ):
50 return None
51 return [_PROCESS_COLORANTS.index(colorant) for colorant in colorants]
52
53
54def _get_image_mode(
55 color_space: str | list[Any] | Any,
56 color_components: int,
57 prev_mode: ImageMode,
58 depth: int = 0,
59) -> tuple[ImageMode, bool]:
60 """
61 Returns:
62 Image mode, not taking into account mask (transparency).
63 ColorInversion is required (like for some DeviceCMYK).
64
65 """
66 if depth > MAX_IMAGE_MODE_NESTING_DEPTH:
67 raise PdfReadError(
68 "Color spaces nested too deeply. If required, consider increasing MAX_IMAGE_MODE_NESTING_DEPTH."
69 )
70 if is_null_or_none(color_space):
71 return "", False
72 color_space_str: str = ""
73 if isinstance(color_space, str):
74 color_space_str = color_space
75 elif not isinstance(color_space, list):
76 raise PdfReadError(
77 "Cannot interpret color space", color_space
78 ) # pragma: no cover
79 elif not color_space:
80 return "", False
81 elif color_space[0].startswith("/Cal"): # /CalRGB or /CalGray
82 color_space_str = "/Device" + color_space[0][4:]
83 elif color_space[0] == "/ICCBased":
84 icc_profile = color_space[1].get_object()
85 color_components = cast(int, icc_profile["/N"])
86 color_space_str = icc_profile.get("/Alternate", "")
87 elif color_space[0] == "/Indexed":
88 color_space_str = color_space[1].get_object()
89 if _get_process_colorant_channels(color_space_str) is not None:
90 color_space_str = ColorSpaces.DEVICE_CMYK
91 mode, invert_color = _get_image_mode(
92 color_space_str, color_components, prev_mode, depth + 1
93 )
94 if mode in ("RGB", "CMYK"):
95 mode = "P"
96 return mode, invert_color
97 elif color_space[0] == "/Separation":
98 color_space_str = color_space[2].get_object()
99 mode, invert_color = _get_image_mode(
100 color_space_str, color_components, prev_mode, depth + 1
101 )
102 return mode, True
103 elif color_space[0] == "/DeviceN":
104 original_color_space = color_space
105 color_components = len(color_space[1])
106 color_space_str = color_space[2].get_object()
107 if color_space_str == "/DeviceCMYK" and color_components == 1:
108 if original_color_space[1][0] != "/Black":
109 logger_warning(
110 "Color %(color)s converted to Gray. Please share PDF with pypdf dev team",
111 source=__name__,
112 color=original_color_space[1][0],
113 )
114 return "L", True
115 mode, invert_color = _get_image_mode(
116 color_space_str, color_components, prev_mode, depth + 1
117 )
118 return mode, invert_color
119
120 mode_map: dict[str, ImageMode] = {
121 "1bit": "1", # must be zeroth position: color_components may index the values
122 "/DeviceGray": "L", # must be first position: color_components may index the values
123 "palette": "P", # must be second position: color_components may index the values
124 "/DeviceRGB": "RGB", # must be third position: color_components may index the values
125 "/DeviceCMYK": "CMYK", # must be fourth position: color_components may index the values
126 "2bit": "2bits",
127 "4bit": "4bits",
128 }
129
130 mode_values = list(mode_map.values())
131 mode = (
132 mode_map.get(color_space_str)
133 or (
134 mode_values[color_components]
135 if 0 <= color_components < len(mode_values)
136 else None
137 )
138 or prev_mode
139 )
140
141 return mode, mode == "CMYK"
142
143
144def bits2byte(
145 data: bytes,
146 size: tuple[int, int],
147 bits: int,
148 colors: int = 1,
149 scale: bool = False,
150) -> bytes:
151 configuration = get_configuration()
152
153 # Number of samples per row = pixels per row * components per pixel.
154 samples_per_row = size[0] * colors
155 buffer_size = samples_per_row * size[1]
156 if buffer_size > configuration.image_maximum_buffer_size:
157 raise LimitReachedError(
158 f"Requested buffer size {buffer_size} exceeds limit of {configuration.image_maximum_buffer_size}."
159 )
160
161 byte_buffer = bytearray(buffer_size)
162 mask = (1 << bits) - 1
163 # Scale a b-bit sample up to the full 0-255 range (e.g. 4-bit 15 -> 255)
164 # when the output is consumed directly as color (RGB) rather than as a
165 # palette index.
166 factor = 255 // mask if scale and mask else 1
167
168 required = size[1] * ((samples_per_row * bits + 7) // 8)
169 if (length := len(data)) < required:
170 logger_warning("Image data is not rectangular. Adding padding.", source=__name__)
171 data += b"\x00" * (required - length)
172
173 data_index = 0
174 bit = 8 - bits
175 for y in range(size[1]):
176 if bit != 8 - bits:
177 data_index += 1
178 bit = 8 - bits
179 for x in range(samples_per_row):
180 byte_buffer[x + y * samples_per_row] = (
181 ((data[data_index] >> bit) & mask) * factor
182 )
183 bit -= bits
184 if bit < 0:
185 data_index += 1
186 bit = 8 - bits
187 return bytes(byte_buffer)
188
189
190def _expand_low_bit_samples(
191 mode: ImageMode,
192 size: tuple[int, int],
193 data: bytes,
194 color_space: str | ArrayObject,
195) -> tuple[ImageMode, bytes]:
196 """
197 Expand 2- or 4-bit-per-component samples to one byte per component.
198
199 Pillow has no mode for sub-byte samples, so the packed data has to be
200 unpacked before an image can be built from it. A single-component
201 /DeviceGray image holds grayscale samples, scaled to the full 0-255 range
202 as an "L" image. A multi-component space such as /DeviceRGB has interleaved
203 color components, also scaled and combined into an "RGB" image. An indexed
204 color space keeps its raw sample values as palette indices ("P").
205
206 Returns the resulting mode and data, unchanged when the mode is not a
207 low-bit one.
208 """
209 if mode not in ("2bits", "4bits"):
210 return mode, data
211 bits = int(mode[0])
212 if color_space == "/DeviceRGB":
213 return "RGB", bits2byte(data, size, bits, colors=3, scale=True)
214 if color_space == "/DeviceGray":
215 return "L", bits2byte(data, size, bits, scale=True)
216 return "P", bits2byte(data, size, bits)
217
218
219# Bytes per pixel Pillow allocates for a single-band image, keyed by mode.
220# Pillow keeps one sample of "1", "L" and "P" in one byte, the 16-bit family in
221# two and "I"/"F" in four. Image.getmodetype() cannot tell them apart: it
222# reports "L" for "1", "L", "P" and the whole 16-bit family.
223_SINGLE_BAND_BYTES_PER_PIXEL: dict[str, int] = {
224 "1": 1,
225 "L": 1,
226 "P": 1,
227 "I;16": 2,
228 "I;16B": 2,
229 "I;16L": 2,
230 "I;16N": 2,
231 "I": 4,
232 "F": 4,
233}
234
235
236def _get_allocated_bytes_per_pixel(mode: str) -> int:
237 """Bytes Pillow allocates per pixel for a decoded image in the given mode.
238
239 This is the size of the internal pixel, not the size of the raw data: every
240 mode with two or more bands is stored in a four-byte pixel, so "RGB",
241 "YCbCr", "LAB", "HSV", "LA", "La" and "PA" all take four bytes although
242 they have three or two bands. The length of the mode name says nothing
243 about it either: "I" and "F" need four bytes per pixel and the 16-bit modes
244 two.
245
246 The number of bands is taken from Pillow, so the multi-band half needs no
247 table. The four bytes are Pillow's image32 storage, which the API does not
248 report: it holds for every mode Pillow had from 8.0.0 to 12.3.0, and the
249 test over Image.MODES fails when a release adds a mode, so the assumption
250 cannot go stale unnoticed. The width of a single sample is not exposed in a
251 version-independent way either, so those modes stay in a table; an unknown
252 mode takes four bytes, the safe direction for a limit.
253 """
254 try:
255 bands = Image.getmodebands(mode)
256 except KeyError:
257 # Not a mode Pillow knows: _get_mode_and_invert_color() returns an empty
258 # mode when the color space is missing, and _handle_flate() builds an
259 # image from it. Keep the name length so that such data is still
260 # reported by Pillow instead of failing here.
261 return len(mode)
262 if bands > 1:
263 return 4
264 return _SINGLE_BAND_BYTES_PER_PIXEL.get(mode, 4)
265
266
267def _validate_image_size(*, mode: str, size: tuple[int, int]) -> tuple[int, int]:
268 pixel_count = size[0] * size[1]
269 required_byte_count = pixel_count * _get_allocated_bytes_per_pixel(mode)
270
271 configuration = get_configuration()
272 if required_byte_count > configuration.image_maximum_buffer_size:
273 raise LimitReachedError(
274 f"Requested image buffer size {required_byte_count} exceeds limit "
275 f"{configuration.image_maximum_buffer_size}."
276 )
277
278 return pixel_count, required_byte_count
279
280
281def _create_image_from_bytes(
282 mode: str, size: tuple[int, int], data: bytes
283) -> Image.Image:
284 pixel_count, _ = _validate_image_size(mode=mode, size=size)
285
286 try:
287 img = Image.frombytes(mode, size, data)
288 except ValueError as exc:
289 data_length = len(data)
290 if data_length == 0:
291 raise EmptyImageDataError(
292 "Data is 0 bytes, cannot process an image from empty data."
293 ) from exc
294 if data_length % pixel_count != 0:
295 raise
296 # The expansion factor counts raw samples per pixel, not the bytes
297 # Pillow allocates: the modes that reach this function are "1", "L",
298 # "P", "RGB", "RGBA" and "CMYK", whose names spell out their samples,
299 # so len(mode) is the sample count.
300 raw_byte_count = pixel_count * len(mode)
301 k = raw_byte_count / data_length
302 data = b"".join(bytes((x,) * int(k)) for x in data)
303 img = Image.frombytes(mode, size, data)
304 return img
305
306
307def _create_image_from_buffer(*, buf: IO[bytes], formats: tuple[str, ...] | None = None) -> Image.Image:
308 image = Image.open(fp=buf, formats=formats)
309 _validate_image_size(mode=image.mode, size=image.size)
310 return image
311
312
313def _convert_image(*, image: Image.Image, mode: str) -> Image.Image:
314 _validate_image_size(mode=mode, size=image.size)
315 return image.convert(mode)
316
317
318def _resize_image(*, image: Image.Image, size: tuple[int, int]) -> Image.Image:
319 _validate_image_size(mode=image.mode, size=size)
320 return image.resize(size)
321
322
323def _merge_image(*, mode: str, bands: Sequence[Image.Image]) -> Image.Image:
324 if not bands:
325 return Image.merge(mode=mode, bands=bands)
326 _validate_image_size(mode=mode, size=bands[0].size)
327 return Image.merge(mode=mode, bands=bands)
328
329
330def __handle_flate__indexed(color_space: ArrayObject) -> tuple[Any, Any, Any, Any]:
331 count = len(color_space)
332 if count == 4:
333 color_space, base, hival, lookup = (value.get_object() for value in color_space)
334 return color_space, base, hival, lookup
335
336 # Deal with strange AutoDesk files where `base` and `hival` look like this:
337 # /DeviceRGB\x00255
338 element1 = color_space[1]
339 element1 = element1 if isinstance(element1, str) else element1.get_object()
340 if count == 3 and "\x00" in element1:
341 color_space, lookup = color_space[0].get_object(), color_space[2].get_object()
342 base, hival = element1.split("\x00")
343 hival = int(hival)
344 return color_space, base, hival, lookup
345 raise PdfReadError(f"Expected color space with 4 values, got {count}: {color_space}")
346
347
348def _handle_flate(
349 size: tuple[int, int],
350 data: bytes,
351 mode: ImageMode,
352 color_space: str | ArrayObject,
353 colors: int,
354 obj_as_text: str,
355) -> tuple[Image.Image, str, str, bool]:
356 """
357 Process image encoded using the zlib/deflate compression method, corresponds to the FlateDecode filter
358 Returns img, image_format, extension, color inversion
359 """
360 base: Any
361 hival: Any
362 lookup: Any
363 if isinstance(color_space, ArrayObject) and color_space[0] == "/Indexed":
364 color_space, base, hival, lookup = __handle_flate__indexed(color_space)
365 mode, data = _expand_low_bit_samples(mode, size, data, color_space)
366 img = _create_image_from_bytes(mode, size, data)
367 if color_space == "/Indexed":
368 if isinstance(lookup, (EncodedStreamObject, DecodedStreamObject)):
369 lookup = lookup.get_data()
370 if isinstance(lookup, TextStringObject):
371 lookup = lookup.original_bytes
372 if isinstance(lookup, str):
373 lookup = lookup.encode()
374 if (channels := _get_process_colorant_channels(base)) is not None:
375 # Put each tint into its own CMYK channel instead of evaluating the tint transform.
376 colorant_count = len(channels)
377 cmyk_lookup = bytearray()
378 for index in range(0, len(lookup) - colorant_count + 1, colorant_count):
379 cmyk = bytearray(4)
380 for channel, tint in zip(channels, lookup[index : index + colorant_count]):
381 cmyk[channel] = tint
382 cmyk_lookup += cmyk
383 lookup = bytes(cmyk_lookup)
384 base = ColorSpaces.DEVICE_CMYK
385 try:
386 nb, conv, mode = { # type: ignore[assignment]
387 "1": (0, "", ""),
388 "L": (1, "P", "L"),
389 "P": (0, "", ""),
390 "RGB": (3, "P", "RGB"),
391 "CMYK": (4, "P", "CMYK"),
392 }[_get_image_mode(base, 0, "")[0]]
393 except KeyError: # pragma: no cover
394 logger_warning(
395 "Base %(base)s not coded. Please share PDF with pypdf dev team",
396 source=__name__,
397 base=base,
398 )
399 lookup = None
400 else:
401 if img.mode == "1" and nb == 0:
402 # A two-color lookup needs at least one byte per color, but the
403 # base color space resolves to a 1-bit or palette image.
404 logger_warning(
405 "Cannot apply lookup for base %(base)s to image with mode 1. "
406 "Please share PDF with pypdf dev team",
407 source=__name__,
408 base=base,
409 )
410 elif img.mode == "1":
411 # Two values ("high" and "low").
412 expected_count = 2 * nb
413 actual_count = len(lookup)
414 if actual_count != expected_count:
415 if actual_count < expected_count:
416 logger_warning(
417 "Not enough lookup values: Expected %(expected_count)d, got %(actual_count)d.",
418 source=__name__,
419 expected_count=expected_count,
420 actual_count=actual_count,
421 )
422 lookup += bytes([0] * (expected_count - actual_count))
423 elif not check_if_whitespace_only(lookup[expected_count:]):
424 logger_warning(
425 "Too many lookup values: Expected %(expected_count)d, got %(actual_count)d.",
426 source=__name__,
427 expected_count=expected_count,
428 actual_count=actual_count,
429 )
430 lookup = lookup[:expected_count]
431 colors_arr = [lookup[:nb], lookup[nb:]]
432 source = _convert_image(image=img, mode="L")
433 bands = [
434 source.point(
435 [low_value] * 128 + [high_value] * 128
436 )
437 for low_value, high_value in zip(colors_arr[0], colors_arr[1])
438 ]
439 img = bands[0] if nb == 1 else _merge_image(mode=mode, bands=bands)
440 else:
441 img = _convert_image(image=img, mode=conv)
442 if len(lookup) != (hival + 1) * nb:
443 logger_warning("Invalid Lookup Table in %(obj_as_text)s", source=__name__, obj_as_text=obj_as_text)
444 lookup = None
445 elif mode == "L":
446 # gray lookup does not work: it is converted to a similar RGB lookup
447 lookup = b"".join([bytes([b, b, b]) for b in lookup])
448 mode = "RGB"
449 elif mode == "CMYK":
450 # Convert the CMYK palette to RGB manually. Pillow can unpack
451 # CMYK palettes natively since 10.1.0 (see
452 # https://github.com/python-pillow/Pillow/pull/7310),
453 # but this is not reliable across versions: Starting with
454 # Pillow 12.2.0, the palette stays CMYK and `convert("RGB")`
455 # does not convert its colors anymore.
456 # Pillow rounds the values while this code truncates them, so
457 # results can differ by one for some channels.
458 _rgb = []
459 for _c, _m, _y, _k in (
460 lookup[n : n + 4] for n in range(0, 4 * (len(lookup) // 4), 4)
461 ):
462 _r = int(255 * (1 - _c / 255) * (1 - _k / 255))
463 _g = int(255 * (1 - _m / 255) * (1 - _k / 255))
464 _b = int(255 * (1 - _y / 255) * (1 - _k / 255))
465 _rgb.append(bytes((_r, _g, _b)))
466 lookup = b"".join(_rgb)
467 mode = "RGB"
468 if lookup is not None:
469 img.putpalette(lookup, rawmode=mode)
470 img = _convert_image(image=img, mode="L" if base == ColorSpaces.DEVICE_GRAY else "RGB")
471 elif not is_null_or_none(color_space) and color_space[0] == "/ICCBased":
472 # Exclude pure black-and-white images.
473 # TODO: The ICC profile itself is never applied; only the number of components
474 # (/N) and the alternate color space are used to pick the image mode.
475 # Applying the profile would require an actual color transformation,
476 # for example using PIL.ImageCms.
477 # The reload below uses the same mode, size and data as the image which
478 # has already been created above, so it currently does not change the result.
479 if mode != "1":
480 # Table 65 - Additional Entries Specific to an ICC Profile Stream Dictionary
481 mode2 = _get_image_mode(color_space, colors, mode)[0]
482 if mode != mode2:
483 img = _create_image_from_bytes(mode, size, data) # reloaded as mode may have changed
484 if mode == "CMYK":
485 image_format = "TIFF"
486 extension = ".tif"
487 else:
488 image_format = "PNG"
489 extension = ".png" # mime_type: "image/png"
490 return img, image_format, extension, False
491
492
493def _handle_jpx(
494 size: tuple[int, int],
495 data: bytes,
496 mode: ImageMode,
497 color_space: str,
498 colors: int,
499) -> tuple[Image.Image, str, str, bool]:
500 """
501 Process image encoded as JPX/JPEG2000
502 Returns img, image_format, extension, inversion
503 """
504 img1: Image.Image = _create_image_from_buffer(buf=BytesIO(data), formats=("JPEG2000",))
505 mode, invert_color = _get_image_mode(color_space, colors, mode)
506 if mode == "":
507 mode = cast(ImageMode, img1.mode)
508 invert_color = mode == "CMYK"
509 if img1.mode == "RGBA" and mode == "RGB":
510 mode = "RGBA"
511 # we need to convert to the good mode
512 if img1.mode == mode or {img1.mode, mode} == {"L", "P"}: # compare (unordered) sets
513 # L and P are indexed modes which should not be changed.
514 img = img1
515 elif {img1.mode, mode} == {"RGBA", "CMYK"}:
516 # RGBA / CMYK are 4bytes encoding where
517 # the encoding should be corrected
518 img = _create_image_from_bytes(mode, img1.size, img1.tobytes())
519 else: # pragma: no cover
520 img = _convert_image(image=img1, mode=mode)
521 # CMYK conversion
522 # https://stackverflow.com/questions/38855022/
523 if img.mode == "CMYK" and color_space == "/ICCBased":
524 img = _convert_image(image=img, mode="RGB")
525 return img, "JPEG2000", ".jp2", invert_color
526
527
528def _apply_decode(
529 img: Image.Image,
530 x_object: dict[str, Any],
531 lfilters: FilterTypes,
532 color_space: str | list[Any] | Any,
533 invert_color: bool,
534) -> Image.Image:
535 # CMYK image and other color spaces without decode
536 # requires reverting scale (cf p243,2§ last sentence)
537 if ImageAttributes.DECODE in x_object:
538 decode = x_object[ImageAttributes.DECODE]
539 if img.mode == "CMYK" and lfilters == FilterTypes.DCT_DECODE:
540 # Adobe writes CMYK JPEGs with inverted component values, which is
541 # what the [min max] -> [1 0] remap in the branches below
542 # compensates for. An explicit /Decode array is expressed in terms
543 # of the true values, so it has to be combined with that inversion
544 # rather than replacing it - otherwise an identity /Decode leaves
545 # the image inverted (#2931).
546 #
547 # Substituting s -> 1-s into dmin + s*(dmax-dmin) gives
548 # dmax + s*(dmin-dmax), which is the same pair swapped. A malformed
549 # odd-length array is left untouched here and dropped with a
550 # warning further down.
551 decode = [
552 value
553 for index in range(0, len(decode) - 1, 2)
554 for value in (decode[index + 1], decode[index])
555 ]
556 elif img.mode == "CMYK" and lfilters == FilterTypes.JPX_DECODE:
557 decode = [1.0, 0.0] if not invert_color else [0.0, 1.0]
558 decode = decode * len(img.getbands())
559 elif (img.mode == "CMYK" and lfilters == FilterTypes.DCT_DECODE) or (invert_color and img.mode == "L"):
560 decode = [1.0, 0.0] * len(img.getbands())
561 else:
562 decode = None
563
564 if (
565 isinstance(color_space, ArrayObject)
566 and color_space[0].get_object() == "/Indexed"
567 ):
568 decode = None # decode is meaningless if Indexed
569 if (
570 isinstance(color_space, ArrayObject)
571 and color_space[0].get_object() == "/Separation"
572 ):
573 decode = [1.0, 0.0] * len(img.getbands())
574 if decode is not None and (
575 not isinstance(decode, list) or len(decode) % 2 != 0
576 ):
577 # /Decode is read straight from the image dictionary and must hold an
578 # even number of values (a [min max] pair per component). A malformed
579 # array would otherwise read past its end at decode[i + 1]; drop it and
580 # render the image without the remap.
581 logger_warning(
582 "Ignoring malformed /Decode array %(decode)s; expected an even number of values.",
583 source=__name__,
584 decode=decode,
585 )
586 decode = None
587 if decode is not None and not all(decode[i] == i % 2 for i in range(len(decode))):
588 lut: list[int] = []
589 for i in range(0, len(decode), 2):
590 dmin = decode[i]
591 dmax = decode[i + 1]
592 lut.extend(
593 round(255.0 * (j / 255.0 * (dmax - dmin) + dmin)) for j in range(256)
594 )
595 img = img.point(lut)
596 return img
597
598
599def _get_mode_and_invert_color(
600 x_object: dict[str, Any], colors: int, color_space: str | list[Any] | Any
601) -> tuple[ImageMode, bool]:
602 bits = x_object.get("/BitsPerComponent", 8)
603 if (
604 ImageAttributes.COLOR_SPACE in x_object
605 and x_object[ImageAttributes.COLOR_SPACE] == ColorSpaces.DEVICE_RGB
606 and bits >= 8
607 ):
608 # Full-width /DeviceRGB samples are RGB. Narrower samples stay on
609 # the low-bit path so they can be expanded (#3367).
610 return "RGB", False
611 if bits < 8:
612 mode, invert_color = _get_image_mode(
613 f"{bits}bit", 0, ""
614 )
615 else:
616 mode, invert_color = _get_image_mode(
617 color_space,
618 2
619 if (
620 colors == 1
621 and (
622 not is_null_or_none(color_space)
623 and "Gray" not in color_space
624 )
625 )
626 else colors,
627 "",
628 )
629 return mode, invert_color
630
631
632def _apply_alpha(
633 *,
634 img: Image.Image,
635 x_object: dict[str, Any],
636 obj_as_text: str,
637 image_format: str,
638 extension: str,
639 visited: set[int],
640) -> tuple[Image.Image, str, str]:
641 if ImageAttributes.S_MASK not in x_object:
642 return img, extension, image_format
643
644 s_mask = x_object[ImageAttributes.S_MASK]
645 if id(s_mask) in visited:
646 # A soft mask that refers back to an image already being
647 # converted would recurse until the interpreter runs out of
648 # stack. Such a chain cannot describe a real alpha channel, so
649 # drop the mask and keep the image we have.
650 logger_warning(
651 "Ignoring cyclic /SMask reference in %(obj_as_text)s",
652 source=__name__,
653 obj_as_text=obj_as_text,
654 )
655 return img, extension, image_format
656
657 alpha = _xobj_to_image(s_mask, visited=visited)[2]
658 # TODO: implement mask
659 if alpha.mode != "L":
660 alpha = _convert_image(image=alpha, mode="L")
661 if img.size != alpha.size:
662 # Both are mapped onto the unit square, thus a soft mask may use other dimensions than its image.
663 alpha = _resize_image(image=alpha, size=img.size)
664 if img.mode == "P":
665 img = _convert_image(image=img, mode="RGB")
666 elif img.mode == "1":
667 img = _convert_image(image=img, mode="L")
668 img.putalpha(alpha)
669
670 if "JPEG" in image_format:
671 image_format = "JPEG2000"
672 extension = ".jp2"
673 else:
674 image_format = "PNG"
675 extension = ".png"
676
677 return img, extension, image_format
678
679
680def _xobj_to_image(
681 x_object: dict[str, Any],
682 pillow_parameters: dict[str, Any] | None = None,
683 visited: set[int] | None = None,
684) -> tuple[str | None, bytes, Any]:
685 """
686 Args:
687 x_object:
688 pillow_parameters: parameters provided to Pillow Image.save() method,
689 cf. <https://pillow.readthedocs.io/en/stable/reference/Image.html#PIL.Image.Image.save>
690 visited: Set of id() values of XObjects already being converted higher
691 up the /SMask chain, used to detect cyclic soft masks.
692
693 Returns:
694 Tuple[file extension, bytes, PIL.Image.Image]
695
696 """
697 if visited is None:
698 visited = set()
699 visited.add(id(x_object))
700
701 # For error reporting
702 obj_as_text = (
703 x_object.indirect_reference.__repr__()
704 if x_object is None # pragma: no cover
705 else x_object.__repr__()
706 )
707
708 # Get size and data
709 size = (cast(int, x_object[ImageAttributes.WIDTH]), cast(int, x_object[ImageAttributes.HEIGHT]))
710 data = x_object.get_data() # type: ignore[attr-defined]
711 if isinstance(data, str): # pragma: no cover
712 data = data.encode()
713 if len(data) % (size[0] * size[1]) == 1 and data[-1] == 0x0A: # i.e. '\n'
714 data = data[:-1]
715
716 # Get color properties
717 colors = x_object.get("/Colors", 1)
718 color_space: Any = x_object.get("/ColorSpace", NullObject()).get_object()
719 if isinstance(color_space, list) and len(color_space) == 1:
720 color_space = color_space[0].get_object()
721
722 mode, invert_color = _get_mode_and_invert_color(x_object, colors, color_space)
723
724 # Get filters
725 filters = x_object.get(StreamAttributes.FILTER, NullObject()).get_object()
726 # An empty array is a valid way of saying that no filter is applied: treat it
727 # like a missing /Filter entry rather than raising IndexError on the lookup.
728 last_filter = filters[-1] if filters and isinstance(filters, list) else filters
729 decode_parms = x_object.get(StreamAttributes.DECODE_PARMS)
730 if decode_parms and isinstance(decode_parms, (tuple, list)):
731 decode_parms = decode_parms[0]
732 else:
733 decode_parms = {}
734 if not isinstance(decode_parms, dict):
735 decode_parms = {}
736
737 extension = None
738 if last_filter in (FilterTypes.FLATE_DECODE, FilterTypes.RUN_LENGTH_DECODE):
739 img, image_format, extension, _ = _handle_flate(
740 size,
741 data,
742 mode,
743 color_space,
744 colors,
745 obj_as_text,
746 )
747 elif last_filter in (FilterTypes.LZW_DECODE, FilterTypes.ASCII_85_DECODE):
748 # The filter does not tell which image format the decoded data has, so
749 # let Pillow detect it.
750 try:
751 img = _create_image_from_buffer(buf=BytesIO(data), formats=("TIFF", "PNG"))
752 except UnidentifiedImageError:
753 # Not a TIFF or PNG container: interpret the data as raw pixel samples.
754 fallback_mode, fallback_data = _expand_low_bit_samples(
755 mode, size, data, color_space
756 )
757 img = _create_image_from_bytes(fallback_mode, size, fallback_data)
758 # There is no format information, thus fall back to the usual one
759 # for the filter.
760 image_format = "TIFF" if last_filter == FilterTypes.LZW_DECODE else "PNG"
761 else:
762 image_format = cast(str, img.format)
763 extension = ".tiff" if image_format == "TIFF" else ".png"
764 elif last_filter == FilterTypes.DCT_DECODE:
765 img, image_format, extension = _create_image_from_buffer(buf=BytesIO(data), formats=("JPEG",)), "JPEG", ".jpg"
766 # invert_color kept unchanged
767 elif last_filter == FilterTypes.JPX_DECODE:
768 img, image_format, extension, invert_color = _handle_jpx(
769 size, data, mode, color_space, colors
770 )
771 elif last_filter == FilterTypes.CCITT_FAX_DECODE:
772 img, image_format, extension, invert_color = (
773 _create_image_from_buffer(buf=BytesIO(data), formats=("TIFF",)),
774 "TIFF",
775 ".tiff",
776 False,
777 )
778 elif last_filter == FilterTypes.JBIG2_DECODE:
779 img, image_format, extension, invert_color = (
780 _create_image_from_buffer(buf=BytesIO(data), formats=("PNG", "PPM")),
781 "PNG",
782 ".png",
783 False,
784 )
785 elif mode == "CMYK":
786 img, image_format, extension, invert_color = (
787 _create_image_from_bytes(mode, size, data),
788 "TIFF",
789 ".tif",
790 False,
791 )
792 elif mode == "":
793 raise PdfReadError(f"ColorSpace field not found in {x_object}")
794 else:
795 # Images without a filter (for example inline images) reach Pillow
796 # directly, so low-bit samples have to be expanded here as well.
797 mode, data = _expand_low_bit_samples(mode, size, data, color_space)
798 img, image_format, extension, invert_color = (
799 _create_image_from_bytes(mode, size, data),
800 "PNG",
801 ".png",
802 False,
803 )
804
805 img = _apply_decode(img, x_object, last_filter, color_space, invert_color)
806 img, extension, image_format = _apply_alpha(
807 img=img, x_object=x_object, obj_as_text=obj_as_text, image_format=image_format, extension=extension,
808 visited=visited,
809 )
810
811 if pillow_parameters is None:
812 pillow_parameters = {}
813 # Preserve JPEG image quality - see issue #3515.
814 if image_format == "JPEG":
815 # This prevents: Cannot use 'keep' when original image is not a JPEG:
816 # "JPEG" is the value of PIL.JpegImagePlugin.JpegImageFile.format
817 img.format = "JPEG"
818 if "quality" not in pillow_parameters:
819 pillow_parameters["quality"] = "keep"
820
821 # Save image to bytes
822 img_byte_arr = BytesIO()
823 try:
824 img.save(img_byte_arr, format=image_format, **pillow_parameters)
825 except OSError: # pragma: no cover # covered with pillow 10.3
826 # in case of we convert to RGBA and then to PNG
827 img1 = _convert_image(image=img, mode="RGBA")
828 image_format = "PNG"
829 extension = ".png"
830 img_byte_arr = BytesIO()
831 img1.save(img_byte_arr, format=image_format)
832 data = img_byte_arr.getvalue()
833
834 try:
835 img = _create_image_from_buffer(buf=BytesIO(data), formats=None)
836 except MemoryError: # pragma: no cover # TODO: BLE001
837 raise
838 except Exception as exception:
839 logger_warning("Failed loading image: %(exception)s", source=__name__, exception=exception)
840 img = None # type: ignore[assignment,unused-ignore]
841 return extension, data, img