ライブラリ

KatanA Render Runtime

図やTeX数式のソースをSVGへ変換するRustライブラリとCLIです。共通の入出力APIで描画結果と診断情報を受け取れます。

図や数式のSVGレンダリングをアプリへ組み込むRust開発者

01

実装済みの機能

Mermaid、Draw.io、ZenUML、PlantUMLのSVGレンダリング

根拠

MathJaxによるTeXのSVGレンダリング

根拠

krr CLIのrender、compare、reference-update、bench

根拠

02

はじめ方

  1. RustとREADME記載のランタイムアセットを準備し、krr CLIを導入します。
  2. Mermaidの入力ファイルを用意し、renderコマンドでSVGを生成します。

Rustと必要な開発ツールを準備し、導入前にリンク先のREADMEで環境要件を確認してください。実行例は機能の入口であり、すべての環境での動作を保証するものではありません。

根拠
sh
cargo install katana-render-runtime-cli
printf 'graph TD\n  A-->B\n' > sample.mmd
krr mermaid render --input sample.mmd --output sample.svg

01 / KRR

どんな場面で使うか

図と数式を同じ契約で SVG 化

Mermaid、ZenUML、Draw.io、PlantUML の図ソースと MathJax の TeX を、種別付きの RenderInput として渡します。KRR は各 runtime を選んで SVG、寸法、viewBox、runtime 情報、警告・エラー、cache fingerprint を含む RenderOutput を返すため、プレビューや文書表示側は図種ごとの実装を持たずに描画結果を扱えます。

数式入力の診断付きプレビュー

MathJaxRenderer は通常のインライン TeX と display 数式を SVG に変換し、無効な TeX や未導入 runtime では入力文字列を保持したまま diagnostics.errors に理由を返します。描画失敗を画面全体の失敗にせず、編集画面で元のソースと診断を示す用途に向きます。公開テストでも正常系は SVG と寸法、異常系は元入力・0 寸法・非空エラーを確認しています。

02 / KRR

入力から出力までの流れ

  1. source と種別を入力

    呼び出し側が RenderInput に RenderKind、分類済みの source、RenderConfig、RenderPolicy、RenderContext を設定します。KRR は Markdown AST を受け取らず、図または TeX の文字列を直接処理する責務です。

  2. runtime とテーマを解決

    RuntimePathResolver は明示された runtime path を優先し、未指定なら Mermaid、Draw.io、MathJax の bundled asset、PlantUML の versioned cache path を解決します。PlantUML では vendor_config のテーマや cache directory を読み、設定不正なら RenderError として返します。

  3. SVG と診断を受け取る

    Renderer::render の戻り値は RenderOutput です。正常な図や数式では SVG と正の寸法を返し、入力エラーや runtime 不在時は RenderError、または backend が定義した raw source と diagnostics を返すため、利用側は警告とエラーを表示・記録できます。

03 / KRR

主要API・CLIの使い分け

Renderer::render
統一入口は Renderer::render(&RenderInput) です。RenderKind と source の組み合わせが backend に合わない場合は UnsupportedKind、runtime 解決失敗は RuntimeResolution などの RenderError になります。
RenderOutput
出力には svg、width、height、view_box、runtime、profile、diagnostics、cache_fingerprint が含まれます。単に SVG 文字列だけでなく、表示寸法と再利用判断に必要なメタデータまで受け取れます。
krr render
CLI は krr mermaid render、krr drawio render、krr plantuml render の形式で入力ファイルを処理します。--output、--runtime、PlantUML の --theme・--theme-mode・--cache-dir を指定でき、出力ファイルを省略した場合は標準出力へ結果を出します。
比較・診断用コマンド
reference-update、compare、bench は fixture directory を対象にします。compare の既定 minimum score は 99.0 なので、製品統合時の回帰検査導線として利用できますが、これは品質比較の仕組みであり実行性能の保証ではありません。

04 / KRR

具体例で理解する

MathJax の不正入力を診断付きで扱う

Rust 側で RuntimePathResolver から MathJax runtime を解決し、MathJaxRenderer に RenderInput を渡します。入力を \not_a_real_mathjax_command とした場合も render は出力を返し、svg は元の入力、width と height は 0、diagnostics.errors は非空になります。正常な E = mc^2 なら SVG、viewBox、正の幅と高さが得られます。

rust
use katana_render_runtime::{
    MathJaxRenderer, RenderConfig, RenderContext, RenderInput, RenderKind,
    RenderPolicy, Renderer, RuntimePathResolver,
};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let runtime = RuntimePathResolver::resolve(RenderKind::MathJax, None)?;
    let renderer = MathJaxRenderer::with_runtime_path(runtime);
    let input = RenderInput {
        kind: RenderKind::MathJax,
        source: r"\not_a_real_mathjax_command".to_string(),
        config: RenderConfig::default(),
        policy: RenderPolicy::default(),
        context: RenderContext::default(),
    };
    let output = renderer.render(&input)?;
    println!("svg={} errors={:?}", output.svg, output.diagnostics.errors);
    Ok(())
}

05 / KRR

組み込み条件と責務の境界

導入前提

公開 workspace は Rust 1.95.0、edition 2024 で、runtime asset は Mermaid、Draw.io、MathJax、PlantUML などの version と checksum を管理します。既定 asset を使うか、明示 path・環境変数で runtime を差し替える運用を選べます。

責務境界

KRR は分類済みの図・TeX source の runtime 描画を担当します。Markdown AST の解析、HTML/PDF/PNG/JPG の文書 export、viewer/editor UI、KDV の pagination と document export は担当しないため、それらは上位のモデル・viewer・アプリ側で組み合わせます。

根拠

調査時点の公開リポジトリに基づく紹介です。リンク先の固定コミットで実装と手順を確認できます。

リポジトリREADME8654789f69d2
根拠 · KRR
すべての製品