ccy-ocr-local

本技能用于本地离线 OCR 与图表结构化识别。默认只处理本机文件，不上传图片，不调用外部 API。

什么时候使用

• 用户给出本机图片、截图、扫描件，要求识别文字
• 用户给出图表图片，要求提取标题、标签、数值或粗略结构化数据
• 需要批量 OCR 多张图片，并保存 txt/json/tsv 结果

快速路径

技能目录：skills/ccy-ocr-local/

普通 OCR

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 ：目录批处理并生成 manifest.json

JSON 输出会包含 avg_conf、low_conf_words、quality_warning 和 suggestions，用于判断是否需要重跑或人工复核。

示例：

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

图表识别

python3 skills/ccy-ocr-local/scripts/chart_ocr.py <image_path> --chart-type auto --json

支持 auto | pie | bar | line | table | dashboard。

示例：

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

检查语言包：

tesseract --list-langs

如果 tesseract 不在 PATH，可用：

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. 建真实样本集

把实际会遇到的图片按类型放到固定目录，例如：

skills/ccy-ocr-local/assets/eval/
├── text/          # 普通文档、截图、票据、标签
├── label/         # 短文本标签、产品标签、物流标签
├── chart-bar/     # 柱状图
├── chart-line/    # 折线图
├── chart-pie/     # 饼图
└── dashboard/     # 多图表看板

每张图片旁边放一个同名 .expected.json，记录人工校验后的期望结果。建议字段：

{
  "type": "text",
  "lang": "chi_sim+eng",
  "expected_text": "人工校验后的完整文字",
  "important_terms": ["供应商", "数量", "软头镊子"],
  "expected_numbers": [123, 45.6]
}

图表样本建议记录：

{
  "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：建议重跑参数

低质量时优先重跑：

python3 skills/ccy-ocr-local/scripts/local_ocr.py image.png \
  --lang chi_sim+eng \
  --autorotate \
  --multi-variant \
  --mode accurate \
  --json

标签、票据、短文本图片加：

--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. 每次提升后都跑回归

修改代码或参数后至少运行：

python3 skills/ccy-ocr-local/scripts/regression.py
python3 skills/ccy-ocr-local/scripts/test_chart_ocr.py

如果增加了真实样本集，建议再补一个专门的 eval 脚本，输出每次修改前后的准确率变化。只有评测变好，才算真正提升准确率。

回归验证

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

from scripts.chart_ocr import ChartOCR

chart_ocr = ChartOCR(lang="chi_sim+eng")
result = chart_ocr.extract_chart_data("chart.png", ["auto"])
print(result)