Transforms complex documents like PDFs and Office docs into LLM-ready markdown/JSON for your Agentic workflows.
Python ai4sciencedocument-analysisdocxextract-datalayout-analysisocrparserpdfpdf-converterpdf-extractor-llmpdf-extractor-pretrainpdf-extractor-ragpdf-parserpptxpythonxlsx
refactor(ocr): unify degenerate crop handling and reduce copies
myhloli99e66dff364b
diff --git a/mineru/model/ocr/image.py b/mineru/model/ocr/image.pyindex 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 Noneif 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.pyindex fc4045d7..669b30e0 100644--- a/mineru/model/ocr/results.py+++ b/mineru/model/ocr/results.py@@ -3,7 +3,6 @@from __future__ import annotations-import copyfrom typing import Anyimport 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_listocr_result_list = []- ori_im = Nonefor box_ocr_res in ocr_res:img_crop = Noneneed_ocr_rec = False@@ -60,21 +58,17 @@ def get_ocr_result_list(else:p1, p2, p3, p4 = box_ocr_restext, 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_enablepoly = [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:+ continueif calculate_is_angle(poly):x_center = sum(point[0] for point in poly) / 4y_center = sum(point[1] for point in poly) / 4diff --git a/tests/unittest/test_ocr_text_crop_degenerate.py b/tests/unittest/test_ocr_text_crop_degenerate.pyindex 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 Anyfrom unittest.mock import Mockimport numpy as npimport pytest+from mineru.model.ocr import image as ocr_imagefrom 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_recfrom 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 Noneassert 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 = Falsemodel.enable_merge_det_boxes = Falsemodel.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])