pptx

PPTX の作成、編集、分析

概要

依頼に応じて、.pptx ファイルの内容を作成、編集、分析します。.pptx ファイルは基本的に、XML ファイルやその他のリソースを含む ZIP アーカイブです。タスクに応じて、さまざまなツールやワークフローを利用できます。

重要：最初にすべてのドキュメントを読む

プレゼンテーションに関する作業を始める前に、関連するすべてのドキュメントファイルを最後まで読み、ワークフロー全体を把握してください。

1. 新しいプレゼンテーションを作成する場合：html2pptx.md と css.md をすべて読んでください
2. 既存のプレゼンテーションを編集する場合：ooxml.md をすべて読んでください
3. テンプレートを使用して作成する場合：このファイルの関連セクションと css.md を読んでください

これらのファイルを読む際に、範囲の上限を設定してはいけません。 高品質なプレゼンテーションを作成するには、作業を始める前にワークフロー全体、制約、ベストプラクティスを把握することが不可欠です。部分的な知識では、エラーやスタイルの不統一、視覚的な欠陥が生じ、手戻りが必要になります。

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

テキストの抽出

プレゼンテーションのテキストのみを読むには、ドキュメントを 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/public/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. テーマファイルを読む：ppt/theme/theme1.xml で色（<a:clrScheme>）とフォント（<a:fontScheme>）を確認します
2. スライドの内容を確認する：ppt/slides/slide1.xml で実際に使用されているフォント（<a:rPr>）と色を調べます
3. パターンを検索する：grep を使用して、すべての XML ファイルから色（<a:solidFill>、<a:srgbClr>）とフォントの参照を検索します

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

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

ワークフロー

1. ドキュメントを読む：html2pptx.md と css.md をすべて読んでください（上記の「重要：最初にすべてのドキュメントを読む」セクションを参照）

2. 前提条件 - html2pptx ライブラリを展開する：

   • スクリプトの隣にライブラリを展開します：mkdir -p html2pptx && tar -xzf skills/public/pptx/html2pptx.tgz -C html2pptx
   • これにより、ライブラリファイルと CLI バイナリを含む html2pptx/ ディレクトリが作成されます

3. プレゼンテーションを計画する：html2pptx.md の「デザイン哲学」セクションに従って、次の項目を決めます：

   • 美的な方向性と大胆なデザインの選択
   • カラーパレットの選定（「カラーパレットの作成」を参照）
   • タイポグラフィ戦略
   • スライドのレイアウトと発表者ノートを含む詳細なアウトラインを作成します（各スライドにつき1～3文）

4. CSS 変数を設定する：共有 .css ファイルで CSS 変数を上書きし、色、タイポグラフィ、間隔を設定します（css.md の「デザインシステム変数」を参照）

5. HTML スライドを作成する（16:9 の場合は 960px × 540px）：html2pptx.md に従って、次の項目を確認します：

   • スライドのレイアウト領域（タイトル、コンテンツ、脚注）
   • 重要なテキストルール（適切な HTML タグ）
   • サポートされている要素とスタイル設定

6. html2pptx ライブラリを使用する JavaScript ファイルを作成して実行し、HTML スライドを PowerPoint に変換してプレゼンテーションを保存します

   • 次のコマンドで実行します：NODE_PATH="$(npm root -g)" node your-script.js 2>&1

   • html2pptx 関数を使用して各 HTML ファイルを処理します

   • PptxGenJS API を使用して、プレースホルダー領域にグラフや表を追加します

   • pptx.writeFile() を使用してプレゼンテーションを保存します

   • ⚠️ 重要： スクリプトは必ず次の例の構造に従ってください。API を正しく使用していることを確認するため、スクリプトを書く前に考えを整理してください。pptx.addSlide は呼び出さないでください。

   const pptxgen = require("pptxgenjs");
   const { html2pptx } = require("./html2pptx");
   
   // Create a new pptx presentation
   const pptx = new pptxgen();
   pptx.layout = "LAYOUT_16x9"; // Must match HTML body dimensions
   
   // Add an HTML-only slide
   await html2pptx("slide1.html", pptx);
   
   // Add a HTML slide with chart placeholders
   const { slide: slide2, placeholders } = await html2pptx("slide2.html", pptx);
   slide.addChart(pptx.charts.LINE, chartData, placeholders[0]);
   
   // Save the presentation
   await pptx.writeFile("output.pptx");
   

7. 視覚的な検証：画像に変換し、レイアウト上の問題がないか確認します

   • まず PPTX を PDF に変換します：soffice --headless --convert-to pdf output.pptx
   • 次に PDF を画像に変換します：pdftoppm -jpeg -r 150 output.pdf slide
     • slide-1.jpg、slide-2.jpg などのファイルが作成されます
   • 生成された画像ファイルを1つずつ読み込み、次の項目を慎重に確認します：
     • テキストの欠け：ヘッダーバー、図形、スライドの端によってテキストが切れていないか
     • テキストの重なり：テキストが他のテキストや図形と重なっていないか
     • 配置の問題：コンテンツがスライドの境界や他の要素に近すぎないか
     • コントラストの問題：テキストと背景のコントラストが不足していないか
     • 配置の整列：要素同士が適切に揃っているか
     • 視覚的な階層：重要なコンテンツが適切に強調されているか
   • 重要：ユーザーに納品する前に、すべてのスライドが必ずこれらの検証項目に合格している必要があります。 この手順を省略したり、視覚的な欠陥があるプレゼンテーションを納品したりしないでください。
   • 問題が見つかった場合は、次の優先順位で修正します：
     1. 余白を増やす - 問題のある要素の周囲にパディングや間隔を追加します
     2. フォントサイズを調整する - 使用可能なスペースに収まるようにテキストサイズを小さくします
     3. レイアウト全体を再検討する - 上記の修正で解決しない場合は、スライドのレイアウトを再設計します
   • 変更後、プレゼンテーションを再生成します
   • すべてのスライドが視覚的に問題なくなるまで繰り返します

既存の PowerPoint プレゼンテーションを編集する

既存の PowerPoint プレゼンテーションのスライドを編集するには、Office Open XML（OOXML）の生データ形式を使用します。.pptx ファイルを展開し、XML コンテンツを編集してから再パッケージ化します。

ワークフロー

1. ドキュメントを読む：ooxml.md をすべて読んでください（上記の「重要：最初にすべてのドキュメントを読む」セクションを参照）
2. プレゼンテーションを展開します：python ooxml/scripts/unpack.py <office_file> <output_dir>
3. XML ファイルを編集します（主に ppt/slides/slide{N}.xml と関連ファイル）
4. 重要：編集のたびに、すぐに検証します：python ooxml/scripts/validate.py <dir> --original <file>
5. 最終版のプレゼンテーションをパッケージ化します：python ooxml/scripts/pack.py <input_directory> <office_file>

テンプレートを使用して新しい PowerPoint プレゼンテーションを作成する

既存のテンプレートのデザインに沿ったプレゼンテーションを作成するには、プレースホルダーの内容を置き換える前に、テンプレートのスライドを複製して並べ替えます。

ワークフロー

1. テンプレートのテキストを抽出し、サムネイルのグリッドも作成する：

   • テキストを抽出します：python -m markitdown template.pptx > template-content.md
   • template-content.md を最後まで読み、テンプレートの内容を把握します
   • サムネイルのグリッドを作成します：python scripts/thumbnail.py template.pptx
   • 詳細は「サムネイルのグリッドを作成する」セクションを参照してください

2. テンプレートを分析し、インベントリをファイルに保存する：

   • 視覚的な分析：サムネイルのグリッドを確認し、スライドのレイアウト、デザインパターン、視覚的な構成を把握します

   • template-inventory.md にテンプレートのインベントリを作成して保存します。内容は次のとおりです：

     # Template Inventory Analysis
     
     **Total Slides: [count]**
     **IMPORTANT: Slides are 0-indexed (first slide = 0, last slide = count-1)**
     
     ## [Category Name]
     
     - Slide 0: [Layout code if available] - Description/purpose
     - Slide 1: [Layout code] - Description/purpose
     - Slide 2: [Layout code] - Description/purpose
       [... EVERY slide must be listed individually with its index ...]
     

   • サムネイルのグリッドを使用する：視覚的なサムネイルを参照して、次の点を特定します：

     • レイアウトパターン（タイトルスライド、コンテンツレイアウト、セクション区切り）
     • 画像プレースホルダーの位置と数
     • スライドグループ間でのデザインの一貫性
     • 視覚的な階層と構成

   • 次のステップで適切なテンプレートを選択するには、このインベントリファイルが必須です

3. テンプレートのインベントリに基づいてプレゼンテーションのアウトラインを作成する：

   • ステップ 2 で確認した利用可能なテンプレートを確認します。
   • 最初のスライドには、導入またはタイトル用のテンプレートを選択します。最初の方にあるテンプレートを使用してください。
   • その他のスライドには、安全なテキストベースのレイアウトを選択します。
   • 重要：レイアウトの構成を実際のコンテンツに合わせます：
     • 1 列レイアウト：一貫した説明や 1 つのトピックに使用します
     • 2 列レイアウト：明確に異なる項目や概念がちょうど 2 つある場合にのみ使用します
     • 3 列レイアウト：明確に異なる項目や概念がちょうど 3 つある場合にのみ使用します
     • 画像とテキストのレイアウト：挿入する画像が実際にある場合にのみ使用します
     • 引用レイアウト：人物の実際の引用（出典付き）にのみ使用し、強調目的では決して使用しません
     • 利用できるコンテンツよりプレースホルダーが多いレイアウトは使用しないでください
     • 項目が 2 つの場合、無理に 3 列レイアウトに当てはめないでください
     • 項目が 4 つ以上ある場合は、複数のスライドに分けるか、リスト形式を検討してください
   • レイアウトを選択する前に、実際のコンテンツの数を数えます
   • 選択したレイアウトの各プレースホルダーに、意味のあるコンテンツが入ることを確認します
   • 各コンテンツセクションに最適なレイアウトを 1 つ選択します。
   • デザインを活用したコンテンツとテンプレートの対応関係を含めて、outline.md を保存します
   • テンプレートの対応付けの例：

     # Template slides to use (0-based indexing)
     # WARNING: Verify indices are within range! Template with 73 slides has indices 0-72
     # Mapping: slide numbers from outline -> template slide indices
     template_mapping = [
         0,   # Use slide 0 (Title/Cover)
         34,  # Use slide 34 (B1: Title and body)
         34,  # Use slide 34 again (duplicate for second B1)
         50,  # Use slide 50 (E1: Quote)
         54,  # Use slide 54 (F2: Closing + Text)
     ]
     

4. rearrange.py を使ってスライドを複製、並べ替え、削除する：

   • scripts/rearrange.py スクリプトを使って、スライドを希望する順序に並べたプレゼンテーションを新規作成します。

     python scripts/rearrange.py template.pptx working.pptx 0,34,34,50,52
     

   • スクリプトが、スライドの複製、未使用スライドの削除、並べ替えを自動的に処理します。
   • スライドのインデックスは 0 始まりです（最初のスライドは 0、2 枚目は 1 など）。
   • 同じスライドのインデックスを複数回指定すると、そのスライドが複製されます。

5. inventory.py スクリプトを使ってすべてのテキストを抽出します：

   • インベントリを抽出します：

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

   • すべての図形とそのプロパティを把握するため、text-inventory.json を最後まで読みます。

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

     {
       "slide-0": {
         "shape-0": {
           "placeholder_type": "TITLE", // またはプレースホルダー以外の場合は null
           "left": 1.5, // インチ単位の位置
           "top": 2.0,
           "width": 7.5,
           "height": 1.2,
           "paragraphs": [
             {
               "text": "Paragraph text",
               // 任意のプロパティ（デフォルト値以外の場合のみ含まれます）：
               "bullet": true, // 明示的な箇条書きを検出
               "level": 0, // bullet が true の場合のみ含まれます
               "alignment": "CENTER", // CENTER、RIGHT（LEFT は含まれません）
               "space_before": 10.0, // 段落前の間隔（ポイント単位）
               "space_after": 6.0, // 段落後の間隔（ポイント単位）
               "line_spacing": 22.4, // 行間（ポイント単位）
               "font_name": "Arial", // 最初のランから取得
               "font_size": 14.0, // ポイント単位
               "bold": true,
               "italic": false,
               "underline": false,
               "color": "FF0000" // RGB カラー
             }
           ]
         }
       }
     }
     

   • 主な機能：

     • スライド：「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」が指定されていない場合、インベントリ内のすべてのテキスト図形が消去されます
   • コンテンツが必要な図形には、「replacement_paragraphs」ではなく「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（SVG 形式のアイコンを使用するため）
• LibreOffice：PDF への変換用（視覚的な検証手順に必要です）
  • macOS：brew install --cask libreoffice
  • Linux：sudo apt-get install libreoffice
• Poppler：sudo apt-get install poppler-utils（PDF を画像に変換する pdftoppm 用）
• defusedxml：pip install defusedxml（安全な XML 解析用）