PixiJS-SVG-Import: Graphics oder Textur wählen

PixiJS kann ein SVG auf zwei Arten verwenden: Graphics.svg() liest unterstützte Zeichnungsgeometrie ein, während das Laden des SVGs als Textur einem Sprite Pixel zur Anzeige liefert. Wähle Geometrie, wenn die Grafik stark skaliert werden muss, und eine Textur, wenn ein an die gewünschte Anzeigegröße angepasstes Rasterbild zum Asset passt. PixiJS beschreibt beide Wege in seinem SVG-Leitfaden.

Teste dieselbe Datei über beide Wege, bevor du dich entscheidest. Unser kleines Emblem behielt in beiden seine Öffnung und Farben, aber beim Geometrieweg fehlte die Gruppenverschiebung. Die Textur entsprach der Browserplatzierung und wurde beim Vergrößern weicher. Das sind separate Probleme mit unterschiedlichen Lösungen.

Entscheide, was die Szene benötigt

Ein Graphics-Objekt ist Pixi-Zeicheninhalt, kein SVG-DOM-Baum mit den ursprünglichen Element-IDs. Sein Kontext kann zwischen Instanzen geteilt werden, wie der Graphics-Leitfaden erklärt. Behalte das ursprüngliche SVG, wenn du einzelne Quellpfade bearbeiten oder später ein weiteres SVG exportieren möchtest. Beide Wege zeichnen letztlich Pixel auf den Bildschirm.

Teste eine Kurve, ein Loch und eine Transformation

Dieses Beispiel verwendet PixiJS 8.21.0, ein SVG mit 96 × 96, die Rendererauflösung 1 und eine SVG-Textur, die mit Auflösung 1 geladen wurde. Die kleine Variante wird in ihrer nativen Größe gezeichnet; die große verwendet Skalierung 3. Das eigene Emblem enthält zwei farbige Pfade und eine Gruppe, die entlang beider Achsen um acht SVG-Einheiten verschoben ist. Ihre innere Kontur läuft entgegengesetzt zur äußeren und bildet dadurch die Öffnung.

Dasselbe eigene SVG durch drei Renderer

Das Schachbrett scheint in allen drei Spalten durch die Öffnung. Es ist ein Hintergrund hinter der Grafik, keine weiße Form im Loch. Der Versatz der mittleren Spalte ist bei beiden Größen sichtbar: Acht Einheiten bei nativer Skalierung werden bei Skalierung 3 zu 24 Anzeigepixeln.

Diese Beobachtungen gelten für diese Quelle und Version. Sie belegen nicht, dass jedes Loch, jede Transformation, jeder Verlauf oder jedes exportierte SVG gleich funktioniert.

Speichere die SVG-Quelle

Speichere dies als emblem.svg neben deiner Seite. Es ist eine eigens für den Vergleich gezeichnete Grafik, kein Vektorisierungsergebnis.

<svg xmlns="http://www.w3.org/2000/svg"
     width="96" height="96" viewBox="0 0 96 96">
  <g transform="translate(8 8)">
    <path fill="#145c61" d="M40 0
      C62 0 80 18 80 40 C80 62 62 80 40 80
      C18 80 0 62 0 40 C0 18 18 0 40 0 Z
      M40 20 C29 20 20 29 20 40 C20 51 29 60 40 60
      C51 60 60 51 60 40 C60 29 51 20 40 20 Z"/>
    <path fill="#e68546"
      d="M62 5 C74 9 80 21 78 34 L61 32
         C63 23 61 15 55 10 Z"/>
  </g>
</svg>

Teste beide Wege

Füge dieses Skript in eine über HTTP bereitgestellte HTML-Seite neben emblem.svg ein. Es importiert den festgelegten Pixi-Build, lädt dein vertrauenswürdiges SVG und zeichnet native und vergrößerte Versionen in zwei Spalten. Links wird Geometrie verwendet, rechts eine Textur.

<script type="module">
import { Application, Assets, Graphics, Sprite }
  from 'https://cdn.jsdelivr.net/npm/pixi.js@8.21.0/dist/pixi.mjs';
 
const app = new Application();
await app.init({
  width: 640, height: 420, resolution: 1,
  antialias: true, background: '#e7eeea', preference: 'webgl'
});
document.body.append(app.canvas);
 
const response = await fetch('emblem.svg');
if (!response.ok) throw new Error('SVG request failed');
const svgText = await response.text();
const texture = await Assets.load({
  src: 'emblem.svg', data: { resolution: 1 }
});
 
for (const [scale, y] of [[1, 12], [3, 120]]) {
  const geometry = new Graphics().svg(svgText);
  geometry.scale.set(scale);
  geometry.position.set(16, y);
  const sprite = new Sprite(texture);
  sprite.scale.set(scale);
  sprite.position.set(336, y);
  app.stage.addChild(geometry, sprite);
}
</script>

Öffne auch das ursprüngliche SVG im Browser. Vergleiche Außenkontur, Öffnung, Akzentform und Platzierung, nicht nur, ob die Datei fehlerfrei geladen wurde.

Korrigiere den Unterschied, den du tatsächlich siehst

Die Geometrie ist verschoben

In diesem Test wendete Graphics.svg() das umschließende translate(8 8) nicht an. Die SVG-Parserimplementierung der festgelegten Version ist nützlich, wenn du das Verhalten deiner Projektversion prüfst.

Für genau diese Datei kompensiert das Ersetzen der Geometriepositionszeile durch Folgendes diese eine bekannte Verschiebung:

geometry.position.set(16 + 8 * scale, y + 8 * scale);

Die Korrektur enthält scale, weil die fehlende Verschiebung zum Koordinatensystem der Quelle gehört. Bei Skalierung 3 beträgt die Korrektur 24 Pixel entlang jeder Achse. Das ist kein allgemeines Werkzeug zum Einrechnen von Transformationen. Eine Datei mit verschachtelten Drehungen, Scherungen oder unterschiedlichen Transformationen auf einzelnen Pfaden benötigt ein korrekt vorbereitetes Ausgabe-SVG oder einen anderen Renderingweg. Vergleiche die exportierte Ausgabedatei mit dem bearbeitbaren Original.

Die vergrößerte Textur ist weich

Die SVG-Textur in der Abbildung enthält 96 × 96 Pixel. Wenn du ihr Sprite auf 288 × 288 skalierst, werden die Quellkurven nicht erneut eingelesen. Lade eine separate Textur mit höherer Auflösung, um mehr Pixel vorzubereiten:

const largeTexture = await Assets.load({
  src: 'emblem.svg?resolution=3',
  data: { resolution: 3 }
});

Im getesteten Build erzeugte dies eine Quelle mit 288 × 288 Pixeln, einer logischen Texturgröße von 96 × 96 und Quellauflösung 3. Verwende beim Erstellen des Sprites largeTexture. Der Query-String gibt diesem Experiment einen eigenen Cache-Schlüssel; der Server muss unter dieser URL dasselbe SVG bereitstellen. Pixis Assets-Leitfaden erklärt das URL-basierte Caching, und der Texturleitfaden unterscheidet eine Textur von ihrer Quelle.

Wähle die Auflösung für die größte benötigte Bildschirmdarstellung, einschließlich der tatsächlich ausgelieferten Rendererauflösung. Allein eine höhere Rendererauflösung fügt einer bereits geladenen niedrig aufgelösten Textur keine Details hinzu. Prüfe auch die kleinste Icon-Größe: Eine größere Quelle macht eine winzige Öffnung nicht lesbar, wenn die endgültige Anzeige zu klein ist.

Ein Detail fehlt

Prüfe die ursprüngliche Quelle im Browser und teste dann eine einfachere Kopie in Pixi. Reduziere das SVG auf die betroffenen Formen und füge Gruppen, Farben und Effekte einzeln wieder hinzu. Pixis Graphics-Dokumentation beschreibt die SVG-Unterstützung als Teilmenge; erfolgreiches Laden ist keine vollständige Kompatibilitätsprüfung.

Behalte eine Rasterausgabekopie, wenn sie die Grafik bei bekannten Größen zuverlässig erhält. Bei einem einfachen geometrischen Symbol kann das direkte Zeichnen der Formen in Pixi leichter zu pflegen sein. Wähle keinen Weg aufgrund einer nicht durch Messungen belegten Behauptung, er sei immer schneller oder speichersparender. Teste deine Szene und Zielgeräte.

Bereite die Quelle vor dem Import vor

Wenn ein SVG ein platziertes PNG enthält, rekonstruieren weder das Ändern des Dateinamens noch der Import als Geometrie die fehlenden Vektorkonturen. Nutze zuerst die Checkliste für eingebettete Rasterbilder, um die Quelle zu prüfen. Der umfassendere Leitfaden zur Bildvektorisierung erklärt, wann Nachzeichnen nützlich ist.

PerfectVector passt, wenn nur ein flaches PNG oder JPG übrig ist und du bearbeitbare Quellformen für das Icon benötigst. Konvertiere dein Bild zu SVG und prüfe dann Kontur, getrennte Farben und kleine Öffnungen in einem SVG-Editor, bevor du den Pixi-Test wiederholst. Verwende ein vorhandenes sauberes Vektororiginal direkt. Nachzeichnen repariert weder Pixis Transformationsverarbeitung noch konfiguriert es die Texturauflösung.

Andere Engines treffen eigene Importentscheidungen. Der Godot-SVG-Importleitfaden erklärt das dortige Textur- und Oversamplingverhalten; der Unity-SVG-Leitfaden behandelt diesen separaten Workflow. Übertrage die Einstellungen einer Engine nicht allein aufgrund der SVG-Endung auf eine andere.

Prüfe das ausgelieferte Icon

Vergleiche das Asset vor der Abnahme mit der im Browser gerenderten Quelle in der kleinsten und größten vorgesehenen Größe. Prüfe die Öffnung über kontrastierenden Hintergründen, die Gruppenplatzierung und benötigte Effekte. Dokumentiere Pixi-Version, Rendererauflösung, Pixelabmessungen der Texturquelle und Szenenskalierung. Behalte das SVG-Original im Projekt, damit spätere Layout- oder Importeränderungen gegen dieselbe Quelle getestet werden können.

Hast du nur Rastergrafiken? Bereite mit PerfectVector ein bearbeitbares SVG vor, prüfe Kontur und Negativraum und teste dann den tatsächlichen Pixi-Importweg in den Größen deiner Oberfläche.

FAQ

Bleibt ein SVG beim Import in PixiJS Vektorgeometrie? Das hängt vom Weg ab. Graphics.svg liest unterstützte Zeichnungsgeometrie ein. Das Laden eines SVGs als Textur gibt einem Sprite eine Rasterquelle. Behalte das ursprüngliche SVG separat für Quellbearbeitung und spätere Exporte.

Warum kann ein PixiJS-SVG-Sprite unscharf aussehen? Ein Sprite kann seine Textur größer als deren Pixelabmessungen anzeigen. Prüfe Quellauflösung und größte vorgesehene Anzeigegröße. Lade eine ausreichend große Textur oder teste den Geometrieweg für unterstützte Grafiken.

Erhält Graphics.svg jede SVG-Funktion? Nein. Es unterstützt eine Teilmenge von SVG. In diesem PixiJS-8.21.0-Beispiel blieben Loch und zwei Farben erhalten, aber die Gruppenverschiebung nicht. Teste deine eigene Exportdatei gegen eine Browserreferenz.

Quellen

1. PixiJS-SVG-Leitfaden — Beschreibt Textur- und Geometrieimportwege sowie die Texturauflösung.
2. PixiJS-Graphics-Leitfaden — Erklärt das Teilen von GraphicsContext und die Grenze der SVG-Unterstützung.
3. PixiJS-Assets-Leitfaden — Dokumentiert Asset-Laden und URL-basiertes Caching.
4. PixiJS-Texturleitfaden — Beschreibt die Beziehung zwischen Texturen und ihren Quellen.
5. PixiJS-8.21.0-SVG-Parser — Liefert die auf eine Version festgelegte Implementierung zur Untersuchung von Importunterschieden.