docvortex 0.2.1__tar.gz → 0.2.2__tar.gz

{docvortex-0.2.1/src/docvortex.egg-info → docvortex-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docvortex
-Version: 0.2.1
+Version: 0.2.2
 Summary: A fast, multi-format document parsing and conversion engine
 License-Expression: MIT
 Project-URL: Repository, https://github.com/myhloli/DocVortex

{docvortex-0.2.1 → docvortex-0.2.2}/docs/COMPATIBILITY.md

@@ -42,7 +42,7 @@ Saved results and Doclib caches are not rewritten automatically. After upgrading
 restart running services and use the existing `mineru parse ... --force` option
 to regenerate results with the current font and text policies.
 
-MinerU declares `docvortex>=0.2.1,<0.3.0`. DocVortex declares
+MinerU declares `docvortex>=0.2.2,<1.0.0` to use the shared PDF layout renderer. DocVortex declares
 `pypdfium2>=5.10.1,<6`; this constraint also applies when MinerU installs its own
 direct PDFium dependency. Other shared dependency floors remain aligned, including
 `pydantic>=2.12.5,<3` and `numpy>=1.21.6`.

{docvortex-0.2.1 → docvortex-0.2.2}/docs/DOCVORTEX_UPGRADE.md

@@ -5,6 +5,56 @@ DocGale. The GitHub repository is `myhloli/DocVortex`; the Python distribution,
 import and command are all `docvortex`. The existing repository history and release
 draft are retained. Version 0.1.0 remains a draft, not a PyPI publication.
 
+## Shared PDF layout visualization in 0.2.2
+
+`docvortex.visualization.render_layout_pdf(pdf_bytes, pages, *, page_indices=None)`
+returns PDF bytes with colored layout outlines and `block_type: index` labels. Pass current `MiddleJson.pages`;
+the renderer uses normalized `blocks/content` geometry without changing the input
+document. It preserves page dimensions, CropBox offsets and right-angle rotations.
+This overlays the source PDF; it does not reflow semantic content like `render_pdf`.
+
+```python
+from pathlib import Path
+import docvortex
+from docvortex.visualization import render_layout_pdf
+
+source = Path("report.pdf")
+result = docvortex.parse(source)
+Path("layout.pdf").write_bytes(render_layout_pdf(source.read_bytes(), result.middle_json.pages))
+```
+
+For a cropped or reordered PDF, `page_indices[i]` must name the original zero-based
+page index of its i-th page. Omit the mapping only for an original full PDF. A
+mapping with the wrong length raises `ValueError`; missing result pages remain
+unmarked rather than borrowing another page's boxes. For example, a PDF containing
+only original pages 2 and 5 requires `page_indices=(1, 4)`.
+
+Page footnotes use teal (`#008080`); headers, footers, page numbers and aside text
+use gray (`#9E9E9E`). Other block colors retain the current palette. All layout
+rectangles use 1 pt outlines without interior fill. Each outlined block has a
+matching 7 pt Helvetica label on a small white background above its top-left corner.
+Labels show the block's own zero-based `index`, including gaps and duplicate
+parent/child values; a missing child index is shown as `-`. Visual parent containers
+are not outlined or labeled separately. Code and algorithm parents still share
+`type="code"`, distinguished by `sub_type`; algorithm children retain
+`algorithm_body` and the same purple as `code_body`.
+
+Labels stay upright after page rotation, shift left at the right edge and move
+inside the box when there is no room above it. Overlapping labels move up by rows
+first, then down from the box top; if no non-overlapping row remains on the page,
+the renderer chooses the row with the least label overlap. Labels add extractable
+text to the output PDF; the input PDF and Middle JSON are not modified.
+Label avoidance checks other labels, not source text. Where adjacent blocks have
+little vertical spacing, a label's white background can cover nearby source text
+visually; that text remains in the PDF content stream.
+
+MinerU's Gradio preview delegates to this renderer and retains its artifact names.
+`PDFDocument.draw_layout_bbox(pages, output_path,
+page_indices=None)` remains a file-writing wrapper (the mapping is keyword-only),
+now using current `PageInfo` rather than removed legacy layout fields. Legacy
+filled boxes and separately renumbered red reading-order markers are not retained. Private helpers from
+`docvortex.document.pdf.diagnostics` have been removed.
+
 ## On-demand PDF crops in 0.2.1
 
 `docvortex.document.pdf.visuals.attach_visual_block_images_from_pdf(document,
@@ -59,7 +109,7 @@ Markdown embedded HTML share the new namespace. PDF, DOCX and LaTeX generated
 titles, metadata, styles and macros use DocVortex. Supported explicit user titles
 and authors retain their existing precedence.
 
-MinerU requires `docvortex>=0.2.1,<0.3.0`. Both projects share the new envelope,
+MinerU requires `docvortex>=0.2.2,<1.0.0`. Both projects share the new envelope,
 with `metadata.file_suffix`, `metadata.producer`, and optional `extensions.mineru`
 containing actual tier and resolved parse mode. Old JSON adapters and historical
 page conversion are removed. Python top-level metadata attributes have no aliases.

{docvortex-0.2.1 → docvortex-0.2.2}/src/docvortex/document/pdf/document.py

@@ -1,10 +1,11 @@
 from __future__ import annotations
 
 import logging
-import os
 import time
+from collections.abc import Sequence
 from contextlib import contextmanager
 from io import BytesIO
+from pathlib import Path
 from typing import Iterator, Literal, cast
 
 import pypdfium2 as pdfium
@@ -544,12 +545,14 @@ class PDFDocument:
     #  Visualization
     # ------------------------------------------------------------------ #
 
-    def draw_layout_bbox(self, pages: list[PageInfo], output_path: str) -> None:
-        from .diagnostics import draw_layout_bbox
+    def draw_layout_bbox(self, pages: list[PageInfo], output_path: str, *, page_indices: Sequence[int] | None = None) -> None:
+        """写出带类型与原始编号标签的布局预览；抽页后的文档需传入原始页号映射。"""
+        from ...visualization import render_layout_pdf
 
-        out_dir = os.path.dirname(output_path) or "."
-        filename = os.path.basename(output_path)
-        draw_layout_bbox(pages, self._pdf_bytes, out_dir, filename)
+        pdf_bytes = render_layout_pdf(self._pdf_bytes, pages, page_indices=page_indices)
+        output = Path(output_path)
+        output.parent.mkdir(parents=True, exist_ok=True)
+        output.write_bytes(pdf_bytes)
 
     # ------------------------------------------------------------------ #
     #  Internal

{docvortex-0.2.1 → docvortex-0.2.2}/src/docvortex/version.py

@@ -1,3 +1,3 @@
-__version__ = "0.2.1"
+__version__ = "0.2.2"
 
 __all__ = ["__version__"]

docvortex-0.2.2/src/docvortex/visualization.py

@@ -0,0 +1,222 @@
+"""在原始 PDF 上标注严格 Middle JSON 的布局，共享实现不负责文件读写。"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Sequence
+from io import BytesIO
+
+from pypdf import PageObject, PdfReader, PdfWriter
+from pypdf.generic import RectangleObject
+from reportlab.pdfbase import pdfmetrics
+from reportlab.pdfgen import canvas
+
+from .schema import PAGE_AUXILIARY_BLOCK_TYPES, BBox, BlockBase, BlockType, PageInfo
+
+_VISUAL_PARENT_TYPES = {BlockType.IMAGE, BlockType.TABLE, BlockType.CHART, BlockType.CODE}
+
+# 当前布局使用实色边框和同色类型标签；页面脚注独立着色，页面辅助块统一为灰色。
+_BLOCK_COLORS: dict[str, tuple[float, float, float]] = {
+    "text": (0.60, 0.05, 0.30),
+    "ref_text": (0.45, 0.20, 0.65),
+    "doc_title": (0.20, 0.20, 0.80),
+    "paragraph_title": (0.20, 0.40, 0.90),
+    "equation": (0.00, 0.60, 0.10),
+    "list": (0.10, 0.60, 0.35),
+    "index": (0.10, 0.60, 0.35),
+    "image_body": (0.30, 0.85, 0.05),
+    "image_caption": (0.10, 0.55, 0.90),
+    "image_footnote": (0.95, 0.45, 0.10),
+    "table_body": (0.80, 0.80, 0.00),
+    "table_caption": (1.00, 0.85, 0.10),
+    "table_footnote": (0.55, 0.90, 0.25),
+    "chart_body": (0.30, 0.85, 0.05),
+    "chart_caption": (0.10, 0.55, 0.90),
+    "chart_footnote": (0.95, 0.45, 0.10),
+    "code_body": (0.40, 0.00, 0.80),
+    "algorithm_body": (0.40, 0.00, 0.80),
+    "code_caption": (0.70, 0.35, 0.95),
+    "code_footnote": (0.85, 0.70, 0.95),
+    "page_footnote": (0, 128 / 255, 128 / 255),
+    **{str(kind): (158 / 255, 158 / 255, 158 / 255) for kind in PAGE_AUXILIARY_BLOCK_TYPES},
+}
+
+_LABEL_FONT = "Helvetica"
+_LABEL_FONT_SIZE = 7
+_LABEL_PADDING = 1.0
+_LABEL_GAP = 1.0
+
+
+def render_layout_pdf(
+    pdf_bytes: bytes,
+    pages: Sequence[PageInfo],
+    *,
+    page_indices: Sequence[int] | None = None,
+) -> bytes:
+    """把当前 PageInfo 布局画到 PDF，返回新字节且不修改解析结果。
+
+    bbox 使用页面显示方向下、以 CropBox 左上角为原点的归一化坐标。
+    page_indices 的第 i 项是输入 PDF 第 i 页对应的原始 page_idx；
+    完整原文可省略映射，抽页或重排后的 PDF 必须显式提供映射。
+    没有对应解析结果的页面原样保留，映射长度错误时抛出 ValueError。
+    每个边框标注自身类型和原始 index，缺失 index 显示 -；标签文字可被 PDF 提取。
+    """
+    if any(not isinstance(page, PageInfo) for page in pages):
+        raise TypeError("pages must contain PageInfo instances")
+    pages_by_index = {page.page_idx: page for page in pages}
+    if len(pages_by_index) != len(pages):
+        raise ValueError("pages must have unique page_idx values")
+
+    reader = PdfReader(BytesIO(pdf_bytes))
+    indices = tuple(range(len(reader.pages))) if page_indices is None else tuple(page_indices)
+    if len(indices) != len(reader.pages):
+        raise ValueError("page_indices length must match the PDF page count")
+    if any(isinstance(index, bool) or not isinstance(index, int) or index < 0 for index in indices):
+        raise ValueError("page_indices must contain non-negative integers")
+
+    writer = PdfWriter()
+    for source_page, original_index in zip(reader.pages, indices):
+        # 直接复制原页可保留 MediaBox、CropBox、Rotate 和原有批注。
+        page_copy = writer.add_page(source_page)
+        middle_page = pages_by_index.get(original_index)
+        if middle_page is not None:
+            overlay = _build_page_overlay(source_page, middle_page)
+            if overlay is not None:
+                page_copy.merge_page(overlay)
+
+    output = BytesIO()
+    writer.write(output)
+    return output.getvalue()
+
+
+def _build_page_overlay(page: PageObject, middle_page: PageInfo) -> PageObject | None:
+    """先绘制边框，再按显示方向放置标签，保留原页方向和页面框。"""
+    if page.cropbox.width <= 0 or page.cropbox.height <= 0:
+        return None
+    boxes = list(_iter_overlay_boxes(middle_page.blocks))
+    if not boxes:
+        return None
+
+    packet = BytesIO()
+    painter = canvas.Canvas(packet, pagesize=(float(page.mediabox.width), float(page.mediabox.height)))
+    painter.setLineWidth(1.0)
+    for block_type, bbox, _ in boxes:
+        x0, y0, x1, y1 = _normalized_bbox_to_pdf(bbox, page)
+        painter.setStrokeColorRGB(*_BLOCK_COLORS.get(block_type, (0.90, 0.10, 0.10)))
+        painter.rect(x0, y0, max(0.5, x1 - x0), max(0.5, y1 - y0), stroke=1, fill=0)
+    _draw_overlay_labels(painter, page, boxes)
+    painter.save()
+    packet.seek(0)
+    overlay = PdfReader(packet).pages[0]
+    # merge_page 按 overlay 的 CropBox 裁剪，必须同步原页偏移，支持负坐标。
+    overlay.mediabox = RectangleObject(page.mediabox)
+    overlay.cropbox = RectangleObject(page.cropbox)
+    return overlay
+
+
+def _iter_overlay_boxes(blocks: Iterable[BlockBase]) -> Iterable[tuple[str, BBox, int | None]]:
+    """遍历当前 block 树并保留自身 index；视觉父块只画子块，列表保留层级框。"""
+    for block in blocks:
+        if block.bbox is not None and block.type not in _VISUAL_PARENT_TYPES:
+            yield str(block.type), block.bbox, block.index
+        content = getattr(block, "content", None)
+        children = [child for child in content if isinstance(child, BlockBase)] if isinstance(content, list) else []
+        if block.type in _VISUAL_PARENT_TYPES:
+            for child in children:
+                if child.bbox is not None:
+                    yield str(child.type), child.bbox, child.index
+        elif children:
+            yield from _iter_overlay_boxes(children)
+
+
+def _draw_overlay_labels(painter: canvas.Canvas, page: PageObject, boxes: Sequence[tuple[str, BBox, int | None]]) -> None:
+    """在显示方向的左下原点坐标系中绘制正向标签，并用白底保护文字可读性。"""
+    left, bottom = float(page.cropbox.left), float(page.cropbox.bottom)
+    width, height = float(page.cropbox.width), float(page.cropbox.height)
+    rotation = page.rotation % 360
+    transforms = {
+        0: (1, 0, 0, 1, left, bottom),
+        90: (0, 1, -1, 0, left + width, bottom),
+        180: (-1, 0, 0, -1, left + width, bottom + height),
+        270: (0, -1, 1, 0, left, bottom + height),
+    }
+    painter.saveState()
+    painter.transform(*transforms[rotation])
+    if rotation in (90, 270):
+        width, height = height, width
+    ascent, descent = pdfmetrics.getAscentDescent(_LABEL_FONT, _LABEL_FONT_SIZE)
+    label_height = ascent - descent + 2 * _LABEL_PADDING
+    occupied: list[BBox] = []
+    for block_type, bbox, index in boxes:
+        label = f"{block_type}: {index if index is not None else '-'}"
+        text_width = pdfmetrics.stringWidth(label, _LABEL_FONT, _LABEL_FONT_SIZE)
+        label_width = min(text_width + 2 * _LABEL_PADDING, width)
+        rect = _place_label(bbox[0] * width, (1 - bbox[1]) * height, label_width, label_height, width, height, occupied)
+        occupied.append(rect)
+        x0, y0, x1, y1 = rect
+        painter.setFillColorRGB(1, 1, 1)
+        painter.rect(x0, y0, x1 - x0, y1 - y0, stroke=0, fill=1)
+        painter.setFillColorRGB(*_BLOCK_COLORS.get(block_type, (0.90, 0.10, 0.10)))
+        text = painter.beginText(x0 + _LABEL_PADDING, y0 + _LABEL_PADDING - descent)
+        text.setFont(_LABEL_FONT, _LABEL_FONT_SIZE)
+        # 极窄页面仅压缩标签的水平宽度，不让右侧文字越过 CropBox。
+        text.setHorizScale(100 * min(1, max(0, label_width - 2 * _LABEL_PADDING) / text_width))
+        text.textOut(label)
+        painter.drawText(text)
+    painter.restoreState()
+
+
+def _place_label(
+    left: float,
+    top: float,
+    width: float,
+    height: float,
+    page_width: float,
+    page_height: float,
+    occupied: Sequence[BBox],
+) -> BBox:
+    """优先在框上方逐行避让，页顶受限时向框内下移；满页时选遮叠面积最小的位置。"""
+    left = max(0, min(left, page_width - width))
+    step = height + _LABEL_GAP
+    candidates: list[BBox] = []
+    y = top + _LABEL_GAP
+    while y + height <= page_height:
+        candidates.append((left, y, left + width, y + height))
+        y += step
+    y = min(top - _LABEL_GAP - height, page_height - height)
+    while y >= 0:
+        candidates.append((left, y, left + width, y + height))
+        y -= step
+    if not candidates:
+        candidates.append((left, 0, left + width, min(height, page_height)))
+    best = candidates[0]
+    best_overlap = float("inf")
+    for candidate in candidates:
+        x0, y0, x1, y1 = candidate
+        overlap = sum(
+            max(0, min(x1, other[2]) - max(x0, other[0])) * max(0, min(y1, other[3]) - max(y0, other[1])) for other in occupied
+        )
+        if overlap == 0:
+            return candidate
+        if overlap < best_overlap:
+            best, best_overlap = candidate, overlap
+    return best
+
+
+def _normalized_bbox_to_pdf(bbox: BBox, page: PageObject) -> BBox:
+    """反转显示方向的直角旋转，并把 CropBox 内的归一化框还原为 PDF 坐标。"""
+    left, bottom = float(page.cropbox.left), float(page.cropbox.bottom)
+    width, height = float(page.cropbox.width), float(page.cropbox.height)
+    x0, y0, x1, y1 = bbox
+    rotation = page.rotation % 360
+    if rotation == 90:
+        return left + y0 * width, bottom + x0 * height, left + y1 * width, bottom + x1 * height
+    if rotation == 180:
+        return left + (1 - x1) * width, bottom + y0 * height, left + (1 - x0) * width, bottom + y1 * height
+    if rotation == 270:
+        return left + (1 - y1) * width, bottom + (1 - x1) * height, left + (1 - y0) * width, bottom + (1 - x0) * height
+    if rotation != 0:
+        raise ValueError("PDF page rotation must be a multiple of 90 degrees")
+    return left + x0 * width, bottom + (1 - y1) * height, left + x1 * width, bottom + (1 - y0) * height
+
+
+__all__ = ["render_layout_pdf"]

{docvortex-0.2.1 → docvortex-0.2.2/src/docvortex.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docvortex
-Version: 0.2.1
+Version: 0.2.2
 Summary: A fast, multi-format document parsing and conversion engine
 License-Expression: MIT
 Project-URL: Repository, https://github.com/myhloli/DocVortex

{docvortex-0.2.1 → docvortex-0.2.2}/src/docvortex.egg-info/SOURCES.txt

@@ -67,6 +67,7 @@ src/docvortex/options.py
 src/docvortex/result.py
 src/docvortex/schema.py
 src/docvortex/version.py
+src/docvortex/visualization.py
 src/docvortex.egg-info/PKG-INFO
 src/docvortex.egg-info/SOURCES.txt
 src/docvortex.egg-info/dependency_links.txt
@@ -318,7 +319,6 @@ src/docvortex/document/source.py
 src/docvortex/document/pdf/__init__.py
 src/docvortex/document/pdf/classify.py
 src/docvortex/document/pdf/constants.py
-src/docvortex/document/pdf/diagnostics.py
 src/docvortex/document/pdf/document.py
 src/docvortex/document/pdf/font_runtime.py
 src/docvortex/document/pdf/geometry.py
@@ -555,6 +555,7 @@ tests/unittest/test_pdf_document.py
 tests/unittest/test_pdf_render.py
 tests/unittest/test_pdf_render_diagnostics.py
 tests/unittest/test_pdf_text_styles.py
+tests/unittest/test_pdf_visualization.py
 tests/unittest/test_postprocess_page_blocks.py
 tests/unittest/test_postprocess_pages.py
 tests/unittest/test_postprocess_paragraphs.py