Metadata-Version: 2.4
Name: py-wechat-ocr
Version: 0.1.0
Summary: 微信 OCR 的 Python 封装库
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# py-wechat-ocr

这是一个基于微信 OCR 引擎（`WeChatOCR`）的 Python 封装库。它通过直接加载微信解包后的 `wxocr.dll` 结合底层的 CPython 扩展模块 `wcocr.pyd`（该二进制模块编译自 [swigger/wechat-ocr](https://github.com/swigger/wechat-ocr) 开源项目），实现极速、高准确率的本地图片文字识别（OCR）。

> **注意：** 本库底层依赖编译好的 Windows 动态链接库，因此**仅支持 Windows 平台**。

---

## 环境要求

- **操作系统**：Windows 10/11
- **Python 版本**：`>= 3.10`
- **已测试微信版本**：微信 `4.1.9.57` 版本测试通过
- **本地依赖**：电脑中已安装微信客户端（本库会自动从微信安装路径提取并解压核心的 OCR 依赖 `WeChatOcr.bin`）

---

## 安装方法

您可以使用 `uv` 或 `pip` 在本地项目中直接进行安装。

### 本地编译打包安装

首先，在项目根目录下构建包：

```bash
uv build
```

构建完成后会在 `dist/` 目录下生成 `.whl` 文件，您可以通过以下命令安装：

```bash
uv pip install dist/py_wechat_ocr-0.1.0-py3-none-any.whl
```

### 开发模式安装

如果您想要对本项目进行二次开发或调试，建议使用编辑模式（Editable Mode）安装：

```bash
uv pip install -e .
```

---

## 快速上手

安装完成后，您可以直接在您的 Python 代码中导入并使用它：

```python
from wechat_ocr import WeChatOCR

try:
    # 1. 初始化 OCR 引擎，需传入微信的实际安装路径
    # 引擎在首次运行时，会自动从该路径解压所需的 wxocr.dll 依赖文件
    wx_ocr = WeChatOCR(r"D:\Program Files\Tencent\Weixin")

    # 2. 识别指定图片
    print("开始识别...")
    result = wx_ocr.ocr_img("test.png")
    print("识别结果:", result)

    # 3. 如果需要保存识别后的 JSON 数据，可以将 save_json 设为 True
    # 识别结果将会自动保存在图片同目录下，命名为 test.png.json
    wx_ocr.ocr_img("test.png", save_json=True)

    # 4. 释放 OCR 引擎资源
    wx_ocr.close()
    print("微信 OCR 引擎已成功关闭。")

except Exception as e:
    print(f"运行期间发生错误: {e}")
```

---

## 核心 API 说明

### `WeChatOCR(wx_dir: str | Path)`
- **作用**：初始化 OCR 引擎环境。
- **参数**：
  - `wx_dir`: 微信客户端的安装路径（例如 `C:\Program Files\Tencent\Weixin`）。引擎将在此目录的子文件夹中寻找版本目录，并自动释放、定位 `wxocr.dll` 核心库。

### `ocr_img(image_path: str, save_json: bool = False)`
- **作用**：对指定的图片进行 OCR 文字识别。
- **参数**：
  - `image_path`: 需要识别的图片文件路径。
  - `save_json`: 是否在图片所在目录下输出一份同名 `.json` 结果文件，默认为 `False`。
- **返回值**：返回识别出来的 JSON 字典，包含文字内容、坐标位置与置信度。

### `close()`
- **作用**：手动关闭底层的 OCR 引擎并释放内存。

---

## 常见问题解答

1. **为什么提示“未找到核心文件: WeChatOcr.bin”？**
   请检查您传入的微信目录是否正确。本库需要在此目录下的子文件夹内找到类似 `[版本号]\WeChatOcr.bin` 的文件。如果微信安装在非常规路径下，请务必传入该非常规的微信安装根路径。
2. **能支持 Linux 或 macOS 吗？**
   不支持。核心的解压、DLL 注入以及 `wcocr.pyd` 的编译代码深度绑定了 Windows 操作系统下的微信客户端依赖。

---

## 鸣谢

- 本项目所使用的二进制扩展模块 `wcocr.pyd` 编译自开源项目 [swigger/wechat-ocr](https://github.com/swigger/wechat-ocr)。非常感谢原作者的开源贡献！

