OcrCN

ocrCN — Multi-Platform Chinese OCR Skill

Overview

Extract text from images and documents with Chinese-optimized OCR. 5 backends, all work in China.

#	Backend	Cost	Key strength
1	PaddleOCR (default)	Free	Best Chinese accuracy, local, offline
2	Baidu AI OCR	~0.004 RMB/call	Specialized doc types (ID cards, invoices)
3	Tencent Cloud OCR	~0.01 RMB/call	Smart structural analysis, table recognition
4	Alibaba Cloud OCR	~0.01 RMB/call	DocMind layout analysis, complex documents
5	EasyOCR	Free	Multilingual, simple setup, offline

Cross-platform: Windows, macOS, Linux

When to Use This Skill

Automatically activate this skill when:

• User wants to extract text from an image (Chinese, English, or mixed)
• User needs OCR on screenshots, scanned documents, or photos
• Extracting Chinese text from PDFs, receipts, invoices, ID cards, or business licenses
• Recognizing handwriting, table data, or structured forms
• User mentions any of: OCR, text recognition, 文字识别, 图像识别, 图片转文字, PaddleOCR, Baidu OCR, 百度OCR, Tencent OCR, 腾讯OCR, Alibaba OCR, 阿里OCR, EasyOCR
• Any task where extracting Chinese text from images would be helpful

Workflow

Step 1 — Understand the request

Clarify what the user needs:

• Source: single image, batch of images, PDF, or screenshot?
• Content type: printed text, handwriting, table, form, ID card, invoice?
• Language: Chinese only, Chinese + English mixed, or multilingual?
• Output format: plain text, JSON with coordinates, or markdown table?

Step 2 — Pick a backend

Choose based on the use case (see Backend Selection Guide). Default to PaddleOCR (local, free, best Chinese accuracy) if unsure. Mention your choice.

Step 3 — Run OCR

python skills/ocrCN/scripts/ocr.py "image.png"
# or with options
python skills/ocrCN/scripts/ocr.py --platform baidu --type id_card "id_card.jpg"

Step 4 — Report

Present the extracted text clearly. For structured documents, preserve the layout. For tables, output as markdown table.

Backend Selection Guide

Quick Pick

Use case	Backend	Why
Default / general	paddle	Best Chinese accuracy, free, offline
ID card / 身份证	baidu	Specialized model, structured output
Invoice / 发票	baidu	VAT invoice fields auto-extracted
Business license / 营业执照	baidu	Unified social credit code parsing
Bank card / 银行卡	baidu	Card number recognition
Table / 表格	tencent	Smart table structure detection
Complex layout	ali	DocMind: paragraphs, tables, figures
Handwriting / 手写	paddle	Best handwriting model
Multilingual	easyocr	80+ languages, simple API
Batch processing	paddle	Local, no API cost
PDF documents	paddle	Direct PDF processing
License plate / 车牌	baidu	Specialized model
Seal/stamp / 印章	baidu	Red stamp detection and recognition
Cost-sensitive	paddle	Completely free, unlimited calls

Full Capability Comparison

Capability	PaddleOCR	Baidu AI	Tencent Cloud	Alibaba Cloud	EasyOCR
Cost (per 1K calls)	Free	~4元	~10元	~10元	Free
Chinese accuracy	⭐⭐⭐⭐⭐	⭐⭐⭐⭐⭐	⭐⭐⭐⭐	⭐⭐⭐⭐	⭐⭐⭐
English accuracy	⭐⭐⭐⭐	⭐⭐⭐⭐	⭐⭐⭐⭐	⭐⭐⭐⭐	⭐⭐⭐⭐
Handwriting	✅ Best	✅	✅	✅	⚠️ Limited
Vertical text	✅	✅	✅	✅	⚠️ Limited
Table recognition	✅	✅	✅ Smart	✅ DocMind	❌
PDF input	✅	❌	✅	✅	❌
Structured output	JSON+bbox	JSON+fields	JSON+structure	JSON+layout	Text+bbox
Specialized models	15+	50+	20+	10+	General only
Batch processing	✅	✅	✅	✅	✅
Offline	✅	❌	❌	❌	✅
GPU acceleration	✅ CUDA	Cloud	Cloud	Cloud	✅ CUDA
Setup difficulty	Medium	Easy	Medium	Medium	Easy
API key	None	BAIDU_*	TENCENT_*	ALIBABA_*	None
Max image size	Unlimited	4 MB	7 MB	20 MB	Unlimited

Platform Details

1. PaddleOCR (Default — Free, Local)

Baidu's open-source OCR engine. The gold standard for Chinese OCR. No API key, no internet required, no usage limits.

Key features:

• 15+ specialized models: text detection, recognition, table, formula, seal
• PP-OCRv5: state-of-the-art Chinese + English
• GPU acceleration via CUDA
• PDF and image input
• JSON output with bounding boxes and confidence scores

Installation:

pip install paddlepaddle paddleocr

Best for: General Chinese OCR, handwriting, batch processing, privacy-sensitive documents.

2. Baidu AI OCR (Cloud API)

Baidu's cloud OCR service with 50+ specialized models for Chinese document types.

Specialized models include:

• ID card (身份证), business license (营业执照), VAT invoice (增值税发票)
• Bank card (银行卡), driver's license (驾驶证), vehicle license (行驶证)
• Table recognition, seal/stamp recognition, license plate
• Handwriting, formula, form fields

Installation:

pip install requests

Best for: Structured documents (ID cards, invoices), when specialized field extraction is needed.

3. Tencent Cloud OCR (Cloud API)

Tencent's OCR with smart structural analysis — auto-detects tables, forms, paragraphs.

Installation:

pip install tencentcloud-sdk-python-ocr

Best for: Complex forms, smart table extraction, mixed content documents.

4. Alibaba Cloud OCR (Cloud API)

Alibaba's DocMind service — document layout analysis that separates text, tables, and figures.

Installation:

pip install alibabacloud_ocr_api20210707

Best for: Complex multi-column layouts, magazines, academic papers, mixed text/table/figure documents.

5. EasyOCR (Free, Local)

General-purpose multilingual OCR. Simpler than PaddleOCR but less accurate for Chinese.

Installation:

pip install easyocr

Best for: Quick multilingual needs, simple documents, when PaddleOCR setup is too heavy.

Usage

Basic Usage

# Default (PaddleOCR, free, local)
python skills/ocrCN/scripts/ocr.py image.png

# Output to file
python skills/ocrCN/scripts/ocr.py image.png -o result.txt

# JSON output with bounding boxes
python skills/ocrCN/scripts/ocr.py --format json image.png

# Specify language
python skills/ocrCN/scripts/ocr.py --lang ch image.png
python skills/ocrCN/scripts/ocr.py --lang ch_en image.png

Cloud Backends

# Baidu AI — ID card recognition
BAIDU_APP_ID="xxx" BAIDU_API_KEY="xxx" BAIDU_SECRET_KEY="xxx" \
python skills/ocrCN/scripts/ocr.py --platform baidu --type id_card id_card.jpg

# Baidu AI — VAT invoice
BAIDU_APP_ID="xxx" BAIDU_API_KEY="xxx" BAIDU_SECRET_KEY="xxx" \
python skills/ocrCN/scripts/ocr.py --platform baidu --type invoice invoice.jpg

# Tencent Cloud — table recognition
TENCENT_SECRET_ID="xxx" TENCENT_SECRET_KEY="xxx" \
python skills/ocrCN/scripts/ocr.py --platform tencent --type table form.png

# Alibaba Cloud — layout analysis
ALIBABA_ACCESS_KEY_ID="xxx" ALIBABA_ACCESS_KEY_SECRET="xxx" \
python skills/ocrCN/scripts/ocr.py --platform ali --layout document.png

# EasyOCR — multilingual
python skills/ocrCN/scripts/ocr.py --platform easyocr --lang ch_sim image.png

Advanced Options

# Handwriting recognition (PaddleOCR)
python skills/ocrCN/scripts/ocr.py --handwriting handwritten.jpg

# Table extraction (PaddleOCR)
python skills/ocrCN/scripts/ocr.py --table table.png

# Batch processing
python skills/ocrCN/scripts/ocr.py images/*.png -o results/

# PDF processing (PaddleOCR)
python skills/ocrCN/scripts/ocr.py document.pdf

# Confidence threshold
python skills/ocrCN/scripts/ocr.py --min-confidence 0.8 image.png

# Visualize results (draw bounding boxes on output image)
python skills/ocrCN/scripts/ocr.py --visualize image.png -o result.png

# Dry run (preview without processing)
python skills/ocrCN/scripts/ocr.py --dry-run image.png

# List all options
python skills/ocrCN/scripts/ocr.py --list

Doc Types (Baidu AI Specialized Models)

When using --platform baidu --type <type>, the following specialized models are available:

Type	Description	Returns
general	General text (default)	Text + confidence
id_card	身份证	Name, ID number, address, photo fields
invoice	增值税发票	Invoice code, amount, date, seller/buyer
business_license	营业执照	Company name, legal rep, registered capital
bank_card	银行卡	Card number, bank name
driver_license	驾驶证	Name, license number, vehicle type
vehicle_license	行驶证	Plate number, vehicle model, VIN
table	表格识别	Structured table as JSON/CSV
seal	印章识别	Seal text content
license_plate	车牌识别	Plate number, color
form	表单识别	Key-value pairs from forms
handwriting	手写识别	Handwritten text
formula	公式识别	LaTeX or plain formula text
receipt	票据识别	Receipt amount, date, merchant

Requirements

# Core (always needed)
pip install paddlepaddle paddleocr  # For PaddleOCR (default, free, best Chinese)

# Optional backends — install only what you use
pip install requests                          # Baidu AI
pip install tencentcloud-sdk-python-ocr       # Tencent Cloud
pip install alibabacloud_ocr_api20210707      # Alibaba Cloud
pip install easyocr                           # EasyOCR

Environment Variables

# Global defaults (optional)
export OCR_BACKEND="paddle"
export OCR_LANG="ch"

# Baidu AI OCR
export BAIDU_APP_ID="your_app_id"
export BAIDU_API_KEY="your_api_key"
export BAIDU_SECRET_KEY="your_secret_key"

# Tencent Cloud OCR
export TENCENT_SECRET_ID="your_secret_id"
export TENCENT_SECRET_KEY="your_secret_key"

# Alibaba Cloud OCR (DocMind)
export ALIBABA_ACCESS_KEY_ID="your_access_key_id"
export ALIBABA_ACCESS_KEY_SECRET="your_access_key_secret"

# PaddleOCR (optional)
export PADDLE_DEVICE="cpu"       # cpu or gpu
export PADDLE_LANG="ch"          # ch, en, ch_en

Get API Keys:

• Baidu AI: https://console.bce.baidu.com/ai/#/ai/ocr/overview
• Tencent Cloud: https://console.cloud.tencent.com/ocr
• Alibaba Cloud: https://ocr.console.aliyun.com/
• PaddleOCR: https://github.com/PaddlePaddle/PaddleOCR (open source, no key needed)
• EasyOCR: https://github.com/JaidedAI/EasyOCR (open source, no key needed)

Config File (Optional)

Create ~/.ocrCN.json for personal defaults, or .ocrCN.json in a project directory:

{
  "backend": "paddle",
  "lang": "ch",
  "min_confidence": 0.8
}

Priority (highest first):

1. CLI arguments (--platform, --lang, --type)
2. Project config (.ocrCN.json in current directory)
3. User config (~/.ocrCN.json)
4. Environment variables (OCR_BACKEND, OCR_LANG)
5. Built-in defaults

Examples

Quick Text Extraction (Free, Local)

python skills/ocrCN/scripts/ocr.py screenshot.png
# → 今天天气真好，适合出去走走。
#   从明天开始，新一轮冷空气将影响我国大部分地区。

Chinese + English Mixed

python skills/ocrCN/scripts/ocr.py --lang ch_en mixed_text.png
# → 我们使用 Python 3.11 和 PyTorch 2.0 进行模型训练。
#   The BLEU score reached 42.8 on the WMT22 test set.

ID Card Recognition (Baidu AI)

BAIDU_APP_ID="xxx" BAIDU_API_KEY="xxx" BAIDU_SECRET_KEY="xxx" \
python skills/ocrCN/scripts/ocr.py --platform baidu --type id_card shenfenzheng.jpg
# → 姓名: 张三
#   性别: 男
#   民族: 汉
#   出生: 1990-01-15
#   住址: 北京市海淀区中关村大街1号
#   公民身份号码: 11010819900115XXXX

Invoice Data Extraction (Baidu AI)

BAIDU_APP_ID="xxx" BAIDU_API_KEY="xxx" BAIDU_SECRET_KEY="xxx" \
python skills/ocrCN/scripts/ocr.py --platform baidu --type invoice fapiao.jpg
# → 发票代码: 011001900111
#   发票号码: 12345678
#   开票日期: 2026-07-09
#   价税合计: ¥1,234.56
#   销售方名称: 北京科技有限公司

Table to Markdown (Tencent Cloud)

TENCENT_SECRET_ID="xxx" TENCENT_SECRET_KEY="xxx" \
python skills/ocrCN/scripts/ocr.py --platform tencent --type table --format markdown table.png
# → | 姓名 | 部门 | 职位 | 入职日期 |
#   |------|------|------|----------|
#   | 张三 | 研发部 | 工程师 | 2020-03-15 |
#   | 李四 | 产品部 | 经理 | 2019-07-01 |

Complex Document Layout (Alibaba DocMind)

ALIBABA_ACCESS_KEY_ID="xxx" ALIBABA_ACCESS_KEY_SECRET="xxx" \
python skills/ocrCN/scripts/ocr.py --platform ali --layout paper.png
# → [Paragraph] Introduction
#   Recent advances in natural language processing...
#   [Table 1] Model comparison results
#   | Model | BLEU | Speed |
#   ...
#   [Figure 1] Architecture overview (omitted)

Handwriting Recognition (PaddleOCR)

python skills/ocrCN/scripts/ocr.py --handwriting handwritten_note.jpg
# → 今天下午三点开会，记得带笔记本。
#   老板说要讨论下个季度的销售目标。

Batch Process with Visualize

python skills/ocrCN/scripts/ocr.py --visualize screenshots/*.png -o results/
# Processes each image and saves:
#   results/screenshot1.png (with bounding boxes)
#   results/screenshot1.txt (extracted text)
#   results/screenshot2.png
#   results/screenshot2.txt

PDF to Text (PaddleOCR)

python skills/ocrCN/scripts/ocr.py contract.pdf -o contract.txt
# Extracts text from all pages of the PDF

Agent-Native CLI Reference

ocrCN follows the agent-native-design contract. It serves humans (readable terminal output), AI agents (structured JSON on stdout), and orchestrators (distinct exit codes) simultaneously.

JSON Mode

# Explicit JSON mode
python skills/ocrCN/scripts/ocr.py --format json image.png

# Auto-detect: pipe to jq → JSON automatically
python skills/ocrCN/scripts/ocr.py --list | jq .data.backends[0].name

# Error envelope always structured
python skills/ocrCN/scripts/ocr.py --format json --platform baidu image.png
# → {"ok":false, "error":{"code":"auth_missing_env","message":"...","retryable":false,...}}

Output Envelope

// Success
{"ok":true, "data":{
  "text": "extracted text...",
  "blocks": [{"text":"...", "confidence":0.98, "bbox":[x1,y1,x2,y2,x3,y3,x4,y4]}],
  "stats": {"chars":123, "blocks":5, "lang":"ch", "time_ms": 450}
}, "meta":{"version":"1.0.0","schema_version":"1.0.0","timestamp":"...","ms":450}}

// Error
{"ok":false, "error":{"code":"file_not_found","message":"image.png does not exist","retryable":false,"field":"input"}, "meta":{...}}

Exit Codes

Code	Meaning	Agent action
0	Success	Parse data, proceed
1	Internal / runtime error	Report to user, do not retry
2	Validation / input error	Fix input, retry allowed
3	Auth / missing credentials	Ask user for API key, do not retry
4	Backend API error	Retry with backoff
5	File not found / unreadable	Fix path, retry allowed

Schema Introspection

ocr.py schema backends              # All 5 backends (compact by default)
ocr.py schema backends --full       # All fields per backend
ocr.py schema backends.baidu        # Single backend full detail
ocr.py schema doctypes              # All specialized doc types (Baidu)
ocr.py schema version               # Version info

Agent Compatibility Flags

# No-ops accepted for agent runtime compatibility
ocr.py --yes --no-input image.png