Importar SVG no PixiJS: escolha Graphics ou uma textura

O PixiJS pode usar um SVG de duas maneiras: Graphics.svg() interpreta a geometria de desenho compatível, enquanto carregar o SVG como textura fornece pixels para um Sprite exibir. Escolha geometria quando a arte precisar de grandes mudanças de escala, e uma textura quando uma imagem raster ajustada ao tamanho de exibição pretendido for adequada ao recurso. O PixiJS descreve as duas opções em seu guia de SVG.

Teste o mesmo arquivo pelas duas opções antes de escolher. Nosso pequeno emblema manteve sua abertura e suas cores nas duas, mas a opção de geometria perdeu a translação do grupo. A textura correspondeu ao posicionamento no navegador e ficou menos nítida quando ampliada. São problemas separados, com correções diferentes.

Decida o que a cena precisa

Um objeto Graphics é conteúdo de desenho do Pixi, não uma árvore DOM SVG com os IDs originais dos elementos. Seu contexto pode ser compartilhado entre instâncias, como explica o guia de Graphics. Mantenha o SVG original quando precisar editar traçados individuais do SVG original ou exportar outro SVG depois. As duas opções acabam desenhando pixels na tela.

Teste uma curva, um vazado e uma transformação

Este exemplo usa PixiJS 8.21.0, um SVG de 96 × 96, resolução do renderizador 1 e uma textura SVG carregada com resolução 1. A versão pequena é desenhada no tamanho nativo; a grande usa escala 3. O emblema original tem dois traçados coloridos e um grupo transladado em oito unidades SVG em cada direção. Seu contorno interno segue a orientação oposta à do contorno externo para formar a abertura.

O mesmo SVG original em três renderizadores

O quadriculado aparece através da abertura nas três colunas. Ele é um fundo atrás da arte, não uma forma branca pintada no vazado. O deslocamento da coluna central é visível nos dois tamanhos: oito unidades na escala nativa se tornam 24 pixels de exibição na escala 3.

Essas observações se aplicam a este SVG original e a esta versão. Elas não demonstram que todos os vazados, transformações, gradientes ou SVGs exportados funcionarão da mesma maneira.

Salve o SVG original

Salve isto como emblem.svg ao lado da sua página. É uma arte original desenhada para a comparação, não um resultado de vetorização.

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

Execute as duas opções

Coloque este script em uma página HTML servida por HTTP junto de emblem.svg. Ele importa a versão fixada do Pixi, busca seu SVG confiável e desenha versões nativas e ampliadas em duas colunas. A coluna esquerda usa geometria; a direita usa uma textura.

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

Abra também o SVG original no navegador. Compare o contorno externo, a abertura, a forma de destaque e o posicionamento, em vez de conferir somente se o arquivo carregou sem erro.

Corrija a diferença que você realmente observa

A geometria mudou de posição

Neste teste, Graphics.svg() não aplicou o translate(8 8) do grupo envolvente. A implementação do interpretador SVG na versão fixada é útil para conferir o comportamento da versão do seu projeto.

Para este arquivo específico, substituir a linha de posição da geometria pela seguinte compensa essa única translação conhecida:

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

A correção inclui scale porque a translação ausente pertence ao sistema de coordenadas do SVG original. Na escala 3, a correção é de 24 pixels em cada direção. Isso não é uma ferramenta geral para incorporar transformações à geometria. Um arquivo com rotações ou inclinações aninhadas, ou transformações diferentes em traçados separados, precisa de um SVG de entrega devidamente preparado ou de outra opção de renderização. Compare o arquivo exportado para entrega com o mestre editável.

A textura ampliada perdeu nitidez

A textura SVG da figura contém 96 × 96 pixels. Escalar seu sprite para 288 × 288 não relê as curvas do SVG original. Para preparar mais pixels, carregue uma textura separada com resolução maior:

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

Na versão testada, isso produziu uma fonte de textura de 288 × 288 pixels com tamanho lógico de textura de 96 × 96 e resolução da fonte 3. Use largeTexture ao criar o sprite. A string de consulta dá a esse experimento uma chave de cache distinta; o servidor precisa servir o mesmo SVG nessa URL. O guia de Assets do Pixi explica seu cache baseado em URL, e seu guia de texturas distingue uma textura de sua fonte.

Selecione a resolução para o maior uso necessário na tela, incluindo a resolução do renderizador que você efetivamente entrega. Aumentar apenas a resolução do renderizador não acrescenta detalhes a uma textura de baixa resolução já carregada. Confira também o menor tamanho do ícone: uma fonte de textura maior não consegue tornar uma abertura minúscula legível se a exibição final for pequena demais.

Falta um detalhe

Confira o SVG original em um navegador e teste uma cópia mais simples no Pixi. Reduza o SVG às formas afetadas e acrescente de volta seus grupos, pintura e efeitos, um por vez. A documentação de Graphics do Pixi descreve o suporte a SVG como um subconjunto; carregar com sucesso não é uma verificação completa de compatibilidade.

Mantenha uma cópia raster para entrega quando ela preservar a arte de maneira confiável em tamanhos conhecidos. Para um símbolo geométrico simples, desenhar as formas diretamente no Pixi pode ser mais fácil de manter. Não escolha uma opção com base em uma afirmação sem medição de que ela sempre será mais rápida ou usará menos memória. Teste sua cena e os dispositivos de destino.

Prepare o arquivo original antes de importar

Se um SVG contém um PNG inserido, mudar seu nome de arquivo ou importá-lo como geometria não reconstrói os contornos vetoriais ausentes. Use a lista de verificação de imagens raster incorporadas para inspecionar primeiro o arquivo original. O guia mais amplo de vetorização de imagens explica quando a vetorização é útil.

O PerfectVector é adequado quando resta apenas um PNG ou JPG de imagem plana e você precisa de formas originais editáveis para o ícone. Converta sua imagem para SVG e inspecione o contorno, as cores separadas e as pequenas aberturas em um editor SVG antes de repetir o teste no Pixi. Use diretamente um arquivo mestre vetorial limpo existente. A vetorização não corrige o tratamento de transformações do Pixi nem configura a resolução da textura.

Outros motores fazem suas próprias escolhas de importação. O guia de importação SVG no Godot explica o comportamento de texturas e sobreamostragem nele; o guia de SVG no Unity aborda esse fluxo separado. Não transfira as configurações de um motor para outro com base apenas na extensão SVG.

Confira o ícone entregue

Antes de aceitar o recurso, compare-o com o SVG original renderizado no navegador nos menores e maiores tamanhos pretendidos. Confira a abertura sobre fundos contrastantes, o posicionamento do grupo e quaisquer efeitos necessários. Registre a versão do Pixi, a resolução do renderizador, as dimensões em pixels da fonte da textura e a escala da cena. Mantenha o mestre SVG com o projeto para que uma alteração posterior no layout ou no importador possa ser testada contra o mesmo SVG original.

Você só tem uma arte raster? Prepare um SVG editável com o PerfectVector, inspecione seu contorno e espaço negativo e teste a opção real de importação do Pixi nos tamanhos usados pela sua interface.

Perguntas frequentes

Importar um SVG no PixiJS o mantém como geometria vetorial? Depende da opção. Graphics.svg interpreta a geometria de desenho compatível. Carregar um SVG como textura fornece uma fonte raster a um Sprite. Mantenha o SVG original separadamente para editar o arquivo original e fazer exportações futuras.

Por que um sprite SVG do PixiJS pode parecer borrado? Um sprite pode exibir sua textura em um tamanho maior que as dimensões em pixels da textura. Confira a resolução da fonte e o maior tamanho pretendido de exibição. Carregue uma textura de tamanho adequado ou teste a opção de geometria para artes compatíveis.

Graphics.svg preserva todos os recursos de SVG? Não. Ele oferece suporte a um subconjunto de SVG. Neste exemplo com PixiJS 8.21.0, o vazado e as duas cores foram preservados, mas a translação do grupo não. Teste seu próprio arquivo exportado contra uma referência no navegador.

Fontes

1. Guia de SVG do PixiJS — Descreve as opções de importação como textura e geometria e a resolução da textura.
2. Guia de Graphics do PixiJS — Explica o compartilhamento de GraphicsContext e os limites do suporte a SVG.
3. Guia de Assets do PixiJS — Documenta o carregamento de recursos e o cache baseado em URL.
4. Guia de texturas do PixiJS — Descreve a relação entre texturas e suas fontes.
5. Interpretador SVG do PixiJS 8.21.0 — Fornece a implementação na versão fixada para investigar diferenças na importação.