pptx2md2.py ドキュメント

このドキュメントは、Pythonプログラム pptx2md2.py の機能、原理、使用方法について記述します。

プログラムの動作

pptx2md2.py は、Microsoft PowerPointプレゼンテーションファイル (.pptx) からテキスト、数式、および画像を抽出し、それらを構造化されたMarkdownファイルとして出力するためのユーティリティです。

主な機能:

テキスト抽出: スライド内のすべてのテキストコンテンツを抽出し、元の書式設定（改行、箇条書きレベル）を可能な限り保持してMarkdown形式で出力します。
数式変換: PowerPointに埋め込まれたOMML (Office Math Markup Language) 形式の数式を解析し、LaTeX形式の数式に変換してMarkdownに出力します。
画像抽出: スライドに埋め込まれた画像を抽出し、指定されたディレクトリに保存し、Markdownファイル内で参照する形式で出力します。
Markdown出力: 各スライドの内容をMarkdownの見出し、箇条書き、数式ブロック、画像リンクとして構成します。

解決する課題: PowerPointファイルは、その内容を再利用したり、他のドキュメント形式に変換したりするのが難しい場合があります。特に、プレゼンテーションからテキストや数式、画像を効率的に抽出し、ウェブサイト、技術ブログ、あるいは他のドキュメンテーションツールで利用できる形式（Markdown）に変換するニーズに応えます。

原理

pptx2md2.py は、主に python-pptx と lxml の二つの非標準ライブラリを利用して、PowerPointファイルの内部構造を解析します。

PowerPointファイルの読み込み:
- pptx.Presentation(input_pptx) を使用して、指定されたPowerPointファイルを開きます。これにより、プレゼンテーションの各スライドにアクセスできるようになります。
XML構造の解析:
- PowerPointファイルは、実質的にはZIPアーカイブであり、内部にXMLファイル群が含まれています。特に、各スライドの内容はXML形式で記述されています。
- プログラムは slide.part.blob を通じてスライドの生のXMLコンテンツを取得し、lxml.etree.fromstring() を使ってXMLツリーを構築します。
- 定義された名前空間 NAMESPACES を利用し、XPathクエリ (root.xpath(...)) を使って、特定の要素（テキスト段落 a:p、数式 m:oMathPara / m:oMath、画像 a:blip）を効率的に抽出します。
テキスト抽出と整形:
- //a:p XPathで段落要素をすべて取得します。
- 各段落内で、テキストラン (a:r)、改行 (a:br)、および埋め込み数式 (m:oMath/m:oMathPara) を順に走査します。
- 箇条書きのインデントレベルは、段落プロパティ a:pPr/@lvl から取得し、Markdownの箇条書き (* ) とインデント ( ) に変換します。
OMML数式からLaTeXへの変換:
- プログラムの核となる機能の一つは、OMML形式の数式をLaTeX形式に変換する omml_to_latex 関数です。
- この関数は再帰的に動作し、OMMLの様々なタグに対応するLaTeXコマンドを生成します。
  - 分数: m:f は \frac{...}{...} に変換されます。
  - 平方根: m:rad は \sqrt{...} または \sqrt[...]{...} に変換されます。
  - 上付き/下付き文字: m:sSup, m:sSub, m:sSubSup は ^{...}, _{...}, _{...}^{...} にそれぞれ変換されます。
  - 括弧類: m:d は () や [], {} などの区切り文字を処理します。
  - 積分や総和: m:int, m:nary は \int, \sum などの演算子と、その上・下限を処理します。例えば、 $$\sum_{i=1}^{n} x_i$$ のような数式は、対応するOMML構造から生成されます。
- _safe_text_replace_math_unicode 関数は、MATH_UNICODE_MAP に定義されたUnicode数学記号（例: ∑, α, −）を対応するLaTeXコマンド（例: \sum, \alpha, -）に置換します。
- split_latex_blocks 関数は、生成されたLaTeXコード内の \\ (LaTeXの改行コマンド) で区切られた部分を個別の数式ブロックとして分離し、Markdownのブロック数式 $$ ... $$ として出力します。
画像抽出:
- //a:blip[@r:embed] XPathで、スライドに埋め込まれた画像の参照要素を特定します。
- 各画像要素の r:embed 属性からリレーションシップIDを取得し、slide.part.rels[r_id].target_part を使って実際の画像データにアクセスします。
- 画像のコンテンツタイプから拡張子を特定し、image_part.blob からバイナリデータを読み込み、指定された画像ディレクトリに保存します。
- Markdownファイルには、![代替テキスト](画像ディレクトリ/画像ファイル名) の形式で画像へのリンクが生成されます。

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

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

python-pptx: PowerPointファイル (.pptx) の読み書きを可能にします。
lxml: XMLファイルを高速かつ効率的に処理するためのライブラリで、PowerPointファイル内部のXML構造の解析に使用されます。

これらのライブラリは pip コマンドを使用してインストールできます。

pip install python-pptx lxml

必要な入力ファイル

プログラムは以下の形式の入力ファイルを必要とします。

PowerPointプレゼンテーションファイル: .pptx 拡張子を持つファイル。
- このファイルは、テキスト、Office数式（OMML形式）、および画像を含むことができます。プログラムはこれらの要素を抽出しようとします。
- ファイルが見つからない場合、プログラムはエラーメッセージを表示して終了します。

生成される出力ファイル

プログラムは以下の種類のファイルとディレクトリを生成します。

Markdownファイル:
- 指定された出力ファイル名（例: output.md）で生成されます。
- ファイルの内容は、入力されたPowerPointプレゼンテーションの構造を反映しています。
- 各スライドはMarkdownの第一段階見出し # スライド N タイトル で始まり、その後に --- (水平線) で区切られます。
- スライドごとに以下のセクションが含まれる場合があります。
  - ## テキスト: スライド内のテキストが箇条書き形式で出力されます。元の箇条書きレベルはインデントとして表現されます。数式がテキスト行にインラインで埋め込まれている場合、 $...$ 形式で出力されます。
  - ## 数式: スライドから抽出されたすべてのOMML数式が、LaTeX形式に変換され、ブロック数式 $$ ... $$ で出力されます。各数式ブロックの前後は空行で区切られます。
  - ## 図: スライドから抽出された画像が、Markdownの画像リンク ![alt_text](imagedir/filename.ext) として出力されます。
- 出力されるMarkdownファイルの例:
```
# スライド 1 タイトル

## テキスト

* テキストの段落 1
*   入れ子の箇条書き $E=mc^2$
*   もう一つの段落

## 数式

$$ \frac{1}{\sqrt{x^2 + y^2}} $$

$$ \sum_{n=0}^{\infty} \frac{x^n}{n!} = e^x $$

## 図

![スライド1の図1](images/slide1_image1.png)

---

# スライド 2 別のタイトル

...
```
画像ディレクトリ:
- デフォルトでは images という名前のディレクトリが作成されます。この名前は --imagedir オプションで変更できます。
- PowerPointから抽出されたすべての画像ファイルが、slideN_imageM.ext の命名規則でこのディレクトリに保存されます（例: slide1_image1.png, slide2_image1.jpeg）。

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

pptx2md2.py は、以下のコマンドライン引数をサポートします。

usage: pptx2md2.py [-h] -i INPUT -o OUTPUT [--xml] [--imagedir IMAGEDIR] [--pause PAUSE]

PowerPointファイルからテキスト、数式、図を抽出し、Markdownに出力します。

options:
  -h, --help            show this help message and exit
  -i INPUT, --input INPUT
                        入力するPowerPointファイル名 (必須)
  -o OUTPUT, --output OUTPUT
                        出力するMarkdownファイル名 (必須)
  --xml                 数式の元のOMML XMLを出力します。 (オプション)
  --imagedir IMAGEDIR   画像ディレクトリ (デフォルト: images)
  --pause PAUSE         終了時待機 (デフォルト: 0)

基本的な実行コマンド形式:

python pptx2md2.py -i <入力PowerPointファイル名> -o <出力Markdownファイル名> [オプション]

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

ここでは、pptx2md2.py の具体的な使用例をいくつか示します。

最も基本的な変換例: presentation.pptx という名前のPowerPointファイルを output.md というMarkdownファイルに変換し、画像はデフォルトの images ディレクトリに保存します。
```
python pptx2md2.py -i presentation.pptx -o output.md
```
実行結果の説明:
- presentation.pptx の内容が解析されます。
- output.md というMarkdownファイルが生成されます。
- 現在のディレクトリに images というディレクトリが作成され、抽出されたすべての画像ファイルがその中に保存されます。output.md 内の画像リンクは images/ ディレクトリを参照します。
- 変換が完了すると、「変換完了: output.md」というメッセージが表示されます。
画像ディレクトリを指定した変換例: report.pptx を report.md に変換し、画像を my_images ディレクトリに保存します。
```
python pptx2md2.py -i report.pptx -o report.md --imagedir my_images
```
実行結果の説明:
- report.pptx の内容が解析されます。
- report.md というMarkdownファイルが生成されます。
- 現在のディレクトリに my_images というディレクトリが作成され、抽出された画像がその中に保存されます。report.md 内の画像リンクは my_images/ ディレクトリを参照します。
- 変換が完了すると、「変換完了: report.md」というメッセージが表示されます。
終了時に待機する例: 変換後、ユーザーがEnterキーを押すまでプログラムが終了しないようにします。これは、スクリプトの実行結果をすぐに確認したい場合に便利です。
```
python pptx2md2.py -i input.pptx -o output.md --pause 1
```
実行結果の説明:
- 上記と同様にファイル変換が行われます。
- 変換完了後、「Press ENTER to terminate」というプロンプトが表示され、ユーザーがEnterキーを押すまでプログラムは終了を待ちます。