函式庫

KatanA Render Runtime

將圖表與 TeX 公式 source 轉換為 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 列出的 runtime asset,並安裝 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 資訊、警告與錯誤及快取指紋的 RenderOutput,因此預覽或文件顯示端無需分別實現各類圖表的渲染。

公式輸入的診斷預覽

MathJaxRenderer 將普通行內 TeX 和 display 數式轉換為 SVG;TeX 無效或 runtime 缺失時會保留輸入字串,並在 diagnostics.errors 中返回原因。這適合在編輯介面展示原文和診斷,而不讓一次渲染失敗導致整個介面失敗。公開測試分別驗證正常輸入的 SVG 與尺寸,以及異常輸入的原文、0 尺寸和非空錯誤。

02 / KRR

從輸入到輸出的流程

  1. 輸入來源和型別

    呼叫者通過 RenderKind、分類源、RenderConfig、RenderPolicy 和 RenderContext 設定 RenderInput。 KRR 不接受 Markdown AST,並負責直接處理圖表或 TeX 字串。

  2. 解決執行時和主題

    RuntimePathResolver 優先考慮指定的執行時路徑,如果未指定,它將解析 Mermaid、Draw.io、MathJax 中的捆綁資源以及 PlantUML 中的版本化快取路徑。 PlantUML讀取vendor_config中的主題和快取目錄,如果設定無效則返回RenderError。

  3. 接收 SVG 和診斷

    Renderer::render的返回值是RenderOutput。返回正常圖表和公式的 SVG 和正尺寸,並返回 RenderError 或後端定義的原始源以及輸入錯誤或執行時缺失的診斷,允許使用者檢視和記錄警告和錯誤。

03 / KRR

主要 API 與 CLI

Renderer::render — 渲染契約
統一的入口是Renderer::render(&RenderInput)。如果RenderKind和source的組合與後端不匹配,則會是UnsupportedKind,如果執行時解析失敗,則會是RuntimeResolution等RenderError。
RenderOutput — 輸出資料
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,再把 RenderInput 傳給 MathJaxRenderer。對於輸入 \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 等的版本和 checksum。可使用預設 asset,也可通過顯式 path 或環境變數替換 runtime。

責任邊界

KRR 負責分類圖形和 TeX 源的執行時繪製。我們不負責 Markdown AST 分析、HTML/PDF/PNG/JPG 文件匯出、檢視器/編輯器 UI、KDV 分頁和文件匯出,因此這些都合併在上層模型/檢視器/應用程式端。

依據

內容根據調查時點的公開儲存庫。可透過連結中的固定提交確認實作與使用方式。

儲存庫閱讀指南8654789f69d2
依據 · KRR
所有產品