Coordenadas de SVG y las utilidades de path

La mitad de los problemas de animación en SVG que parecen misteriosos son problemas de coordenadas. Un elemento que aparece a 300 píxeles de donde debería, un trazado que se recorre a escala equivocada, un punto calculado con getBoundingClientRect que no cuadra con las coordenadas del viewBox. La causa siempre es la misma: hay varios sistemas de coordenadas en juego y se están mezclando números de unos con números de otros. MotionPathPlugin expone, casi como efecto colateral, el juego de herramientas más completo que hay para operar entre esos espacios.

Cuántos sistemas hay en juego

En una página con un SVG hay al menos cuatro espacios distintos, y confundirlos es lo que produce los desajustes.

El espacio del viewport, que es el que devuelve getBoundingClientRect: píxeles CSS medidos desde la esquina superior izquierda de la ventana visible.

El espacio del documento, igual que el anterior pero sin restar el scroll.

El espacio del viewBox, que es el sistema interno del SVG. Si un SVG tiene viewBox="0 0 100 100" y ocupa 400 píxeles de ancho en pantalla, cada unidad del viewBox vale cuatro píxeles.

Y el espacio local de cada elemento, resultado de componer todas las transformaciones de sus ancestros. Un grupo con transform="translate(20,30) scale(2)" define un espacio para sus hijos que no coincide con el del viewBox.

Las coordenadas del atributo d de un path están en el espacio local del elemento. Las que devuelve getBoundingClientRect están en el del viewport. Y las transformaciones x e y que aplica GSAP a un elemento se expresan en el espacio de su padre. Mezclar tres espacios sin convertir es la receta del desajuste.

// Estos dos numeros NO son comparables aunque ambos se llamen x
const rect = elemento.getBoundingClientRect();   // espacio del viewport
const cx = circulo.getAttribute("cx");           // espacio local del circulo

convertCoordinates

El método que resuelve el caso general. Recibe un elemento de origen, un elemento de destino y un punto en el espacio del primero, y devuelve el punto equivalente en el espacio del segundo.

import { gsap } from "gsap";
import { MotionPathPlugin } from "gsap/MotionPathPlugin";

gsap.registerPlugin(MotionPathPlugin);

// Punto en coordenadas del SVG, expresado en coordenadas del contenedor HTML
const punto = MotionPathPlugin.convertCoordinates(
  document.querySelector("svg"),
  document.querySelector(".panel"),
  { x: 50, y: 80 }
);

gsap.set(".marcador", { x: punto.x, y: punto.y });

Acepta window como cualquiera de los dos elementos, lo que da conversiones a y desde el espacio del viewport. Si en lugar de un punto no le pasas nada, devuelve la matriz de conversión, que puedes reutilizar para muchos puntos sin recalcularla.

Este es el método que hace posible el caso que parece imposible: colocar un elemento de HTML exactamente encima de un punto de un SVG, con el SVG escalado, dentro de un contenedor rotado, con la página desplazada. Todo eso lo absorbe la composición de matrices.

getRelativePosition y getGlobalMatrix

getRelativePosition es la versión abreviada del caso más habitual: dónde está un elemento respecto a otro, medido desde un punto de origen concreto de cada uno.

// Vector desde el centro del boton hasta el centro del objetivo
const d = MotionPathPlugin.getRelativePosition(
  document.querySelector(".boton"),
  document.querySelector(".objetivo"),
  [0.5, 0.5],   // origen en el elemento de partida
  [0.5, 0.5]    // origen en el elemento de destino
);

gsap.to(".boton", { x: d.x, y: d.y, duration: 0.6 });

Los dos arrays son progresos dentro de la caja de cada elemento, igual que alignOrigin: [0.5, 0.5] es el centro, [0, 0] la esquina superior izquierda.

Es exactamente lo que necesitas para “mueve este elemento hasta encima de aquel otro”, sin importar cuántos contenedores transformados haya entre ellos, y es notablemente más fiable que restar dos getBoundingClientRect, porque esa resta ignora las escalas de los ancestros.

getGlobalMatrix devuelve la matriz de transformación acumulada de un elemento respecto al viewport, y con el segundo parámetro a true devuelve su inversa. Es el nivel más bajo y el que usarías si estuvieras construyendo tu propia capa.

Las utilidades de RawPath

Un RawPath es la representación interna que GSAP usa para los trazados: un array que contiene un array por cada subcontorno, y dentro, coordenadas alternadas de curvas cúbicas de Bézier. Un path con dos comandos M produce dos subarrays.

// <path d="M0,0 C10,20,15,30,5,18 M0,100 C50,120,80,110,100,100">
// se convierte en:
[
  [0, 0, 10, 20, 15, 30, 5, 18],
  [0, 100, 50, 120, 80, 110, 100, 100],
]

Sea cual sea el comando original —líneas, arcos, cuadráticas— el RawPath siempre son cúbicas. Esa uniformidad es lo que hace posible operar sobre él.

La combinación más útil es la de obtener puntos a lo largo de un trazado para colocar cosas.

// Repartir doce puntos a lo largo de una curva
const raw = MotionPathPlugin.getRawPath("#ruta");

for (let i = 0; i < 12; i++) {
  const p = MotionPathPlugin.getPositionOnPath(raw, i / 11, true);
  const punto = document.createElement("div");
  punto.className = "punto";
  document.body.appendChild(punto);
  gsap.set(punto, { x: p.x, y: p.y, rotation: p.angle });
}

Y sliceRawPath permite construir el path de un tramo y asignarlo a un elemento, lo que da un efecto de trazado que crece por segmentos con control total.

const raw = MotionPathPlugin.getRawPath("#ruta");
const tramo = MotionPathPlugin.sliceRawPath(raw, 0.2, 0.6);
document.querySelector("#tramo").setAttribute("d", MotionPathPlugin.rawPathToString(tramo));