docling-parse 7.16.0__tar.gz → 7.18.0__tar.gz

{docling_parse-7.16.0 → docling_parse-7.18.0}/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [v7.18.0](https://github.com/docling-project/docling-parse/releases/tag/v7.18.0) - 2026-09-08
+
+### Feature
+
+* Resolve-bookmarks-using-page-aware-PDF-outlines ([#341](https://github.com/docling-project/docling-parse/issues/341)) ([`e6b04ca`](https://github.com/docling-project/docling-parse/commit/e6b04cab04f3d29ffd86ceb75b0d2a5548f96c97))
+
+## [v7.17.0](https://github.com/docling-project/docling-parse/releases/tag/v7.17.0) - 2026-09-02
+
+### Feature
+
+* Optimization of the parse/render with up to 3.84× speedup ([#333](https://github.com/docling-project/docling-parse/issues/333)) ([`0d9cac5`](https://github.com/docling-project/docling-parse/commit/0d9cac5807ee69683eead658273cfb1fdca8dc3b))
+
 ## [v7.16.0](https://github.com/docling-project/docling-parse/releases/tag/v7.16.0) - 2026-08-25
 
 ### Feature

{docling_parse-7.16.0 → docling_parse-7.18.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docling-parse
-Version: 7.16.0
+Version: 7.18.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
@@ -25,7 +25,7 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: pillow<13.0.0,>=10.0.0
 Requires-Dist: pydantic>=2.0.0
-Requires-Dist: docling-core<3.0.0,>=2.85.0
+Requires-Dist: docling-core<3.0.0,>=2.95.0
 Requires-Dist: pywin32>=305; sys_platform == "win32"
 Dynamic: license-file
 

{docling_parse-7.16.0 → docling_parse-7.18.0}/app/pybind_parse.cpp

@@ -382,6 +382,8 @@ PYBIND11_MODULE(pdf_parsers, m) {
     .def_readwrite("keep_glyphs", &pdflib::decode_config::keep_glyphs)
     .def_readwrite("keep_qpdf_warnings", &pdflib::decode_config::keep_qpdf_warnings)
     .def_readwrite("extract_font_programs", &pdflib::decode_config::extract_font_programs)
+    .def_readwrite("extract_bitmap_pixels", &pdflib::decode_config::extract_bitmap_pixels)
+    .def_readwrite("bitmap_target_pixels_per_unit", &pdflib::decode_config::bitmap_target_pixels_per_unit)
     .def("__copy__", [](const pdflib::decode_config& self) { return self; })
     .def("__deepcopy__", [](const pdflib::decode_config& self, pybind11::dict) { return self; });
 
@@ -1100,6 +1102,19 @@ PYBIND11_MODULE(pdf_parsers, m) {
 
     Returns:
         int: Number of pages that will be emitted by the threaded parser.)")
+    .def("get_annotations",
+         [](docling::docling_threaded_parser& self, const std::string& key) -> nlohmann::json {
+           return self.get_annotations(key);
+         },
+         pybind11::arg("key"),
+         R"(
+    Retrieve annotations for a loaded document and return them as JSON.
+
+    Parameters:
+        key (str): The unique key identifying the document.
+
+    Returns:
+        dict: A JSON object containing the annotations for the document.)")
     .def("unload_document",
          [](docling::docling_threaded_parser& self, const std::string& key) -> bool {
            return self.unload_document(key);
@@ -1163,6 +1178,7 @@ PYBIND11_MODULE(pdf_parsers, m) {
         resolve_fonts (bool): Resolve PDF font names to system fonts [default=true].
         use_embedded_fonts (bool): Prefer embedded font programs (TrueType/OpenType via Blend2D, Type 1/CFF via FreeType outlines) over system font resolution [default=true].
         font_similarity_cutoff (float): Minimum Jaccard similarity for fuzzy font matching; candidates below this threshold fall back to the default font [default=0.25].
+        glyph_bbox_cache_capacity (int): Maximum cached embedded-font glyph bounding boxes per render worker; zero disables caching [default=65536].
         scale (float): Target render scale in multiples of the PDF page size; -1 disables scale-based sizing [default=-1].
         canvas_width (int): Target canvas width in pixels; -1 means use PDF page size [default=-1].
         canvas_height (int): Target canvas height in pixels; -1 means use PDF page size [default=-1].
@@ -1181,6 +1197,7 @@ PYBIND11_MODULE(pdf_parsers, m) {
     .def_readwrite("resolve_fonts",           &pdflib::render_config::resolve_fonts)
     .def_readwrite("use_embedded_fonts",      &pdflib::render_config::use_embedded_fonts)
     .def_readwrite("font_similarity_cutoff",  &pdflib::render_config::font_similarity_cutoff)
+    .def_readwrite("glyph_bbox_cache_capacity", &pdflib::render_config::glyph_bbox_cache_capacity)
     .def_readwrite("scale",                   &pdflib::render_config::scale)
     .def_readwrite("canvas_width",            &pdflib::render_config::canvas_width)
     .def_readwrite("canvas_height",           &pdflib::render_config::canvas_height);
@@ -1309,6 +1326,11 @@ PYBIND11_MODULE(pdf_parsers, m) {
            return self.scheduled_number_of_pages(key);
          },
          pybind11::arg("key"))
+    .def("get_annotations",
+         [](docling::docling_threaded_renderer& self, const std::string& key) -> nlohmann::json {
+           return self.get_annotations(key);
+         },
+         pybind11::arg("key"))
     .def("unload_document",
          [](docling::docling_threaded_renderer& self, const std::string& key) -> bool {
            return self.unload_document(key);

{docling_parse-7.16.0 → docling_parse-7.18.0}/app/render.cpp

@@ -312,6 +312,7 @@ int main(int argc, char* argv[])
       if (result.count("keep-qpdf-warnings"))       { page_config.keep_qpdf_warnings        = result["keep-qpdf-warnings"].as<bool>(); }
       // This app always renders, so embedded font extraction defaults to on.
       page_config.extract_font_programs = true;
+      page_config.extract_bitmap_pixels = true;
       if (result.count("extract-font-programs"))    { page_config.extract_font_programs     = result["extract-font-programs"].as<bool>(); }
       if (result.count("populate-json"))            { page_config.populate_json_objects      = result["populate-json"].as<bool>(); }
       bool export_bitmaps = result["export-bitmaps"].as<bool>();
@@ -341,6 +342,14 @@ int main(int argc, char* argv[])
       if (result.count("canvas-width"))           { cfg.canvas_width           = result["canvas-width"].as<int>(); }
       if (result.count("canvas-height"))          { cfg.canvas_height          = result["canvas-height"].as<int>(); }
 
+      // Let the decode side know what resolution the samples are drawn at, so
+      // oversampled scans decode down rather than in full. Only the scale form
+      // states a per-page-independent resolution; see docling_threaded_renderer.
+      if (cfg.scale > 0.0f)
+        {
+          page_config.bitmap_target_pixels_per_unit = cfg.scale;
+        }
+
       utils::timer timer;
 
       // --- single-file mode (-i) ---

{docling_parse-7.16.0 → docling_parse-7.18.0}/app/run_scaling.cpp

@@ -8,6 +8,7 @@
 #include <cctype>
 #include <chrono>
 #include <condition_variable>
+#include <cstddef>
 #include <cstdlib>
 #include <filesystem>
 #include <fstream>
@@ -33,9 +34,11 @@ namespace
 
   enum class run_mode
   {
-    parse,
+    parse_without_bitmaps,
+    parse_with_bitmaps,
     render,
-    both,
+    default_mode,
+    all,
   };
 
   struct scheduled_doc
@@ -82,14 +85,16 @@ namespace
   struct cli_options
   {
     std::filesystem::path input;
-    run_mode mode = run_mode::render;
+    run_mode mode = run_mode::default_mode;
     bool recursive = false;
     std::optional<int> max_pages = std::nullopt;
     int max_concurrent_results = 64;
     std::vector<int> threads{1, 2, 4, 8, 12, 16};
-    float scale = 1.0f;
+    float scale = 2.0f;
+    std::size_t glyph_bbox_cache_capacity = 65536;
     bool enable_timing = false;
     std::filesystem::path timing_csv = "timing-cpp.csv";
+    std::optional<std::filesystem::path> output_dir = std::nullopt;
     std::string loglevel = "fatal";
   };
 
@@ -124,11 +129,13 @@ namespace
   {
     switch(mode)
       {
-      case run_mode::parse: return "parse";
+      case run_mode::parse_without_bitmaps: return "parse-without-bitmaps";
+      case run_mode::parse_with_bitmaps: return "parse-with-bitmaps";
       case run_mode::render: return "render";
-      case run_mode::both: return "both";
+      case run_mode::default_mode: return "default";
+      case run_mode::all: return "all";
       }
-    return "render";
+    return "default";
   }
 
   std::vector<int> parse_thread_counts(const std::string& raw)
@@ -200,6 +207,13 @@ namespace
     return ss.str();
   }
 
+  std::string zero_padded(std::size_t value, int width = 6)
+  {
+    std::ostringstream ss;
+    ss << std::setw(width) << std::setfill('0') << value;
+    return ss.str();
+  }
+
   class progress_bar
   {
   public:
@@ -554,18 +568,39 @@ namespace
                        int num_threads,
                        int max_concurrent_results,
                        pdflib::decode_config decode_config,
-                       std::optional<pdflib::render_config> render_config):
+                       std::optional<pdflib::render_config> render_config,
+                       std::optional<std::filesystem::path> output_dir):
       schedule_(schedule),
       docs_(docs),
       num_threads_(num_threads),
       max_concurrent_results_(max_concurrent_results),
       decode_config_(decode_config),
-      render_config_(render_config)
+      render_config_(render_config),
+      output_dir_(std::move(output_dir))
     {
       if(render_config_.has_value())
         {
+          // Rendering needs the image samples and the embedded font programs,
+          // whatever the CLI asked for. Without the latter this benchmark
+          // silently rasterised with substituted system fonts, which is both
+          // cheaper and not what the library does.
+          decode_config_.extract_bitmap_pixels = true;
+          decode_config_.extract_font_programs = true;
+
+          // Same resolution hint the library sets, so this benchmark measures
+          // the decode work the library actually does; see
+          // docling_threaded_renderer for why only the scale form qualifies.
+          if(render_config_->scale > 0.0f)
+            {
+              decode_config_.bitmap_target_pixels_per_unit = render_config_->scale;
+            }
+
           font_resolver_ = std::make_shared<pdflib::blend2d_font_resolver>();
           font_resolver_->warm();
+
+          // shared across pages, exactly as docling_threaded_renderer does;
+          // a per-page cache would reload every embedded font program
+          embedded_font_cache_ = std::make_shared<pdflib::blend2d_embedded_font_cache>();
         }
     }
 
@@ -620,6 +655,18 @@ namespace
   private:
     void worker_loop()
     {
+      std::shared_ptr<pdflib::freetype_font_cache> freetype_font_cache;
+      std::shared_ptr<pdflib::glyph_bbox_cache> glyph_bbox_cache;
+      if(render_config_.has_value())
+        {
+          // FT_Face objects mutate their selected size and charmap while
+          // building an outline. This cache is reused across the worker's
+          // pages, but never shared with another render worker.
+          freetype_font_cache = std::make_shared<pdflib::freetype_font_cache>();
+          glyph_bbox_cache = std::make_shared<pdflib::glyph_bbox_cache>(
+            render_config_->glyph_bbox_cache_capacity);
+        }
+
       while(true)
         {
           const std::size_t task_index = next_task_.fetch_add(1);
@@ -668,11 +715,25 @@ namespace
               if(render_config_.has_value())
                 {
                   stage_start = clock_type::now();
-                  pdflib::renderer<pdflib::BLEND2D> rnd(*render_config_, font_resolver_);
+                  pdflib::renderer<pdflib::BLEND2D> rnd(*render_config_,
+                                                        font_resolver_,
+                                                        embedded_font_cache_,
+                                                        freetype_font_cache,
+                                                        glyph_bbox_cache);
                   page_decoder->get_instructions().iterate_over_instructions(rnd);
                   result.timings.render_page_s =
                     std::chrono::duration<double>(clock_type::now() - stage_start).count();
-                  result.image_data = rnd.get_canvas();
+                  if(output_dir_.has_value())
+                    {
+                      const auto page_path = *output_dir_ /
+                        ("doc_" + zero_padded(task.doc_index + 1) +
+                         "_page_" + zero_padded(task.page_number + 1) + ".png");
+                      rnd.save(page_path.string());
+                    }
+                  else
+                    {
+                      result.image_data = rnd.get_canvas();
+                    }
                 }
 
               result.timings.total_s =
@@ -735,7 +796,9 @@ namespace
     int max_concurrent_results_;
     pdflib::decode_config decode_config_;
     std::optional<pdflib::render_config> render_config_;
+    std::optional<std::filesystem::path> output_dir_;
     std::shared_ptr<pdflib::blend2d_font_resolver> font_resolver_;
+    std::shared_ptr<pdflib::blend2d_embedded_font_cache> embedded_font_cache_;
 
     std::vector<page_task> tasks_;
     std::atomic<std::size_t> next_task_{0};
@@ -769,6 +832,7 @@ namespace
               << std::setw(32) << "fit_glyph_bbox_to_target" << config.fit_glyph_bbox_to_target << "\n"
               << std::setw(32) << "resolve_fonts" << config.resolve_fonts << "\n"
               << std::setw(32) << "font_similarity_cutoff" << config.font_similarity_cutoff << "\n"
+              << std::setw(32) << "glyph_bbox_cache_capacity" << config.glyph_bbox_cache_capacity << "\n"
               << std::setw(32) << "scale" << config.scale << "\n"
               << std::setw(32) << "canvas_width" << config.canvas_width << "\n"
               << std::setw(32) << "canvas_height" << config.canvas_height << "\n";
@@ -778,7 +842,12 @@ namespace
                    const std::vector<benchmark_result>& results,
                    int total_pages)
   {
-    const double t1 = results.empty() ? 0.0 : results.front().wall_time_s;
+    const auto baseline = std::find_if(
+      results.begin(), results.end(),
+      [](const benchmark_result& result) { return result.threads == 1; });
+    const bool has_baseline = baseline != results.end()
+      && baseline->wall_time_s > 0.0;
+    const double t1 = has_baseline ? baseline->wall_time_s : 0.0;
 
     std::cout << "\n=== " << title << " ===\n";
     std::cout << std::left
@@ -787,15 +856,17 @@ namespace
               << std::setw(10) << "threads"
               << std::setw(18) << "wall_time (s)"
               << std::setw(18) << "vs threaded(1)"
+              << std::setw(14) << "efficiency"
               << std::setw(14) << "pages/sec"
               << std::setw(12) << "ms/page"
               << std::setw(10) << "errors"
               << "\n";
-    std::cout << std::string(100, '-') << "\n";
+    std::cout << std::string(114, '-') << "\n";
 
     for(const auto& result : results)
       {
-        const double speedup = result.wall_time_s > 0.0 ? t1 / result.wall_time_s : 0.0;
+        const double speedup = has_baseline && result.wall_time_s > 0.0
+          ? t1 / result.wall_time_s : 0.0;
         const double pages_per_sec = result.wall_time_s > 0.0
           ? static_cast<double>(total_pages) / result.wall_time_s : 0.0;
         const double ms_per_page = total_pages > 0
@@ -803,13 +874,24 @@ namespace
 
         std::ostringstream speedup_ss;
         speedup_ss << std::fixed << std::setprecision(2) << speedup << "x";
+        std::ostringstream efficiency_ss;
+        if(has_baseline && result.threads > 0 && result.wall_time_s > 0.0)
+          {
+            efficiency_ss << std::fixed << std::setprecision(0)
+                          << (100.0 * speedup / result.threads) << "%";
+          }
+        else
+          {
+            efficiency_ss << "n/a";
+          }
 
         std::cout << std::left
                   << std::setw(18) << "docling threaded"
                   << std::right
                   << std::setw(10) << result.threads
                   << std::setw(18) << std::fixed << std::setprecision(3) << result.wall_time_s
-                  << std::setw(18) << speedup_ss.str()
+                  << std::setw(18) << (has_baseline ? speedup_ss.str() : "n/a")
+                  << std::setw(14) << efficiency_ss.str()
                   << std::setw(14) << std::fixed << std::setprecision(1) << pages_per_sec
                   << std::setw(12) << std::fixed << std::setprecision(2) << ms_per_page
                   << std::setw(10) << result.errors
@@ -831,12 +913,14 @@ namespace
     cxxopts::Options options("run_scaling", "Thread-scaling benchmark for docling-parse C++");
     options.add_options()
       ("input", "Local PDF file or directory", cxxopts::value<std::string>())
-      ("mode", "Benchmark stage: parse, render, or both", cxxopts::value<std::string>()->default_value("render"))
+      ("mode", "Benchmark stage: parse-without-bitmaps, parse-with-bitmaps, render, default, or all", cxxopts::value<std::string>()->default_value("default"))
       ("recursive,r", "Recurse into subdirectories", cxxopts::value<bool>()->default_value("false")->implicit_value("true"))
       ("max-pages,l", "Maximum number of pages to process across all input PDFs", cxxopts::value<int>())
       ("max-concurrent-results", "Max buffered results for threaded processing", cxxopts::value<int>()->default_value("64"))
       ("threads", "Comma-separated thread counts", cxxopts::value<std::string>()->default_value("1,2,4,8,12,16"))
-      ("scale", "Render scale for render mode", cxxopts::value<float>()->default_value("1.0"))
+      ("scale", "Render scale for render mode", cxxopts::value<float>()->default_value("2.0"))
+      ("glyph-bbox-cache-capacity", "Maximum cached glyph bounding boxes per render worker; 0 disables caching", cxxopts::value<std::size_t>()->default_value("65536"))
+      ("output-dir", "Write rendered PNGs under this directory", cxxopts::value<std::string>())
       ("enable-timing", "Write one CSV timing row per page result", cxxopts::value<bool>()->default_value("false")->implicit_value("true"))
       ("timing-csv", "CSV path used when --enable-timing is set", cxxopts::value<std::string>()->default_value("timing-cpp.csv"))
       ("loglevel", "Log level [fatal, error, warning, info]", cxxopts::value<std::string>()->default_value("fatal"))
@@ -878,9 +962,15 @@ namespace
       }
     cli.threads = parse_thread_counts(result["threads"].as<std::string>());
     cli.scale = result["scale"].as<float>();
+    cli.glyph_bbox_cache_capacity =
+      result["glyph-bbox-cache-capacity"].as<std::size_t>();
     cli.enable_timing = result["enable-timing"].as<bool>();
     cli.timing_csv = result["timing-csv"].as<std::string>();
     cli.loglevel = result["loglevel"].as<std::string>();
+    if(result.count("output-dir"))
+      {
+        cli.output_dir = result["output-dir"].as<std::string>();
+      }
 
     if(result.count("max-pages"))
       {
@@ -890,21 +980,31 @@ namespace
     std::string raw_mode = result["mode"].as<std::string>();
     std::transform(raw_mode.begin(), raw_mode.end(), raw_mode.begin(),
                    [](unsigned char c) { return std::tolower(c); });
-    if(raw_mode == "parse")
+    if(raw_mode == "parse" or raw_mode == "parse-without-bitmaps")
+      {
+        cli.mode = run_mode::parse_without_bitmaps;
+      }
+    else if(raw_mode == "parse-with-bitmaps")
       {
-        cli.mode = run_mode::parse;
+        cli.mode = run_mode::parse_with_bitmaps;
       }
     else if(raw_mode == "render")
       {
         cli.mode = run_mode::render;
       }
-    else if(raw_mode == "both")
+    else if(raw_mode == "default")
       {
-        cli.mode = run_mode::both;
+        cli.mode = run_mode::default_mode;
+      }
+    else if(raw_mode == "all")
+      {
+        cli.mode = run_mode::all;
       }
     else
       {
-        throw std::runtime_error("--mode must be one of parse, render, both");
+        throw std::runtime_error(
+          "--mode must be parse-without-bitmaps, parse-with-bitmaps, render, "
+          "default, or all");
       }
 
     if(result.count("page-boundary")) { decode_config.page_boundary = result["page-boundary"].as<std::string>(); }
@@ -955,6 +1055,11 @@ int main(int argc, char* argv[])
           return 2;
         }
 
+      if(cli.output_dir.has_value())
+        {
+          std::filesystem::create_directories(*cli.output_dir);
+        }
+
       std::cout << "Benchmark: " << schedule.size()
                 << " documents, " << total_pages << " total pages\n";
       std::cout << "Mode: " << mode_to_string(cli.mode) << "\n";
@@ -966,7 +1071,9 @@ int main(int argc, char* argv[])
         }
       std::cout << "\n";
       std::cout << "Max concurrent results: " << cli.max_concurrent_results << "\n";
-      if(cli.mode == run_mode::render or cli.mode == run_mode::both)
+      if(cli.mode == run_mode::render
+         or cli.mode == run_mode::default_mode
+         or cli.mode == run_mode::all)
         {
           std::cout << "Render scale: " << cli.scale << "\n";
         }
@@ -974,7 +1081,10 @@ int main(int argc, char* argv[])
 
       print_decode_config(decode_config);
       auto render_config = default_render_config(cli.scale);
-      if(cli.mode == run_mode::render or cli.mode == run_mode::both)
+      render_config.glyph_bbox_cache_capacity = cli.glyph_bbox_cache_capacity;
+      if(cli.mode == run_mode::render
+         or cli.mode == run_mode::default_mode
+         or cli.mode == run_mode::all)
         {
           print_render_config(render_config);
         }
@@ -983,9 +1093,15 @@ int main(int argc, char* argv[])
       auto docs = load_documents(schedule);
 
       std::vector<run_mode> modes;
-      if(cli.mode == run_mode::both)
+      if(cli.mode == run_mode::all)
+        {
+          modes = {run_mode::parse_without_bitmaps,
+                   run_mode::parse_with_bitmaps,
+                   run_mode::render};
+        }
+      else if(cli.mode == run_mode::default_mode)
         {
-          modes = {run_mode::parse, run_mode::render};
+          modes = {run_mode::parse_without_bitmaps, run_mode::render};
         }
       else
         {
@@ -995,7 +1111,14 @@ int main(int argc, char* argv[])
       for(run_mode mode : modes)
         {
           const bool render = (mode == run_mode::render);
-          const std::string title = render ? "RENDER (decode + rasterise)" : "PARSE (decode only)";
+          const bool parse_with_bitmaps = mode == run_mode::parse_with_bitmaps;
+          const std::string title = render ? "RENDER (decode + rasterise)"
+            : parse_with_bitmaps ? "PARSE WITH BITMAPS (decode only)"
+            : "PARSE WITHOUT BITMAPS (decode only)";
+          auto mode_decode_config = decode_config;
+          mode_decode_config.keep_shapes = render or decode_config.keep_shapes;
+          mode_decode_config.keep_bitmaps = render or parse_with_bitmaps; // if render is not here, we skip the bitmap in the rendered page-image
+          mode_decode_config.extract_bitmap_pixels = parse_with_bitmaps; // if we have render here, we keep the bitmaps to be iterated over
           std::cout << "\n##### " << title << " #####\n";
 
           std::vector<benchmark_result> results;
@@ -1009,9 +1132,10 @@ int main(int argc, char* argv[])
                                            docs,
                                            threads,
                                            cli.max_concurrent_results,
-                                           decode_config,
+                                           mode_decode_config,
                                            render ? std::optional<pdflib::render_config>(render_config)
-                                                  : std::nullopt);
+                                                  : std::nullopt,
+                                           render ? cli.output_dir : std::nullopt);
               benchmark_result result = benchmark.run(render ? "render" : "parse",
                                                       cli.enable_timing,
                                                       cli.timing_csv);