docling-parse 6.1.0__tar.gz → 6.2.0__tar.gz

{docling_parse-6.1.0 → docling_parse-6.2.0}/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [v6.2.0](https://github.com/docling-project/docling-parse/releases/tag/v6.2.0) - 2026-05-28
+
+### Feature
+
+* Add materialize_bitmap_bytes flag to skip bitmap byte extraction ([#277](https://github.com/docling-project/docling-parse/issues/277)) ([`918d7b9`](https://github.com/docling-project/docling-parse/commit/918d7b90911403fd2e9fec3eb5550ebaf4590e89))
+
 ## [v6.1.0](https://github.com/docling-project/docling-parse/releases/tag/v6.1.0) - 2026-05-26
 
 ### Feature

{docling_parse-6.1.0 → docling_parse-6.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docling-parse
-Version: 6.1.0
+Version: 6.2.0
 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-6.1.0 → docling_parse-6.2.0}/app/pybind_parse.cpp

@@ -269,13 +269,14 @@ PYBIND11_MODULE(pdf_parsers, m) {
     Attributes:
         page_boundary (str): The page boundary specification [choices: crop_box, media_box].
         do_sanitization (bool): Sanitize the chars into lines [default=true].
-        keep_char_cells (bool): Keep all the individual char cells [default=true].
+        keep_char_cells (bool): Expose individual char cells in the decoded output. Internal base text cells are still built when words or lines are requested [default=true].
         keep_shapes (bool): Keep all the graphic shapes [default=true].
         keep_bitmaps (bool): Keep all the bitmap resources [default=true].
         max_num_lines (int): Maximum number of lines to keep (-1 means no cap) [default=-1].
         max_num_bitmaps (int): Maximum number of bitmaps to keep (-1 means no cap) [default=-1].
         keep_glyphs (bool): If true, keep GLYPH<...> fallback strings in output; if false, replace them with a space [default=false].
         keep_qpdf_warnings (bool): If true, QPDF warnings are emitted; if false, they are suppressed [default=false].
+        materialize_bitmap_bytes (bool): If true (default), bitmap byte data is extracted and embedded in BitmapResource objects. If false, only bitmap geometry (rectangles) is preserved and image bytes are skipped. Consumed by the Python layer only; has no effect in C++ [default=true].
     )")
     .def(pybind11::init<>())
     .def_readwrite("page_boundary", &pdflib::decode_config::page_boundary)
@@ -295,7 +296,10 @@ PYBIND11_MODULE(pdf_parsers, m) {
     .def_readwrite("do_thread_safe", &pdflib::decode_config::do_thread_safe)
     .def_readwrite("release_native_memory_every_n_pages", &pdflib::decode_config::release_native_memory_every_n_pages)
     .def_readwrite("keep_glyphs", &pdflib::decode_config::keep_glyphs)
-    .def_readwrite("keep_qpdf_warnings", &pdflib::decode_config::keep_qpdf_warnings);
+    .def_readwrite("keep_qpdf_warnings", &pdflib::decode_config::keep_qpdf_warnings)
+    .def_readwrite("materialize_bitmap_bytes", &pdflib::decode_config::materialize_bitmap_bytes)
+    .def("__copy__", [](const pdflib::decode_config& self) { return self; })
+    .def("__deepcopy__", [](const pdflib::decode_config& self, pybind11::dict) { return self; });
 
   // ============= Typed Resource Bindings (for zero-copy access) =============
 

{docling_parse-6.1.0 → docling_parse-6.2.0}/docling_parse/pdf_parser.py

@@ -1,5 +1,6 @@
 """Parser for PDF files"""
 
+import copy
 import hashlib
 import logging
 import math
@@ -366,46 +367,52 @@ def _to_hyperlinks_from_decoder(hyperlinks_container) -> List[PdfHyperlink]:
     return result
 
 
-def _to_bitmap_resources_from_decoder(images_container) -> List[BitmapResource]:
+def _to_bitmap_resources_from_decoder(
+    images_container,
+    materialize_bitmap_bytes: bool = True,
+) -> List[BitmapResource]:
     result: List[BitmapResource] = []
 
     for ind, image in enumerate(images_container):
         image_ref = None
         mode = ImageRefMode.PLACEHOLDER
 
-        try:
-            image_bytes = image.get_image_as_bytes()
-
-            if image_bytes and len(image_bytes) > 0:
-                fmt = image.get_image_format()
-                pil_image: PILImage.Image | None = None
-
-                if fmt in ("jpeg", "jp2"):
-                    pil_image = PILImage.open(BytesIO(image_bytes))
-                elif fmt in ("raw", "jbig2"):
-                    pil_mode = image.get_pil_mode()
-                    w = image.image_width
-                    h = image.image_height
-                    if w > 0 and h > 0:
-                        pil_image = PILImage.frombytes(pil_mode, (w, h), image_bytes)
-
-                if pil_image is not None:
-                    if pil_image.mode != "RGBA":
-                        pil_image = pil_image.convert("RGBA")
-
-                    bbox_width = abs(image.x1 - image.x0)
-                    if bbox_width > 0 and image.image_width > 0:
-                        dpi = round(image.image_width * 72.0 / bbox_width)
-                    else:
-                        dpi = 72
-
-                    image_ref = ImageRef.from_pil(pil_image, dpi=dpi)
-                    mode = ImageRefMode.EMBEDDED
-
-        except Exception:
-            _log.debug(
-                "Failed to extract image data for bitmap, falling back to placeholder"
-            )
+        if materialize_bitmap_bytes:
+            try:
+                image_bytes = image.get_image_as_bytes()
+
+                if image_bytes and len(image_bytes) > 0:
+                    fmt = image.get_image_format()
+                    pil_image: PILImage.Image | None = None
+
+                    if fmt in ("jpeg", "jp2"):
+                        pil_image = PILImage.open(BytesIO(image_bytes))
+                    elif fmt in ("raw", "jbig2"):
+                        pil_mode = image.get_pil_mode()
+                        w = image.image_width
+                        h = image.image_height
+                        if w > 0 and h > 0:
+                            pil_image = PILImage.frombytes(
+                                pil_mode, (w, h), image_bytes
+                            )
+
+                    if pil_image is not None:
+                        if pil_image.mode != "RGBA":
+                            pil_image = pil_image.convert("RGBA")
+
+                        bbox_width = abs(image.x1 - image.x0)
+                        if bbox_width > 0 and image.image_width > 0:
+                            dpi = round(image.image_width * 72.0 / bbox_width)
+                        else:
+                            dpi = 72
+
+                        image_ref = ImageRef.from_pil(pil_image, dpi=dpi)
+                        mode = ImageRefMode.EMBEDDED
+
+            except Exception:
+                _log.debug(
+                    "Failed to extract image data for bitmap, falling back to placeholder"
+                )
 
         result.append(
             BitmapResource(
@@ -432,6 +439,7 @@ def _to_bitmap_resources_from_decoder(images_container) -> List[BitmapResource]:
 def segmented_page_from_decoder(
     page_decoder: PdfPageDecoder,
     boundary_type: PdfPageBoundaryType = PdfPageBoundaryType.CROP_BOX,
+    materialize_bitmap_bytes: bool = True,
 ) -> SegmentedPdfPage:
     """Convert a C++ PdfPageDecoder to a SegmentedPdfPage."""
     char_cells = _to_cells_from_decoder(page_decoder.get_char_cells())
@@ -445,7 +453,8 @@ def segmented_page_from_decoder(
         textline_cells=[],
         has_chars=len(char_cells) > 0,
         bitmap_resources=_to_bitmap_resources_from_decoder(
-            page_decoder.get_page_images()
+            page_decoder.get_page_images(),
+            materialize_bitmap_bytes=materialize_bitmap_bytes,
         ),
         shapes=_to_shapes_from_decoder(page_decoder.get_page_shapes()),
         widgets=_to_widgets_from_decoder(page_decoder.get_page_widgets()),
@@ -492,7 +501,7 @@ class PdfDocument:
         self._parser: pdf_parser = parser
         self._key = key
         self._boundary_type = boundary_type
-        self._pages: Dict[int, SegmentedPdfPage] = {}
+        self._pages: Dict[tuple[int, bool], SegmentedPdfPage] = {}
         self._toc: PdfTableOfContents | None = None
         self._meta: PdfMetaData | None = None
         self._annotations: PdfAnnotations | None = None
@@ -520,11 +529,13 @@ class PdfDocument:
             if page_no < 1:
                 _log.error("page_no should always be >=1!")
 
-            if page_no in self._pages:
+            cache_keys = [k for k in self._pages if k[0] == page_no]
+            if cache_keys:
                 # we are using 0 indexing in the C++ docling-parse!
                 page_num = page_no - 1
                 self._parser.unload_document_page(key=self._key, page=page_num)
-                del self._pages[page_no]
+                for k in cache_keys:
+                    del self._pages[k]
 
     def number_of_pages(self) -> int:
         if self.is_loaded():
@@ -702,6 +713,7 @@ class PdfDocument:
 
         segmented_page = self._to_segmented_page_from_decoder(
             page_decoder=page_decoder,
+            materialize_bitmap_bytes=config.materialize_bitmap_bytes,
         )
 
         # Get timings from the page decoder
@@ -740,19 +752,26 @@ class PdfDocument:
         return _to_hyperlinks_from_decoder(hyperlinks_container)
 
     def _to_bitmap_resources_from_decoder(
-        self, images_container
+        self,
+        images_container,
+        materialize_bitmap_bytes: bool = True,
     ) -> List[BitmapResource]:
         """Convert typed PdfImages container to list of BitmapResource objects."""
-        return _to_bitmap_resources_from_decoder(images_container)
+        return _to_bitmap_resources_from_decoder(
+            images_container,
+            materialize_bitmap_bytes=materialize_bitmap_bytes,
+        )
 
     def _to_segmented_page_from_decoder(
         self,
         page_decoder,
+        materialize_bitmap_bytes: bool = True,
     ) -> SegmentedPdfPage:
         """Convert typed PdfPageDecoder to SegmentedPdfPage (zero-copy path)."""
         return segmented_page_from_decoder(
             page_decoder=page_decoder,
             boundary_type=self._boundary_type,
+            materialize_bitmap_bytes=materialize_bitmap_bytes,
         )
 
     def _get_page_typed(
@@ -773,8 +792,9 @@ class PdfDocument:
         Returns:
             SegmentedPdfPage with the parsed page data.
         """
-        if page_no in self._pages.keys():
-            return self._pages[page_no]
+        cache_key = (page_no, config.materialize_bitmap_bytes)
+        if cache_key in self._pages:
+            return self._pages[cache_key]
 
         if 1 <= page_no <= self.number_of_pages():
             page_decoder = self._parser.get_page_decoder(
@@ -786,10 +806,11 @@ class PdfDocument:
             if page_decoder is None:
                 raise ValueError(f"Failed to decode page {page_no}")
 
-            self._pages[page_no] = self._to_segmented_page_from_decoder(
+            self._pages[cache_key] = self._to_segmented_page_from_decoder(
                 page_decoder=page_decoder,
+                materialize_bitmap_bytes=config.materialize_bitmap_bytes,
             )
-            return self._pages[page_no]
+            return self._pages[cache_key]
 
         raise ValueError(
             f"incorrect page_no: {page_no} for key={self._key} (min:1, max:{self.number_of_pages()})"
@@ -923,10 +944,12 @@ class PageParseResult:
         *,
         boundary_type: PdfPageBoundaryType,
         render_config: RenderConfig | None,
+        decode_config: DecodePageConfig,
     ):
         self._raw = raw_result
         self._boundary_type = boundary_type
         self._render_config = render_config
+        self._decode_config = decode_config
         self._page: SegmentedPdfPage | None = None
         self._page_decoder: PdfPageDecoder | None = None
         self._default_image: PILImage.Image | None = None
@@ -972,6 +995,7 @@ class PageParseResult:
             self._page = segmented_page_from_decoder(
                 page_decoder=self._require_page_decoder(),
                 boundary_type=self._boundary_type,
+                materialize_bitmap_bytes=self._decode_config.materialize_bitmap_bytes,
             )
         return self._page
 
@@ -1113,31 +1137,6 @@ class PageParseResult:
         return self._require_page_decoder().export_bitmap_artifacts()
 
 
-def _copy_decode_config(src: DecodePageConfig) -> DecodePageConfig:
-    dst = DecodePageConfig()
-    dst.page_boundary = src.page_boundary
-    dst.do_sanitization = src.do_sanitization
-    dst.keep_char_cells = src.keep_char_cells
-    dst.keep_shapes = src.keep_shapes
-    dst.keep_bitmaps = src.keep_bitmaps
-    dst.max_num_lines = src.max_num_lines
-    dst.max_num_bitmaps = src.max_num_bitmaps
-    dst.create_word_cells = src.create_word_cells
-    dst.create_line_cells = src.create_line_cells
-    dst.enforce_same_font = src.enforce_same_font
-    dst.horizontal_cell_tolerance = src.horizontal_cell_tolerance
-    dst.word_space_width_factor_for_merge = src.word_space_width_factor_for_merge
-    dst.line_space_width_factor_for_merge = src.line_space_width_factor_for_merge
-    dst.line_space_width_factor_for_merge_with_space = (
-        src.line_space_width_factor_for_merge_with_space
-    )
-    dst.do_thread_safe = src.do_thread_safe
-    dst.release_native_memory_every_n_pages = src.release_native_memory_every_n_pages
-    dst.keep_glyphs = src.keep_glyphs
-    dst.keep_qpdf_warnings = src.keep_qpdf_warnings
-    return dst
-
-
 def _copy_render_config(src: RenderConfig) -> RenderConfig:
     dst = RenderConfig()
     dst.render_text = src.render_text
@@ -1189,7 +1188,7 @@ class DoclingThreadedPdfParser:
                 parser_config.render_config
             )
         self._decode_config = (
-            _copy_decode_config(decode_config)
+            copy.copy(decode_config)
             if decode_config is not None
             else DecodePageConfig()
         )
@@ -1318,4 +1317,5 @@ class DoclingThreadedPdfParser:
             self._parser.get_task(),
             boundary_type=self._parser_config.boundary_type,
             render_config=self._parser_config.render_config,
+            decode_config=self._decode_config,
         )

{docling_parse-6.1.0 → docling_parse-6.2.0}/docling_parse.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docling-parse
-Version: 6.1.0
+Version: 6.2.0
 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-6.1.0 → docling_parse-6.2.0}/docling_parse.egg-info/SOURCES.txt

@@ -540,6 +540,7 @@ src/parse/pdf_states/grph.h
 src/parse/pdf_states/shape.h
 src/parse/pdf_states/text.h
 src/parse/qpdf/annots.h
+src/parse/qpdf/logger.h
 src/parse/qpdf/qpdf_compat.h
 src/parse/qpdf/stream_decoder.h
 src/parse/qpdf/stream_instruction.h

{docling_parse-6.1.0 → docling_parse-6.2.0}/pyproject.toml

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

{docling_parse-6.1.0 → docling_parse-6.2.0}/src/parse/config.h

@@ -39,10 +39,13 @@ namespace pdflib
     bool do_thread_safe = true; // slight compute/memory overhead in single threaded case
     int release_native_memory_every_n_pages = 0; // 0 disables allocator trimming
 
-    // debug: in production, we dont want to have ugly GLYPH<...> 
+    // debug: in production, we dont want to have ugly GLYPH<...>
     bool keep_glyphs = false;
     bool keep_qpdf_warnings = false;
-    
+
+    // consumed by Python layer only; C++ ignores this field
+    bool materialize_bitmap_bytes = true;
+
     nlohmann::json to_json() const;
     void from_json(const nlohmann::json& j);
 
@@ -83,6 +86,7 @@ namespace pdflib
 
     j["keep_glyphs"] = keep_glyphs;
     j["keep_qpdf_warnings"] = keep_qpdf_warnings;
+    j["materialize_bitmap_bytes"] = materialize_bitmap_bytes;
 
     return j;
   }
@@ -116,6 +120,7 @@ namespace pdflib
 
     if(j.count("keep_glyphs")) { keep_glyphs = j["keep_glyphs"]; }
     if(j.count("keep_qpdf_warnings")) { keep_qpdf_warnings = j["keep_qpdf_warnings"]; }
+    if(j.count("materialize_bitmap_bytes")) { materialize_bitmap_bytes = j["materialize_bitmap_bytes"]; }
   }
 
   bool decode_config::load(const std::string& filename)
@@ -169,7 +174,8 @@ namespace pdflib
        << std::setw(48) << "populate_json_objects" << (populate_json_objects ? "true" : "false") << "\n"
        << std::setw(48) << "release_native_memory_every_n_pages" << release_native_memory_every_n_pages << "\n"
        << std::setw(48) << "keep_glyphs" << (keep_glyphs ? "true" : "false") << "\n"
-       << std::setw(48) << "keep_qpdf_warnings" << (keep_qpdf_warnings ? "true" : "false") << "\n";
+       << std::setw(48) << "keep_qpdf_warnings" << (keep_qpdf_warnings ? "true" : "false") << "\n"
+       << std::setw(48) << "materialize_bitmap_bytes" << (materialize_bitmap_bytes ? "true" : "false") << "\n";
 
     return ss.str();
   }

{docling_parse-6.1.0 → docling_parse-6.2.0}/src/parse/pdf_decoders/document.h

@@ -9,7 +9,8 @@
 #include <qpdf/QPDFAcroFormDocumentHelper.hh>
 #include <qpdf/QPDF.hh>
 #include <qpdf/QPDFWriter.hh>
-//#include <qpdf/QPDFPageObjectHelper.hh>
+
+#include <parse/qpdf/logger.h>
 
 namespace pdflib
 {
@@ -61,22 +62,14 @@ namespace pdflib
 
     pdf_timings& get_timings() { return timings; }
 
-    std::shared_ptr<std::string> get_buffer() { return buffer; }
-    std::optional<std::string> get_password() { return password; }
-
   private:
 
     std::shared_ptr<std::string> get_thread_safe_page_buffer(int page_ind);
-    
-    void update_qpdf_logger();
 
     void ensure_annots_loaded();
 
     void update_timings(pdf_timings& timings_, bool set_timer);
 
-    bool process_document_components();
-    std::shared_ptr<std::string> build_canonical_thread_safe_buffer();
-
   private:
 
     std::string filename;
@@ -84,14 +77,10 @@ namespace pdflib
     std::optional<std::string> password; // stored for thread-safe page decoding
 
     std::mutex thread_safe_buffer_mutex;
-    bool needs_thread_safe_canonicalization;
-
     pdf_timings timings;
 
     QPDF qpdf_document;
-
-    QPDFObjectHandle qpdf_root;
-    QPDFObjectHandle qpdf_pages;
+    std::vector<QPDFObjectHandle> qpdf_pages;
 
     int number_of_pages;
 
@@ -107,14 +96,10 @@ namespace pdflib
     buffer(nullptr),
 
     password(std::nullopt),
-    needs_thread_safe_canonicalization(false),
 
     timings({}),
     qpdf_document(),
-
-    // have compatibulity between QPDF v10 and v11
-    qpdf_root(),
-    qpdf_pages(),
+    qpdf_pages({}),
 
     number_of_pages(-1),
 
@@ -122,7 +107,7 @@ namespace pdflib
     annots_loaded(false),
     page_decoders({})
   {
-    update_qpdf_logger();
+    configure_qpdf_warnings(qpdf_document);
   }
 
   pdf_decoder<DOCUMENT>::pdf_decoder(pdf_timings& timings_):
@@ -130,14 +115,10 @@ namespace pdflib
     buffer(nullptr),
 
     password(std::nullopt),
-    needs_thread_safe_canonicalization(false),
 
     timings(timings_),
     qpdf_document(),
-
-    // have compatibulity between QPDF v10 and v11
-    qpdf_root(),
-    qpdf_pages(),
+    qpdf_pages({}),
 
     number_of_pages(-1),
 
@@ -145,31 +126,12 @@ namespace pdflib
     annots_loaded(false),
     page_decoders({})
   {
-    update_qpdf_logger();
+    configure_qpdf_warnings(qpdf_document);
   }
 
   pdf_decoder<DOCUMENT>::~pdf_decoder()
   {}
 
-  void pdf_decoder<DOCUMENT>::update_qpdf_logger()
-  {
-    if(loguru::g_stderr_verbosity==loguru::Verbosity_INFO or
-       loguru::g_stderr_verbosity==loguru::Verbosity_WARNING)
-      {
-        // ignore ...
-      }
-    else if(loguru::g_stderr_verbosity==loguru::Verbosity_ERROR or
-            loguru::g_stderr_verbosity==loguru::Verbosity_FATAL)
-      {
-        qpdf_document.setSuppressWarnings(true);
-        //qpdf_document.setMaxWarnings(0); only for later versions ...
-      }
-    else
-      {
-
-      }
-  }
-
   void pdf_decoder<DOCUMENT>::ensure_annots_loaded()
   {
     if(annots_loaded)
@@ -179,6 +141,8 @@ namespace pdflib
 
     try
       {
+        QPDFObjectHandle qpdf_root = qpdf_document.getRoot();
+	
         utils::timer annots_timer;
         json_annots = extract_document_annotations_in_json(qpdf_document, qpdf_root);
 
@@ -278,26 +242,23 @@ namespace pdflib
         LOG_S(INFO) << "buffer processed by qpdf which took  " << process_timer.get_time() << " sec";
 
 	timings.add_timing(pdf_timings::KEY_QPDF_PROCESS, process_timer.get_time());
-	
-        qpdf_root = qpdf_document.getRoot();
-        needs_thread_safe_canonicalization = qpdf_document.anyWarnings();
 
-	if(needs_thread_safe_canonicalization)
+	if(qpdf_document.anyWarnings())
 	  {
 	    LOG_S(WARNING) << "qpdf detected inconsistencies!";
 	  }
+
+	qpdf_pages = qpdf_document.getAllPages();
+	number_of_pages = qpdf_pages.size();
+	
+        LOG_S(INFO) << "#-pages: " << number_of_pages;	
       }
     catch(const std::exception & exc)
       {
         LOG_S(ERROR) << "could not process buffer by qpdf: " << exc.what();
         return false;
       }
-
-    if(not process_document_components())
-      {
-        return false;
-      }
-
+    
     ensure_annots_loaded();
 
     timings.add_timing(pdf_timings::KEY_PROCESS_DOCUMENT_FROM_BYTESIO, timer.get_time());
@@ -305,64 +266,14 @@ namespace pdflib
     return true;
   }
 
-  bool pdf_decoder<DOCUMENT>::process_document_components()
-  {
-    utils::timer timer;
-
-    if(qpdf_root.hasKey("/Pages"))
-      {
-        qpdf_pages = qpdf_root.getKey("/Pages");
-
-        if(qpdf_pages.hasKey("/Count"))
-          {
-            number_of_pages = qpdf_pages.getKey("/Count").getIntValue();
-          }
-        else
-          {
-            LOG_S(WARNING) << "filename: " << filename << " has no `/Count`";
-            number_of_pages = 0;
-            for(QPDFObjectHandle page : qpdf_document.getAllPages())
-              {
-                number_of_pages += 1;
-              }
-          }
-
-        LOG_S(INFO) << "#-pages: " << number_of_pages;
-      }
-    else
-      {
-        LOG_S(ERROR) << "filename: " << filename << " has no pages";
-        return false;
-      }
-
-    timings.add_timing(pdf_timings::KEY_PROCESS_DOCUMENT_COMPONENTS, timer.get_time());
-
-    return true;
-  }
-  
-  std::shared_ptr<std::string> pdf_decoder<DOCUMENT>::build_canonical_thread_safe_buffer()
-  {
-    utils::timer timer;
-    QPDFWriter writer(qpdf_document);
-    writer.setOutputMemory();
-    writer.setObjectStreamMode(qpdf_o_preserve);
-    writer.setStreamDataMode(qpdf_s_preserve);
-    writer.setPreserveEncryption(true);
-    writer.write();
-
-    auto out = writer.getBufferSharedPointer();
-    timings.add_timing(pdf_timings::KEY_QPDF_BUILD_THREAD_SAFE_BUFFER, timer.get_time());
-    return std::make_shared<std::string>(reinterpret_cast<char const*>(out->getBuffer()),
-                                         out->getSize());
-  }
-
   std::shared_ptr<std::string> pdf_decoder<DOCUMENT>::get_thread_safe_page_buffer(int page_ind)
   {
+    // Thread-safe decoding uses standalone one-page PDF buffers.
+    // Page extraction and serialization are intentionally serialized, and
+    // the mutex is expected to remain held across QPDFWriter::write().
     std::lock_guard<std::mutex> lock(thread_safe_buffer_mutex);
 
-    std::shared_ptr<std::string> result = NULL; 
-    
-    std::vector<QPDFObjectHandle> qpdf_pages = qpdf_document.getAllPages();
+    std::shared_ptr<std::string> result = nullptr;
 
     QPDFObjectHandle qpdf_page = qpdf_pages.at(page_ind);
     
@@ -374,11 +285,11 @@ namespace pdflib
       QPDFPageDocumentHelper out_pages(out_pdf);
       QPDFAcroFormDocumentHelper out_afdh(out_pdf);
       QPDFAcroFormDocumentHelper src_afdh(qpdf_document);
-      QPDFPageObjectHelper source_page(qpdf_page);
-      out_pages.addPage(source_page, false);
+      QPDFPageObjectHelper page_helper(qpdf_page);
+      out_pages.addPage(page_helper, false);
       auto out_page = out_pages.getAllPages().at(0);
       out_afdh.fixCopiedAnnotations(
-          out_page.getObjectHandle(), source_page.getObjectHandle(), src_afdh);
+          out_page.getObjectHandle(), page_helper.getObjectHandle(), src_afdh);
       
       QPDFWriter writer(out_pdf);
       writer.setOutputMemory();
@@ -495,8 +406,7 @@ namespace pdflib
       else
         {
 	  LOG_S(INFO) << "decoding page thread-unsafe";
-          std::vector<QPDFObjectHandle> pages = qpdf_document.getAllPages();
-          QPDFObjectHandle qpdf_page = pages.at(page_number);
+          QPDFObjectHandle qpdf_page = qpdf_pages.at(page_number);
 
           page_decoder = std::make_shared<pdf_decoder<PAGE>>(qpdf_page, page_number);
         }