本地 OCR / 图表识别技能。对本机图片做离线文字识别,支持截图、文档图片、扫描件、表格/图表图片中的中英文文本与图表数据提取;默认不上传文件、不依赖外部 API。
---
name: ccy-ocr-local
description: 本地 OCR / 图表识别技能。对本机图片做离线文字识别,支持截图、文档图片、扫描件、表格/图表图片中的中英文文本与图表数据提取;默认不上传文件、不依赖外部 API。
---
# ccy-ocr-local
本技能用于**本地离线 OCR 与图表结构化识别**。默认只处理本机文件,不上传图片,不调用外部 API。
## 什么时候使用
- 用户给出本机图片、截图、扫描件,要求识别文字
- 用户给出图表图片,要求提取标题、标签、数值或粗略结构化数据
- 需要批量 OCR 多张图片,并保存 txt/json/tsv 结果
## 快速路径
技能目录:`skills/ccy-ocr-local/`
### 普通 OCR
```bash
python3 skills/ccy-ocr-local/scripts/local_ocr.py <image_path> --lang chi_sim+eng
```
常用参数:
- `--json`:输出内容和元数据
- `--format tsv`:输出带坐标/置信度的 TSV
- `--autorotate`:自动尝试方向
- `--doc-hint label`:标签、票据、短文本图片优先用这个
- `--multi-variant`:多预处理候选搜索,慢一些但更稳
- `--mode accurate`:更适合追求准确率的单张图片
- `--batch --out-dir <dir>`:目录批处理并生成 `manifest.json`
JSON 输出会包含 `avg_conf`、`low_conf_words`、`quality_warning` 和 `suggestions`,用于判断是否需要重跑或人工复核。
示例:
```bash
python3 skills/ccy-ocr-local/scripts/local_ocr.py image.png --lang chi_sim+eng --autorotate --json
python3 skills/ccy-ocr-local/scripts/local_ocr.py images/ --batch --recursive --out-dir ocr-out --lang chi_sim+eng
```
### 图表识别
```bash
python3 skills/ccy-ocr-local/scripts/chart_ocr.py <image_path> --chart-type auto --json
```
支持 `auto | pie | bar | line | table | dashboard`。
示例:
```bash
python3 skills/ccy-ocr-local/scripts/chart_ocr.py chart.png --chart-type dashboard --json
python3 skills/ccy-ocr-local/scripts/chart_ocr.py chart.png --chart-type bar --extract-numbers --extract-labels --json
python3 skills/ccy-ocr-local/scripts/chart_ocr.py chart.png --chart-type auto --visualize --visualize-output chart_debug.png --json
```
`--visualize` 会生成调试标注图:灰框为候选区域,橙/红框为选中图表或 dashboard 子图区域。
## 依赖
- Python 3
- Tesseract 可执行文件
- Python 包:`pillow pytesseract opencv-python numpy`
- 中文识别需要 Tesseract 语言包 `chi_sim`;英文只需 `eng`
检查语言包:
```bash
tesseract --list-langs
```
如果 tesseract 不在 PATH,可用:
```bash
python3 skills/ccy-ocr-local/scripts/local_ocr.py image.png --tesseract-cmd /path/to/tesseract
```
或设置 `TESSERACT_CMD` 环境变量。
## 输出与判断
- 普通 OCR 输出以 Tesseract 结果为准;图片质量、字体、分辨率、语言包会显著影响效果。
- 图表识别是“OpenCV 结构线索 + OCR 文本”的规则/启发式提取,适合常见饼图、柱状图、折线图、表格和 dashboard 粗提取;不要把结果当作人工校验后的精确数据。
- 图表 JSON 会包含 `quality_notes`;如果提示低置信,优先查看 `--visualize` 调试图,并考虑裁剪图表主体或手动指定 `--chart-type`。
- 若结果差,优先尝试:`--autorotate`、`--multi-variant`、`--mode accurate`、提高图片分辨率、换 `--psm`、确认语言包。
## 持续提升准确率
如果要让这个技能在真实业务图片上越来越准,按下面顺序迭代。不要只凭单张样例调参,先建样本和评测。
### 1. 建真实样本集
把实际会遇到的图片按类型放到固定目录,例如:
```text
skills/ccy-ocr-local/assets/eval/
├── text/ # 普通文档、截图、票据、标签
├── label/ # 短文本标签、产品标签、物流标签
├── chart-bar/ # 柱状图
├── chart-line/ # 折线图
├── chart-pie/ # 饼图
└── dashboard/ # 多图表看板
```
每张图片旁边放一个同名 `.expected.json`,记录人工校验后的期望结果。建议字段:
```json
{
"type": "text",
"lang": "chi_sim+eng",
"expected_text": "人工校验后的完整文字",
"important_terms": ["供应商", "数量", "软头镊子"],
"expected_numbers": [123, 45.6]
}
```
图表样本建议记录:
```json
{
"type": "chart-bar",
"chart_type": "bar",
"title": "月度产量",
"labels": ["1月", "2月", "3月"],
"values": [120, 160, 150]
}
```
### 2. 固定评测指标
普通 OCR 建议看:
- 字符准确率:人工文本 vs OCR 文本
- 关键字段命中率:`important_terms` 是否识别出来
- 数字准确率:金额、数量、型号等是否识别正确
- 平均置信度:JSON 里的 `avg_conf`、`low_conf_words`
图表识别建议看:
- 图表类型准确率:`bar / line / pie / table / dashboard`
- 标题/图例命中率
- 数值误差:提取值和期望值的绝对/相对误差
- 区域检测是否正确:结合 `--visualize` 调试图人工抽检
### 3. 用质量字段决定是否重跑
普通 OCR 的 JSON 会输出:
- `avg_conf`:平均置信度,低于 55 通常要复核
- `low_conf_words`:低置信词数量,越多越不稳
- `quality_warning`:低质量原因
- `suggestions`:建议重跑参数
低质量时优先重跑:
```bash
python3 skills/ccy-ocr-local/scripts/local_ocr.py image.png \
--lang chi_sim+eng \
--autorotate \
--multi-variant \
--mode accurate \
--json
```
标签、票据、短文本图片加:
```bash
--doc-hint label
```
### 4. 按类型调参,不要全局乱改
推荐调参顺序:
1. 确认语言包:中文图片必须有 `chi_sim`,中英混排用 `chi_sim+eng`
2. 尝试 PSM:常用 `6`、`7`、`11`、`3`
3. 尝试预处理:`--multi-variant`、`--sharpen`、提高 `--min-edge`
4. 尝试旋转:`--autorotate --autorotate-strategy full`
5. 对稳定错字加入领域纠错:编辑 `DOMAIN_CORRECTIONS`
6. 对某类图片固定最佳参数:在调用侧按目录/文件名选择 `--doc-hint`、`--psm`、`--mode`
### 5. 图表准确率提升路径
图表识别优先这样做:
1. 先用 `--visualize` 确认图表区域是否选对
2. 区域错了:优化 `_find_chart_regions` / `_classify_region`
3. 类型错了:补关键词、线条/圆形/表格判定规则
4. 文本错了:优化标题、坐标轴、图例 OCR 配置
5. 数值错了:优先做几何反推,而不是只依赖 OCR
- 柱状图:检测柱子矩形高度 + 坐标轴刻度映射
- 折线图:检测折线点位 + 坐标轴刻度映射
- 饼图:检测扇区角度 + 图例/百分比匹配
### 6. 每次提升后都跑回归
修改代码或参数后至少运行:
```bash
python3 skills/ccy-ocr-local/scripts/regression.py
python3 skills/ccy-ocr-local/scripts/test_chart_ocr.py
```
如果增加了真实样本集,建议再补一个专门的 eval 脚本,输出每次修改前后的准确率变化。只有评测变好,才算真正提升准确率。
## 回归验证
```bash
python3 skills/ccy-ocr-local/scripts/regression.py
python3 skills/ccy-ocr-local/scripts/test_chart_ocr.py
```
## 目录导航
- `scripts/local_ocr.py`:通用离线 OCR CLI
- `scripts/chart_ocr.py`:图表识别 CLI 与 `ChartOCR` API
- `scripts/regression.py`:OCR 样例回归
- `scripts/test_chart_ocr.py`:图表识别回归
- `assets/`:样例图片
- `OCR-CONFIG.md` / `ROADMAP-*.md`:更细的配置与路线说明,需要时再读
## Python API
```python
from scripts.chart_ocr import ChartOCR
chart_ocr = ChartOCR(lang="chi_sim+eng")
result = chart_ocr.extract_chart_data("chart.png", ["auto"])
print(result)
```
don't have the plugin yet? install it then click "run inline in claude" again.