docvortex 0.2.1__py3-none-any.whl

docvortex/document/pdf/native_objects.py

@@ -0,0 +1,902 @@
+"""PDF Path、Image 与 Form 对象提取，保持原生提取算法与资源语义。"""
+
+from __future__ import annotations
+import ctypes
+import hashlib
+import logging
+import math
+from typing import Any, Iterator
+import pypdfium2 as pdfium
+import pypdfium2.raw as pdfium_c
+from ...schema import BBox
+
+from .native_contracts import (
+    DRAWING_FORM_MAX_DEPTH,
+    DRAWING_LINE_AXIS_ABSOLUTE_TOLERANCE,
+    DRAWING_LINE_AXIS_RATIO_TOLERANCE,
+    DRAWING_LINE_MERGE_TOLERANCE,
+    DRAWING_LINE_MIN_LENGTH,
+    DRAWING_THIN_RECT_MAX_THICKNESS,
+    DRAWING_THIN_RECT_MIN_ASPECT_RATIO,
+    PDFDrawingLine,
+    PDFImageInfo,
+    PDFPathInfo,
+    PDF_IMAGE_FINGERPRINT_MAX_RAW_BYTES,
+    _PathSubpath,
+)
+from .native_coordinates import (
+    _apply_pdf_matrix,
+    _drawing_page_size,
+    _get_raw_object_matrix,
+    _multiply_pdf_matrices,
+    _transform_drawing_point,
+)
+
+logger = logging.getLogger("docvortex.document.pdf.document")
+
+
+def _walk_raw_page_objects_with_depth(
+    container: Any,
+    *,
+    is_form: bool,
+    parent_matrix: tuple[float, float, float, float, float, float],
+    depth: int,
+    target_type: int,
+) -> Iterator[tuple[Any, tuple[float, float, float, float, float, float], int]]:
+    """递归遍历目标对象，并携带累积矩阵及所在 Form 深度。"""
+    if depth >= DRAWING_FORM_MAX_DEPTH:
+        return
+
+    count_objects = pdfium_c.FPDFFormObj_CountObjects if is_form else pdfium_c.FPDFPage_CountObjects
+    get_object = pdfium_c.FPDFFormObj_GetObject if is_form else pdfium_c.FPDFPage_GetObject
+    try:
+        object_count = int(count_objects(container))
+    except Exception:
+        return
+    if object_count < 0:
+        return
+
+    for object_index in range(object_count):
+        try:
+            raw_obj = get_object(container, object_index)
+            if not raw_obj:
+                continue
+            object_type = int(pdfium_c.FPDFPageObj_GetType(raw_obj))
+            object_matrix = _get_raw_object_matrix(raw_obj)
+            if object_matrix is None:
+                continue
+            combined_matrix = _multiply_pdf_matrices(object_matrix, parent_matrix)
+        except Exception:
+            # 单个损坏页面对象不能中断同页其他目标对象遍历。
+            continue
+
+        if object_type == target_type:
+            yield raw_obj, combined_matrix, depth
+        if object_type == pdfium_c.FPDF_PAGEOBJ_FORM:
+            yield from _walk_raw_page_objects_with_depth(
+                raw_obj,
+                is_form=True,
+                parent_matrix=combined_matrix,
+                depth=depth + 1,
+                target_type=target_type,
+            )
+
+
+def _walk_raw_page_objects(
+    container: Any,
+    *,
+    is_form: bool,
+    parent_matrix: tuple[float, float, float, float, float, float],
+    depth: int,
+    target_type: int,
+) -> Iterator[tuple[Any, tuple[float, float, float, float, float, float]]]:
+    """兼容既有调用，仅返回目标对象及累积到页面坐标的矩阵。"""
+
+    for raw_obj, matrix, _form_depth in _walk_raw_page_objects_with_depth(
+        container,
+        is_form=is_form,
+        parent_matrix=parent_matrix,
+        depth=depth,
+        target_type=target_type,
+    ):
+        yield raw_obj, matrix
+
+
+def _walk_raw_path_objects(
+    container: Any,
+    *,
+    is_form: bool,
+    parent_matrix: tuple[float, float, float, float, float, float],
+    depth: int,
+) -> Iterator[tuple[Any, tuple[float, float, float, float, float, float]]]:
+    """递归遍历页面或 Form 中的 Path，并携带累积到页面坐标的矩阵。"""
+    yield from _walk_raw_page_objects(
+        container,
+        is_form=is_form,
+        parent_matrix=parent_matrix,
+        depth=depth,
+        target_type=pdfium_c.FPDF_PAGEOBJ_PATH,
+    )
+
+
+def _iter_raw_path_objects(
+    page: pdfium.PdfPage,
+) -> Iterator[tuple[Any, tuple[float, float, float, float, float, float]]]:
+    """从页面根对象开始遍历全部 Path，包括嵌套 Form 中的 Path。"""
+    identity = (1.0, 0.0, 0.0, 1.0, 0.0, 0.0)
+    yield from _walk_raw_path_objects(
+        page,
+        is_form=False,
+        parent_matrix=identity,
+        depth=0,
+    )
+
+
+def _iter_raw_path_objects_with_depth(
+    page: pdfium.PdfPage,
+) -> Iterator[tuple[Any, tuple[float, float, float, float, float, float], int]]:
+    """遍历全部 Path，并保留其所在 Form 深度供上层过滤图标。"""
+
+    identity = (1.0, 0.0, 0.0, 1.0, 0.0, 0.0)
+    yield from _walk_raw_page_objects_with_depth(
+        page,
+        is_form=False,
+        parent_matrix=identity,
+        depth=0,
+        target_type=pdfium_c.FPDF_PAGEOBJ_PATH,
+    )
+
+
+def _iter_raw_image_objects(
+    page: pdfium.PdfPage,
+) -> Iterator[tuple[Any, tuple[float, float, float, float, float, float]]]:
+    """从页面根对象开始遍历全部点阵图，包括嵌套 Form 中的图片。"""
+    identity = (1.0, 0.0, 0.0, 1.0, 0.0, 0.0)
+    yield from _walk_raw_page_objects(
+        page,
+        is_form=False,
+        parent_matrix=identity,
+        depth=0,
+        target_type=pdfium_c.FPDF_PAGEOBJ_IMAGE,
+    )
+
+
+def _iter_raw_root_form_objects(page: pdfium.PdfPage) -> Iterator[Any]:
+    """只遍历页面根层的 Form，避免把同一矢量图的嵌套子 Form 重复输出。"""
+
+    try:
+        object_count = int(pdfium_c.FPDFPage_CountObjects(page))
+    except Exception:
+        return
+    if object_count < 0:
+        return
+
+    for object_index in range(object_count):
+        try:
+            raw_obj = pdfium_c.FPDFPage_GetObject(page, object_index)
+            if raw_obj and int(pdfium_c.FPDFPageObj_GetType(raw_obj)) == pdfium_c.FPDF_PAGEOBJ_FORM:
+                yield raw_obj
+        except Exception:
+            # 单个损坏对象不能阻断同页其他顶层 Form 的提取。
+            continue
+
+
+def _get_raw_object_rgba(
+    raw_obj: Any,
+    color_getter: Any,
+) -> tuple[int, int, int, int] | None:
+    """读取对象 RGBA；旧 PDFium、不支持的对象或读取失败时返回 None。"""
+
+    red = ctypes.c_uint()
+    green = ctypes.c_uint()
+    blue = ctypes.c_uint()
+    alpha = ctypes.c_uint()
+    try:
+        ok = color_getter(
+            raw_obj,
+            ctypes.byref(red),
+            ctypes.byref(green),
+            ctypes.byref(blue),
+            ctypes.byref(alpha),
+        )
+    except Exception:
+        return None
+    if not ok:
+        return None
+    return (
+        int(red.value),
+        int(green.value),
+        int(blue.value),
+        int(alpha.value),
+    )
+
+
+def _get_raw_object_alpha(raw_obj: Any, color_getter: Any) -> int:
+    """读取对象颜色 alpha；旧 PDFium 或读取失败时按不透明处理。"""
+
+    rgba = _get_raw_object_rgba(raw_obj, color_getter)
+    return rgba[3] if rgba is not None else 255
+
+
+def _get_path_visibility(raw_obj: Any) -> tuple[bool, bool]:
+    """分别判断 Path 的填充与描边是否实际可见。"""
+    fill_mode = ctypes.c_int()
+    stroke = ctypes.c_int()
+    try:
+        ok = pdfium_c.FPDFPath_GetDrawMode(raw_obj, ctypes.byref(fill_mode), ctypes.byref(stroke))
+    except Exception:
+        return False, False
+    if not ok:
+        return False, False
+
+    fill_visible = (
+        fill_mode.value != pdfium_c.FPDF_FILLMODE_NONE and _get_raw_object_alpha(raw_obj, pdfium_c.FPDFPageObj_GetFillColor) > 0
+    )
+    stroke_visible = bool(stroke.value) and _get_raw_object_alpha(raw_obj, pdfium_c.FPDFPageObj_GetStrokeColor) > 0
+    return fill_visible, stroke_visible
+
+
+def _get_raw_stroke_width(raw_obj: Any) -> float:
+    """读取 Path 在对象局部坐标中的描边宽度。"""
+    stroke_width = ctypes.c_float()
+    try:
+        ok = pdfium_c.FPDFPageObj_GetStrokeWidth(raw_obj, ctypes.byref(stroke_width))
+    except Exception:
+        return 0.0
+    if not ok:
+        return 0.0
+    width = abs(float(stroke_width.value))
+    return width if math.isfinite(width) else 0.0
+
+
+def _get_segment_stroke_width(
+    raw_width: float,
+    start: tuple[float, float],
+    end: tuple[float, float],
+    matrix: tuple[float, float, float, float, float, float],
+) -> float:
+    """按线段局部法向量换算非等比矩阵下的实际描边宽度。"""
+    delta_x = end[0] - start[0]
+    delta_y = end[1] - start[1]
+    segment_length = math.hypot(delta_x, delta_y)
+    a, b, c, d, _, _ = matrix
+    if segment_length <= 0:
+        scale = math.sqrt(abs(a * d - b * c))
+    else:
+        normal_x = -delta_y / segment_length
+        normal_y = delta_x / segment_length
+        transformed_x = a * normal_x + c * normal_y
+        transformed_y = b * normal_x + d * normal_y
+        scale = math.hypot(transformed_x, transformed_y)
+    width = raw_width * scale
+    return width if math.isfinite(width) else 0.0
+
+
+def _read_raw_path_subpaths(raw_obj: Any) -> list[_PathSubpath]:
+    """读取 Path 段并拆为子路径，只把 LINETO 与闭合边记录为直线段。"""
+    try:
+        segment_count = int(pdfium_c.FPDFPath_CountSegments(raw_obj))
+    except Exception:
+        return []
+    if segment_count <= 0:
+        return []
+
+    subpaths: list[_PathSubpath] = []
+    current_subpath: _PathSubpath | None = None
+    current_point: tuple[float, float] | None = None
+    subpath_start: tuple[float, float] | None = None
+
+    for segment_index in range(segment_count):
+        try:
+            segment = pdfium_c.FPDFPath_GetPathSegment(raw_obj, segment_index)
+            if not segment:
+                continue
+            x = ctypes.c_float()
+            y = ctypes.c_float()
+            if not pdfium_c.FPDFPathSegment_GetPoint(segment, ctypes.byref(x), ctypes.byref(y)):
+                continue
+            point = (float(x.value), float(y.value))
+            segment_type = int(pdfium_c.FPDFPathSegment_GetType(segment))
+            segment_closes = bool(pdfium_c.FPDFPathSegment_GetClose(segment))
+        except Exception:
+            continue
+
+        if segment_type == pdfium_c.FPDF_SEGMENT_MOVETO:
+            if current_subpath is not None and current_subpath.points:
+                subpaths.append(current_subpath)
+            current_subpath = _PathSubpath(points=[point], straight_segments=[])
+            current_point = point
+            subpath_start = point
+        else:
+            if current_subpath is None:
+                current_subpath = _PathSubpath(points=[point], straight_segments=[])
+                current_point = point
+                subpath_start = point
+            else:
+                current_subpath.points.append(point)
+                if segment_type == pdfium_c.FPDF_SEGMENT_LINETO and current_point is not None:
+                    current_subpath.straight_segments.append((current_point, point))
+                current_point = point
+
+        if segment_closes and current_subpath is not None and current_point is not None and subpath_start is not None:
+            if current_point != subpath_start:
+                current_subpath.straight_segments.append((current_point, subpath_start))
+            current_subpath.closed = True
+            current_point = subpath_start
+
+    if current_subpath is not None and current_subpath.points:
+        subpaths.append(current_subpath)
+    return subpaths
+
+
+def _transform_path_subpath(
+    subpath: _PathSubpath,
+    matrix: tuple[float, float, float, float, float, float],
+    page_bbox: BBox,
+    page_rotation: int,
+) -> _PathSubpath:
+    """将一个子路径从对象局部坐标转换为页面左上坐标。"""
+
+    def transform(point: tuple[float, float]) -> tuple[float, float]:
+        """先应用对象/Form 矩阵，再应用页面坐标与旋转转换。"""
+        return _transform_drawing_point(_apply_pdf_matrix(point, matrix), page_bbox, page_rotation)
+
+    return _PathSubpath(
+        points=[transform(point) for point in subpath.points],
+        straight_segments=[(transform(start), transform(end)) for start, end in subpath.straight_segments],
+        closed=subpath.closed,
+    )
+
+
+def _path_info_from_object(
+    raw_obj: Any,
+    matrix: tuple[float, float, float, float, float, float],
+    page_bbox: BBox,
+    page_rotation: int,
+    form_depth: int,
+    source_index: int,
+    *,
+    subpaths: list[_PathSubpath] | None = None,
+) -> PDFPathInfo | None:
+    """将一个原始 Path 转换为页面几何；贝塞尔控制点也纳入保守 bbox。"""
+
+    try:
+        segment_count = int(pdfium_c.FPDFPath_CountSegments(raw_obj))
+    except Exception:
+        return None
+    if segment_count <= 0:
+        return None
+
+    fill_visible, stroke_visible = _get_path_visibility(raw_obj)
+    points = [
+        point
+        for raw_subpath in (_read_raw_path_subpaths(raw_obj) if subpaths is None else subpaths)
+        for point in _transform_path_subpath(
+            raw_subpath,
+            matrix,
+            page_bbox,
+            page_rotation,
+        ).points
+    ]
+    if not points:
+        return None
+    coordinates = [coordinate for point in points for coordinate in point]
+    if not all(math.isfinite(value) for value in coordinates):
+        return None
+
+    page_width, page_height = _drawing_page_size(page_bbox, page_rotation)
+    stroke_margin = 0.0
+    if stroke_visible:
+        a, b, c, d, _, _ = matrix
+        stroke_scale = max(math.hypot(a, b), math.hypot(c, d))
+        stroke_margin = 0.5 * _get_raw_stroke_width(raw_obj) * stroke_scale
+    bbox = (
+        max(0.0, min(point[0] for point in points) - stroke_margin),
+        max(0.0, min(point[1] for point in points) - stroke_margin),
+        min(page_width, max(point[0] for point in points) + stroke_margin),
+        min(page_height, max(point[1] for point in points) + stroke_margin),
+    )
+    if bbox[2] <= bbox[0] or bbox[3] <= bbox[1]:
+        return None
+    return PDFPathInfo(
+        bbox=bbox,
+        segment_count=segment_count,
+        fill_visible=fill_visible,
+        stroke_visible=stroke_visible,
+        form_depth=form_depth,
+        source_index=source_index,
+        fill_rgba=(
+            _get_raw_object_rgba(
+                raw_obj,
+                pdfium_c.FPDFPageObj_GetFillColor,
+            )
+            if fill_visible
+            else None
+        ),
+    )
+
+
+def _get_thin_filled_subpath_line(
+    subpath: _PathSubpath,
+    page_size: tuple[float, float],
+) -> PDFDrawingLine | None:
+    """把闭合的细长填充子路径折叠为一条中心线，避免把矩形四边重复输出。"""
+    if not subpath.closed or len(subpath.points) < 4:
+        return None
+    x_values = [point[0] for point in subpath.points]
+    y_values = [point[1] for point in subpath.points]
+    x0, x1 = min(x_values), max(x_values)
+    y0, y1 = min(y_values), max(y_values)
+    width = x1 - x0
+    height = y1 - y0
+    long_side = max(width, height)
+    short_side = min(width, height)
+    if (
+        long_side < DRAWING_LINE_MIN_LENGTH
+        or short_side > DRAWING_THIN_RECT_MAX_THICKNESS
+        or long_side < DRAWING_THIN_RECT_MIN_ASPECT_RATIO * max(short_side, 0.01)
+    ):
+        return None
+    if width >= height:
+        return _make_axis_drawing_line((x0, (y0 + y1) / 2), (x1, (y0 + y1) / 2), short_side, page_size)
+    return _make_axis_drawing_line(((x0 + x1) / 2, y0), ((x0 + x1) / 2, y1), short_side, page_size)
+
+
+def _make_axis_drawing_line(
+    start: tuple[float, float],
+    end: tuple[float, float],
+    width: float,
+    page_size: tuple[float, float],
+) -> PDFDrawingLine | None:
+    """将近水平或近竖直线段吸附到坐标轴、裁剪到页面并生成公开结果。"""
+    page_width, page_height = page_size
+    x0, y0 = start
+    x1, y1 = end
+    if not all(math.isfinite(value) for value in (x0, y0, x1, y1, width)):
+        return None
+    delta_x = abs(x1 - x0)
+    delta_y = abs(y1 - y0)
+
+    if delta_x >= delta_y and delta_y <= max(
+        DRAWING_LINE_AXIS_ABSOLUTE_TOLERANCE,
+        delta_x * DRAWING_LINE_AXIS_RATIO_TOLERANCE,
+    ):
+        coordinate = (y0 + y1) / 2
+        if coordinate < 0 or coordinate > page_height:
+            return None
+        main_start = max(0.0, min(x0, x1))
+        main_end = min(page_width, max(x0, x1))
+        if main_end - main_start < DRAWING_LINE_MIN_LENGTH:
+            return None
+        line_width = max(0.0, width, delta_y)
+        half_width = line_width / 2
+        bbox = (
+            main_start,
+            max(0.0, coordinate - half_width),
+            main_end,
+            min(page_height, coordinate + half_width),
+        )
+        return PDFDrawingLine(
+            start=(main_start, coordinate),
+            end=(main_end, coordinate),
+            bbox=bbox,
+            width=line_width,
+            orientation="horizontal",
+        )
+
+    if delta_y > delta_x and delta_x <= max(
+        DRAWING_LINE_AXIS_ABSOLUTE_TOLERANCE,
+        delta_y * DRAWING_LINE_AXIS_RATIO_TOLERANCE,
+    ):
+        coordinate = (x0 + x1) / 2
+        if coordinate < 0 or coordinate > page_width:
+            return None
+        main_start = max(0.0, min(y0, y1))
+        main_end = min(page_height, max(y0, y1))
+        if main_end - main_start < DRAWING_LINE_MIN_LENGTH:
+            return None
+        line_width = max(0.0, width, delta_x)
+        half_width = line_width / 2
+        bbox = (
+            max(0.0, coordinate - half_width),
+            main_start,
+            min(page_width, coordinate + half_width),
+            main_end,
+        )
+        return PDFDrawingLine(
+            start=(coordinate, main_start),
+            end=(coordinate, main_end),
+            bbox=bbox,
+            width=line_width,
+            orientation="vertical",
+        )
+    return None
+
+
+def _extract_path_drawing_lines(
+    raw_obj: Any,
+    matrix: tuple[float, float, float, float, float, float],
+    page_bbox: BBox,
+    page_rotation: int,
+    *,
+    subpaths: list[_PathSubpath] | None = None,
+) -> list[PDFDrawingLine]:
+    """从单个 Path 提取可见直线，坏 Path 返回空结果且不影响同页其他对象。"""
+    fill_visible, stroke_visible = _get_path_visibility(raw_obj)
+    if not fill_visible and not stroke_visible:
+        return []
+
+    page_size = _drawing_page_size(page_bbox, page_rotation)
+    raw_stroke_width = _get_raw_stroke_width(raw_obj) if stroke_visible else 0.0
+    drawing_lines: list[PDFDrawingLine] = []
+    for raw_subpath in _read_raw_path_subpaths(raw_obj) if subpaths is None else subpaths:
+        subpath = _transform_path_subpath(raw_subpath, matrix, page_bbox, page_rotation)
+        if fill_visible:
+            filled_line = _get_thin_filled_subpath_line(subpath, page_size)
+            if filled_line is not None:
+                drawing_lines.append(filled_line)
+                # 细长填充矩形已经折叠为中心线，不再输出其描边四条边。
+                continue
+        if not stroke_visible:
+            continue
+        for (raw_start, raw_end), (segment_start, segment_end) in zip(
+            raw_subpath.straight_segments,
+            subpath.straight_segments,
+        ):
+            stroke_width = _get_segment_stroke_width(raw_stroke_width, raw_start, raw_end, matrix)
+            drawing_line = _make_axis_drawing_line(segment_start, segment_end, stroke_width, page_size)
+            if drawing_line is not None:
+                drawing_lines.append(drawing_line)
+    return drawing_lines
+
+
+def _line_axis_coordinate(line: PDFDrawingLine) -> float:
+    """返回绘图线在垂直于自身方向的轴坐标。"""
+    return line.start[1] if line.orientation == "horizontal" else line.start[0]
+
+
+def _line_main_interval(line: PDFDrawingLine) -> tuple[float, float]:
+    """返回绘图线沿自身方向的起止区间。"""
+    if line.orientation == "horizontal":
+        return line.start[0], line.end[0]
+    return line.start[1], line.end[1]
+
+
+def _combine_collinear_line_group(
+    lines: list[PDFDrawingLine],
+    page_size: tuple[float, float],
+) -> PDFDrawingLine | None:
+    """把坐标接近且区间相连的一组线合并为一条稳定中心线。"""
+    orientation = lines[0].orientation
+    intervals = [_line_main_interval(line) for line in lines]
+    lengths = [max(end - start, 0.01) for start, end in intervals]
+    coordinates = [_line_axis_coordinate(line) for line in lines]
+    total_length = sum(lengths)
+    coordinate = sum(value * length for value, length in zip(coordinates, lengths)) / total_length
+    coordinate_span = max(coordinates) - min(coordinates)
+    width = max(max(line.width for line in lines), coordinate_span + max(line.width for line in lines))
+    main_start = min(start for start, _ in intervals)
+    main_end = max(end for _, end in intervals)
+    if orientation == "horizontal":
+        return _make_axis_drawing_line((main_start, coordinate), (main_end, coordinate), width, page_size)
+    return _make_axis_drawing_line((coordinate, main_start), (coordinate, main_end), width, page_size)
+
+
+def _merge_orientation_lines(
+    lines: list[PDFDrawingLine],
+    page_size: tuple[float, float],
+) -> list[PDFDrawingLine]:
+    """按轴坐标聚类，再合并间距不超过约 2pt 的同方向线段。"""
+    if not lines:
+        return []
+    coordinate_clusters: list[list[PDFDrawingLine]] = []
+    for line in sorted(lines, key=lambda item: (_line_axis_coordinate(item), _line_main_interval(item)[0])):
+        if (
+            not coordinate_clusters
+            or _line_axis_coordinate(line) - min(_line_axis_coordinate(item) for item in coordinate_clusters[-1])
+            > DRAWING_LINE_MERGE_TOLERANCE
+        ):
+            coordinate_clusters.append([line])
+        else:
+            coordinate_clusters[-1].append(line)
+
+    merged: list[PDFDrawingLine] = []
+    for cluster in coordinate_clusters:
+        interval_group: list[PDFDrawingLine] = []
+        interval_end = -math.inf
+        for line in sorted(cluster, key=lambda item: _line_main_interval(item)[0]):
+            line_start, line_end = _line_main_interval(line)
+            if interval_group and line_start > interval_end + DRAWING_LINE_MERGE_TOLERANCE:
+                combined = _combine_collinear_line_group(interval_group, page_size)
+                if combined is not None:
+                    merged.append(combined)
+                interval_group = []
+                interval_end = -math.inf
+            interval_group.append(line)
+            interval_end = max(interval_end, line_end)
+        if interval_group:
+            combined = _combine_collinear_line_group(interval_group, page_size)
+            if combined is not None:
+                merged.append(combined)
+    return merged
+
+
+def _merge_collinear_drawing_lines(
+    lines: list[PDFDrawingLine],
+    page_size: tuple[float, float],
+) -> list[PDFDrawingLine]:
+    """合并水平和竖直共线段，并按页面视觉位置稳定排序。"""
+    horizontal = _merge_orientation_lines(
+        [line for line in lines if line.orientation == "horizontal"],
+        page_size,
+    )
+    vertical = _merge_orientation_lines(
+        [line for line in lines if line.orientation == "vertical"],
+        page_size,
+    )
+    return sorted(
+        [*horizontal, *vertical],
+        key=lambda line: (line.bbox[1], line.bbox[0], line.orientation),
+    )
+
+
+def _image_bbox_from_matrix(
+    matrix: tuple[float, float, float, float, float, float],
+    page_bbox: BBox,
+    page_rotation: int,
+) -> BBox | None:
+    """把点阵图单位矩形经对象/Form 矩阵转换并裁剪为页面左上坐标 bbox。"""
+    page_points = [
+        _transform_drawing_point(
+            _apply_pdf_matrix(point, matrix),
+            page_bbox,
+            page_rotation,
+        )
+        for point in ((0.0, 0.0), (0.0, 1.0), (1.0, 0.0), (1.0, 1.0))
+    ]
+    coordinates = [coordinate for point in page_points for coordinate in point]
+    if not all(math.isfinite(value) for value in coordinates):
+        return None
+
+    page_width, page_height = _drawing_page_size(page_bbox, page_rotation)
+    left = max(0.0, min(point[0] for point in page_points))
+    top = max(0.0, min(point[1] for point in page_points))
+    right = min(page_width, max(point[0] for point in page_points))
+    bottom = min(page_height, max(point[1] for point in page_points))
+    if right <= left or bottom <= top:
+        return None
+    return left, top, right, bottom
+
+
+def _form_bbox_from_object(
+    raw_obj: Any,
+    page_bbox: BBox,
+    page_rotation: int,
+) -> BBox | None:
+    """读取顶层 Form 的页面坐标边界，并转换、裁剪到视觉页面范围。"""
+
+    left = ctypes.c_float()
+    bottom = ctypes.c_float()
+    right = ctypes.c_float()
+    top = ctypes.c_float()
+    try:
+        ok = pdfium_c.FPDFPageObj_GetBounds(
+            raw_obj,
+            ctypes.byref(left),
+            ctypes.byref(bottom),
+            ctypes.byref(right),
+            ctypes.byref(top),
+        )
+    except Exception:
+        return None
+    if not ok:
+        return None
+
+    raw_bbox = (float(left.value), float(bottom.value), float(right.value), float(top.value))
+    if not all(math.isfinite(value) for value in raw_bbox):
+        return None
+    page_points = [
+        _transform_drawing_point(point, page_bbox, page_rotation)
+        for point in (
+            (raw_bbox[0], raw_bbox[1]),
+            (raw_bbox[0], raw_bbox[3]),
+            (raw_bbox[2], raw_bbox[1]),
+            (raw_bbox[2], raw_bbox[3]),
+        )
+    ]
+    page_width, page_height = _drawing_page_size(page_bbox, page_rotation)
+    visual_left = max(0.0, min(point[0] for point in page_points))
+    visual_top = max(0.0, min(point[1] for point in page_points))
+    visual_right = min(page_width, max(point[0] for point in page_points))
+    visual_bottom = min(page_height, max(point[1] for point in page_points))
+    if visual_right <= visual_left or visual_bottom <= visual_top:
+        return None
+    return visual_left, visual_top, visual_right, visual_bottom
+
+
+def _extract_page_image_bboxes(
+    page: pdfium.PdfPage,
+    page_bbox: BBox,
+    page_rotation: int,
+) -> list[BBox]:
+    """在调用方持有 PDFium 锁时提取全部有效点阵图 bbox，并隔离单对象异常。"""
+    image_bboxes: list[BBox] = []
+    for _raw_obj, matrix in _iter_raw_image_objects(page):
+        try:
+            image_bbox = _image_bbox_from_matrix(matrix, page_bbox, page_rotation)
+        except Exception:
+            # 单个损坏 Image 对象不能中断同页其他点阵图提取。
+            continue
+        if image_bbox is not None:
+            image_bboxes.append(image_bbox)
+    return sorted(image_bboxes, key=lambda bbox: (bbox[1], bbox[0], bbox[3], bbox[2]))
+
+
+def _get_raw_image_fingerprint(raw_obj: Any, page: pdfium.PdfPage) -> str | None:
+    """读取受限大小的图片原始流，并结合像素宽高生成 SHA-256 指纹。"""
+
+    metadata = pdfium_c.FPDF_IMAGEOBJ_METADATA()
+    try:
+        if not pdfium_c.FPDFImageObj_GetImageMetadata(
+            raw_obj,
+            page.raw,
+            ctypes.byref(metadata),
+        ):
+            return None
+        width = int(metadata.width)
+        height = int(metadata.height)
+        raw_size = int(pdfium_c.FPDFImageObj_GetImageDataRaw(raw_obj, None, 0))
+    except Exception:
+        return None
+    if width <= 0 or height <= 0 or raw_size <= 0 or raw_size > PDF_IMAGE_FINGERPRINT_MAX_RAW_BYTES:
+        return None
+
+    try:
+        buffer = ctypes.create_string_buffer(raw_size)
+    except (MemoryError, OverflowError):
+        return None
+    try:
+        bytes_read = int(pdfium_c.FPDFImageObj_GetImageDataRaw(raw_obj, buffer, raw_size))
+    except Exception:
+        return None
+    if bytes_read <= 0 or bytes_read > raw_size:
+        return None
+
+    digest = hashlib.sha256()
+    digest.update(f"{width}:{height}:".encode("ascii"))
+    digest.update(buffer.raw[:bytes_read])
+    return digest.hexdigest()
+
+
+def _extract_page_image_infos(
+    page: pdfium.PdfPage,
+    page_bbox: BBox,
+    page_rotation: int,
+) -> list[PDFImageInfo]:
+    """提取全部有效点阵图几何；单图指纹失败时保留 bbox 并按放行处理。"""
+
+    image_infos: list[PDFImageInfo] = []
+    for raw_obj, matrix in _iter_raw_image_objects(page):
+        try:
+            image_bbox = _image_bbox_from_matrix(matrix, page_bbox, page_rotation)
+        except Exception:
+            # 单个损坏 Image 对象不能中断同页其他点阵图提取。
+            continue
+        if image_bbox is None:
+            continue
+        image_infos.append(
+            PDFImageInfo(
+                bbox=image_bbox,
+                fingerprint=_get_raw_image_fingerprint(raw_obj, page),
+            )
+        )
+    return sorted(
+        image_infos,
+        key=lambda info: (info.bbox[1], info.bbox[0], info.bbox[3], info.bbox[2]),
+    )
+
+
+def _extract_page_form_bboxes(
+    page: pdfium.PdfPage,
+    page_bbox: BBox,
+    page_rotation: int,
+) -> list[BBox]:
+    """在调用方持有 PDFium 锁时提取顶层 Form bbox，并隔离单对象异常。"""
+
+    form_bboxes: list[BBox] = []
+    for raw_obj in _iter_raw_root_form_objects(page):
+        try:
+            form_bbox = _form_bbox_from_object(raw_obj, page_bbox, page_rotation)
+        except Exception:
+            # PDFium 遇到个别损坏 Form 时，保留同页其他有效结果。
+            continue
+        if form_bbox is not None:
+            form_bboxes.append(form_bbox)
+    return sorted(form_bboxes, key=lambda bbox: (bbox[1], bbox[0], bbox[3], bbox[2]))
+
+
+def _extract_page_path_infos(
+    page: pdfium.PdfPage,
+    page_bbox: BBox,
+    page_rotation: int,
+) -> list[PDFPathInfo]:
+    """在调用方持有 PDFium 锁时提取 Path 信息，并隔离单对象异常。"""
+
+    path_infos: list[PDFPathInfo] = []
+    for source_index, (raw_obj, matrix, form_depth) in enumerate(_iter_raw_path_objects_with_depth(page)):
+        try:
+            path_info = _path_info_from_object(
+                raw_obj,
+                matrix,
+                page_bbox,
+                page_rotation,
+                form_depth,
+                source_index,
+            )
+        except Exception:
+            # PDFium 遇到个别损坏 Path 时，保留同页其他对象的有效结果。
+            continue
+        if path_info is not None:
+            path_infos.append(path_info)
+    return path_infos
+
+
+def _extract_page_paths_and_lines(
+    page: pdfium.PdfPage,
+    page_bbox: BBox,
+    page_rotation: int,
+) -> tuple[list[PDFDrawingLine], list[PDFPathInfo]]:
+    """一次遍历和解码 Path，分别隔离绘图线与路径信息的派生异常。"""
+
+    drawing_lines: list[PDFDrawingLine] = []
+    path_infos: list[PDFPathInfo] = []
+    for source_index, (raw_obj, matrix, form_depth) in enumerate(_iter_raw_path_objects_with_depth(page)):
+        try:
+            subpaths = _read_raw_path_subpaths(raw_obj)
+        except Exception:
+            continue
+        try:
+            drawing_lines.extend(_extract_path_drawing_lines(raw_obj, matrix, page_bbox, page_rotation, subpaths=subpaths))
+        except Exception:
+            pass
+        try:
+            info = _path_info_from_object(
+                raw_obj,
+                matrix,
+                page_bbox,
+                page_rotation,
+                form_depth,
+                source_index,
+                subpaths=subpaths,
+            )
+        except Exception:
+            continue
+        if info is not None:
+            path_infos.append(info)
+    return _merge_collinear_drawing_lines(drawing_lines, _drawing_page_size(page_bbox, page_rotation)), path_infos
+
+
+def _extract_page_drawing_lines(
+    page: pdfium.PdfPage,
+    page_bbox: BBox,
+    page_rotation: int,
+) -> list[PDFDrawingLine]:
+    """在调用方持有 PDFium 锁时提取整页绘图线，并隔离单个对象异常。"""
+    drawing_lines: list[PDFDrawingLine] = []
+    for raw_obj, matrix in _iter_raw_path_objects(page):
+        try:
+            drawing_lines.extend(
+                _extract_path_drawing_lines(
+                    raw_obj,
+                    matrix,
+                    page_bbox,
+                    page_rotation,
+                )
+            )
+        except Exception:
+            # PDFium 遇到个别损坏 Path 时，保留同页其他对象的有效结果。
+            continue
+    return _merge_collinear_drawing_lines(
+        drawing_lines,
+        _drawing_page_size(page_bbox, page_rotation),
+    )