docvortex 0.2.1__py3-none-any.whl

docvortex/analyzers/native/ofd/constants.py

@@ -0,0 +1,59 @@
+"""OFD 命名空间、版本与安全资源上限。"""
+
+from __future__ import annotations
+
+from typing import Final
+
+
+OFD_NAMESPACE: Final = "http://www.ofdspec.org/2016"
+OFD_LEGACY_NAMESPACE: Final = "http://www.ofdspec.org"
+OFD_NAMESPACES: Final = frozenset({OFD_NAMESPACE, OFD_LEGACY_NAMESPACE})
+OFD_KNOWN_VERSIONS: Final = frozenset({"1.0", "1.1", "1.2"})
+
+MAX_ENTRY_BYTES: Final = 128 * 1024 * 1024
+MAX_TOTAL_BYTES: Final = 512 * 1024 * 1024
+MAX_ENTRY_COUNT: Final = 100_000
+MAX_XML_DEPTH: Final = 256
+MAX_XML_NODES: Final = 2_000_000
+MAX_DOCUMENT_COUNT: Final = 10_000
+MAX_PAGE_COUNT: Final = 10_000
+MAX_ASSET_TOTAL_BYTES: Final = 128 * 1024 * 1024
+MAX_EXPANDED_TEXT_BYTES: Final = 64 * 1024 * 1024
+MAX_EXPANDED_GLYPHS: Final = 2_000_000
+MAX_GLYPH_TOKENS: Final = 2_000_000
+MAX_DELTA_TOKENS: Final = MAX_EXPANDED_GLYPHS
+MAX_PATH_COMMANDS: Final = 2_000_000
+MAX_PATH_TOKENS: Final = MAX_PATH_COMMANDS * 8
+MAX_TABLE_INTERSECTION_CHECKS: Final = MAX_PATH_COMMANDS
+MAX_OBJECT_RECURSION: Final = 64
+MAX_DRAW_PARAM_INHERITANCE: Final = 64
+MAX_FONT_BYTES: Final = 32 * 1024 * 1024
+
+MM_TO_POINTS: Final = 72.0 / 25.4
+
+
+__all__ = [
+    "MAX_ASSET_TOTAL_BYTES",
+    "MAX_DOCUMENT_COUNT",
+    "MAX_DELTA_TOKENS",
+    "MAX_DRAW_PARAM_INHERITANCE",
+    "MAX_ENTRY_BYTES",
+    "MAX_ENTRY_COUNT",
+    "MAX_EXPANDED_GLYPHS",
+    "MAX_EXPANDED_TEXT_BYTES",
+    "MAX_FONT_BYTES",
+    "MAX_GLYPH_TOKENS",
+    "MAX_OBJECT_RECURSION",
+    "MAX_PAGE_COUNT",
+    "MAX_PATH_COMMANDS",
+    "MAX_PATH_TOKENS",
+    "MAX_TABLE_INTERSECTION_CHECKS",
+    "MAX_TOTAL_BYTES",
+    "MAX_XML_DEPTH",
+    "MAX_XML_NODES",
+    "MM_TO_POINTS",
+    "OFD_KNOWN_VERSIONS",
+    "OFD_LEGACY_NAMESPACE",
+    "OFD_NAMESPACE",
+    "OFD_NAMESPACES",
+]

docvortex/analyzers/native/ofd/converter.py

@@ -0,0 +1,31 @@
+"""OFD 二进制流到分页 raw model-list 的转换入口。"""
+
+from __future__ import annotations
+
+from typing import BinaryIO
+
+from .constants import MAX_TOTAL_BYTES
+from .errors import OfdResourceLimitError
+from .package import OfdPackage
+from .reading_order import OfdReadingOrderProjector
+from .scene import OfdSceneBuilder
+
+
+class OfdConverter:
+    """编排 OFD 包读取、场景构建和阅读顺序投影。"""
+
+    def __init__(self) -> None:
+        """初始化空的分页输出。"""
+        self.pages: list[list[dict[str, object]]] = []
+
+    def convert(self, file_binary: BinaryIO) -> None:
+        """读取整份 OFD 并更新分页 model-list。"""
+        file_bytes = file_binary.read(MAX_TOTAL_BYTES + 1)
+        if len(file_bytes) > MAX_TOTAL_BYTES:
+            raise OfdResourceLimitError(f"OFD resource limit exceeded: max_total_bytes={MAX_TOTAL_BYTES}")
+        with OfdPackage(file_bytes) as package:
+            scenes = OfdSceneBuilder(package).build()
+            self.pages = OfdReadingOrderProjector(scenes).project()
+
+
+__all__ = ["OfdConverter"]

docvortex/analyzers/native/ofd/errors.py

@@ -0,0 +1,16 @@
+"""OFD 原生解析错误类型。"""
+
+
+class OfdParseError(ValueError):
+    """表示 OFD 包结构或必需内容不合法。"""
+
+
+class OfdEncryptedError(OfdParseError):
+    """表示 OFD 包或成员使用了不支持的加密。"""
+
+
+class OfdResourceLimitError(OfdParseError):
+    """表示 OFD 输入超过固定资源预算。"""
+
+
+__all__ = ["OfdEncryptedError", "OfdParseError", "OfdResourceLimitError"]

docvortex/analyzers/native/ofd/geometry.py

@@ -0,0 +1,215 @@
+"""OFD 毫米坐标、仿射矩阵与 bbox 工具。"""
+
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass
+from typing import Iterable
+
+from ....schema import BBox
+from .constants import MM_TO_POINTS
+
+Point = tuple[float, float]
+Quad = tuple[Point, Point, Point, Point]
+
+
+@dataclass(frozen=True, slots=True)
+class Affine:
+    """保存 OFD 六参数仿射矩阵。"""
+
+    a: float = 1.0
+    b: float = 0.0
+    c: float = 0.0
+    d: float = 1.0
+    e: float = 0.0
+    f: float = 0.0
+
+    def apply(self, point: Point) -> Point:
+        """把一个局部点变换到目标坐标空间。"""
+        x, y = point
+        return (self.a * x + self.c * y + self.e, self.b * x + self.d * y + self.f)
+
+    def compose(self, inner: Affine) -> Affine:
+        """返回先执行 inner、再执行当前矩阵的组合结果。"""
+        return Affine(
+            a=self.a * inner.a + self.c * inner.b,
+            b=self.b * inner.a + self.d * inner.b,
+            c=self.a * inner.c + self.c * inner.d,
+            d=self.b * inner.c + self.d * inner.d,
+            e=self.a * inner.e + self.c * inner.f + self.e,
+            f=self.b * inner.e + self.d * inner.f + self.f,
+        )
+
+    @classmethod
+    def translation(cls, x: float, y: float) -> Affine:
+        """构造只包含平移的矩阵。"""
+        return cls(e=x, f=y)
+
+    @classmethod
+    def rotation(cls, angle: float) -> Affine:
+        """构造绕局部原点旋转指定角度的矩阵。"""
+        radians = math.radians(angle)
+        cosine = math.cos(radians)
+        sine = math.sin(radians)
+        return cls(a=cosine, b=sine, c=-sine, d=cosine)
+
+
+def parse_numbers(value: str | None, *, expected: int | None = None) -> tuple[float, ...] | None:
+    """把空白分隔的有限数值解析为元组。"""
+    if not value:
+        return None
+    try:
+        numbers = tuple(float(item) for item in value.replace(",", " ").split())
+    except (TypeError, ValueError):
+        return None
+    if expected is not None and len(numbers) != expected:
+        return None
+    if not all(math.isfinite(item) for item in numbers):
+        return None
+    return numbers
+
+
+def parse_st_box(value: str | None) -> BBox | None:
+    """把 OFD 的 x/y/width/height 转换为 x0/y0/x1/y1。"""
+    numbers = parse_numbers(value, expected=4)
+    if numbers is None:
+        return None
+    x, y, width, height = numbers
+    if width <= 0 or height <= 0:
+        return None
+    return (x, y, x + width, y + height)
+
+
+def parse_affine(value: str | None) -> Affine:
+    """解析可选 CTM，缺失或非法时返回单位矩阵。"""
+    numbers = parse_numbers(value, expected=6)
+    return Affine(*numbers) if numbers is not None else Affine()
+
+
+def rect_quad(bbox: BBox) -> Quad:
+    """把轴对齐矩形转换为顺时针四点。"""
+    x0, y0, x1, y1 = bbox
+    return ((x0, y0), (x1, y0), (x1, y1), (x0, y1))
+
+
+def quad_bbox(points: Iterable[Point]) -> BBox | None:
+    """计算一组有限点的轴对齐外接框。"""
+    materialized = list(points)
+    if not materialized or not all(math.isfinite(value) for point in materialized for value in point):
+        return None
+    xs = [point[0] for point in materialized]
+    ys = [point[1] for point in materialized]
+    bbox = (min(xs), min(ys), max(xs), max(ys))
+    return bbox if bbox[2] > bbox[0] and bbox[3] > bbox[1] else None
+
+
+def transform_quad(quad: Quad, transform: Affine) -> Quad:
+    """把四点按给定仿射矩阵变换。"""
+    return tuple(transform.apply(point) for point in quad)  # type: ignore[return-value]
+
+
+def transform_bbox(bbox: BBox, transform: Affine) -> BBox | None:
+    """变换矩形四角并返回目标空间 AABB。"""
+    return quad_bbox(transform_quad(rect_quad(bbox), transform))
+
+
+def bbox_union(bboxes: Iterable[BBox]) -> BBox | None:
+    """合并全部有效 bbox。"""
+    materialized = list(bboxes)
+    if not materialized:
+        return None
+    return (
+        min(item[0] for item in materialized),
+        min(item[1] for item in materialized),
+        max(item[2] for item in materialized),
+        max(item[3] for item in materialized),
+    )
+
+
+def bbox_intersection(first: BBox, second: BBox) -> BBox | None:
+    """返回两个 bbox 的非退化交集。"""
+    bbox = (
+        max(first[0], second[0]),
+        max(first[1], second[1]),
+        min(first[2], second[2]),
+        min(first[3], second[3]),
+    )
+    return bbox if bbox[2] > bbox[0] and bbox[3] > bbox[1] else None
+
+
+def bbox_center(bbox: BBox) -> Point:
+    """返回 bbox 中心点。"""
+    return ((bbox[0] + bbox[2]) / 2.0, (bbox[1] + bbox[3]) / 2.0)
+
+
+def bbox_area(bbox: BBox) -> float:
+    """返回非负 bbox 面积。"""
+    return max(0.0, bbox[2] - bbox[0]) * max(0.0, bbox[3] - bbox[1])
+
+
+def bbox_overlap_ratio(first: BBox, second: BBox) -> float:
+    """返回交集相对较小 bbox 的面积比例。"""
+    intersection = bbox_intersection(first, second)
+    smaller = min(bbox_area(first), bbox_area(second))
+    return bbox_area(intersection) / smaller if intersection is not None and smaller > 0 else 0.0
+
+
+def transform_angle(transform: Affine) -> float:
+    """返回局部 X 轴经过矩阵后的页面角度。"""
+    return math.degrees(math.atan2(transform.b, transform.a)) % 360.0
+
+
+def canonical_angle(angle: float, *, tolerance: float = 5.0) -> int:
+    """把接近直角的角度收敛为 0/90/180/270。"""
+    normalized = angle % 360.0
+    nearest = min((0, 90, 180, 270, 360), key=lambda item: abs(normalized - item))
+    if abs(normalized - nearest) <= tolerance:
+        return nearest % 360
+    return int(round(normalized)) % 360
+
+
+def bbox_to_points(bbox: BBox) -> list[float]:
+    """把毫米 bbox 转换为供共享 XYCut 使用的 point 坐标。"""
+    return [value * MM_TO_POINTS for value in bbox]
+
+
+def normalize_bbox(bbox: BBox, physical_box: BBox) -> list[float] | None:
+    """把页面 bbox 裁剪并归一化到 PhysicalBox。"""
+    clipped = bbox_intersection(bbox, physical_box)
+    if clipped is None:
+        return None
+    width = physical_box[2] - physical_box[0]
+    height = physical_box[3] - physical_box[1]
+    if width <= 0 or height <= 0:
+        return None
+    values = [
+        round((clipped[0] - physical_box[0]) / width, 3),
+        round((clipped[1] - physical_box[1]) / height, 3),
+        round((clipped[2] - physical_box[0]) / width, 3),
+        round((clipped[3] - physical_box[1]) / height, 3),
+    ]
+    values = [max(0.0, min(1.0, value)) for value in values]
+    return values if values[2] > values[0] and values[3] > values[1] else None
+
+
+__all__ = [
+    "Affine",
+    "Point",
+    "Quad",
+    "bbox_area",
+    "bbox_center",
+    "bbox_intersection",
+    "bbox_overlap_ratio",
+    "bbox_to_points",
+    "bbox_union",
+    "canonical_angle",
+    "normalize_bbox",
+    "parse_affine",
+    "parse_numbers",
+    "parse_st_box",
+    "quad_bbox",
+    "rect_quad",
+    "transform_angle",
+    "transform_bbox",
+    "transform_quad",
+]

docvortex/analyzers/native/ofd/images.py

@@ -0,0 +1,124 @@
+"""OFD ImageObject 资源解码与安全图片投影。"""
+
+from __future__ import annotations
+
+import math
+from io import BytesIO
+
+from loguru import logger
+from PIL import Image, UnidentifiedImageError
+from lxml import etree  # type: ignore[reportMissingImports]
+
+from docvortex.foundation.image_encoding import image_to_b64str
+from ....schema import BBox
+from ....foundation.image_payload import validate_decoded_raster_size
+from .errors import OfdParseError
+from .geometry import Affine, bbox_intersection, canonical_angle, parse_affine, parse_st_box, transform_angle, transform_bbox
+from .models import ImageItem, ResourceRegistry
+from .package import OfdPackage, parse_int
+
+_JBIG2_SIGNATURE = b"\x97JB2\r\n\x1a\n"
+
+
+def _serialize_raster(data: bytes, *, alpha: int, angle: int) -> str | None:
+    """使用 Pillow 校验、旋转并编码常见位图。"""
+    try:
+        with Image.open(BytesIO(data)) as source:
+            validate_decoded_raster_size(*source.size)
+            source.load()
+            image = source.copy()
+    except (Image.DecompressionBombError, UnidentifiedImageError, OSError, SyntaxError, ValueError):
+        return None
+    if angle == 90:
+        image = image.transpose(Image.Transpose.ROTATE_270)
+    elif angle == 180:
+        image = image.transpose(Image.Transpose.ROTATE_180)
+    elif angle == 270:
+        image = image.transpose(Image.Transpose.ROTATE_90)
+    if alpha < 255:
+        rgba = image.convert("RGBA")
+        current_alpha = rgba.getchannel("A")
+        current_alpha = current_alpha.point(lambda value: round(value * alpha / 255))
+        rgba.putalpha(current_alpha)
+        image = rgba
+    if image.mode in {"RGBA", "LA"} or (image.mode == "P" and "transparency" in image.info):
+        return image_to_b64str(image.convert("RGBA"), image_format="PNG")
+    return image_to_b64str(image.convert("RGB"), image_format="JPEG")
+
+
+def build_image_item(
+    image_object: etree._Element,
+    *,
+    parent_transform: Affine,
+    parent_clip: BBox,
+    resources: ResourceRegistry,
+    package: OfdPackage,
+    paint_order: int,
+    layer_type: str,
+    template_id: int | None,
+    resolved_style: dict[str, str] | None = None,
+) -> ImageItem | None:
+    """解析一个 ImageObject，并保留不支持图片的占位几何。"""
+    style = resolved_style or {}
+    if (style.get("Visible") or image_object.get("Visible") or "true").casefold() in {"false", "0"}:
+        return None
+    boundary = parse_st_box(image_object.get("Boundary"))
+    if boundary is None:
+        return None
+    page_bbox = transform_bbox(boundary, parent_transform)
+    if page_bbox is None:
+        return None
+    page_bbox = bbox_intersection(page_bbox, parent_clip)
+    if page_bbox is None:
+        return None
+    raw_resource_id = image_object.get("ResourceID") or image_object.get("ResouceID")
+    resource_id = parse_int(raw_resource_id)
+    media = resources.media.get(resource_id) if resource_id is not None else None
+    object_id = parse_int(image_object.get("ID"))
+    if raw_resource_id is not None and media is None:
+        raise OfdParseError(
+            f"Malformed OFD package: ImageObject id={object_id} references missing media resource {raw_resource_id!r}"
+        )
+    if media is None:
+        return ImageItem(
+            bbox=page_bbox,
+            image_base64=None,
+            paint_order=paint_order,
+            object_id=object_id,
+            layer_type=layer_type,
+            template_id=template_id,
+            diagnostic="missing_media_resource",
+        )
+    data = package.read_part(media.media_part, required=True, asset=True)
+    assert data is not None
+    if data.startswith(_JBIG2_SIGNATURE):
+        diagnostic = "unsupported_jbig2"
+        payload = None
+    else:
+        try:
+            alpha = min(255, max(0, int(float(style.get("Alpha") or image_object.get("Alpha") or 255))))
+        except ValueError:
+            alpha = 255
+        ctm = parse_affine(image_object.get("CTM"))
+        raw_angle = transform_angle(parent_transform.compose(ctm))
+        angle = canonical_angle(raw_angle)
+        if angle not in {0, 90, 180, 270} or not math.isclose(math.remainder(raw_angle, 90.0), 0.0, abs_tol=5.0):
+            diagnostic = "unsupported_image_affine"
+            payload = None
+        else:
+            payload = _serialize_raster(data, alpha=alpha, angle=angle)
+            diagnostic = None if payload is not None else "unsupported_image_payload"
+    if diagnostic:
+        logger.warning(f"OFD_IMAGE_SKIPPED: code={diagnostic}, object_id={object_id}, part={media.media_part!r}")
+    return ImageItem(
+        bbox=page_bbox,
+        image_base64=payload,
+        paint_order=paint_order,
+        object_id=object_id,
+        layer_type=layer_type,
+        template_id=template_id,
+        diagnostic=diagnostic,
+    )
+
+
+__all__ = ["build_image_item"]

docvortex/analyzers/native/ofd/metadata.py

@@ -0,0 +1,53 @@
+"""从 OFD.xml 与 Document.xml 提取 Doclib 基础元数据。"""
+
+from __future__ import annotations
+
+from typing import BinaryIO
+
+from .constants import MAX_PAGE_COUNT, MAX_TOTAL_BYTES
+from .errors import OfdResourceLimitError
+from .package import OfdPackage, first_descendant, local_name
+
+
+def extract_ofd_metadata(file_binary: BinaryIO) -> dict[str, object | None]:
+    """返回全部 DocBody 的总页数和首个非空文档元数据。"""
+    file_bytes = file_binary.read(MAX_TOTAL_BYTES + 1)
+    if len(file_bytes) > MAX_TOTAL_BYTES:
+        raise OfdResourceLimitError(f"OFD resource limit exceeded: max_total_bytes={MAX_TOTAL_BYTES}")
+    with OfdPackage(file_bytes) as package:
+        refs = package.document_refs()
+        page_count = 0
+        metadata: dict[str, str | None] = {
+            "title": None,
+            "author": None,
+            "subject": None,
+            "keywords": None,
+        }
+        key_map = {
+            "Title": "title",
+            "Author": "author",
+            "Subject": "subject",
+            "Keywords": "keywords",
+        }
+        for ref in refs:
+            document_root = package.xml_part(ref.document_part, required=True)
+            assert document_root is not None
+            pages = first_descendant(document_root, "Pages")
+            if pages is not None:
+                for child in pages:
+                    if local_name(child.tag) != "Page":
+                        continue
+                    page_count += 1
+                    if page_count > MAX_PAGE_COUNT:
+                        raise OfdResourceLimitError(f"OFD resource limit exceeded: max_page_count={MAX_PAGE_COUNT}")
+            for source_key, target_key in key_map.items():
+                if metadata[target_key] is None and ref.metadata.get(source_key):
+                    metadata[target_key] = ref.metadata[source_key]
+        return {
+            "page_count": page_count,
+            **metadata,
+            "is_image_based": 0,
+        }
+
+
+__all__ = ["extract_ofd_metadata"]

docvortex/analyzers/native/ofd/models.py

@@ -0,0 +1,170 @@
+"""OFD 解析器内部使用的确定性数据模型。"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from lxml import etree  # type: ignore[reportMissingImports]
+
+from ....schema import BBox
+from .geometry import Affine, Point, Quad
+
+
+@dataclass(frozen=True, slots=True)
+class FontResource:
+    """保存字体资源及可选内嵌字体成员路径。"""
+
+    resource_id: int
+    font_name: str
+    family_name: str
+    font_part: str | None
+    bold: bool = False
+    italic: bool = False
+
+
+@dataclass(frozen=True, slots=True)
+class MediaResource:
+    """保存多媒体资源的成员路径与声明格式。"""
+
+    resource_id: int
+    media_type: str
+    media_format: str
+    media_part: str
+
+
+@dataclass(frozen=True, slots=True)
+class CompositeResource:
+    """保存可递归展开的复合图元资源。"""
+
+    resource_id: int
+    width: float
+    height: float
+    element: etree._Element
+
+
+@dataclass(slots=True)
+class ResourceRegistry:
+    """保存当前文档或页面作用域内的资源索引。"""
+
+    fonts: dict[int, FontResource] = field(default_factory=dict)
+    media: dict[int, MediaResource] = field(default_factory=dict)
+    composites: dict[int, CompositeResource] = field(default_factory=dict)
+    draw_params: dict[int, dict[str, str]] = field(default_factory=dict)
+
+
+@dataclass(frozen=True, slots=True)
+class GlyphItem:
+    """保存一个语义字符在页面空间中的几何。"""
+
+    text: str
+    bbox: BBox
+    quad: Quad
+    origin: Point
+    glyph_id: int | None = None
+
+
+@dataclass(slots=True)
+class TextLine:
+    """保存一个 TextCode 恢复出的可排序文字行。"""
+
+    text: str
+    bbox: BBox
+    glyphs: list[GlyphItem]
+    angle: int
+    font_size: float
+    paint_order: int
+    object_id: int | None
+    layer_type: str
+    template_id: int | None
+    styles: tuple[str, ...] = ()
+
+
+@dataclass(frozen=True, slots=True)
+class AxisLine:
+    """保存页面空间中的一条可见水平或垂直线。"""
+
+    bbox: BBox
+    orientation: str
+    width: float
+    paint_order: int
+    template_id: int | None
+
+
+@dataclass(frozen=True, slots=True)
+class ImageItem:
+    """保存页面图片载荷、几何和绘制来源。"""
+
+    bbox: BBox
+    image_base64: str | None
+    paint_order: int
+    object_id: int | None
+    layer_type: str
+    template_id: int | None
+    diagnostic: str | None = None
+
+
+@dataclass(slots=True)
+class OfdPageScene:
+    """保存一页 OFD 的原生场景和可投影对象。"""
+
+    page_idx: int
+    physical_box: BBox
+    content_box: BBox | None
+    text_lines: list[TextLine] = field(default_factory=list)
+    axis_lines: list[AxisLine] = field(default_factory=list)
+    images: list[ImageItem] = field(default_factory=list)
+    diagnostics: list[dict[str, Any]] = field(default_factory=list)
+
+
+@dataclass(frozen=True, slots=True)
+class OfdDocumentRef:
+    """保存 OFD.xml 中一个 DocBody 的入口和元数据。"""
+
+    document_part: str
+    signatures_part: str | None
+    metadata: dict[str, str]
+
+
+@dataclass(frozen=True, slots=True)
+class PageRef:
+    """保存 Document.xml 页树中的一个页面引用。"""
+
+    page_id: int | None
+    page_part: str
+
+
+@dataclass(frozen=True, slots=True)
+class TemplateRef:
+    """保存模板 ID 到模板页面成员的映射。"""
+
+    template_id: int
+    page_part: str
+
+
+@dataclass(frozen=True, slots=True)
+class PageBuildContext:
+    """保存递归图元构建所需的父级状态。"""
+
+    transform: Affine
+    clip_bbox: BBox
+    layer_type: str
+    template_id: int | None
+    draw_style: dict[str, str] = field(default_factory=dict)
+
+
+__all__ = [
+    "AxisLine",
+    "CompositeResource",
+    "FontResource",
+    "GlyphItem",
+    "ImageItem",
+    "MediaResource",
+    "OfdDocumentRef",
+    "OfdPageScene",
+    "PageBuildContext",
+    "PageRef",
+    "ResourceRegistry",
+    "TemplateRef",
+    "TextLine",
+]