drawio-to-png

Draw.io から PNG への変換

draw.io デスクトップのコマンドラインインターフェースまたはヘッドレスブラウザー自動化を使用して、draw.io の図ファイルを高解像度の PNG 画像に変換します。

概要

このスキルでは、draw.io 形式のファイル（.drawio、.dio、.xml）を高品質な PNG 画像に変換する方法を説明します。バッチ変換、解像度のカスタム設定、透明な背景、複数ページの図のページ選択に対応しています。

使用する場面

次のような場合にこのスキルを使用します。

• ドキュメント用に draw.io の図を PNG に変換する
• プレゼンテーションや記事用に図をエクスポートする
• Web 公開用に draw.io ファイルから画像を生成する
• 複数の図ファイルを一括処理する
• 印刷物用に高 DPI の画像を作成する

トリガーフレーズ

• "convert drawio to png"
• "export drawio diagram"
• "generate png from drawio"
• "drawio导出png"
• "转换drawio图片"
• "drawio转图片"
• "生成高清drawio图片"
• "批量导出drawio"

変換方法

方法 1：draw.io デスクトップ CLI を使用する（推奨）

draw.io の公式デスクトップアプリケーションには、変換用のコマンドラインインターフェースが用意されています。

インストール：

# macOS
brew install --cask drawio

# Or download from: https://github.com/jgraph/drawio-desktop/releases

基本的な変換：

# Convert single file
/Applications/draw.io.app/Contents/MacOS/draw.io -x -f png -o output.png input.drawio

# With custom scale (higher DPI)
/Applications/draw.io.app/Contents/MacOS/draw.io -x -f png -s 2 -o output.png input.drawio

# Transparent background
/Applications/draw.io.app/Contents/MacOS/draw.io -x -f png --transparent -o output.png input.drawio

# Export specific page (for multi-page diagrams)
/Applications/draw.io.app/Contents/MacOS/draw.io -x -f png -p 0 -o output.png input.drawio

パラメーター：

• -x：エクスポートモード
• -f png：出力形式（png）
• -o：出力ファイルのパス
• -s <scale>：スケール係数（1.0 = 100%、2.0 = 200% など）
• --transparent：透明な背景
• -p <page>：複数ページの図のページインデックス（0 始まり）
• -w <width>：カスタム幅（ピクセル単位）
• -h <height>：カスタム高さ（ピクセル単位）
• --border <size>：境界線のサイズ（ピクセル単位）

方法 2：draw.io Web と Puppeteer を使用する

ヘッドレスブラウザー自動化を使用して、draw.io の Web インターフェース経由で図をレンダリングします。

インストール：

npm install puppeteer

変換スクリプト（scripts/convert-with-puppeteer.js を参照）：

const puppeteer = require('puppeteer');
const fs = require('fs');
const path = require('path');

async function convertDrawioToPng(inputPath, outputPath, options = {}) {
  const {
    scale = 2,
    transparent = true,
    page = 0
  } = options;

  const browser = await puppeteer.launch();
  const browserPage = await browser.newPage();
  
  // Set viewport for high DPI
  await browserPage.setViewport({
    width: 1920,
    height: 1080,
    deviceScaleFactor: scale
  });

  // Read drawio file
  const drawioContent = fs.readFileSync(inputPath, 'utf8');
  const encoded = encodeURIComponent(drawioContent);
  
  // Load in draw.io viewer
  await browserPage.goto(`https://viewer.diagrams.net/?lightbox=1&edit=_blank#R${encoded}`);
  
  // Wait for diagram to render
  await browserPage.waitForSelector('.geDiagramContainer', { timeout: 10000 });
  await browserPage.waitForTimeout(1000);

  // Take screenshot
  const element = await browserPage.$('.geDiagramContainer');
  await element.screenshot({
    path: outputPath,
    omitBackground: transparent
  });

  await browser.close();
}

方法 3：@diagram.net/drawio-cli を使用する（Docker）

Docker ベースの公式 CLI ツールです。

インストール：

docker pull rlespinasse/drawio-cli

変換：

docker run --rm -v "$(pwd):/data" rlespinasse/drawio-cli \
  -x -f png -s 2 -o /data/output.png /data/input.drawio

ワークフロー

単一ファイルの変換

1. draw.io ファイル形式を検出する

   • ファイルが存在し、有効な形式（.drawio、.dio、.xml）であることを確認します
   • ファイルが XML 形式で、draw.io の構造を含んでいることを確認します

2. 出力先のパスを決定する

   • 既定値：同じディレクトリに、拡張子を .png に変更した同じ名前で出力します
   • カスタムの出力先が必要かどうかをユーザーに確認します

3. オプションを設定する

   • スケール係数（既定値：高 DPI 用に 2）
   • 透明な背景（既定値：true）
   • ページ選択（複数ページの場合）

4. 変換を実行する

   • 主な方法として draw.io CLI（方法 1）を使用します
   • CLI が利用できない場合は Puppeteer に切り替えます

5. 出力を確認する

   • PNG ファイルが作成されたことを確認します
   • ファイルサイズが妥当であることを確認します
   • 出力先のパスをユーザーに示します

バッチ変換

1. ディレクトリ内の draw.io ファイルをスキャンする

   find . -type f \( -name "*.drawio" -o -name "*.dio" -o -name "*.xml" \)
   

2. 有効な draw.io ファイルを絞り込む

   • 図ではない XML ファイルを除外します
   • ファイルの内容に draw.io の構造が含まれていることを確認します

3. 各ファイルを処理する

   • 同じ命名規則を使用します（拡張子を .png に置き換えます）
   • 一貫したエクスポート設定を適用します
   • 各ファイルの成功または失敗を記録します

4. 結果を報告する

   • 変換に成功したファイルを一覧表示します
   • 失敗があれば、その理由とともに報告します
   • 合計件数と出力先を示します

よくある使用例

ドキュメント用

# Export with border for better visibility
drawio -x -f png -s 2 --border 10 -o docs/images/architecture.png architecture.drawio

プレゼンテーションのスライド用

# High resolution with transparent background
drawio -x -f png -s 3 --transparent -o slides/diagram.png diagram.drawio

Web 公開用

# Moderate resolution to balance quality and file size
drawio -x -f png -s 1.5 -o public/images/flowchart.png flowchart.drawio

複数ページの図

# Export all pages
for i in {0..4}; do
  drawio -x -f png -s 2 -p $i -o "output-page-$i.png" multi-page.drawio
done

品質設定

スケール係数のガイドライン

• 1.0：標準解像度（72～96 DPI）— Web サムネイル用
• 2.0：高解像度（144～192 DPI）— 標準エクスポート用（推奨）
• 3.0：非常に高い解像度（216～288 DPI）— プレゼンテーション用
• 4.0：印刷品質（288～384 DPI）— プロ向け印刷用

ファイルサイズに関する考慮事項

• スケールが高いほど、ファイルサイズが大きくなります
• 透明な背景にすると、ファイルサイズが若干増加します
• 図形の多い複雑な図ほど、ファイルサイズが大きくなります
• Web で使用する場合は、圧縮を検討してください

エラー処理

よくある問題

1. draw.io CLI が見つからない

   • draw.io デスクトップがインストールされているか確認します
   • パスを確認します：/Applications/draw.io.app/Contents/MacOS/draw.io（macOS）
   • 別の方法（Puppeteer または Docker）を試します

2. draw.io ファイルが無効

   • ファイルが XML 形式であることを確認します
   • ファイルの内容が破損していないか確認します
   • draw.io デスクトップで開いて検証します

3. エクスポートが失敗しても何も表示されない

   • ディスク容量を確認します
   • 出力ディレクトリへの書き込み権限を確認します
   • 問題を切り分けるため、よりシンプルな図で試します

4. 出力が空白、または一部しか表示されない

   • 複雑な図の場合は待機時間を延長します
   • 外部画像への参照がないか確認します
   • 必要なフォントがすべて利用可能か確認します

ベストプラクティス

1. バージョン管理

   • .drawio ソースファイルをバージョン管理に含めます
   • PNG ファイルは必要に応じて再生成します（コミットしないでください）
   • CI/CD を使用して画像を自動生成します

2. 命名規則

   • .drawio ファイルと .png ファイルに同じ名前を使用します
   • 異なるスケールには接尾辞を付けます：diagram-2x.png、diagram-3x.png
   • 複数ページの場合はページ番号を含めます：flow-page-1.png

3. 自動化

   • 一括変換用の npm スクリプトまたは Makefile を作成します
   • ファイルの変更を監視して自動的に再生成します
   • ドキュメントのビルドプロセスに統合します

4. 最適化

   • 用途に適したスケールを使用します
   • pngquant や optipng などのツールで PNG ファイルを圧縮します
   • Web 用には SVG エクスポートを検討します（ファイルサイズが小さく、拡大縮小できます）

代替形式

このスキルでは PNG エクスポートを中心に説明していますが、draw.io は次の形式にも対応しています：

• SVG：ベクター形式で、拡大縮小が可能で、ファイルサイズも小さくなります
• PDF：印刷に適しており、品質を維持できます
• JPEG：ファイルサイズが小さく、透過には対応せず、非可逆圧縮です

形式を柔軟に選択するには、scripts/convert.sh を使用します。

参考資料

references/ ディレクトリを参照してください：

• cli-reference.md：draw.io CLI の完全なドキュメント
• quality-guide.md：品質と DPI に関する詳細なガイドライン
• automation-examples.md：CI/CD 統合用のスクリプト

例

examples/ ディレクトリを参照してください：

• single-file.sh：単一ファイルの変換例
• batch-convert.sh：一括変換スクリプト
• watch-and-convert.sh：自動変換用のファイル監視ツール