Import SVG do PixiJS: wybierz Graphics lub teksturę

PixiJS może używać SVG na dwa różne sposoby: Graphics.svg() parsuje obsługiwaną geometrię rysunku, a wczytanie SVG jako tekstury dostarcza obiektowi Sprite piksele do wyświetlenia. Wybierz geometrię, gdy grafika wymaga znacznego skalowania, a teksturę, gdy do danego zasobu wystarczy obraz rastrowy dopasowany do docelowego rozmiaru wyświetlania. PixiJS opisuje obie metody w swoim SVG guide.

Zanim wybierzesz, przetestuj ten sam plik obiema metodami. Nasz mały emblemat zachował otwór i kolory w obu przypadkach, ale metoda oparta na geometrii pominęła przesunięcie grupy. Tekstura odpowiadała położeniu w przeglądarce, a po powiększeniu stała się mniej ostra. To odrębne problemy wymagające różnych rozwiązań.

Ustal, czego potrzebuje scena

Obiekt Graphics to zawartość rysunkowa Pixi, a nie drzewo DOM SVG z oryginalnymi identyfikatorami elementów. Jego kontekst można współdzielić między instancjami, co wyjaśnia Graphics guide. Zachowaj oryginalny SVG, jeśli potrzebujesz edytować poszczególne ścieżki źródłowe lub później wyeksportować kolejny SVG. Obie metody ostatecznie rysują piksele na ekranie.

Przetestuj krzywą, otwór i transformację

Ten przykład używa PixiJS 8.21.0, SVG o wymiarach 96 × 96, rozdzielczości renderera 1 oraz tekstury SVG wczytanej z rozdzielczością 1. Mała wersja jest rysowana w swoim oryginalnym rozmiarze; duża używa skali 3. Oryginalny emblemat ma dwie kolorowe ścieżki i grupę przesuniętą o osiem jednostek SVG w każdym kierunku. Jego wewnętrzny kontur biegnie w kierunku przeciwnym do zewnętrznego, tworząc otwór.

Ten sam oryginalny SVG w trzech rendererach

Szachownica prześwituje przez otwór we wszystkich trzech kolumnach. To tło za grafiką, a nie biały kształt namalowany w otworze. Przesunięcie w środkowej kolumnie jest widoczne w obu rozmiarach: osiem jednostek przy oryginalnej skali staje się 24 pikselami na ekranie przy skali 3.

Te obserwacje dotyczą tego pliku źródłowego i tej wersji. Nie dowodzą, że każdy otwór, transformacja, gradient czy wyeksportowany SVG będzie działać tak samo.

Zapisz źródło SVG

Zapisz ten kod jako emblem.svg obok swojej strony. To oryginalna grafika narysowana na potrzeby porównania, a nie wynik wektoryzacji.

<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>

Uruchom obie metody

Umieść ten skrypt na stronie HTML udostępnianej przez HTTP obok pliku emblem.svg. Importuje on wskazaną wersję Pixi, pobiera Twój zaufany SVG i rysuje wersje oryginalne oraz powiększone w dwóch kolumnach. Lewa kolumna używa geometrii; prawa używa tekstury.

<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>

Otwórz również oryginalny SVG w przeglądarce. Porównaj zewnętrzny kontur, otwór, kształt akcentu i położenie, zamiast sprawdzać wyłącznie, czy plik wczytał się bez błędu.

Napraw rozbieżność, którą faktycznie widzisz

Geometria się przesunęła

W tym teście Graphics.svg() nie zastosowało otaczającej transformacji translate(8 8). Implementacja parsera SVG dla wskazanej wersji przydaje się do sprawdzania zachowania wersji używanej w Twoim projekcie.

W przypadku tego konkretnego pliku zastąpienie wiersza ustawiającego pozycję geometrii poniższym kodem kompensuje to jedno znane przesunięcie:

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

Korekta uwzględnia scale, ponieważ pominięte przesunięcie należy do układu współrzędnych źródła. Przy skali 3 korekta wynosi 24 piksele w każdym kierunku. Nie jest to ogólne rozwiązanie do spłaszczania transformacji. Plik z zagnieżdżonymi obrotami, pochyleniami lub różnymi transformacjami na osobnych ścieżkach wymaga odpowiednio przygotowanego SVG do użycia w aplikacji albo innej metody renderowania. Porównaj wyeksportowany plik przeznaczony do użycia z edytowalnym plikiem głównym.

Powiększona tekstura jest nieostra

Tekstura SVG na ilustracji zawiera 96 × 96 pikseli. Skalowanie jej obiektu Sprite do 288 × 288 nie powoduje ponownego odczytania krzywych źródłowych. Aby przygotować więcej pikseli, wczytaj osobną teksturę z wyższą rozdzielczością:

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

W testowanej wersji dało to źródło o wymiarach 288 × 288 pikseli, logicznym rozmiarze tekstury 96 × 96 i rozdzielczości źródła 3. Przy tworzeniu obiektu Sprite użyj largeTexture. Ciąg zapytania nadaje temu eksperymentowi osobny klucz pamięci podręcznej; serwer musi udostępniać ten sam SVG pod tym adresem URL. Assets guide Pixi wyjaśnia buforowanie oparte na adresach URL, a texture guide rozróżnia teksturę i jej źródło.

Dobierz rozdzielczość do największego wymaganego rozmiaru na ekranie, uwzględniając rozdzielczość renderera faktycznie używaną we wdrażanej aplikacji. Samo zwiększenie rozdzielczości renderera nie dodaje szczegółów do już wczytanej tekstury o niskiej rozdzielczości. Sprawdź też najmniejszy rozmiar ikony: większe źródło nie sprawi, że maleńki otwór będzie czytelny, jeśli końcowy rozmiar wyświetlania jest zbyt mały.

Brakuje szczegółu

Sprawdź oryginalne źródło w przeglądarce, a następnie przetestuj uproszczoną kopię w Pixi. Ogranicz SVG do kształtów, których dotyczy problem, i przywracaj kolejno jego grupy, wypełnienia i obrysy oraz efekty. Graphics documentation Pixi opisuje obsługę SVG jako podzbiór funkcji; pomyślne wczytanie nie jest pełnym sprawdzeniem zgodności.

Zachowaj kopię rastrową przeznaczoną do użycia w aplikacji, jeśli niezawodnie zachowuje wygląd grafiki w znanych rozmiarach. W przypadku prostego symbolu geometrycznego rysowanie kształtów bezpośrednio w Pixi może być łatwiejsze w utrzymaniu. Nie wybieraj metody na podstawie niepotwierdzonego pomiarami twierdzenia, że zawsze będzie szybsza lub zużyje mniej pamięci. Przetestuj swoją scenę i urządzenia docelowe.

Przygotuj źródło przed importem

Jeśli SVG zawiera umieszczony obraz PNG, ani zmiana nazwy pliku, ani zaimportowanie go jako geometrii nie odtworzą brakujących konturów wektorowych. Najpierw sprawdź źródło, korzystając z listy kontrolnej dotyczącej osadzonego obrazu rastrowego. Szerszy przewodnik po wektoryzacji obrazów wyjaśnia, kiedy przydaje się trasowanie.

PerfectVector sprawdzi się, gdy pozostał tylko płaski obraz PNG lub JPG, a potrzebujesz edytowalnych kształtów źródłowych ikony. Przekonwertuj obraz na SVG, a następnie sprawdź kontur, oddzielne kolory i małe otwory w edytorze SVG, zanim powtórzysz test w Pixi. Jeśli masz już czysty główny plik grafiki wektorowej, użyj go bezpośrednio. Trasowanie nie naprawia obsługi transformacji w Pixi ani nie konfiguruje rozdzielczości tekstury.

Inne silniki podejmują własne decyzje dotyczące importu. Przewodnik po imporcie SVG do Godot wyjaśnia działanie tekstur i nadpróbkowania w tym silniku; przewodnik po SVG w Unity omawia ten odrębny sposób pracy. Nie przenoś ustawień jednego silnika do drugiego wyłącznie na podstawie rozszerzenia SVG.

Sprawdź ikonę przygotowaną do użycia

Zanim zaakceptujesz zasób, porównaj go ze źródłem renderowanym w przeglądarce w najmniejszym i największym docelowym rozmiarze. Sprawdź otwór na kontrastujących tłach, położenie grupy i wszystkie wymagane efekty. Zapisz wersję Pixi, rozdzielczość renderera, wymiary źródła tekstury w pikselach i skalę w scenie. Zachowaj główny plik SVG w projekcie, aby późniejszą zmianę układu lub importera można było przetestować względem tego samego źródła.

Masz tylko grafikę rastrową? Przygotuj edytowalny SVG za pomocą PerfectVector, sprawdź jego kontur i przestrzeń negatywową, a następnie przetestuj faktycznie używaną metodę importu do Pixi w rozmiarach stosowanych w Twoim interfejsie.

Najczęściej zadawane pytania

Czy import SVG do PixiJS zachowuje go jako geometrię wektorową? To zależy od metody. Graphics.svg parsuje obsługiwaną geometrię rysunku. Wczytanie SVG jako tekstury dostarcza obiektowi Sprite źródło rastrowe. Zachowaj oryginalny SVG osobno do edycji źródła i przyszłych eksportów.

Dlaczego obiekt Sprite z SVG w PixiJS może wyglądać na rozmyty? Obiekt Sprite może wyświetlać teksturę w rozmiarze większym niż jej wymiary w pikselach. Sprawdź rozdzielczość źródła i największy docelowy rozmiar wyświetlania. Wczytaj teksturę o odpowiednich wymiarach lub przetestuj metodę opartą na geometrii dla obsługiwanej grafiki.

Czy Graphics.svg zachowa każdą funkcję SVG? Nie. Obsługuje podzbiór funkcji SVG. W tym przykładzie z PixiJS 8.21.0 otwór i dwa kolory zostały zachowane, ale przesunięcie grupy nie. Porównaj własny wyeksportowany plik z wersją referencyjną w przeglądarce.

Źródła

1. PixiJS SVG guide — Opisuje metody importu jako tekstury i geometrii oraz rozdzielczość tekstury.
2. PixiJS Graphics guide — Wyjaśnia współdzielenie GraphicsContext i zakres obsługi SVG.
3. PixiJS Assets guide — Dokumentuje wczytywanie zasobów i buforowanie oparte na adresach URL.
4. PixiJS texture guide — Opisuje relację między teksturami a ich źródłami.
5. Parser SVG w PixiJS 8.21.0 — Udostępnia implementację dla wskazanej wersji, pomocną przy badaniu różnic w imporcie.