Skip to content

Transforms complex documents like PDFs and Office docs into LLM-ready markdown/JSON for your Agentic workflows.

refactor(ocr): unify degenerate crop handling and reduce copies

myhloli99e66dff364b
diff --git a/mineru/model/ocr/image.py b/mineru/model/ocr/image.py
index 0f3e64e5..cc82f517 100644
--- a/mineru/model/ocr/image.py
+++ b/mineru/model/ocr/image.py
@@ -82,9 +82,14 @@ def mask_formula_regions_for_ocr_det(
return masked_image
-def get_rotate_crop_image(img: np.ndarray, points: np.ndarray) -> np.ndarray:
- """按四边形透视裁剪文本区域,并自动转正高纵横比结果。"""
+def get_rotate_crop_image(img: np.ndarray, points: np.ndarray) -> np.ndarray | None:
+ """裁剪四边形,退化框返回 None,透视裁图保留既有的高纵横比转正规则。"""
assert len(points) == 4, "shape of points must be 4*2"
+ img_crop_width = int(max(np.linalg.norm(points[0] - points[1]), np.linalg.norm(points[2] - points[3])))
+ img_crop_height = int(max(np.linalg.norm(points[0] - points[3]), np.linalg.norm(points[1] - points[2])))
+ # 在轴对齐快捷路径之前过滤,避免跨整数边界的亚像素框被切成一列或一行像素。
+ if img_crop_width < 1 or img_crop_height < 1:
+ return None
if is_bbox_aligned_rect(points):
xmin = int(np.min(points[:, 0]))
xmax = int(np.max(points[:, 0]))
@@ -94,8 +99,6 @@ def get_rotate_crop_image(img: np.ndarray, points: np.ndarray) -> np.ndarray:
if new_img.shape[0] > 0 and new_img.shape[1] > 0:
return new_img
- img_crop_width = int(max(np.linalg.norm(points[0] - points[1]), np.linalg.norm(points[2] - points[3])))
- img_crop_height = int(max(np.linalg.norm(points[0] - points[3]), np.linalg.norm(points[1] - points[2])))
pts_std = np.float32([[0, 0], [img_crop_width, 0], [img_crop_width, img_crop_height], [0, img_crop_height]])
# 四边形裁图调用共享数值内核,轴对齐区域继续直接复制。
@@ -144,12 +147,7 @@ def resize_text_recognition_image(
def get_rotate_crop_image_for_text_rec(img: np.ndarray, points: np.ndarray) -> np.ndarray | None:
- """裁剪四边形文本区域并应用文字识别方向规则。"""
- # 对边长度截断不足一个像素的退化框没有可识别裁图,避免送入共享 warp 的零尺寸目标。
- crop_width = max(np.linalg.norm(points[0] - points[1]), np.linalg.norm(points[2] - points[3]))
- crop_height = max(np.linalg.norm(points[0] - points[3]), np.linalg.norm(points[1] - points[2]))
- if crop_width < 1 or crop_height < 1:
- return None
+ """复用基础裁图的退化检查,并对有效裁片应用文字识别方向规则。"""
return rotate_vertical_crop_if_needed(get_rotate_crop_image(img, points))
diff --git a/mineru/model/ocr/results.py b/mineru/model/ocr/results.py
index fc4045d7..669b30e0 100644
--- a/mineru/model/ocr/results.py
+++ b/mineru/model/ocr/results.py
@@ -3,7 +3,6 @@
from __future__ import annotations
-import copy
from typing import Any
import numpy as np
@@ -48,7 +47,6 @@ def get_ocr_result_list(
"""过滤 OCR 输出并将坐标回投到原始页面。"""
paste_x, paste_y, xmin, ymin, _xmax, _ymax, _new_width, _new_height = useful_list
ocr_result_list = []
- ori_im = None
for box_ocr_res in ocr_res:
img_crop = None
need_ocr_rec = False
@@ -60,21 +58,17 @@ def get_ocr_result_list(
else:
p1, p2, p3, p4 = box_ocr_res
text, score = "", 1
- # 公式遮罩拆框可能产生零宽或窄残片;沿用既有过滤条件,先过滤再裁图。
- if (p3[0] - p1[0]) < OcrConfidence.min_width:
- continue
- if ocr_enable:
- if ori_im is None:
- ori_im = bgr_image.copy()
- tmp_box = copy.deepcopy(np.array([p1, p2, p3, p4]).astype("float32"))
- img_crop = get_rotate_crop_image_for_text_rec(ori_im, tmp_box)
- if img_crop is None:
- continue
- need_ocr_rec = True
+ need_ocr_rec = ocr_enable
poly = [p1, p2, p3, p4]
+ # 公式遮罩拆框可能产生零宽或窄残片;两类结果共用过滤条件,先过滤再裁图。
if (p3[0] - p1[0]) < OcrConfidence.min_width:
continue
+ if need_ocr_rec:
+ # 裁图只读源图且返回独立裁片,无需复制整个输入图或重复复制坐标数组。
+ img_crop = get_rotate_crop_image_for_text_rec(bgr_image, np.array(poly, dtype=np.float32))
+ if img_crop is None:
+ continue
if calculate_is_angle(poly):
x_center = sum(point[0] for point in poly) / 4
y_center = sum(point[1] for point in poly) / 4
diff --git a/tests/unittest/test_ocr_text_crop_degenerate.py b/tests/unittest/test_ocr_text_crop_degenerate.py
index 90537f6e..74974a65 100644
--- a/tests/unittest/test_ocr_text_crop_degenerate.py
+++ b/tests/unittest/test_ocr_text_crop_degenerate.py
@@ -2,29 +2,112 @@
from __future__ import annotations
+from typing import Any
from unittest.mock import Mock
import numpy as np
import pytest
+from mineru.model.ocr import image as ocr_image
from mineru.model.ocr.geometry import update_det_boxes
-from mineru.model.ocr.image import get_rotate_crop_image_for_text_rec
+from mineru.model.ocr.image import get_rotate_crop_image, get_rotate_crop_image_for_text_rec
from mineru.model.ocr.results import get_ocr_result_list
@pytest.mark.parametrize(
"points",
(
- [[4, 4], [4, 4], [4, 12], [4, 12]],
- [[4, 4], [16, 4], [16, 4], [4, 4]],
- [[4, 4], [16, 6], [16, 6.5], [4, 4.5]],
+ pytest.param([[4, 4], [4, 4], [4, 12], [4, 12]], id="zero-width"),
+ pytest.param([[4, 4], [16, 4], [16, 4], [4, 4]], id="zero-height"),
+ pytest.param([[4, 4], [16, 6], [16, 6.5], [4, 4.5]], id="inclined-subpixel-height"),
+ pytest.param([[4, 4], [4.4, 4], [4.4, 12], [4, 12]], id="subpixel-width"),
+ pytest.param([[4, 4], [16, 4], [16, 4.4], [4, 4.4]], id="subpixel-height"),
+ pytest.param([[4.8, 4], [5.2, 4], [5.2, 12], [4.8, 12]], id="subpixel-width-crosses-integer"),
+ pytest.param([[4, 4.8], [16, 4.8], [16, 5.2], [4, 5.2]], id="subpixel-height-crosses-integer"),
),
)
-def test_zero_pixel_text_crop_is_discarded(points: list[list[float]]) -> None:
- """零宽、零高及倾斜亚像素高度不能进入透视采样或后续 OCR rec。"""
+def test_zero_pixel_text_crop_is_discarded(points: list[list[float]], monkeypatch: pytest.MonkeyPatch) -> None:
+ """两个裁图入口均拒绝退化框,跨整数边界也不能绕过检查进入采样或 OCR。"""
image = np.zeros((24, 24, 3), dtype=np.uint8)
- assert get_rotate_crop_image_for_text_rec(image, np.asarray(points, dtype=np.float32)) is None
+ matrix = Mock(side_effect=AssertionError("invalid crop must not create a perspective matrix"))
+ warp = Mock(side_effect=AssertionError("invalid crop must not reach warp_image"))
+ monkeypatch.setattr(ocr_image, "perspective_matrix", matrix)
+ monkeypatch.setattr(ocr_image, "warp_image", warp)
+ quad = np.asarray(points, dtype=np.float32)
+ assert get_rotate_crop_image(image, quad) is None
+ assert get_rotate_crop_image_for_text_rec(image, quad) is None
assert get_ocr_result_list([points], [0, 0, 0, 0, 24, 24, 24, 24], True, image) == []
+ matrix.assert_not_called()
+ warp.assert_not_called()
+
+
+ ("bbox", "rotate_for_rec"),
+ (
+ pytest.param((4, 4, 5, 16), True, id="one-pixel-width"),
+ pytest.param((4, 4, 16, 5), False, id="one-pixel-height"),
+ pytest.param((4, 4, 16, 12), False, id="horizontal"),
+ pytest.param((4, 4, 8, 16), True, id="vertical"),
+ ),
+)
+def test_valid_text_crops_keep_pixels_and_source_ownership(bbox: tuple[int, int, int, int], rotate_for_rec: bool) -> None:
+ """有效单像素及横竖裁图保留原始像素和转正规则,支持只读输入且不共享源图存储。"""
+ image = np.arange(24 * 24 * 3, dtype=np.uint8).reshape(24, 24, 3)
+ original = image.copy()
+ image.flags.writeable = False
+ x0, y0, x1, y1 = bbox
+ points = np.asarray([[x0, y0], [x1, y0], [x1, y1], [x0, y1]], dtype=np.float32)
+ original_points = points.copy()
+ points.flags.writeable = False
+ expected = original[y0:y1, x0:x1]
+
+ crop = get_rotate_crop_image(image, points)
+ rec_crop = get_rotate_crop_image_for_text_rec(image, points)
+ assert crop is not None and rec_crop is not None
+ np.testing.assert_array_equal(crop, expected)
+ np.testing.assert_array_equal(rec_crop, np.rot90(expected) if rotate_for_rec else expected)
+ assert not np.shares_memory(crop, image) and not np.shares_memory(rec_crop, image)
+ np.testing.assert_array_equal(image, original)
+ np.testing.assert_array_equal(points, original_points)
+
+
+def test_valid_text_crop_does_not_hide_unrelated_warp_errors(monkeypatch: pytest.MonkeyPatch) -> None:
+ """有效倾斜框的其他采样错误继续抛出,不能被退化裁图处理吞掉。"""
+ image = np.zeros((24, 24, 3), dtype=np.uint8)
+ points = np.asarray([[4, 4], [16, 6], [16, 14], [4, 12]], dtype=np.float32)
+ monkeypatch.setattr(ocr_image, "warp_image", Mock(side_effect=ValueError("unexpected warp error")))
+ with pytest.raises(ValueError, match="unexpected warp error"):
+ get_rotate_crop_image_for_text_rec(image, points)
+
+
[email protected]("recognized", (False, True))
[email protected]("ocr_enable", (False, True))
+def test_ocr_result_filter_keeps_thresholds_and_read_only_input(recognized: bool, ocr_enable: bool) -> None:
+ """合并过滤后仍保留宽度和置信度边界、结果字段及只读源图的裁片像素。"""
+ image = np.arange(24 * 24 * 3, dtype=np.uint8).reshape(24, 24, 3)
+ original = image.copy()
+ image.flags.writeable = False
+ narrow = [[4, 4], [6, 4], [6, 8], [4, 8]]
+ valid = [[10, 4], [13, 4], [13, 8], [10, 8]]
+ ocr_res = (
+ [[narrow, ("narrow", 0.9)], [valid, ("valid", 0.876)], [valid, ("low-score", 0.49)]] if recognized else [narrow, valid]
+ )
+ output = get_ocr_result_list(ocr_res, [0, 0, 0, 0, 24, 24, 24, 24], ocr_enable, image)
+ assert len(output) == 1
+ item = output[0].copy()
+ crop = item.pop("np_img", None)
+ assert item == {
+ "label": "ocr_text",
+ "bbox": (10, 4, 13, 8),
+ "score": 0.88 if recognized and not ocr_enable else 1.0,
+ "text": "valid" if recognized else "",
+ }
+ if ocr_enable and not recognized:
+ assert crop is not None and not np.shares_memory(crop, image)
+ np.testing.assert_array_equal(crop, original[4:8, 10:13])
+ else:
+ assert crop is None
+ np.testing.assert_array_equal(image, original)
def test_formula_split_zero_width_fragment_preserves_valid_text() -> None:
@@ -41,25 +124,59 @@ def test_formula_split_zero_width_fragment_preserves_valid_text() -> None:
np.testing.assert_array_equal(output[0]["np_img"], image[4:12, 11:20])
[email protected]("mask_right", (10, 20))
-def test_torch_ocr_discards_invalid_crops_without_text_misalignment(mask_right: int) -> None:
- """Torch 整体 OCR 同步过滤零宽框和裁图,全部被过滤时不调用识别器。"""
- pytest.importorskip("torch")
- from mineru.model.ocr.pytorch_paddle import PytorchPaddleOCR
+def _build_text_ocr_model(engine: str, boxes: np.ndarray, texts: list[tuple[str, float]]) -> Any:
+ """仅替换检测和识别模型,保留两个后端的真实排序、裁图、过滤和结果组装。"""
+ if engine == "torch":
+ pytest.importorskip("torch")
+ from mineru.model.ocr.pytorch_paddle import PytorchPaddleOCR
- model = object.__new__(PytorchPaddleOCR)
+ model = object.__new__(PytorchPaddleOCR)
+ else:
+ from mineru.model.ocr.pp_ocr_v6_onnx import PPOCRv6ONNX
+
+ model = object.__new__(PPOCRv6ONNX)
model.is_seal = False
model.enable_merge_det_boxes = False
model.drop_score = 0.5
- model.text_detector = Mock(return_value=(np.asarray([[[4, 4], [20, 4], [20, 12], [4, 12]]]), 0.0))
- model.text_recognizer = Mock(return_value=([("valid", 0.99)], 0.0))
+ model.text_detector = Mock(return_value=(boxes, 0.0))
+ model.text_recognizer = Mock(return_value=(texts, 0.0))
+ return model
+
+
[email protected]("engine", [pytest.param("torch", marks=pytest.mark.torch), "onnx"])
[email protected]("mask_right", (10, 20))
+def test_formula_split_ocr_keeps_text_alignment(engine: str, mask_right: int) -> None:
+ """两个后端同步过滤公式拆框后的零宽裁片,全部被过滤时不调用识别器。"""
+ boxes = np.asarray([[[4, 4], [20, 4], [20, 12], [4, 12]]], dtype=np.float32)
+ model = _build_text_ocr_model(engine, boxes, [("valid", 0.99)])
image = np.zeros((24, 24, 3), dtype=np.uint8)
- boxes, texts = model(image, mfd_res=[{"bbox": [5, 4, mask_right, 12]}])
+ result = model.ocr(image, mfd_res=[{"bbox": [5, 4, mask_right, 12]}])
if mask_right == 20:
- assert boxes == texts == []
+ assert result == [None]
model.text_recognizer.assert_not_called()
else:
- assert len(boxes) == 1 and texts == [("valid", 0.99)]
- np.testing.assert_array_equal(boxes[0], [[11, 4], [20, 4], [20, 12], [11, 12]])
+ assert result == [[[[[11, 4], [20, 4], [20, 12], [11, 12]], ("valid", 0.99)]]]
assert len(model.text_recognizer.call_args.args[0]) == 1
+
+
[email protected]("engine", [pytest.param("torch", marks=pytest.mark.torch), "onnx"])
[email protected]("all_invalid", (False, True))
+def test_text_ocr_keeps_alignment_after_subpixel_crop_filter(engine: str, all_invalid: bool) -> None:
+ """跳过中间亚像素裁片后文字仍对应前后检测框,全无效输入保持空结果并跳过识别。"""
+ first = np.asarray([[4, 4], [12, 4], [12, 12], [4, 12]], dtype=np.float32)
+ invalid = np.asarray([[13, 4], [13.4, 4], [13.4, 12], [13, 12]], dtype=np.float32)
+ last = first + [16, 0]
+ boxes = np.asarray([invalid] if all_invalid else [first, invalid, last])
+ texts = [] if all_invalid else [("first", 0.99), ("last", 0.98)]
+ model = _build_text_ocr_model(engine, boxes, texts)
+ image = np.arange(32 * 32 * 3, dtype=np.uint8).reshape(32, 32, 3)
+ result = model.ocr(image)
+ if all_invalid:
+ assert result == [None]
+ model.text_recognizer.assert_not_called()
+ else:
+ assert result == [[[first.tolist(), texts[0]], [last.tolist(), texts[1]]]]
+ crops = model.text_recognizer.call_args.args[0]
+ assert len(crops) == 2
+ np.testing.assert_array_equal(crops[0], image[4:12, 4:12])
+ np.testing.assert_array_equal(crops[1], image[4:12, 20:28])