Opérations SVG Paper.js : découpe et réunis les formes

Importe le SVG, trouve les objets de tracé souhaités, puis appelle unite() pour réunir des régions remplies ou subtract() pour retirer une région d’une autre. Conserve les opérandes jusqu’à la vérification du résultat et rouvre le SVG exporté avant de l’utiliser ailleurs.

Le choix important précède l’opération booléenne : quelles formes vont ensemble ? Un groupe importé peut contenir des rectangles de fond, des chemins de découpage, du lettrage et des éléments décoratifs. Combiner tous les enfants peut effacer les séparations que tu voulais préserver. Ce guide utilise trois tracés fermés nommés pour montrer exactement ce qui change.

Pars d’une géométrie remplie identifiable

L’importateur SVG de Paper.js accepte du code SVG, un élément SVG ou une URL. Ces méthodes nécessitent des traitements de chargement différents : cet exemple importe une chaîne en ligne ; un fichier distant doit être traité après chargement dans la fonction de rappel d’importation.

Pour cette tâche, les opérandes doivent être des objets Path ou CompoundPath. Un groupe est un conteneur et une image matricielle ne fournit pas la limite nécessaire à une opération booléenne sur des tracés. Si un fichier se comporte seulement comme une image unique, vérifie d’abord pourquoi un SVG ne se dégroupe pas.

Utilise des ID pour les parties que tu contrôles. Ne suppose pas que children[0] signifie « le logo » dans des exports quelconques. Examine les illustrations inconnues et attribue les parties délibérément. Conserve un tracé composé existant intact lorsque ses sous-tracés définissent déjà les trous souhaités.

Exécute une petite importation, une union et une soustraction

Nous avons testé le code suivant avec Paper.js 0.12.18 dans un navigateur. L’illustration est un SVG original créé à la main : un corps carré, une languette superposée et un carré blanc marquant l’ouverture souhaitée. Ce n’est pas un exemple de conversion PerfectVector.

Dans un dossier vide, installe cette version précise de la bibliothèque :

npm install --save-exact paper@0.12.18

Enregistre ceci sous 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>

Enregistre ceci sous example.js, puis ouvre le HTML dans un navigateur :

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’import reste hors de la scène avec insert: false. expandShapes: true demande à l’importateur de transformer les formes primitives prises en charge en tracés ; notre exemple contient déjà des éléments path. La vérification explicite de la classe compte encore car un ID importé peut identifier un conteneur ou un autre type d’élément.

L’API booléenne renvoie un nouvel élément de tracé. Ici, le résultat reste hors de la scène jusqu’à l’ajout de la forme finale découpée. Les parties originales restent disponibles sous imported : une opération ratée n’exige donc pas de reconstruire la source.

joined.subtract(hole) retire le trou de la silhouette réunie. Inverser les opérandes pose une autre question et peut produire un résultat vide ou inattendu. Le mode de soustraction par défaut de Paper.js traite les opérandes comme des surfaces. Son option trace concerne la géométrie booléenne ; elle n’a aucun rapport avec la vectorisation d’un PNG.

Vérifie le résultat comme géométrie et comme fichier

Dans cet exemple, l’union renvoyait un Path ; la soustraction renvoyait un CompoundPath avec deux contours. Les limites finales étaient x = 40, y = 40, largeur = 220 et hauteur = 140 en unités SVG. L’illustration se trouve dans une zone d’export de 300 × 220 : les limites et la taille du document sont donc volontairement différentes.

Nous avons vérifié le centre de l’ouverture à (105, 105) : il était dans la silhouette réunie et hors du résultat soustrait. Un point du corps plein à (60, 60) restait à l’intérieur. Réimporter le SVG exporté conservait les limites et excluait à nouveau le centre du trou. Ces résultats concernent cet exemple simple, pas tous les fichiers importés.

L’API d’export peut renvoyer une chaîne SVG et recevoir des limites explicites. Copie le code affiché sous le résultat dans result.svg, puis ouvre ce fichier indépendamment. Notre export enregistré contenait un élément path avec deux sous-tracés fermés ; il s’affichait aussi correctement lorsqu’il était ouvert directement dans le navigateur.

Pour ta propre illustration, vérifie :

• la silhouette et chaque ouverture par rapport à l’original ;
• l’absence d’inclusion accidentelle d’un fond ou d’une forme auxiliaire cachée ;
• le remplissage souhaité, car une forme réunie ne peut pas préserver deux remplissages unis modifiables séparément ;
• la zone d’affichage exportée, surtout si l’illustration atteint le bord du document ;
• le fichier dans l’application qui l’utilisera réellement.

Un élément blanc superposé peut ressembler à une ouverture sur du papier blanc. Place le résultat sur un fond contrasté pour vérifier la transparence. Le guide des trous SVG remplis explique les problèmes associés de tracés composés et de fill-rule.

Si l’opération donne la mauvaise forme

Une méthode manque. Examine la classe de l’élément sélectionné. Trouve le tracé voulu dans un groupe ou convertis les primitives prises en charge pendant l’importation. Ne résous pas cela en combinant tous les descendants : les tracés composés ont aussi des enfants, et leurs relations de trous comptent.

Le résultat semble inchangé. Assure-toi d’afficher l’élément renvoyé. Laisser les originaux visibles peut recouvrir une soustraction réussie. Dans l’exemple, seul le résultat final entre dans le calque actif.

Un contour disparaît ou change de sens. Cet exemple agit sur des régions fermées remplies. Une ligne épaisse visible n’est pas automatiquement la même forme que la surface balayée par son contour. Si tu as besoin de cette bordure comme opérande rempli, prépare une copie au contour converti en forme dans un éditeur vectoriel et examine-la avant importation. Conserve l’original modifiable.

Une illustration détaillée se comporte mal. Isole deux opérandes et examine leurs contours avant d’appliquer une séquence sur toute l’illustration. Doublons, auto-intersections et minuscules fragments nécessitent des vérifications propres au cas. Ce petit exemple ne mesure ni les performances ni la compatibilité SVG générale. Pour une réparation ponctuelle, les outils de sélection et de nœuds d’un éditeur vectoriel peuvent être plus simples qu’un processus géométrique programmé.

Si ta source est encore un PNG ou JPG

Si l’original modifiable manque, le processus d’image en vecteur PerfectVector peut aider à préparer un SVG à partir d’une illustration matricielle adaptée. Prévisualise le résultat, examine les contours et les espaces négatifs, puis télécharge un candidat à tester dans Paper.js.

La vectorisation n’identifie pas les parties que ton programme doit réunir ou soustraire. Tu dois encore examiner la structure importée, sélectionner les bons opérandes et vérifier le résultat exporté. Utilise le vecteur original si tu le possèdes ; dessine directement un carré ou un cercle simple plutôt que de le vectoriser. La présentation de la vectorisation d’images traite de ce choix de source.

FAQ

Puis-je appeler unite sur un groupe SVG importé ? Sélectionne d’abord les opérandes Path ou CompoundPath souhaités dans le groupe. Un groupe décrit l’organisation ; combiner tous ses enfants peut inclure des fonds ou détruire des séparations voulues.

subtract supprime-t-il les tracés originaux ? Il renvoie un nouvel élément de tracé. Cet exemple utilise insert: false pour l’importation et les résultats booléens, puis insère uniquement le résultat final. Les opérandes sources restent disponibles dans le conteneur importé.

Pourquoi un trou semble-t-il encore blanc ? Vérifie-le sur un fond coloré. Un objet rempli en blanc recouvre ce qui se trouve derrière ; une ouverture soustraite révèle ce fond. Rouvre le fichier exporté pour confirmer que cette relation subsiste.

La vectorisation effectue-t-elle le nettoyage booléen à ma place ? Non. Elle peut reconstruire des tracés à partir d’une source matricielle adaptée, mais ton application doit encore choisir les géométries à réunir, la surface à retirer et la méthode de validation du résultat.

Sources

1. Paper.js — référence Project — Décrit l’importation et l’export SVG, les limites et le contenu du projet.
2. Paper.js — référence Path — Définit l’union, la soustraction, les éléments de tracé renvoyés et les options booléennes.
3. Paper.js — référence CompoundPath — Décrit la géométrie composée et les tracés qui la constituent.

Si une image matricielle est ta seule source, prépare un candidat SVG, examine ses parties, puis teste la plus petite opération booléenne utile avant de traiter le reste de l’illustration.