mermaid-to-gif

スキル：Mermaid から GIF への変換

Mermaid 図を、豊かなアニメーション効果を加えた GIF に変換します。.mmd ファイルに対応し、.md ファイルから ```mermaid コードブロックを抽出することもできます。

前提条件：FFmpeg、Python 3.8 以降、Playwright（pip install playwright && playwright install chromium）

---

使用する場面

• Mermaid 図をアニメーション GIF に変換したい場合
• .mmd ファイル、または Mermaid コードブロックを含む .md ファイルがある場合
• プレゼンテーション、ドキュメント、ソーシャルメディア向けのアニメーション画像が必要な場合
• 1 つのドキュメント内にあるすべての Mermaid ブロックを一括変換したい場合

---

コンテキストに応じたスタイル選択

重要：.md ファイルから Mermaid ブロックを変換する場合は、周囲の Markdown コンテキストを読んで、図ごとに最も適切なアニメーションスタイルを選択してください。すべてのブロックに同じスタイルをむやみに適用しないでください。

選択ガイド

1. 各 Mermaid ブロックの周囲にある Markdown テキストを読む — 図が何を表しているかを理解します
2. 意味に合わせてスタイルを選ぶ：

コンテキストの手がかり	推奨スタイル	理由
データパイプライン、ETL フロー、リクエスト／レスポンス経路	pulse-flow	流れる破線がデータの移動を表現します
アーキテクチャのレイヤー、組織図、階層	progressive	要素がレイヤーごとに順番にアクティブになります
段階的なプロセス、チュートリアル形式の手順	highlight-walk	スポットライトが各ステップを順番に案内します
システム概要、タイトル図、シンプルな参考図	wave	明るさの波紋が、邪魔にならない程度に動きを加えます
メッセージの流れを示すシーケンス図	progressive	メッセージが会話の順序に沿って 1 つずつアクティブになります
クラス図／ER 図（参考用／静的）	progressive または wave	構造が順に明るくなるか、控えめな波紋が加わります

3. 特別な処理を検討する：

   • 周囲のテキストに「A から B へデータが流れる」とある場合は、単純なフローチャートでも pulse-flow を使います
   • テキストで「3 つのレイヤー」や「2 層」と説明されている場合は、レイヤーごとにアクティブにする progressive を使います
   • 図が装飾的または補足的なものである場合は、シンプルさを保つため wave を使います
   • 非常に大きい図や複雑な図では、GIF のサイズを適切に保つため、wave または短めの --duration を優先します

4. ブロックごとのスタイル上書き：.md ファイルを一括処理する場合は、特定のブロックを抽出して異なるスタイルでスクリプトを複数回実行する必要があるかもしれません。または、適切なデフォルト設定でファイル全体を処理し、個別の対応が必要なブロックだけ再実行してください。

例：コンテキストに応じた処理

## Data Ingestion Pipeline        ← context: "pipeline" → pulse-flow
[mermaid block: graph LR with ETL stages]

## System Architecture            ← context: "architecture" → progressive
[mermaid block: graph TD with layers]

## Quick Reference                ← context: "reference" → wave
[mermaid block: simple diagram]

---

デフォルトのワークフロー

単一の .mmd ファイル

python <skill-root>/scripts/mermaid_to_gif.py diagram.mmd

Mermaid ブロックを含む Markdown ファイル

python <skill-root>/scripts/mermaid_to_gif.py document.md -o ./images/

これにより、すべての ```mermaid コードブロックが抽出され、ブロックごとに GIF が 1 つ生成されます。

複数のファイル

python <skill-root>/scripts/mermaid_to_gif.py *.mmd -o ./gifs/
python <skill-root>/scripts/mermaid_to_gif.py doc1.md doc2.md -o ./gifs/

Markdown 内の Mermaid ブロックを置き換える

GIF を生成した後、元の ```mermaid コードブロックを画像への参照に置き換えます。

![Flow Diagram](images/document-1.gif)

図の内容に基づいた、わかりやすい代替テキストを使用してください。画像のパスは Markdown ファイルからの相対パスにします。

---

アニメーションスタイル

すべてのスタイルで、図は最初のフレームから完全に表示されます。要素が非表示の状態で始まったり、透明度ゼロからフェードインしたりすることはありません。どのスタイルでも、図の構造全体を常に見られる状態で動きを加えます。

スタイル	効果	最適な用途
progressive（デフォルト）	すべての要素が暗い状態（不透明度 25%）で始まり、順番に完全な明るさになります。エッジはストロークアニメーションで描画されます	フローチャート、アーキテクチャ、階層
highlight-walk	すべての要素が暗い状態（不透明度 15%）で始まります。青い光彩を伴うスポットライトが各要素を移動し、通過した要素を明るい状態に保ちます	段階的なプロセス、チュートリアル
pulse-flow	すべての要素が完全に表示されます。エッジが流れる破線になります（破線のサイズと速度は均一です）	データフロー、パイプライン、リクエスト経路
wave	すべての要素が完全に表示されます。明るさのパルスと青い光彩の波紋が要素を順番に移動します	シンプルな図、概要図、参考図

アニメーションの詳細

• progressive：要素は不透明度25％で開始します（図の構造は常に表示されます）。ノード、エッジ、ラベルがフローの方向に沿って交互の順序（ノード → エッジ → ノード → エッジ）でアクティブになります。エッジは stroke-dashoffset を使って視覚的に描画されます。アクティブ化は高速で、各要素にかかる時間は全体の長さの8％です。
• highlight-walk：すべての要素は不透明度15％で開始します。青いグローを伴うスポットライトが順番に要素を移動し、通過した要素は不透明度90％になります。スポットライトが各要素に到達する前から、図全体が「ゴースト」として表示されます。
• pulse-flow：すべての要素が不透明度100％で表示されます。エッジのパスには均一な破線パターン（ダッシュ10px＋間隔6px）が適用され、一定速度（1サイクルあたり200px）で流れます。これにより、長さに関係なく、すべてのエッジが同じペースでアニメーションします。
• wave：すべての要素が不透明度100％で表示されます。青いグローを伴う明るさのパルス（1.0→1.4→1.0）が、要素を順番になぞるように移動します。位置は変化せず、視覚的な波紋効果のみが生じます。

---

共通オプション

フラグ	デフォルト	説明
-o, --output-dir	入力と同じ	生成されたGIFの出力ディレクトリ
-s, --style	progressive	アニメーションスタイル（上の表を参照）
--fps	10	1秒あたりのフレーム数
--duration	4.0	アニメーションの長さ（秒）
--hold	1.0	ループ開始前に最終フレームを保持する時間（秒）
--theme	default	Mermaid のテーマ：default、dark、forest、neutral
--bg	#ffffff	背景色（16進数）
--padding	40	図の周囲の余白（ピクセル）
--scale	2	レンダリング倍率（2 = Retina 品質）
--custom-css	—	カスタム CSS ファイルのパス
--no-loop	—	GIFをループせずに1回だけ再生

---

使用例

# Dark theme with faster animation
python <skill-root>/scripts/mermaid_to_gif.py arch.mmd --theme dark --bg "#1a1a2e" --duration 3

# High FPS for smoother animation
python <skill-root>/scripts/mermaid_to_gif.py flow.mmd --fps 15 --duration 5

# Batch convert all mermaid blocks from a doc
python <skill-root>/scripts/mermaid_to_gif.py README.md -o ./images/

# Custom CSS for special effects
python <skill-root>/scripts/mermaid_to_gif.py diagram.mmd --custom-css my-style.css

# No loop, suitable for one-time playback
python <skill-root>/scripts/mermaid_to_gif.py intro.mmd --no-loop --duration 6

# Lower resolution for smaller file size
python <skill-root>/scripts/mermaid_to_gif.py diagram.mmd --scale 1

---

カスタム CSS

アニメーション中の図の外観をカスタマイズするには、CSS ファイルを作成します。

/* Rounded nodes with shadow */
.node rect {
    rx: 10;
    filter: drop-shadow(2px 2px 4px rgba(0,0,0,0.3));
}

/* Thicker edge lines */
.edgePath path {
    stroke-width: 2.5;
}

/* Custom background for actors (sequence diagram) */
.actor {
    fill: #e8f4f8;
}

--custom-css で指定します。

python <skill-root>/scripts/mermaid_to_gif.py diagram.mmd --custom-css my-style.css

---

動作の仕組み

1. 入力の解析 — .mmd または .md ファイルから Mermaid コードを抽出します
2. HTML の生成 — Mermaid.js（CDN）とアニメーション用 JS/CSS を埋め込んだ、自己完結型の HTML ファイルを生成します
3. レンダリング — Playwright 経由で、ヘッドレス Chromium 上の Mermaid.js が図を SVG としてレンダリングします（Retina 品質にするため、デバイス倍率は2倍です）
4. 拡大縮小 — 小さな SVG は、読みやすさを確保するため、CSS 上の幅が最小700pxになるよう自動的に拡大されます
5. アニメーション — JS アニメーションエンジンが、フレーム単位で制御するための setProgress(t) を公開します（t：0→1）。要素を収集し、位置で並べ替えた後（LR/TB の方向を考慮）、ノードとエッジを交互にアニメーションさせます
6. キャプチャ — Playwright が各フレームのタイミングでスクリーンショットを撮影します
7. 組み立て — FFmpeg による2パスのパレットエンコードを行います（palettegen → Floyd-Steinberg ディザリングを使用した paletteuse）

---

重要な注意事項

• インターネット接続が必要：レンダリング時に Mermaid.js を CDN から読み込みます
• 対応する図の種類：フローチャート、シーケンス図、クラス図、状態図、ER 図、gitgraph、マインドマップ、円グラフ、ガントチャートなど
• 非表示の要素はありません：4つのスタイルすべてで、最初のフレームから図が表示されます。要素が現れるまで待つ必要はありません
• フォールバック動作：認識できない図の種類の場合、またはアニメーション可能な要素が検出されない場合は、図全体の不透明度を徐々に上げる表示に切り替わります
• 解像度：デフォルトの scale=2 では、Retina 品質（幅約1400～1600px）の画像が生成されます。ファイルを小さくするには --scale 1 を使用してください
• GIF のサイズ：出力が非常に大きい場合は、FPS を8に下げる、長さを短くする、--scale 1 を使用する、または wave スタイルを使用してください