# WeChatOCR

**Repository Path**: da9527/WeChatOCR

## Basic Information

- **Project Name**: WeChatOCR
- **Description**: python调用微信OCR
- **Primary Language**: Python
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 2
- **Forks**: 0
- **Created**: 2025-03-04
- **Last Updated**: 2026-01-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# WeChatOCR - 微信OCR识别工具

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Python](https://img.shields.io/badge/Python-3.x-blue.svg)](https://www.python.org/)
[![Platform](https://img.shields.io/badge/Platform-Windows-green.svg)]()

这是一个基于微信OCR引擎的Python文字识别工具，提供批处理和Web界面两种使用方式。

> 🙏 **致谢**：首先非常感谢 swigger、52PJ的FeiyuYip、nulptr 以及其他对此做出贡献的朋友。

## ✨ 项目特色

### 🔧 核心功能
- ✅ **本地化部署**：WeChatOCR.exe 完全本地化，不依赖微信安装路径
- ✅ **多格式支持**：支持 JPG、JPEG、PNG、BMP、TIF 等多种图片格式
- ✅ **批量处理**：自动遍历 `src/` 目录下所有图片进行OCR识别
- ✅ **结果导出**：OCR结果自动保存为 DOCX 格式文件
- ✅ **Web界面**：现代化的网页界面，支持单张图片识别和预览
- ✅ **图片标注**：在识别结果上绘制边界框和文字标注
- ✅ **图片预览**：支持点击放大查看高清图片

### 🎨 界面特性
- 🖼️ **左右对比**：原始图片与标注结果并排显示
- 🔍 **放大预览**：点击图片即可全屏查看高清大图
- 📱 **响应式设计**：适配不同屏幕尺寸
- 🎭 **现代UI**：渐变背景、卡片式布局、流畅动画
- ⌨️ **快捷键支持**：ESC关闭预览，键盘操作友好

### 🛠️ 开发特性
- 📦 **模块化设计**：通用工具函数提取到 `tools.py`
- 🧪 **类型安全**：完整的类型注解（Type Hints）
- 📝 **详细文档**：每个函数都有完整的docstring
- 🔄 **错误处理**：完善的异常处理和验证机制

## 📁 项目结构

```
WeChatOCR/
├── src/                    # 图片源文件夹（自动遍历）
│   ├── jpg/
│   ├── png/
│   ├── bmp/
│   └── tif/
├── docx/                   # OCR结果输出目录（自动生成）
├── uploads/                # Web上传临时目录（自动生成）
├── path/                   # WeChatOCR依赖文件
│   ├── WeChatOCR/         # WeChatOCR.exe 和模型文件
│   ├── mmmojo.dll
│   └── mmmojo_64.dll
├── templates/              # Web界面模板
│   └── index.html         # 前端页面
├── wcocr.pyd               # Windows Python扩展模块
├── OCR.py                  # 批量处理脚本
├── server.py               # Web服务器
├── tools.py                # 通用工具函数库
├── requirements.txt        # Python依赖
├── README.md               # 项目说明
└── LICENSE                 # MIT许可证
```

## 🚀 快速开始

### 1️⃣ 环境要求
- **操作系统**：Windows 7/10/11
- **Python版本**：Python 3.7+
- **依赖库**：见 `requirements.txt`

### 2️⃣ 安装步骤

```bash
# 1. 创建虚拟环境（推荐）
python -m venv .venv

# 2. 激活虚拟环境（Windows）
.venv\Scripts\activate

# 3. 安装依赖
pip install -r requirements.txt
```

### 3️⃣ 运行方式

#### 方式一：Web界面（推荐）
```bash
python server.py
```
访问 http://localhost:5000 即可使用现代化的Web界面

#### 方式二：批量处理
```bash
# 将图片放入 src/ 目录（支持子文件夹）
python OCR.py
# 结果将自动保存到 docx/ 目录
```

#### 方式三：编程调用
```python
from tools import wechat_ocr, draw_boxes_on_image

# 执行OCR识别
result = wechat_ocr("test.png")

# 绘制标注图片
annotated_img = draw_boxes_on_image("test.png", result)
annotated_img.save("result_annotated.png")
```

## 🌐 Web API 接口

### 📤 上传接口

#### 1. `/api/ocr` - 基础OCR接口
**请求方式**：POST
**参数**：`file` - 图片文件
**返回**：JSON格式的OCR结果

```json
{
  "success": true,
  "data": {
    "imgpath": "...",
    "errcode": 0,
    "width": 1024,
    "height": 768,
    "ocr_response": [
      {
        "text": "识别的文字",
        "left": 100,
        "top": 200,
        "right": 300,
        "bottom": 250,
        "rate": 0.95
      }
    ]
  }
}
```

#### 2. `/api/ocr_with_image` - OCR + 标注图片（推荐）
**请求方式**：POST
**参数**：`file` - 图片文件
**返回**：OCR结果 + Base64编码的标注图片

```json
{
  "success": true,
  "data": {
    "ocr_result": {...},
    "annotated_image": "data:image/png;base64,..."
  }
}
```

#### 3. `/api/ocr_with_image_file` - OCR + 图片文件
**请求方式**：POST
**参数**：`file` - 图片文件
**返回**：OCR结果 + 标注图片URL

```json
{
  "success": true,
  "data": {
    "ocr_result": {...},
    "annotated_image_url": "/api/image/annotated_xxx.png"
  }
}
```

#### 4. `/api/image/<filename>` - 获取标注图片
**请求方式**：GET
**参数**：filename - 图片文件名
**返回**：PNG图片文件

## 🛠️ 工具函数库 (tools.py)

### 核心函数

#### `wechat_ocr(image_path, wechat_path="path", wechatocr_path="path/WeChatOCR/WeChatOCR.exe")`
微信OCR识别函数
- **参数**：
  - `image_path`: 要识别的图片路径
  - `wechat_path`: WeChat路径（默认：path）
  - `wechatocr_path`: WeChatOCR.exe路径
- **返回**：OCR结果字典

#### `draw_boxes_on_image(image_path, ocr_result, box_color="red", text_color="black", bg_color="white", font_size=16)`
在图片上绘制OCR边界框和文字标注
- **参数**：
  - `image_path`: 图片路径
  - `ocr_result`: OCR识别结果
  - `box_color`: 边界框颜色（默认：red）
  - `text_color`: 文字颜色（默认：black）
  - `bg_color`: 文字背景颜色（默认：white）
  - `font_size`: 字体大小（默认：16）
- **返回**：PIL Image对象

#### `image_to_base64(img, format="PNG")`
将PIL Image转换为base64字符串
- **参数**：
  - `img`: PIL Image对象
  - `format`: 图片格式（默认：PNG）
- **返回**：base64编码字符串

#### `save_annotated_image(img, output_path, format="PNG")`
保存标注图片到文件
- **参数**：
  - `img`: PIL Image对象
  - `output_path`: 输出路径
  - `format`: 图片格式（默认：PNG）
- **返回**：保存的文件路径

#### `parse_ocr_result(result)`
解析OCR识别结果，统一为字典格式
- **参数**：`result` - OCR识别结果
- **返回**：解析后的字典

#### `generate_unique_filename(original_filename, prefix="")`
生成唯一文件名（UUID + 原始文件名）
- **参数**：
  - `original_filename`: 原始文件名
  - `prefix`: 文件名前缀（默认：空）
- **返回**：唯一的文件名

#### `validate_wechat_ocr_environment()`
验证WeChatOCR运行环境是否就绪
- **返回**：环境是否就绪（bool）

## 📖 使用示例

### 示例1：Web界面使用
```bash
# 启动服务器
python server.py

# 浏览器访问
# http://localhost:5000

# 操作步骤：
# 1. 选择OCR接口（推荐：OCR + 标注图片）
# 2. 上传图片文件
# 3. 点击"开始识别"
# 4. 查看原始图片和标注结果
# 5. 点击图片可放大预览
```

### 示例2：批量处理
```bash
# 1. 将图片放入 src/ 目录
#    src/
#    ├── photo1.png
#    ├── photo2.jpg
#    └── subfolder/
#        └── photo3.png

# 2. 运行批量处理
python OCR.py

# 3. 查看结果
#    docx/
#    ├── photo1_OCR.docx
#    ├── photo2_OCR.docx
#    └── subfolder/
#        └── photo3_OCR.docx
```

### 示例3：编程调用
```python
from tools import (
    wechat_ocr,
    draw_boxes_on_image,
    image_to_base64,
    parse_ocr_result,
    generate_unique_filename,
)

# 1. 执行OCR
result = wechat_ocr("test.png")

# 2. 解析结果
parsed_result = parse_ocr_result(result)

# 3. 绘制标注
annotated_img = draw_boxes_on_image("test.png", parsed_result)

# 4. 转换为base64（用于Web显示）
base64_str = image_to_base64(annotated_img)

# 5. 保存文件
unique_name = generate_unique_filename("result.png")
annotated_img.save(unique_name)
```

### 示例4：批量处理脚本
```python
from tools import wechat_ocr, draw_boxes_on_image, save_annotated_image
import os

def batch_ocr(folder_path, output_folder):
    """批量OCR处理"""
    os.makedirs(output_folder, exist_ok=True)

    for root, dirs, files in os.walk(folder_path):
        for file in files:
            if file.lower().endswith(('.png', '.jpg', '.jpeg', '.bmp', '.tif')):
                image_path = os.path.join(root, file)

                # 执行OCR
                result = wechat_ocr(image_path)

                if result and 'ocr_response' in result:
                    # 绘制标注
                    annotated_img = draw_boxes_on_image(image_path, result)

                    # 保存结果
                    relative_path = os.path.relpath(root, folder_path)
                    output_dir = os.path.join(output_folder, relative_path)
                    os.makedirs(output_dir, exist_ok=True)

                    output_path = os.path.join(output_dir, f"annotated_{file}")
                    save_annotated_image(annotated_img, output_path)
                    print(f"✅ 处理完成: {file}")

# 使用示例
batch_ocr("src", "annotated_output")
```

## ⚙️ 配置说明

### 图片格式支持
- ✅ **推荐格式**：PNG（识别效果最佳）
- ✅ **支持格式**：JPG、JPEG、PNG、BMP、TIF
- ✅ **自动遍历**：支持 `src/` 目录下的子文件夹

### OCR结果格式
- **DOCX文件**：批量处理时自动生成
- **JSON数据**：Web API返回结构化数据
- **标注图片**：带边界框和文字的可视化结果

### 字体配置
- **优先使用**：Windows系统字体（黑体、宋体、微软雅黑）
- **备用方案**：PIL默认字体（自动降级）

## 🔧 常见问题

### Q1: 为什么推荐PNG格式？
A: 微信OCR对PNG格式的识别准确率最高，建议将其他格式转换为PNG后再处理。

### Q2: 如何处理大量图片？
A: 使用批量处理模式 `python OCR.py`，会自动遍历 `src/` 目录下所有图片。

### Q3: Web界面无法访问？
A: 检查端口5000是否被占用，或防火墙设置。

### Q4: OCR识别结果为空？
A: 检查 `path/` 目录是否完整，包含 WeChatOCR.exe 和相关DLL文件。

### Q5: 如何自定义输出路径？
A: 修改 `server.py` 中的 `UPLOAD_FOLDER` 或 `OCR.py` 中的输出路径配置。

## 📋 依赖说明

### Python包
- `Flask==3.1.0` - Web框架
- `Pillow==11.1.0` - 图片处理
- `python-docx==1.1.2` - Word文档生成
- `click==8.1.8` - 命令行工具
- `colorama==0.4.6` - 彩色输出
- `lxml==5.3.0` - XML处理
- `Werkzeug==3.1.3` - Web工具包

### 系统依赖
- **Windows系统**：仅支持Windows（wcocr.pyd为Windows扩展）
- **Python 3.7+**：推荐Python 3.8+
- **Pillow库**：用于图片处理和标注

## 📄 许可证

本项目采用 [MIT License](LICENSE) 许可证。

## 🤝 贡献

欢迎提交Issue和Pull Request！

## 📞 联系方式

如有问题，请在GitHub Issues中提出。

---

**注意**：本项目基于微信OCR引擎，仅供学习和研究使用。请遵守相关法律法规和使用条款。