ocr

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:

1. 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).
2. A course PDF is image-based (scanned slides, lecture photos) and direct text extraction returns nothing.
3. 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:

1. 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).
2. If the PDF is image-based (no extractable text), each page is rasterized at 200 DPI and OCR'd page by page.
3. If the input is an image, it is OCR'd directly.
4. Results are written to <input>.ocr.txt and also printed to stdout.
5. 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:

1. 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
   

2. Run ocr.py on that file. The text is saved next to the image as textbook_p142_problem3.png.ocr.txt.
3. Read the OCR'd text alongside the image (you can also see the image visually).
4. 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.