pptx

PPTX の作成、編集、分析

概要

ユーザーから、.pptx ファイルの作成、編集、内容の分析を依頼されることがあります。.pptx ファイルは基本的に、読み取りや編集が可能な XML ファイルやその他のリソースを含む ZIP アーカイブです。タスクに応じて、さまざまなツールやワークフローを利用できます。

コンテンツの読み取りと分析

テキストの抽出

プレゼンテーションのテキストだけを読み取る場合は、ドキュメントを Markdown に変換します。

# Convert document to markdown
python -m markitdown path-to-file.pptx

生の XML へのアクセス

コメント、発表者ノート、スライドレイアウト、アニメーション、デザイン要素、複雑な書式設定には、生の XML へのアクセスが必要です。これらの機能を確認するには、プレゼンテーションを展開して生の XML コンテンツを読み取ります。

ファイルの展開

python ooxml/scripts/unpack.py <office_file> <output_dir>

注：unpack.py スクリプトは、プロジェクトのルートディレクトリからの相対パスで skills/pptx/ooxml/scripts/unpack.py にあります。このパスにスクリプトがない場合は、find . -name "unpack.py" を使って場所を特定してください。

主なファイル構成

• ppt/presentation.xml - プレゼンテーションのメタデータとスライド参照
• ppt/slides/slide{N}.xml - 個々のスライドのコンテンツ（slide1.xml、slide2.xml など）
• ppt/notesSlides/notesSlide{N}.xml - 各スライドの発表者ノート
• ppt/comments/modernComment_*.xml - 個々のスライドのコメント
• ppt/slideLayouts/ - スライドのレイアウトテンプレート
• ppt/slideMasters/ - スライドマスターテンプレート
• ppt/theme/ - テーマとスタイルの情報
• ppt/media/ - 画像やその他のメディアファイル

タイポグラフィと色の抽出

参考デザインが提示された場合：以下の方法で、まずプレゼンテーションのタイポグラフィと色を必ず分析します。

1. テーマファイルを読む：色（<a:clrScheme>）とフォント（<a:fontScheme>）を確認するため、ppt/theme/theme1.xml を確認します
2. スライドの内容をサンプリングする：実際に使用されているフォント（<a:rPr>）と色を確認するため、ppt/slides/slide1.xml を調べます
3. パターンを検索する：すべての XML ファイルを対象に grep を使って、色（<a:solidFill>、<a:srgbClr>）やフォントの参照を検索します

テンプレートを使わずに新しい PowerPoint プレゼンテーションを作成する

新しい PowerPoint プレゼンテーションを一から作成する場合は、正確な位置に配置した HTML スライドを PowerPoint に変換するために、html2pptx ワークフローを使用します。

デザイン原則

重要：プレゼンテーションを作成する前に、内容を分析し、適切なデザイン要素を選びます。

1. テーマを考慮する：このプレゼンテーションのテーマは何ですか？どのようなトーン、業界、雰囲気がふさわしいですか？
2. ブランドを確認する：ユーザーが企業や組織に言及している場合は、そのブランドカラーとアイデンティティを考慮します
3. 配色を内容に合わせる：テーマを反映する色を選びます
4. 方針を説明する：コードを書く前に、デザインの選択について説明します

要件：

• ✅ コードを書く前に、内容に基づいたデザイン方針を示します
• ✅ Web セーフフォントのみを使用します：Arial、Helvetica、Times New Roman、Georgia、Courier New、Verdana、Tahoma、Trebuchet MS、Impact
• ✅ サイズ、太さ、色を使って、明確な視覚的階層を作ります
• ✅ 読みやすさを確保します：十分なコントラスト、適切な文字サイズ、整った配置
• ✅ 一貫性を保ちます：スライド全体でパターン、間隔、視覚表現を繰り返します

カラーパレットの選択

創造的な色選び：

• 既定の選択肢にとらわれない：この特定のテーマに本当に合う色は何でしょうか？　惰性で選ぶのは避けましょう。
• さまざまな角度から検討する：テーマ、業界、雰囲気、エネルギーの度合い、対象読者、ブランドアイデンティティ（言及されている場合）
• 大胆に試す：意外な組み合わせを試してみましょう。医療関連のプレゼンテーションに必ずしも緑を使う必要はなく、金融関連に必ずしもネイビーを使う必要もありません。
• パレットを作る：組み合わせて使える色を3～5色選びます（メインカラー＋補助色＋アクセントカラー）。
• コントラストを確保する：背景に対してテキストがはっきり読めるようにします。

カラーパレットの例（創造性を引き出す参考にしてください。いずれかを選ぶ、調整する、または独自のパレットを作成できます）：

1. クラシックブルー：ディープネイビー（#1C2833）、スレートグレー（#2E4053）、シルバー（#AAB7B8）、オフホワイト（#F4F6F6）
2. ティール＆コーラル：ティール（#5EA8A7）、ディープティール（#277884）、コーラル（#FE4447）、ホワイト（#FFFFFF）
3. 鮮やかなレッド：レッド（#C0392B）、ブライトレッド（#E74C3C）、オレンジ（#F39C12）、イエロー（#F1C40F）、グリーン（#2ECC71）
4. 温かみのあるブラッシュ：モーブ（#A49393）、ブラッシュ（#EED6D3）、ローズ（#E8B4B8）、クリーム（#FAF7F2）
5. バーガンディ＆ラグジュアリー：バーガンディ（#5D1D2E）、クリムゾン（#951233）、ラスト（#C15937）、ゴールド（#997929）
6. ディープパープル＆エメラルド：パープル（#B165FB）、ダークブルー（#181B24）、エメラルド（#40695B）、ホワイト（#FFFFFF）
7. クリーム＆フォレストグリーン：クリーム（#FFE1C7）、フォレストグリーン（#40695B）、ホワイト（#FCFCFC）
8. ピンク＆パープル：ピンク（#F8275B）、コーラル（#FF574A）、ローズ（#FF737D）、パープル（#3D2F68）
9. ライム＆プラム：ライム（#C5DE82）、プラム（#7C3A5F）、コーラル（#FD8C6E）、ブルーグレー（#98ACB5）
10. ブラック＆ゴールド：ゴールド（#BF9A4A）、ブラック（#000000）、クリーム（#F4F6F6）
11. セージ＆テラコッタ：セージ（#87A96B）、テラコッタ（#E07A5F）、クリーム（#F4F1DE）、チャコール（#2C2C2C）
12. チャコール＆レッド：チャコール（#292929）、レッド（#E33737）、ライトグレー（#CCCBCB）
13. 鮮やかなオレンジ：オレンジ（#F96D00）、ライトグレー（#F2F2F2）、チャコール（#222831）
14. フォレストグリーン：ブラック（#191A19）、グリーン（#4E9F3D）、ダークグリーン（#1E5128）、ホワイト（#FFFFFF）
15. レトロレインボー：パープル（#722880）、ピンク（#D72D51）、オレンジ（#EB5C18）、アンバー（#F08800）、ゴールド（#DEB600）
16. ヴィンテージアースカラー：マスタード（#E3B448）、セージ（#CBD18F）、フォレストグリーン（#3A6B35）、クリーム（#F4F1DE）
17. コースタルローズ：オールドローズ（#AD7670）、ビーバー（#B49886）、エッグシェル（#F3ECDC）、アッシュグレー（#BFD5BE）
18. オレンジ＆ターコイズ：ライトオレンジ（#FC993E）、グレイッシュターコイズ（#667C6F）、ホワイト（#FCFCFC）

ビジュアルの詳細オプション

幾何学模様：

• 水平ではなく斜めのセクション区切りを使用する
• 非対称な列幅（30/70、40/60、25/75）
• 90°または270°に回転した見出しテキスト
• 画像を円形または六角形の枠で囲む
• 角に三角形のアクセント形状を配置する
• 図形を重ねて奥行きを出す

境界線とフレームの処理：

• 片側のみに太い単色の境界線（10～20pt）を配置する
• 対照的な色の二重線の境界線を使用する
• フレーム全体ではなく、角括弧状の線を使用する
• L字型の境界線（上部＋左側、または下部＋右側）を使用する
• 見出しの下に下線のアクセント（太さ3～5pt）を配置する

タイポグラフィの処理：

• 極端なサイズのコントラスト（見出しは72pt、本文は11pt）
• 文字間隔を広くしたすべて大文字の見出し
• 大きなディスプレイ書体で番号付きセクションを表現する
• データ／統計／技術的な内容に等幅フォント（Courier New）を使用する
• 情報量が多い箇所には幅の狭いフォント（Arial Narrow）を使用する
• 強調する箇所にはアウトライン文字を使用する

グラフとデータのスタイル：

• 重要なデータに単一のアクセントカラーを使用したモノクロのグラフ
• 縦棒グラフではなく横棒グラフを使用する
• 棒グラフではなくドットプロットを使用する
• グリッド線を最小限にする、または使用しない
• 凡例は使わず、要素に直接データラベルを付ける
• 重要な指標は大きな数字で表示する

レイアウトの工夫：

• テキストを重ねたフルブリード画像
• ナビゲーション／コンテキスト用のサイドバー列（幅20～30%）
• モジュール式のグリッドシステム（3×3、4×4のブロック）
• ZパターンまたはFパターンでコンテンツを配置する
• 色付きの図形の上にフローティングテキストボックスを配置する
• 雑誌風の複数列レイアウト

背景の処理：

• スライドの40～60%を占める単色のブロック
• グラデーションの塗りつぶし（垂直または斜めのみ）
• 背景を2色に分割する（斜めまたは垂直）
• 端から端まで広がる色の帯
• デザイン要素としてネガティブスペースを活用する

レイアウトのヒント

グラフや表を含むスライドを作成する場合：

• 2列レイアウト（推奨）：幅いっぱいにヘッダーを配置し、その下を2列に分けます。片方の列にはテキスト／箇条書き、もう片方の列には主要なコンテンツを配置します。これによりバランスがよくなり、グラフや表も読みやすくなります。各コンテンツタイプに合わせてスペースを最適化するため、列幅に差をつけたフレックスボックス（例：40%／60%）を使用します。
• スライド全体を使うレイアウト：インパクトと読みやすさを最大限に高めるため、主要なコンテンツ（グラフ／表）をスライド全体に配置します。
• 縦方向に積み重ねないでください：1列の中でテキストの下にグラフ／表を配置しないでください。読みやすさが損なわれ、レイアウトにも問題が生じます。

ワークフロー

1. 必須 — ファイル全体を読む：html2pptx.md を最初から最後まで完全に読んでください。このファイルを読む際に、範囲を指定してはいけません。プレゼンテーションの作成に進む前に、詳細な構文、重要な書式ルール、ベストプラクティスを把握するため、ファイルの内容全体を読んでください。
2. 各スライドについて、適切な寸法（例：16:9 の場合は 720pt × 405pt）で HTML ファイルを作成します。
   • すべてのテキストコンテンツに <p>、<h1>〜<h6>、<ul>、<ol> を使用します。
   • グラフや表を追加する領域には class="placeholder" を使用します（視認できるよう、グレーの背景でレンダリングします）。
   • 重要：グラデーションとアイコンは、HTML で参照する前に Sharp を使って PNG 画像にラスタライズします。
   • レイアウト：グラフ、表、画像があるスライドでは、読みやすさを高めるため、スライド全体を使うレイアウトか 2 列レイアウトを使用します。
3. html2pptx.js ライブラリを使って HTML スライドを PowerPoint に変換し、プレゼンテーションを保存する JavaScript ファイルを作成して実行します。
   • html2pptx() 関数を使って、各 HTML ファイルを処理します。
   • PptxGenJS API を使って、プレースホルダー領域にグラフや表を追加します。
   • pptx.writeFile() を使って、プレゼンテーションを保存します。
4. 視覚的な検証：サムネイルを生成して、レイアウトに問題がないか確認します。
   • サムネイルのグリッドを作成します：python scripts/thumbnail.py output.pptx workspace/thumbnails --cols 4
   • サムネイル画像を読み込み、次の点を注意深く確認します。
     • テキストの切れ：ヘッダーバー、図形、またはスライドの端でテキストが切れていないか
     • テキストの重なり：テキストが他のテキストや図形と重なっていないか
     • 配置の問題：コンテンツがスライドの境界や他の要素に近すぎないか
     • コントラストの問題：背景色に対してテキストの色が読みやすいか
   • 問題が見つかった場合は、HTML を修正して PPTX とサムネイルを再生成します。
5. pptx.writeFile('presentation.pptx') を使って、プレゼンテーションを保存します。

テンプレートを使った新しい PowerPoint プレゼンテーションの作成

このワークフローは、実際のコンテンツに置き換えるプレースホルダーテキストが含まれるテンプレートから、プレゼンテーションを作成するためのものです。

ワークフロー

1. 必須 — ファイル全体を読む：XML のリファレンスとして、まず ooxml.md を完全に読んでください。

2. テンプレートを作業用ファイルにコピーする 変更するテンプレートの作業用コピーを作成します：cp template.pptx working.pptx

3. テンプレートのサムネイルグリッドを作成する：利用できるすべてのスライドを確認します。

   python scripts/thumbnail.py template.pptx workspace/thumbnails --cols 4
   

4. コンテンツ要件に基づいてスライドを並べ替える

   python scripts/rearrange.py template.pptx working.pptx 0,5,12,12,23
   

   • 希望する順序で、0 から始まるスライド番号を指定します。
   • スライドは複製できます（例：12,12 はスライド 12 を 2 回使用します）。
   • 欠けている番号のスライドはすべて省略されます。

5. 作業用プレゼンテーションからテキスト一覧を抽出する

   python scripts/inventory.py working.pptx text-inventory.json
   

   • text-inventory.json を読む：すべての図形とそのプロパティを把握するため、text-inventory.json ファイル全体を読んでください。このファイルを読む際に、範囲を指定してはいけません。

   • インベントリ JSON の構造：

       {
         "slide-0": {
           "shape-0": {
             "placeholder_type": "TITLE",  // or null for non-placeholders
             "left": 1.5,                  // position in inches
             "top": 2.0,
             "width": 7.5,
             "height": 1.2,
             "paragraphs": [
               {
                 "text": "Paragraph text",
                 // Optional properties (only included when non-default):
                 "bullet": true,           // explicit bullet detected
                 "level": 0,               // only included when bullet is true
                 "alignment": "CENTER",    // CENTER, RIGHT (not LEFT)
                 "space_before": 10.0,     // space before paragraph in points
                 "space_after": 6.0,       // space after paragraph in points
                 "line_spacing": 22.4,     // line spacing in points
                 "font_name": "Arial",     // from first run
                 "font_size": 14.0,        // in points
                 "bold": true,
                 "italic": false,
                 "underline": false,
                 "color": "FF0000"         // RGB color
               }
             ]
           }
         }
       }
     

   • 主な機能：

     • スライド：「slide-0」、「slide-1」などの名前が付けられます。
     • 図形：視覚的な位置（上から下、左から右）の順に「shape-0」、「shape-1」などの名前が付けられます。
     • プレースホルダーの種類：TITLE、CENTER_TITLE、SUBTITLE、BODY、OBJECT、または null
     • 既定のフォントサイズ：利用可能な場合、レイアウトのプレースホルダーから抽出されたポイント単位の default_font_size
     • スライド番号は除外：SLIDE_NUMBER プレースホルダータイプの図形は、インベントリから自動的に除外されます。
     • 箇条書き：bullet: true の場合、level は常に含まれます（0 の場合も含みます）。
     • 間隔：ポイント単位の space_before、space_after、line_spacing（設定されている場合のみ含まれます）
     • 色：RGB カラーの color（例：「FF0000」）、テーマカラーの theme_color（例：「DARK_1」）
     • プロパティ：既定値以外の値のみが出力に含まれます。

6. 置換テキストを生成し、データを JSON ファイルに保存する 前の手順で取得したテキスト一覧に基づいて、以下を行います。

   • 重要：まず、一覧に存在する図形を確認してください。実際に存在する図形のみを参照してください
   • 検証：replace.py スクリプトは、置換用 JSON 内のすべての図形が一覧に存在することを検証します
     • 存在しない図形を参照すると、利用可能な図形を示すエラーが表示されます
     • 存在しないスライドを参照すると、そのスライドが存在しないことを示すエラーが表示されます
     • スクリプトの終了前に、すべての検証エラーがまとめて表示されます
   • 重要：replace.py スクリプトは、内部で inventory.py を使用してすべてのテキスト図形を特定します
   • 自動クリア：テキスト一覧にあるすべてのテキスト図形は、"paragraphs" を指定しない限りクリアされます
   • 内容が必要な図形には、"paragraphs" フィールドを追加してください（"replacement_paragraphs" ではありません）
   • 置換用 JSON で "paragraphs" が指定されていない図形のテキストは、自動的にクリアされます
   • 箇条書きの段落は自動的に左揃えになります。"bullet": true の場合、alignment プロパティを設定しないでください
   • プレースホルダーテキストに適した置換コンテンツを生成します
   • 図形のサイズを参考に、適切なコンテンツの長さを決めます
   • 重要：元の一覧にある段落プロパティを含めてください。テキストだけを指定しないでください
   • 重要："bullet": true の場合、テキストに箇条書き記号（•、-、*）を含めないでください。記号は自動的に追加されます
   • 必須の書式ルール：
     • 見出し／タイトルには通常、"bold": true を指定してください
     • リスト項目には "bullet": true, "level": 0 を指定してください（"bullet": true の場合、level は必須です）
     • 配置プロパティを維持してください（例：中央揃えのテキストには "alignment": "CENTER"）
     • デフォルトと異なる場合はフォントプロパティを含めてください（例："font_size": 14.0、"font_name": "Lora"）
     • 色：RGB には "color": "FF0000"、テーマカラーには "theme_color": "DARK_1" を使用します
     • 置換スクリプトでは、テキスト文字列だけでなく、適切に書式設定された段落が必要です
     • 重なり合う図形：デフォルトの font_size が大きい図形、またはより適切な placeholder_type を持つ図形を優先してください
   • 置換内容を含む更新済みの一覧を replacement-text.json に保存します
   • 警告：テンプレートのレイアウトによって図形の数は異なります。置換内容を作成する前に、必ず実際の一覧を確認してください

   適切な書式を設定した "paragraphs" フィールドの例：

   "paragraphs": [
     {
       "text": "New presentation title text",
       "alignment": "CENTER",
       "bold": true
     },
     {
       "text": "Section Header",
       "bold": true
     },
     {
       "text": "First bullet point without bullet symbol",
       "bullet": true,
       "level": 0
     },
     {
       "text": "Red colored text",
       "color": "FF0000"
     },
     {
       "text": "Theme colored text",
       "theme_color": "DARK_1"
     },
     {
       "text": "Regular paragraph text without special formatting"
     }
   ]
   

   置換用 JSON に記載されていない図形は、自動的にクリアされます：

   {
     "slide-0": {
       "shape-0": {
         "paragraphs": [...] // This shape gets new text
       }
       // shape-1 and shape-2 from inventory will be cleared automatically
     }
   }
   

   プレゼンテーションでよく使われる書式パターン：

   • タイトルスライド：太字テキスト。中央揃えにする場合もあります
   • スライド内のセクション見出し：太字テキスト
   • 箇条書き：各項目に "bullet": true, "level": 0 が必要です
   • 本文：通常、特別なプロパティは不要です
   • 引用：特別な配置やフォントプロパティが使われる場合があります

7. replace.py スクリプトを使用して置換を適用する

   python scripts/replace.py working.pptx replacement-text.json output.pptx
   

   スクリプトは次の処理を行います。

   • まず、inventory.py の関数を使用してすべてのテキスト図形の一覧を抽出します
   • 置換用 JSON 内のすべての図形が一覧に存在することを検証します
   • 一覧で特定されたすべての図形のテキストをクリアします
   • 置換用 JSON で "paragraphs" が定義されている図形にのみ新しいテキストを適用します
   • JSON の段落プロパティを適用して書式を維持します
   • 箇条書き、配置、フォントプロパティ、色を自動的に処理します
   • 更新済みのプレゼンテーションを保存します

   検証エラーの例：

   ERROR: Invalid shapes in replacement JSON:
     - Shape 'shape-99' not found on 'slide-0'. Available shapes: shape-0, shape-1, shape-4
     - Slide 'slide-999' not found in inventory
   

   ERROR: Replacement text made overflow worse in these shapes:
     - slide-0/shape-2: overflow worsened by 1.25" (was 0.00", now 1.25")
   

サムネイルグリッドの作成

PowerPoint スライドのサムネイルグリッドを視覚的に作成し、すばやく分析および参照するには、次のようにします。

python scripts/thumbnail.py template.pptx [output_prefix]

機能：

• 作成されるファイル：thumbnails.jpg（または、大規模なデッキの場合はthumbnails-1.jpg、thumbnails-2.jpgなど）
• デフォルト：5 列、グリッドあたり最大 30 枚のスライド（5×6）
• カスタムプレフィックス：python scripts/thumbnail.py template.pptx my-grid
  • 注：特定のディレクトリに出力する場合は、出力プレフィックスにパスを含めてください（例：workspace/my-grid）
• 列数の調整：--cols 4（範囲：3～6。グリッドあたりのスライド数に影響します）
• グリッドの上限：3 列＝グリッドあたり 12 枚、4 列＝20 枚、5 列＝30 枚、6 列＝42 枚
• スライドのインデックスは 0 から始まります（Slide 0、Slide 1 など）

用途：

• テンプレート分析：スライドのレイアウトやデザインパターンをすばやく把握できます
• コンテンツの確認：プレゼンテーション全体を視覚的に確認できます
• ナビゲーション用の参照：見た目から特定のスライドを見つけられます
• 品質チェック：すべてのスライドが正しくフォーマットされていることを確認できます

例：

# Basic usage
python scripts/thumbnail.py presentation.pptx

# Combine options: custom name, columns
python scripts/thumbnail.py template.pptx analysis --cols 4

スライドを画像に変換する

PowerPoint スライドを視覚的に分析するには、次の 2 段階の手順で画像に変換します。

1. PPTX を PDF に変換する：

   soffice --headless --convert-to pdf template.pptx
   

2. PDF のページを JPEG 画像に変換する：

   pdftoppm -jpeg -r 150 template.pdf slide
   

   これにより、slide-1.jpg、slide-2.jpgなどのファイルが作成されます。

オプション：

• -r 150：解像度を 150 DPI に設定します（画質とファイルサイズのバランスに応じて調整してください）
• -jpeg：出力形式を JPEG に設定します（PNG がよい場合は-pngを使用してください）
• -f N：変換する最初のページ（例：-f 2では 2 ページ目から開始します）
• -l N：変換する最後のページ（例：-l 5では 5 ページ目で終了します）
• slide：出力ファイルのプレフィックス

特定の範囲を指定する例：

pdftoppm -jpeg -r 150 -f 2 -l 5 template.pdf slide  # Converts only pages 2-5

コードスタイルのガイドライン

重要：PPTX 操作用のコードを生成する際は、次の点に従ってください。

• 簡潔なコードを書く
• 冗長な変数名や重複する処理を避ける
• 不要な print 文を避ける

依存関係

必要な依存関係（すでにインストールされているはずです）：

• markitdown：pip install "markitdown[pptx]"（プレゼンテーションからテキストを抽出するため）
• pptxgenjs：npm install -g pptxgenjs（html2pptx 経由でプレゼンテーションを作成するため）
• playwright：npm install -g playwright（html2pptx で HTML をレンダリングするため）
• react-icons：npm install -g react-icons react react-dom（アイコン用）
• sharp：npm install -g sharp（SVG のラスタライズと画像処理用）
• LibreOffice：sudo apt-get install libreoffice（PDF 変換用）
• Poppler：sudo apt-get install poppler-utils（PDF を画像に変換する pdftoppm 用）
• defusedxml：pip install defusedxml（安全な XML 解析用）