pptx2md_with_image.py 技術ドキュメント

プログラムの動作

pptx2md_with_image.py は、PowerPointプレゼンテーションファイル（.pptx）またはPDFファイルを入力として受け取り、その内容を解析してAIモデルによる詳細な解説レポートを生成するPythonスクリプトです。

主な機能:

  1. コンテンツ抽出:

    • スライドのタイトルと通常のテキストコンテンツを抽出します。

    • Office Math Markup Language (OMML) 形式の数式をLaTeX形式に変換します。

    • PowerPointに埋め込まれた画像を抽出し、指定された作業ディレクトリに保存します。

  2. PDF/画像変換:

    • 入力がPPTXファイルの場合、まず pywin32 を使用してPowerPointアプリケーション経由でPDFに変換します。

    • 次に、PyMuPDF を使用して、そのPDF（または直接入力されたPDF）の各ページをPNG画像に変換します。

  3. AIモデル連携:

    • 抽出されたテキスト、変換されたLaTeX数式、および各スライドのPNG画像をAIモデル（OpenAI GPT-4o/GPT-5.2 または Google Gemini）への入力として使用します。

    • AIはこれらの情報に基づいてスライドの詳細な解説を生成します。

  4. Markdownレポート出力:

    • AIが生成した解説は、各スライドごとにMarkdown形式のレポートとして出力ファイルに保存されます。出力Markdownファイルには、抽出された画像への相対パスリンクも含まれます。

    • 既存のMarkdownテキストファイルをスライドテキストとして入力することも可能です。

解決する課題:

このプログラムは、PowerPointスライドの内容を自動的にテキスト化し、特に数式や画像が豊富に含まれる技術的なプレゼンテーションに対して、AIが文脈を理解した上で詳細な解説レポートを生成する手間を大幅に削減します。これにより、ドキュメント作成や学習プロセスを効率化します。

原理

1. PPTXファイル解析とコンテンツ抽出

プログラムは python-pptx ライブラリを使用してPowerPointプレゼンテーションファイル（Open XML形式）を読み込み、各スライドの構造にアクセスします。

  • テキスト抽出: スライド内のテキストフレームからテキストコンテンツを直接抽出します。スライドタイトルも特定のプレースホルダータイプから取得します。

  • 画像抽出: スライドのXML構造 (slide.part.blob) を lxml で解析し、a:blip 要素の r:embed 属性から埋め込み画像のリレーションシップIDを取得します。このIDを使用して画像パート (slide.part.rels[r_id].target_part) からバイナリデータ (image_part.blob) を抽出し、PNGまたはJPG形式で保存します。

2. 数式（OMML）からLaTeXへの変換

Microsoft Officeの数式はOffice Math Markup Language (OMML) というXMLベースの形式で保存されています。プログラムは lxml を使用してスライドのXMLからOMML要素（<m:oMathPara> や <m:oMath>）を抽出し、再帰関数 omml_to_latex を用いてLaTeX形式に変換します。

omml_to_latex 関数の変換ロジックの概要は以下の通りです。

  • 名前空間: NAMESPACES 辞書を使用して、OMML (m), DrawingML (a), PresentationML (p) などのXML名前空間を定義します。

  • 記号変換:

    • MATH_UNICODE_MAP を使用して、Unicodeの数学記号（例: '𝑷' -> 'P', '−' -> '-', '∑' -> \sum）をASCIIまたはLaTeXコマンドに置換します。

    • NARY_TO_LATEX を使用して、n-ary演算子（例: '∑' -> \sum, '∫' -> \int）を対応するLaTeXコマンドに変換します。

  • 構造変換: OMMLの各要素は対応するLaTeXの構文に変換されます。

    • <m:f> (Fraction): 分子 <m:num> と分母 <m:den> を抽出し、\frac{numerator}{denominator} に変換します。

    • <m:rad> (Root): ルート記号。オプションの次数 <m:deg> と内容 <m:e> を抽出し、\sqrt[degree]{expression} または \sqrt{expression} に変換します。

    • <m:sSup> (Superscript), <m:sSub> (Subscript), <m:sSubSup> (Superscript and Subscript): 基数 <m:e>, 上付き <m:sup>, 下付き <m:sub> を抽出し、base^{superscript}, base_{subscript}, base_{subscript}^{superscript} の形式に変換します。

    • <m:d> (Delimiter): 区切り文字 <m:dPr/m:begChr>, <m:dPr/m:endChr>（通常は括弧）と内容を抽出し、{beg_chr}{content}{end_chr} に変換します。

    • <m:limLow> (Limit Lower), <m:limUpp> (Limit Upper): 積分や和などの下限・上限を表現します。

    • <m:int> (Integral), <m:nary> (N-ary Operator): 積分や総和などの演算子 <m:naryPr/m:chr> と、下限 <m:sub>/<m:low>, 上限 <m:sup>/<m:up>, 内容 <m:e> を抽出し、operator_{lower}^{upper}{expression} の形式に変換します。

  • 複数行数式: split_latex_blocks 関数は、LaTeX文字列内の \\\\ を検出して複数行の数式を個別の $$. . .$$ ブロックに分割し、Pandocなどのレンダリングツールで正しく表示されるようにします。

3. PDF/画像変換

AIモデルにスライド全体を画像として入力するため、PPTXファイルをPDFに変換し、さらに各ページをPNG画像に変換します。

  • PPTXからPDFへ: pywin32 ライブラリを使用してWindowsのCOMオートメーション機能を利用し、PowerPointアプリケーションをバックグラウンドで起動してPPTXファイルをPDF形式で保存します。

  • PDFからPNGへ: PyMuPDF (fitz) ライブラリを使用してPDFファイルを読み込みます。各ページを get_pixmap() メソッドで高解像度（2.0倍）のピクセルマップとしてレンダリングし、PNG画像として保存します。

4. AIモデル連携とプロンプト生成

AIモデルとの連携は、選択されたAPI（OpenAIまたはGoogle Gemini）に応じて行われます。

  • プロンプトテンプレート: DEFAULT_PROMPT_TEMPLATE に定義されたテンプレートを使用し、スライド番号、抽出されたテキスト、出力言語を埋め込んでプロンプトを動的に生成します。INIファイルでカスタムプロンプトテンプレートを指定することも可能です。

    • AIへの指示には、生成されるMarkdown中の数式をブロック数式 $$...$$ で出力するよう明示的に含めています。

  • API呼び出し:

    • Google Gemini: google.generativeai クライアントを使用し、プロンプトテキストと画像バイナリデータを直接 model.generate_content() メソッドに渡します。

    • OpenAI: openai クライアントを使用し、プロンプトテキストとBase64エンコードされた画像データURL（data:image/png;base64,...）を client.chat.completions.create() メソッドに渡します。

5. 出力Markdownの生成

AIから返された解説テキストは、各スライドのセクションとして出力Markdownファイルに追記されます。これにより、# Analysis Report: [ファイル名] で始まり、各スライドが # Slide N で区切られた、画像と解説を含むレポートが完成します。

必要な非標準ライブラリとインストール方法

このプログラムの実行には、以下の非標準Pythonライブラリが必要です。

ライブラリ名

pip インストールコマンド

概要

pywin32

pip install pywin32

PowerPointからPDFへの変換（Windows環境のみ）

PyMuPDF (fitz)

pip install pymupdf

PDFからPNG画像への変換

python-pptx

pip install python-pptx

PPTXファイルの解析とテキスト/画像抽出

lxml

pip install lxml

XML（OMML数式）の解析

openai

pip install openai

OpenAI APIとの連携

google-generativeai

pip install google-generativeai

Google Gemini APIとの連携

インストール方法:

以下のコマンドをターミナルまたはコマンドプロンプトで実行して、必要なライブラリをインストールしてください。

pip install pywin32 pymupdf python-pptx lxml openai google-generativeai

APIキーの設定:

OpenAIまたはGemini APIを使用するには、環境変数にAPIキーを設定する必要があります。

  • OpenAI: OPENAI_API_KEY

  • Gemini (Google): GEMINI_API_KEY または GOOGLE_API_KEY

例 (Linux/macOS):

export OPENAI_API_KEY="your_openai_api_key_here"
export GEMINI_API_KEY="your_gemini_api_key_here"

例 (Windows Command Prompt):

set OPENAI_API_KEY="your_openai_api_key_here"
set GEMINI_API_KEY="your_gemini_api_key_here"

必要な入力ファイル

  1. 入力PowerPointファイル (.pptx) またはPDFファイル (.pdf) (必須)

    • プログラムが解析する主要なファイルです。

    • PPTXファイルの場合、プレゼンテーションのテキスト、数式、埋め込み画像を抽出します。

    • PDFファイルの場合、各ページを画像として抽出し、AIモデルに渡します（テキスト/数式は抽出されません）。

  2. 既存のテキストファイル (.md) (オプション: --txt 引数で指定)

    • PowerPointからテキストを抽出する代わりに、既存のMarkdown形式のファイルからスライドごとのテキストコンテンツを読み込む場合に使用します。

    • ファイルは、各スライドのコンテンツを # Slide N (Nはスライド番号、1から始まる) の形式で区切る必要があります。

    • 例:

      # Slide 1
これは1ページ目のテキストです。
ここに数式やその他の情報があります。

# Slide 2
これは2ページ目のテキストです。
...

  3. INI設定ファイル (.ini) (オプション: --ini または -i 引数で指定)

    • AIへのプロンプトテンプレートなどの設定を外部ファイルから読み込むために使用します。

    • 指定がない場合、プログラムはカレントディレクトリまたはスクリプトディレクトリで pptx2md_with_image.ini という名前のファイルを探索します。

    • ファイルの内容は key = value 形式で、prompt_template キーにAIへの指示を含めることができます。複数行の値は「3重引用符」で囲むことで指定できます。

    • 例:

      prompt_template = """
あなたは熟練した講師です。
以下のスライド内容について詳細に解説してください。
# スライド情報:
{slide_text}
# 出力言語: {lang}
"""

生成される出力ファイル

プログラムを実行すると、以下のファイルとディレクトリが生成されます。

  1. Markdown形式の解説レポートファイル (.md)

    • ファイル名: --output (または -o) 引数で指定しない場合、入力ファイル名（拡張子を除く）に .md 拡張子が追加されます（例: presentation.pptx -> presentation.md）。

    • 内容:

      • レポートの冒頭に # Analysis Report: [入力ファイル名] というタイトルが含まれます。

      • 各スライドの解説は # Slide [スライド番号] の見出しで区切られます。

      • AIによって生成された詳細な解説がMarkdown形式で含まれます。AIのプロンプトテンプレートで指定された形式（例: ## 1. 解説, ## 2. 図・グラフの分析 など）に従って構成されます。

      • 抽出された数式は、ブロック数式として独立した行に $$ LaTeX数式 $$ の形式で記述されます。

      • 抽出された画像は、作業ディレクトリ内の画像ファイルへの相対パスを含むMarkdownの画像リンク ![alt_text](path/to/image.png) として埋め込まれます。

  2. 作業ディレクトリ (_work ディレクトリ)

    • ディレクトリ名: 入力ファイル名（拡張子を除く）に _work が追加されます（例: presentation.pptx -> presentation_work/）。

    • 内容: このディレクトリには、以下のファイルとサブディレクトリが含まれます。

      • 中間PDFファイル: 入力がPPTXファイルの場合、PPTXから変換されたPDFファイルが保存されます（例: presentation_work/presentation.pdf）。

      • 画像サブディレクトリ (slides_png/): 各スライドをPNG画像に変換したファイルが保存されます（例: presentation_work/slides_png/slide_001.png, slide_002.png など）。これらの画像ファイルは、最終的なMarkdownレポートから参照されます。

コマンドラインでの使用例 (Usage)

プログラムは以下の形式で実行します。

python pptx2md_with_image.py <infile> [オプション]

引数:

  • <infile> (必須): 処理するPowerPointファイル（.pptx）またはPDFファイル（.pdf）へのパス。

オプション:

  • -o, --output <file_name>: 生成されるMarkdownレポートのファイル名を指定します。指定しない場合、入力ファイル名に基づいて自動生成されます。

  • --txt <file_path>: PPTXからテキストを抽出する代わりに、既存のMarkdown形式のテキストファイルをスライドテキストとして使用します。

  • -i, --ini <file_path>: AIプロンプトテンプレートなどの設定を読み込むINIファイルのパスを指定します。

  • --api <api_name>: 使用するAIモデルのAPIを指定します。

    • gemini (デフォルト): Google Gemini APIを使用します。

    • google: gemini と同じです。

    • openai: OpenAI API (GPT-4oなど) を使用します。

    • openai5: OpenAI API (GPT-5.2など、OPENAI_MODEL5 環境変数で指定されたモデル) を使用します。

  • --model <model_name>: 使用するAIモデルの名前を明示的に指定します。この値は --api で選択されたAPIのデフォルトモデルを上書きします。

  • --google_model <model_name>: Google Gemini APIで使用するモデルを指定します（デフォルト: gemini-2.5-flash または GEMINI_MODEL/GOOGLE_MODEL 環境変数）。

  • --openai_model <model_name>: OpenAI API (デフォルトの openai モード) で使用するモデルを指定します（デフォルト: gpt-4o または OPENAI_MODEL 環境変数）。

  • --openai_model5 <model_name>: OpenAI API (openai5 モード) で使用するモデルを指定します（デフォルト: gpt-5.2 または OPENAI_MODEL5 環境変数）。

  • --visible: PPTXからPDFへの変換時に、PowerPointアプリケーションのウィンドウを表示します（Windows環境のみ、デバッグ用）。

  • --language <lang>: AIに解説を生成させる言語を指定します（デフォルト: Japanese）。

  • --pause <int>: プログラム終了時にユーザーの入力を待機するかどうかを制御します（0で無効、1で有効）。

コマンドラインでの具体的な使用例

例1: デフォルト設定でPowerPointファイルを処理する

最も基本的な使用例です。example.pptx という名前のPowerPointファイルを処理し、Google Gemini API（デフォルトモデル）を使用して日本語の解説を生成します。

python pptx2md_with_image.py example.pptx

実行結果の説明:

  • example.md というMarkdownレポートファイルがカレントディレクトリに生成されます。

  • example_work/ という作業ディレクトリが作成され、その中に example.pdf（PowerPointから変換されたPDF）と slides_png/ ディレクトリが保存されます。

  • slides_png/ ディレクトリには、各スライドのPNG画像（例: slide_001.png）が保存されます。

  • example.md ファイルには、各スライドのテキスト、LaTeX数式、画像が埋め込まれたAIによる日本語の解説が含まれます。

例2: OpenAI GPT-4oモデルを使用し、英語でレポートを生成する

OpenAIの特定のモデルを指定し、出力言語を英語に設定して処理します。

python pptx2md_with_image.py my_presentation.pptx --api openai --model gpt-4o --language English -o report_en.md

実行結果の説明:

  • OPENAI_API_KEY 環境変数が設定されている必要があります。

  • my_presentation_work/ ディレクトリに中間ファイルが生成されます。

  • report_en.md というMarkdownレポートファイルが生成されます。

  • AIはOpenAIの gpt-4o モデルを使用し、英語で解説を生成します。

例3: 既存のテキストファイルとカスタムINIファイルを使用して処理する

presentation.pptx ファイルの画像のみを使用し、スライドテキストは my_notes.md から読み込みます。また、AIへのプロンプトは custom_prompt.ini に定義されたものを使用します。

my_notes.md の内容:

# Slide 1
これはカスタムノートの1ページ目です。
主要な概念は、$E = mc^2$ です。

# Slide 2
2ページ目の詳細な説明。

custom_prompt.ini の内容:

prompt_template = """
あなたは、スライドの内容と提供されたノートに基づいて、詳細な講義ノートを作成するアシスタントです。
以下のスライド画像とノートを参考に、深い洞察を提供してください。

# スライド番号: {slide_no}
# 講義ノート:
{slide_text}
# 出力言語: {lang}

# 指示:
1. 講義ノートを基盤とし、画像の内容と統合して、包括的な解説を作成してください。
2. 出力はMarkdown形式とし、各セクションを明確に区切ってください。
3. 数式は必ず $$ LaTeX $$ のブロック形式で記述してください。
"""

コマンド:

python pptx2md_with_image.py presentation.pptx --txt my_notes.md --ini custom_prompt.ini --api gemini

実行結果の説明:

  • GEMINI_API_KEY または GOOGLE_API_KEY 環境変数が設定されている必要があります。

  • presentation.md というMarkdownレポートファイルが生成されます。

  • スライドのテキスト情報として my_notes.md の内容が使用されます。

  • AIへのプロンプトは custom_prompt.ini の prompt_template に従って構築されます。

  • AIはGoogle Geminiモデルを使用し、指定されたノートとスライド画像を基に解説を生成します。