| name | ocr |
| description | Run PaddleOCR on images or PDFs to extract text. Use for textbook-problem screenshots, image-based PDF lecture slides, scanned exam papers, or any handwritten/printed material the user needs read into text. For PDFs, tries direct text extraction first and falls back to OCR only when the PDF is image-based. |
OCR (PaddleOCR)
Purpose
Convert images or PDFs into searchable text. Use this whenever:
- The user sends a screenshot of a textbook problem (often the case for 微观经济学 and 计量经济学 — those courses' Canvas assignments only reference textbook problems by chapter/page).
- A course PDF is image-based (scanned slides, lecture photos) and direct text extraction returns nothing.
- You want to learn from a course material before drafting an assignment — text-extracted PDFs and OCR'd images can both be read by Claude.
This skill wraps PaddleOCR with Chinese + English support and a smart-fallback PDF reader.
When to invoke
- Before drafting any assignment, OCR (or text-extract) the relevant course materials so that the assistant actually reads what the lecturer covered. For courses listed in
.claude/skills/canvas-study-agent/course_profiles.md, follow the per-course rules.
- Whenever the user uploads a screenshot relevant to coursework, run OCR on it before answering. Save the image into the assignment's
attachments/ directory and the text alongside it.
Tool
python .claude/skills/ocr/scripts/ocr.py <input> [--out <txt-path>] [--lang ch|en|chinese_cht|...] [--force]
<input> — a single image (.png, .jpg, .jpeg, .bmp, .tiff, .webp) or a PDF.--out — optional output .txt path. Defaults to <input>.ocr.txt next to the source.--lang — PaddleOCR language. Default ch (Chinese + English mixed).--force — re-OCR even if a cached .ocr.txt newer than the input exists.
Behavior:
- If the input is a PDF, the script tries PyMuPDF text extraction first. If that yields a reasonable amount of text, it uses that and skips OCR (fast and exact).
- If the PDF is image-based (no extractable text), each page is rasterized at 200 DPI and OCR'd page by page.
- If the input is an image, it is OCR'd directly.
- Results are written to
<input>.ocr.txt and also printed to stdout.
- Cache: if
<input>.ocr.txt exists and is newer than the input file, the script reuses it unless --force is passed.
The script prints clean text only, with each line on its own line. Page breaks in PDFs are marked with --- page N ---.
Saving user-shared screenshots
When the user pastes a screenshot in chat:
- The harness gives you a temp path. Copy or move the file into the relevant assignment's
attachments/ folder, naming it descriptively, e.g.:
workspace/courses/<course>/assignments/<assignment>/attachments/textbook_p142_problem3.png
- Run
ocr.py on that file. The text is saved next to the image as textbook_p142_problem3.png.ocr.txt.
- Read the OCR'd text alongside the image (you can also see the image visually).
- If the OCR text is garbled or incomplete (handwriting, math formulas, low resolution), tell the user — don't silently work from a bad transcription.
Handling math, formulas, tables
PaddleOCR is good at printed Chinese + English text. It is not reliable for:
- Heavy math notation (subscripts, integrals, matrices) — read those visually from the image and write LaTeX yourself.
- Hand-drawn diagrams.
- Multi-column tables — column order may be lost.
When OCR is unreliable, say so and prefer your own visual reading of the image.
Install
PaddleOCR is heavy (~1.5 GB models on first run). The dependencies are listed under "OCR skill" in requirements.txt:
pip install paddleocr paddlepaddle PyMuPDF pillow
On Apple Silicon, paddlepaddle ships CPU wheels via pip; first OCR run will download model files automatically into ~/.paddleocr/.
If paddleocr is not installed, ocr.py falls back to PDF text extraction only and prints a clear error when asked to OCR an image.
