phanghonghao PDF Reader Skill (PyMuPDF)
Use PyMuPDF (import fitz) to read PDF files. Supports 3 extraction modes with increasing fidelity. Handles Chinese text, multi-page PDFs, and image-based PDFs.
When to Use
- Any time you need to read a .pdf file — always use this instead of the native Read tool
- User mentions: "read PDF", "读取PDF", "PDF内容", "提取PDF", "PDF text", "open PDF"
- User provides a file path ending in
.pdf - Any task requiring PDF content extraction
Extraction Modes
Choose the mode based on the downstream task:
| Mode | Method | Output | Best for |
|---|---|---|---|
| text (default) | get_text() |
Plain text | Simple reading, summarization |
| html | get_text("html") |
HTML with CSS formatting | High-fidelity intermediate format, preserving bold/italic/font size/color |
| dict | get_text("dict") |
Structured JSON-like dict | Maximum fidelity — font name, size, color, position, flags; ideal for PDF → .tex conversion |
Mode selection guide:
- Just need to read content? →
text - Need to preserve formatting (bold, italic, headings, tables)? →
html - Converting PDF to .tex/.docx and need font size / layout info? →
dict - Not sure? → Use
dict(most complete, can derive everything else)
Implementation
Step 1: Check PyMuPDF Installation
python -m pip install PyMuPDF 2>&1 | tail -3
Step 2: Extract PDF Content
Always set PYTHONIOENCODING=utf-8 to avoid GBK encoding issues on Windows.
Mode: text (default — plain text extraction)
PYTHONIOENCODING=utf-8 python -c "
import fitz, sys
pdf_path = sys.argv[1]
doc = fitz.open(pdf_path)
print(f'Total pages: {len(doc)}')
for page in doc:
text = page.get_text()
if text.strip():
print(f'--- Page {page.number + 1} ---')
print(text)
else:
print(f'--- Page {page.number + 1}: [empty/image-only] ---')
doc.close()
" "<PDF_PATH>"
With page range:
PYTHONIOENCODING=utf-8 python -c "
import fitz, sys
pdf_path = sys.argv[1]
start, end = int(sys.argv[2]) - 1, int(sys.argv[3])
doc = fitz.open(pdf_path)
print(f'Total pages: {len(doc)}, extracting pages {start+1}-{end}')
for i in range(start, min(end, len(doc))):
text = doc[i].get_text()
if text.strip():
print(f'--- Page {i + 1} ---')
print(text)
else:
print(f'--- Page {i + 1}: [empty/image-only] ---')
doc.close()
" "<PDF_PATH>" "<START>" "<END>"
Mode: html (high-fidelity HTML with CSS formatting)
Outputs HTML preserving bold, italic, font family, font size, text color, and paragraph structure. Ideal as an intermediate format before converting to .tex or .docx.
PYTHONIOENCODING=utf-8 python -c "
import fitz, sys
pdf_path = sys.argv[1]
out_path = sys.argv[2] if len(sys.argv) > 2 else pdf_path.rsplit('.', 1)[0] + '.html'
doc = fitz.open(pdf_path)
with open(out_path, 'w', encoding='utf-8') as f:
f.write('<html><head><meta charset=\"utf-8\"><style>body{font-family:sans-serif;}</style></head><body>\n')
for page in doc:
html = page.get_text('html')
f.write(html + '\n')
f.write('</body></html>')
print(f'Exported HTML: {out_path} ({len(doc)} pages)')
doc.close()
" "<PDF_PATH>" "<OUTPUT_HTML_PATH>"
<OUTPUT_HTML_PATH> is optional — defaults to same name as PDF with .html extension.
To page range:
PYTHONIOENCODING=utf-8 python -c "
import fitz, sys
pdf_path = sys.argv[1]
start, end = int(sys.argv[2]) - 1, int(sys.argv[3])
out_path = sys.argv[4] if len(sys.argv) > 4 else pdf_path.rsplit('.', 1)[0] + '.html'
doc = fitz.open(pdf_path)
with open(out_path, 'w', encoding='utf-8') as f:
f.write('<html><head><meta charset=\"utf-8\"><style>body{font-family:sans-serif;}</style></head><body>\n')
for i in range(start, min(end, len(doc))):
f.write(doc[i].get_text('html') + '\n')
f.write('</body></html>')
print(f'Exported HTML: {out_path} (pages {start+1}-{min(end, len(doc))})')
doc.close()
" "<PDF_PATH>" "<START>" "<END>" "<OUTPUT_HTML_PATH>"
Mode: dict (maximum fidelity — structured data with font metadata)
Outputs a structured summary of every text span, including font name, font size (pt), text color, bold/italic flags, and position (x, y). This is the best mode for PDF → LaTeX conversion because font sizes can be mapped to heading levels.
PYTHONIOENCODING=utf-8 python -c "
import fitz, json, sys
pdf_path = sys.argv[1]
start = int(sys.argv[2]) - 1 if len(sys.argv) > 2 else 0
end = int(sys.argv[3]) if len(sys.argv) > 3 else 999999
doc = fitz.open(pdf_path)
total = len(doc)
end = min(end, total)
print(f'Total pages: {total}, extracting pages {start+1}-{end} (dict mode)')
print('=' * 60)
for i in range(start, end):
page = doc[i]
data = page.get_text('dict')
print(f'\n--- Page {i + 1} (size: {page.rect.width:.0f} x {page.rect.height:.0f} pt) ---')
for block in data['blocks']:
if block['type'] == 0: # text block
for line in block['lines']:
for span in line['spans']:
flags = span['flags']
bold = bool(flags & (1 << 4))
italic = bool(flags & (1 << 1))
size = span['size']
font = span['font']
color = span['color']
text = span['text'].strip()
if not text:
continue
origin = span['origin']
# Print with metadata annotations
attrs = []
if bold: attrs.append('bold')
if italic: attrs.append('italic')
if size > 14: attrs.append(f'HEADING?({size:.1f}pt)')
elif size > 12: attrs.append(f'subtitle?({size:.1f}pt)')
attr_str = f' [{\" \".join(attrs)}]' if attrs else ''
print(f' L{origin[1]:6.1f} {size:5.1f}pt {font:20s} {text}{attr_str}')
elif block['type'] == 1: # image block
print(f' [IMAGE {block[\"width\"]}x{block[\"height\"]} at ({block[\"bbox\"][0]:.0f},{block[\"bbox\"][1]:.0f})]')
doc.close()
" "<PDF_PATH>" "<START>" "<END>"
This prints a compact, human-readable summary like:
--- Page 1 (size: 595 x 842 pt) ---
L 56.0 24.0pt SimHei 第一章 绪论 [bold HEADING?(24.0pt)]
L 82.0 12.0pt SimSun 本文研究了...
L 98.0 12.0pt TimesNewRoman E = mc^2 [italic]
[IMAGE 400x300 at (100,200)]
To save full dict as JSON file (for programmatic downstream use):
PYTHONIOENCODING=utf-8 python -c "
import fitz, json, sys
pdf_path = sys.argv[1]
out_path = sys.argv[2] if len(sys.argv) > 2 else pdf_path.rsplit('.', 1)[0] + '.dict.json'
doc = fitz.open(pdf_path)
result = {'pages': [], 'total_pages': len(doc)}
for page in doc:
data = page.get_text('dict')
result['pages'].append(data)
doc.close()
with open(out_path, 'w', encoding='utf-8') as f:
json.dump(result, f, ensure_ascii=False, indent=2)
print(f'Saved dict JSON: {out_path} ({len(result[\"pages\"])} pages)')
" "<PDF_PATH>" "<OUTPUT_JSON_PATH>"
Step 3: Handle Image-Only PDFs
If text extraction returns empty/pages show [empty/image-only], the PDF is likely a scanned document:
This PDF appears to be an image-based (scanned) document. Text extraction returned empty. To extract content, you would need OCR tools like
pytesseract+pdf2image, orpaddleocr.
Rules
- Always use
PYTHONIOENCODING=utf-8— Windows defaults to GBK which fails on Unicode characters - Always use
python -m pip install(not barepip) — ensures installation into the correct venv - Use
python -cwith the script inline — no need to create temporary .py files - Pass PDF path as sys.argv[1] — avoids shell quoting issues with paths containing spaces or Chinese characters
- Do NOT use the native Read tool for PDF files — this skill replaces it entirely
- Default to
dictmode when the user needs high fidelity, format preservation, or PDF → LaTeX conversion htmlmode writes to file (not stdout) — HTML output is too large for terminal display; always save to.htmlfiledictmode prints a compact summary to stdout by default; use the JSON variant to save full structured data to.dict.jsonfile