DOMMatrix.rotateAxisAngleSelf() — Methode · JavaScript-Referenz

Signatur

DOMMatrix.prototype.rotateAxisAngleSelf(x, y, z, angle)

Beschreibung

rotateAxisAngleSelf() multipliziert die aktuelle DOMMatrix von rechts mit einer Rotationsmatrix. Diese dreht um eine frei wählbare Achse, die durch den Vektor (x, y, z) festgelegt ist. Der Winkel wird in Grad angegeben. Das Ergebnis entspricht der CSS-Funktion rotate3d(x, y, z, angle).

Anders als rotateAxisAngle() legt die Methode keine Kopie an, sondern verändert die Matrix selbst (in place). Zurückgegeben wird dieselbe Instanz, deshalb kann man mehrere Aufrufe verketten, etwa m.translateSelf(…).rotateAxisAngleSelf(…). Das spart Speicher und ist bei Animationen mit vielen Einzelbildern nützlich, bei denen eine Matrix fortlaufend weiterverändert wird.

Der Achsenvektor muss nicht normiert sein, der Browser normiert ihn intern. Enthält die Achse einen Anteil in x oder y, wird die Matrix zur 3D-Matrix (is2D === false). Eine reine Drehung um die z-Achse (0, 0, 1) lässt die Matrix zweidimensional.

Parameter

Name	Typ	Beschreibung
$x	number	x-Anteil des Achsenvektors.
$y	number	y-Anteil des Achsenvektors.
$z	number	z-Anteil des Achsenvektors.
$angle	number	Drehwinkel in Grad, nicht im Bogenmaß. Bei positiven Werten wird im Uhrzeigersinn gedreht, gesehen entgegen der Achsrichtung (gleiche Konvention wie bei CSS `rotate3d()`).

Rückgabewert

Typ

DOMMatrix

Beschreibung

Dieselbe DOMMatrix-Instanz, auf der die Methode aufgerufen wurde, jetzt mit der zusätzlichen Drehung.

Beispiele

Drehung um die z-Achse (bleibt 2D)

const m = new DOMMatrix();
const result = m.rotateAxisAngleSelf(0, 0, 1, 90);

// Gleiche Instanz, keine Kopie
console.log(result === m);
console.log(m.is2D);

// Rundungsfehler von cos(90°) ausblenden
const r = (v) => +v.toFixed(3);
console.log(r(m.a), r(m.b), r(m.c), r(m.d));

true true 0 1 -1 0

3D-Drehung um die y-Achse und Anwendung auf ein Element

const card = document.querySelector('.card');

const m = new DOMMatrix()
  .translateSelf(0, 0, -100)
  .rotateAxisAngleSelf(0, 1, 0, 45);

console.log(m.is2D);
console.log(+m.m11.toFixed(3), +m.m13.toFixed(3), +m.m31.toFixed(3));

// Ergibt einen matrix3d(...)-String
card.style.transform = m.toString();

false 0.707 -0.707 0.707

Fortlaufende Drehung um eine schräge Achse (Animation)

const cube = document.querySelector('#cube');
const matrix = new DOMMatrix();
let last = performance.now();

const tick = (now) => {
  const dt = (now - last) / 1000;
  last = now;
  // 60 Grad pro Sekunde um die Raumdiagonale; die Achse muss nicht normiert sein
  matrix.rotateAxisAngleSelf(1, 1, 1, 60 * dt);
  cube.style.transform = matrix.toString();
  requestAnimationFrame(tick);
};

requestAnimationFrame(tick);

Unterschied zu rotateAxisAngle()

const base = new DOMMatrix();

const copy = base.rotateAxisAngle(1, 0, 0, 30); // neue Matrix
console.log(base.isIdentity); // base unverändert

base.rotateAxisAngleSelf(1, 0, 0, 30);           // verändert base
console.log(base.isIdentity);
console.log(base.toString() === copy.toString());

true false true

// Wichtig · Fallstricke

Grad statt Bogenmaß: angle wird in Grad erwartet. Wer Math.PI / 2 übergibt, dreht nur um etwa 1,57°.
Veränderung in place: Die Methode überschreibt die Matrix. Wird die ursprüngliche Matrix noch gebraucht, rotateAxisAngle() verwenden oder vorher mit DOMMatrix.fromMatrix(m) kopieren.
Nur bei DOMMatrix: Die unveränderliche DOMMatrixReadOnly hat keine …Self()-Methoden, dort gibt es nur rotateAxisAngle().
Reihenfolge: Die Drehung wird von rechts multipliziert. Sie wirkt also im lokalen Koordinatensystem der vorherigen Transformationen, genau wie mehrere Funktionen hintereinander in einer CSS-transform-Liste.
Nullvektor: Die Achse (0, 0, 0) ergibt keine sinnvolle Drehung und sollte vermieden werden.
Gleitkomma-Ungenauigkeit: Werte wie cos(90°) ergeben etwa 6.12e-17 statt 0. Für Vergleiche runden.
Kompatibilität: In allen modernen Browsern verfügbar, auch in Web Workern. Node.js stellt DOMMatrix nicht von Haus aus bereit.

Siehe auch

DOMMatrixReadOnly.rotateAxisAngle() DOMMatrix.rotateSelf() DOMMatrix.rotateFromVectorSelf() DOMMatrix.translateSelf() DOMMatrix.multiplySelf() DOMMatrix new XRInputSourcesChangeEvent()