WeKnora/docreader/parser/source_locator.py

294 lines
11 KiB
Python
Raw Blame History

This file contains ambiguous Unicode characters!

This file contains ambiguous Unicode characters that may be confused with others in your current locale. If your use case is intentional and legitimate, you can safely ignore this warning. Use the Escape button to highlight these characters.

"""Source locators: map ranges of parsed markdown back to the original file.
A source block is ``{"start": int, "end": int, "locator": {...}}`` where
``start``/``end`` are code point offsets into the document content (end
exclusive) and the locator says where that text sits in the original file.
For PDFs the locator is ``{"type": "pdf", "page": n}`` plus an optional
``"bbox": [x0, y0, x1, y1]`` given as fractions of the displayed page with
the origin at its top-left corner, so viewers can draw it at any zoom.
"""
from __future__ import annotations
import re
import statistics
import unicodedata
from typing import Iterable, List, Optional, Sequence, Tuple
# How far past the cursor a line is searched for, in normalized characters.
_SEARCH_WINDOW = 6000
# How much of a line's normalized text is searched for.
_KEY_CHARS = 24
# Lines shorter than this (normalized) are too ambiguous to place.
_MIN_KEY_CHARS = 2
# Lines shorter than this are placed only when their text is unique on the
# page: labels inside figures ("LLM", "EBAE") otherwise steal body offsets.
# Wide (CJK) characters count as four, since each carries about a word.
_SHORT_KEY_WEIGHT = 16
_LIST_START_RE = re.compile(
r"^\s*(?:"
r"\d{1,3}(?:\.\d{1,3}){0,4}[\.、.))]?\s" # 1 1. 8.14.11 2)
r"|[((]\d{1,3}[))]" # (1) (1)
r"|[一二三四五六七八九十百]+[、..]" # 一、
r"|[•·●○■□◆◇▪\-–*]\s" # bullets
r"|第[一二三四五六七八九十百零\d]+[章节条款部分篇]" # 第三章
r")"
)
_SENTENCE_END = tuple("。..!?!?::;;」』”))")
def _fold(ch: str) -> str:
"""Letters and digits only, lower-cased, full-width folded."""
if not ch.isalnum():
return ""
return unicodedata.normalize("NFKC", ch).lower()
def normalize_with_positions(text: str) -> Tuple[str, List[int]]:
"""Project text onto letters and digits.
Returns the projection and, for each of its characters, the offset in
``text`` of the character it came from.
"""
out: List[str] = []
pos: List[int] = []
for i, ch in enumerate(text):
folded = _fold(ch)
for f in folded:
out.append(f)
pos.append(i)
return "".join(out), pos
def normalize(text: str) -> str:
return "".join(_fold(ch) for ch in text)
def _key_weight(key: str) -> int:
return sum(4 if unicodedata.east_asian_width(ch) in ("W", "F") else 1 for ch in key)
def _column_cursor(boxes, idx: int, ends: List[Optional[int]]) -> Optional[int]:
"""End of the nearest placed line above ``boxes[idx]`` in the same column."""
x0, y0, x1, _ = boxes[idx]
for j in range(idx - 1, max(-1, idx - 80), -1):
if ends[j] is None:
continue
px0, py0, px1, _ = boxes[j]
if px0 < x1 and x0 < px1 and py0 > y0:
return ends[j]
return None
def locate_lines(
page_text: str,
line_texts: Sequence[str],
boxes: Optional[Sequence[Tuple[float, float, float, float]]] = None,
) -> List[Optional[int]]:
"""Find where each visual line starts in the page text.
Lines are searched in order after the previous hit so repeated phrases
resolve to the right occurrence. With ``boxes`` (PDF points, bottom-left
origin) the search first continues from the line above in the same
column, since glyph lines of side-by-side columns arrive interleaved. A
line not found after either cursor is searched from the start of the page,
which tolerates text extractors that order columns differently from the
glyph grouping. Returns one offset (or None) per line.
"""
norm, pos = normalize_with_positions(page_text)
hits: List[Optional[int]] = []
ends: List[Optional[int]] = []
cursor = 0
for idx, line in enumerate(line_texts):
key = normalize(line)[:_KEY_CHARS]
if len(key) < _MIN_KEY_CHARS or (
_key_weight(key) < _SHORT_KEY_WEIGHT and norm.count(key) > 1
):
hits.append(None)
ends.append(None)
continue
cursors = [cursor]
if boxes is not None:
column = _column_cursor(boxes, idx, ends)
if column is not None:
cursors.insert(0, column)
at = -1
for start_at in cursors:
at = norm.find(key, start_at, start_at + _SEARCH_WINDOW + len(key))
if at >= 0:
break
if at < 0:
at = norm.find(key)
if at < 0:
hits.append(None)
ends.append(None)
continue
else:
cursor = at + len(key)
ends.append(at + len(key))
start = pos[at]
# Pull in leading punctuation or markup on the same text line
# (brackets, "## ", list bullets) that normalization skipped.
while start > 0 and page_text[start - 1] != "\n" and not page_text[start - 1].isalnum():
start -= 1
hits.append(start)
return hits
class PageGeometry:
"""Converts PDF user-space points to fractions of the displayed page."""
def __init__(self, cropbox: Tuple[float, float, float, float], rotation: int = 0):
left, bottom, right, top = cropbox
self.left, self.bottom = min(left, right), min(bottom, top)
self.width = abs(right - left) or 1.0
self.height = abs(top - bottom) or 1.0
self.rotation = int(rotation or 0) % 360
def bbox(self, box: Tuple[float, float, float, float]) -> List[float]:
x0, y0, x1, y1 = box
# Unrotated, top-left origin.
ux0 = (x0 - self.left) / self.width
ux1 = (x1 - self.left) / self.width
uy0 = 1.0 - (y1 - self.bottom) / self.height
uy1 = 1.0 - (y0 - self.bottom) / self.height
corners = [self._rotate(ux0, uy0), self._rotate(ux1, uy1)]
xs = [c[0] for c in corners]
ys = [c[1] for c in corners]
return [
round(_clamp(min(xs)), 4),
round(_clamp(min(ys)), 4),
round(_clamp(max(xs)), 4),
round(_clamp(max(ys)), 4),
]
def _rotate(self, x: float, y: float) -> Tuple[float, float]:
# Viewers display /Rotate clockwise.
if self.rotation == 90:
return 1.0 - y, x
if self.rotation == 180:
return 1.0 - x, 1.0 - y
if self.rotation == 270:
return y, 1.0 - x
return x, y
def _clamp(v: float) -> float:
return 0.0 if v < 0 else 1.0 if v > 1 else v
def _union(boxes: Iterable[Tuple[float, float, float, float]]):
boxes = list(boxes)
return (
min(b[0] for b in boxes),
min(b[1] for b in boxes),
max(b[2] for b in boxes),
max(b[3] for b in boxes),
)
def _line_gap(prev: dict, cur: dict) -> Optional[float]:
"""Vertical gap from ``prev`` down to ``cur`` when they share a column."""
px0, py0, px1, _ = prev["bbox"]
cx0, _, cx1, cy1 = cur["bbox"]
if cx1 < px0 or cx0 > px1 or cy1 > py0:
return None
return py0 - cy1
def _starts_paragraph(
prev: dict, cur: dict, line_h: float, usual_gap: float, col_right: float
) -> bool:
"""Whether ``cur`` opens a new visual paragraph after ``prev``.
Boxes are PDF points with a bottom-left origin, so reading downwards means
decreasing y. ``usual_gap`` is the page's typical gap between consecutive
lines of a paragraph, which absorbs double-spaced layouts.
"""
px0, py0, px1, _ = prev["bbox"]
cx0, _, cx1, cy1 = cur["bbox"]
if cx1 < px0 or cx0 > px1:
return True # moved to another column
if cy1 > py0 + line_h * 0.5:
return True # went back up the page: a new column or region
if py0 - cy1 > usual_gap * 1.5 + line_h * 0.3:
return True # vertical gap wider than the usual line spacing
if _LIST_START_RE.match(cur["text"]):
return True
ends_sentence = prev["text"].rstrip().endswith(_SENTENCE_END)
short = col_right - px1 > line_h * 2
return ends_sentence and short
def page_blocks(
page_text: str,
offset: int,
page_number: int,
lines: Sequence[dict],
geometry: Optional[PageGeometry],
) -> List[dict]:
"""Source blocks for one text page placed at ``offset`` in the document.
``lines`` are visual lines ``{"text", "bbox"}`` (bbox in PDF points). Lines
are placed in ``page_text``, grouped into paragraphs by geometry, and each
paragraph becomes a block spanning from its first line to the next
paragraph, boxed by the union of its lines. Text before the first placed
line, or a page with no placeable lines, gets a page-only block, so the
blocks always tile the page's text.
"""
end = offset + len(page_text)
page_only = {"type": "pdf", "page": page_number}
if not page_text:
return []
placed = []
if lines and geometry is not None:
starts = locate_lines(
page_text, [ln["text"] for ln in lines], [ln["bbox"] for ln in lines]
)
placed = sorted(
(
(at, ln)
for at, ln in zip(starts, lines)
if at is not None
),
key=lambda item: item[0],
)
if not placed:
return [{"start": offset, "end": end, "locator": dict(page_only)}]
heights = [ln["bbox"][3] - ln["bbox"][1] for _, ln in placed if ln["bbox"][3] > ln["bbox"][1]]
line_h = statistics.median(heights) if heights else 10.0
gaps = [
g
for g in (_line_gap(a[1], b[1]) for a, b in zip(placed, placed[1:]))
if g is not None and g >= 0
]
usual_gap = statistics.median(gaps) if gaps else line_h * 0.5
paragraphs: List[Tuple[int, List[dict]]] = []
for at, ln in placed:
if paragraphs:
prev = paragraphs[-1][1][-1]
col_right = max(p["bbox"][2] for p in paragraphs[-1][1])
col_right = max(col_right, ln["bbox"][2])
if not _starts_paragraph(prev, ln, line_h, usual_gap, col_right):
paragraphs[-1][1].append(ln)
continue
paragraphs.append((at, [ln]))
blocks: List[dict] = []
first_at = paragraphs[0][0]
if first_at > 0 and page_text[:first_at].strip():
blocks.append({"start": offset, "end": offset + first_at, "locator": dict(page_only)})
for i, (at, members) in enumerate(paragraphs):
stop = paragraphs[i + 1][0] if i + 1 < len(paragraphs) else len(page_text)
if i == 0:
at = 0 if not blocks else at
if stop <= at:
continue
locator = dict(page_only)
locator["bbox"] = geometry.bbox(_union(m["bbox"] for m in members))
blocks.append({"start": offset + at, "end": offset + stop, "locator": locator})
return blocks