Metadata-Version: 2.4
Name: copaw-ocr-skill
Version: 1.0.0
Summary: 基于 RapidOCR 的高性能本地 OCR 技能
Home-page: https://github.com/lcq225/copaw-ocr-skill
Author: 老 K
Author-email: lcq225@github.com
Project-URL: Bug Reports, https://github.com/lcq225/copaw-ocr-skill/issues
Project-URL: Source, https://github.com/lcq225/copaw-ocr-skill
Project-URL: Documentation, https://github.com/lcq225/copaw-ocr-skill/blob/main/SKILL.md
Keywords: ocr rapidocr copaw skill ai agent image-recognition
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Image Recognition
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: rapidocr-onnxruntime>=1.4.4
Requires-Dist: Pillow>=8.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: black>=22.0.0; extra == "dev"
Requires-Dist: flake8>=4.0.0; extra == "dev"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license-file
Dynamic: project-url
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# CoPaw OCR Skill

[![Python Version](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
[![OCR Engine](https://img.shields.io/badge/OCR-RapidOCR-orange.svg)](https://github.com/RapidAI/RapidOCR)

> 基于 RapidOCR 的高性能本地 OCR 技能，支持文件识别、截图识别、Base64 识别

---

## ✨ 特性

- 🚀 **高性能** - 速度快 3-5 倍，基于 ONNX Runtime
- 🎯 **高准确率** - 99.61% 平均置信度，工业级质量
- 📦 **轻量级** - 仅 14.9MB，比 PaddleOCR 小 10 倍
- 🔗 **智能路由** - 自动识别输入类型（文件/Base64/截图）
- 💰 **完全免费** - 无 API Key，无任何费用
- 🔧 **易于使用** - 一行代码搞定

---

## 📦 安装

### 方式 1：从 PyPI 安装（推荐）

```bash
pip install copaw-ocr-skill
```

### 方式 2：从 GitHub 安装

```bash
pip install git+https://github.com/lcq225/copaw-ocr-skill.git
```

### 方式 3：本地安装

```bash
git clone https://github.com/lcq225/copaw-ocr-skill.git
cd copaw-ocr-skill
pip install -e .
```

---

## 🚀 快速开始

### 基础用法

```python
from copaw_ocr import recognize, extract_text

# 文件识别
result = recognize('image.png')
print(result['full_text'])

# 截图识别
result = recognize()
print(result['full_text'])

# 提取纯文本
text = extract_text('image.png')
print(text)
```

### 高级用法

```python
from copaw_ocr import OCRSkill

# 创建 OCR 实例
skill = OCRSkill()

# 文件识别
result = skill.recognize_from_file('image.png')

# Base64 识别
result = skill.recognize_from_base64(base64_data)

# 截图识别
result = skill.recognize_from_screenshot()
```

---

## 📖 使用示例

### 示例 1：批量处理

```python
from pathlib import Path
from copaw_ocr import OCRSkill

skill = OCRSkill()

for img_path in Path('images').glob('*.png'):
    result = skill.recognize_from_file(str(img_path))
    if result.get('success'):
        print(f"{img_path.name}: {result['text_count']} 个文本块")
```

### 示例 2：置信度过滤

```python
from copaw_ocr import recognize

result = recognize('image.png')

# 过滤高置信度文本
high_conf_texts = [
    t['text'] for t in result['texts']
    if t['confidence'] >= 0.95
]

print(high_conf_texts)
```

### 示例 3：与 Windows-MCP 集成

```python
from windows_mcp import WindowsMCP
from copaw_ocr import recognize

with WindowsMCP() as mcp:
    # 点击按钮
    mcp.Click(loc=[500, 300])

    # 截图识别
    result = recognize()

    if result.get('success'):
        print(result['full_text'])
```

更多示例请参考 [`examples/`](examples/) 目录。

---

## 📊 返回结果格式

```python
{
    "success": True,
    "text_count": 212,
    "full_text": "任务管理器\n进程\n运行新任务...",
    "texts": [
        {
            "text": "任务管理器",
            "confidence": 0.9999,
            "bbox": [[x1, y1], [x2, y2], [x3, y3], [x4, y4]]
        },
        ...
    ],
    "source": "file",
    "elapse": {
        "detection": 2.24,
        "recognition": 0.87,
        "total": 4.32
    }
}
```

---

## 🔧 配置

### 初始化参数

```python
from copaw_ocr import OCRSkill

skill = OCRSkill(use_gpu=False)
```

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `use_gpu` | bool | False | 是否使用 GPU（暂不支持） |

---

## ⚠️ 注意事项

1. **首次使用** - 会自动下载模型（约 50MB），模型位置：`C:\Users\<用户名>\.rapidocr\`
2. **图片要求** - 支持 PNG、JPG、JPEG、BMP 格式，建议分辨率 1000px × 1000px 以上
3. **性能优化** - 批量处理时复用 `OCRSkill` 实例，避免重复初始化
4. **GPU 支持** - 当前版本仅支持 CPU，GPU 支持计划在后续版本推出

---

## 🐛 故障排查

### 问题 1：RapidOCR 未安装

**错误信息：**
```
RuntimeError: RapidOCR 未安装，请运行：pip install rapidocr_onnxruntime
```

**解决方案：**
```bash
pip install rapidocr_onnxruntime
```

### 问题 2：模型下载失败

**解决方案：**
1. 检查网络连接
2. 使用国内镜像：
   ```bash
   pip install -i https://pypi.tuna.tsinghua.edu.cn/simple rapidocr_onnxruntime
   ```

### 问题 3：截图失败

**错误信息：**
```
PIL ImageGrab 不可用
```

**解决方案：**
```bash
pip install Pillow
```

---

## 📚 文档

- **完整文档：** [SKILL.md](SKILL.md)
- **使用示例：** [examples/](examples/)
- **API 文档：** [docs/API.md](docs/API.md)

---

## 🤝 贡献

欢迎贡献代码、报告问题或提出建议！

1. Fork 本仓库
2. 创建功能分支 (`git checkout -b feature/amazing-feature`)
3. 提交更改 (`git commit -m 'Add some amazing feature'`)
4. 推送到分支 (`git push origin feature/amazing-feature`)
5. 创建 Pull Request

---

## 📄 许可证

本项目采用 MIT 许可证 - 详见 [LICENSE](LICENSE) 文件。

---

## 🙏 致谢

- [RapidOCR](https://github.com/RapidAI/RapidOCR) - 高性能 OCR 引擎
- [CoPaw](https://github.com/agentscope-ai/CoPaw) - AI Agent 框架

---

## 📞 联系方式

- **作者：** 老 K
- **GitHub：** https://github.com/lcq225
- **项目地址：** https://github.com/lcq225/copaw-ocr-skill

---

## 🎊 星标支持

如果这个项目对你有帮助，请给我一个 ⭐️！

---

**版本：** 1.0.0
**最后更新：** 2026-04-11
