Libreria

KatanA Render Runtime

Libreria Rust e CLI che convertono sorgenti di diagrammi e formule TeX in SVG. Un'API comune restituisce risultato di rendering e diagnostica.

Sviluppatori Rust che integrano rendering SVG di diagrammi e formule

01

Funzioni implementate

Rendering SVG di Mermaid, Draw.io, ZenUML e PlantUML

Fonti

Rendering SVG di TeX tramite MathJax

Fonti

Comandi render, compare, reference-update e bench della CLI krr

Fonti

02

Per iniziare

  1. Prepara Rust e gli asset runtime indicati nel README e installa la CLI krr.
  2. Prepara un file Mermaid e genera SVG con il comando render.

Prepara Rust e gli strumenti di sviluppo necessari e consulta il README collegato per i requisiti prima dell'integrazione. Gli esempi sono punti di partenza e non garantiscono il funzionamento in ogni ambiente.

Fonti
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

Casi d'uso

Convertire diagrammi e formule in SVG con lo stesso contratto

Passa sorgenti Mermaid, ZenUML, Draw.io e PlantUML e TeX di MathJax come RenderInput tipizzati. KRR sceglie il runtime e restituisce RenderOutput con SVG, dimensioni, viewBox, informazioni sul runtime, warning/errori e cache fingerprint; preview e document viewer non devono implementare ogni tipo di diagramma.

Preview diagnostica per input matematici

MathJaxRenderer converte TeX inline e display in SVG e, con TeX non valido o runtime non installato, conserva la stringa di input e restituisce il motivo in diagnostics.errors. È adatto a mostrare sorgente e diagnostica nell’editor senza far fallire l’intera schermata. I test pubblici verificano SVG e dimensioni nel caso valido, input originale, dimensioni 0 ed errori non vuoti nel caso anomalo.

02 / KRR

Flusso da input a output

  1. Inserire sorgente e tipo

    Il chiamante configura in RenderInput RenderKind, source classificato, RenderConfig, RenderPolicy e RenderContext. KRR non riceve un Markdown AST: è responsabile di elaborare direttamente la stringa del diagramma o del TeX.

  2. Risolvere runtime e tema

    RuntimePathResolver dà priorità al runtime path esplicito; se manca, risolve gli asset bundled di Mermaid, Draw.io e MathJax e il versioned cache path di PlantUML. Per PlantUML legge theme e cache directory da vendor_config e restituisce RenderError se la configurazione non è valida.

  3. Ricevere SVG e diagnostica

    Renderer::render restituisce RenderOutput. Per diagrammi e formule validi produce SVG e dimensioni positive; con input errato o runtime assente restituisce RenderError oppure raw source e diagnostics definiti dal backend, così il chiamante può mostrare e registrare warning ed errori.

03 / KRR

API e CLI principali

Renderer::render — Contratto di rendering
L’entry point unificato è Renderer::render(&RenderInput). Se RenderKind e source non sono compatibili con il backend si ottiene UnsupportedKind; un errore nella risoluzione del runtime produce errori RenderError come RuntimeResolution.
RenderOutput — Dati di uscita
L’output contiene svg, width, height, view_box, runtime, profile, diagnostics e cache_fingerprint. Non ricevi solo la stringa SVG, ma anche dimensioni e metadati necessari per decidere il riuso.
krr render — Ingresso CLI
La CLI elabora file con krr mermaid render, krr drawio render e krr plantuml render. Puoi specificare --output, --runtime e, per PlantUML, --theme, --theme-mode e --cache-dir; senza file di output il risultato va su stdout.
Comandi per confronto e diagnostica
reference-update, compare e bench lavorano su una fixture directory. Il minimum score predefinito di compare è 99.0: può servire alla regressione d’integrazione, ma è un meccanismo di confronto qualitativo e non una garanzia delle prestazioni di esecuzione.

04 / KRR

Capire con un esempio

Gestire input MathJax non valido con diagnostica

Sul lato Rust risolvi il runtime MathJax con RuntimePathResolver e passa un RenderInput a MathJaxRenderer. Con input \not_a_real_mathjax_command, render restituisce comunque un output: svg contiene l’input originale, width e height sono 0 e diagnostics.errors non è vuoto. Con E = mc^2 valido ottieni SVG, viewBox e larghezza e altezza positive.

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

Integrazione e limiti

Prerequisiti di adozione

Il workspace pubblico usa Rust 1.95.0 ed edition 2024; gli asset runtime di Mermaid, Draw.io, MathJax e PlantUML sono gestiti con version e checksum. Puoi usare gli asset predefiniti oppure sostituire il runtime con path espliciti o variabili d’ambiente.

Confine di responsabilità

KRR esegue il rendering runtime di sorgenti di diagrammi e TeX classificati. Non analizza Markdown AST, non esporta documenti in HTML/PDF/PNG/JPG, non gestisce viewer/editor UI né pagination ed export documentale di KDV: queste responsabilità appartengono a modello, viewer e app superiori.

Fonti

Presentazione basata sui repository pubblici disponibili al momento della ricerca. Implementazione e procedure sono verificabili nel commit fissato del link.

Archivio del codiceLeggimi8654789f69d2
Fonti · KRR
Tutti i prodotti