Immagini SVG in Graphviz: rendile portabili

Un diagramma Graphviz può contenere nodi e frecce vettoriali mentre la grafica personalizzata dei nodi punta ancora a un file immagine separato. Se quella grafica scompare dopo aver spostato l'SVG, esamina il riferimento all'immagine generato prima di cambiare il disegno. La parte mancante potrebbe essere il pacchetto di consegna.

Nell'output SVG provato qui sotto, Graphviz mantiene motif.svg come immagine collegata. Il pacchetto completo la visualizza; il diagramma spostato da solo la perde. Una copia confezionata esplicitamente include i byte della grafica e la visualizza nello stesso test del browser. Questo passaggio di confezionamento lascia comunque un elemento immagine SVG, anziché trasformare il motivo in tracciati nativi del grafo.

Conserva la sorgente DOT per nomi e relazioni dei nodi. Conserva separatamente l'originale della grafica e prova l'output esatto nel visualizzatore o nel flusso di pubblicazione che lo riceverà.

Distingui il nodo, la sua grafica e il riferimento al file

L'attributo image di Graphviz indica la grafica mostrata all'interno di un nodo. Non sostituisce l'identità o le relazioni del nodo nel grafo. La documentazione richiede le dimensioni sorgente; per le immagini SVG, fornisci width e height espliciti con unità appropriate.

Il motivo originale qui è un disegno a due tracciati con uno spazio di coordinate di 96 per 64. Le sue dimensioni esterne sono 96pt per 64pt. Il nodo circostante e la freccia appartengono a Graphviz.

Un elemento immagine può puntare a grafica SVG o a pixel. Per esaminare una sorgente raster, usa la diagnosi delle immagini incorporate negli SVG. Un nome di file che termina in .svg non basta a stabilire il contenuto di nessuno dei due file.

Esegui un piccolo esempio con un renderer esplicito

Abbiamo usato @viz-js/viz 3.31.0, una build WebAssembly che riporta Graphviz 16.1.0, con il motore di layout dot e l'output SVG integrato. È un test di quella build e di quel renderer, non un'affermazione secondo cui ogni installazione Graphviz ha un comportamento identico nel caricamento delle immagini.

In una nuova cartella di progetto Node.js, installa il pacchetto nella versione fissata:

npm install @viz-js/viz@3.31.0

Salva la grafica originale come motif.svg:

<svg xmlns="http://www.w3.org/2000/svg"
     width="96pt" height="64pt" viewBox="0 0 96 64">
  <path fill="#173b40" fill-rule="evenodd"
    d="M48 4C70 4 88 17 88 32S70 60 48 60S8 47 8 32S26 4 48 4Z
       M48 14C31 14 19 22 19 32S31 50 48 50S77 42 77 32S65 14 48 14Z"/>
  <path fill="#28bfa3"
    d="M43 20H53V27H60V37H53V44H43V37H36V27H43Z"/>
</svg>

Salva il grafo come diagram.dot:

digraph G {
  graph [rankdir=LR, bgcolor="white", margin=0.1];
  node [shape=box, fontname="Arial", fontsize=16,
        color="#173b40", penwidth=1.5,
        fixedsize=true, width=1.8, height=1.1];
  artwork [label="", image="motif.svg", imagescale=true];
  review [label="Review"];
  artwork -> review [color="#173b40", penwidth=1.5];
}

Poi salva questo come render.mjs ed esegui node render.mjs da quella cartella:

import { instance } from '@viz-js/viz';
import fs from 'node:fs';
 
const viz = await instance();
const dot = fs.readFileSync('diagram.dot', 'utf8');
const svg = viz.renderString(dot, {
  engine: 'dot',
  format: 'svg',
  images: [{ name: 'motif.svg', width: '96pt', height: '64pt' }]
});
 
fs.mkdirSync('bundle', { recursive: true });
fs.copyFileSync('motif.svg', 'bundle/motif.svg');
fs.writeFileSync('bundle/diagram.svg', svg);
process.stdout.write(`Graphviz ${viz.graphvizVersion}\n`);

La documentazione API di Viz.js descrive l'opzione images come informazioni sulle dimensioni delle immagini. Fornirla comunica al layout le dimensioni di questa grafica denominata; non inserisce i byte del file nel risultato. Le unità esplicite evitano che un numero senza unità venga trattato come pixel CSS. L'API usa punti per le dimensioni senza unità.

Per un'installazione nativa di Graphviz, la documentazione ufficiale di image descrive le risorse immagine locali e le dimensioni lette dal file sorgente. Non copiare la configurazione dei metadati WebAssembly in un comando nativo presumendo che abbia lo stesso meccanismo di caricamento.

Esamina ciò che ha scritto il renderer

L'SVG generato contiene questo elemento:

<image xlink:href="motif.svg"
       width="118.8px" height="79.2px"
       preserveAspectRatio="xMinYMin meet"
       x="5.4" y="-79.2"/>

Le dimensioni e la posizione sono valori osservati in questo campione. La parte che determina la consegna è xlink:href="motif.svg": il risultato richiede ancora una risorsa in quel percorso relativo.

Copia soltanto diagram.svg in un'altra cartella e lascia indietro la grafica. Confrontalo con il pacchetto completo. Abbiamo servito entrambe le cartelle via HTTP locale e mostrato ogni SVG come documento attraverso un elemento HTML object.

I riquadri dei nodi e la freccia generati rimangono presenti quando il motivo collegato manca. Ricostruire il layout del grafo non fornisce il file assente. Ripristina la posizione prevista della risorsa, consegna l'intero pacchetto o scegli un passaggio di confezionamento adatto alla destinazione.

Aprire un SVG come documento e mostrarlo tramite un elemento HTML img sono test diversi. La guida MDN agli SVG come immagini spiega che i contesti immagine possono limitare le risorse esterne, mentre gli URL dati possono incorporarle. Le restrizioni descritte per il contesto immagine non si applicano ai documenti SVG diretti o all'incorporamento di documenti tramite object e iframe. Controlla il contesto di consegna che usi davvero.

Confeziona esplicitamente questo motivo semplice

Per questo motivo originale autonomo, lo script seguente sostituisce esattamente un riferimento noto con i byte SVG del file. Salvalo come package.mjs ed eseguilo dopo il rendering:

import fs from 'node:fs';
 
const svg = fs.readFileSync('bundle/diagram.svg', 'utf8');
const needle = 'xlink:href="motif.svg"';
if (svg.split(needle).length !== 2) {
  throw new Error('Expected exactly one motif reference');
}
 
const data = 'data:image/svg+xml;base64,' +
  fs.readFileSync('bundle/motif.svg').toString('base64');
const packaged = svg.replace(needle, `xlink:href="${data}"`);
fs.writeFileSync('self-contained.svg', packaged);

È un esempio di confezionamento mirato, non un incorporatore SVG generico. Gestisce il riferimento noto in questo output e un motivo che non ha font, immagini, fogli di stile o altre dipendenze esterne. Una grafica più complessa richiede un proprio controllo delle dipendenze.

La copia confezionata ha mostrato il motivo nel nostro test nel browser. Il confronto delle due stringhe di output dopo aver mascherato il valore del riferimento all'immagine ha mostrato una geometria del grafo identica. Il file contiene ancora un elemento immagine; il suo riferimento ora inizia con data:image/svg+xml;base64,.

Incorporare i byte dell'immagine SVG può eliminare questa dipendenza dal percorso del file mantenendo la sorgente vettoriale della grafica. Non rende quella grafica una forma nativa di nodo Graphviz, non aggiunge punti di connessione al suo interno e non garantisce che un altro editor esponga direttamente i suoi tracciati. Prova il comportamento di importazione del destinatario.

Evita anche di confondere svg_inline con l'incorporamento delle immagini. La documentazione dell'output SVG di Graphviz lo descrive come output senza intestazione per l'inclusione in HTML. Nel nostro stesso grafo, selezionare svg_inline ha prodotto ancora il riferimento motif.svg. La modalità di output non ha confezionato la grafica.

Separa dimensioni e scala dalla portabilità

Il riferimento di imagescale di Graphviz distingue l'adattamento dell'immagine all'interno del nodo dalle dimensioni naturali della sorgente. In questo esempio, imagescale=true la scala uniformemente per farla entrare. L'opzione both scala larghezza e altezza separatamente, e può cambiare le proporzioni.

Se il motivo appare ma è deformato, esamina l'opzione di scala. Se appare soltanto in parte, esamina i suoi limiti e lo spazio disponibile nel nodo. Se scompare dopo aver spostato il file, esamina prima il percorso della risorsa. La guida alle dimensioni SVG spiega come differiscono le dimensioni dichiarate e le coordinate del disegno.

La pagina ufficiale sull'output SVG osserva che l'output Cairo può differire dall'output SVG integrato per leggibilità e trasformabilità dell'XML. Qui non abbiamo provato Cairo. Mantieni il renderer esplicito in un progetto riproducibile e ripeti il controllo del confezionamento quando lo cambi.

Recupera la grafica a monte quando la sorgente è persa

PerfectVector può aiutare quando un motivo illustrativo adatto sopravvive solo come PNG o scansione. Il suo flusso di recupero della grafica scientifica fornisce un candidato vettoriale da esaminare prima dell'uso. Ritaglia il motivo, controllane sagoma e spazi vuoti, poi verifica limiti e dimensioni dell'SVG scaricato prima di aggiungerlo al grafo.

Questo recupero non ricostruisce le relazioni dei nodi, i significati delle frecce o le etichette DOT. Mantienili nella sorgente del grafo. Usa l'SVG originale quando disponibile, ridisegna un simbolo semplice quando è più facile da mantenere e conserva le fotografie come immagini raster. La panoramica sulla vettorializzazione delle immagini spiega il limite del recupero.

Altri strumenti per diagrammi confezionano la grafica personalizzata in modo diverso. La guida alle icone Mermaid tratta i dati delle icone registrate, mentre la grafica SVG personalizzata in draw.io distingue un'immagine importata da uno stencil nativo. Tieni conto dei requisiti della destinazione nella preparazione della grafica.

FAQ

L'output SVG di Graphviz include automaticamente l'immagine del mio nodo? Nell'output SVG integrato provato, il diagramma contiene un riferimento all'immagine nel file separato motif.svg. Esamina il tuo output e consegna le sue dipendenze oppure usa un passaggio di confezionamento verificato.

svg_inline unisce i tracciati di un'immagine SVG al grafo? No. È una modalità di output senza intestazione per l'inclusione in HTML. Nel nostro test ha mantenuto il riferimento esterno a motif.svg.

Un SVG autonomo equivale a una geometria di nodo nativa modificabile? No. L'esempio confezionato mantiene un elemento immagine contenente byte SVG. La struttura del grafo rimane in DOT e l'editor di destinazione determina come espone quella grafica.

Fonti

1. Graphviz — image — Risorse locali per le immagini dei nodi e dimensioni SVG richieste.
2. Graphviz — imagescale — Adattamento uniforme e scala indipendente di larghezza e altezza.
3. Graphviz — Output SVG — Output integrato e Cairo, oltre al significato di svg_inline.
4. Viz.js — API — Metadati sulle dimensioni delle immagini, unità esplicite e chiamate di rendering SVG.
5. MDN — SVG come immagine — Restrizioni delle risorse esterne nei contesti immagine e distinzione dall'incorporamento di documenti.

Prova un nodo attraverso il flusso di consegna prima di preparare un'intera libreria di grafica. Se rimane solo un motivo raster, prepara un candidato SVG della grafica, esamina i suoi spazi e le proporzioni, poi aggiungilo al grafo DOT e verifica l'output spostato o confezionato nel visualizzatore di destinazione.