chem-pdf2ppt 2.0.0

package/README.md

@@ -0,0 +1,235 @@
+# PDF2PPT — 化学学术论文 → 演示文稿转换器
+
+将化学领域学术论文 PDF 转换为专业学术演示文稿。支持 **PPTX** 和 **HTML** 两种输出格式。
+
+## 核心特性
+
+- **论文化学类型自动识别**：实验化学 / 理论计算化学 / 实验+理论混合，自动匹配叙事结构
+- **双格式输出**：PPTX（python-pptx）和单文件 HTML（横向翻页，图片 base64 嵌入）
+- **化学领域深度适配**：催化、材料、有机合成、计算化学、电化学、能源、环境、辐射化学等
+- **智能内容生成**：从论文提取真实信息，不生成"请手动添加XX"占位符
+- **多策略图表提取**：矢量图聚类 + 嵌入式图片 + 整页渲染回退，兼容 PyMuPDF 1.19–1.23+
+- **错误追踪与报告**：全链路 JSON 报告（分析 → 提取 → 构建），Windows 编码安全
+- **4 套学术配色**：学术经典 / 分子科技 / 绿色化学 / Nature 风格
+- **7 种幻灯片类型**：封面、章节分隔、内容要点、图表说明（4 种布局）、数据表格、总结、致谢
+
+---
+
+## 安装
+
+```bash
+pip install -r requirements.txt
+```
+
+**依赖**：`pymupdf>=1.19.0` · `python-pptx>=0.6.23` · `pdfplumber>=0.10.0` · `Pillow>=10.0.0`
+
+`pdf2image` 可选（需系统安装 Poppler）。
+
+---
+
+## 快速开始
+
+### 完整工作流
+
+```bash
+# Step 1: 分析论文类型与结构
+python scripts/analyze_paper.py paper.pdf --json analysis.json
+
+# Step 2: 提取图表（多策略 + 自动回退）
+python scripts/extract_charts.py paper.pdf output/figures 300 --report
+
+# Step 3: 构建 PPTX 或 HTML
+python build_my_ppt.py
+```
+
+### PPTX 格式
+
+```python
+import sys
+sys.path.insert(0, 'scripts')
+from create_ppt import ChemistryPPT
+
+ppt = ChemistryPPT(theme='academic')
+
+ppt.add_title_slide(
+    title_cn='Ru₁/Cu 单原子合金高效电催化 CO₂ 还原',
+    title_en='Single-Atom Ru Alloyed with Cu for Efficient CO₂RR',
+    authors='Zhang, L. et al.',
+    journal='J. Am. Chem. Soc., 2024, 146, 12345',
+    doi='10.1021/jacs.4c01234'
+)
+
+ppt.add_section_slide('研究背景')
+ppt.add_content_slide(
+    title='电催化 CO₂ 还原的核心挑战',
+    bullets=[
+        'CO₂RR 产物分布广泛，选择性控制困难',
+        'Cu 基催化剂 C₂₊ FE 通常 < 50%',
+        '关键瓶颈：*CO 吸附能与 C-C 偶联动力学的矛盾'
+    ]
+)
+ppt.add_figure_slide(
+    title='HAADF-STEM 确认 Ru 单原子分散',
+    figure_path='figures/p3_fig1.png',
+    bullets=['亮点均匀分散，无团簇', 'EDS mapping 确认均匀分布'],
+    figure_label='Figure 1',
+    layout='figure_right'
+)
+ppt.add_table_slide(
+    title='催化性能对比',
+    headers=['催化剂', 'FE(C₂₊)%', 'j (mA/cm²)', '稳定性 (h)'],
+    rows=[['Ru₁/Cu', '82%', '300', '100'], ['Cu NPs', '45%', '150', '20']]
+)
+ppt.add_summary_slide(
+    title='全文总结',
+    bullets=['核心发现1', '核心发现2', '核心发现3']
+)
+ppt.add_thankyou_slide()
+
+ppt.save('output/presentation.pptx')
+ppt.save_report('output/presentation.pptx')  # 生成 JSON 构建报告
+```
+
+### HTML 格式
+
+```python
+import sys
+sys.path.insert(0, 'scripts')
+from generate_html import HtmlPPT
+
+html = HtmlPPT(title="学术报告", theme="molecular")
+
+# API 与 ChemistryPPT 完全一致
+html.add_title_slide("标题", title_en="Title", authors="...", journal="...")
+html.add_section_slide("第一部分")
+html.add_content_slide("要点标题", ["bullet 1", "bullet 2"])
+html.add_figure_slide("图表", figure_path="figures/fig1.png",
+                       bullets=["说明"], figure_label="Figure 1",
+                       layout="figure_right")
+html.add_summary_slide("总结", ["结论1", "结论2"])
+html.add_thankyou_slide()
+
+html.save('output/presentation.html')  # 单文件，可直接浏览器打开
+```
+
+**HTML 特性**：
+- 图片以 base64 嵌入，单文件零依赖
+- 横向翻页：键盘 ← → Home End、滚轮、触摸滑动、底部圆点导航
+- 页码追踪 + 键盘提示
+- 响应式设计，适配投影仪和移动端
+
+---
+
+## 配色主题
+
+| 主题 | PPTX 参数 | HTML 参数 | 适合 |
+|------|-----------|-----------|------|
+| 学术经典 | `theme="academic"` | `theme="academic"` | 通用化学（默认） |
+| 分子科技 | `theme="molecular"` | `theme="molecular"` | 计算化学/材料 |
+| 绿色化学 | `theme="green"` | `theme="green"` | 催化/能源/环境 |
+| Nature 风格 | `theme="nature"` | `theme="nature"` | CNS 期刊汇报 |
+
+---
+
+## 幻灯片类型
+
+| 方法 | PPTX | HTML | 用途 |
+|------|------|------|------|
+| `add_title_slide()` | ✓ | ✓ | 封面页（中英文标题、作者、期刊、DOI） |
+| `add_section_slide()` | ✓ | ✓ | 章节分隔页（深色背景） |
+| `add_content_slide()` | ✓ | ✓ | 文字要点页（标题 + bullets + 备注） |
+| `add_figure_slide()` | ✓ | ✓ | 图表+说明（4 种布局：right/top/left/full） |
+| `add_table_slide()` | ✓ | ✓ | 数据对比表（斑马纹、表头着色） |
+| `add_image_grid_slide()` | ✓ | — | 多图网格页 |
+| `add_summary_slide()` | ✓ | ✓ | 总结页（浅色背景） |
+| `add_thankyou_slide()` | ✓ | ✓ | 致谢/提问页 |
+
+---
+
+## 图表提取：多策略 + 版本兼容
+
+```
+策略 1: cluster_drawings() 默认容忍度 (3,3)
+   ↓ 结果 < 3
+策略 2: 多容忍度尝试 (6,6) → (10,10) → (15,15) → (20,20)
+   ↓
+策略 3: 提取嵌入式位图 (get_images)
+   ↓ 结果 < 3
+策略 4: 图页整页渲染回退
+```
+
+- 兼容 PyMuPDF 1.19+ (`get_drawings` 手动聚类) 和 1.23+ (`cluster_drawings`)
+- `--report` 输出 `extraction_report.json`（各策略提取详情）
+
+---
+
+## 错误处理与报告
+
+全链路 JSON 报告，便于自动化集成和问题诊断：
+
+| 阶段 | 报告文件 | 生成方式 |
+|------|---------|---------|
+| 论文分析 | `analysis.json` | `analyze_paper.py --json analysis.json` |
+| 图表提取 | `extraction_report.json` | `extract_charts.py --report` |
+| PPTX 构建 | `presentation_report.json` | `ppt.save_report("output.pptx")` |
+
+**Windows 编码安全**：所有脚本使用 `_safe_print()` 避免 GBK 编码崩溃。
+
+**常见问题自动诊断**：
+
+| 症状 | 可能原因 | 脚本输出 |
+|------|---------|---------|
+| 矢量图提取 0 个 | PyMuPDF < 1.23 或 PDF 渲染特殊 | 自动回退到 `get_drawings` 手动聚类 |
+| 图表总数仍不足 | 图片均为嵌入式位图 | 策略 3 自动覆盖 |
+| Windows `print` 崩溃 | Unicode 字符 (如 − ₂) | `_safe_print` 回退 ASCII |
+| 论文类型误判 | 参考文献含表征术语 | 加权检测 + confidence 标注 |
+| PPT 中图片缺失 | 图片路径不存在 | 记录到 `missing_images`，构建不中断 |
+
+---
+
+## 论文化学类型适配
+
+| 实验化学 | 理论计算化学 | 实验+理论混合 |
+|---------|------------|-------------|
+| 合成 → 表征 → 性能 → 机理 | 方法 → 模型 → 电子结构 → 能量 → 机理 | 实验 → 计算 → 互验 → 统一机理 |
+| 催化/材料/有机/能源 | DFT/MM/AIMD/电子结构 | 实验+DFT 联合 |
+
+详细模板见 `references/chemistry_templates.md`。
+
+---
+
+## 文件结构
+
+```
+PDF2PPT/
+├── SKILL.md                         # Skill 主文件
+├── README.md                        # 本文件
+├── requirements.txt
+├── assets/
+│   └── academic_template.html       # HTML PPT 模板（CSS + 翻页 JS）
+├── scripts/
+│   ├── create_ppt.py                # PPTX 构建器 (ChemistryPPT)
+│   ├── generate_html.py             # HTML 构建器 (HtmlPPT)
+│   ├── extract_charts.py            # 多策略图表提取
+│   ├── analyze_paper.py             # 论文分析 + 类型分类
+│   └── convert_to_images.py         # PDF 页面 → 图片
+├── references/
+│   ├── chemistry_templates.md       # 三种论文类型的逐页模板
+│   └── visual_style.md              # 学术 PPT 视觉设计规范
+└── examples/
+    └── example_usage.py             # 三种化学论文类型的完整示例
+```
+
+---
+
+## 兼容性
+
+- **OS**: macOS / Linux / Windows
+- **Python**: 3.8+
+- **PyMuPDF**: 1.19+（自动兼容新旧 API）
+- **环境**: Claude Code / Claude Desktop / Cursor / VS Code / 任何 Python 环境
+- **HTML 输出**: 任何现代浏览器（Chrome / Firefox / Edge / Safari）
+
+## 许可证
+
+MIT License

package/README_EN.md

@@ -0,0 +1,239 @@
+# PDF2PPT — Chemistry Academic Paper → Presentation Converter
+
+Convert chemistry academic paper PDFs into professional presentations for group meetings, defenses, and academic reports. Supports both **PPTX** and **HTML** output formats.
+
+## Key Features
+
+- **Automatic paper type recognition**: Experimental / Computational / Hybrid chemistry — auto-matched narrative structure
+- **Dual output formats**: PPTX (python-pptx) and single-file HTML (horizontal-slide, base64-embedded figures)
+- **Deep chemistry domain support**: Catalysis, materials, organic synthesis, computational chemistry, electrochemistry, energy, environmental, radiation chemistry, and more
+- **Intelligent content generation**: Extracts real information from papers — no "please fill in XX" placeholder content
+- **Multi-strategy figure extraction**: Vector clustering + embedded images + page rendering fallback, compatible with PyMuPDF 1.19–1.23+
+- **Error tracking & reporting**: Full-chain JSON reports (analysis → extraction → build), Windows encoding-safe
+- **4 academic color themes**: Academic Classic / Molecular Tech / Green Chemistry / Nature Style
+- **7 slide types**: Title, section divider, content, figure (4 layouts), data table, summary, thank you
+
+---
+
+## Installation
+
+```bash
+pip install -r requirements.txt
+```
+
+**Dependencies**: `pymupdf>=1.19.0` · `python-pptx>=0.6.23` · `pdfplumber>=0.10.0` · `Pillow>=10.0.0`
+
+`pdf2image` is optional (requires system Poppler installation).
+
+---
+
+## Quick Start
+
+### Complete Workflow
+
+```bash
+# Step 1: Analyze paper type and structure
+python scripts/analyze_paper.py paper.pdf --json analysis.json
+
+# Step 2: Extract figures (multi-strategy + auto-fallback)
+python scripts/extract_charts.py paper.pdf output/figures 300 --report
+
+# Step 3: Build PPTX or HTML
+python build_my_ppt.py
+```
+
+### PPTX Format
+
+```python
+import sys
+sys.path.insert(0, 'scripts')
+from create_ppt import ChemistryPPT
+
+ppt = ChemistryPPT(theme='academic')
+
+ppt.add_title_slide(
+    title_cn='Ru₁/Cu Single-Atom Alloy for Efficient CO₂ Electroreduction',
+    title_en='Single-Atom Ru Alloyed with Cu for Efficient CO₂RR',
+    authors='Zhang, L. et al.',
+    journal='J. Am. Chem. Soc., 2024, 146, 12345',
+    doi='10.1021/jacs.4c01234'
+)
+
+ppt.add_section_slide('Background')
+ppt.add_content_slide(
+    title='Core Challenge in Electrocatalytic CO₂ Reduction',
+    bullets=[
+        'CO₂RR produces diverse products — selectivity control is difficult',
+        'Cu-based catalysts achieve C₂₊ FE typically < 50%',
+        'Key bottleneck: conflicting demands on *CO binding and C-C coupling'
+    ]
+)
+ppt.add_figure_slide(
+    title='HAADF-STEM Confirms Single-Atom Ru Dispersion',
+    figure_path='figures/p3_fig1.png',
+    bullets=['Bright dots uniformly dispersed — no clusters', 'EDS mapping confirms uniformity'],
+    figure_label='Figure 1',
+    layout='figure_right'
+)
+ppt.add_table_slide(
+    title='Performance Comparison',
+    headers=['Catalyst', 'FE(C₂₊)%', 'j (mA/cm²)', 'Stability (h)'],
+    rows=[['Ru₁/Cu', '82%', '300', '100'], ['Cu NPs', '45%', '150', '20']]
+)
+ppt.add_summary_slide(
+    title='Summary',
+    bullets=['Finding 1', 'Finding 2', 'Finding 3']
+)
+ppt.add_thankyou_slide()
+
+ppt.save('output/presentation.pptx')
+ppt.save_report('output/presentation.pptx')  # JSON build report
+```
+
+### HTML Format
+
+```python
+import sys
+sys.path.insert(0, 'scripts')
+from generate_html import HtmlPPT
+
+html = HtmlPPT(title="Academic Report", theme="molecular")
+
+# API is identical to ChemistryPPT
+html.add_title_slide("Title", title_en="Title EN", authors="...", journal="...")
+html.add_section_slide("Part 1")
+html.add_content_slide("Key Point", ["bullet 1", "bullet 2"])
+html.add_figure_slide("Figure", figure_path="figures/fig1.png",
+                       bullets=["description"], figure_label="Figure 1",
+                       layout="figure_right")
+html.add_summary_slide("Summary", ["finding 1", "finding 2"])
+html.add_thankyou_slide()
+
+html.save('output/presentation.html')  # Single file, open directly in browser
+```
+
+**HTML features**:
+- Figures embedded as base64 — single file, zero dependencies
+- Horizontal navigation: keyboard ← → Home End, scroll wheel, touch swipe, dot navigation
+- Page counter + keyboard hints
+- Responsive design for projectors and mobile
+
+---
+
+## Color Themes
+
+| Theme | PPTX param | HTML param | Best for |
+|-------|-----------|------------|----------|
+| Academic Classic | `theme="academic"` | `theme="academic"` | General chemistry (default) |
+| Molecular Tech | `theme="molecular"` | `theme="molecular"` | Computational/materials |
+| Green Chemistry | `theme="green"` | `theme="green"` | Catalysis/energy/environment |
+| Nature Style | `theme="nature"` | `theme="nature"` | CNS journal presentations |
+
+---
+
+## Slide Types
+
+| Method | PPTX | HTML | Purpose |
+|--------|------|------|---------|
+| `add_title_slide()` | ✓ | ✓ | Cover: bilingual title, authors, journal, DOI |
+| `add_section_slide()` | ✓ | ✓ | Section divider (dark background) |
+| `add_content_slide()` | ✓ | ✓ | Text content: title + bullets + notes |
+| `add_figure_slide()` | ✓ | ✓ | Figure + explanation (4 layouts: right/top/left/full) |
+| `add_table_slide()` | ✓ | ✓ | Data comparison table (striped rows, colored header) |
+| `add_image_grid_slide()` | ✓ | — | Multi-image grid |
+| `add_summary_slide()` | ✓ | ✓ | Summary (light background) |
+| `add_thankyou_slide()` | ✓ | ✓ | Thank you / Q&A |
+
+---
+
+## Figure Extraction: Multi-Strategy + Version Compatibility
+
+```
+Strategy 1: cluster_drawings() default tolerance (3,3)
+   ↓ < 3 results
+Strategy 2: Multi-tolerance retry (6,6) → (10,10) → (15,15) → (20,20)
+   ↓
+Strategy 3: Extract embedded bitmaps (get_images)
+   ↓ < 3 results
+Strategy 4: Full-page rendering fallback for figure pages
+```
+
+- Compatible with PyMuPDF 1.19+ (`get_drawings` manual clustering) and 1.23+ (`cluster_drawings`)
+- `--report` outputs `extraction_report.json` (per-strategy details)
+
+---
+
+## Error Handling & Reports
+
+Full-chain JSON reports for workflow automation and diagnostics:
+
+| Stage | Report File | Generated By |
+|-------|------------|--------------|
+| Paper analysis | `analysis.json` | `analyze_paper.py --json analysis.json` |
+| Figure extraction | `extraction_report.json` | `extract_charts.py --report` |
+| PPTX build | `presentation_report.json` | `ppt.save_report("output.pptx")` |
+
+**Windows encoding safety**: All scripts use `_safe_print()` to prevent GBK encoding crashes.
+
+**Common issue diagnostics**:
+
+| Symptom | Likely Cause | Script Behavior |
+|---------|-------------|-----------------|
+| 0 vector figures extracted | PyMuPDF < 1.23 or special PDF rendering | Auto-fallback to `get_drawings` manual clustering |
+| Still too few figures total | All bitmaps | Strategy 3 auto-covers |
+| Windows `print` crash | Unicode chars (e.g. − ₂) | `_safe_print` fallback to ASCII |
+| Paper type misclassified | Characterization terms in references | Weighted detection + confidence annotation |
+| Images missing in PPT | Non-existent file paths | Recorded in `missing_images`, build continues |
+
+---
+
+## Paper Type Adaptations
+
+| Experimental Chemistry | Computational Chemistry | Experimental + Theoretical |
+|------------------------|------------------------|---------------------------|
+| Synthesis → Characterization → Performance → Mechanism | Method → Model → Electronic Structure → Energetics → Mechanism | Experiment → Computation → Cross-Validation → Unified Mechanism |
+| Catalysis / Materials / Organic / Energy | DFT / MM / AIMD / Electronic Structure | Experiment + DFT joint studies |
+
+Detailed templates in `references/chemistry_templates.md`.
+
+---
+
+## File Structure
+
+```
+PDF2PPT/
+├── SKILL.md                         # Skill main file (Chinese)
+├── SKILL_EN.md                      # Skill main file (English)
+├── README.md                        # This file (Chinese)
+├── README_EN.md                     # This file (English)
+├── requirements.txt
+├── assets/
+│   └── academic_template.html       # HTML PPT template (CSS + navigation JS)
+├── scripts/
+│   ├── create_ppt.py                # PPTX builder (ChemistryPPT)
+│   ├── generate_html.py             # HTML builder (HtmlPPT)
+│   ├── extract_charts.py            # Multi-strategy figure extraction
+│   ├── analyze_paper.py             # Paper analysis + type classification
+│   └── convert_to_images.py         # PDF page → image conversion
+├── references/
+│   ├── chemistry_templates.md       # Slide-by-slide templates for 3 paper types
+│   ├── chemistry_templates_en.md    # (English version)
+│   ├── visual_style.md              # Academic PPT visual design spec
+│   └── visual_style_en.md           # (English version)
+└── examples/
+    └── example_usage.py             # Complete examples for 3 chemistry paper types
+```
+
+---
+
+## Compatibility
+
+- **OS**: macOS / Linux / Windows
+- **Python**: 3.8+
+- **PyMuPDF**: 1.19+ (auto-detects and adapts API)
+- **Environment**: Claude Code / Claude Desktop / Cursor / VS Code / any Python environment
+- **HTML output**: Any modern browser (Chrome / Firefox / Edge / Safari)
+
+## License
+
+MIT License