docvortex 0.2.1__py3-none-any.whl

docvortex/document/pdf/native_text_geometry.py

@@ -0,0 +1,315 @@
+"""PDF 字符去重及原始文字几何提取，保持原生提取算法与资源语义。"""
+
+from __future__ import annotations
+import logging
+import math
+from typing import Any, Iterator, cast
+import pypdfium2 as pdfium
+import pypdfium2.raw as pdfium_c
+from .text.extract import get_chars, deduplicate_chars
+from .text.contracts import Char
+from .text.geometry import char_bbox_values as _char_bbox_values
+
+from .native_contracts import (
+    NEAR_IDENTICAL_CHAR_BBOX_TOLERANCE,
+    OFFSET_DUPLICATE_CHAR_BBOX_TOLERANCE,
+    OFFSET_DUPLICATE_MIN_BBOX_OVERLAP_RATIO,
+    OFFSET_DUPLICATE_TRANSLATION_TOLERANCE,
+    PDFPageImage,
+    PDFPageTextGeometry,
+)
+from .native_lifecycle import _try_close
+
+logger = logging.getLogger("docvortex.document.pdf.document")
+
+
+def _get_visible_char_signature(
+    char: Char,
+) -> tuple[str, tuple[Any, Any, Any, Any], float]:
+    """生成可见字符去重签名，不把 bbox 放入签名以便单独做近重合判断。"""
+    font = char.get("font") or {}
+    font_key = (
+        font.get("name"),
+        font.get("flags"),
+        font.get("size"),
+        font.get("weight"),
+    )
+    rotation_key = round(float(char.get("rotation") or 0.0), 3)
+    return str(char.get("char", "")), font_key, rotation_key
+
+
+def _is_near_identical_bbox(
+    bbox_a: tuple[float, float, float, float],
+    bbox_b: tuple[float, float, float, float],
+) -> bool:
+    """判断两个字符 bbox 是否属于同一视觉位置的一点内抖动。"""
+    return all(abs(coord_a - coord_b) <= NEAR_IDENTICAL_CHAR_BBOX_TOLERANCE for coord_a, coord_b in zip(bbox_a, bbox_b))
+
+
+def _calculate_bbox_overlap_in_smaller_area(
+    bbox_a: tuple[float, float, float, float],
+    bbox_b: tuple[float, float, float, float],
+) -> float:
+    """计算两个字符框交集占较小字符框面积的比例。"""
+    intersection_width = max(
+        0.0,
+        min(bbox_a[2], bbox_b[2]) - max(bbox_a[0], bbox_b[0]),
+    )
+    intersection_height = max(
+        0.0,
+        min(bbox_a[3], bbox_b[3]) - max(bbox_a[1], bbox_b[1]),
+    )
+    bbox_a_area = max(0.0, bbox_a[2] - bbox_a[0]) * max(
+        0.0,
+        bbox_a[3] - bbox_a[1],
+    )
+    bbox_b_area = max(0.0, bbox_b[2] - bbox_b[0]) * max(
+        0.0,
+        bbox_b[3] - bbox_b[1],
+    )
+    smaller_area = min(bbox_a_area, bbox_b_area)
+    if smaller_area == 0:
+        return 0.0
+    return intersection_width * intersection_height / smaller_area
+
+
+def _is_adjacent_offset_duplicate_char(
+    previous_char: Char,
+    current_char: Char,
+) -> bool:
+    """识别相邻字符中由对角平移阴影产生的第二个重复字符。"""
+    if _get_visible_char_signature(previous_char) != _get_visible_char_signature(current_char):
+        return False
+
+    previous_bbox = _char_bbox_values(previous_char.get("bbox"))
+    current_bbox = _char_bbox_values(current_char.get("bbox"))
+    if previous_bbox is None or current_bbox is None:
+        return False
+
+    x_start_offset = current_bbox[0] - previous_bbox[0]
+    y_start_offset = current_bbox[1] - previous_bbox[1]
+    x_end_offset = current_bbox[2] - previous_bbox[2]
+    y_end_offset = current_bbox[3] - previous_bbox[3]
+
+    # 阴影层应是同一字符框的刚性平移，避免把大小不同的相邻同字误判为重复。
+    if (
+        abs(x_start_offset - x_end_offset) > OFFSET_DUPLICATE_TRANSLATION_TOLERANCE
+        or abs(y_start_offset - y_end_offset) > OFFSET_DUPLICATE_TRANSLATION_TOLERANCE
+    ):
+        return False
+
+    if not (
+        NEAR_IDENTICAL_CHAR_BBOX_TOLERANCE < abs(x_start_offset) <= OFFSET_DUPLICATE_CHAR_BBOX_TOLERANCE
+        and NEAR_IDENTICAL_CHAR_BBOX_TOLERANCE < abs(y_start_offset) <= OFFSET_DUPLICATE_CHAR_BBOX_TOLERANCE
+    ):
+        return False
+
+    return _calculate_bbox_overlap_in_smaller_area(previous_bbox, current_bbox) >= OFFSET_DUPLICATE_MIN_BBOX_OVERLAP_RATIO
+
+
+def _get_near_identical_bbox_bucket_key(
+    bbox_coords: tuple[float, float, float, float],
+) -> tuple[int, int]:
+    """按字符 bbox 左上角生成空间桶 key，缩小近重合判断的候选范围。"""
+    return (
+        math.floor(bbox_coords[0] / NEAR_IDENTICAL_CHAR_BBOX_TOLERANCE),
+        math.floor(bbox_coords[1] / NEAR_IDENTICAL_CHAR_BBOX_TOLERANCE),
+    )
+
+
+def _iter_neighbor_bbox_bucket_keys(
+    bucket_key: tuple[int, int],
+) -> Iterator[tuple[int, int]]:
+    """遍历当前桶及周围 8 个邻近桶，覆盖 bbox 容差范围内的候选字符。"""
+    bucket_x, bucket_y = bucket_key
+    for offset_x in (-1, 0, 1):
+        for offset_y in (-1, 0, 1):
+            yield bucket_x + offset_x, bucket_y + offset_y
+
+
+def _deduplicate_near_identical_chars(chars: list[Char]) -> list[Char]:
+    """清理 PDFium 文本层边界处同字符、同位置及对角阴影重复字符。"""
+    seen_visible_char_bboxes: dict[
+        tuple[str, tuple[Any, Any, Any, Any], float],
+        dict[tuple[int, int], list[tuple[float, float, float, float]]],
+    ] = {}
+    deduplicated_chars: list[Char] = []
+
+    for char in chars:
+        text = str(char.get("char", ""))
+        if not text or text.isspace():
+            deduplicated_chars.append(char)
+            continue
+
+        visible_char_key = _get_visible_char_signature(char)
+        bbox_coords = _char_bbox_values(char.get("bbox"))
+        if bbox_coords is None:
+            deduplicated_chars.append(char)
+            continue
+
+        if deduplicated_chars and _is_adjacent_offset_duplicate_char(
+            deduplicated_chars[-1],
+            char,
+        ):
+            continue
+
+        bbox_bucket_key = _get_near_identical_bbox_bucket_key(bbox_coords)
+        visible_char_bbox_buckets = seen_visible_char_bboxes.setdefault(
+            visible_char_key,
+            {},
+        )
+        if any(
+            _is_near_identical_bbox(bbox_coords, seen_bbox)
+            for neighbor_bucket_key in _iter_neighbor_bbox_bucket_keys(bbox_bucket_key)
+            for seen_bbox in visible_char_bbox_buckets.get(neighbor_bucket_key, [])
+        ):
+            continue
+
+        visible_char_bbox_buckets.setdefault(bbox_bucket_key, []).append(bbox_coords)
+        deduplicated_chars.append(char)
+
+    return deduplicated_chars
+
+
+def _restore_pdfium_surrogate_pairs(
+    chars: list[Char],
+    textpage: pdfium.PdfTextPage,
+    *,
+    raw_codes: dict[int, int] | None = None,
+) -> list[Char]:
+    """利用 PDFium 原始 UTF-16 code unit 恢复 pdftext 丢失的补充平面字符。"""
+    if not any(
+        len(text := str(char.get("char", ""))) == 1 and (text == "\ufffd" or 0xD800 <= ord(text) <= 0xDFFF) for char in chars
+    ):
+        return chars
+
+    try:
+        textpage_raw = textpage.raw
+        char_count = int(textpage.count_chars())
+    except Exception:
+        textpage_raw = None
+        char_count = 0
+
+    restored_chars: list[Char] = []
+    consumed_char_indices: set[int] = set()
+
+    def get_unicode(handle: object, index: int) -> int:
+        """优先复用首次读取的原始码值，仅为独立辅助调用读取原生接口。"""
+        return raw_codes[index] if raw_codes is not None else int(pdfium_c.FPDFText_GetUnicode(handle, index))
+
+    for char in chars:
+        text = str(char.get("char", ""))
+        raw_char_idx = char.get("char_idx")
+        try:
+            char_idx = int(raw_char_idx) if raw_char_idx is not None else -1
+        except (TypeError, ValueError):
+            char_idx = -1
+
+        if char_idx in consumed_char_indices:
+            continue
+
+        raw_code = None
+        if (
+            textpage_raw is not None
+            and 0 <= char_idx < char_count
+            and len(text) == 1
+            and (text == "\ufffd" or 0xD800 <= ord(text) <= 0xDFFF)
+        ):
+            raw_code = int(get_unicode(textpage_raw, char_idx))
+
+        high_surrogate = None
+        low_surrogate = None
+        if raw_code is not None and 0xD800 <= raw_code <= 0xDBFF and char_idx + 1 < char_count:
+            next_code = int(get_unicode(textpage_raw, char_idx + 1))
+            if 0xDC00 <= next_code <= 0xDFFF:
+                high_surrogate = raw_code
+                low_surrogate = next_code
+                consumed_char_indices.add(char_idx + 1)
+        elif raw_code is not None and 0xDC00 <= raw_code <= 0xDFFF and char_idx > 0:
+            previous_code = int(get_unicode(textpage_raw, char_idx - 1))
+            if 0xD800 <= previous_code <= 0xDBFF:
+                high_surrogate = previous_code
+                low_surrogate = raw_code
+
+        if high_surrogate is not None and low_surrogate is not None:
+            restored_char = cast(Char, dict(char))
+            restored_char["char"] = chr(0x10000 + ((high_surrogate - 0xD800) << 10) + (low_surrogate - 0xDC00))
+            restored_char["source_indices"] = tuple(
+                sorted(
+                    set(
+                        (
+                            *char.get("source_indices", (char_idx,)),
+                            char_idx + 1 if raw_code is not None and raw_code <= 0xDBFF else char_idx - 1,
+                        )
+                    )
+                )
+            )
+            restored_chars.append(restored_char)
+            continue
+
+        if len(text) == 1 and 0xD800 <= ord(text) <= 0xDFFF:
+            restored_char = cast(Char, dict(char))
+            restored_char["char"] = "\ufffd"
+            restored_chars.append(restored_char)
+            continue
+
+        restored_chars.append(char)
+
+    return restored_chars
+
+
+def _page_to_image(page: pdfium.PdfPage, scale: float, max_edge: int) -> PDFPageImage:
+    """按原缩放与长边上限复制页面像素，并返回独立持有的图片。"""
+    long_edge_length = max(*page.get_size())
+    if (long_edge_length * scale) > max_edge:
+        scale = max_edge / long_edge_length
+
+    bitmap = None
+    try:
+        bitmap = page.render(scale=scale)  # type: ignore
+        bitmap = cast(pdfium.PdfBitmap, bitmap)
+        pil_image = bitmap.to_pil()
+    finally:
+        _try_close(bitmap)
+
+    return PDFPageImage(pil_image=pil_image, scale=scale)
+
+
+def _extract_page_text_geometry(
+    page: pdfium.PdfPage,
+    *,
+    include_extended_geometry: bool,
+) -> PDFPageTextGeometry:
+    """在调用方持有的页面和锁内读取字符，使批量提取与独立接口共用实现。"""
+    textpage = None
+    try:
+        textpage = page.get_textpage()
+        raw_page_bbox: list[float] = list(page.get_bbox())
+        page_rotation: int = 0
+        try:
+            page_rotation = page.get_rotation()
+        except Exception:
+            pass
+        chars = get_chars(textpage, raw_page_bbox, page_rotation, include_geometry=include_extended_geometry)
+        raw_codes = {char["char_idx"]: char["raw_code"] for char in chars}
+        chars = deduplicate_chars(chars)
+        chars = _restore_pdfium_surrogate_pairs(chars, textpage, raw_codes=raw_codes)
+        chars = _deduplicate_near_identical_chars(chars)
+        if include_extended_geometry:
+            loose_bboxes = {
+                char["char_idx"]: char["loose_bbox"]
+                for char in chars
+                if char.get("loose_bbox") is not None and abs(char["rotation"]) > 1e-9
+            }
+            tight_bboxes = {char["char_idx"]: char["tight_bbox"] for char in chars if char.get("tight_bbox") is not None}
+            origins = {char["char_idx"]: char["origin"] for char in chars if char.get("origin") is not None}
+        else:
+            loose_bboxes, tight_bboxes, origins = {}, {}, {}
+    finally:
+        _try_close(textpage)
+    return PDFPageTextGeometry(
+        chars=chars,
+        tight_bboxes=tight_bboxes,
+        origins=origins,
+        loose_bboxes=loose_bboxes,
+    )

docvortex/document/pdf/pdfium.py

@@ -0,0 +1,325 @@
+import os
+import threading
+from contextlib import contextmanager
+from dataclasses import dataclass, field
+from io import BytesIO
+from typing import Any, Iterator, Sequence, TypeVar
+
+from loguru import logger
+
+from .font_runtime import PdfiumFontError, PdfiumRuntimeInfo, _FontProvider
+
+_pdfium_lock = threading.RLock()
+_font_provider: _FontProvider | None = None
+
+T = TypeVar("T")
+
+
+def _check_runtime_process() -> None:
+    """拒绝复用 fork 继承的字体接口；渲染 worker 应通过 spawn/forkserver 独立初始化。"""
+    if _font_provider is not None and _font_provider.pid != os.getpid():
+        raise PdfiumFontError("Inherited PDFium font runtime: use spawn/forkserver instead of forking after PDF use")
+
+
+def initialize_pdfium_runtime() -> PdfiumRuntimeInfo:
+    """幂等安装本进程的固定 CJK 字体提供器；必须先于首次 PDF 字体使用。"""
+    global _font_provider
+    _check_runtime_process()
+    with _pdfium_lock:
+        if _font_provider is None:
+            import pypdfium2 as pdfium
+            import pypdfium2.raw as raw
+
+            provider = _FontProvider(raw, str(pdfium.PDFIUM_INFO))
+            # 注册前保留强引用，保证即使安装阶段回调失败，C 指针也不会指向被回收的对象。
+            _font_provider = provider
+            provider.install()
+        _font_provider.raise_if_failed()
+        return _font_provider.info
+
+
+@dataclass
+class PdfiumRewriteResult:
+    """记录 PDFium 安全重写结果，供调用方按实际保留页修正原始页号。"""
+
+    pdf_bytes: bytes
+    retained_page_indices: list[int] | None = None
+    broken_page_indices: list[int] = field(default_factory=list)
+    used_original: bool = False
+
+
+@contextmanager
+def pdfium_guard() -> Iterator[None]:
+    """串行化访问并确保字体运行时就绪，在原生栈退出后传播字体故障。"""
+    _check_runtime_process()
+    with _pdfium_lock:
+        initialize_pdfium_runtime()
+        assert _font_provider is not None
+        try:
+            yield
+        finally:
+            _font_provider.raise_if_failed()
+
+
+def close_pdfium_document(pdf_doc: Any) -> None:
+    """清理时只持锁，不安装字体、不重建已销毁的 PDFium 运行时。"""
+    if pdf_doc is None:
+        return
+    with _pdfium_lock:
+        pdf_doc.close()
+
+
+def close_pdfium_child(pdfium_obj: Any) -> None:
+    """显式关闭 PDFium 子对象，避免依赖 weakref/finalizer 延迟释放 native 资源。"""
+    if pdfium_obj is None:
+        return
+    close = getattr(pdfium_obj, "close", None)
+    if callable(close):
+        with _pdfium_lock:
+            close()
+
+
+def close_pdfium_objects_safely(*pdfium_objs: object, owner: str = "pdfium cleanup") -> None:
+    """清理多个 PDFium 对象时逐个尝试关闭，避免前一个关闭失败阻断后续对象释放。"""
+    for pdfium_obj in pdfium_objs:
+        if pdfium_obj is None:
+            continue
+        try:
+            close_pdfium_child(pdfium_obj)
+        except Exception as exc:
+            logger.warning(f"Failed to close PDFium object during {owner}: {exc}")
+
+
+def get_loadable_pdfium_page_indices(
+    src_pdf_bytes: bytes,
+    start_page_id: int = 0,
+    end_page_id: int | None = None,
+) -> tuple[list[int], list[int]]:
+    """逐页探测 PDFium 可加载页面，返回可保留页和损坏页的 0-based 索引。"""
+    import pypdfium2 as pdfium
+
+    loadable_page_indices = []
+    broken_page_indices = []
+    pdf_doc = None
+
+    try:
+        with pdfium_guard():
+            pdf_doc = pdfium.PdfDocument(src_pdf_bytes)
+            total_page_count = len(pdf_doc)
+            if total_page_count == 0:
+                return [], []
+
+            normalized_start_page_id = max(0, start_page_id)
+            normalized_end_page_id = end_page_id if end_page_id is not None and end_page_id >= 0 else total_page_count - 1
+            if normalized_end_page_id > total_page_count - 1:
+                normalized_end_page_id = total_page_count - 1
+            if normalized_start_page_id > normalized_end_page_id:
+                return [], []
+
+            for page_index in range(
+                normalized_start_page_id,
+                normalized_end_page_id + 1,
+            ):
+                page = None
+                try:
+                    page = pdf_doc[page_index]
+                    page.get_size()
+                    loadable_page_indices.append(page_index)
+                except Exception:
+                    broken_page_indices.append(page_index)
+                finally:
+                    close_pdfium_child(page)
+    finally:
+        close_pdfium_document(pdf_doc)
+
+    return loadable_page_indices, broken_page_indices
+
+
+def _normalize_rewrite_page_indices(
+    total_page_count: int,
+    start_page_id: int = 0,
+    end_page_id: int | None = None,
+    page_indices: Sequence[int] | None = None,
+) -> list[int]:
+    """按 rewrite_pdf_bytes_with_pdfium 的规则归一化实际导出的 0-based 页号。"""
+    if total_page_count == 0:
+        return []
+
+    if page_indices is not None:
+        return sorted({int(page_index) for page_index in page_indices if 0 <= int(page_index) < total_page_count})
+
+    normalized_start_page_id = max(0, start_page_id)
+    normalized_end_page_id = end_page_id if end_page_id is not None and end_page_id >= 0 else total_page_count - 1
+    if normalized_end_page_id > total_page_count - 1:
+        normalized_end_page_id = total_page_count - 1
+    if normalized_start_page_id > normalized_end_page_id:
+        return []
+    return list(range(normalized_start_page_id, normalized_end_page_id + 1))
+
+
+def _get_rewrite_page_indices_from_pdf(
+    src_pdf_bytes: bytes,
+    start_page_id: int = 0,
+    end_page_id: int | None = None,
+    page_indices: Sequence[int] | None = None,
+) -> list[int]:
+    """读取源 PDF 页数并计算本次重写会保留的原始页号。"""
+    import pypdfium2 as pdfium
+
+    pdf_doc = None
+    try:
+        with pdfium_guard():
+            pdf_doc = pdfium.PdfDocument(src_pdf_bytes)
+            return _normalize_rewrite_page_indices(
+                len(pdf_doc),
+                start_page_id=start_page_id,
+                end_page_id=end_page_id,
+                page_indices=page_indices,
+            )
+    finally:
+        close_pdfium_document(pdf_doc)
+
+
+def rewrite_pdf_bytes_with_pdfium(
+    src_pdf_bytes: bytes,
+    start_page_id: int = 0,
+    end_page_id: int | None = None,
+    page_indices: Sequence[int] | None = None,
+) -> bytes:
+    import pypdfium2 as pdfium
+
+    pdf_doc = None
+    output_doc = None
+    try:
+        with pdfium_guard():
+            pdf_doc = pdfium.PdfDocument(src_pdf_bytes)
+            total_page_count = len(pdf_doc)
+            if total_page_count == 0:
+                return b""
+
+            normalized_page_indices = _normalize_rewrite_page_indices(
+                total_page_count,
+                start_page_id=start_page_id,
+                end_page_id=end_page_id,
+                page_indices=page_indices,
+            )
+            if not normalized_page_indices:
+                return b""
+
+            output_doc = pdfium.PdfDocument.new()
+            output_doc.import_pages(pdf_doc, normalized_page_indices)
+
+            output_buffer = BytesIO()
+            output_doc.save(output_buffer)
+            return output_buffer.getvalue()
+    finally:
+        close_pdfium_objects_safely(
+            output_doc,
+            pdf_doc,
+            owner="rewrite_pdf_bytes_with_pdfium",
+        )
+
+
+def safe_rewrite_pdf_bytes_with_pdfium(
+    src_pdf_bytes: bytes,
+    start_page_id: int = 0,
+    end_page_id: int | None = None,
+    page_indices: Sequence[int] | None = None,
+) -> bytes:
+    """安全重写 PDF 字节；常规重写失败时跳过损坏页并保留可加载页面。"""
+    return safe_rewrite_pdf_bytes_with_pdfium_result(
+        src_pdf_bytes,
+        start_page_id=start_page_id,
+        end_page_id=end_page_id,
+        page_indices=page_indices,
+    ).pdf_bytes
+
+
+def safe_rewrite_pdf_bytes_with_pdfium_result(
+    src_pdf_bytes: bytes,
+    start_page_id: int = 0,
+    end_page_id: int | None = None,
+    page_indices: Sequence[int] | None = None,
+) -> PdfiumRewriteResult:
+    """安全重写 PDF 字节，并返回重写后 PDF 对应的原始页号映射。"""
+    try:
+        rebuilt_pdf_bytes = rewrite_pdf_bytes_with_pdfium(
+            src_pdf_bytes,
+            start_page_id=start_page_id,
+            end_page_id=end_page_id,
+            page_indices=page_indices,
+        )
+        if rebuilt_pdf_bytes:
+            retained_page_indices = _get_rewrite_page_indices_from_pdf(
+                src_pdf_bytes,
+                start_page_id=start_page_id,
+                end_page_id=end_page_id,
+                page_indices=page_indices,
+            )
+            return PdfiumRewriteResult(
+                pdf_bytes=rebuilt_pdf_bytes,
+                retained_page_indices=retained_page_indices,
+            )
+        logger.warning("PDFium rewrite returned empty bytes, trying to skip broken pages.")
+    except PdfiumFontError:
+        raise
+    except Exception as fallback_error:
+        logger.warning(f"Error in converting PDF bytes with pdfium: {fallback_error}, trying to skip broken pages.")
+
+    try:
+        if page_indices is not None:
+            requested_page_indices = sorted({int(page_index) for page_index in page_indices if int(page_index) >= 0})
+            if not requested_page_indices:
+                logger.warning("PDFium safe rewrite received no valid requested pages, using original PDF bytes.")
+                return PdfiumRewriteResult(pdf_bytes=src_pdf_bytes, retained_page_indices=None, used_original=True)
+            probe_start_page_id = requested_page_indices[0]
+            probe_end_page_id = requested_page_indices[-1]
+        else:
+            requested_page_indices = None
+            probe_start_page_id = start_page_id
+            probe_end_page_id = end_page_id
+
+        loadable_page_indices, broken_page_indices = get_loadable_pdfium_page_indices(
+            src_pdf_bytes,
+            start_page_id=probe_start_page_id,
+            end_page_id=probe_end_page_id,
+        )
+        if requested_page_indices is not None:
+            requested_page_index_set = set(requested_page_indices)
+            loadable_page_indices = [
+                page_index for page_index in loadable_page_indices if page_index in requested_page_index_set
+            ]
+            broken_page_indices = [page_index for page_index in broken_page_indices if page_index in requested_page_index_set]
+
+        if broken_page_indices:
+            skipped_pages = [page_index + 1 for page_index in broken_page_indices]
+            logger.warning(f"Skipped broken PDF pages during PDFium rewrite: {skipped_pages}")
+        if not loadable_page_indices:
+            logger.warning("PDFium skip-broken-page rewrite found no loadable pages, using original PDF bytes.")
+            return PdfiumRewriteResult(
+                pdf_bytes=src_pdf_bytes,
+                retained_page_indices=None,
+                broken_page_indices=broken_page_indices,
+                used_original=True,
+            )
+
+        rebuilt_pdf_bytes = rewrite_pdf_bytes_with_pdfium(
+            src_pdf_bytes,
+            start_page_id=probe_start_page_id,
+            end_page_id=probe_end_page_id,
+            page_indices=loadable_page_indices,
+        )
+        if rebuilt_pdf_bytes:
+            return PdfiumRewriteResult(
+                pdf_bytes=rebuilt_pdf_bytes,
+                retained_page_indices=loadable_page_indices,
+                broken_page_indices=broken_page_indices,
+            )
+        logger.warning("PDFium skip-broken-page rewrite returned empty bytes, using original PDF bytes.")
+    except PdfiumFontError:
+        raise
+    except Exception as fallback_error:
+        logger.warning(
+            f"Error in converting PDF bytes with skip-broken-page fallback: {fallback_error}, using original PDF bytes."
+        )
+    return PdfiumRewriteResult(pdf_bytes=src_pdf_bytes, retained_page_indices=None, used_original=True)

docvortex/document/pdf/raster.py

@@ -0,0 +1,46 @@
+from loguru import logger
+from PIL import Image
+from pypdfium2 import PdfBitmap, PdfPage
+
+from .pdfium import pdfium_guard
+
+DEFAULT_PDF_IMAGE_DPI = 200
+DEFAULT_MAX_RENDER_EDGE = 3500
+
+
+def estimate_page_image_bytes(page_size: tuple[float, float], dpi: int = DEFAULT_PDF_IMAGE_DPI) -> int:
+    """按现有渲染缩放估算四通道页图字节，用于限制批量驻留内存。"""
+    import math
+
+    width, height = page_size
+    scale = min(dpi / 72, DEFAULT_MAX_RENDER_EDGE / max(width, height))
+    return math.ceil(width * scale) * math.ceil(height * scale) * 4
+
+
+def page_to_image(
+    page: PdfPage,
+    dpi: int = DEFAULT_PDF_IMAGE_DPI,
+    max_width_or_height: int = DEFAULT_MAX_RENDER_EDGE,
+) -> tuple[Image.Image, float]:
+    """按既有 DPI 与长边上限渲染页面，并独立持有返回图片的像素。"""
+    with pdfium_guard():
+        scale = dpi / 72
+
+        long_side_length = max(*page.get_size())
+        if (long_side_length * scale) > max_width_or_height:
+            scale = max_width_or_height / long_side_length
+
+        bitmap: PdfBitmap | None = None
+        try:
+            bitmap = page.render(scale=scale)  # type: ignore
+            image = bitmap.to_pil().copy()
+        finally:
+            if bitmap is not None:
+                try:
+                    bitmap.close()
+                except Exception as e:
+                    logger.error(f"Failed to close bitmap: {e}")
+    return image, scale
+
+
+__all__ = ["page_to_image"]