Operazioni booleane SVG in Paper.js: unisci e ritaglia

Importa l'SVG, trova gli oggetti tracciato desiderati, poi chiama unite() per unire regioni riempite o subtract() per rimuovere una regione da un'altra. Conserva gli operandi finché non hai verificato il risultato e riapri l'SVG esportato prima di usarlo altrove.

La decisione importante precede l'operazione booleana: quali forme vanno unite? Un gruppo importato può contenere rettangoli di sfondo, tracciati di ritaglio, lettere e parti decorative. Combinare ogni figlio può eliminare le separazioni che volevi preservare. Questa guida usa tre tracciati chiusi con un nome, così puoi vedere esattamente cosa cambia.

Parti da geometria riempita che puoi identificare

L'importatore SVG di Paper.js accetta markup SVG, un elemento SVG o un URL. Queste modalità richiedono una gestione diversa del caricamento: questo esempio importa una stringa inline; un file remoto va elaborato nel callback di importazione dopo il caricamento.

Per questo lavoro, gli operandi devono essere oggetti Path o CompoundPath. Un gruppo è un contenitore e un'immagine raster non fornisce il contorno necessario per un'operazione booleana sui tracciati. Se un file si comporta soltanto come un'unica immagine, controlla prima perché non riesci a separare un SVG.

Usa ID per le parti che controlli. Non presumere che children[0] significhi “il logo” in qualsiasi esportazione. Esamina la grafica sconosciuta e assegna le parti in modo deliberato. Mantieni intatto un tracciato composto esistente quando i suoi sottotracciati definiscono già i fori desiderati.

Esegui una piccola importazione, un'unione e una sottrazione

Abbiamo verificato il codice seguente con Paper.js 0.12.18 in un browser. La grafica è un SVG originale scritto a mano: un corpo quadrato, una linguetta sovrapposta e un quadrato bianco che indica l'apertura prevista. Non è un esempio di conversione PerfectVector.

In una cartella vuota, installa la versione fissata della libreria:

npm install --save-exact paper@0.12.18

Salva questo codice come index.html:

<!doctype html>
<meta charset="utf-8">
<title>SVG Boolean example</title>
<canvas id="work" width="300" height="220" hidden></canvas>
<div id="result" style="background:#d8e8e0; width:300px"></div>
<pre id="svg-output"></pre>
<script src="node_modules/paper/dist/paper-full.min.js"></script>
<script src="example.js"></script>

Salva questo codice come example.js, poi apri l'HTML in un browser:

paper.setup(document.getElementById('work'));
const source = `<svg xmlns="http://www.w3.org/2000/svg" width="300" height="220" viewBox="0 0 300 220">
  <path id="body" fill="#176b62" d="M40 40H180V180H40Z"/>
  <path id="tab" fill="#ee9852" d="M160 80H260V140H160Z"/>
  <path id="hole" fill="#ffffff" d="M80 80H130V130H80Z"/>
</svg>`;
const imported = paper.project.importSVG(source, { insert: false, expandShapes: true });
function operand(name) {
  const item = imported.getItem({ name });
  if (!(item instanceof paper.Path || item instanceof paper.CompoundPath)) {
    throw new Error(`Expected path geometry for ${name}`);
  }
  return item;
}
const joined = operand('body').unite(operand('tab'), { insert: false });
const cut = joined.subtract(operand('hole'), { insert: false });
cut.fillColor = '#176b62';
cut.strokeColor = null;
paper.project.activeLayer.addChild(cut);
const output = paper.project.exportSVG({ asString: true, bounds: new paper.Rectangle(0, 0, 300, 220) });
document.getElementById('result').innerHTML = output;
document.getElementById('svg-output').textContent = output;

L'importazione resta fuori dalla scena con insert: false. expandShapes: true chiede all'importatore di trasformare in tracciati le forme primitive supportate; il nostro esempio contiene già elementi path. Il controllo esplicito della classe resta importante perché un ID importato può identificare un contenitore o un altro tipo di elemento.

L'API booleana restituisce un nuovo elemento tracciato. Qui il risultato resta fuori dalla scena finché non viene aggiunta la forma finale ritagliata. Le parti originali rimangono disponibili in imported, quindi un'operazione fallita non richiede di ricostruire la sorgente.

joined.subtract(hole) rimuove il foro dalla sagoma unita. Invertire gli operandi pone una domanda diversa e può dare un risultato vuoto o inatteso. La modalità di sottrazione predefinita di Paper.js tratta gli operandi come aree. La sua opzione trace riguarda la geometria booleana; non ha relazione con il ricalco di un PNG in vettori.

Verifica il risultato come geometria e come file

In questo esempio, l'unione ha restituito un Path; la sottrazione ha restituito un CompoundPath con due contorni. I limiti finali erano x = 40, y = 40, larghezza = 220, altezza = 140 in unità SVG. La grafica si trova dentro un viewport di esportazione di 300 × 220, quindi limiti e dimensioni del documento sono volutamente diversi.

Abbiamo controllato il centro dell'apertura a (105, 105): era dentro la sagoma unita e fuori dal risultato della sottrazione. Un punto nel corpo pieno a (60, 60) è rimasto all'interno. Reimportare l'SVG esportato ha preservato i limiti ed escluso di nuovo il centro del foro. Questi sono risultati per questo esempio semplice, non una garanzia per ogni file importato.

L'API di esportazione può restituire una stringa SVG e accettare limiti espliciti. Copia il markup visualizzato sotto il risultato in result.svg, poi apri quel file autonomamente. La nostra esportazione salvata conteneva un elemento path con due sottotracciati chiusi; si visualizzava correttamente anche aprendola direttamente nel browser.

Per la tua grafica, controlla:

• la sagoma e ogni apertura rispetto all'originale;
• se sono state incluse accidentalmente forme di sfondo o ausiliarie nascoste;
• il riempimento previsto, poiché una forma unita non può mantenere due riempimenti piatti modificabili indipendentemente;
• il viewport esportato, soprattutto quando la grafica raggiunge il bordo del documento;
• il file nell'applicazione che lo userà effettivamente.

Una sovrapposizione bianca può sembrare un'apertura su carta bianca. Metti il risultato su uno sfondo contrastante per controllare la trasparenza. La guida ai fori SVG che si riempiono spiega i problemi correlati dei tracciati composti e delle regole di riempimento.

Quando l'operazione produce la forma sbagliata

Manca un metodo. Controlla la classe dell'elemento selezionato. Trova il tracciato desiderato dentro un gruppo oppure converti le forme primitive supportate durante l'importazione. Non risolvere il problema combinando ogni discendente: anche i tracciati composti contengono figli e le loro relazioni con i fori contano.

Il risultato sembra invariato. Assicurati di visualizzare l'elemento restituito. Lasciare visibili gli originali può coprire una sottrazione riuscita. Nell'esempio, soltanto il risultato finale entra nel livello attivo.

Un tratto scompare o cambia significato. Questo esempio opera su regioni chiuse e riempite. Una linea spessa visibile non è automaticamente la stessa forma dell'area coperta dal suo tratto. Se ti serve quel contorno come operando riempito, prepara una copia con il tratto convertito in forma in un editor vettoriale e controllala prima dell'importazione. Conserva l'originale modificabile.

La grafica dettagliata si comporta male. Isola due operandi e controllane i contorni prima di applicare una sequenza a un'intera illustrazione. Duplicati, autointersezioni e piccoli frammenti richiedono controlli specifici. Questo piccolo esempio non misura né le prestazioni né la compatibilità SVG generale. Per una correzione singola, gli strumenti di selezione e modifica dei nodi di un editor vettoriale possono essere più semplici della scrittura di una pipeline geometrica.

Quando la sorgente è ancora un PNG o JPG

Se manca l'originale modificabile, il flusso da immagine a vettore di PerfectVector può aiutarti a preparare un SVG da grafica raster adatta. Visualizza l'anteprima del risultato, controlla contorni e spazi negativi e scarica un candidato da verificare in Paper.js.

La vettorializzazione non identifica quali parti il programma debba unire o sottrarre. Devi ancora esaminare la struttura importata, selezionare gli operandi corretti e controllare il risultato esportato. Usa il vettore originale quando lo hai; disegna direttamente un quadrato o un cerchio semplice invece di ricalcarlo. La panoramica sulla vettorializzazione delle immagini tratta questa decisione sulla sorgente.

FAQ

Posso chiamare unite su un gruppo SVG importato? Seleziona prima gli operandi Path o CompoundPath desiderati dentro il gruppo. Un gruppo descrive l'organizzazione e combinare ogni figlio può includere sfondi o distruggere separazioni volute.

subtract rimuove i tracciati originali? Restituisce un nuovo elemento tracciato. Questo esempio usa insert: false per l'importazione e i risultati booleani, poi inserisce soltanto il risultato finale. Gli operandi sorgente restano disponibili nel contenitore importato.

Perché un foro sembra ancora bianco? Controllalo su uno sfondo colorato. Un oggetto con riempimento bianco copre ciò che sta dietro; un'apertura sottratta rivela quello sfondo. Riapri il file esportato per confermare che questa relazione sia mantenuta.

La vettorializzazione esegue la pulizia booleana al posto mio? No. Può ricostruire grafica a tracciati da una sorgente raster adatta, ma l'applicazione deve ancora scegliere quali geometrie unire, quale area rimuovere e come validare il risultato.

Fonti

1. Paper.js — Riferimento Project — Documenta importazione ed esportazione SVG, limiti e contenuti del progetto.
2. Paper.js — Riferimento Path — Definisce unione e sottrazione, elementi tracciato restituiti e opzioni booleane.
3. Paper.js — Riferimento CompoundPath — Descrive la geometria composta e i tracciati che la costituiscono.

Se un'immagine raster è la tua unica sorgente, prepara un candidato SVG, esaminane le parti, poi verifica la più piccola operazione booleana utile prima di elaborare il resto della grafica.