BACK HOME

rsvg-convert の独自実装について

1 概要

pub_markdown では、rsvg-convert を独自実装している。
このスクリプトは、Pandoc で SVG ファイルを含む DOCX ファイルを生成する際に、標準の rsvg-convert の代替として動作する Puppeteer ベースの SVG→PNG 変換ツールである。

2 背景と目的

2.1 Pandoc の画像変換の仕組み

Pandoc が Markdown やその他の形式から DOCX ファイルを生成する際、SVG 画像は直接 DOCX に埋め込むことができない。そのため、以下の流れで処理される。

SVG 検出: ドキュメント内の SVG 画像を識別する
PNG 変換: SVG を PNG 形式に変換 (rsvg-convert を使用)
DOCX 埋め込み: 変換した PNG を DOCX ファイルに埋め込む

2.2 標準 rsvg-convert の課題

従来の rsvg-convert には以下の制約がある。

フォント互換性: システムにインストールされていないフォントの処理が困難
Web フォント対応: オンラインフォントや CSS [@import] の処理が限定的
レンダリング品質: 一部の複雑な SVG 要素で期待通りの出力が得られない場合

2.3 本スクリプトの利点

Puppeteer を使用することで以下の改善を実現している。

高いフォント互換性: Chromium エンジンによる豊富なフォント対応
高解像度出力: DPI 設定に基づく高精細 PNG 生成
完全な SVG 仕様対応: モダンブラウザと同等のレンダリング品質

3 アーキテクチャ

3.1 ファイル構成

rsvg-convert.exe    # Windows 用エントリーポイント
rsvg-convert.cmd    # Windows 用バッチファイル (rsvg-convert.exe から起動)
rsvg-convert        # Linux 用シェルファイル (エントリーポイント)
rsvg-convert.js     # メインの Node.js スクリプト

3.2 処理フロー

4 技術仕様

4.1 サポートされるオプション

スクリプトは標準 rsvg-convert と互換性のある以下のオプションをサポートする。

-f png: 出力形式 (PNG 固定)
--dpi-x N: 水平解像度 (デフォルト: 96)
--dpi-y N: 垂直解像度 (デフォルト: 96)

4.2 高解像度レンダリング

const scale = Math.max(dpiX, dpiY) * 3 / 96;

指定された DPI の 3 倍でレンダリングを行い、高精細な出力を実現している。

4.3 SVG サイズ決定アルゴリズム

優先順位に従って SVG の実際のサイズを決定する。

width/height 属性: width="100px" height="50px" など単位付き値
viewBox 属性: viewBox="0 0 100 50" の幅・高さ
実レンダリングサイズ: ブラウザでの実際の描画サイズ

4.4 単位変換対応

SVG で使用される各種単位を正確にピクセルに変換する。

px: そのまま (基準単位)
pt: 1pt = 1.25px
pc: 1pc = 15px
mm: 1mm ≈ 3.78px
cm: 1cm = 37.8px
in: 1in = 96px

5 使用方法

5.1 Pandoc での利用

通常の Pandoc 使用時に、システムの rsvg-convert の代わりに本スクリプトが自動的に呼び出される。

pandoc input.md -o output.docx

5.2 直接実行

コマンドラインから直接 SVG 変換も可能である。

echo "<svg width='100' height='100'>...</svg>" | node rsvg-convert.js

echo "<svg>...</svg>" | node rsvg-convert.js --dpi-x 300 --dpi-y 300

5.3 最適化ポイント

--no-sandbox フラグでセキュリティオーバーヘッドを削減
waitUntil:'load' で外部リソースの完全読み込みを保証
omitBackground:true で透明背景を維持

6 エラーハンドリング

主要なエラーケースと対応を以下に示す。

空の STDIN: 終了コード 2 で異常終了
非 PNG 形式指定: 終了コード 1 で異常終了
Puppeteer エラー: 終了コード 3 で詳細エラー出力

7 前提事項、制約事項

PNG 出力のみサポート (SVG、PDF 等は未対応)
Node.js + Puppeteer 環境が必要