---
name: add-figures
description: Extracts important figures and diagrams from papers and adds them to reports. Use when the user wants to enhance a report with visual elements from the original paper.
---

# 図表追加スキル

論文分析レポートに、元論文および参照論文から重要な図表（Figure/Table）を抽出・追加します。

## 概要

このスキルは以下を行います：

1. 既存レポートの分析
2. 元論文から重要な図表を特定・抽出
3. **参照論文から重要な図表を特定・抽出**
4. 図表の保存
5. レポートへの図表埋め込み
6. 図表の説明文を追加

**重要**: このスキルは元論文だけでなく、レポートで言及されている参照論文からも図表を抽出します。

---

## Python モジュール

このスキルは `src/figure_extractor.py` モジュールを使用します。

### CLI の使用方法

```bash
# 基本的な使用方法（自動検出モード）
uv run figure-extractor https://arxiv.org/abs/2401.12345

# 特定の図のみ抽出
uv run figure-extractor 2401.12345 --figures 1,2,3

# 埋め込み画像を全て抽出
uv run figure-extractor 2401.12345 --mode images

# 特定のページを画像として抽出
uv run figure-extractor 2401.12345 --mode pages --pages 2,5,8

# Table を除外
uv run figure-extractor 2401.12345 --no-tables

# ズーム倍率を変更（高解像度）
uv run figure-extractor 2401.12345 --zoom 3.0
```

### Python API の使用方法

```python
from pathlib import Path
from src.figure_extractor import (
    FigureExtractor,
    generate_markdown_embed,
    update_report_with_figures,
)
from src.arxiv_helper import download_pdf, extract_arxiv_id

# arXiv ID を抽出して PDF をダウンロード
arxiv_id = extract_arxiv_id("https://arxiv.org/abs/2401.12345")
pdf_path = download_pdf(arxiv_id, output_dir="downloads")

# 図表を抽出
extractor = FigureExtractor(output_dir="reports/figures", zoom=2.0)

# 方法1: 自動検出で Figure/Table を抽出
result = extractor.extract_from_pdf(
    pdf_path,
    arxiv_id,
    figure_numbers=[1, 2, 3],  # 特定の図のみ
    extract_tables=True,
)

# 方法2: 埋め込み画像を全て抽出
result = extractor.extract_embedded_images(pdf_path, arxiv_id)

# 方法3: 特定のページを画像として抽出
result = extractor.extract_page_as_image(pdf_path, arxiv_id, page_numbers=[2, 5, 8])

# 結果を確認
print(f"Extracted {len(result.figures)} figures")
for fig in result.figures:
    print(f"  - {fig.figure_id}: {fig.image_path}")

# Markdown 埋め込みコードを生成
for fig in result.figures:
    print(generate_markdown_embed(fig, relative_to=Path("reports")))

# レポートに図表を自動挿入
updated_content = update_report_with_figures(
    "reports/2401.12345_report.md",
    result,
    insert_positions={
        "fig1": "### 3.2 アーキテクチャ",
        "table1": "### 5.1 主要な結果",
    },
)
```

---

## ワークフロー

### 1. 対象レポートと論文の特定

#### 1.1 レポートの読み込み

```bash
# 最新のレポートを確認
ls -lt reports/*.md | head -5
```

対象レポートを `Read` ツールで読み込み、以下を把握：
- 論文の arXiv ID
- レポートの構造
- 既に言及されている Figure/Table

#### 1.2 元論文の取得と図表抽出

```bash
# PDF をダウンロードして図表を抽出
uv run figure-extractor <arxiv_id>
```

### 2. 重要な図表の特定

#### 2.1 論文全体をスキャン

`Read` ツールで PDF を読み取り、全ての Figure と Table を特定：

```markdown
## 論文内の図表一覧

| 番号 | 種類 | ページ | タイトル/キャプション | 重要度 |
|------|------|--------|---------------------|--------|
| Figure 1 | 図 | 2 | System Architecture | 高 |
| Figure 2 | 図 | 4 | Training Pipeline | 高 |
| Table 1 | 表 | 6 | Main Results | 高 |
| Figure 3 | 図 | 7 | Ablation Study | 中 |
```

#### 2.2 重要な図表の選定基準

以下の基準で優先度を判定：

**高優先度（必須）**:
- **アーキテクチャ図**: システム全体の構造を示す図
- **メイン結果**: 主要な実験結果のテーブル/グラフ
- **手法の概念図**: 提案手法の核心を示す図
- **比較図**: ベースラインとの比較を示すグラフ

**中優先度（推奨）**:
- **アブレーション結果**: アブレーション研究の結果
- **ケーススタディ**: 具体的な事例を示す図
- **分類体系図**: サーベイ論文のTaxonomy図

**低優先度（オプション）**:
- **補足図**: Appendix の詳細図
- **実装詳細図**: 特定の実装を示す図

---

### 3. 図表の抽出

#### 3.1 CLI ツールで抽出（推奨）

```bash
# 全ての図表を自動検出して抽出
uv run figure-extractor 2401.12345

# 特定の図のみ抽出
uv run figure-extractor 2401.12345 --figures 1,2,5

# 埋め込み画像を全て抽出（ベクター図に対応）
uv run figure-extractor 2401.12345 --mode images

# 特定のページ全体を画像として抽出
uv run figure-extractor 2401.12345 --mode pages --pages 2,5,8
```

#### 3.2 抽出した図表の命名規則

```
reports/figures/{arxiv_id}/
  ├── fig1.png               # Figure 1
  ├── fig2.png               # Figure 2
  ├── table1.png             # Table 1
  ├── fig3.png               # Figure 3
  └── references/            # 参照論文の図表
      └── ref1_xxx_fig1.png
```

---

### 4. 参照論文の図表抽出（詳細ワークフロー）

参照論文からの図表抽出は、レポートの理解を深めるために重要です。以下の詳細なワークフローに従ってください。

#### 4.1 レポートから参照論文の arXiv ID を抽出

レポートの「重要な参照論文」セクションを読み取り、各論文の arXiv URL から ID を抽出します。

**手順**:
1. `Read` ツールでレポートを読み込む
2. 「参照論文の詳細」セクションを探す
3. 各論文の URL フィールドから arXiv ID を抽出

**抽出対象の例**:
```markdown
| **URL** | https://arxiv.org/abs/2310.08560 |  → arXiv ID: 2310.08560
| **URL** | https://arxiv.org/abs/2302.04761 |  → arXiv ID: 2302.04761
```

#### 4.2 重要な参照論文の選定基準

全ての参照論文から図を抽出するのではなく、以下の基準で **3-5 本** を選定：

| 優先度 | 条件 | 抽出する図の種類 |
|-------|------|----------------|
| **最高** | ベースライン/比較対象として使用 | アーキテクチャ図、結果図 |
| **高** | 提案手法の基盤となっている | 手法の概念図、アルゴリズム図 |
| **中** | 関連アプローチとして詳しく言及 | 全体像を示す図 |
| **低** | 背景知識として引用 | 通常は不要 |

**選定例**（サーベイ論文の場合）:
- MemGPT → メモリアーキテクチャ図（Figure 1）
- ReAct → Thought-Action-Observation サイクル図
- LATS → MCTS 探索木の図
- Reflexion → 自己反省ループの図

#### 4.3 参照論文の PDF 取得と図表抽出

各参照論文について以下を実行：

```bash
# 1. ディレクトリを作成
mkdir -p reports/figures/{main_arxiv_id}/references

# 2. 参照論文の PDF をダウンロード
uv run arxiv-helper https://arxiv.org/abs/{ref_arxiv_id}

# 3. 図表を抽出（特定の図のみ）
uv run figure-extractor {ref_arxiv_id} --figures 1 --output-dir reports/figures/{main_arxiv_id}/references

# 4. ファイル名をリネーム（参照論文であることを明示）
mv reports/figures/{main_arxiv_id}/references/fig1.png \
   reports/figures/{main_arxiv_id}/references/{ref_name}_{ref_arxiv_id}_fig1.png
```

**複数の参照論文を並列で処理する例**:
```bash
# 並列でダウンロード
uv run arxiv-helper 2310.08560 &  # MemGPT
uv run arxiv-helper 2302.04761 &  # Toolformer
uv run arxiv-helper 2210.03629 &  # ReAct
wait

# 各論文から図を抽出
for id in 2310.08560 2302.04761 2210.03629; do
  uv run figure-extractor $id --figures 1 --output-dir reports/figures/{main_id}/references
done
```

#### 4.4 参照論文の図を特定する方法

参照論文の PDF を `Read` ツールで読み込み、重要な図を特定します。

**特定すべき図**:
1. **論文の Figure 1**: 通常、手法の全体像を示す
2. **アーキテクチャ図**: システム構造を示す図
3. **アルゴリズムの可視化**: 処理フローを示す図
4. **主要結果の図**: 性能比較グラフ等

**PDF 読み取り例**:
```
# Read ツールで参照論文の PDF を読み取り
Read downloads/{ref_arxiv_id}.pdf

# 図のページ番号を特定後、ページ単位で抽出
uv run figure-extractor {ref_arxiv_id} --mode pages --pages 2,5
```

#### 4.5 参照論文図表の命名規則

```
reports/figures/{main_arxiv_id}/references/
  ├── memgpt_2310.08560_fig1.png      # MemGPT の Figure 1
  ├── toolformer_2302.04761_fig1.png  # Toolformer の Figure 1
  ├── react_2210.03629_fig1.png       # ReAct の Figure 1
  ├── reflexion_2303.11366_fig1.png   # Reflexion の Figure 1
  └── lats_2310.04406_fig2.png        # LATS の Figure 2
```

**命名規則**:
- `{短縮名}_{arxiv_id}_fig{番号}.png`
- 短縮名は論文のキーワード（memgpt, react, lats 等）

#### 4.6 参照論文の図をレポートに埋め込む

参照論文の図は、レポートの「参照論文の詳細」セクション内の各論文説明に追加します。

**埋め込み位置の例**:
```markdown
### [1]. MemGPT: Towards LLMs as Operating Systems

| 項目 | 内容 |
|------|------|
| **著者** | Charles Packer, et al. |
| **URL** | https://arxiv.org/abs/2310.08560 |

![MemGPT Architecture](./figures/2601.14192/references/memgpt_2310.08560_fig1.png)

*Figure 1 (MemGPT): 階層的メモリシステムのアーキテクチャ。メインコンテキストと外部メモリの関係を示す。*

#### 概要
MemGPTは、LLMをオペレーティングシステムになぞらえ...
```

---

### 5. レポートへの図表埋め込み

#### 5.1 図表の挿入位置

**元論文の図表**:
| レポートセクション | 挿入する図表 |
|------------------|-------------|
| サーベイ/研究の概要 | Figure: 研究の発展・全体像 |
| 提案手法 > アーキテクチャ | Figure: System Architecture |
| 提案手法 > 手法の概要 | Figure: Method Overview |
| 実験 > 結果 | Table: Main Results, Figure: Comparison |
| 結果と考察 > アブレーション | Figure: Ablation Study |

**参照論文の図表**:
| レポートセクション | 挿入する図表 |
|------------------|-------------|
| 参照論文 > [論文名] > 概要の直後 | 参照論文の Figure 1（アーキテクチャ図） |
| 参照論文 > [論文名] > 手法の概要 | 参照論文の手法説明図 |
| 比較分析セクション | 複数論文の比較図（並べて表示） |

#### 5.2 図表埋め込みフォーマット

```markdown
### 3.2 アーキテクチャ

![Figure 1: System Architecture](./figures/{arxiv_id}/fig1_architecture.png)

*Figure 1: [論文からのキャプション]*

本アーキテクチャは以下のコンポーネントから構成される：
- [コンポーネント1の説明]
- [コンポーネント2の説明]
```

#### 5.3 表の埋め込み

表は可能な限り Markdown 形式で再現し、画像は補助として使用：

```markdown
### 5.1 主要な結果

**Table 1: Main Results**

| Method | Accuracy | F1 Score | Latency |
|--------|----------|----------|---------|
| Baseline | 85.2 | 84.1 | 120ms |
| Proposed | **92.4** | **91.8** | 95ms |

![Table 1: Main Results (Original)](./figures/{arxiv_id}/table1_main_results.png)

*Table 1: [論文からのキャプション]*
```

#### 5.4 参照論文の図表埋め込み

参照論文の図は、レポートの「参照論文の詳細」セクション内に追加します。

**フォーマット**:
```markdown
### [1]. MemGPT: Towards LLMs as Operating Systems

| 項目 | 内容 |
|------|------|
| **著者** | Charles Packer, Vivian Fang, et al. |
| **年** | 2023 |
| **URL** | https://arxiv.org/abs/2310.08560 |

#### アーキテクチャ図

![MemGPT Architecture](./figures/{main_arxiv_id}/references/memgpt_2310.08560_fig1.png)

*Figure 1 (MemGPT 論文より): MemGPT の階層的メモリアーキテクチャ。LLM のコンテキストウィンドウをメインメモリ、外部ストレージを仮想メモリとして扱い、OS のページング機構を模倣している。*

#### 概要
MemGPTは、LLMをオペレーティングシステムになぞらえ...
```

**複数の参照論文図を並べて比較する例**:
```markdown
### メモリアーキテクチャの比較

以下の図は、主要なメモリ手法のアーキテクチャを比較しています。

| MemGPT | MemoryBank |
|--------|------------|
| ![MemGPT](./figures/{id}/references/memgpt_fig1.png) | ![MemoryBank](./figures/{id}/references/memorybank_fig1.png) |
| 階層的メモリ（メイン + 外部） | 忘却曲線に基づくメモリ管理 |
```

---

### 6. 図表の説明追加

#### 6.1 図表の詳細解説

各図表について、以下の解説を追加：

```markdown
#### Figure 1 の詳細解説

**図の目的**: [この図が何を示しているか]

**主要な要素**:
1. **[要素1]**: [説明]
2. **[要素2]**: [説明]
3. **[要素3]**: [説明]

**データフロー**:
[入力] → [処理1] → [処理2] → [出力]

**注目すべきポイント**:
- [ポイント1]
- [ポイント2]

**論文での言及**:
> "[論文からの引用]"
```

#### 6.2 図表間の関連付け

複数の図表の関連性を説明：

```markdown
> **図表の関連性**: Figure 1 のアーキテクチャで示される各コンポーネントは、
> Table 1 の実験結果と対応しており、各コンポーネントの貢献度は
> Figure 4 のアブレーション研究で検証されている。
```

---

## 実行コマンド

```bash
# 基本的な使用方法（元論文のみ）
/add-figures 2401.12345

# 特定の図表のみを追加
/add-figures 2401.12345 --figures "1,2,5"

# 参照論文の図表も含める（推奨）
/add-figures 2401.12345 --include-references

# 高解像度で抽出
/add-figures 2401.12345 --high-res

# レポートファイルを直接指定
/add-figures @reports/2401.12345_report.md
```

**引数の説明**:
- `--include-references`: 参照論文から重要な図（3-5本分）を抽出してレポートに追加
- `--figures "1,2,5"`: 特定の図番号のみを抽出
- `--high-res`: 高解像度（zoom=3.0）で抽出
- `@reports/*.md`: レポートファイルのパスを直接指定

---

## 出力構造

```
reports/
  ├── {arxiv_id}_report.md          # 更新されたレポート
  └── figures/
      └── {arxiv_id}/
          ├── fig1.png              # 元論文の Figure 1
          ├── fig2.png              # 元論文の Figure 2
          ├── fig3.png              # 元論文の Figure 3
          ├── table1.png            # 元論文の Table 1
          ├── table2.png            # 元論文の Table 2
          └── references/           # 参照論文の図表
              ├── memgpt_2310.08560_fig1.png      # MemGPT の Figure 1
              ├── toolformer_2302.04761_fig1.png  # Toolformer の Figure 1
              ├── react_2210.03629_fig1.png       # ReAct の Figure 1
              ├── reflexion_2303.11366_fig1.png   # Reflexion の Figure 1
              ├── lats_2310.04406_fig1.png        # LATS の Figure 1
              └── swiftsage_2305.17390_fig1.png   # SwiftSage の Figure 1
```

**ディレクトリ構造の説明**:
- `figures/{arxiv_id}/`: 元論文（分析対象論文）の図表
- `figures/{arxiv_id}/references/`: 参照論文の図表
- ファイル名規則: `{論文短縮名}_{arxiv_id}_fig{番号}.png`

---

## 依存関係

PyMuPDF は既にプロジェクトの依存関係に含まれています（`pyproject.toml`）。

```bash
# 依存関係のインストール（未実行の場合）
uv sync
```

### 主な依存パッケージ

- `pymupdf`: PDF からの図表抽出に使用

---

## トラブルシューティング

### 図表が抽出できない場合

1. **ベクター形式の図**: ページ全体をキャプチャする方法に切り替え
2. **埋め込み画像がない**: PDF が画像として図を含んでいない可能性
3. **品質が低い**: 解像度を上げて再抽出

### 大きな PDF の処理

```bash
# 特定のページのみ処理
uv run python -c "
import fitz
doc = fitz.open('paper.pdf')
# ページ 2, 5, 8 のみ処理
for page_num in [1, 4, 7]:  # 0-indexed
    page = doc[page_num]
    # ...
"
```

---

## レポート更新例

### 更新前

```markdown
## 3. 提案手法

### 3.2 アーキテクチャ

提案手法は、エンコーダー、メモリモジュール、デコーダーの3つの主要コンポーネントから構成される。
```

### 更新後

```markdown
## 3. 提案手法

### 3.2 アーキテクチャ

![Figure 1: Overall Architecture](./figures/2401.12345/fig1_architecture.png)

*Figure 1: Overview of the proposed architecture showing the encoder, memory module, and decoder components.*

提案手法は、エンコーダー、メモリモジュール、デコーダーの3つの主要コンポーネントから構成される。

**Figure 1 の詳細解説**:

本アーキテクチャは以下の処理フローで動作する：

1. **エンコーダー** (左側): 入力データを潜在表現に変換
2. **メモリモジュール** (中央): 過去の情報を保持・参照
3. **デコーダー** (右側): 潜在表現から出力を生成

> 論文より: "Our architecture integrates a novel memory mechanism that enables..."
```

---

## 修正履歴への追記

図表追加後、レポート末尾の修正履歴を更新：

```markdown
## 修正履歴

| 日付 | 修正タイプ | 内容 |
|------|-----------|------|
| 2026-01-24 | 図表追加 | Figure 1-3, Table 1 を追加 |
```

---

## 完全なワークフロー（まとめ）

以下は、元論文と参照論文の両方から図表を抽出してレポートに追加する完全なワークフローです。

### ステップ 1: レポートの分析

```bash
# レポートを読み込み、arXiv ID と参照論文を確認
Read reports/{arxiv_id}_report.md
```

確認事項：
- 元論文の arXiv ID
- 参照論文セクションの各論文の arXiv URL
- 既存の図表埋め込み状況

### ステップ 2: 元論文の図表抽出

```bash
# 元論文の図表を抽出
uv run figure-extractor {arxiv_id}
```

### ステップ 3: 参照論文の特定と選定

レポートの「参照論文の詳細」セクションから、arXiv URL を持つ論文を抽出：

```
2310.08560 → MemGPT
2302.04761 → Toolformer
2210.03629 → ReAct
2303.11366 → Reflexion
2310.04406 → LATS
2305.17390 → SwiftSage
2305.10250 → MemoryBank
2303.17580 → HuggingGPT
```

重要度に基づいて 3-5 本を選定。

### ステップ 4: 参照論文の PDF 取得

```bash
# 参照論文をダウンロード
uv run arxiv-helper 2310.08560  # MemGPT
uv run arxiv-helper 2210.03629  # ReAct
uv run arxiv-helper 2303.11366  # Reflexion
```

### ステップ 5: 参照論文の PDF を読み取り、重要な図を特定

```bash
# 各参照論文の PDF を読み取り
Read downloads/2310.08560.pdf
```

各論文から抽出すべき図を特定（通常 Figure 1 が最も重要）。

### ステップ 6: 参照論文の図表を抽出

```bash
# 参照論文用のディレクトリ作成
mkdir -p reports/figures/{arxiv_id}/references

# 各参照論文から図を抽出
uv run figure-extractor 2310.08560 --figures 1 --output-dir reports/figures/{arxiv_id}/references
uv run figure-extractor 2210.03629 --figures 1 --output-dir reports/figures/{arxiv_id}/references
uv run figure-extractor 2303.11366 --figures 1 --output-dir reports/figures/{arxiv_id}/references
```

### ステップ 7: ファイル名のリネーム

```bash
# 参照論文であることを明示するためリネーム
cd reports/figures/{arxiv_id}/references
mv fig1.png memgpt_2310.08560_fig1.png
# ... 他の論文も同様
```

### ステップ 8: レポートへの埋め込み

`Edit` ツールを使用して、レポートの適切な位置に図表を埋め込む：

1. **元論文の図表**: 各セクションの冒頭に追加
2. **参照論文の図表**: 「参照論文の詳細」セクション内の各論文説明に追加

### ステップ 9: 修正履歴の更新

```markdown
## 修正履歴

| 日付 | 修正タイプ | 内容 |
|------|-----------|------|
| 2026-01-24 | 図表追加 | Figure 1-5, Table 1-3 を追加 |
| 2026-01-24 | 参照論文図追加 | MemGPT, ReAct, Reflexion の図を追加 |
```

---

## 注意事項

- 著作権に配慮し、論文からの図表は引用として適切に使用すること
- 抽出した図表は個人的な学習・研究目的での使用を想定
- 高解像度の抽出は処理時間が長くなる場合がある
- 一部の PDF は図表抽出に対応していない形式の場合がある
- 参照論文の図表は、元論文での言及と合わせて使用すること
- **参照論文は全て抽出するのではなく、重要な 3-5 本に絞ること**
- 参照論文の図表は、その論文の説明を補完する目的で使用すること