From a3ff6106cd812af571be49acfbaa1c1b6482ecc5 Mon Sep 17 00:00:00 2001 From: Nick Franck <46548427+CyMule@users.noreply.github.com> Date: Tue, 6 Oct 2026 13:18:50 -0400 Subject: [PATCH 1/5] perf: render the PDF once in hi_res instead of once per pipeline stage --- CHANGELOG.md | 4 + pyproject.toml | 4 +- .../partition/pdf_image/test_ocr.py | 26 ++ .../partition/pdf_image/test_pdf.py | 65 +++- .../pdf_image/test_pdf_image_utils.py | 34 ++ unstructured/partition/pdf.py | 360 ++++++++++-------- unstructured/partition/pdf_image/ocr.py | 26 +- .../partition/pdf_image/pdf_image_utils.py | 66 ++-- 8 files changed, 382 insertions(+), 203 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 873d7e4c50..95dc9a31aa 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,9 @@ ## 0.27.19-dev0 +### Enhancements + +- **Render the PDF once in `hi_res`.** Layout inference, OCR and image extraction each rendered every page of the PDF again. The pages are now rendered a single time and shared, and `save_elements` keeps one page image open instead of re-decoding the page for every element. Requires `unstructured-inference>=1.6.14`. + ### Maintenance - **Start CI tests without waiting for setup and lint.** Lint installs only its own dependency group, extras jobs install only the system packages their tests use, and a new push cancels the pull request's previous CI run. diff --git a/pyproject.toml b/pyproject.toml index 1ab29df708..20cf965f92 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -69,8 +69,8 @@ image = [ "pi-heif>=1.2.0, <2.0.0", "pikepdf>=10.3.0, <11.0.0", "pypdf>=6.9.1, <7.0.0", - "unstructured-inference>=1.6.12, <2.0.0; platform_system != 'Windows'", - "unstructured-inference>=1.6.12, <2.0.0; platform_system == 'Windows' and python_version >= '3.12' and python_version < '3.13'", + "unstructured-inference>=1.6.14, <2.0.0; platform_system != 'Windows'", + "unstructured-inference>=1.6.14, <2.0.0; platform_system == 'Windows' and python_version >= '3.12' and python_version < '3.13'", "unstructured-pytesseract>=0.3.15, <1.0.0", ] md = [ diff --git a/test_unstructured/partition/pdf_image/test_ocr.py b/test_unstructured/partition/pdf_image/test_ocr.py index b431446e14..0c9cfb78cd 100644 --- a/test_unstructured/partition/pdf_image/test_ocr.py +++ b/test_unstructured/partition/pdf_image/test_ocr.py @@ -673,3 +673,29 @@ def test_pass_down_agents(mock_ocr_get_instance, mocker, mock_page): "language": "eng", "ocr_agent_module": OCR_AGENT_TESSERACT, } + + +def test_process_file_with_ocr_uses_given_image_paths_without_rendering(mocker, tmp_path): + from unstructured.partition.pdf_image.ocr import PILImage + + def fail_render(*args, **kwargs): + raise AssertionError("pdf must not be rendered when image_paths are given") + + mocker.patch.object(ocr, "convert_pdf_to_image", side_effect=fail_render) + supplement = mocker.patch.object( + ocr, "supplement_page_layout_with_ocr", side_effect=lambda page_layout, **kw: page_layout + ) + page_paths = [] + for i in range(2): + page_path = tmp_path / f"page-{i}.png" + PILImage.new("RGB", (50, 50)).save(page_path) + page_paths.append(str(page_path)) + doc = MagicMock(DocumentLayout) + doc.pages = [MagicMock(), MagicMock()] + + result = ocr.process_file_with_ocr( + "foo.pdf", doc, [[], []], is_image=False, image_paths=page_paths + ) + + assert supplement.call_count == 2 + assert len(result.pages) == 2 diff --git a/test_unstructured/partition/pdf_image/test_pdf.py b/test_unstructured/partition/pdf_image/test_pdf.py index 6b7b640d45..ac4d7d58d4 100644 --- a/test_unstructured/partition/pdf_image/test_pdf.py +++ b/test_unstructured/partition/pdf_image/test_pdf.py @@ -44,7 +44,7 @@ ) from unstructured.errors import PageCountExceededError, UnprocessableEntityError from unstructured.partition import pdf, strategies -from unstructured.partition.pdf_image import ocr, pdfminer_processing +from unstructured.partition.pdf_image import ocr, pdf_image_utils, pdfminer_processing from unstructured.partition.pdf_image.pdfminer_processing import get_uris_from_annots from unstructured.partition.utils import config as partition_config from unstructured.partition.utils.constants import ( @@ -177,6 +177,7 @@ def pages(self): ], ) def test_partition_pdf_local(monkeypatch, filename, file): + monkeypatch.setattr(pdf_image_utils, "convert_pdf_to_image", lambda *a, **k: []) monkeypatch.setattr( layout, "process_data_with_model", @@ -213,7 +214,7 @@ def test_partition_pdf_local(monkeypatch, filename, file): def test_partition_pdf_local_raises_with_no_filename(): - with pytest.raises((FileNotFoundError, PDFPageCountError, TypeError)): + with pytest.raises((FileNotFoundError, PDFPageCountError, TypeError, ValueError)): pdf._partition_pdf_or_image_local(filename="", file=None, is_image=False) @@ -252,6 +253,7 @@ def test_partition_pdf_local_threads_rotation_corrections_into_pdfminer( rotated_layout = _layout_with_rotation_corrections( [{"pdf_rotation_correction": 90}, {"pdf_rotation_correction": 0}] ) + monkeypatch.setattr(pdf_image_utils, "convert_pdf_to_image", lambda *a, **k: []) monkeypatch.setattr(layout, model_target, lambda *a, **k: rotated_layout) captured = {} @@ -276,6 +278,65 @@ def _capture_pdfminer(*args, **kwargs): assert captured["rotation_corrections"] == [90, 0] +@pytest.mark.parametrize( + ("file_arg", "model_target", "pdfminer_target", "ocr_target"), + [ + (None, "process_file_with_model", "process_file_with_pdfminer", "process_file_with_ocr"), + ( + b"0000", + "process_data_with_model", + "process_data_with_pdfminer", + "process_data_with_ocr", + ), + ], +) +def test_partition_pdf_local_renders_pages_once_and_shares_them( + monkeypatch, file_arg, model_target, pdfminer_target, ocr_target +): + """The PDF is rendered a single time and the page images reach layout inference, OCR + and image extraction instead of each of them rendering the PDF again.""" + rendered = ["page-1.png", "page-2.png"] + render_calls = [] + received = {} + saved_with = [] + + def _render(*args, **kwargs): + render_calls.append(kwargs) + return rendered + + def _capture(name): + def _inner(*args, **kwargs): + received[name] = kwargs.get("image_paths") + return MockDocumentLayout() + + return _inner + + monkeypatch.setattr(pdf_image_utils, "convert_pdf_to_image", _render) + monkeypatch.setattr(layout, model_target, _capture("model")) + monkeypatch.setattr(pdfminer_processing, pdfminer_target, lambda *a, **k: ([], [])) + monkeypatch.setattr( + pdfminer_processing, + "merge_inferred_with_extracted_layout", + lambda **k: MockDocumentLayout(), + ) + monkeypatch.setattr(ocr, ocr_target, _capture("ocr")) + monkeypatch.setattr( + pdf_image_utils, + "save_elements", + lambda **kwargs: saved_with.append(kwargs["image_paths"]), + ) + + pdf._partition_pdf_or_image_local( + filename=example_doc_path("pdf/layout-parser-paper-fast.pdf") if file_arg is None else "", + file=file_arg, + extract_image_block_types=["Image", "Table"], + ) + + assert len(render_calls) == 1 + assert received == {"model": rendered, "ocr": rendered} + assert saved_with == [rendered, rendered] + + @pytest.mark.parametrize("file_mode", ["filename", "rb", "spool"]) @pytest.mark.parametrize( ("strategy", "starting_page_number", "expected_page_numbers", "origin"), diff --git a/test_unstructured/partition/pdf_image/test_pdf_image_utils.py b/test_unstructured/partition/pdf_image/test_pdf_image_utils.py index f3ae17c199..c22aae5130 100644 --- a/test_unstructured/partition/pdf_image/test_pdf_image_utils.py +++ b/test_unstructured/partition/pdf_image/test_pdf_image_utils.py @@ -249,6 +249,40 @@ def test_save_elements( assert not el.metadata.image_mime_type +def test_save_elements_uses_given_image_paths_without_rendering(monkeypatch, tmp_path): + def fail_render(*args, **kwargs): + raise AssertionError("pdf must not be rendered when image_paths are given") + + monkeypatch.setattr(pdf_image_utils, "convert_pdf_to_image", fail_render) + page_paths = [] + for i in range(2): + page_path = tmp_path / f"page-{i}.png" + PILImg.new("RGB", (400, 400), "white").save(page_path) + page_paths.append(str(page_path)) + elements = [ + Image( + text=f"Image {page}", + coordinates=((10, 10), (10, 100), (100, 100), (100, 10)), + coordinate_system=PixelSpace(width=400, height=400), + metadata=ElementMetadata(page_number=page), + ) + for page in (1, 1, 2) + ] + + pdf_image_utils.save_elements( + elements=elements, + starting_page_number=1, + element_category_to_save=ElementType.IMAGE, + pdf_image_dpi=200, + filename="unused.pdf", + output_dir_path=str(tmp_path), + extract_image_block_to_payload=True, + image_paths=page_paths, + ) + + assert all(el.metadata.image_base64 for el in elements) + + def test_save_elements_with_inverted_point_ordering(monkeypatch): """Regression: points whose ordering puts points[0] below points[2] (as happens when coordinates come from / were converted from a y-up CARTESIAN system) must not raise diff --git a/unstructured/partition/pdf.py b/unstructured/partition/pdf.py index a1b0cacde0..475d0f69d1 100644 --- a/unstructured/partition/pdf.py +++ b/unstructured/partition/pdf.py @@ -5,6 +5,7 @@ import io import os import re +import tempfile import warnings from pathlib import Path from typing import IO, TYPE_CHECKING, Any, Iterator, NoReturn, Optional, Union, cast @@ -1034,6 +1035,7 @@ def _partition_pdf_or_image_local( from unstructured.partition.pdf_image.ocr import process_data_with_ocr, process_file_with_ocr from unstructured.partition.pdf_image.pdf_image_utils import ( check_element_types_to_extract, + convert_pdf_to_image, save_elements, ) from unstructured.partition.pdf_image.pdfminer_processing import ( @@ -1064,194 +1066,222 @@ def _partition_pdf_or_image_local( skip_analysis_dump = env_config.ANALYSIS_DUMP_OD_SKIP - def _run_layout_inference(processor, source): - try: - return processor( - source, - is_image=is_image, - model_name=hi_res_model_name, - pdf_image_dpi=pdf_image_dpi, - password=password, - **model_render_kwargs, + with tempfile.TemporaryDirectory() as page_image_dir: + # The pages are rendered once and shared by layout inference, OCR and image extraction. + page_image_paths: Optional[list[str]] = None + if not is_image: + page_image_paths = cast( + list[str], + convert_pdf_to_image( + filename, + file, + pdf_image_dpi, + output_folder=page_image_dir, + path_only=True, + password=password, + ), ) - except PdfRenderTooLargeError as exc: - raise UnprocessableEntityError(str(exc)) from exc + if hasattr(file, "seek"): + file.seek(0) - if file is None: - inferred_document_layout = _run_layout_inference(process_file_with_model, filename) - _record_image_layout_document_type(inferred_document_layout, is_image) + def _run_layout_inference(processor, source): + try: + return processor( + source, + is_image=is_image, + model_name=hi_res_model_name, + pdf_image_dpi=pdf_image_dpi, + password=password, + **model_render_kwargs, + **({"image_paths": page_image_paths} if page_image_paths is not None else {}), + ) + except PdfRenderTooLargeError as exc: + raise UnprocessableEntityError(str(exc)) from exc - pdfminer_config = _enable_detect_vertical_if_rotated( - inferred_document_layout, - pdfminer_config, - ) + if file is None: + inferred_document_layout = _run_layout_inference(process_file_with_model, filename) + _record_image_layout_document_type(inferred_document_layout, is_image) - extracted_layout, layouts_links = ( - process_file_with_pdfminer( - filename=filename, - dpi=pdf_image_dpi, - password=password, - pdfminer_config=pdfminer_config, - rotation_corrections=_rotation_corrections_from_layout(inferred_document_layout), + pdfminer_config = _enable_detect_vertical_if_rotated( + inferred_document_layout, + pdfminer_config, ) - if pdf_text_extractable - else ([], []) - ) - if analysis: - if not analyzed_image_output_dir_path: - if env_config.GLOBAL_WORKING_DIR_ENABLED: - analyzed_image_output_dir_path = str( - Path(env_config.GLOBAL_WORKING_PROCESS_DIR) / "annotated" - ) - else: - analyzed_image_output_dir_path = str(Path.cwd() / "annotated") - os.makedirs(analyzed_image_output_dir_path, exist_ok=True) - if not skip_analysis_dump: - od_model_layout_dumper = ObjectDetectionLayoutDumper( - layout=inferred_document_layout, - model_name=hi_res_model_name, - ) - extracted_layout_dumper = ExtractedLayoutDumper( - layout=[layout.as_list() for layout in extracted_layout], + extracted_layout, layouts_links = ( + process_file_with_pdfminer( + filename=filename, + dpi=pdf_image_dpi, + password=password, + pdfminer_config=pdfminer_config, + rotation_corrections=_rotation_corrections_from_layout( + inferred_document_layout + ), ) - ocr_layout_dumper = OCRLayoutDumper() - # NOTE(christine): merged_document_layout = extracted_layout + inferred_layout - merged_document_layout = merge_inferred_with_extracted_layout( - inferred_document_layout=inferred_document_layout, - extracted_layout=extracted_layout, - hi_res_model_name=hi_res_model_name, - ) + if pdf_text_extractable + else ([], []) + ) - final_document_layout = process_file_with_ocr( - filename, - merged_document_layout, - extracted_layout=extracted_layout, - is_image=is_image, - infer_table_structure=infer_table_structure, - ocr_agent=ocr_agent, - ocr_languages=ocr_languages, - ocr_mode=ocr_mode, - pdf_image_dpi=pdf_image_dpi, - ocr_layout_dumper=ocr_layout_dumper, - password=password, - table_ocr_agent=table_ocr_agent, - ) - else: - inferred_document_layout = _run_layout_inference(process_data_with_model, file) - _record_image_layout_document_type(inferred_document_layout, is_image) + if analysis: + if not analyzed_image_output_dir_path: + if env_config.GLOBAL_WORKING_DIR_ENABLED: + analyzed_image_output_dir_path = str( + Path(env_config.GLOBAL_WORKING_PROCESS_DIR) / "annotated" + ) + else: + analyzed_image_output_dir_path = str(Path.cwd() / "annotated") + os.makedirs(analyzed_image_output_dir_path, exist_ok=True) + if not skip_analysis_dump: + od_model_layout_dumper = ObjectDetectionLayoutDumper( + layout=inferred_document_layout, + model_name=hi_res_model_name, + ) + extracted_layout_dumper = ExtractedLayoutDumper( + layout=[layout.as_list() for layout in extracted_layout], + ) + ocr_layout_dumper = OCRLayoutDumper() + # NOTE(christine): merged_document_layout = extracted_layout + inferred_layout + merged_document_layout = merge_inferred_with_extracted_layout( + inferred_document_layout=inferred_document_layout, + extracted_layout=extracted_layout, + hi_res_model_name=hi_res_model_name, + ) - if hasattr(file, "seek"): - file.seek(0) + final_document_layout = process_file_with_ocr( + filename, + merged_document_layout, + extracted_layout=extracted_layout, + is_image=is_image, + infer_table_structure=infer_table_structure, + ocr_agent=ocr_agent, + ocr_languages=ocr_languages, + ocr_mode=ocr_mode, + pdf_image_dpi=pdf_image_dpi, + ocr_layout_dumper=ocr_layout_dumper, + password=password, + table_ocr_agent=table_ocr_agent, + image_paths=page_image_paths, + ) + else: + inferred_document_layout = _run_layout_inference(process_data_with_model, file) + _record_image_layout_document_type(inferred_document_layout, is_image) - pdfminer_config = _enable_detect_vertical_if_rotated( - inferred_document_layout, - pdfminer_config, - ) + if hasattr(file, "seek"): + file.seek(0) - extracted_layout, layouts_links = ( - process_data_with_pdfminer( - file=file, - dpi=pdf_image_dpi, - password=password, - pdfminer_config=pdfminer_config, - rotation_corrections=_rotation_corrections_from_layout(inferred_document_layout), + pdfminer_config = _enable_detect_vertical_if_rotated( + inferred_document_layout, + pdfminer_config, ) - if pdf_text_extractable - else ([], []) - ) - if analysis: - if not analyzed_image_output_dir_path: - if env_config.GLOBAL_WORKING_DIR_ENABLED: - analyzed_image_output_dir_path = str( - Path(env_config.GLOBAL_WORKING_PROCESS_DIR) / "annotated" - ) - else: - analyzed_image_output_dir_path = str(Path.cwd() / "annotated") - if not skip_analysis_dump: - od_model_layout_dumper = ObjectDetectionLayoutDumper( - layout=inferred_document_layout, - model_name=hi_res_model_name, - ) - extracted_layout_dumper = ExtractedLayoutDumper( - layout=[layout.as_list() for layout in extracted_layout], + extracted_layout, layouts_links = ( + process_data_with_pdfminer( + file=file, + dpi=pdf_image_dpi, + password=password, + pdfminer_config=pdfminer_config, + rotation_corrections=_rotation_corrections_from_layout( + inferred_document_layout + ), ) - ocr_layout_dumper = OCRLayoutDumper() + if pdf_text_extractable + else ([], []) + ) - # NOTE(christine): merged_document_layout = extracted_layout + inferred_layout - merged_document_layout = merge_inferred_with_extracted_layout( - inferred_document_layout=inferred_document_layout, - extracted_layout=extracted_layout, - hi_res_model_name=hi_res_model_name, - ) + if analysis: + if not analyzed_image_output_dir_path: + if env_config.GLOBAL_WORKING_DIR_ENABLED: + analyzed_image_output_dir_path = str( + Path(env_config.GLOBAL_WORKING_PROCESS_DIR) / "annotated" + ) + else: + analyzed_image_output_dir_path = str(Path.cwd() / "annotated") + if not skip_analysis_dump: + od_model_layout_dumper = ObjectDetectionLayoutDumper( + layout=inferred_document_layout, + model_name=hi_res_model_name, + ) + extracted_layout_dumper = ExtractedLayoutDumper( + layout=[layout.as_list() for layout in extracted_layout], + ) + ocr_layout_dumper = OCRLayoutDumper() - if hasattr(file, "seek"): - file.seek(0) - final_document_layout = process_data_with_ocr( - file, - merged_document_layout, - extracted_layout=extracted_layout, - is_image=is_image, - infer_table_structure=infer_table_structure, - ocr_agent=ocr_agent, - ocr_languages=ocr_languages, - ocr_mode=ocr_mode, - pdf_image_dpi=pdf_image_dpi, - ocr_layout_dumper=ocr_layout_dumper, - password=password, - table_ocr_agent=table_ocr_agent, - ) + # NOTE(christine): merged_document_layout = extracted_layout + inferred_layout + merged_document_layout = merge_inferred_with_extracted_layout( + inferred_document_layout=inferred_document_layout, + extracted_layout=extracted_layout, + hi_res_model_name=hi_res_model_name, + ) - # vectorization of the data structure ends here - final_document_layout = clean_pdfminer_inner_elements(final_document_layout) + if hasattr(file, "seek"): + file.seek(0) + final_document_layout = process_data_with_ocr( + file, + merged_document_layout, + extracted_layout=extracted_layout, + is_image=is_image, + infer_table_structure=infer_table_structure, + ocr_agent=ocr_agent, + ocr_languages=ocr_languages, + ocr_mode=ocr_mode, + pdf_image_dpi=pdf_image_dpi, + ocr_layout_dumper=ocr_layout_dumper, + password=password, + table_ocr_agent=table_ocr_agent, + image_paths=page_image_paths, + ) - elements = document_to_element_list( - final_document_layout, - sortable=True, - include_page_breaks=include_page_breaks, - last_modification_date=metadata_last_modified, - # NOTE(crag): do not attempt to derive ListItem's from a layout-recognized "list" - # block with NLP rules. Otherwise, the assumptions in - # unstructured.partition.common::layout_list_to_list_items often result in weird chunking. - infer_list_items=False, - languages=languages, - starting_page_number=starting_page_number, - layouts_links=layouts_links, - **kwargs, - ) + # vectorization of the data structure ends here + final_document_layout = clean_pdfminer_inner_elements(final_document_layout) - extract_image_block_types = check_element_types_to_extract(extract_image_block_types) - # NOTE(christine): `extract_images_in_pdf` would deprecate - # (but continue to support for a while) - if extract_images_in_pdf: - save_elements( - elements=elements, + elements = document_to_element_list( + final_document_layout, + sortable=True, + include_page_breaks=include_page_breaks, + last_modification_date=metadata_last_modified, + # NOTE(crag): do not attempt to derive ListItem's from a layout-recognized "list" + # block with NLP rules. Otherwise, the assumptions in + # unstructured.partition.common::layout_list_to_list_items often result in weird + # chunking. + infer_list_items=False, + languages=languages, starting_page_number=starting_page_number, - element_category_to_save=ElementType.IMAGE, - filename=filename, - file=file, - is_image=is_image, - pdf_image_dpi=pdf_image_dpi, - extract_image_block_to_payload=extract_image_block_to_payload, - output_dir_path=extract_image_block_output_dir, + layouts_links=layouts_links, + **kwargs, ) - for el_type in extract_image_block_types: - if extract_images_in_pdf and el_type == ElementType.IMAGE: - continue + extract_image_block_types = check_element_types_to_extract(extract_image_block_types) + # NOTE(christine): `extract_images_in_pdf` would deprecate + # (but continue to support for a while) + if extract_images_in_pdf: + save_elements( + elements=elements, + starting_page_number=starting_page_number, + element_category_to_save=ElementType.IMAGE, + filename=filename, + file=file, + is_image=is_image, + pdf_image_dpi=pdf_image_dpi, + extract_image_block_to_payload=extract_image_block_to_payload, + output_dir_path=extract_image_block_output_dir, + image_paths=page_image_paths, + ) - save_elements( - elements=elements, - starting_page_number=starting_page_number, - element_category_to_save=el_type, - filename=filename, - file=file, - is_image=is_image, - pdf_image_dpi=pdf_image_dpi, - extract_image_block_to_payload=extract_image_block_to_payload, - output_dir_path=extract_image_block_output_dir, - ) + for el_type in extract_image_block_types: + if extract_images_in_pdf and el_type == ElementType.IMAGE: + continue + + save_elements( + elements=elements, + starting_page_number=starting_page_number, + element_category_to_save=el_type, + filename=filename, + file=file, + is_image=is_image, + pdf_image_dpi=pdf_image_dpi, + extract_image_block_to_payload=extract_image_block_to_payload, + output_dir_path=extract_image_block_output_dir, + image_paths=page_image_paths, + ) out_elements = [] for el in elements: diff --git a/unstructured/partition/pdf_image/ocr.py b/unstructured/partition/pdf_image/ocr.py index 6fa89e4e94..5507cda6f5 100644 --- a/unstructured/partition/pdf_image/ocr.py +++ b/unstructured/partition/pdf_image/ocr.py @@ -46,6 +46,7 @@ def process_data_with_ocr( ocr_layout_dumper: Optional[OCRLayoutDumper] = None, password: Optional[str] = None, table_ocr_agent: str = OCR_AGENT_TESSERACT, + image_paths: Optional[List[str]] = None, ) -> "DocumentLayout": """ Process OCR data from a given data and supplement the output DocumentLayout @@ -72,6 +73,9 @@ def process_data_with_ocr( - pdf_image_dpi (int, optional): DPI (dots per inch) for processing PDF images. Defaults to env_config.PDF_RENDER_DPI's value. + - image_paths (List[str], optional): Page images already rendered from the PDF at + `pdf_image_dpi`. When given, the PDF is not rendered again. + - ocr_layout_dumper (OCRLayoutDumper, optional): The OCR layout dumper to save the OCR layout. Returns: @@ -97,6 +101,7 @@ def process_data_with_ocr( ocr_layout_dumper=ocr_layout_dumper, password=password, table_ocr_agent=table_ocr_agent, + image_paths=image_paths, ) return merged_layouts @@ -116,6 +121,7 @@ def process_file_with_ocr( ocr_layout_dumper: Optional[OCRLayoutDumper] = None, password: Optional[str] = None, table_ocr_agent: str = OCR_AGENT_TESSERACT, + image_paths: Optional[List[str]] = None, ) -> "DocumentLayout": """ Process OCR data from a given file and supplement the output DocumentLayout @@ -144,6 +150,9 @@ def process_file_with_ocr( - pdf_image_dpi (int, optional): DPI (dots per inch) for processing PDF images. Defaults to env_config.PDF_RENDER_DPI. + - image_paths (List[str], optional): Page images already rendered from the PDF at + `pdf_image_dpi`. When given, the PDF is not rendered again. + Returns: DocumentLayout: The merged layout information obtained after OCR processing. """ @@ -174,14 +183,15 @@ def process_file_with_ocr( return DocumentLayout.from_pages(merged_page_layouts) else: with tempfile.TemporaryDirectory() as temp_dir: - _image_paths = convert_pdf_to_image( - filename, - dpi=pdf_image_dpi, - output_folder=temp_dir, - path_only=True, - password=password, - ) - image_paths = cast(List[str], _image_paths) + if image_paths is None: + _image_paths = convert_pdf_to_image( + filename, + dpi=pdf_image_dpi, + output_folder=temp_dir, + path_only=True, + password=password, + ) + image_paths = cast(List[str], _image_paths) for i, image_path in enumerate(image_paths): extracted_regions = extracted_layout[i] if i < len(extracted_layout) else None diff --git a/unstructured/partition/pdf_image/pdf_image_utils.py b/unstructured/partition/pdf_image/pdf_image_utils.py index a4888ac131..57d753f533 100644 --- a/unstructured/partition/pdf_image/pdf_image_utils.py +++ b/unstructured/partition/pdf_image/pdf_image_utils.py @@ -125,6 +125,7 @@ def save_elements( extract_image_block_to_payload: bool = False, output_dir_path: str | None = None, password: Optional[str] = None, + image_paths: Optional[List[str]] = None, ): """ Saves specific elements from a PDF as images either to a directory or embeds them in the @@ -133,6 +134,9 @@ def save_elements( This function processes a list of elements partitioned from a PDF file. For each element of a specified category, it extracts and saves the image. The images can either be saved to a specified directory or embedded into the element's payload as a base64-encoded string. + + `image_paths` are page images already rendered from the PDF at `pdf_image_dpi`. When given, + the PDF is not rendered again. """ # Determine the output directory path @@ -146,32 +150,35 @@ def save_elements( os.makedirs(output_dir_path, exist_ok=True) with tempfile.TemporaryDirectory() as temp_dir: - if is_image: - if file is None: - image_paths = [filename] - else: - if isinstance(file, bytes): - file_data = file + if image_paths is None: + if is_image: + if file is None: + image_paths = [filename] else: - file.seek(0) - file_data = file.read() - - tmp_file_path = os.path.join(temp_dir, "tmp_file") - with open(tmp_file_path, "wb") as tmp_file: - tmp_file.write(file_data) - image_paths = [tmp_file_path] - else: - _image_paths = convert_pdf_to_image( - filename, - file, - pdf_image_dpi, - output_folder=temp_dir, - path_only=True, - password=password, - ) - image_paths = cast(List[str], _image_paths) + if isinstance(file, bytes): + file_data = file + else: + file.seek(0) + file_data = file.read() + + tmp_file_path = os.path.join(temp_dir, "tmp_file") + with open(tmp_file_path, "wb") as tmp_file: + tmp_file.write(file_data) + image_paths = [tmp_file_path] + else: + _image_paths = convert_pdf_to_image( + filename, + file, + pdf_image_dpi, + output_folder=temp_dir, + path_only=True, + password=password, + ) + image_paths = cast(List[str], _image_paths) figure_number = 0 + page_image: Optional[Image.Image] = None + page_image_index: Optional[int] = None for el in elements: if el.category != element_category_to_save: continue @@ -205,9 +212,14 @@ def save_elements( figure_number += 1 try: - image_path = image_paths[page_index] - image = Image.open(image_path) - cropped_image = image.crop(padded_bbox) + if page_image_index != page_index: + if page_image is not None: + page_image.close() + page_image = None + page_image_index = None + page_image = Image.open(image_paths[page_index]) + page_image_index = page_index + cropped_image = page_image.crop(padded_bbox) # PNG images with transparency need to be converted before saving if cropped_image.mode == "RGBA": @@ -232,6 +244,8 @@ def save_elements( el.metadata.image_path = output_f_path except (ValueError, IOError): logger.warning("Image Extraction Error: Skipping the failed image", exc_info=True) + if page_image is not None: + page_image.close() def check_element_types_to_extract( From 6f34d9dc6d28ffbd1718614241d6917c3ca9f17c Mon Sep 17 00:00:00 2001 From: Nick Franck <46548427+CyMule@users.noreply.github.com> Date: Tue, 6 Oct 2026 14:43:43 -0400 Subject: [PATCH 2/5] fix: render streams without readinto from their bytes in hi_res --- .../partition/pdf_image/test_pdf.py | 41 +++++++++++++++++++ unstructured/partition/pdf.py | 8 +++- 2 files changed, 47 insertions(+), 2 deletions(-) diff --git a/test_unstructured/partition/pdf_image/test_pdf.py b/test_unstructured/partition/pdf_image/test_pdf.py index ac4d7d58d4..bb6861e108 100644 --- a/test_unstructured/partition/pdf_image/test_pdf.py +++ b/test_unstructured/partition/pdf_image/test_pdf.py @@ -337,6 +337,47 @@ def _inner(*args, **kwargs): assert saved_with == [rendered, rendered] +def test_partition_pdf_local_renders_streams_without_readinto(monkeypatch): + """pdfium can only open streams that implement `readinto`; other file-likes are rendered + from their bytes.""" + + class ReadSeekOnly: + def __init__(self, data): + self._buffer = io.BytesIO(data) + + def read(self, *args): + return self._buffer.read(*args) + + def seek(self, *args): + return self._buffer.seek(*args) + + def tell(self): + return self._buffer.tell() + + rendered_inputs = [] + + def _render(filename, file=None, *args, **kwargs): + rendered_inputs.append(file) + return [] + + monkeypatch.setattr(pdf_image_utils, "convert_pdf_to_image", _render) + monkeypatch.setattr(layout, "process_data_with_model", lambda *a, **k: MockDocumentLayout()) + monkeypatch.setattr(pdfminer_processing, "process_data_with_pdfminer", lambda *a, **k: ([], [])) + monkeypatch.setattr( + pdfminer_processing, + "merge_inferred_with_extracted_layout", + lambda **k: MockDocumentLayout(), + ) + monkeypatch.setattr(ocr, "process_data_with_ocr", lambda *a, **k: MockDocumentLayout()) + with open(example_doc_path("pdf/layout-parser-paper-fast.pdf"), "rb") as f: + stream = ReadSeekOnly(f.read()) + + pdf._partition_pdf_or_image_local(filename="", file=stream) + + assert isinstance(rendered_inputs[0], bytes) + assert stream.tell() == 0 + + @pytest.mark.parametrize("file_mode", ["filename", "rb", "spool"]) @pytest.mark.parametrize( ("strategy", "starting_page_number", "expected_page_numbers", "origin"), diff --git a/unstructured/partition/pdf.py b/unstructured/partition/pdf.py index 475d0f69d1..3041cd6b5e 100644 --- a/unstructured/partition/pdf.py +++ b/unstructured/partition/pdf.py @@ -1070,11 +1070,15 @@ def _partition_pdf_or_image_local( # The pages are rendered once and shared by layout inference, OCR and image extraction. page_image_paths: Optional[list[str]] = None if not is_image: + # pdfium can only open streams that implement `readinto`. + render_source = file + if file is not None and not isinstance(file, bytes) and not hasattr(file, "readinto"): + render_source = file.read() page_image_paths = cast( list[str], convert_pdf_to_image( filename, - file, + render_source, pdf_image_dpi, output_folder=page_image_dir, path_only=True, @@ -1093,7 +1097,7 @@ def _run_layout_inference(processor, source): pdf_image_dpi=pdf_image_dpi, password=password, **model_render_kwargs, - **({"image_paths": page_image_paths} if page_image_paths is not None else {}), + image_paths=page_image_paths, ) except PdfRenderTooLargeError as exc: raise UnprocessableEntityError(str(exc)) from exc From b74e1f5cadb87a802412fd8c85c2a17d75ef0e47 Mon Sep 17 00:00:00 2001 From: Nick Franck <46548427+CyMule@users.noreply.github.com> Date: Tue, 6 Oct 2026 14:52:58 -0400 Subject: [PATCH 3/5] test: assert page-specific crops and OCR image hand-off for pre-rendered pages --- .../partition/pdf_image/test_ocr.py | 18 +++++++++++------- .../pdf_image/test_pdf_image_utils.py | 10 +++++++--- 2 files changed, 18 insertions(+), 10 deletions(-) diff --git a/test_unstructured/partition/pdf_image/test_ocr.py b/test_unstructured/partition/pdf_image/test_ocr.py index 0c9cfb78cd..9fda59d6f8 100644 --- a/test_unstructured/partition/pdf_image/test_ocr.py +++ b/test_unstructured/partition/pdf_image/test_ocr.py @@ -682,13 +682,17 @@ def fail_render(*args, **kwargs): raise AssertionError("pdf must not be rendered when image_paths are given") mocker.patch.object(ocr, "convert_pdf_to_image", side_effect=fail_render) - supplement = mocker.patch.object( - ocr, "supplement_page_layout_with_ocr", side_effect=lambda page_layout, **kw: page_layout - ) + seen = [] + + def record(page_layout, image, **kwargs): + seen.append((page_layout, image.size)) + return page_layout + + mocker.patch.object(ocr, "supplement_page_layout_with_ocr", side_effect=record) page_paths = [] - for i in range(2): + for i, size in enumerate(((50, 50), (60, 70))): page_path = tmp_path / f"page-{i}.png" - PILImage.new("RGB", (50, 50)).save(page_path) + PILImage.new("RGB", size).save(page_path) page_paths.append(str(page_path)) doc = MagicMock(DocumentLayout) doc.pages = [MagicMock(), MagicMock()] @@ -697,5 +701,5 @@ def fail_render(*args, **kwargs): "foo.pdf", doc, [[], []], is_image=False, image_paths=page_paths ) - assert supplement.call_count == 2 - assert len(result.pages) == 2 + assert seen == [(doc.pages[0], (50, 50)), (doc.pages[1], (60, 70))] + assert result.pages == doc.pages diff --git a/test_unstructured/partition/pdf_image/test_pdf_image_utils.py b/test_unstructured/partition/pdf_image/test_pdf_image_utils.py index c22aae5130..031769c6bc 100644 --- a/test_unstructured/partition/pdf_image/test_pdf_image_utils.py +++ b/test_unstructured/partition/pdf_image/test_pdf_image_utils.py @@ -255,9 +255,9 @@ def fail_render(*args, **kwargs): monkeypatch.setattr(pdf_image_utils, "convert_pdf_to_image", fail_render) page_paths = [] - for i in range(2): + for i, color in enumerate(("red", "blue")): page_path = tmp_path / f"page-{i}.png" - PILImg.new("RGB", (400, 400), "white").save(page_path) + PILImg.new("RGB", (400, 400), color).save(page_path) page_paths.append(str(page_path)) elements = [ Image( @@ -280,7 +280,11 @@ def fail_render(*args, **kwargs): image_paths=page_paths, ) - assert all(el.metadata.image_base64 for el in elements) + def dominant_channel(el): + crop = PILImg.open(io.BytesIO(base64.b64decode(el.metadata.image_base64))).convert("RGB") + return max(range(3), key=lambda channel: crop.getpixel((10, 10))[channel]) + + assert [dominant_channel(el) for el in elements] == [0, 0, 2] def test_save_elements_with_inverted_point_ordering(monkeypatch): From c7657b5e95cef0b115f9575d439321d80c3c7481 Mon Sep 17 00:00:00 2001 From: Nick Franck <46548427+CyMule@users.noreply.github.com> Date: Tue, 6 Oct 2026 15:22:38 -0400 Subject: [PATCH 4/5] perf: only pre-render hi_res pages when the installed inference can reuse them --- CHANGELOG.md | 2 +- pyproject.toml | 4 +- .../partition/pdf_image/test_pdf.py | 37 +++++++++++++++++++ unstructured/partition/pdf.py | 14 ++++++- 4 files changed, 52 insertions(+), 5 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 95dc9a31aa..1c92256e1f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,7 +2,7 @@ ### Enhancements -- **Render the PDF once in `hi_res`.** Layout inference, OCR and image extraction each rendered every page of the PDF again. The pages are now rendered a single time and shared, and `save_elements` keeps one page image open instead of re-decoding the page for every element. Requires `unstructured-inference>=1.6.14`. +- **Render the PDF once in `hi_res`.** Layout inference, OCR and image extraction each rendered every page of the PDF again. The pages are now rendered a single time and shared, and `save_elements` keeps one page image open instead of re-decoding the page for every element. Takes effect with `unstructured-inference>=1.6.14`; older versions keep rendering per stage. ### Maintenance diff --git a/pyproject.toml b/pyproject.toml index 20cf965f92..1ab29df708 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -69,8 +69,8 @@ image = [ "pi-heif>=1.2.0, <2.0.0", "pikepdf>=10.3.0, <11.0.0", "pypdf>=6.9.1, <7.0.0", - "unstructured-inference>=1.6.14, <2.0.0; platform_system != 'Windows'", - "unstructured-inference>=1.6.14, <2.0.0; platform_system == 'Windows' and python_version >= '3.12' and python_version < '3.13'", + "unstructured-inference>=1.6.12, <2.0.0; platform_system != 'Windows'", + "unstructured-inference>=1.6.12, <2.0.0; platform_system == 'Windows' and python_version >= '3.12' and python_version < '3.13'", "unstructured-pytesseract>=0.3.15, <1.0.0", ] md = [ diff --git a/test_unstructured/partition/pdf_image/test_pdf.py b/test_unstructured/partition/pdf_image/test_pdf.py index bb6861e108..a8c499b45e 100644 --- a/test_unstructured/partition/pdf_image/test_pdf.py +++ b/test_unstructured/partition/pdf_image/test_pdf.py @@ -295,6 +295,7 @@ def test_partition_pdf_local_renders_pages_once_and_shares_them( ): """The PDF is rendered a single time and the page images reach layout inference, OCR and image extraction instead of each of them rendering the PDF again.""" + monkeypatch.setattr(pdf, "_inference_reuses_page_images", lambda: True) rendered = ["page-1.png", "page-2.png"] render_calls = [] received = {} @@ -340,6 +341,7 @@ def _inner(*args, **kwargs): def test_partition_pdf_local_renders_streams_without_readinto(monkeypatch): """pdfium can only open streams that implement `readinto`; other file-likes are rendered from their bytes.""" + monkeypatch.setattr(pdf, "_inference_reuses_page_images", lambda: True) class ReadSeekOnly: def __init__(self, data): @@ -378,6 +380,41 @@ def _render(filename, file=None, *args, **kwargs): assert stream.tell() == 0 +def test_partition_pdf_local_does_not_prerender_when_inference_cannot_reuse_pages(monkeypatch): + """Without inference support the pages would be rendered twice, so the pipeline keeps + rendering per stage.""" + monkeypatch.setattr(pdf, "_inference_reuses_page_images", lambda: False) + monkeypatch.setattr( + pdf_image_utils, + "convert_pdf_to_image", + lambda *a, **k: pytest.fail("pdf must not be pre-rendered"), + ) + received = {} + + def _capture(name): + def _inner(*args, **kwargs): + received[name] = kwargs + return MockDocumentLayout() + + return _inner + + monkeypatch.setattr(layout, "process_file_with_model", _capture("model")) + monkeypatch.setattr(pdfminer_processing, "process_file_with_pdfminer", lambda *a, **k: ([], [])) + monkeypatch.setattr( + pdfminer_processing, + "merge_inferred_with_extracted_layout", + lambda **k: MockDocumentLayout(), + ) + monkeypatch.setattr(ocr, "process_file_with_ocr", _capture("ocr")) + + pdf._partition_pdf_or_image_local( + filename=example_doc_path("pdf/layout-parser-paper-fast.pdf"), + ) + + assert received["model"].get("image_paths") is None + assert received["ocr"].get("image_paths") is None + + @pytest.mark.parametrize("file_mode", ["filename", "rb", "spool"]) @pytest.mark.parametrize( ("strategy", "starting_page_number", "expected_page_numbers", "origin"), diff --git a/unstructured/partition/pdf.py b/unstructured/partition/pdf.py index 3041cd6b5e..797c480108 100644 --- a/unstructured/partition/pdf.py +++ b/unstructured/partition/pdf.py @@ -2,6 +2,8 @@ import contextlib import copy +import functools +import inspect import io import os import re @@ -976,6 +978,14 @@ def _enable_detect_vertical_if_rotated( return pdfminer_config +@functools.lru_cache(maxsize=1) +def _inference_reuses_page_images() -> bool: + """Whether the installed unstructured-inference accepts pre-rendered page images.""" + from unstructured_inference.inference.layout import DocumentLayout + + return "image_paths" in inspect.signature(DocumentLayout.from_file).parameters + + def _rotation_corrections_from_layout(inferred_document_layout) -> list[int]: """Per-page rotations unstructured-inference applied to the page images to make their text upright. Mirrored onto the pdfminer coordinates so both layers share one frame.""" @@ -1069,7 +1079,7 @@ def _partition_pdf_or_image_local( with tempfile.TemporaryDirectory() as page_image_dir: # The pages are rendered once and shared by layout inference, OCR and image extraction. page_image_paths: Optional[list[str]] = None - if not is_image: + if not is_image and _inference_reuses_page_images(): # pdfium can only open streams that implement `readinto`. render_source = file if file is not None and not isinstance(file, bytes) and not hasattr(file, "readinto"): @@ -1097,7 +1107,7 @@ def _run_layout_inference(processor, source): pdf_image_dpi=pdf_image_dpi, password=password, **model_render_kwargs, - image_paths=page_image_paths, + **({"image_paths": page_image_paths} if page_image_paths is not None else {}), ) except PdfRenderTooLargeError as exc: raise UnprocessableEntityError(str(exc)) from exc From 601d03be3985bdf567a81bfb588aae17537b21e6 Mon Sep 17 00:00:00 2001 From: Nick Franck <46548427+CyMule@users.noreply.github.com> Date: Tue, 6 Oct 2026 15:48:48 -0400 Subject: [PATCH 5/5] perf: release the in-memory PDF copy once the pages are rendered --- unstructured/partition/pdf.py | 1 + 1 file changed, 1 insertion(+) diff --git a/unstructured/partition/pdf.py b/unstructured/partition/pdf.py index 797c480108..b5294b74a8 100644 --- a/unstructured/partition/pdf.py +++ b/unstructured/partition/pdf.py @@ -1095,6 +1095,7 @@ def _partition_pdf_or_image_local( password=password, ), ) + render_source = None if hasattr(file, "seek"): file.seek(0)