Signatur
Beschreibung
rotateAxisAngle() multipliziert die aktuelle Matrix von rechts mit einer 3D-Drehmatrix. Die Drehung erfolgt um eine beliebige Achse, die durch den Vektor (rotX, rotY, rotZ) beschrieben wird, um den Winkel angle in Grad. Das Ergebnis entspricht der CSS-Funktion rotate3d(x, y, z, angle).
Die Methode ist nicht verändernd: Die Ausgangsmatrix bleibt unverändert, zurückgegeben wird immer eine neue DOMMatrix. Willst du die Matrix direkt verändern, nimm die veränderbare Variante DOMMatrix.prototype.rotateAxisAngleSelf().
Der Achsenvektor wird intern normiert, seine Länge spielt also keine Rolle, nur seine Richtung. Sobald rotX oder rotY ungleich 0 ist, wird die Ergebnismatrix zu einer 3D-Matrix (is2D === false). Eine Drehung nur um die Z-Achse (0, 0, 1) bleibt 2D und entspricht rotate(angle).
Typische Anwendungen sind 3D-Effekte in CSS (Karten umdrehen, Würfel drehen), eigene Transformationsberechnungen für Canvas bzw. WebGL-nahe Logik und das Transformieren einzelner Punkte mit DOMPoint.matrixTransform().
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $rotX | number | 0 | X-Komponente des Achsenvektors. |
| $rotY | number | 0 | Y-Komponente des Achsenvektors. |
| $rotZ | number | 0 | Z-Komponente des Achsenvektors. |
| $angle | number | 0 | Drehwinkel in Grad (nicht im Bogenmaß). Positive Werte drehen im Uhrzeigersinn, wenn man entgegen der Achsrichtung blickt (Koordinatensystem mit Y-Achse nach unten, wie in CSS). |
Rückgabewert
DOMMatrix, die aus der Ausgangsmatrix und der angehängten Drehung besteht. Die Ausgangsmatrix bleibt unverändert.Beispiele
Drehung um die Z-Achse entspricht rotate()
const base = new DOMMatrixReadOnly();
const rotated = base.rotateAxisAngle(0, 0, 1, 90);
console.log(rotated.is2D);
console.log(rotated.toString());
console.log(base.isIdentity); // Ausgangsmatrix bleibt unverändertPunkt um die Y-Achse drehen
const m = new DOMMatrixReadOnly().rotateAxisAngle(0, 1, 0, 90);
const p = new DOMPoint(1, 0, 0).matrixTransform(m);
// Rundungsfehler bei Gleitkommazahlen glätten
const round = (n) => Math.round(n * 1e6) / 1e6 + 0;
console.log(round(p.x), round(p.y), round(p.z));
console.log(m.is2D);3D-Drehung einer Karte per CSS-Transform
const card = document.querySelector('.card');
const start = new DOMMatrixReadOnly('perspective(800px)');
let angle = 0;
const tick = () => {
angle = (angle + 2) % 360;
// Diagonale Achse – wird intern normiert
const m = start.rotateAxisAngle(1, 1, 0, angle);
card.style.transform = m.toString(); // ergibt matrix3d(...)
requestAnimationFrame(tick);
};
requestAnimationFrame(tick);// Wichtig · Fallstricke
- Grad statt Bogenmaß: Anders als
Math.sin()/Math.cos()erwartetangleGrad. WerMath.PI / 2übergibt, dreht nur um etwa 1,57°. - Gleitkomma-Ungenauigkeit: Werte wie
cos(90°)ergeben6.123233995736766e-17statt0. Vergleiche daher mit einer Toleranz und nicht mit===. - Nullvektor: Sind alle drei Achsenkomponenten 0 (das ist der Standard, wenn man sie weglässt), lässt sich keine Achse bestimmen und es findet keine sinnvolle Drehung statt. Gib die Achse daher immer ausdrücklich an.
- 2D wird zu 3D: Ist
rotXoderrotYungleich 0, wirdis2Dauffalsegesetzt.toString()liefert dannmatrix3d(...), und das Ergebnis lässt sich nicht mehr verlustfrei als 2D-Canvas-Transformation (setTransform) verwenden. - Reihenfolge: Die Drehung wird von rechts multipliziert, wirkt also im lokalen Koordinatensystem nach den bereits vorhandenen Transformationen. Die Reihenfolge verketteter Aufrufe ist entscheidend.
- Kompatibilität: Wird von allen aktuellen Browsern unterstützt, auch in Web Workern. In Node.js gibt es
DOMMatrixnicht von Haus aus, dort braucht man Polyfills (z. B. auscanvas- oderjsdom-Umgebungen).