DOMPointReadOnly.matrixTransform() — Methode · JavaScript-Referenz

Signatur

DOMPointReadOnly.prototype.matrixTransform(matrix)

Beschreibung

matrixTransform() multipliziert eine 4×4-Transformationsmatrix mit dem Punkt. Der Punkt wird dabei als homogener Spaltenvektor (x, y, z, w) behandelt. Die Methode gibt einen neuen DOMPoint zurück. Der ursprüngliche Punkt bleibt unverändert, das gilt auch, wenn die Methode auf einem veränderbaren DOMPoint aufgerufen wird, der sie erbt.

Typische Anwendungsfälle:

Koordinaten zwischen Koordinatensystemen umrechnen, z. B. Mausposition in lokale Canvas- oder SVG-Koordinaten.
Punkte eines Polygons verschieben, drehen oder skalieren, ohne die Rechnung selbst zu schreiben.
Eckpunkte von 3D-Transformationen berechnen, etwa für Treffertests oder Begrenzungsrahmen.

Als Argument eignet sich ein DOMMatrix- oder DOMMatrixReadOnly-Objekt oder ein einfaches Objekt nach dem DOMMatrixInit-Schema, z. B. { a: 2, d: 2 }. Nicht angegebene Werte werden mit denen der Einheitsmatrix aufgefüllt.

Ist die Matrix 2D und hat der Punkt z = 0 und w = 1, entspricht das Ergebnis einer normalen affinen 2D-Transformation. Bei 3D- oder Perspektivmatrizen kann sich w ändern. Die Division durch w wird nicht automatisch durchgeführt.

Parameter

Name	Typ	Default	Beschreibung
$matrix	DOMMatrix \| DOMMatrixReadOnly \| DOMMatrixInit	{} (Einheitsmatrix)	Die Matrix, die auf den Punkt angewendet wird. Möglich sind ein Matrixobjekt oder ein Objekt mit den Eigenschaften `a`–`f`, `m11`–`m44` bzw. `is2D`.

Rückgabewert

Typ

DOMPoint

Beschreibung

Ein neuer, veränderbarer DOMPoint mit den transformierten Koordinaten x, y, z und w.

Beispiele

Punkt verschieben und skalieren

const point = new DOMPointReadOnly(10, 20);
// Zuerst verschieben, dann skalieren (Reihenfolge der Matrix-Methoden beachten)
const matrix = new DOMMatrix().translate(5, 5).scale(2);

const result = point.matrixTransform(matrix);
console.log(result.x, result.y, result.z, result.w);
console.log(point.x, point.y); // Original bleibt unverändert

25 45 0 1 10 20

Einfaches DOMMatrixInit-Objekt statt DOMMatrix

const point = new DOMPointReadOnly(3, 4);

// Skalierung um Faktor 2 in x und 3 in y
const scaled = point.matrixTransform({ a: 2, d: 3 });
console.log(`${scaled.x}, ${scaled.y}`);

6, 12

Punkt um 90° drehen (Rundungsfehler beachten)

const point = new DOMPointReadOnly(1, 0);
const rotated = point.matrixTransform(new DOMMatrix().rotate(90));

// Fließkomma-Artefakte beim Runden entfernen
const round = (n) => Math.round(n * 1e6) / 1e6;
console.log(round(rotated.x), round(rotated.y));

0 1

Mausposition in lokale Canvas-Koordinaten umrechnen

const canvas = document.querySelector('canvas');
const ctx = canvas.getContext('2d');

// Zeichenkontext ist verschoben, gedreht und gezoomt
ctx.setTransform(new DOMMatrix().translate(200, 150).rotate(30).scale(1.5));

canvas.addEventListener('click', (event) => {
  const rect = canvas.getBoundingClientRect();
  const screenPoint = new DOMPointReadOnly(
    event.clientX - rect.left,
    event.clientY - rect.top
  );
  // Inverse Matrix: Bildschirmkoordinaten -> Zeichenkoordinaten
  const local = screenPoint.matrixTransform(ctx.getTransform().inverse());
  console.log(`Lokal: ${local.x.toFixed(1)}, ${local.y.toFixed(1)}`);
});

z. B. "Lokal: 12.3, -40.7" (abhängig von der Klickposition)

// Wichtig · Fallstricke

Keine Perspektiv-Division: Bei Matrizen mit Perspektive (z. B. m34 ≠ 0) ist w im Ergebnis nicht 1. Für Bildschirmkoordinaten musst du selbst x / w und y / w rechnen.
Widersprüchliche Angaben: Enthält ein DOMMatrixInit-Objekt unterschiedliche Werte für gleichbedeutende Felder (z. B. a: 2, m11: 3), wird ein TypeError geworfen. Dasselbe passiert, wenn is2D: true zusammen mit 3D-Werten angegeben wird.
Reihenfolge: Gerechnet wird Matrix × Punkt. Bei verketteten Aufrufen wie translate().scale() wirkt die zuletzt angehängte Transformation zuerst auf den Punkt.
Fließkomma: Nach Drehungen entstehen oft Werte wie 6.12e-17 statt 0. Vor Vergleichen deshalb runden.
Kompatibilität: Wird in allen aktuellen Browsern unterstützt, auch in Web Workern. Node.js bietet DOMPoint nicht von Haus aus an, dort ist ein Polyfill oder eine Bibliothek nötig.

Siehe auch

DOMPointReadOnly DOMPoint DOMMatrix DOMMatrixReadOnly.transformPoint() DOMMatrixReadOnly.inverse() CanvasRenderingContext2D.getTransform()