SVGGraphicsElement.getCTM() — Methode · JavaScript-Referenz

Signatur

SVGGraphicsElement.prototype.getCTM()

Beschreibung

getCTM() („Current Transformation Matrix“) liefert eine Matrix, in der alle Transformationen zwischen dem Element und seinem nächsten Viewport-Element zusammengefasst sind. Das ist in der Regel das umgebende <svg>-Element. Dazu zählen die transform-Attribute des Elements selbst und aller Vorfahren bis zum Viewport, ebenso eine eventuell vorhandene viewBox-Abbildung dieses Viewports.

Die Methode ist nützlich, wenn du wissen willst, wo ein Punkt aus dem lokalen Koordinatenraum eines Elements im Viewport liegt. Beispiele sind das Ausrichten von Beschriftungen, Kollisionsprüfungen, das Berechnen von Verbindungslinien zwischen verschachtelten Gruppen oder das Auslesen der tatsächlich wirksamen Skalierung und Rotation.

Wichtig ist der Unterschied zu getScreenCTM(): getCTM() endet am nächsten SVG-Viewport, getScreenCTM() rechnet dagegen bis in die Bildschirm- bzw. Client-Koordinaten des Dokuments. Für Mauskoordinaten (clientX/clientY) brauchst du deshalb fast immer getScreenCTM().

Die Matrix hat die Form [a c e; b d f; 0 0 1]. a/d enthalten Skalierung (bzw. zusammen mit b/c die Rotation), e/f die Verschiebung.

Rückgabewert

Typ

DOMMatrix | null

Beschreibung

Eine DOMMatrix (in älteren Spezifikationen und Browsern SVGMatrix, heute ein Alias von DOMMatrix) mit der zusammengefassten Transformation in den Viewport. Kann die Matrix nicht bestimmt werden, z. B. weil das Element nicht im Dokument hängt oder nicht gerendert wird, geben manche Browser null zurück.

Beispiele

Verschachtelte Transformationen auslesen

const svgNS = 'http://www.w3.org/2000/svg';
const svg = document.createElementNS(svgNS, 'svg');
svg.setAttribute('width', '300');
svg.setAttribute('height', '200');

const group = document.createElementNS(svgNS, 'g');
group.setAttribute('transform', 'translate(50, 20)');

const rect = document.createElementNS(svgNS, 'rect');
rect.setAttribute('width', '40');
rect.setAttribute('height', '20');
rect.setAttribute('transform', 'scale(2)');

group.append(rect);
svg.append(group);
document.body.append(svg); // Element muss im Dokument hängen

const m = rect.getCTM();
console.log(m.a, m.b, m.c, m.d, m.e, m.f);

2 0 0 2 50 20

Lokalen Punkt in Viewport-Koordinaten umrechnen

// Fortsetzung: rect aus dem vorherigen Beispiel
const ctm = rect.getCTM();

// Rechte untere Ecke des Rechtecks im lokalen Koordinatensystem
const local = new DOMPoint(40, 20);
const inViewport = local.matrixTransform(ctm);

console.log(`x=${inViewport.x}, y=${inViewport.y}`);

x=130, y=60

Viewport-Punkt zurück in lokale Koordinaten (inverse Matrix)

// Wo liegt der Viewport-Punkt (100, 50) im lokalen Raum von rect?
const toLocal = rect.getCTM().inverse();
const p = new DOMPoint(100, 50).matrixTransform(toLocal);

console.log(p.x, p.y);

25 15

Abgrenzung: Mausklick ins SVG-Koordinatensystem umrechnen

// Für clientX/clientY braucht man getScreenCTM(), nicht getCTM()
svg.addEventListener('click', (event) => {
  const screenCTM = rect.getScreenCTM();
  if (!screenCTM) return; // Element nicht gerendert
  const pt = new DOMPoint(event.clientX, event.clientY)
    .matrixTransform(screenCTM.inverse());
  console.log(`Lokal im rect: ${pt.x.toFixed(1)}, ${pt.y.toFixed(1)}`);
});

// Wichtig · Fallstricke

Nicht mit Bildschirmkoordinaten verwechseln: getCTM() endet am nächsten SVG-Viewport. Die Position des <svg> auf der Seite, Scrollen und CSS-Transformationen auf HTML-Vorfahren werden nicht berücksichtigt. Für Maus- und Touch-Koordinaten nimm getScreenCTM().
Verschachtelte <svg>-Elemente: Jedes innere <svg> bildet einen eigenen Viewport. Die Matrix bezieht sich dann auf diesen inneren Viewport und nicht auf das äußere SVG. Ältere Browser-Versionen haben sich hier teils unterschiedlich verhalten.
null möglich: Bei Elementen, die nicht im Dokument hängen oder nicht gerendert werden (z. B. display: none, Inhalt von <defs>), kann null oder eine Einheitsmatrix zurückkommen. Prüfe den Rückgabewert vor der Nutzung.
Momentaufnahme: Die zurückgegebene Matrix ist eine Kopie. Ändert sich später ein transform, musst du getCTM() erneut aufrufen. Änderungen an der Matrix wirken nicht zurück auf das Element.
CSS-Transformationen (transform als CSS-Eigenschaft auf SVG-Elementen) fließen in modernen Browsern mit ein. Bei transform-origin und Animationen können sich die Engines in Details unterscheiden.
Kompatibilität: Wird von allen modernen Browsern unterstützt. Früher lieferte die Methode ein SVGMatrix, heute ist das ein Alias von DOMMatrix. Die alten Hilfsmethoden wie svg.createSVGPoint() funktionieren weiterhin, für neuen Code ist aber DOMPoint vorzuziehen.

Siehe auch

SVGGraphicsElement.getBBox() SVGGraphicsElement.getScreenCTM() SVGImageElement.decode() Element.getHTML() SVGElement.focus() new PromiseRejectionEvent() new WheelEvent()