Importar SVG en PixiJS: elige Graphics o una textura

PixiJS puede usar un SVG de dos formas: Graphics.svg() analiza geometría de dibujo compatible, mientras que cargar el SVG como textura proporciona a un Sprite píxeles que mostrar. Elige geometría cuando la ilustración necesite cambios de escala importantes y una textura cuando una imagen rasterizada ajustada al tamaño de visualización previsto sea adecuada para el recurso. PixiJS describe ambos métodos en su guía SVG.

Prueba el mismo archivo con ambos métodos antes de elegir. Nuestro pequeño emblema conservó su abertura y colores en ambos, pero el método geométrico perdió la traslación de su grupo. La textura coincidió con la posición del navegador y se volvió menos nítida al ampliarla. Son problemas independientes con soluciones diferentes.

Decide qué necesita la escena

Un objeto Graphics es contenido de dibujo de Pixi, no un árbol DOM SVG con los IDs de elementos originales. Su contexto puede compartirse entre instancias, como explica la guía de Graphics. Conserva el SVG original cuando necesites editar trazados individuales o exportar otro SVG después. Ambos métodos terminan dibujando píxeles en pantalla.

Prueba una curva, un hueco y una transformación

Este ejemplo usa PixiJS 8.21.0, un SVG de 96 × 96, resolución de renderizador 1 y una textura SVG cargada con resolución 1. La versión pequeña se dibuja a tamaño nativo; la grande usa escala 3. El emblema original tiene dos trazados de color y un grupo trasladado ocho unidades SVG en cada dirección. Su contorno interior recorre el sentido opuesto al exterior para formar la abertura.

El mismo SVG original en tres renderizadores

El damero se ve a través de la abertura en las tres columnas. Es un fondo detrás de la ilustración, no una forma blanca pintada dentro del hueco. El desplazamiento de la columna central es visible a ambos tamaños: ocho unidades a escala nativa se convierten en 24 píxeles de visualización a escala 3.

Estas observaciones se aplican a este original y esta versión. No demuestran que todos los huecos, transformaciones, degradados o SVG exportados funcionen igual.

Guarda el original SVG

Guarda esto como emblem.svg junto a tu página. Es una ilustración original dibujada para la comparación, no un resultado de vectorización.

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

Ejecuta ambos métodos

Coloca este script en una página HTML servida mediante HTTP junto a emblem.svg. Importa la compilación fijada de Pixi, obtiene tu SVG de confianza y dibuja versiones nativas y ampliadas en dos columnas. La izquierda usa geometría; la derecha, una 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>

Abre también el SVG original en el navegador. Compara el contorno exterior, la abertura, la forma decorativa y la posición, no solo si el archivo se cargó sin errores.

Corrige la diferencia que realmente ves

La geometría se ha desplazado

En esta prueba, Graphics.svg() no aplicó el translate(8 8) del grupo contenedor. La implementación del analizador SVG fijada a esta versión es útil para comprobar el comportamiento de la versión de tu proyecto.

Para este archivo concreto, sustituir la línea de posición de geometría por la siguiente compensa esa única traslación conocida:

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

La corrección incluye scale porque la traslación ausente pertenece al sistema de coordenadas del original. A escala 3, la corrección es de 24 píxeles en cada dirección. Esto no es una solución general para incorporar transformaciones a la geometría. Un archivo con rotaciones anidadas, inclinaciones o transformaciones distintas en trazados separados necesita un SVG de entrega debidamente preparado u otro método de renderizado. Compara el archivo de entrega exportado con el archivo maestro editable.

La textura ampliada pierde nitidez

La textura SVG de la figura contiene 96 × 96 píxeles. Escalar su sprite a 288 × 288 no vuelve a leer las curvas originales. Para preparar más píxeles, carga una textura independiente con mayor resolución:

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

En la compilación probada, esto produjo un original de 288 × 288 píxeles con un tamaño lógico de textura de 96 × 96 y resolución de origen 3. Usa largeTexture al crear el sprite. La cadena de consulta da a este experimento una clave de caché distinta; el servidor debe servir el mismo SVG para esa URL. La guía de Assets de Pixi explica su caché basada en URL y su guía de texturas distingue una textura de su origen.

Elige la resolución para el mayor uso necesario en pantalla, incluida la resolución de renderizador que realmente publiques. Aumentar solo la resolución del renderizador no añade detalle a una textura de baja resolución ya cargada. Comprueba también el tamaño mínimo del icono: un original mayor no puede hacer legible una abertura diminuta si la visualización final es demasiado pequeña.

Falta un detalle

Comprueba el original en un navegador y prueba después una copia más sencilla en Pixi. Reduce el SVG a las formas afectadas y vuelve a añadir sus grupos, pintura y efectos uno a uno. La documentación de Graphics de Pixi describe la compatibilidad SVG como un subconjunto; cargarse correctamente no es una comprobación completa de compatibilidad.

Conserva una copia rasterizada de entrega cuando preserve de forma fiable la ilustración a tamaños conocidos. Para un símbolo geométrico sencillo, dibujar las formas directamente en Pixi puede ser más fácil de mantener. No elijas un método basándote en una afirmación no medida de que siempre será más rápido o usará menos memoria. Prueba tu escena y los dispositivos de destino.

Prepara el original antes de importar

Si un SVG contiene un PNG colocado, cambiar su nombre o importarlo como geometría no reconstruye los contornos vectoriales ausentes. Usa la lista de comprobación de imágenes rasterizadas incrustadas para inspeccionar primero el original. La guía general de vectorización de imágenes explica cuándo es útil vectorizar.

PerfectVector encaja cuando solo queda un PNG o JPG plano y necesitas formas de origen editables para el icono. Convierte tu imagen en SVG e inspecciona el contorno, los colores separados y las aberturas pequeñas en un editor SVG antes de repetir la prueba de Pixi. Usa directamente un archivo maestro vectorial limpio existente. La vectorización no corrige el tratamiento de transformaciones de Pixi ni configura la resolución de texturas.

Otros motores toman sus propias decisiones de importación. La guía de importación SVG de Godot explica su comportamiento de texturas y sobremuestreo; la guía SVG de Unity cubre ese flujo independiente. No transfieras los ajustes de un motor a otro basándote solo en la extensión SVG.

Comprueba el icono entregado

Antes de aceptar el recurso, compáralo con el original renderizado en navegador a los tamaños mínimo y máximo previstos. Comprueba la abertura sobre fondos contrastantes, la posición del grupo y los efectos necesarios. Registra la versión de Pixi, la resolución del renderizador, las dimensiones en píxeles del origen de textura y la escala de escena. Conserva el archivo maestro SVG con el proyecto para poder probar futuros cambios de distribución o importador contra el mismo original.

¿Solo tienes una ilustración rasterizada? Prepara un SVG editable con PerfectVector, inspecciona su contorno y espacio negativo y prueba el método real de importación Pixi a los tamaños que usa tu interfaz.

Preguntas frecuentes

¿Importar un SVG en PixiJS lo conserva como geometría vectorial? Depende del método. Graphics.svg analiza geometría de dibujo compatible. Cargar un SVG como textura proporciona a un Sprite un origen rasterizado. Conserva el SVG original por separado para editarlo y exportarlo después.

¿Por qué puede verse borroso un sprite SVG de PixiJS? Un sprite puede mostrar su textura a un tamaño mayor que sus dimensiones en píxeles. Comprueba la resolución de origen y el mayor tamaño de visualización previsto. Carga una textura de tamaño adecuado o prueba el método geométrico para ilustraciones compatibles.

¿Graphics.svg conservará todas las funciones SVG? No. Admite un subconjunto de SVG. En este ejemplo de PixiJS 8.21.0 se conservaron el hueco y los dos colores, pero no la traslación del grupo. Prueba tu propio archivo exportado frente a una referencia del navegador.

Fuentes

1. Guía SVG de PixiJS — Describe los métodos de importación de textura y geometría y la resolución de textura.
2. Guía de Graphics de PixiJS — Explica cómo compartir GraphicsContext y los límites de compatibilidad SVG.
3. Guía de Assets de PixiJS — Documenta la carga de recursos y la caché basada en URL.
4. Guía de texturas de PixiJS — Describe la relación entre las texturas y sus orígenes.
5. Analizador SVG de PixiJS 8.21.0 — Proporciona la implementación fijada a la versión para investigar diferencias de importación.