PointerEvent.azimuthAngle — Eigenschaft · JavaScript-Referenz

Signatur

PointerEvent.azimuthAngle

Beschreibung

Die schreibgeschützte Eigenschaft azimuthAngle eines PointerEvent gibt an, in welche Richtung der Stift auf der Bildschirmebene (X-Y-Ebene) zeigt. Der Wert ist ein Winkel in Bogenmaß im Bereich 0 bis 2π. Bei 0 zeigt das hintere Ende des Stifts in Richtung steigender X-Werte („3 Uhr“). Der Wert wächst im Uhrzeigersinn: π/2 entspricht „6 Uhr“, π „9 Uhr“ und 3π/2 „12 Uhr“. Im Uhrzeigersinn deshalb, weil die Y-Achse im Browser nach unten zeigt.

Zusammen mit altitudeAngle beschreibt azimuthAngle die Lage des Stifts in Kugelkoordinaten. altitudeAngle gibt an, wie steil der Stift steht, azimuthAngle gibt an, wohin er geneigt ist. Mit diesem Wertepaar lässt sich oft leichter rechnen als mit den älteren Eigenschaften tiltX/tiltY, die zwei getrennte Neigungswinkel in Grad liefern. Der Browser berechnet beide Darstellungen und rechnet sie bei Bedarf ineinander um.

Typische Anwendungen sind Zeichen- und Malprogramme: Pinselspitzen lassen sich passend zur Stiftrichtung drehen, Kalligrafie-Federn simulieren oder Schatten und Schraffuren abhängig von der Haltung des Stifts zeichnen. Wenn eine Maus benutzt wird oder die Hardware keine Neigung meldet, ist der Wert immer 0.

Rückgabewert

Typ

number

Beschreibung

Winkel in Bogenmaß im Bereich [0, 2π]. Der Wert ist 0, wenn der Stift senkrecht steht (altitudeAngle === π/2) oder das Gerät keine Neigung meldet (z. B. Maus oder Finger).

Beispiele

Stiftrichtung beim Zeichnen auslesen

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

canvas.addEventListener('pointermove', (event) => {
  if (event.pointerType !== 'pen') return;

  // Bogenmaß in Grad umrechnen
  const azimuthDeg = (event.azimuthAngle * 180 / Math.PI).toFixed(1);
  const altitudeDeg = (event.altitudeAngle * 180 / Math.PI).toFixed(1);

  console.log(`Azimut: ${azimuthDeg}°, Höhe: ${altitudeDeg}°`);
});

Azimut: 135.0°, Höhe: 52.3°

Pinselspitze passend zur Stiftrichtung drehen

const canvas = document.querySelector('#paint');
const ctx = canvas.getContext('2d');
canvas.style.touchAction = 'none'; // verhindert Scrollen beim Zeichnen

canvas.addEventListener('pointermove', (event) => {
  if (event.buttons !== 1) return;

  const { offsetX: x, offsetY: y, azimuthAngle, altitudeAngle, pressure } = event;
  // Je flacher der Stift liegt, desto länger ist die Pinselspitze
  const length = 4 + 20 * Math.cos(altitudeAngle ?? Math.PI / 2);

  ctx.save();
  ctx.translate(x, y);
  ctx.rotate(azimuthAngle ?? 0);
  ctx.fillStyle = `rgba(20, 20, 80, ${0.2 + pressure * 0.8})`;
  ctx.beginPath();
  ctx.ellipse(0, 0, length, 3, 0, 0, Math.PI * 2);
  ctx.fill();
  ctx.restore();
});

Ersatzwert aus tiltX/tiltY berechnen, wenn azimuthAngle fehlt

const toRad = (deg) => deg * Math.PI / 180;

const getAzimuth = (event) => {
  if ('azimuthAngle' in event) return event.azimuthAngle;

  const { tiltX = 0, tiltY = 0 } = event;
  if (tiltX === 0 && tiltY === 0) return 0;

  let azimuth = Math.atan2(Math.tan(toRad(tiltY)), Math.tan(toRad(tiltX)));
  if (azimuth < 0) azimuth += 2 * Math.PI; // auf [0, 2π) normalisieren
  return azimuth;
};

document.addEventListener('pointerdown', (event) => {
  console.log('Azimut (rad):', getAzimuth(event).toFixed(3));
});

Azimut (rad): 0.785

// Wichtig · Fallstricke

Einheit: Der Wert ist in Bogenmaß angegeben, nicht in Grad wie bei tiltX/tiltY. Zum Umrechnen in Grad mit 180 / Math.PI multiplizieren.
Drehrichtung: Weil die Y-Achse im Browser nach unten zeigt, steigt der Winkel im Uhrzeigersinn. Das passt direkt zu CanvasRenderingContext2D.rotate() und CSS-rotate().
Standardwert 0: Bei Maus, Finger oder Stiften ohne Neigungssensor ist der Wert immer 0. Das gilt auch, wenn der Stift senkrecht steht. Ob ein Stift wirklich nach „3 Uhr“ geneigt ist, lässt sich deshalb nur zusammen mit altitudeAngle (Wert kleiner als π/2) oder pointerType === 'pen' entscheiden.
Browser-Unterstützung: Chromium-Browser unterstützen die Eigenschaft seit Version 86, Safari und Firefox erst in neueren Versionen. Am besten mit 'azimuthAngle' in event prüfen und notfalls einen Ersatzwert aus tiltX/tiltY berechnen.
Genauigkeit: Wie genau und wie oft der Winkel aktualisiert wird, hängt von der Hardware und vom Treiber ab. Bei schnellen Bewegungen liefert getCoalescedEvents() Zwischenwerte, mit denen Linien glatter werden.
Für ungestörtes Zeichnen per Stift oder Touch auf dem Zeichenelement touch-action: none setzen. Sonst kann der Browser die Zeiger-Events für Scrollen oder Zoomen abbrechen (pointercancel).

Siehe auch

PointerEvent.altitudeAngle PointerEvent.pointerType PointerEvent.width PointerEvent.height PointerEvent.pointerId InputEvent.dataTransfer PointerEvent.isPrimary