docling-parse 7.24.0__tar.gz → 7.24.2__tar.gz

{docling_parse-7.24.0 → docling_parse-7.24.2}/CHANGELOG.md

@@ -1,3 +1,16 @@
+## [v7.24.2](https://github.com/docling-project/docling-parse/releases/tag/v7.24.2) - 2026-10-29
+
+### Fix
+
+* Bind take_load_error for the threaded renderer ([#432](https://github.com/docling-project/docling-parse/issues/432)) ([`4ebbb8a`](https://github.com/docling-project/docling-parse/commit/4ebbb8afa3516e2aec1f3d37bf67568fb3deb9ed))
+* **render:** Draw images in /CalGray and /CalRGB colour spaces ([#411](https://github.com/docling-project/docling-parse/issues/411)) ([`4df810b`](https://github.com/docling-project/docling-parse/commit/4df810b4878603dbe64ae8ad2b7c13cb47299480))
+
+## [v7.24.1](https://github.com/docling-project/docling-parse/releases/tag/v7.24.1) - 2026-10-28
+
+### Fix
+
+* **render:** Decode reduced bitmaps again for a finer re-render ([#429](https://github.com/docling-project/docling-parse/issues/429)) ([`436ff5a`](https://github.com/docling-project/docling-parse/commit/436ff5ac0d09f9a994251fb41bc1ff04ceb2f6f4))
+
 ## [v7.24.0](https://github.com/docling-project/docling-parse/releases/tag/v7.24.0) - 2026-10-27
 
 ### Feature

{docling_parse-7.24.0 → docling_parse-7.24.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docling-parse
-Version: 7.24.0
+Version: 7.24.2
 Summary: Simple package to extract text with coordinates from programmatic PDFs
 Author-email: Peter Staar <taa@zurich.ibm.com>, Christoph Auer <cau@zurich.ibm.com>, Michele Dolfi <dol@zurich.ibm.com>, Panos Vagenas <pva@zurich.ibm.com>, Maxim Lysak <mly@zurich.ibm.com>
 License-Expression: MIT

{docling_parse-7.24.0 → docling_parse-7.24.2}/app/pybind_parse.cpp

@@ -1421,6 +1421,23 @@ PYBIND11_MODULE(pdf_parsers, m) {
          pybind11::arg("page_numbers") = pybind11::none(),
          pybind11::arg("page_range") = pybind11::none())
 
+    .def("take_load_error",
+         [](docling::docling_threaded_renderer& self, const std::string& key) -> std::map<std::string, std::string> {
+           return self.take_load_error(key);
+         },
+         pybind11::arg("key"),
+         R"(
+    Return and clear why the last load of `key` failed.
+
+    Parameters:
+        key (str): The key passed to the failed load call.
+
+    Returns:
+        dict[str, str]: {"category": ..., "message": ...}, or an empty dict when
+        no failure is recorded for the key. category is one of "password",
+        "damaged", "unsupported", "io" and "unknown"; message is the text of
+        the underlying (qpdf) error.)")
+
     .def("number_of_pages",
          [](docling::docling_threaded_renderer& self, const std::string& key) -> int {
            return self.number_of_pages(key);

{docling_parse-7.24.0 → docling_parse-7.24.2}/docling_parse/pdf_parser.py

@@ -1218,6 +1218,11 @@ class PageParseResult:
         self._pages: Dict[tuple[int, int, int, int, int, bool], SegmentedPdfPage] = {}
         self._page_decoder: PdfPageDecoder | None = None
         self._default_image: PILImage.Image | None = None
+        # Last image rendered at a non-default scale for a cropped request: OCR
+        # crops several regions of a page at the same scale, and each crop would
+        # re-render the page. Full-page requests are not kept: callers such as
+        # Docling cache those already, and one per live page adds up quickly.
+        self._scaled_image: tuple[float, PILImage.Image] | None = None
 
         self.doc_key: str = raw_result.doc_key
         self.page_number: int = raw_result.page_number + 1
@@ -1448,7 +1453,9 @@ class PageParseResult:
             )
         return self._default_image
 
-    def _render_image_at_scale(self, scale: float) -> PILImage.Image:
+    def _render_image_at_scale(self, scale: float, cache: bool) -> PILImage.Image:
+        if self._scaled_image is not None and self._scaled_image[0] == scale:
+            return self._scaled_image[1]
         page_decoder = self._require_page_decoder()
         render_config = self._rendering_config()
         render_config.scale = scale
@@ -1459,7 +1466,10 @@ class PageParseResult:
             raise RuntimeError(
                 f"Rendered image is empty for page {self.page_number} of {self.doc_key}"
             )
-        return self._image_from_bytes(raw_bytes, image_shape)
+        image = self._image_from_bytes(raw_bytes, image_shape)
+        if cache:
+            self._scaled_image = (scale, image)
+        return image
 
     def _render_image_at_canvas_size(
         self, canvas_size: tuple[int, int]
@@ -1519,7 +1529,7 @@ class PageParseResult:
             ):
                 image = self._get_default_image()
             else:
-                image = self._render_image_at_scale(scale)
+                image = self._render_image_at_scale(scale, cache=cropbox is not None)
         else:
             assert canvas_size is not None
             if canvas_size[0] <= 0 or canvas_size[1] <= 0:

{docling_parse-7.24.0 → docling_parse-7.24.2}/docling_parse.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docling-parse
-Version: 7.24.0
+Version: 7.24.2
 Summary: Simple package to extract text with coordinates from programmatic PDFs
 Author-email: Peter Staar <taa@zurich.ibm.com>, Christoph Auer <cau@zurich.ibm.com>, Michele Dolfi <dol@zurich.ibm.com>, Panos Vagenas <pva@zurich.ibm.com>, Maxim Lysak <mly@zurich.ibm.com>
 License-Expression: MIT

{docling_parse-7.24.0 → docling_parse-7.24.2}/docling_parse.egg-info/SOURCES.txt

@@ -738,6 +738,7 @@ tests/conftest.py
 tests/constants.py
 tests/data_utils.py
 tests/groundtruth_io.py
+tests/image_fixtures.py
 tests/outline_fixtures.py
 tests/pdf_builder.py
 tests/regression_page_selection.py
@@ -746,12 +747,14 @@ tests/test_regression_cell_contraction.py
 tests/test_regression_embedded_fonts.py
 tests/test_regression_locale_safety.py
 tests/test_regression_parse.py
+tests/test_regression_pypdfium_cited_pages.py
 tests/test_regression_pypdfium_render.py
 tests/test_regression_threaded_parse.py
 tests/test_regression_threaded_render.py
 tests/test_unit_acroform_widgets.py
 tests/test_unit_actual_text.py
 tests/test_unit_bitmap_artifacts.py
+tests/test_unit_cal_colorspace_images.py
 tests/test_unit_ccitt_images.py
 tests/test_unit_cid_to_gid_map.py
 tests/test_unit_cjk_fonts.py
@@ -776,6 +779,7 @@ tests/test_unit_nul_mapping.py
 tests/test_unit_page_count.py
 tests/test_unit_patterns.py
 tests/test_unit_quote_sanitization.py
+tests/test_unit_rerender_reduced_bitmaps.py
 tests/test_unit_rotated_cell_contraction.py
 tests/test_unit_shading.py
 tests/test_unit_shadings.py

{docling_parse-7.24.0 → docling_parse-7.24.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "docling-parse"
-version = "7.24.0"
+version = "7.24.2"
 description = "Simple package to extract text with coordinates from programmatic PDFs"
 license = "MIT"
 keywords = ["docling", "pdf", "parser"]

{docling_parse-7.24.0 → docling_parse-7.24.2}/src/parse/config.h

@@ -74,6 +74,10 @@ namespace pdflib
     // magnify what it used to minify. Rendered output does change: the
     // discarded resolution levels are ones the rasteriser would have
     // resampled away, but not with the same filter the codec uses.
+    //
+    // A later render of the same instructions at a finer resolution decodes
+    // the reduced images again from their encoded bytes, so it matches a
+    // render whose decode was sized for it (bitmap_instruction::redecoded_for).
     double bitmap_target_pixels_per_unit = 0.0;
 
     // threading

{docling_parse-7.24.0 → docling_parse-7.24.2}/src/parse/page_items/render_instructions.h

@@ -5,6 +5,8 @@
 
 #include <algorithm>
 #include <cstdint>
+#include <functional>
+#include <optional>
 #include <string>
 #include <vector>
 #include <array>
@@ -29,6 +31,15 @@ namespace pdflib
     CMYK_CONVENTION_PROCESS,
   };
 
+  // The decoded samples of one image, as a bitmap_instruction carries them.
+  struct bitmap_samples
+  {
+    std::shared_ptr<std::vector<uint8_t> > data;
+    std::array<int, 3> shape = {0, 0, 0};
+    pixel_format fmt = PIXEL_FORMAT_UNKNOWN;
+    cmyk_convention cmyk_conv = CMYK_CONVENTION_UNKNOWN;
+  };
+
   enum clip_rule {
     CLIP_RULE_NONE,
     CLIP_RULE_NONZERO,
@@ -585,18 +596,58 @@ namespace pdflib
     void set_filters(std::vector<std::string> filters) { filters_ = std::move(filters); }
     const std::vector<std::string>& get_filters() const { return filters_; }
 
+    // Set when the samples were decoded at a reduced resolution, sized for a
+    // render at `pixels_per_unit` (decode_config::bitmap_target_pixels_per_unit).
+    // `redecode` decodes the image again for a finer target and returns empty
+    // samples when the stored ones already cover it. It holds the encoded
+    // bytes the page keeps anyway, never full-resolution pixels.
+    void set_redecoder(double pixels_per_unit,
+                       std::function<bitmap_samples(double)> redecode)
+    {
+      decoded_for_pixels_per_unit_ = pixels_per_unit;
+      redecode_ = std::move(redecode);
+    }
+
+    // A copy of this instruction with samples decoded for a render at
+    // `pixels_per_unit`, when the stored ones were reduced below what that
+    // render needs; otherwise nothing, and the stored samples are drawn.
+    std::optional<bitmap_instruction> redecoded_for(double pixels_per_unit) const
+    {
+      if(not redecode_ or pixels_per_unit <= decoded_for_pixels_per_unit_)
+        {
+          return std::nullopt;
+        }
+
+      bitmap_samples samples = redecode_(pixels_per_unit);
+      if(not samples.data or samples.data->empty())
+        {
+          return std::nullopt;
+        }
+
+      bitmap_instruction sharper(*this);
+      sharper.data = std::move(samples.data);
+      sharper.shape = samples.shape;
+      sharper.fmt = samples.fmt;
+      sharper.cmyk_conv = samples.cmyk_conv;
+      sharper.redecode_ = nullptr;
+      return sharper;
+    }
+
   private:
 
+    double decoded_for_pixels_per_unit_ = 0.0;
+    std::function<bitmap_samples(double)> redecode_;
+
     blend_mode_name blend_mode_ = BLEND_MODE_NORMAL;
     std::vector<std::string> filters_;
 
     const std::string xobject_key;
     
-    const std::shared_ptr<std::vector<uint8_t> > data;
+    std::shared_ptr<std::vector<uint8_t> > data;
     const std::shared_ptr<std::vector<uint8_t> > alpha_data;
-    const cmyk_convention cmyk_conv;
-    const std::array<int, 3> shape;
-    const pixel_format fmt;
+    cmyk_convention cmyk_conv;
+    std::array<int, 3> shape;
+    pixel_format fmt;
     const bool image_mask;
     const std::array<int, 3> rgb_filling;
     const double fill_alpha;

{docling_parse-7.24.0 → docling_parse-7.24.2}/src/parse/pdf_resources/page_xobject_image.h

@@ -19,6 +19,15 @@ namespace pdflib
 
   namespace detail
   {
+    // [/CalGray dict] and [/CalRGB dict] samples read as their device space; the
+    // calibration (WhitePoint, Gamma, Matrix) is not modelled. Other names pass through.
+    inline std::string cal_to_device_space(std::string const& name)
+    {
+      if(name == "/CalGray") return "/DeviceGray";
+      if(name == "/CalRGB")  return "/DeviceRGB";
+      return name;
+    }
+
     inline int icc_signature_to_components(char const* sig)
     {
       if(std::memcmp(sig, "GRAY", 4) == 0) return 1;
@@ -616,7 +625,7 @@ namespace pdflib
                           }
                         else if(base_name.isName())
                           {
-                            indexed_base_cs = base_name.getName();
+                            indexed_base_cs = detail::cal_to_device_space(base_name.getName());
                             LOG_S(INFO) << "Indexed array base color space: " << indexed_base_cs;
                           }
 
@@ -780,6 +789,12 @@ namespace pdflib
                           }
                       }
                   }
+                else if(name_obj.isName()
+                        and (name_obj.getName() == "/CalGray" or name_obj.getName() == "/CalRGB"))
+                  {
+                    color_space = detail::cal_to_device_space(name_obj.getName());
+                    LOG_S(INFO) << "reading " << name_obj.getName() << " samples as " << color_space;
+                  }
               }
           }
       }

{docling_parse-7.24.0 → docling_parse-7.24.2}/src/parse/pdf_states/bitmap.h

@@ -207,6 +207,12 @@ namespace pdflib
                                 clip_state_instruction clip_state,
                                 bitmap_source source);
 
+    // Decodes the image's samples, at 1/2^decode_reduction_shift of the
+    // stored resolution where the codec supports it. Depends on nothing but
+    // the image, so a bitmap_instruction can call it again at render time.
+    static bitmap_samples decode_samples(const page_item<PAGE_IMAGE>& image,
+                                         int decode_reduction_shift);
+
     void populate_geometry(page_item<PAGE_IMAGE>& image,
                            const clip_state_instruction& clip_state) const;
 
@@ -576,13 +582,6 @@ namespace pdflib
                                                  clip_state_instruction clip_state,
                                                  bitmap_source source)
   {
-    std::shared_ptr<std::vector<uint8_t>> pixel_data;
-    std::array<int, 3> pixel_shape = {0, 0, 0};
-    pixel_format fmt = PIXEL_FORMAT_UNKNOWN;
-    cmyk_convention cmyk_conv = CMYK_CONVENTION_UNKNOWN;
-
-    int channels = 0;
-
     // An oversampled image is decoded down to the resolution it is drawn at,
     // when the codec can do that natively. Three cases are held back:
     //
@@ -610,6 +609,73 @@ namespace pdflib
                                       image.image_height,
                                       config.bitmap_target_pixels_per_unit)
       : 0;
+
+    bitmap_samples samples = decode_samples(image, decode_reduction_shift);
+
+    bitmap_instruction binstr(image.xobject_key,
+                              std::move(samples.data),
+                              image.soft_mask_data,
+                              samples.cmyk_conv,
+                              samples.shape,
+                              samples.fmt,
+                              image.image_mask,
+                              image.rgb_filling_ops,
+                              grph_state.get_fill_alpha(),
+                              image.r_x0, image.r_y0,
+                              image.r_x1, image.r_y1,
+                              image.r_x2, image.r_y2,
+                              image.r_x3, image.r_y3,
+                              source,
+                              std::move(clip_state));
+    binstr.set_blend_mode(grph_state.get_blend_mode());
+    binstr.set_filters(image.filters);
+
+    // The reduced samples fit a render at the configured scale only. A later
+    // render at a finer scale (PageParseResult.get_image(scale=...)) decodes
+    // the image again from its encoded bytes, which the page keeps anyway.
+    //
+    // Only /DCTDecode and /JPXDecode honour the shift. Every other branch
+    // (Flate, raw, CCITT, JBIG2, or a stream QPDF already decoded) returns
+    // full-resolution samples, which a finer render would only decode again
+    // unchanged, so the re-decoder is kept for samples that really are reduced.
+    const auto& decoded_shape = binstr.get_shape();
+    const bool samples_reduced =
+      binstr.has_data()
+      and (decoded_shape[0] < image.image_height
+           or decoded_shape[1] < image.image_width);
+
+    if(decode_reduction_shift > 0 and samples_reduced)
+      {
+        binstr.set_redecoder(
+          config.bitmap_target_pixels_per_unit,
+          [image, decode_reduction_shift](double target_pixels_per_unit) -> bitmap_samples
+          {
+            const int shift = detail::codec_reduction_shift(image.x1 - image.x0,
+                                                            image.y1 - image.y0,
+                                                            image.image_width,
+                                                            image.image_height,
+                                                            target_pixels_per_unit);
+            if(shift >= decode_reduction_shift)
+              {
+                return {};
+              }
+            return decode_samples(image, shift);
+          });
+      }
+
+    instructions.add_bitmap_instruction(std::move(binstr));
+  }
+
+  bitmap_samples pdf_state<BITMAP>::decode_samples(const page_item<PAGE_IMAGE>& image,
+                                                   int decode_reduction_shift)
+  {
+    std::shared_ptr<std::vector<uint8_t>> pixel_data;
+    std::array<int, 3> pixel_shape = {0, 0, 0};
+    pixel_format fmt = PIXEL_FORMAT_UNKNOWN;
+    cmyk_convention cmyk_conv = CMYK_CONVENTION_UNKNOWN;
+
+    int channels = 0;
+
     auto has_default_adobe_cmyk_decode = [&](std::vector<double> const& decode_array) -> bool
       {
         static constexpr double expected_decode[8] = {
@@ -1623,25 +1689,7 @@ namespace pdflib
           }
       }
 
-    bitmap_instruction binstr(image.xobject_key,
-                              std::move(pixel_data),
-                              image.soft_mask_data,
-                              cmyk_conv,
-                              pixel_shape,
-                              fmt,
-                              image.image_mask,
-                              image.rgb_filling_ops,
-                              grph_state.get_fill_alpha(),
-                              image.r_x0, image.r_y0,
-                              image.r_x1, image.r_y1,
-                              image.r_x2, image.r_y2,
-                              image.r_x3, image.r_y3,
-                              source,
-                              std::move(clip_state));
-    binstr.set_blend_mode(grph_state.get_blend_mode());
-    binstr.set_filters(image.filters);
-
-    instructions.add_bitmap_instruction(std::move(binstr));
+    return {std::move(pixel_data), pixel_shape, fmt, cmyk_conv};
   }
 
 }

{docling_parse-7.24.0 → docling_parse-7.24.2}/src/render/blend2d_renderer.h

@@ -3385,6 +3385,16 @@ namespace pdflib
 
   inline void renderer<BLEND2D>::render_bitmap(bitmap_instruction& instr)
   {
+    // Samples decoded down for a coarser render are decoded again when this
+    // render is finer, so a re-render at a larger scale is not upscaled.
+    const double pixels_per_unit =
+      config_.scale > 0.0f ? config_.scale : std::max(scale_x_, scale_y_);
+    if (auto sharper = instr.redecoded_for(pixels_per_unit))
+      {
+        render_bitmap(*sharper);
+        return;
+      }
+
     utils::scoped_timer phase_timer(timings_, pdf_timings::KEY_RENDER_BITMAP);
 
     LOG_S(INFO) << __FUNCTION__ << " for xobject_key=" << instr.get_key();

{docling_parse-7.24.0 → docling_parse-7.24.2}/tests/constants.py

@@ -1,7 +1,7 @@
 from tests.regression_page_selection import REGRESSION_PAGE_SELECTION
 
 HF_DATASET_REPO_ID = "docling-project/regression-dataset-for-docling-parse"
-HF_DATASET_REVISION = "21374211ec8e84cb58eea3c62f869c2adfcc9a54"
+HF_DATASET_REVISION = "bc46a476692b0b035112d2e47a64843fdfb6337b"
 
 REGRESSION_DIR = "tests/data/regression"
 

docling_parse-7.24.2/tests/image_fixtures.py

@@ -0,0 +1,47 @@
+#!/usr/bin/env python
+"""Image sample data for the unit fixtures.
+
+The codestreams come from a real encoder (Pillow's) rather than from a test's
+own understanding of one, so a renderer that disagrees with them disagrees with
+the encoder, not with this file.
+"""
+
+from __future__ import annotations
+
+import io
+from collections.abc import Sequence
+
+from PIL import Image, TiffImagePlugin
+
+
+def middle_half(extent: int) -> range:
+    return range(extent // 4, 3 * extent // 4)
+
+
+def g4_codes(
+    columns: int, rows: int, ink_columns: Sequence[range], ink_rows: range
+) -> bytes:
+    """Group 4 codes for bands of ink, `columns` pixels to the row.
+
+    Pillow writes a mode-"1" image with photometric=BlackIsZero, which makes
+    its *0* pixels the codestream's white runs. A PDF reads the opposite way
+    round under the default /BlackIs1 false, where a decoded 0 bit is black, so
+    the image handed to Pillow is the inverse of the samples wanted back.
+    """
+    image = Image.new("1", (columns, rows), 0)
+    for y in ink_rows:
+        for band in ink_columns:
+            for x in band:
+                image.putpixel((x, y), 1)
+
+    buffer = io.BytesIO()
+    image.save(buffer, format="TIFF", compression="group4")
+
+    tiff = Image.open(io.BytesIO(buffer.getvalue()))
+    # Only a TIFF carries the strip tags this reads back out.
+    assert isinstance(tiff, TiffImagePlugin.TiffImageFile)
+
+    offsets, counts = tiff.tag_v2[273], tiff.tag_v2[279]
+    assert len(offsets) == 1, "the fixture wants one strip, i.e. one codestream"
+
+    return buffer.getvalue()[offsets[0] : offsets[0] + counts[0]]

docling_parse-7.24.2/tests/test_regression_pypdfium_cited_pages.py

@@ -0,0 +1,93 @@
+#!/usr/bin/env python
+"""Enforced comparison against pypdfium2 on the pages that rendering fixes cite.
+
+`test_regression_pypdfium_render.py` reports how the whole corpus compares with
+pypdfium2 but never fails. This file holds the pages a rendering fix was shown
+on: each one must stay within its own tolerance of pypdfium2, so the fix cannot
+regress unnoticed. A fix adds its pages here, with a tolerance that fails on the
+code before the fix.
+"""
+
+from pathlib import Path
+
+import pytest
+
+from tests.rendering_regression import (
+    ImageTolerance,
+    flatten_on_white,
+    image_comparison_failed,
+    measure_image_pair,
+    render_pypdfium_page,
+)
+from tests.test_regression_pypdfium_render import (
+    PYPDFIUM_RENDER_SCALE,
+    _make_pypdfium_render_config,
+)
+from tests.test_regression_threaded_render import _make_parser
+
+REGRESSION_DIR = Path("tests/data/regression")
+
+CITED_PAGES = [
+    # A /CalRGB JPEG image XObject. It was drawn as the semi-transparent yellow
+    # "missing image" placeholder (mean_abs_error 5.10, changed_pixels_ratio
+    # 0.131 before the fix; 0.26 and 0.0045 after it).
+    pytest.param(
+        "dln_23cb379bc6159a37e5488b65bb08ad295ce3ff21d9ddf682064330594ad59db3.pdf",
+        1,
+        ImageTolerance(
+            pixel_threshold=12, mean_abs_error=1.0, changed_pixels_ratio=0.02
+        ),
+        id="calrgb-image",
+    ),
+    # docling#4861: a scanned invoice written as a /CalGray CCITT Group 4 image
+    # by an image-to-PDF converter. It was drawn as the yellow placeholder, so
+    # OCR on the rendered page found nothing (mean_abs_error 38.1, changed_pixels_ratio
+    # 0.111 before the fix; 3.30 and 0.051 after it, the rest being how the 1-bit
+    # scan is anti-aliased when downsampled).
+    pytest.param(
+        "APT002_issue_calibrated_gray_colorspace.pdf",
+        1,
+        ImageTolerance(
+            pixel_threshold=12, mean_abs_error=5.0, changed_pixels_ratio=0.08
+        ),
+        id="calgray-fax-scan",
+    ),
+]
+
+
+@pytest.mark.parametrize(("document", "page", "tolerance"), CITED_PAGES)
+def test_cited_page_matches_pypdfium(
+    document: str, page: int, tolerance: ImageTolerance
+) -> None:
+    pytest.importorskip(
+        "pypdfium2",
+        reason="pypdfium2 is required for the cross-renderer comparison",
+    )
+    pdf_path = REGRESSION_DIR / document
+
+    parser = _make_parser(render_config=_make_pypdfium_render_config())
+    doc_key = parser.load(str(pdf_path), page_numbers=[page])
+    results = list(parser.iterate_results())
+    parser.unload_all()
+
+    assert len(results) == 1
+    result = results[0]
+    assert result.doc_key == doc_key
+    assert result.success, result.error_message
+
+    reference = render_pypdfium_page(pdf_path, page, scale=PYPDFIUM_RENDER_SCALE)
+    comparison = measure_image_pair(
+        document,
+        page,
+        flatten_on_white(result.get_image()),
+        flatten_on_white(reference),
+        tolerance=tolerance,
+    )
+
+    assert not image_comparison_failed(comparison, tolerance=tolerance), (
+        f"{document}@{page}: mean_abs_error={comparison.mean_abs_error:.4f} "
+        f"(limit {tolerance.mean_abs_error}), "
+        f"changed_pixels_ratio={comparison.changed_pixels_ratio:.4f} "
+        f"(limit {tolerance.changed_pixels_ratio}), "
+        f"size_matches={comparison.size_matches}"
+    )