|
|
@@ -0,0 +1,491 @@
|
|
|
+# 水印去除技术文档
|
|
|
+
|
|
|
+## 概述
|
|
|
+
|
|
|
+水印去除模块 (`ocr_utils/watermark_utils.py`) 提供了**两层独立的水印去除能力**，针对不同类型的文档和场景进行优化：
|
|
|
+
|
|
|
+| 层级 | 处理对象 | 适用场景 | 特点 |
|
|
|
+|------|---------|---------|------|
|
|
|
+| **PDF 层级** | 文字型 PDF 的 XObject | 银行流水等文字型 PDF | 保留文字可搜索性，无损处理 |
|
|
|
+| **图像层级** | 扫描件/渲染图像的像素 | 扫描件、图片 | 像素级处理，适用于 OCR 前预处理 |
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 处理流程
|
|
|
+
|
|
|
+```mermaid
|
|
|
+graph TB
|
|
|
+ A[输入文档] --> B{是否为 PDF?}
|
|
|
+
|
|
|
+ B -->|是| C[阶段一: PDF 层级去水印]
|
|
|
+ B -->|否| F
|
|
|
+
|
|
|
+ C --> D{启用 txt_pdf_watermark_removal?}
|
|
|
+ D -->|是| E[扫描前 N 页检测水印 XObject]
|
|
|
+ D -->|否| G
|
|
|
+ E --> E1{发现水印?}
|
|
|
+ E1 -->|是| E2[清除 XObject 内容流]
|
|
|
+ E1 -->|否| G
|
|
|
+ E2 --> G
|
|
|
+
|
|
|
+ G[渲染为图像] --> H{PDF 类型?}
|
|
|
+ H -->|文字型 txt| I[跳过阶段二]
|
|
|
+ H -->|扫描件 ocr| J
|
|
|
+
|
|
|
+ F[图像输入] --> J[阶段二: 图像级去水印]
|
|
|
+
|
|
|
+ J --> K{启用 watermark_removal?}
|
|
|
+ K -->|是| L[检测浅色斜向水印]
|
|
|
+ K -->|否| N
|
|
|
+ L --> M[阈值化去除水印]
|
|
|
+ M --> N[方向校正]
|
|
|
+
|
|
|
+ N --> O[Layout 检测]
|
|
|
+ O --> P[OCR 识别]
|
|
|
+
|
|
|
+ style C fill:#e1f5ff
|
|
|
+ style E fill:#e1f5ff
|
|
|
+ style E2 fill:#e1f5ff
|
|
|
+ style J fill:#fff4e1
|
|
|
+ style L fill:#fff4e1
|
|
|
+ style M fill:#fff4e1
|
|
|
+```
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 阶段一：PDF 层级水印去除
|
|
|
+
|
|
|
+### 适用场景
|
|
|
+
|
|
|
+**文字型 PDF（`pdf_type='txt'`）**：PDF 内部包含可提取的文字层，水印通常以 XObject 形式叠加在文字上方。
|
|
|
+
|
|
|
+### 原理
|
|
|
+
|
|
|
+PDF 文件中的水印通常通过以下两种 XObject 实现：
|
|
|
+
|
|
|
+1. **Form XObject**：矢量绘图对象，包含旋转、透明度等变换矩阵
|
|
|
+2. **Image XObject**：位图对象，通常是半透明的全页背景图
|
|
|
+
|
|
|
+通过 PyMuPDF (fitz) 直接操作 PDF 内部结构，**清空或替换水印 XObject 的内容流**，而不影响文字层的可搜索性。
|
|
|
+
|
|
|
+### 水印 XObject 判断规则
|
|
|
+
|
|
|
+#### Form XObject 水印判断 (`_is_watermark_xobj`)
|
|
|
+
|
|
|
+满足以下条件之一即判定为水印：
|
|
|
+
|
|
|
+| 规则 | 说明 | 原理 |
|
|
|
+|------|------|------|
|
|
|
+| 旋转变换 | 内容流中 `cm` 指令的 sin/cos 分量非零 | 水印通常斜向 45° 放置 |
|
|
|
+| 透明度组 + 透明操作符 | `/Group` 存在且内容流含 `ca/CA` | 水印具有半透明效果 |
|
|
|
+| 透明度组 + 大体积流 | `/Group` 存在且流体积 > 2KB | 大量重复绘图 = 平铺水印 |
|
|
|
+
|
|
|
+```python
|
|
|
+# 判断逻辑伪代码
|
|
|
+def _is_watermark_xobj(doc, xref, obj_str):
|
|
|
+ if "/Form" not in obj_str:
|
|
|
+ return False
|
|
|
+
|
|
|
+ stream_text = doc.xref_stream(xref).decode("latin-1")
|
|
|
+
|
|
|
+ # 规则1：旋转变换
|
|
|
+ if has_rotation_transform(stream_text):
|
|
|
+ return True
|
|
|
+
|
|
|
+ # 规则2-3：透明度组相关
|
|
|
+ if "/Group" in obj_str:
|
|
|
+ if has_transparency_operators(stream_text):
|
|
|
+ return True
|
|
|
+ if len(stream_text) > 2048:
|
|
|
+ return True
|
|
|
+
|
|
|
+ return False
|
|
|
+```
|
|
|
+
|
|
|
+#### Image XObject 水印判断 (`_is_watermark_image_xobj`)
|
|
|
+
|
|
|
+必须同时满足以下条件：
|
|
|
+
|
|
|
+| 条件 | 说明 |
|
|
|
+|------|------|
|
|
|
+| `/Subtype /Image` | 确认是图像对象 |
|
|
|
+| 存在 `/SMask` | 有透明通道（半透明） |
|
|
|
+| 宽 >= 600 且 高 >= 800 | 全页尺寸（排除小图标） |
|
|
|
+| 像素均值 >= 240 | 近乎全白（水印文字稀疏） |
|
|
|
+
|
|
|
+### 处理方法
|
|
|
+
|
|
|
+```python
|
|
|
+def remove_txt_pdf_watermark(pdf_bytes: bytes) -> Optional[bytes]:
|
|
|
+ """
|
|
|
+ 对文字型 PDF 执行原生水印去除
|
|
|
+
|
|
|
+ 处理方式：
|
|
|
+ - Form XObject：清空内容流 (update_stream(b""))
|
|
|
+ - Image XObject：替换为全白像素 + 移除 DecodeParms
|
|
|
+
|
|
|
+ Returns:
|
|
|
+ 去水印后的 PDF bytes，若未发现水印返回 None
|
|
|
+ """
|
|
|
+ doc = fitz.open(stream=pdf_bytes, filetype="pdf")
|
|
|
+
|
|
|
+ for page in doc:
|
|
|
+ # 处理 Form XObject 水印
|
|
|
+ for xref, name, *_ in page.get_xobjects():
|
|
|
+ if _is_watermark_xobj(doc, xref, obj_str):
|
|
|
+ doc.update_stream(xref, b"") # 清空内容流
|
|
|
+
|
|
|
+ # 处理 Image XObject 水印
|
|
|
+ for img_tuple in page.get_images(full=True):
|
|
|
+ img_xref = img_tuple[0]
|
|
|
+ if _is_watermark_image_xobj(doc, img_xref, obj_str):
|
|
|
+ _blank_watermark_image(doc, img_xref) # 替换为全白
|
|
|
+
|
|
|
+ return doc.tobytes(garbage=4, deflate=True)
|
|
|
+```
|
|
|
+
|
|
|
+### 关键技术细节
|
|
|
+
|
|
|
+**移除 `/DecodeParms` 的必要性**：
|
|
|
+
|
|
|
+当 Image XObject 使用 Predictor 压缩时，必须先移除 `/DecodeParms` 再调用 `update_stream`，否则渲染器会尝试 Predictor 解码失败后回退原始数据，水印依然可见。
|
|
|
+
|
|
|
+```python
|
|
|
+def _blank_watermark_image(doc, img_xref):
|
|
|
+ # 关键：先移除 DecodeParms
|
|
|
+ doc.xref_set_key(img_xref, "DecodeParms", "null")
|
|
|
+ # 再更新为全白像素
|
|
|
+ doc.update_stream(img_xref, bytes([255]) * (w * h * channels))
|
|
|
+```
|
|
|
+
|
|
|
+### 快速预扫描 (`scan_pdf_watermark_xobjs`)
|
|
|
+
|
|
|
+对于大型 PDF（如财报），先执行只读扫描判断是否存在水印，避免不必要的全量处理：
|
|
|
+
|
|
|
+```python
|
|
|
+def scan_pdf_watermark_xobjs(pdf_bytes: bytes, sample_pages: int = 3) -> bool:
|
|
|
+ """
|
|
|
+ 快速扫描前 N 页，判断是否含水印 XObject
|
|
|
+
|
|
|
+ Args:
|
|
|
+ sample_pages: 扫描页数上限，默认 3（银行流水通常前几页有水印）
|
|
|
+
|
|
|
+ Returns:
|
|
|
+ True 表示发现水印 XObject
|
|
|
+ """
|
|
|
+ doc = fitz.open(stream=pdf_bytes, filetype="pdf")
|
|
|
+ for i in range(min(sample_pages, len(doc))):
|
|
|
+ # 检查 Form XObject 和 Image XObject
|
|
|
+ ...
|
|
|
+ return False
|
|
|
+```
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 阶段二：图像级水印去除
|
|
|
+
|
|
|
+### 适用场景
|
|
|
+
|
|
|
+**扫描件/图片（`pdf_type='ocr'`）**：无法从 PDF 内部结构处理，只能对渲染后的图像进行像素级处理。
|
|
|
+
|
|
|
+### 原理
|
|
|
+
|
|
|
+银行流水等金融文档的水印特征：
|
|
|
+
|
|
|
+- **颜色浅**：灰度值通常在 160-220 之间（介于正文和背景之间）
|
|
|
+- **角度斜**：通常 45° 斜向排列
|
|
|
+- **文字稀疏**：水印文字占比较小
|
|
|
+
|
|
|
+基于这些特征，采用**阈值化处理**：将灰度值高于阈值的像素置为白色，保留深色正文。
|
|
|
+
|
|
|
+### 水印检测 (`detect_watermark`)
|
|
|
+
|
|
|
+采用两阶段检测策略：
|
|
|
+
|
|
|
+1. **中间调检测**：统计灰度在 100-220 之间的像素占比
|
|
|
+2. **斜向验证**：使用 Hough 直线变换验证是否存在斜向纹理
|
|
|
+
|
|
|
+```python
|
|
|
+def detect_watermark(image, midtone_low=100, midtone_high=220, ratio_threshold=0.03):
|
|
|
+ """
|
|
|
+ 检测图像中是否存在浅色斜向文字水印
|
|
|
+
|
|
|
+ 步骤：
|
|
|
+ 1. 提取中间调像素（100-220），计算占比
|
|
|
+ 2. 若占比 > 3%，进行斜向验证
|
|
|
+ 3. 使用 Canny 边缘检测 + Hough 直线变换
|
|
|
+ 4. 统计 30-60° 斜向直线数量
|
|
|
+ """
|
|
|
+ gray = to_grayscale(image)
|
|
|
+
|
|
|
+ # 步骤1：中间调检测
|
|
|
+ midtone_mask = (gray > midtone_low) & (gray < midtone_high)
|
|
|
+ if midtone_mask.sum() / gray.size < ratio_threshold:
|
|
|
+ return False
|
|
|
+
|
|
|
+ # 步骤2：斜向验证
|
|
|
+ edges = cv2.Canny(midtone_mask, 50, 150)
|
|
|
+ lines = cv2.HoughLines(edges, rho=1, theta=np.pi/180, threshold=80)
|
|
|
+
|
|
|
+ # 统计斜向（30-60°）直线
|
|
|
+ diagonal_count = count_diagonal_lines(lines, angle_range=(30, 60))
|
|
|
+ return diagonal_count >= 2
|
|
|
+```
|
|
|
+
|
|
|
+### 水印去除 (`remove_watermark_from_image`)
|
|
|
+
|
|
|
+```python
|
|
|
+def remove_watermark_from_image(image, threshold=160, morph_close_kernel=0):
|
|
|
+ """
|
|
|
+ 去除图像中的浅色斜向文字水印
|
|
|
+
|
|
|
+ 原理：
|
|
|
+ - 正文为深黑色（灰度 < threshold）
|
|
|
+ - 水印为浅灰（灰度 > threshold）
|
|
|
+ - 将高于阈值的像素置为白色（255）
|
|
|
+
|
|
|
+ Args:
|
|
|
+ threshold: 灰度阈值，建议 140-180，默认 160
|
|
|
+ morph_close_kernel: 形态学闭运算核，0 表示跳过
|
|
|
+ """
|
|
|
+ gray = to_grayscale(image)
|
|
|
+
|
|
|
+ # 阈值化：保留深色正文
|
|
|
+ cleaned = gray.copy()
|
|
|
+ cleaned[gray > threshold] = 255
|
|
|
+
|
|
|
+ # 可选：形态学闭运算填补字符断裂
|
|
|
+ if morph_close_kernel > 0:
|
|
|
+ kernel = np.ones((morph_close_kernel, morph_close_kernel), np.uint8)
|
|
|
+ cleaned = cv2.morphologyEx(cleaned, cv2.MORPH_CLOSE, kernel)
|
|
|
+
|
|
|
+ return cleaned
|
|
|
+```
|
|
|
+
|
|
|
+### 参数说明
|
|
|
+
|
|
|
+| 参数 | 默认值 | 说明 | 调整建议 |
|
|
|
+|------|--------|------|---------|
|
|
|
+| `threshold` | 160 | 灰度阈值 | 140-180，越大越保守（可能残留水印） |
|
|
|
+| `morph_close_kernel` | 0 | 形态学核大小 | 非二值图建议设为 0（闭运算会适得其反） |
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 配置说明
|
|
|
+
|
|
|
+### 完整配置示例
|
|
|
+
|
|
|
+```yaml
|
|
|
+# 输入配置 - PDF 层级去水印
|
|
|
+input:
|
|
|
+ dpi: 200
|
|
|
+ txt_pdf_watermark_removal:
|
|
|
+ enabled: true # 是否启用 PDF 层级去水印
|
|
|
+ sample_pages: 3 # 快速预扫描页数
|
|
|
+
|
|
|
+# 预处理配置 - 图像级去水印
|
|
|
+preprocessor:
|
|
|
+ module: "mineru"
|
|
|
+ orientation_classifier:
|
|
|
+ enabled: true
|
|
|
+ watermark_removal:
|
|
|
+ enabled: true # 是否启用图像级去水印
|
|
|
+ threshold: 160 # 灰度阈值
|
|
|
+ morph_close_kernel: 0 # 形态学核大小（建议 0）
|
|
|
+```
|
|
|
+
|
|
|
+### 配置项详解
|
|
|
+
|
|
|
+| 配置路径 | 类型 | 默认值 | 说明 |
|
|
|
+|---------|------|--------|------|
|
|
|
+| `input.txt_pdf_watermark_removal.enabled` | bool | `false` | PDF 层级去水印开关 |
|
|
|
+| `input.txt_pdf_watermark_removal.sample_pages` | int | 3 | 预扫描页数 |
|
|
|
+| `preprocessor.watermark_removal.enabled` | bool | `false` | 图像级去水印开关 |
|
|
|
+| `preprocessor.watermark_removal.threshold` | int | 160 | 灰度阈值 |
|
|
|
+| `preprocessor.watermark_removal.morph_close_kernel` | int | 0 | 形态学核大小 |
|
|
|
+
|
|
|
+**注意**：两个配置均无默认值，必须在 YAML 中显式配置 `enabled: true` 才会触发。
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 触发条件
|
|
|
+
|
|
|
+### 阶段一触发条件
|
|
|
+
|
|
|
+```python
|
|
|
+# pipeline_manager_v2.py: process_document()
|
|
|
+
|
|
|
+if is_pdf:
|
|
|
+ wm_cfg = config.get('input', {}).get('txt_pdf_watermark_removal', {})
|
|
|
+ if wm_cfg.get('enabled', False): # 条件①
|
|
|
+ if scan_pdf_watermark_xobjs(pdf_bytes, sample_pages=3): # 条件②
|
|
|
+ cleaned = remove_txt_pdf_watermark(pdf_bytes)
|
|
|
+```
|
|
|
+
|
|
|
+**触发条件**：
|
|
|
+1. 文件是 PDF
|
|
|
+2. `enabled: true`
|
|
|
+3. 扫描发现水印 XObject
|
|
|
+
|
|
|
+### 阶段二触发条件
|
|
|
+
|
|
|
+```python
|
|
|
+# pipeline_manager_v2.py: _process_single_page()
|
|
|
+
|
|
|
+if pdf_type == 'ocr': # 条件①：仅扫描件
|
|
|
+ detection_image, angle = self.preprocessor.process(original_image)
|
|
|
+
|
|
|
+# mineru_adapter.py: MinerUPreprocessor.process()
|
|
|
+
|
|
|
+if config.get('watermark_removal', {}).get('enabled', False): # 条件②
|
|
|
+ image = remove_watermark_from_image_rgb(image, threshold=160)
|
|
|
+```
|
|
|
+
|
|
|
+**触发条件**：
|
|
|
+1. PDF 类型为 `ocr`（扫描件）
|
|
|
+2. `preprocessor.watermark_removal.enabled: true`
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 两阶段对比
|
|
|
+
|
|
|
+| 维度 | 阶段一（PDF 层级） | 阶段二（图像级） |
|
|
|
+|------|------------------|-----------------|
|
|
|
+| **处理对象** | 文字型 PDF | 扫描件/图片 |
|
|
|
+| **处理层级** | PDF XObject | 图像像素 |
|
|
|
+| **保留文字可搜索性** | ✅ 是 | ❌ 否 |
|
|
|
+| **无损处理** | ✅ 是 | ❌ 否（像素修改） |
|
|
|
+| **处理时机** | 渲染前 | 渲染后、检测前 |
|
|
|
+| **依赖库** | PyMuPDF (fitz) | OpenCV, NumPy |
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 代码集成
|
|
|
+
|
|
|
+### 流水线集成
|
|
|
+
|
|
|
+```python
|
|
|
+# pipeline_manager_v2.py
|
|
|
+
|
|
|
+from ocr_utils.watermark_utils import (
|
|
|
+ scan_pdf_watermark_xobjs,
|
|
|
+ remove_txt_pdf_watermark
|
|
|
+)
|
|
|
+
|
|
|
+class EnhancedDocPipeline:
|
|
|
+ def process_document(self, doc_path):
|
|
|
+ # 阶段一：PDF 层级去水印
|
|
|
+ _pdf_bytes_override = None
|
|
|
+ if is_pdf and config['input']['txt_pdf_watermark_removal']['enabled']:
|
|
|
+ raw_bytes = doc_path.read_bytes()
|
|
|
+ if scan_pdf_watermark_xobjs(raw_bytes):
|
|
|
+ _pdf_bytes_override = remove_txt_pdf_watermark(raw_bytes)
|
|
|
+
|
|
|
+ # 渲染 PDF（使用去水印后的 bytes）
|
|
|
+ images, pdf_type, pdf_doc = PDFUtils.load_and_classify_document(
|
|
|
+ doc_path, pdf_bytes=_pdf_bytes_override
|
|
|
+ )
|
|
|
+
|
|
|
+ # 逐页处理
|
|
|
+ for page_idx, original_image in enumerate(images):
|
|
|
+ # 阶段二：图像级去水印（在 preprocessor.process 中）
|
|
|
+ if pdf_type == 'ocr':
|
|
|
+ detection_image, angle = self.preprocessor.process(original_image)
|
|
|
+
|
|
|
+ # Layout 检测、OCR...
|
|
|
+```
|
|
|
+
|
|
|
+### 预处理器集成
|
|
|
+
|
|
|
+```python
|
|
|
+# models/adapters/mineru_adapter.py
|
|
|
+
|
|
|
+from ocr_utils.watermark_utils import remove_watermark_from_image_rgb
|
|
|
+
|
|
|
+class MinerUPreprocessor:
|
|
|
+ def process(self, image):
|
|
|
+ # 图像级水印去除（在方向校正之前）
|
|
|
+ if self.config.get('watermark_removal', {}).get('enabled', False):
|
|
|
+ threshold = self.config.get('watermark_removal', {}).get('threshold', 160)
|
|
|
+ image = remove_watermark_from_image_rgb(image, threshold=threshold)
|
|
|
+
|
|
|
+ # 方向校正
|
|
|
+ if self.orientation_classifier:
|
|
|
+ angle = self.orientation_classifier.predict(image)
|
|
|
+ image = self._apply_rotation(image, angle)
|
|
|
+
|
|
|
+ return image, angle
|
|
|
+```
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 使用示例
|
|
|
+
|
|
|
+### 命令行
|
|
|
+
|
|
|
+```bash
|
|
|
+# 处理含水印的银行流水 PDF
|
|
|
+python main_v2.py -i bank_statement.pdf -c config/bank_statement_yusys_v4.yaml --scene bank_statement
|
|
|
+
|
|
|
+# 配置文件中已启用：
|
|
|
+# input.txt_pdf_watermark_removal.enabled: true
|
|
|
+# preprocessor.watermark_removal.enabled: true
|
|
|
+```
|
|
|
+
|
|
|
+### Python API
|
|
|
+
|
|
|
+```python
|
|
|
+from core.pipeline_manager_v2 import EnhancedDocPipeline
|
|
|
+
|
|
|
+# 使用包含水印去除配置的 YAML
|
|
|
+with EnhancedDocPipeline("config/bank_statement_yusys_v4.yaml") as pipeline:
|
|
|
+ results = pipeline.process_document("document.pdf")
|
|
|
+```
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 调试与验证
|
|
|
+
|
|
|
+### 日志输出
|
|
|
+
|
|
|
+```python
|
|
|
+# 阶段一日志
|
|
|
+logger.info(f"🧹 文字型 PDF 原生去水印完成（{doc_path.name}）")
|
|
|
+logger.debug(f" [Form XObject] 清空水印 xref={xref}, name={name}")
|
|
|
+logger.debug(f" [Image XObject] 替换水印图像 xref={img_xref}")
|
|
|
+
|
|
|
+# 阶段二日志
|
|
|
+logger.info(f"🧹 Watermark removed (threshold={threshold})")
|
|
|
+```
|
|
|
+
|
|
|
+### 可视化验证
|
|
|
+
|
|
|
+在 debug 模式下，可以通过对比去水印前后的图像来验证效果：
|
|
|
+
|
|
|
+```bash
|
|
|
+# 开启 debug 模式
|
|
|
+python main_v2.py -i doc.pdf -c config.yaml --scene bank_statement --debug
|
|
|
+
|
|
|
+# 输出文件：
|
|
|
+# {doc}_pdf_page_001.png - 渲染后的页面图像（去水印后）
|
|
|
+# {doc}_page_001_layout.png - Layout 可视化
|
|
|
+```
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 注意事项
|
|
|
+
|
|
|
+1. **两个阶段是互补的**：阶段一处理文字型 PDF，阶段二处理扫描件，实际不会重复执行
|
|
|
+2. **阈值选择**：`threshold=160` 适用于大多数银行流水，如果误删浅色文字可适当提高
|
|
|
+3. **形态学运算**：`morph_close_kernel=0` 是推荐值，非二值图时闭运算可能引入噪声
|
|
|
+4. **大文件优化**：`sample_pages=3` 快速预扫描，避免对无水印的大文件全量处理
|
|
|
+5. **依赖要求**：PDF 层级去水印需要 `PyMuPDF`，图像级需要 `OpenCV`
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 参考资料
|
|
|
+
|
|
|
+- `ocr_utils/watermark_utils.py` - 水印工具函数实现
|
|
|
+- `core/pipeline_manager_v2.py` - 流水线集成
|
|
|
+- `models/adapters/mineru_adapter.py` - 预处理器集成
|
|
|
+- `config/bank_statement_*.yaml` - 配置示例
|
