Source code

Download source archive ↓

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